@trim21/personal-pi-extensions 0.1.627 → 0.1.630

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.627",
+  "version": "0.1.630",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [

package/src/bwrap/README.md

@@ -1,7 +1,8 @@
 # bwrap 沙箱与网络栈架构
 
 本文档描述 `network: limited` 模式下的进程模型、网络路径与生命周期管理。
-基础沙箱（bwrap 文件系统隔离）见 `core.ts` / `sandbox.ts`；本文聚焦网络栈
+基础沙箱（bwrap 文件系统隔离）见 `core.ts`（配置与 argv 内容）/ `exec.ts`
+（命令行组装与进程生命周期）/ `sandbox.ts`（加载配置并运行）；本文聚焦网络栈
 （`network-stack.ts` / `holder.ts` / `mihomo-config.ts`）。
 
 ## 进程模型
@@ -21,7 +22,7 @@ pi 进程（network-stack.ts）
      必须在宿主 netns 启动（原因见「设计约束」）；持 exit-fd 读端 + tapfd。
 ```
 
-每条命令的短命子树（命令结束即退）：
+每条命令的短命子树（命令结束即退），由 `exec.ts` 组装并 spawn：
 
 ```
 nsenter -U -n --preserve-credentials -t <①的pid> \
@@ -29,7 +30,9 @@ nsenter -U -n --preserve-credentials -t <①的pid> \
 ```
 
 nsenter 进入 holder 的 userns/netns，bwrap 在里面再嵌套创建自己的 user/pid
-ns 跑命令。网络栈是每条命令现建现停（起栈 ~40ms、停栈 ~100ms），不跨命令复用：
+ns 跑命令。网络栈对外只提供 holder pid（`NetworkStack.holderPid`）与停止，
+命令行怎么拼属于执行层——`--print-args` 预览与真正执行共用同一段组装。
+网络栈是每条命令现建现停（起栈 ~40ms、停栈 ~100ms），不跨命令复用：
 allowlist 变更因此即时生效，代价是每条命令重新启动一次 mihomo。
 
 ## 网络路径

package/src/bwrap/approval-rules.ts

@@ -3,9 +3,11 @@
  * 用 tree-sitter 解析命令（含嵌套 `$(...)`），对每条命令的原文做通配
  * 匹配，对 allow/deny 规则求值。规则匹配不经过任何命令归一——BashArity
  * 归一模式只用于 "allow forever" 的建议规则（见 approval-suggest.ts）。
- * 接入 bwrap 的 `dangerouslyDisableSandbox` 审批：命中规则自动
- * 放行/拒绝，未命中才弹审批对话框。文件输出重定向（`>` / `>>` / `&>`
- * 等）不会因命令规则自动放行，避免 `echo *` 把 `echo '' > file` 带过。
+ * 接入 bwrap 的 `dangerouslyDisableSandbox` 审批：审批规则集
+ * （createApprovalRuleSet）独占「自动放行 / 自动拒绝 / 交人审」的判定、
+ * allow 覆盖查询、待允许模式与规则追加，调用方只描述用户动作。
+ * 文件输出重定向（`>` / `>>` / `&>` 等）不会因命令规则自动放行，
+ * 避免 `echo *` 把 `echo '' > file` 带过。
  *
  * 参考实现：
  * - opencode packages/core/src/util/wildcard.ts（通配匹配）
@@ -209,27 +211,17 @@ export function matchRule(input: string, pattern: string): boolean {
   return new RegExp(`^${escaped}$`, "s").test(input);
 }
 
-// ── 规则求值 ────────────────────────────────────────────────────────────────
+// ── 命令树展平 ──────────────────────────────────────────────────────────────
 
 /**
- * 对命令（含所有嵌套命令）求值：
- * - deny 优先：任一命令命中 deny 规则即整体拒绝
- * - 文件输出重定向不自动放行：即使命令规则全匹配，也返回 undefined 交人审
- * - allow 需全量：所有命令都命中 allow 规则才整体放行，否则返回
- *   undefined（有命令未命中规则，交给人审），避免未允许的命令被同链放行带过。
- * - 匹配输入是命令原文（tree-sitter command 节点 text，含嵌套逐条展开），
- *   对齐 opencode shell.ts 的 patterns；通配规则按字面写，`--` 与普通
- *   token 无区别。
- * 规则内后写优先（findLast，对齐 opencode PermissionV2）。
+ * 展平命令树：每条命令本身 + 其所有嵌套命令（`$(...)` 内的），父在子前。
+ * 求值与建议模式生成（approval-suggest.ts）共用——后者依赖本模块，
+ * 反向 import 会成环，所以展平放在这里。
  */
-export async function evaluateBashApproval(
-  command: string,
-  rules: readonly ApprovalRule[],
-): Promise<ApprovalAction | undefined> {
-  const parsed = await parseBashCommands(command);
-  const raws: string[] = [];
+export function flattenCommands(parsed: ParsedBash): BashCommand[] {
+  const flat: BashCommand[] = [];
   const visit = (cmd: BashCommand) => {
-    raws.push(cmd.raw);
+    flat.push(cmd);
     for (const nested of cmd.nested) {
       visit(nested);
     }
@@ -237,21 +229,101 @@ export async function evaluateBashApproval(
   for (const cmd of parsed.commands) {
     visit(cmd);
   }
-  if (raws.length === 0) {
-    return;
+  return flat;
+}
+
+// ── 审批规则集 ──────────────────────────────────────────────────────────────
+
+export interface ApprovalRuleSetOptions {
+  /** 当前规则（读取时取最新，追加后无需重建规则集）。规则数组即优先级：靠后优先。 */
+  rules: () => readonly ApprovalRule[];
+  /** 命令 → 候选模式（BashArity）；注入以免与 approval-suggest.ts 成环。 */
+  suggestPatterns: (command: string) => Promise<readonly string[]>;
+  /** 追加 allow 规则并持久化；resolve 后 rules() 必须能看到它们，抛错即视为未追加。 */
+  persist: (rules: readonly ApprovalRule[]) => Promise<void>;
+}
+
+export interface ApprovalRuleSet {
+  /**
+   * 对命令（含所有嵌套命令）求值：deny 优先 / allow 需全量 / 含文件输出
+   * 重定向不自动放行。返回 undefined 表示未命中规则，交人工审批。
+   */
+  evaluate(command: string): Promise<ApprovalAction | undefined>;
+  /**
+   * 该字符串（命令原文或候选模式）是否被最后一条匹配的规则允许。
+   * 只回答 allow 覆盖，不考虑 deny 与重定向——放行判定一律用 evaluate。
+   */
+  isAllowed(pattern: string): boolean;
+  /** 命令的候选模式（去重）中尚未被 allow 规则覆盖的那些；审批子菜单的唯一来源。 */
+  pendingPatterns(command: string): Promise<string[]>;
+  /** 追加 allow 规则并持久化；persist 成功后立即生效。 */
+  addAllowRules(patterns: readonly string[]): Promise<void>;
+}
+
+/**
+ * 审批规则集：命令自动判定、allow 覆盖查询、待允许模式与规则追加的唯一 owner。
+ * 规则数组的顺序即优先级：靠后优先（项目规则经 deepMerge 排在全局规则之后）。
+ * 三条协作方由调用方注入：规则 getter（reload 或追加后无需重建规则集）、
+ * 候选模式生成、持久化副作用（文件读写留在调用方）。
+ */
+export function createApprovalRuleSet(options: ApprovalRuleSetOptions): ApprovalRuleSet {
+  const { rules, suggestPatterns, persist } = options;
+
+  /** 最后一条匹配 input 的规则；数组靠后者优先（对齐 opencode PermissionV2）。 */
+  function lastMatch(input: string): ApprovalRule | undefined {
+    return rules().findLast((rule) => matchRule(input, rule.pattern));
+  }
+
+  function isAllowed(pattern: string): boolean {
+    return lastMatch(pattern)?.action === "allow";
   }
-  let allowed = 0;
-  for (const raw of raws) {
-    const rule = rules.findLast((r) => matchRule(raw, r.pattern));
-    if (rule?.action === "deny") {
-      return "deny";
+
+  async function evaluate(command: string): Promise<ApprovalAction | undefined> {
+    const parsed = await parseBashCommands(command);
+    // 匹配输入是命令原文（tree-sitter command 节点 text，含嵌套逐条展开），
+    // 对齐 opencode shell.ts 的 patterns；通配规则按字面写，`--` 与普通 token 无区别。
+    const raws = flattenCommands(parsed).map((cmd) => cmd.raw);
+    if (raws.length === 0) {
+      return; // 空命令或解析失败：没有可匹配的命令，交人审
+    }
+    let allowed = 0;
+    for (const raw of raws) {
+      const rule = lastMatch(raw);
+      if (rule?.action === "deny") {
+        return "deny";
+      }
+      if (rule?.action === "allow") {
+        allowed++;
+      }
+    }
+    // 文件输出重定向不自动放行：即使命令规则全匹配也交人审
+    if (parsed.hasFileOutputRedirect) {
+      return;
     }
-    if (rule?.action === "allow") {
-      allowed++;
+    // allow 需全量：有命令未命中规则时交人审，避免未允许的命令被同链放行带过
+    return allowed === raws.length ? "allow" : undefined;
+  }
+
+  async function pendingPatterns(command: string): Promise<string[]> {
+    const pending: string[] = [];
+    const seen = new Set<string>();
+    for (const pattern of await suggestPatterns(command)) {
+      if (seen.has(pattern) || isAllowed(pattern)) {
+        continue;
+      }
+      seen.add(pattern);
+      pending.push(pattern);
     }
+    return pending;
   }
-  if (parsed.hasFileOutputRedirect) {
-    return;
+
+  async function addAllowRules(patterns: readonly string[]): Promise<void> {
+    const additions: ApprovalRule[] = patterns.map((pattern) => ({ action: "allow", pattern }));
+    if (additions.length === 0) {
+      return; // 解析失败或未勾选：本次处理，不写配置
+    }
+    await persist(additions);
   }
-  return allowed === raws.length ? "allow" : undefined;
+
+  return { evaluate, isAllowed, pendingPatterns, addAllowRules };
 }

package/src/bwrap/approval-suggest.ts

@@ -8,7 +8,7 @@
  */
 import { readFileSync } from "node:fs";
 
-import { type BashCommand, parseBashCommands } from "./approval-rules.js";
+import { type BashCommand, flattenCommands, parseBashCommands } from "./approval-rules.js";
 
 /**
  * 命令前缀 → 定义该命令的 token 数。`git checkout main` → `git` 的 arity 2，
@@ -41,21 +41,7 @@ export function commandPattern(command: BashCommand): string {
 }
 
 /** 命令（含所有嵌套命令）的 BashArity 建议模式列表（命令替换里的命令也展开）。 */
-function patternsFromCommands(commands: BashCommand[]): string[] {
-  const flat: string[] = [];
-  const visit = (cmd: BashCommand) => {
-    flat.push(commandPattern(cmd));
-    for (const nested of cmd.nested) {
-      visit(nested);
-    }
-  };
-  for (const cmd of commands) {
-    visit(cmd);
-  }
-  return flat;
-}
-
 export async function commandPatternsFor(command: string): Promise<string[]> {
   const parsed = await parseBashCommands(command);
-  return patternsFromCommands(parsed.commands);
+  return flattenCommands(parsed).map((cmd) => commandPattern(cmd));
 }

package/src/bwrap/core.ts

@@ -1,23 +1,17 @@
-import { type ChildProcess, spawn } from "node:child_process";
-import { constants, type Dirent, existsSync, readFileSync } from "node:fs";
-import { access as fsAccess, readdir, realpath, stat } from "node:fs/promises";
+import { type Dirent, existsSync, readFileSync } from "node:fs";
+import { readdir, realpath, stat } from "node:fs/promises";
 import { delimiter, join } from "node:path";
 import process from "node:process";
 
 import { StringEnum } from "@earendil-works/pi-ai";
-import { type BashOperations, getAgentDir, getShellConfig } from "@earendil-works/pi-coding-agent";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { type Static, Type } from "typebox";
 import { Value } from "typebox/value";
 
 import { parseWithSchema } from "../lib/parse-with-schema.js";
 import { expandHome } from "../lib/path.js";
 import { type ApprovalRule } from "./approval-rules.js";
-import {
-  type NetworkStack,
-  resolveDnsServers,
-  startNetworkStack,
-  TimeoutError,
-} from "./network-stack.js";
+import { type NetworkStack, resolveDnsServers, startNetworkStack } from "./network-stack.js";
 
 const PROTECTED_DIRS = [".pi", ".agent"];
 
@@ -452,17 +446,6 @@ export async function buildBwrapArgs(resolved: ResolvedBwrap, cwd: string): Prom
   return args;
 }
 
-function killChild(child: ChildProcess): void {
-  if (!child.pid) {
-    return;
-  }
-  try {
-    process.kill(-child.pid, "SIGKILL");
-  } catch {
-    child.kill("SIGKILL");
-  }
-}
-
 /** 网络栈子进程输出转发通道，仅用于诊断（默认丢弃）。 */
 export interface NetworkStackLog {
   holder?: (chunk: string) => void;
@@ -484,150 +467,3 @@ export async function createNetworkStack(
     ...(log?.holder && { onHolderOutput: log.holder }),
   });
 }
-
-/** 一次 bwrap 调用的完整组装结果：argv 与干净环境。 */
-export interface BwrapInvocation {
-  /** bwrap 可执行文件路径 */
-  file: string;
-  /** bwrap 参数（不含结尾的 `-- shell -lc command`） */
-  args: string[];
-  /** 沙箱内 shell 的绝对路径 */
-  shell: string;
-  /** 交给 shell 的命令 */
-  command: string;
-  /** 命令执行目录 */
-  cwd: string;
-  /** 沙箱内环境（不继承父进程） */
-  env: Record<string, string>;
-  /** network limited 模式：命令需先经 nsenter 进入 holder 的 netns。 */
-  needsNetworkStack: boolean;
-}
-
-/**
- * 组装一次 bwrap 调用。实际执行（createBwrapBashOperations）与调试打印共用这里，
- * 保证 `--print-args` 输出的命令行与真正跑的那条完全一致。
- */
-export async function buildBwrapInvocation(
-  resolved: ResolvedBwrap,
-  workspace: string,
-  command: string,
-  cwd: string,
-): Promise<BwrapInvocation> {
-  // 干净环境：不继承父进程 env/PATH，由 bash -lc 从 /etc/profile 与用户 profile 重建
-  const home = process.env.HOME;
-  if (home === undefined) {
-    throw new Error("HOME is not set; refusing to run bash in a clean environment");
-  }
-  return {
-    // 沙箱内不透传 PATH，execvp 的默认路径可能找不到 bash（如 NixOS），故在父进程解析绝对路径
-    shell: getShellConfig().shell,
-    file: findBwrap(resolved.bwrapPath),
-    args: [
-      "--ro-bind",
-      "/",
-      "/",
-      ...(await buildBwrapArgs(resolved, workspace)),
-      "--dev",
-      "/dev",
-      "--proc",
-      "/proc",
-    ],
-    command,
-    cwd,
-    env: {
-      HOME: home,
-      SHELL: "/bin/bash",
-      TERM: "dumb",
-      LANG: "C.UTF-8",
-      // 基础 PATH：profile 加载阶段（设置 PATH 前）需要系统命令（如 id），由 profile 随后覆盖；不含 sbin
-      PATH: "/usr/local/bin:/usr/bin:/bin",
-    },
-    needsNetworkStack: resolved.network === "limited",
-  };
-}
-
-/** 完整 argv（`[bwrap, ...args, "--", shell, "-lc", command]`），spawn 与打印共用。 */
-export function bwrapArgv(invocation: BwrapInvocation): string[] {
-  return [invocation.file, ...invocation.args, "--", invocation.shell, "-lc", invocation.command];
-}
-
-/**
- * @param workspace session 工作区：writablePaths 的 "." 与 PROTECTED_DIRS 都基于它解析，
- *   与当次命令的 cwd（仅作为进程执行目录）解耦，避免 workdir 参数漂移可写边界。
- */
-export function createBwrapBashOperations(
-  resolved: ResolvedBwrap,
-  workspace: string,
-  networkStack?: NetworkStack,
-): BashOperations {
-  return {
-    async exec(command, cwd, { onData, signal, timeout }) {
-      await fsAccess(cwd, constants.F_OK).catch(() => {
-        throw new Error(`Working directory does not exist: ${cwd}\nCannot execute bash commands.`);
-      });
-      // 已中断（signal.reason 是 name=AbortError 的 DOMException）：直接抛，不再执行
-      signal?.throwIfAborted();
-
-      const invocation = await buildBwrapInvocation(resolved, workspace, command, cwd);
-
-      if (invocation.needsNetworkStack) {
-        if (!networkStack) {
-          throw new Error("Network stack is not initialized for network limited mode");
-        }
-        return networkStack.exec({
-          command,
-          cwd,
-          bwrapPath: invocation.file,
-          bwrapArgs: invocation.args,
-          shell: invocation.shell,
-          env: invocation.env,
-          onData,
-          signal,
-          timeout,
-        });
-      }
-
-      const argv = bwrapArgv(invocation);
-      const child = spawn(argv[0], argv.slice(1), {
-        cwd,
-        detached: true,
-        stdio: ["ignore", "pipe", "pipe"],
-        env: invocation.env,
-      });
-
-      return new Promise<{ exitCode: number | null }>((resolve, reject) => {
-        let timedOut = false;
-        const timeoutHandle = timeout
-          ? setTimeout(() => {
-              timedOut = true;
-              killChild(child);
-            }, timeout * 1000)
-          : undefined;
-        const onAbort = () => killChild(child);
-        child.stdout.on("data", onData);
-        child.stderr.on("data", onData);
-        signal?.addEventListener("abort", onAbort, { once: true });
-        child.once("error", reject);
-        child.once("close", (exitCode) => {
-          if (timeoutHandle) {
-            clearTimeout(timeoutHandle);
-          }
-          signal?.removeEventListener("abort", onAbort);
-          // 中断：reject signal.reason（默认是 name=AbortError 的 DOMException）
-          if (signal?.aborted) {
-            reject(
-              signal.reason instanceof Error
-                ? signal.reason
-                : new Error("The operation was aborted"),
-            );
-          } else if (timedOut) {
-            // 超时：name=TimeoutError（对齐标准错误分类）
-            reject(new TimeoutError(timeout));
-          } else {
-            resolve({ exitCode });
-          }
-        });
-      });
-    },
-  };
-}

package/src/bwrap/exec.ts

@@ -0,0 +1,246 @@
+/**
+ * 执行层：把一次组装好的 bwrap 调用变成进程。
+ *
+ * 完整命令行只在这里组装（`invocationArgv`），子进程生命周期只有一份实现
+ * （`execInvocation`）——direct 与经 `nsenter` 进 holder netns 两条路径共用，
+ * 预览（`--print-args`）也走同一次组装，超时 / 中断 / 启动失败的错误语义与
+ * 打印出的命令行因此不会漂移。argv 内容与配置解析由 core.ts 提供；holder pid
+ * 由 network-stack.ts 提供，网络栈本身不知道 bwrap 参数怎么拼。
+ */
+
+import { spawn } from "node:child_process";
+import { constants } from "node:fs";
+import { access as fsAccess } from "node:fs/promises";
+
+import { type BashOperations, getShellConfig } from "@earendil-works/pi-coding-agent";
+
+import { buildBwrapArgs, findBwrap, type ResolvedBwrap } from "./core.js";
+import type { NetworkStack } from "./network-stack.js";
+
+/** 命令超时错误：name=TimeoutError（对齐标准错误分类），message 保留 timeout:N 格式。 */
+export class TimeoutError extends Error {
+  constructor(timeout: number | undefined) {
+    super(`timeout:${timeout}`);
+    this.name = "TimeoutError";
+  }
+}
+
+/** 一次 bwrap 调用的完整组装结果：argv 与干净环境。 */
+export interface BwrapInvocation {
+  /** bwrap 可执行文件路径 */
+  file: string;
+  /** bwrap 参数（不含结尾的 `-- shell -lc command`） */
+  args: string[];
+  /** 沙箱内 shell 的绝对路径 */
+  shell: string;
+  /** 交给 shell 的命令 */
+  command: string;
+  /** 沙箱内环境（不继承父进程） */
+  env: Record<string, string>;
+  /** network limited 模式：命令需先经 nsenter 进入 holder 的 netns。 */
+  needsNetworkStack: boolean;
+}
+
+/**
+ * 组装一次 bwrap 调用。实际执行（`execInvocation`）与调试打印共用这里，
+ * 保证 `--print-args` 输出的命令行与真正跑的那条完全一致。
+ */
+export async function buildBwrapInvocation(
+  resolved: ResolvedBwrap,
+  workspace: string,
+  command: string,
+): Promise<BwrapInvocation> {
+  // 干净环境：不继承父进程 env/PATH，由 bash -lc 从 /etc/profile 与用户 profile 重建
+  const home = process.env.HOME;
+  if (home === undefined) {
+    throw new Error("HOME is not set; refusing to run bash in a clean environment");
+  }
+  return {
+    // 沙箱内不透传 PATH，execvp 的默认路径可能找不到 bash（如 NixOS），故在父进程解析绝对路径
+    shell: getShellConfig().shell,
+    file: findBwrap(resolved.bwrapPath),
+    args: [
+      "--ro-bind",
+      "/",
+      "/",
+      ...(await buildBwrapArgs(resolved, workspace)),
+      "--dev",
+      "/dev",
+      "--proc",
+      "/proc",
+    ],
+    command,
+    env: {
+      HOME: home,
+      SHELL: "/bin/bash",
+      TERM: "dumb",
+      LANG: "C.UTF-8",
+      // 基础 PATH：profile 加载阶段（设置 PATH 前）需要系统命令（如 id），由 profile 随后覆盖；不含 sbin
+      PATH: "/usr/local/bin:/usr/bin:/bin",
+    },
+    needsNetworkStack: resolved.network === "limited",
+  };
+}
+
+/**
+ * 完整命令行：`[bwrap, ...args, "--", shell, "-lc", command]`；传 `nsenterPid` 时
+ * 前置 `nsenter` 前缀进入该 holder 的 userns + netns。
+ *
+ * 预览与实际执行都调用这里——`nsenterPid` 传数字是真实 holder pid，传字符串是
+ * 尚未启动时的占位符（打印用），不传即纯 bwrap 命令行。
+ */
+export function invocationArgv(
+  invocation: BwrapInvocation,
+  nsenterPid?: number | string,
+): string[] {
+  const argv = [
+    invocation.file,
+    ...invocation.args,
+    "--",
+    invocation.shell,
+    "-lc",
+    invocation.command,
+  ];
+  if (nsenterPid === undefined) {
+    return argv;
+  }
+  return ["nsenter", "-U", "-n", "--preserve-credentials", "-t", String(nsenterPid), "--", ...argv];
+}
+
+function killChild(pid: number | undefined): void {
+  if (!pid) {
+    return;
+  }
+  try {
+    process.kill(-pid, "SIGKILL");
+  } catch {
+    try {
+      process.kill(pid, "SIGKILL");
+    } catch {
+      // 已退出
+    }
+  }
+}
+
+export interface ExecInvocationOptions {
+  /** 命令执行目录（进程 cwd）；沙箱内可写边界由 invocation 的挂载项决定，与此无关。 */
+  cwd: string;
+  /** netns holder pid：invocation 需要网络栈时必填，缺失即抛错。 */
+  holderPid?: number;
+  /** 流式输出回调（stdout 与 stderr 已合并）。 */
+  onData: (data: Buffer) => void;
+  /** 取消：终止整个进程组并以 signal.reason（默认 AbortError）结束。 */
+  signal?: AbortSignal;
+  /** 超时秒数：终止整个进程组并以 TimeoutError 结束。 */
+  timeout?: number;
+}
+
+/**
+ * 执行一次组装好的调用（唯一一处 spawn 与生命周期）。
+ *
+ * 需要网络栈时自动前置 `nsenter` 前缀；进程以独立进程组启动，超时与取消都
+ * 终止整组，启动失败（spawn error）立即结束且不残留超时定时器。
+ */
+export function execInvocation(
+  invocation: BwrapInvocation,
+  options: ExecInvocationOptions,
+): Promise<{ exitCode: number | null }> {
+  if (invocation.needsNetworkStack && options.holderPid === undefined) {
+    return Promise.reject(new Error("Network stack is not initialized for network limited mode"));
+  }
+  const argv = invocationArgv(
+    invocation,
+    invocation.needsNetworkStack ? options.holderPid : undefined,
+  );
+  const child = spawn(argv[0], argv.slice(1), {
+    cwd: options.cwd,
+    detached: true,
+    stdio: ["ignore", "pipe", "pipe"],
+    env: invocation.env,
+  });
+
+  return new Promise<{ exitCode: number | null }>((resolve, reject) => {
+    let timedOut = false;
+    let settled = false;
+    const timeoutHandle = options.timeout
+      ? setTimeout(() => {
+          timedOut = true;
+          killChild(child.pid);
+        }, options.timeout * 1000)
+      : undefined;
+    const onAbort = (): void => {
+      killChild(child.pid);
+    };
+    // 结算一次：无论走 error 还是 close，都清掉超时定时器与 abort 监听——挂着的
+    // 定时器会白占事件循环到超时那一刻。
+    const settle = (): boolean => {
+      if (settled) {
+        return false;
+      }
+      settled = true;
+      if (timeoutHandle) {
+        clearTimeout(timeoutHandle);
+      }
+      options.signal?.removeEventListener("abort", onAbort);
+      return true;
+    };
+
+    child.stdout.on("data", options.onData);
+    child.stderr.on("data", options.onData);
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+
+    child.once("error", (error) => {
+      if (!settle()) {
+        return;
+      }
+      reject(error);
+    });
+    child.once("close", (exitCode) => {
+      if (!settle()) {
+        return;
+      }
+      // 中断：reject signal.reason（默认是 name=AbortError 的 DOMException）
+      if (options.signal?.aborted) {
+        reject(
+          options.signal.reason instanceof Error
+            ? options.signal.reason
+            : new Error("The operation was aborted"),
+        );
+      } else if (timedOut) {
+        // 超时：name=TimeoutError（对齐标准错误分类）
+        reject(new TimeoutError(options.timeout));
+      } else {
+        resolve({ exitCode });
+      }
+    });
+  });
+}
+
+/**
+ * @param workspace session 工作区：writablePaths 的 "." 与 PROTECTED_DIRS 都基于它解析，
+ *   与当次命令的 cwd（仅作为进程执行目录）解耦，避免 workdir 参数漂移可写边界。
+ */
+export function createBwrapBashOperations(
+  resolved: ResolvedBwrap,
+  workspace: string,
+  networkStack?: NetworkStack,
+): BashOperations {
+  return {
+    async exec(command, cwd, { onData, signal, timeout }) {
+      await fsAccess(cwd, constants.F_OK).catch(() => {
+        throw new Error(`Working directory does not exist: ${cwd}\nCannot execute bash commands.`);
+      });
+      // 已中断（signal.reason 是 name=AbortError 的 DOMException）：直接抛，不再执行
+      signal?.throwIfAborted();
+
+      const invocation = await buildBwrapInvocation(resolved, workspace, command);
+      return execInvocation(invocation, {
+        cwd,
+        holderPid: networkStack?.holderPid,
+        onData,
+        signal,
+        timeout,
+      });
+    },
+  };
+}

package/src/bwrap/network-stack.ts

@@ -9,14 +9,6 @@ import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { forEachLine } from "../lib/proc.js";
 import { generateMihomoConfig, TUN_MTU } from "./mihomo-config.js";
 
-/** 命令超时错误：name=TimeoutError（对齐标准错误分类），message 保留 timeout:N 格式。 */
-export class TimeoutError extends Error {
-  constructor(timeout: number | undefined) {
-    super(`timeout:${timeout}`);
-    this.name = "TimeoutError";
-  }
-}
-
 export interface NetworkStackOptions {
   /** 允许直连的域名 / IP:port 列表（每次命令从配置重新读取）。 */
   readonly allowlist: readonly string[];
@@ -31,19 +23,6 @@ export interface NetworkStackOptions {
   readonly onHolderOutput?: (chunk: string) => void;
 }
 
-interface NetworkStackExecOptions {
-  readonly command: string;
-  readonly cwd: string;
-  readonly bwrapPath: string;
-  /** bwrap 的完整参数（不含 -- 后的 shell 与命令），由 core.ts 组装。 */
-  readonly bwrapArgs: readonly string[];
-  readonly shell: string;
-  readonly env: Readonly<Record<string, string>>;
-  readonly onData: (data: Buffer) => void;
-  readonly signal?: AbortSignal;
-  readonly timeout?: number;
-}
-
 const NAMESERVER_PATTERN = /^\s*nameserver\s+(\S+)/;
 
 /**
@@ -198,21 +177,6 @@ function waitForMihomoStarted(holder: ChildProcess, timeoutMs = 20000): Promise<
   });
 }
 
-function killChild(pid: number | undefined): void {
-  if (!pid) {
-    return;
-  }
-  try {
-    process.kill(-pid, "SIGKILL");
-  } catch {
-    try {
-      process.kill(pid, "SIGKILL");
-    } catch {
-      // 已退出
-    }
-  }
-}
-
 /**
  * 额外转发子进程输出给诊断回调（就绪探测的监听器不受影响），并把全部输出
  * 收进 collect：启动失败时落盘，否则没有别的渠道能看到 holder 的真实死因。
@@ -237,7 +201,6 @@ function forwardOutput(
 }
 
 export interface NetworkStack {
-  exec(options: NetworkStackExecOptions): Promise<{ exitCode: number | null }>;
   stop(): Promise<void>;
   /** holder pid：可 `nsenter -U -n --preserve-credentials -t <pid>` 手动进入该 netns 排查。 */
   readonly holderPid: number;
@@ -391,80 +354,6 @@ export async function startNetworkStack(options: NetworkStackOptions): Promise<N
 
     const state: NetworkStackState = { holderPid, slirpPid: slirp.pid, mihomoHome };
     const stack: NetworkStack = {
-      exec: async (execOptions: NetworkStackExecOptions) => {
-        const child = spawn(
-          "nsenter",
-          [
-            "-U",
-            "-n",
-            "--preserve-credentials",
-            "-t",
-            String(holderPid),
-            "--",
-            execOptions.bwrapPath,
-            ...execOptions.bwrapArgs,
-            "--",
-            execOptions.shell,
-            "-lc",
-            execOptions.command,
-          ],
-          {
-            cwd: execOptions.cwd,
-            detached: true,
-            stdio: ["ignore", "pipe", "pipe"],
-            env: execOptions.env,
-          },
-        );
-
-        return new Promise<{ exitCode: number | null }>((resolve, reject) => {
-          let timedOut = false;
-          let settled = false;
-          const timeoutHandle = execOptions.timeout
-            ? setTimeout(() => {
-                timedOut = true;
-                killChild(child.pid);
-              }, execOptions.timeout * 1000)
-            : undefined;
-          const onAbort = (): void => {
-            killChild(child.pid);
-          };
-
-          child.stdout.on("data", execOptions.onData);
-          child.stderr.on("data", execOptions.onData);
-          execOptions.signal?.addEventListener("abort", onAbort, { once: true });
-
-          child.once("error", (error) => {
-            if (settled) {
-              return;
-            }
-            settled = true;
-            reject(error);
-          });
-          child.once("close", (exitCode) => {
-            if (settled) {
-              return;
-            }
-            settled = true;
-            if (timeoutHandle) {
-              clearTimeout(timeoutHandle);
-            }
-            execOptions.signal?.removeEventListener("abort", onAbort);
-            // 中断：reject signal.reason（默认是 name=AbortError 的 DOMException）
-            if (execOptions.signal?.aborted) {
-              reject(
-                execOptions.signal.reason instanceof Error
-                  ? execOptions.signal.reason
-                  : new Error("The operation was aborted"),
-              );
-            } else if (timedOut) {
-              // 超时：name=TimeoutError（对齐标准错误分类）
-              reject(new TimeoutError(execOptions.timeout));
-            } else {
-              resolve({ exitCode });
-            }
-          });
-        });
-      },
       stop: async () => {
         const children = await readChildPids(state.holderPid);
         // slirp4netns 持有 tap fd（pin 住 netns），必须随 holder 一起显式终止；

package/src/bwrap/runtime.ts

@@ -14,17 +14,24 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { throttle } from "lodash-es";
 import { type TObject, Type } from "typebox";
+import { Value } from "typebox/value";
 
 import { type CommandSpec, parseCommand } from "../lib/cli.js";
 import { fenceCodeBlock } from "../lib/markdown.js";
 import { isUnknownArray } from "../lib/narrow.js";
+import { parseWithSchema } from "../lib/parse-with-schema.js";
 import { formatDisplayPath } from "../lib/path.js";
 import { createRequestPolicy, type RequestPolicy } from "../lib/request-policy.js";
 import { type SelectAction, selectMultiple, selectWithOptionalInput } from "../lib/ui.js";
-import { type ApprovalRule, evaluateBashApproval, matchRule } from "./approval-rules.js";
+import {
+  type ApprovalRule,
+  type ApprovalRuleSet,
+  createApprovalRuleSet,
+} from "./approval-rules.js";
 import { commandPatternsFor } from "./approval-suggest.js";
 import {
   type BwrapConfig,
+  bwrapConfigFileSchema,
   findBwrap,
   findMihomo,
   type FsMode,
@@ -381,6 +388,20 @@ export function sandboxHintBlock(hint: string | undefined): { type: "text"; text
   return hint === undefined ? [] : [{ type: "text", text: hint }];
 }
 
+/**
+ * 项目配置文件形状非法时的错误：消息带文件路径与字段位置，cause 保留校验错误
+ * （Value.Check 只回答是否合法，详情用同一 schema 解析一次取到）。
+ */
+function invalidConfigError(path: string, raw: unknown): Error {
+  try {
+    parseWithSchema(bwrapConfigFileSchema, raw);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    return new Error(`Invalid bwrap configuration at ${path}: ${detail}`, { cause: error });
+  }
+  return new Error(`Invalid bwrap configuration at ${path}: schema validation failed`);
+}
+
 export class BwrapRuntime {
   private resolved: ResolvedBwrap | undefined;
   private bwrapUnavailable = false;
@@ -539,8 +560,14 @@ export class BwrapRuntime {
       ) {
         throw new Error(UNSANDBOXED_DENIED);
       }
-      // 先按 approvalRules 自动判定：allow 直接放行，deny 直接拒绝，未命中才弹框
-      const decision = await evaluateBashApproval(request.command, runtime.approvalRules);
+      // 先按 approvalRules 自动判定：allow 直接放行，deny 直接拒绝，未命中才弹框。
+      // 规则集跟随 this.resolved，reload 或追加规则后无需重建
+      const ruleSet = createApprovalRuleSet({
+        rules: () => this.resolve(request.ctx).approvalRules,
+        suggestPatterns: commandPatternsFor,
+        persist: (rules) => this.persistAllowRules(request.ctx, rules),
+      });
+      const decision = await ruleSet.evaluate(request.command);
       if (decision === "deny") {
         throw new Error(`Command denied by bwrap approval rule: ${request.command}`);
       }
@@ -551,6 +578,7 @@ export class BwrapRuntime {
             request.command,
             request.description,
             execCwd,
+            ruleSet,
           )) === "sandbox";
       }
     }
@@ -686,12 +714,13 @@ export class BwrapRuntime {
     command: string,
     reason: string | undefined,
     execCwd: string,
+    ruleSet: ApprovalRuleSet,
   ): Promise<FullAccessGrant> {
     // hasUI 判定推迟到审批时刻：无 UI 会话弹不了审批框，按用户点 Deny 的标准文案拒绝
     if (!ctx.hasUI) {
       throw new Error(UNSANDBOXED_DENIED);
     }
-    const decision = await this.approveFullAccessUI(ctx, command, reason, execCwd);
+    const decision = await this.approveFullAccessUI(ctx, command, reason, execCwd, ruleSet);
     // 关闭对话框 = 中断并拒绝，不循环重问
     if (decision === undefined) {
       ctx.abort();
@@ -706,13 +735,13 @@ export class BwrapRuntime {
       }
       case DENY: {
         if (foreverApprovedPattern.length > 0) {
-          await this.persistAllowRule(ctx, command, foreverApprovedPattern);
+          await ruleSet.addAllowRules(foreverApprovedPattern);
         }
         throw new Error(UNSANDBOXED_DENIED);
       }
       case DENY_WITH_REASON: {
         if (foreverApprovedPattern.length > 0) {
-          await this.persistAllowRule(ctx, command, foreverApprovedPattern);
+          await ruleSet.addAllowRules(foreverApprovedPattern);
         }
         const feedback = decision.reason?.trim() ?? "";
         throw new Error(
@@ -723,7 +752,7 @@ export class BwrapRuntime {
       }
       case ALLOW_ONCE: {
         if (foreverApprovedPattern.length > 0) {
-          await this.persistAllowRule(ctx, command, foreverApprovedPattern);
+          await ruleSet.addAllowRules(foreverApprovedPattern);
         }
         return "full-access";
       }
@@ -744,22 +773,14 @@ export class BwrapRuntime {
     command: string,
     reason: string | undefined,
     execCwd: string,
+    ruleSet: ApprovalRuleSet,
   ): Promise<FullAccessUIDecision | undefined> {
     // 弹框前解析命令的持久化规则：`echo 1 | head` → `echo *`、`head *`。
     // 持久化规则的勾选折叠进 EDIT_RULES 子菜单，主决策列表只保留放行/拒绝，
     // 避免一屏 checkbox 淹没决策项。
-    const patterns = await commandPatternsFor(command);
     // 子菜单只列出未命中 allow 规则的 pattern：已提前允许的部分自动放行，
     // 无需再展示或重复勾选持久化（deny 命中的命令在 evaluate 阶段已被拒绝）。
-    const rules = this.resolve(ctx).approvalRules;
-    const unallowedPatterns = [
-      ...new Set(
-        patterns.filter((pattern) => {
-          const rule = rules.findLast((r) => matchRule(pattern, r.pattern));
-          return rule?.action !== "allow";
-        }),
-      ),
-    ];
+    const unallowedPatterns = await ruleSet.pendingPatterns(command);
     // dcg 扫描建议是可选的参考文本：未安装时静默跳过；已安装但扫描失败
     // 时 notify 提示，弹窗本身与无 dcg 时一致
     const outcome = await dcgSuggestion(command);
@@ -837,23 +858,27 @@ export class BwrapRuntime {
     }
   }
 
-  /** 把命令的权限模式写入项目 sandbox.json 的 approvalRules（allow forever）。 */
-  private async persistAllowRule(
+  /**
+   * 规则集的持久化实现：把勾选的 allow 规则追加进项目 sandbox.json 的
+   * approvalRules，并刷新缓存的规则使其立即生效。
+   */
+  private async persistAllowRules(
     ctx: ExtensionContext,
-    command: string,
-    patterns?: string[],
+    newRules: readonly ApprovalRule[],
   ): Promise<void> {
-    const rulePatterns = patterns ?? (await commandPatternsFor(command));
-    if (rulePatterns.length === 0) {
-      return; // 解析失败：本次处理，不写规则
-    }
-    const newRules: ApprovalRule[] = rulePatterns.map((pattern) => ({ action: "allow", pattern }));
     const { project } = getBwrapConfigPaths(ctx.cwd);
     let config: Record<string, unknown> = {};
     if (existsSync(project)) {
-      config = JSON.parse(readFileSync(project, "utf8")) as Record<string, unknown>;
+      const raw: unknown = JSON.parse(readFileSync(project, "utf8"));
+      // 会话开始时已校验过配置文件：这里再查一次形状（Value.Check 同时收窄类型），
+      // 避免把新规则追加进一个后续加载必然失败的文件（只在配置文件被中途改坏时可达）
+      if (!Value.Check(bwrapConfigFileSchema, raw)) {
+        throw invalidConfigError(project, raw);
+      }
+      config = raw;
     }
-    // 既有规则按不透明值原样保留（形状不认识也不丢），只追加本次允许的规则。
+    // 既有规则按不透明值原样保留（形状不认识也不丢），只追加本次允许的规则；
+    // 与规则无关的字段（含不认识的）同样原样写回，不经过 schema 往返
     const existing = isUnknownArray(config.approvalRules) ? config.approvalRules : [];
     config.approvalRules = [...existing, ...newRules];
     await mkdir(dirname(project), { recursive: true });

package/src/bwrap/sandbox.ts

@@ -16,10 +16,7 @@ import { createLocalBashOperations } from "@earendil-works/pi-coding-agent";
 
 import { expandHome } from "../lib/path.js";
 import {
-  buildBwrapInvocation,
-  bwrapArgv,
   type BwrapConfig,
-  createBwrapBashOperations,
   createNetworkStack,
   type FsMode,
   getBwrapConfigPaths,
@@ -30,6 +27,7 @@ import {
   resolveBwrapPath,
   type ResolvedBwrap,
 } from "./core.js";
+import { buildBwrapInvocation, createBwrapBashOperations, invocationArgv } from "./exec.js";
 import type { NetworkStack } from "./network-stack.js";
 
 export interface SandboxConfigInput {
@@ -161,7 +159,7 @@ export interface SandboxPreview {
 }
 
 /**
- * 打印将要执行的命令行（`--print-args`）。与 runInSandbox 共用同一段组装逻辑，
+ * 打印将要执行的命令行（`--print-args`）。与 `execInvocation` 共用同一段组装，
  * 不存在「打印的是一回事、跑的是另一回事」的漂移。
  */
 export async function previewSandboxCommand(
@@ -171,23 +169,13 @@ export async function previewSandboxCommand(
   },
 ): Promise<SandboxPreview> {
   const workspace = expandHome(options.workspace);
-  const commandCwd = expandHome(options.commandCwd ?? workspace);
-  const invocation = await buildBwrapInvocation(resolved, workspace, options.command, commandCwd);
+  const invocation = await buildBwrapInvocation(resolved, workspace, options.command);
   if (!invocation.needsNetworkStack || options.unsandboxed === true) {
-    return { argv: bwrapArgv(invocation), env: invocation.env, needsNetworkStack: false };
+    return { argv: invocationArgv(invocation), env: invocation.env, needsNetworkStack: false };
   }
   return {
-    // 与 network-stack.ts 的实际 spawn 一致；holder 未启动时用占位符标出 pid 的位置
-    argv: [
-      "nsenter",
-      "-U",
-      "-n",
-      "--preserve-credentials",
-      "-t",
-      options.holderPid === undefined ? HOLDER_PID_PLACEHOLDER : String(options.holderPid),
-      "--",
-      ...bwrapArgv(invocation),
-    ],
+    // holder 未启动时用占位符标出 pid 的位置
+    argv: invocationArgv(invocation, options.holderPid ?? HOLDER_PID_PLACEHOLDER),
     env: invocation.env,
     needsNetworkStack: true,
   };

package/src/lib/lsp/client.ts

@@ -1123,6 +1123,56 @@ export async function create(input: CreateInput): Promise<LspClient> {
     });
   }
 
+  /** 轮询的归宿：谁先让等待收敛，以及没有收敛时是哪一种耗尽。 */
+  type PollOutcome = "pulled" | "pushed" | "pullTimedOut" | "budgetExhausted";
+
+  /**
+   * 等「当前文档版本」的诊断就绪，两种等待模式的唯一一份轮询实现。
+   * pull 与 push 语义相同（都是等当前文档版本的诊断结果）：先 pull，拿到就绪结论
+   * 即返回；pull 超时说明服务器未响应，不再重试 pull，把「是否退回等 push」交给
+   * 调用方；否则进入三路竞速——版本匹配的 push / 服务器注册表变化 / pull 重试间隔，
+   * 除 push 命中外都再来一轮，直到预算耗尽、连接关闭或等待被中断。
+   */
+  async function pollUntilSettled(request: {
+    path: string;
+    /** 本次等待的预算（毫秒）。 */
+    budgetMs: number;
+    /** 预算起点（调用方传 request.after ?? Date.now()）。 */
+    startedAt: number;
+    /** 版本匹配的 push 兜底，由调用方按自己的预算创建。 */
+    pushWait: Promise<boolean>;
+    /** pull 入口（两种模式各自的那一个）。 */
+    pull: (path: string) => Promise<PullResult>;
+    /** 该模式的就绪判据。 */
+    isSettled: (result: PullResult) => boolean;
+    signal?: AbortSignal;
+  }): Promise<PollOutcome> {
+    while (!connectionClosed && !request.signal?.aborted) {
+      const remaining = request.budgetMs - (Date.now() - request.startedAt);
+      if (remaining <= 0) {
+        return "budgetExhausted";
+      }
+      const result = await request.pull(request.path);
+      if (request.isSettled(result)) {
+        return "pulled";
+      }
+      if (result.timedOut) {
+        return "pullTimedOut";
+      }
+      const next = await Promise.race([
+        request.pushWait.then((ready) => (ready ? ("push" as const) : ("timeout" as const))),
+        waitForRegistrationChange(remaining).then((changed) =>
+          changed ? ("registration" as const) : ("timeout" as const),
+        ),
+        sleep(Math.min(remaining, PULL_RETRY_INTERVAL_MS)).then(() => "interval" as const),
+      ]);
+      if (next === "push") {
+        return "pushed";
+      }
+    }
+    return "budgetExhausted";
+  }
+
   /**
    * 等待「当前文档版本」的诊断结论。返回值表示就绪是否被证实：true = 拿到了
    * 当前版本的诊断结果（push / pull / 已有结论）；false = 等满预算或连接关闭
@@ -1150,9 +1200,6 @@ export async function create(input: CreateInput): Promise<LspClient> {
       files[request.path]?.lastPushEmpty === true
         ? Math.min(diagnosticsDocumentWaitTimeoutMs, diagnosticsSilentWaitTimeoutMs)
         : diagnosticsDocumentWaitTimeoutMs;
-    // pull 与 push 语义相同：都是等「当前文档版本」的诊断结果，统一一个循环。
-    // 先 pull（拿到即返回）；pull 超时说明服务器未响应，不再重试 pull，只等
-    // 版本匹配的 push 兜底；版本不匹配的 push 一律忽略（防迟到旧结果）。
     const pushWait = waitForFreshPush({
       path: request.path,
       version: request.version,
@@ -1160,30 +1207,24 @@ export async function create(input: CreateInput): Promise<LspClient> {
       timeout: budget,
     });
 
-    while (!connectionClosed && !request.signal?.aborted) {
-      const remaining = budget - (Date.now() - startedAt);
-      if (remaining <= 0) {
-        return false;
-      }
-      const result = await requestDocumentDiagnostics(request.path);
-      if (result.matched) {
-        return true;
-      }
-      if (result.timedOut) {
-        return await pushWait;
-      }
-      const next = await Promise.race([
-        pushWait.then((ready) => (ready ? ("push" as const) : ("timeout" as const))),
-        waitForRegistrationChange(remaining).then((changed) =>
-          changed ? ("registration" as const) : ("timeout" as const),
-        ),
-        sleep(Math.min(remaining, PULL_RETRY_INTERVAL_MS)).then(() => "interval" as const),
-      ]);
-      if (next === "push") {
-        return true;
-      }
-    }
-    return false;
+    const outcome = await pollUntilSettled({
+      path: request.path,
+      budgetMs: budget,
+      startedAt,
+      pushWait,
+      pull: requestDocumentDiagnostics,
+      isSettled: (result) => result.matched,
+      signal: request.signal,
+    });
+    // 对应重构前的返回路径：pulled / pushed → `return true`（pull 命中或等到
+    // 版本匹配的 push）；pullTimedOut → `return await pushWait`（pull 挂起不重试，
+    // 但继续等 push 到预算结束，返回是否等到）；budgetExhausted（含连接关闭 /
+    // 中断）→ 循环尾 `return false`。
+    return (
+      outcome === "pulled" ||
+      outcome === "pushed" ||
+      (outcome === "pullTimedOut" && (await pushWait))
+    );
   }
 
   async function waitForFullDiagnostics(request: {
@@ -1200,29 +1241,20 @@ export async function create(input: CreateInput): Promise<LspClient> {
       timeout: diagnosticsFullWaitTimeoutMs,
     });
 
-    while (!connectionClosed && !request.signal?.aborted) {
-      const remaining = diagnosticsFullWaitTimeoutMs - (Date.now() - startedAt);
-      if (remaining <= 0) {
-        return;
-      }
-      const result = await requestFullDiagnostics(request.path);
-      if (result.handled || result.matched) {
-        return;
-      }
-      if (result.timedOut) {
-        await pushWait;
-        return;
-      }
-      const next = await Promise.race([
-        pushWait.then((ready) => (ready ? ("push" as const) : ("timeout" as const))),
-        waitForRegistrationChange(remaining).then((changed) =>
-          changed ? ("registration" as const) : ("timeout" as const),
-        ),
-        sleep(Math.min(remaining, PULL_RETRY_INTERVAL_MS)).then(() => "interval" as const),
-      ]);
-      if (next === "push") {
-        return;
-      }
+    const outcome = await pollUntilSettled({
+      path: request.path,
+      budgetMs: diagnosticsFullWaitTimeoutMs,
+      startedAt,
+      pushWait,
+      pull: requestFullDiagnostics,
+      isSettled: (result) => result.handled || result.matched,
+      signal: request.signal,
+    });
+    // 对应重构前的返回路径：pulled / pushed / budgetExhausted 都对应 `return`
+    // （就绪、等到 push 或耗尽预算）；pullTimedOut → `await pushWait; return`，
+    // 即 pull 挂起后仍等 push 兜底到预算结束，结果丢弃（本函数返回 void）。
+    if (outcome === "pullTimedOut") {
+      await pushWait;
     }
   }