@zhushanwen/pi-base-tool-enhance 0.2.0

package/src/bash-tool.ts

@@ -0,0 +1,226 @@
+/**
+ * bash 工具同名 override 定义（设计文档 docs/design/base-tool-enhance.md §3.2 方案 B / §3.5）。
+ *
+ * 前台行为 100% 委托 pi 官方工厂 createBashToolDefinition——override 后工具的全部
+ * 行为归本包负责，前台语义必须跟随 pi 版本升级而不是自研复刻（自研 spawn 会与
+ * pi 升级双向漂移，截断规则 / shellPath / PI_* env / stdin transport 细节遗漏即回归）。
+ * 本模块真正的增量：
+ *  1. input schema 新增 background?: boolean（D2：工具名保持 bash，只扩 schema）
+ *  2. description 重写——官方文案不含 background 用法，不重写则模型永远发现不了
+ *     新参数，「模型主动要求后台」的路径不可达
+ *  3. background:true 分支（M2）：spawn 后台任务立即返回 task_id（D14：subagent
+ *     进程内降级忽略 background，走前台同步语义）
+ *  4. 白名单强制后台（M4，D3/D13）：命令命中 force-test/force-longrun/用户正则 →
+ *     无视 background 参数强制后台，忽略 LLM 显式 timeout；双模式 timeout 配置注入
+ *     （前台未填 → foregroundTimeoutSeconds，后台未填 → backgroundTimeoutSeconds）
+ */
+
+import type { AgentToolUpdateCallback, BashToolDetails, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { createBashToolDefinition, getAgentDir } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import {
+	resolveBackgroundTimeoutSec,
+	spawnBackgroundTask,
+	truncateCommand,
+} from "./background/spawn-background.ts";
+import { isSubagentProcess } from "./background/subagent-guard.ts";
+import { loadBaseToolEnhanceConfig, type BaseToolEnhanceConfig } from "./config.ts";
+import { compileForcePatterns, describeForceMatch, matchForceBackground } from "./force-patterns.ts";
+
+/**
+ * override 后的 bash input schema。
+ *
+ * 在官方 schema（bash.js bashSchema：command + timeout?）基础上只追加 background。
+ * timeout 单位与官方一致 = 秒；background 缺省 false（不传 = 前台，等价官方行为）。
+ */
+const enhancedBashSchema = Type.Object({
+	command: Type.String({ description: "Bash command to execute" }),
+	timeout: Type.Optional(
+		Type.Number({ description: "Timeout in seconds (optional, no default timeout)" }),
+	),
+	background: Type.Optional(
+		Type.Boolean({
+			description:
+				"Run in background: returns a task_id immediately instead of waiting for the command to finish. Default false.",
+		}),
+	),
+});
+
+/**
+ * 重写的 bash description（给 LLM 的，英文，风格对齐官方文案 bash.js:233）。
+ *
+ * 覆盖设计文档 §3.5 要求的三个要点：
+ *  1. background:true 语义（立即返回 task_id，bash_output 查询 / bash_kill 终止）
+ *  2. 白名单命中命令自动转后台（即使未要求 background）
+ *  3. timeout 单位秒、显式填写会被尊重（唯一例外：白名单强转后台时忽略，D13）
+ *
+ * bash_output / bash_kill 工具由 M2 单元注册，description 先行提及（D2/§3.5 要求）。
+ */
+const ENHANCED_BASH_DESCRIPTION = [
+	"Execute a bash command in the current working directory. Returns stdout and stderr.",
+	"Output is truncated to last 2000 lines or 50KB (whichever is hit first). If truncated, full output is saved to a temp file.",
+	"Optionally provide a timeout in seconds; an explicit timeout is respected, except when a whitelisted long-running command is force-routed to background.",
+	"",
+	"Background mode: set background: true to start the command without waiting for it. The tool returns immediately with a task_id, the pid, and an output file path, and you can continue other work while it runs.",
+	"Poll progress and fetch output with bash_output {task_id} (omit task_id to list all background tasks); terminate a task with bash_kill {task_id}.",
+	"",
+	"Commands matching the force-background whitelist (test suites, dev servers, watch jobs and similar long-running commands) are automatically routed to background even when background was not requested; in that case the result carries a task_id to poll.",
+].join("\n");
+
+/**
+ * spawn 后台任务并拼装立即返回的 tool result（白名单强转与显式 background:true
+ * 两分支共用——spawn 入参、失败抛错、返回文案只有这一份，改文案不再有漏改分叉）。
+ * extraNotes：分支差异文案（如 force 命中说明），插在 Output file 行与 Poll 指引之间。
+ */
+function startBackgroundAndReply(
+	command: string,
+	ctx: ExtensionContext,
+	config: BaseToolEnhanceConfig,
+	timeoutSec: number | undefined,
+	extraNotes: string[] = [],
+) {
+	const spawned = spawnBackgroundTask({
+		command,
+		cwd: ctx.cwd,
+		dataDir: getAgentDir(),
+		sessionId: ctx.sessionManager.getSessionId(),
+		timeoutSec,
+		maxConcurrent: config.maxConcurrentBackground,
+	});
+	if (!spawned.ok) {
+		throw new Error(spawned.error);
+	}
+	const { task } = spawned;
+	return {
+		content: [
+			{
+				type: "text" as const,
+				text: [
+					`Background task started: ${truncateCommand(task.command)}`,
+					`task_id: ${task.taskId}  pid: ${task.pid}`,
+					`Output file: ${task.outputFile}`,
+					...extraNotes,
+					`Poll with bash_output {task_id:"${task.taskId}"} or omit task_id to list all tasks; terminate with bash_kill {task_id:"${task.taskId}"}.`,
+				].join("\n"),
+			},
+		],
+		details: undefined as undefined,
+	};
+}
+
+/**
+ * 构建 bash override 的 ToolDefinition。
+ *
+ * cwd 处理：官方工厂在调用时固化 cwd（execute 闭包捕获），而 extension load 时机
+ * 早于会话 cwd 确定。因此以 execute 时 ctx.cwd 为权威：cwd 变化（cd / session 切换）
+ * 就地重建 delegate；同 cwd 复用（工厂是纯函数，重建仅多创建 ops 闭包，单槽缓存
+ * 防止每次工具调用重复构建）。promptSnippet / promptGuidelines / renderCall /
+ * renderResult 等未覆盖字段从官方 delegate 展开透传——override 掉整个 definition
+ * 后不透传会丢掉系统提示里的工具片段（types.d.ts ToolDefinition：无 promptSnippet
+ * 的 custom tool 会被 Available tools 段省略）与 TUI 渲染（pi 0.84.1 bash 实装的
+ * renderCall 命令格式化 / renderResult elapsed 计时与富结果组件）。
+ */
+export function createBashOverrideToolDefinition() {
+	let cachedCwd: string | undefined;
+	// 官方工厂返回值的形状 = ToolDefinition（bash.js createBashToolDefinition），
+	// 类型交由 pi 公开导出推断，不在本地重复声明（防与 pi 升级漂移）。
+	type OfficialBashTool = ReturnType<typeof createBashToolDefinition>;
+	let cachedDelegate: OfficialBashTool | undefined;
+
+	const getDelegate = (cwd: string): OfficialBashTool => {
+		if (cachedDelegate === undefined || cachedCwd !== cwd) {
+			cachedDelegate = createBashToolDefinition(cwd);
+			cachedCwd = cwd;
+		}
+		return cachedDelegate;
+	};
+
+	// registerTool 发生在 extension load 时（无 execute ctx），初始 delegate 用
+	// 进程 cwd 建立——name/label/promptSnippet/renderCall/renderResult 等静态字段与
+	// cwd 无关，execute 路径会被 getDelegate(ctx.cwd) 纠正。
+	const initial = getDelegate(process.cwd());
+
+	return {
+		// 官方 delegate 展开透传（render 面委托）：pi 0.84.1 bash definition 实装带
+		// renderCall（命令格式化）/ renderResult（elapsed 计时、富结果组件），独立
+		// pi TUI 用户安装本包后渲染不降级为通用组件——凡未在下方显式覆盖的字段
+		// （label/promptSnippet/promptGuidelines/renderCall/renderResult 等）全部随
+		// delegate 透传，cwd 重建 delegate 时静态闭包引用不变（render 闭包与 cwd 无关）
+		...initial,
+		name: initial.name, // "bash"：同名覆盖内置工具（agent-session _refreshToolRegistry 后注册者胜）
+		description: ENHANCED_BASH_DESCRIPTION,
+		parameters: enhancedBashSchema,
+		async execute(
+			toolCallId: string,
+			args: { command: string; timeout?: number; background?: boolean },
+			signal: AbortSignal | undefined,
+			// 与官方 delegate 同型（展开透传后泛型 TDetails=BashToolDetails|undefined
+			// 随 render 面传入，execute 签名必须对齐，否则 registerTool 赋值检查不过）
+			onUpdate: AgentToolUpdateCallback<BashToolDetails | undefined> | undefined,
+			ctx: ExtensionContext,
+		) {
+			// 配置每次 execute 读时加载（热重载契约：禁止上层缓存，同进程改配置文件
+			// 不重启即生效）。D14：subagent 降级是全量的——白名单与 background 参数
+			// 同时失效（判定一次，两个分支共用）
+			const config = loadBaseToolEnhanceConfig();
+			const subagent = isSubagentProcess();
+
+			// 白名单强制后台（D3/M4）：判定在 execute 内部、不改写 input——permission
+			// 审批的永远是原始 command/background/timeout（P1 探针结论的前提）。命中 →
+			// 强制走 background，无视 background:false/缺省
+			if (!subagent) {
+				const forceMatch = matchForceBackground(
+					args.command,
+					compileForcePatterns(config.forceBackgroundPatterns, config.disableBuiltinForcePatterns),
+				);
+				if (forceMatch !== undefined) {
+					// D13：忽略 LLM 显式 timeout（unified-hooks 时代「跑测试带 timeout」习惯
+					// 会精确复刻 §2.2 要解决的失败模式），按「配置默认 → 不限」取值
+					const timeoutSec = resolveBackgroundTimeoutSec(
+						undefined,
+						config.backgroundTimeoutSeconds ?? undefined,
+					);
+					const notes = [
+						`Forced to background: command matched force-background whitelist ${describeForceMatch(forceMatch)}.`,
+						...(args.timeout !== undefined
+							? [
+									`Ignored explicit timeout ${args.timeout}s for whitelisted command ` +
+										`(background timeout: ${timeoutSec !== undefined ? `${timeoutSec}s (config default)` : "unlimited"}).`,
+								]
+							: []),
+					];
+					return startBackgroundAndReply(args.command, ctx, config, timeoutSec, notes);
+				}
+			}
+
+			// background 分支（M2）：显式 background:true 且非 subagent 降级（D14——
+			// subagent 进程内忽略 background 走前台，保持内置同步语义）。abort/interrupt
+			// 不传播到后台任务（D15）：本分支不接触 signal，立即返回
+			if (args.background === true && !subagent) {
+				// timeout 优先级（§3.5）：LLM 显式值 > 配置默认 > 不限；无效显式值沿用
+				// pi 内置文案抛错（注入只发生在「LLM 未填 && 配置了默认」，D4）
+				const timeoutSec = resolveBackgroundTimeoutSec(args.timeout, config.backgroundTimeoutSeconds ?? undefined);
+				return startBackgroundAndReply(args.command, ctx, config, timeoutSec);
+			}
+			const delegate = getDelegate(ctx.cwd);
+			// 前台委托：只转发官方 schema 已识别的字段（command/timeout），background
+			// 是本包增量，官方 execute 不认识（其解构也只取这两个键，显式构造让
+			// 「本层转发面」在代码上自解释）。subagent 降级（D14）与 background 缺省
+			// 都落到这条路径。
+			//
+			// 前台 timeout 注入（M4/G3）：LLM 未填 && foregroundTimeoutSeconds 配置了
+			// 默认 → 注入；默认 null 不注入 = pi 原生不限时语义（D4）。注入与 subagent
+			// 降级正交——D14 只废 background/白名单语义，前台默认超时是全局挂死保护
+			const foregroundTimeout =
+				args.timeout !== undefined ? args.timeout : (config.foregroundTimeoutSeconds ?? undefined);
+			return delegate.execute(
+				toolCallId,
+				{ command: args.command, timeout: foregroundTimeout },
+				signal,
+				onUpdate,
+				ctx,
+			);
+		},
+	};
+}

package/src/config.ts

@@ -0,0 +1,167 @@
+/**
+ * 配置体系（M4，设计文档 §3.5「配置文件」段 + §3.6「config 解析失败」行）。
+ *
+ * 委托 llm-shared loadConfig（mtime+size 读时刷新热重载，同 smart-context/permission
+ * 范式）——【热重载契约】每次需要配置直接调 loadBaseToolEnhanceConfig，禁止上层
+ * 闭包/手动缓存阻断读时刷新（同进程改文件不重启即生效）。
+ *
+ * normalize 原则（部分坏配置不拖垮可用性）：单键类型错/负数/0 → 该键回退默认 +
+ * logger.warn，不整体拒载；文件整体解析失败/不存在 → 全默认值（工具照常工作），
+ * warn 落日志并指向配置文件路径。
+ */
+
+import { getConfigPath as getLlmSharedConfigPath, loadConfig } from "@zhushanwen/pi-llm-shared";
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+
+import { DEFAULT_MAX_CONCURRENT_BACKGROUND } from "./background/spawn-background.ts";
+
+const logger = getLogger("base-tool-enhance");
+
+/** llm-shared 泛型 config 的包名（决定文件名 <dataDir>/config/base-tool-enhance-ext-config.json）。 */
+const CONFIG_PKG = "base-tool-enhance";
+
+const MS_PER_SECOND = 1000;
+/** setTimeout 延迟上限（int32 ms）：timeout 配置换算毫秒后的 clamp 上限。 */
+const INT32_MAX_MS = 2_147_483_647;
+
+export interface BaseToolEnhanceConfig {
+	/** 用户正则（源字符串），追加到内置两组白名单之后（compile 在 force-patterns.ts）。 */
+	forceBackgroundPatterns: string[];
+	/** true = 关闭内置 force-test/force-longrun 两组，只用用户正则。 */
+	disableBuiltinForcePatterns: boolean;
+	/** null = 不注入（D4，pi 原生不限时）；数字 = 前台未填 timeout 时的默认秒数。 */
+	foregroundTimeoutSeconds: number | null;
+	/** null = 不注入；数字 = 后台未填 timeout 时的默认秒数。 */
+	backgroundTimeoutSeconds: number | null;
+	maxConcurrentBackground: number;
+}
+
+/** 默认配置（零配置状态：内置白名单两组全生效、双模式不注入 timeout、并发 8）。 */
+export const DEFAULT_BASE_TOOL_ENHANCE_CONFIG: BaseToolEnhanceConfig = {
+	forceBackgroundPatterns: [],
+	disableBuiltinForcePatterns: false,
+	foregroundTimeoutSeconds: null,
+	backgroundTimeoutSeconds: null,
+	// 单一来源：与 spawnBackgroundTask 的 opts.maxConcurrent 缺省同值（M2 常量）
+	maxConcurrentBackground: DEFAULT_MAX_CONCURRENT_BACKGROUND,
+};
+
+/** 配置文件完整路径（诊断文案与测试用）。 */
+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);
+}
+
+function warnInvalid(key: string, value: unknown, fallback: string): void {
+	// 可操作错误信息：指出键、实际值、回退结果与配置文件路径
+	logger.warn(
+		`Config key '${key}' invalid (got ${describeValue(value)}), falling back to ${fallback}. ` +
+			`Fix or remove it in ${getLlmSharedConfigPath(CONFIG_PKG)}.`,
+	);
+}
+
+/**
+ * timeout 键归一化：null/缺省 → null（不注入，D4）；正有限数 → 原值；
+ * 类型错/负数/0/非有限 → null + warn；换算毫秒超 int32 上限 → clamp + warn。
+ */
+function normalizeTimeoutSeconds(raw: unknown, key: string): number | null {
+	if (raw === null || raw === undefined) return null;
+	if (typeof raw !== "number" || !Number.isFinite(raw) || raw <= 0) {
+		warnInvalid(key, raw, "null (no timeout injection)");
+		return null;
+	}
+	if (raw * MS_PER_SECOND > INT32_MAX_MS) {
+		const clamped = INT32_MAX_MS / MS_PER_SECOND;
+		logger.warn(
+			`Config key '${key}' ${raw}s exceeds int32 ms limit, clamped to ${clamped}s ` +
+				`(${getLlmSharedConfigPath(CONFIG_PKG)}).`,
+		);
+		return clamped;
+	}
+	return raw;
+}
+
+/**
+ * forceBackgroundPatterns 归一化：非数组 → 空 + warn；单条非字符串或 compile 失败 →
+ * 仅丢弃该条 + warn（一条坏正则不让所有前台命令全挂），其余条目保留。
+ */
+function normalizeForceBackgroundPatterns(raw: unknown): string[] {
+	if (raw === undefined || raw === null) return [];
+	if (!Array.isArray(raw)) {
+		warnInvalid("forceBackgroundPatterns", raw, "[] (no user patterns)");
+		return [];
+	}
+	const valid: string[] = [];
+	raw.forEach((item, index) => {
+		if (typeof item !== "string") {
+			warnInvalid(`forceBackgroundPatterns[${index}]`, item, "dropped");
+			return;
+		}
+		try {
+			new RegExp(item);
+		} 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)}).`,
+			);
+			return;
+		}
+		valid.push(item);
+	});
+	return valid;
+}
+
+function normalizeDisableBuiltinForcePatterns(raw: unknown): boolean {
+	if (typeof raw === "boolean") return raw;
+	if (raw !== undefined) warnInvalid("disableBuiltinForcePatterns", raw, "false");
+	return false;
+}
+
+/** 正有限数取 floor（并发数语义为整数）；类型错/负数/0 → 默认 8 + warn。 */
+function normalizeMaxConcurrentBackground(raw: unknown): number {
+	if (typeof raw === "number" && Number.isFinite(raw) && raw > 0) {
+		return Math.floor(raw);
+	}
+	if (raw !== undefined) warnInvalid("maxConcurrentBackground", raw, String(DEFAULT_MAX_CONCURRENT_BACKGROUND));
+	return DEFAULT_MAX_CONCURRENT_BACKGROUND;
+}
+
+/**
+ * 单键归一化（永不 throw——llm-shared 只在文件整体解析失败时走 catch 回退，键级
+ * 问题在这里就地消化）。未知键忽略（前向兼容）。
+ */
+export function normalizeBaseToolEnhanceConfig(raw: unknown): BaseToolEnhanceConfig {
+	if (!isPlainObject(raw)) {
+		if (raw !== undefined && raw !== null) {
+			logger.warn(
+				`Config root is not a JSON object (${describeValue(raw)}), using all defaults ` +
+					`(${getLlmSharedConfigPath(CONFIG_PKG)}).`,
+			);
+		}
+		return { ...DEFAULT_BASE_TOOL_ENHANCE_CONFIG };
+	}
+	return {
+		forceBackgroundPatterns: normalizeForceBackgroundPatterns(raw.forceBackgroundPatterns),
+		disableBuiltinForcePatterns: normalizeDisableBuiltinForcePatterns(raw.disableBuiltinForcePatterns),
+		foregroundTimeoutSeconds: normalizeTimeoutSeconds(raw.foregroundTimeoutSeconds, "foregroundTimeoutSeconds"),
+		backgroundTimeoutSeconds: normalizeTimeoutSeconds(raw.backgroundTimeoutSeconds, "backgroundTimeoutSeconds"),
+		maxConcurrentBackground: normalizeMaxConcurrentBackground(raw.maxConcurrentBackground),
+	};
+}
+
+/**
+ * 加载配置（每次调用直接走 loadConfig 读时刷新——热重载契约，禁止上层缓存）。
+ * 文件不存在 / 坏 JSON → 全默认值 + warn（§3.6：工具按默认值继续工作）。
+ */
+export function loadBaseToolEnhanceConfig(): BaseToolEnhanceConfig {
+	return loadConfig(CONFIG_PKG, DEFAULT_BASE_TOOL_ENHANCE_CONFIG, normalizeBaseToolEnhanceConfig, (msg) => {
+		logger.warn(msg);
+	});
+}

package/src/force-patterns.ts

@@ -0,0 +1,236 @@
+/**
+ * 强制后台白名单（M4，设计文档 §3.5「内置正则基线」+「匹配语义」段）。
+ *
+ * 两组内置正则 + 用户配置正则合并：
+ *  - force-test：逐条迁自 unified-hooks test-timeout-guard.ts（主体逐条迁移；锚定
+ *    前缀从原 `(^|\s|&&|\|{1,2}|;)` 收紧为命令位置锚定 CMD_ANCHOR，匹配语义双向
+ *    翻转——见 FORCE_TEST_PATTERN_ENTRIES 注释）
+ *  - force-longrun：M4 定稿清单，原则 = 命令语义上无自然退出点（dev server / watch /
+ *    tail -f 等），按命令名与 flag 组合匹配
+ *
+ * 匹配语义（防误伤的关键）：正则一律锚定**命令位置**——行首，或 `;` / `&&` / `||` /
+ * `|` / 换行之后的命令起始位，不做裸子串匹配。用户正则同样自动加锚（组内统一语义，
+ * 用户正则无需也不应自带 `^`）。正则近似匹配的固有局限（诚实登记）：引号内换行 /
+ * heredoc 内容理论上可构造误伤样例、`$(...)` 内命令会漏报——force 命中转后台是
+ * 非破坏性的，漏报由模型显式 background:true 兜底。
+ */
+
+/** 命令位置锚定前缀：行首，或 `;`/`&&`/`||`/`|`/换行之后的命令起始位（后随可选空白）。 */
+const CMD_ANCHOR = String.raw`(?:^|&&|\|\||;|\||\n)\s*`;
+
+/** 内置条目：pattern 已含 CMD_ANCHOR 前缀；label 为语义标签（诊断/result 文案引用）。 */
+export interface BuiltinForcePatternEntry {
+	pattern: RegExp;
+	label: string;
+}
+
+/**
+ * force-test 组：测试套件命令（迁自 unified-hooks test-timeout-guard.ts:17-60，
+ * 主体逐条迁移；锚定收紧为命令位置本身是语义变化，两个方向翻转——
+ *  - 不再误伤：原 `\s` 前缀会把 `git commit -m "fix: npm test"` 这类参数文本当命令
+ *    命中，锚定后不再命中
+ *  - 新增漏报：wrapper 形态 `sudo npm test` / `timeout 300 npm test` /
+ *    `xargs npm test` 原靠 `\s` 前缀命中，锚定后 wrapper 名占命令位置、目标命令退到
+ *    参数位不再命中（§3.5 匹配语义的 wrapper 局限），由模型显式 background:true 兜底
+ */
+export const FORCE_TEST_PATTERN_ENTRIES: readonly BuiltinForcePatternEntry[] = [
+	// === Node.js / JS / TS ===
+	// 包管理器 test 脚本：npm test / pnpm test / yarn test / bun test
+	{ pattern: new RegExp(CMD_ANCHOR + String.raw`(pnpm|npm|yarn|bun)\s+test\b`), label: "npm test" },
+	// pnpm/npm run 跑 test 系脚本名（npm run test:unit / run test:watch 等）
+	{
+		pattern: new RegExp(CMD_ANCHOR + String.raw`(pnpm|npm)\s+(--filter\s+\S+\s+)?run\s+\S*test`),
+		label: "npm run test",
+	},
+	// npx 直接调用测试 runner
+	{ pattern: new RegExp(CMD_ANCHOR + String.raw`npx\s+vitest\b`), label: "vitest" },
+	{ pattern: new RegExp(CMD_ANCHOR + String.raw`npx\s+jest\b`), label: "jest" },
+	{ pattern: new RegExp(CMD_ANCHOR + String.raw`npx\s+mocha\b`), label: "mocha" },
+	// e2e runner：npx cypress / npx playwright
+	{ pattern: new RegExp(CMD_ANCHOR + String.raw`npx\s+(cypress|playwright)\s`), label: "e2e runner" },
+	// vue-cli-service / react-scripts test
+	{ pattern: new RegExp(CMD_ANCHOR + String.raw`npx\s+vue-cli-service\s+test`), label: "vue-cli test" },
+	{ pattern: new RegExp(CMD_ANCHOR + String.raw`npx\s+react-scripts\s+test`), label: "react-scripts test" },
+	// node_modules 直调 runner：./node_modules/.bin/vitest 等
+	{
+		pattern: new RegExp(CMD_ANCHOR + String.raw`\.\/?node_modules\/\.bin\/(vitest|jest|mocha)\b`),
+		label: "direct test runner",
+	},
+
+	// === Python ===
+	{ pattern: new RegExp(CMD_ANCHOR + String.raw`pytest\b`), label: "pytest" },
+	// python -m pytest / python3 -m unittest
+	{ pattern: new RegExp(CMD_ANCHOR + String.raw`python[3]?\s+-m\s+(pytest|unittest)\b`), label: "python test" },
+	// uv run pytest / poetry run pytest
+	{ pattern: new RegExp(CMD_ANCHOR + String.raw`(uv|poetry)\s+run\s+pytest\b`), label: "uv/poetry pytest" },
+	{ pattern: new RegExp(CMD_ANCHOR + String.raw`nosetests\b`), label: "nosetests" },
+
+	// === Java / JVM ===
+	// mvn test / mvnw test（mvn verify 等含 test 的 goal 由 \S*test 覆盖）
+	{ pattern: new RegExp(CMD_ANCHOR + String.raw`(mvn|\.\/mvnw)\s+\S*test`), label: "maven test" },
+	{ pattern: new RegExp(CMD_ANCHOR + String.raw`(gradle|\.\/gradlew)\s+\S*test`), label: "gradle test" },
+	{ pattern: new RegExp(CMD_ANCHOR + String.raw`sbt\s+test\b`), label: "sbt test" },
+
+	// === Go ===
+	{ pattern: new RegExp(CMD_ANCHOR + String.raw`go\s+test\b`), label: "go test" },
+
+	// === Rust ===
+	{ pattern: new RegExp(CMD_ANCHOR + String.raw`cargo\s+test\b`), label: "cargo test" },
+
+	// === .NET ===
+	{ pattern: new RegExp(CMD_ANCHOR + String.raw`dotnet\s+test\b`), label: "dotnet test" },
+
+	// === Ruby ===
+	// rspec / bundle exec rspec
+	{ pattern: new RegExp(CMD_ANCHOR + String.raw`(rspec|bundle\s+exec\s+rspec)\b`), label: "rspec" },
+	{ pattern: new RegExp(CMD_ANCHOR + String.raw`rake\s+test\b`), label: "rake test" },
+];
+
+/**
+ * force-longrun 组（M4 定稿）：命令语义上无自然退出点的长驻命令。判定标准 = 按命令
+ * 名与 flag 组合匹配，不做 `--watch` 字面量子串匹配（`rg --files | grep watch` 不命中
+ * ——watch flag 断言限定在同一命令段内、且以独立参数形态出现）。
+ */
+export const FORCE_LONGRUN_PATTERN_ENTRIES: readonly BuiltinForcePatternEntry[] = [
+	// ── dev server：npm run dev 系 ──
+	// 包管理器 dev 脚本（npm/pnpm/yarn/bun run dev，含 dev:web 等冒号变体——dev:* 按约定都是 dev server）
+	{
+		pattern: new RegExp(CMD_ANCHOR + String.raw`(pnpm|npm|yarn|bun)\s+(--filter\s+\S+\s+)?run\s+dev\b`),
+		label: "package run dev",
+	},
+	// pnpm/yarn/bun 允许省略 run 的 dev 脚本简写（npm 无此语义故不含）
+	{ pattern: new RegExp(CMD_ANCHOR + String.raw`(pnpm|yarn|bun)\s+dev\b`), label: "package dev" },
+
+	// ── dev server：npx 直接调用 ──
+	// vite dev server（vite 缺省即 serve；排除 vite build——build 有自然退出点。
+	// 双 lookahead：先钉死 vite 后必须是空白/结尾（防回溯绕过），再排除 build 子命令）
+	{ pattern: new RegExp(CMD_ANCHOR + String.raw`npx\s+vite(?=\s|$)(?!\s*build\b)`), label: "vite" },
+	// next dev / nuxt dev / ng serve：框架 dev server 子命令
+	{ pattern: new RegExp(CMD_ANCHOR + String.raw`npx\s+next\s+dev\b`), label: "next dev" },
+	{ pattern: new RegExp(CMD_ANCHOR + String.raw`npx\s+nuxt\s+dev\b`), label: "nuxt dev" },
+	{ pattern: new RegExp(CMD_ANCHOR + String.raw`npx\s+ng\s+serve\b`), label: "ng serve" },
+	// webpack dev server：webpack-cli v4 serve 子命令 / 旧版 webpack-dev-server 直跑
+	{ pattern: new RegExp(CMD_ANCHOR + String.raw`npx\s+webpack\s+serve\b`), label: "webpack serve" },
+	{ pattern: new RegExp(CMD_ANCHOR + String.raw`npx\s+webpack-dev-server\b`), label: "webpack-dev-server" },
+
+	// ── dev server：语言内置 serve 命令（无自然退出点）──
+	// python 静态文件服务器
+	{ pattern: new RegExp(CMD_ANCHOR + String.raw`python[3]?\s+-m\s+http\.server\b`), label: "http.server" },
+	// django runserver（python manage.py runserver）
+	{ pattern: new RegExp(CMD_ANCHOR + String.raw`python[3]?\s+manage\.py\s+runserver\b`), label: "runserver" },
+	// flask run（flask --app x run 由段内 run 断言覆盖形态此处只认常见直跑）
+	{ pattern: new RegExp(CMD_ANCHOR + String.raw`flask\s+run\b`), label: "flask run" },
+	// rails server / rails s
+	{ pattern: new RegExp(CMD_ANCHOR + String.raw`rails\s+(s|server)\b`), label: "rails server" },
+	// php artisan serve
+	{ pattern: new RegExp(CMD_ANCHOR + String.raw`php\s+artisan\s+serve\b`), label: "artisan serve" },
+
+	// ── 显式 watch flags：工具名 + 同段内独立 watch 参数组合 ──
+	// vitest/jest --watch / --watchAll（排除 --watch=false——显式关 watch 就是一次性运行）
+	{
+		pattern: new RegExp(
+			CMD_ANCHOR + String.raw`(?:npx\s+)?(?:vitest|jest)\b[^;&|\n]*\s--watch(?:All)?\b(?!=)`,
+		),
+		label: "vitest/jest --watch",
+	},
+	// tsc --watch / tsc -w（持续增量编译）
+	{ pattern: new RegExp(CMD_ANCHOR + String.raw`(?:npx\s+)?tsc\b[^;&|\n]*\s(?:--watch|-w)\b`), label: "tsc watch" },
+	// 构建工具 watch 模式：sass / webpack / esbuild / rollup --watch
+	{
+		pattern: new RegExp(CMD_ANCHOR + String.raw`(?:npx\s+)?(?:sass|webpack|esbuild|rollup)\b[^;&|\n]*\s--watch\b`),
+		label: "build --watch",
+	},
+
+	// ── 天然长驻工具 ──
+	// cargo watch（文件变更即重跑命令，直到手动停止）
+	{ pattern: new RegExp(CMD_ANCHOR + String.raw`cargo\s+watch\b`), label: "cargo watch" },
+	// watchexec / nodemon（通用文件监听重启器）
+	{ pattern: new RegExp(CMD_ANCHOR + String.raw`watchexec\b`), label: "watchexec" },
+	{ pattern: new RegExp(CMD_ANCHOR + String.raw`nodemon\b`), label: "nodemon" },
+	// tail -f / tail -F（持续追踪日志文件；可选中段容纳 tail -n 100 -f 形态）
+	{ pattern: new RegExp(CMD_ANCHOR + String.raw`tail\s(?:[^;&|\n]*\s)?-[fF]\b`), label: "tail -f" },
+	// ngrok（隧道转发，直到手动停止）
+	{ pattern: new RegExp(CMD_ANCHOR + String.raw`ngrok\b`), label: "ngrok" },
+];
+
+/** 命中来源：内置组（组名 test/longrun）或用户正则。 */
+export type ForceMatchSource = "builtin-test" | "builtin-longrun" | "user";
+
+/** 编译后的白名单条目。 */
+export interface ForcePattern {
+	re: RegExp;
+	source: ForceMatchSource;
+	/** result 文案引用名：内置 = 组名（test/longrun）；用户 = 正则字面量前 40 字符。 */
+	name: string;
+	/** 细化诊断：内置条目的语义标签。 */
+	label?: string;
+}
+
+/** 用户正则字面量在 result 文案中的展示长度上限。 */
+const USER_PATTERN_DISPLAY_LIMIT = 40;
+
+function compileUserPattern(source: string): ForcePattern | undefined {
+	// 防御性 compile：config normalize 已丢弃非法正则，此处再兜一层（不信任边界）
+	try {
+		return {
+			re: new RegExp(CMD_ANCHOR + source),
+			source: "user",
+			name:
+				source.length > USER_PATTERN_DISPLAY_LIMIT
+					? `${source.slice(0, USER_PATTERN_DISPLAY_LIMIT)}…`
+					: source,
+		};
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * 合并白名单（§3.5 行为矩阵）：
+ *  - 零配置（无用户正则、不 disable）→ 两组内置全生效
+ *  - disableBuiltinForcePatterns:true → 两组内置关闭
+ *  - 用户正则始终追加（与内置并存时匹配任一即命中）
+ */
+export function compileForcePatterns(userPatterns: readonly string[], disableBuiltin: boolean): ForcePattern[] {
+	const patterns: ForcePattern[] = [];
+	if (!disableBuiltin) {
+		for (const entry of FORCE_TEST_PATTERN_ENTRIES) {
+			patterns.push({ re: entry.pattern, source: "builtin-test", name: "test", label: entry.label });
+		}
+		for (const entry of FORCE_LONGRUN_PATTERN_ENTRIES) {
+			patterns.push({ re: entry.pattern, source: "builtin-longrun", name: "longrun", label: entry.label });
+		}
+	}
+	for (const source of userPatterns) {
+		const compiled = compileUserPattern(source);
+		if (compiled !== undefined) patterns.push(compiled);
+	}
+	return patterns;
+}
+
+/** 白名单命中结果。 */
+export interface ForcePatternMatch {
+	source: ForceMatchSource;
+	/** result 文案引用名（组名 test/longrun 或用户正则字面量前 40 字符）。 */
+	name: string;
+	/** 内置条目语义标签（用户正则无）。 */
+	label?: string;
+}
+
+/** 判定命令是否命中白名单（命令位置锚定，见文件头「匹配语义」）。 */
+export function matchForceBackground(command: string, patterns: readonly ForcePattern[]): ForcePatternMatch | undefined {
+	for (const p of patterns) {
+		if (p.re.test(command)) {
+			return { source: p.source, name: p.name, ...(p.label !== undefined ? { label: p.label } : {}) };
+		}
+	}
+	return undefined;
+}
+
+/** result 文案用的命中描述：内置组报组名 + 标签，用户正则报字面量。 */
+export function describeForceMatch(match: ForcePatternMatch): string {
+	if (match.source === "user") {
+		return `user pattern '${match.name}'`;
+	}
+	return match.label !== undefined ? `pattern '${match.name}' (${match.label})` : `pattern '${match.name}'`;
+}