@trim21/personal-pi-extensions 0.1.20261012031237 → 0.1.20261012035337

package/package.json

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

package/src/bwrap/holder.js

@@ -28,7 +28,10 @@ async function waitFor(attempts, delayMs, predicate) {
 async function main() {
   process.stdin.resume();
   process.stdin.on("end", () => process.exit(0));
-  await waitFor(100, 100, tap0Exists);
+  if (!await waitFor(100, 100, tap0Exists)) {
+    console.error("slirp4netns did not create tap0 within 10s");
+    process.exit(1);
+  }
   const mihomo = spawn(mihomoPath, ["-d", mihomoHome, "-config", configBase64], {
     stdio: ["ignore", "inherit", "inherit"]
   });
@@ -43,7 +46,10 @@ async function main() {
     stop();
     process.exit(0);
   });
-  await new Promise((resolve) => mihomo.once("exit", () => resolve()));
+  const exitCode = await new Promise((resolve) => {
+    mihomo.once("exit", (code) => resolve(code));
+  });
+  process.exit(exitCode ?? 1);
 }
 try {
   await main();

package/src/bwrap/holder.ts

@@ -8,6 +8,8 @@ import { setTimeout as sleep } from "node:timers/promises";
 // 否则出站流量会绕回 mihomo 的 TUN 被 dns-hijack 自劫持），它通过 exit-fd 绑定本进程的生命周期：
 // fd 3 是 exit-fd 的写端（network-stack 经 unshare 传入），本进程存活期间保持打开，死亡即关闭，
 // slirp4netns 侧收到 HUP 自行退出并释放 tap fd，netns 引用随之归零。
+// 常规停栈也走这条 stdin EOF 通道（宿主关闭写端而不是按 pid 发信号）：检查 pid 与发信号
+// 之间不是原子的，用 pid 终止可能误伤复用同一 pid 的无关进程。
 const args = process.argv.slice(2);
 const configBase64 = args[0];
 const mihomoPath = args[1];
@@ -45,12 +47,17 @@ async function waitFor(
 async function main(): Promise<void> {
   // 宿主（pi）进程死亡检测：宿主以任何方式退出（含 SIGKILL）都会关闭它持有的 stdin 写端，
   // 这里读到 EOF 即自杀（init 退出即触发内核清理整个 pid ns，顺带关闭 exit-fd 写端）。
+  // 宿主侧的正常停栈同样只是关闭这个写端——这条通道绑定 fd 而非 pid，不存在 pid 复用问题。
   process.stdin.resume();
   process.stdin.on("end", () => process.exit(0));
 
   // tap0 由宿主侧的 slirp4netns（fork 进本 netns）创建，就绪后再拉起 mihomo。
-  // mihomo 日志透传到 holder 的 stdout/stderr，宿主侧监听 "Tun adapter listening" 判定就绪。
-  await waitFor(100, 100, tap0Exists);
+  // 接口没建起来就启动 mihomo 必然失败（配置把出站绑在 tap0 上），宿主侧只会看到
+  // 「过滤进程就绪超时」；这里直接以带原因的失败结束，让真实死因秒级进入诊断日志。
+  if (!(await waitFor(100, 100, tap0Exists))) {
+    console.error("slirp4netns did not create tap0 within 10s");
+    process.exit(1);
+  }
 
   const mihomo = spawn(mihomoPath, ["-d", mihomoHome, "-config", configBase64], {
     stdio: ["ignore", "inherit", "inherit"],
@@ -68,7 +75,11 @@ async function main(): Promise<void> {
     process.exit(0);
   });
 
-  await new Promise<void>((resolve) => mihomo.once("exit", () => resolve()));
+  // 传播 mihomo 的退出码：宿主侧据此区分「过滤进程崩溃」（非零）与「停栈时的优雅退出」
+  const exitCode = await new Promise<number | null>((resolve) => {
+    mihomo.once("exit", (code) => resolve(code));
+  });
+  process.exit(exitCode ?? 1);
 }
 
 try {

package/src/bwrap/network-stack.ts

@@ -6,7 +6,7 @@ import { fileURLToPath } from "node:url";
 
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
-import { forEachLine } from "../lib/proc.js";
+import { childHasExited, forEachLine, killChild, waitForChildExit } from "../lib/proc.js";
 import { generateMihomoConfig, TUN_MTU } from "./mihomo-config.js";
 
 export interface NetworkStackOptions {
@@ -24,6 +24,8 @@ export interface NetworkStackOptions {
 }
 
 const NAMESERVER_PATTERN = /^\s*nameserver\s+(\S+)/;
+/** 停栈时等待单个子进程退出的上限（毫秒）。 */
+const STOP_WAIT_TIMEOUT_MS = 2000;
 
 /**
  * 启动失败时把收集到的子进程完整 stdout/stderr 与错误本身落盘到
@@ -62,40 +64,40 @@ const HOLDER_PATH = fileURLToPath(new URL("holder.js", import.meta.url));
 // ip 通常位于 /usr/sbin 或 /sbin，进程默认 PATH 不含它们；node 则依赖宿主完整 PATH
 const SBIN_PATH_SUFFIX = "/usr/local/sbin:/usr/sbin:/sbin";
 
-function killProcess(pid: number | undefined, signal: NodeJS.Signals = "SIGTERM"): void {
+/** 兜底：对 holder 存活期间读到的 pid ns init pid 发 SIGKILL。 */
+function killInitProcess(pid: number | undefined): void {
   if (!pid) {
     return;
   }
   try {
-    process.kill(pid, signal);
+    process.kill(pid, "SIGKILL");
   } catch {
     // 已退出
   }
 }
 
 /**
- * 终止 holder（unshare 包装进程）必须用 SIGKILL：util-linux 的 unshare 在 fork 前
+ * 请求 holder 自行退出：关闭我们持有的 stdin 写端，holder 读到 EOF 即退出（见
+ * holder.ts），内核随之清理整个 pid namespace，unshare 包装进程 waitpid 后自行退出，
+ * slirp4netns 经 exit-fd HUP 退出。这条通道绑定的是 fd 而不是 pid，不存在「检查时
+ * 还活着、发信号时 pid 已被复用」的窗口——常规停栈走这里，不发任何信号。
+ */
+function requestHolderShutdown(holder: ChildProcess): void {
+  holder.stdin?.destroy();
+}
+
+/**
+ * 兜底强杀 holder（unshare 包装进程）。只在 fd 通道超时（holder 卡死）时使用：Node 的
+ * kill 最终按 pid 调 kill(2)，仍有极小但非零的复用窗口，见 killChild 的说明。
+ *
+ * 必须用 SIGKILL：util-linux 的 unshare 在 fork 前
  * `sigprocmask(SIG_BLOCK, {SIGINT, SIGTERM})`，且只在子进程里恢复掩码——父进程永久
  * 阻塞这两个信号，发给它的 SIGTERM 只会 pending 永不投递（实测 3s 后仍存活）。
  * SIGKILL 不可阻塞，unshare 立即退出；其子进程（pid ns 的 init）经 --kill-child 的
  * PDEATHSIG 收到 SIGTERM，走优雅退出并触发内核清理整个 pid ns。
  */
-function killHolder(pid: number | undefined): void {
-  killProcess(pid, "SIGKILL");
-}
-
-/** 轮询等待进程退出（进程消失即返回）。 */
-async function waitForExit(pid: number): Promise<void> {
-  const timeoutMs = 2000;
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
-    try {
-      process.kill(pid, 0);
-    } catch {
-      return;
-    }
-    await new Promise((resolve) => setTimeout(resolve, 50));
-  }
+function killHolder(holder: ChildProcess): boolean {
+  return killChild(holder, "SIGKILL");
 }
 
 /** 读取 holder 的直接子进程 pid（pid ns 的 init）：PDEATHSIG 未生效时的 SIGKILL 兜底用。 */
@@ -201,25 +203,37 @@ function forwardOutput(
   });
 }
 
+/** 停栈结果：网络栈在命令运行期间自行终止时，调用方据此拿到落盘的诊断日志。 */
+export interface NetworkStackStopResult {
+  /** holder 在本次停栈之前已自行退出（没有收到本次停止信号）。 */
+  readonly exitedEarly: boolean;
+  /** 运行期异常退出时落盘的诊断日志路径。 */
+  readonly logPath?: string;
+}
+
 export interface NetworkStack {
-  stop(): Promise<void>;
+  /** 停止网络栈；幂等，重复调用返回同一结果。 */
+  stop(): Promise<NetworkStackStopResult>;
   /** holder pid：可 `nsenter -U -n --preserve-credentials -t <pid>` 手动进入该 netns 排查。 */
   readonly holderPid: number;
 }
 
 interface NetworkStackState {
-  holderPid: number;
-  slirpPid: number;
+  /** unshare 包装进程句柄：发信号必须经句柄，pid 退出后可能被内核复用。 */
+  holder: ChildProcess;
+  /** slirp4netns 句柄（宿主 netns，exit-fd 绑定 holder 生命周期）。 */
+  slirp: ChildProcess;
   /** 过滤进程的工作目录：GC 兜底路径也要把它删掉。 */
   mihomoHome: string;
 }
 
-/** 兜底：调用方忘记 stop() 时，对象被 GC 回收后 kill 残留进程并清掉工作目录。 */
+/** 兜底：调用方忘记 stop() 时，对象被 GC 回收后让残留进程自行退出并清掉工作目录。 */
 const stackFinalizer = new FinalizationRegistry<NetworkStackState>((state) => {
-  // holder 退出触发内核清理 pid ns 内全部进程；
-  // slirp4netns 在宿主侧持有 tap fd，单独终止
-  killHolder(state.holderPid);
-  killProcess(state.slirpPid);
+  // 只走 fd 通道：关闭 holder 的 stdin 写端让它自己退出（内核随之清理 pid ns），
+  // slirp4netns 由 exit-fd HUP 退出。GC 回调不能 await，更不能按 pid 发信号——对象被
+  // 回收时这些 pid 可能早已被内核复用给无关进程。holder 卡死时这条兜底清理不掉，
+  // 留给宿主退出或人工处理，这是刻意的取舍。
+  requestHolderShutdown(state.holder);
   // FinalizationRegistry 回调不能 await：尽力而为，删不掉就留下（宿主崩溃时同样如此）
   // eslint-disable-next-line unicorn/no-useless-undefined
   void rm(state.mihomoHome, { recursive: true, force: true }).catch(() => undefined);
@@ -353,44 +367,87 @@ export async function startNetworkStack(options: NetworkStackOptions): Promise<N
       mihomoReady.catch(() => undefined);
     });
 
-    const state: NetworkStackState = { holderPid, slirpPid: slirp.pid, mihomoHome };
+    const state: NetworkStackState = { holder, slirp, mihomoHome };
+    const finalizerToken: object = {};
+    let stopResult: NetworkStackStopResult | undefined;
     const stack: NetworkStack = {
       stop: async () => {
-        const children = await readChildPids(state.holderPid);
-        // slirp4netns 持有 tap fd（pin 住 netns），必须随 holder 一起显式终止；
-        // 先杀它再杀 holder，避免 stop() 与 exit-fd HUP 的收尾时序竞争
-        killProcess(state.slirpPid);
-        // SIGKILL holder → init 经 PDEATHSIG 收到 SIGTERM，优雅停 mihomo 后退出，
-        // 内核清理 pid ns 内全部进程，ns 引用随之归零（毫秒级，见 killHolder）
-        killHolder(state.holderPid);
-        await waitForExit(state.holderPid);
-        await waitForExit(state.slirpPid);
-        // 兜底：init 未在超时内退出 → SIGKILL init → 内核清 pid ns
-        for (const pid of children) {
-          killProcess(pid, "SIGKILL");
+        if (stopResult !== undefined) {
+          return stopResult;
+        }
+        // 兜底只服务「调用方忘记停栈」：正常路径在这里注销，不再触发第二条终止路径
+        stackFinalizer.unregister(finalizerToken);
+        // holder 已自行退出（过滤进程崩溃、unshare 被外在因素终止）：这次不是我们停的
+        const exitedEarly = childHasExited(state.holder);
+        // 常规停栈走 fd 通道：关掉 holder 的 stdin 写端，它读到 EOF 自己退出 → 内核清理
+        // pid ns → unshare waitpid 后退出 → slirp4netns 经 exit-fd HUP 退出。全程不按
+        // pid 发信号，因此没有「检查时还活着、发信号时已被复用」的窗口。
+        requestHolderShutdown(state.holder);
+        const holderExited = await waitForChildExit(state.holder, STOP_WAIT_TIMEOUT_MS);
+        const slirpExited = await waitForChildExit(state.slirp, STOP_WAIT_TIMEOUT_MS);
+        // 兜底：fd 通道超时（holder 卡死，EOF 未被 event loop 处理）才强杀。这是唯一
+        // 仍按 pid 发信号的路径（Node 的 kill 最终落到 kill(2)），窗口极小但非零
+        if (!holderExited) {
+          killHolder(state.holder);
+          const killed = await waitForChildExit(state.holder, STOP_WAIT_TIMEOUT_MS);
+          if (!killed) {
+            // holder 仍存活 → 它的 pid ns init 必然仍属本网络栈，pid 兜底才安全
+            for (const pid of await readChildPids(holderPid)) {
+              killInitProcess(pid);
+            }
+          }
+        }
+        if (!slirpExited) {
+          killChild(state.slirp);
+          await waitForChildExit(state.slirp, STOP_WAIT_TIMEOUT_MS);
         }
         // 工作目录只服务本次实例（mihomo 的 cache.db 等运行时缓存），随停栈删除；
         // best-effort：删除失败不外抛，避免掩盖命令结果
         // eslint-disable-next-line unicorn/no-useless-undefined
         await rm(state.mihomoHome, { recursive: true, force: true }).catch(() => undefined);
+        // 运行期异常退出：缓冲里的 holder/slirp 输出是唯一的死因材料，落盘并把
+        // 路径交给调用方；成功路径不落盘
+        const logPath = exitedEarly
+          ? await writeFailureLog(
+              new Error(
+                `Network stack exited during command execution (holder exit code ${String(state.holder.exitCode)}${state.holder.signalCode === null ? "" : `, signal ${state.holder.signalCode}`})`,
+              ),
+              [holderLog.join(""), slirpLog.join("")],
+            )
+          : undefined;
+        stopResult = { exitedEarly, ...(logPath !== undefined && { logPath }) };
+        return stopResult;
       },
       holderPid,
     };
-    stackFinalizer.register(stack, state);
+    stackFinalizer.register(stack, state, finalizerToken);
     return stack;
   } catch (error) {
     // 失败清理：SIGKILL holder（unshare）→ init 经 PDEATHSIG 收到 SIGTERM 后退出，
     // 内核清理 pid ns 内全部进程；slirp4netns 在宿主侧，需单独终止
     //（exit-fd 写端也会随 holder 死亡关闭，这里主动杀只是不等到 HUP 轮询）
-    if (slirp?.pid) {
-      killProcess(slirp.pid);
+    // 启动失败清理同样优先走 fd 通道：关 holder 的 stdin 让它自己退出，slirp4netns
+    // 随之经 exit-fd HUP 退出；只有超时（卡死）才强杀
+    if (holder !== undefined) {
+      requestHolderShutdown(holder);
+    }
+    if (slirp !== undefined) {
+      const slirpExited = await waitForChildExit(slirp, STOP_WAIT_TIMEOUT_MS);
+      if (!slirpExited) {
+        killChild(slirp);
+      }
     }
-    if (holder?.pid) {
-      const children = await readChildPids(holder.pid);
-      killHolder(holder.pid);
-      await waitForExit(holder.pid);
-      for (const pid of children) {
-        killProcess(pid, "SIGKILL");
+    if (holder !== undefined && !childHasExited(holder)) {
+      const holderExited = await waitForChildExit(holder, STOP_WAIT_TIMEOUT_MS);
+      if (!holderExited) {
+        killHolder(holder);
+        const killed = await waitForChildExit(holder, STOP_WAIT_TIMEOUT_MS);
+        if (!killed && holder.pid !== undefined) {
+          // holder 仍存活 → 这些 pid 必然仍属本网络栈
+          for (const pid of await readChildPids(holder.pid)) {
+            killInitProcess(pid);
+          }
+        }
       }
     }
     // 这里刻意不删 mihomoHome：启动失败时它属于现场材料，与下面落盘的诊断日志

package/src/bwrap/runtime.ts

@@ -389,6 +389,18 @@ export function sandboxHintBlock(hint: string | undefined): { type: "text"; text
   return hint === undefined ? [] : [{ type: "text", text: hint }];
 }
 
+/** 网络栈在命令运行期间异常退出时，把落盘的诊断日志路径附进沙箱状态提示。 */
+function withNetworkStackLog(
+  hint: string | undefined,
+  logPath: string | undefined,
+): string | undefined {
+  if (logPath === undefined) {
+    return hint;
+  }
+  const line = `The sandbox network stack exited during the command; diagnostics: ${logPath}`;
+  return hint === undefined ? line : `${hint}\n${line}`;
+}
+
 /**
  * 项目配置文件形状非法时的错误：消息带文件路径与字段位置，cause 保留校验错误
  * （Value.Check 只回答是否合法，详情用同一 schema 解析一次取到）。
@@ -618,7 +630,7 @@ export class BwrapRuntime {
     );
 
     try {
-      const { exitCode } = await runInSandbox(runtime, {
+      const { exitCode, networkStackLog } = await runInSandbox(runtime, {
         workspace,
         commandCwd: execCwd,
         command: request.command,
@@ -633,7 +645,7 @@ export class BwrapRuntime {
       const partial = await this.finalizeOutput(output);
       return {
         exitCode,
-        sandboxHint,
+        sandboxHint: withNetworkStackLog(sandboxHint, networkStackLog),
         ...(sandboxReminder && { sandboxReminder }),
         output: partial.output,
         ...(partial.fullOutputPath && { fullOutputPath: partial.fullOutputPath }),

package/src/bwrap/sandbox.ts

@@ -28,7 +28,7 @@ import {
   type ResolvedBwrap,
 } from "./core.js";
 import { buildBwrapInvocation, createBwrapBashOperations, invocationArgv } from "./exec.js";
-import type { NetworkStack } from "./network-stack.js";
+import type { NetworkStack, NetworkStackStopResult } from "./network-stack.js";
 
 export interface SandboxConfigInput {
   /** 沙箱工作区：默认配置文件的查找目录，也是 writablePaths 中 "." 的解析基准。 */
@@ -65,6 +65,8 @@ export interface SandboxRunOptions {
 export interface SandboxRunResult {
   /** 命令退出码；被信号杀死时为 null。 */
   exitCode: number | null;
+  /** 命令运行期间网络栈异常退出时落盘的诊断日志路径（正常停栈没有这个字段）。 */
+  networkStackLog?: string;
 }
 
 /** 把 "."/"~" 形式的路径收敛成绝对路径，使执行策略自成一体、可断言。 */
@@ -117,6 +119,8 @@ export async function runInSandbox(
   const local = options.unsandboxed === true || !resolved.bwrapEnabled;
   // 每次执行现建现停网络栈（起栈 ~40ms、停栈 ~100ms），作用域结束即停栈：allowlist 变更即时生效
   const stack = local ? undefined : await createNetworkStack(resolved, options.log);
+  let result: SandboxRunResult | undefined;
+  let failure: unknown;
   try {
     if (stack) {
       options.onNetworkStack?.(stack);
@@ -129,14 +133,38 @@ export async function runInSandbox(
       signal: options.signal,
       timeout: options.timeout,
     });
-    return { exitCode };
-  } finally {
-    try {
-      await stack?.stop();
-    } catch {
-      // best-effort：停栈失败（进程已退出/目录删除失败）不掩盖命令结果
+    result = { exitCode };
+  } catch (error) {
+    failure = error;
+  }
+  // 停栈放在命令结束之后、结果返回之前：网络栈若在命令运行期间异常退出，停栈返回的
+  // 日志路径要能附到失败信息上（成功路径不打扰用户，也不改变命令结果）
+  let stopResult: NetworkStackStopResult | undefined;
+  try {
+    stopResult = await stack?.stop();
+  } catch {
+    // best-effort：停栈失败（进程已退出/目录删除失败）不掩盖命令结果
+  }
+  if (failure !== undefined) {
+    if (!(failure instanceof Error)) {
+      // 非 Error 抛出（字符串 / 对象）：保留字符串内容，其余不渲染成 [object Object]
+      throw new Error(
+        typeof failure === "string" ? failure : "Sandbox command failed (non-error value thrown)",
+      );
     }
+    if (stopResult?.exitedEarly === true) {
+      const detail =
+        stopResult.logPath === undefined
+          ? "(network stack exited during the command; diagnostics could not be written)"
+          : `(network stack diagnostics: ${stopResult.logPath})`;
+      failure.message = `${failure.message}\n${detail}`;
+    }
+    throw failure;
   }
+  return {
+    ...(result ?? { exitCode: null }),
+    ...(stopResult?.logPath !== undefined && { networkStackLog: stopResult.logPath }),
+  };
 }
 
 /** 一步式入口：按配置加载策略并在对应沙箱里执行命令（CLI 与集成测试用）。 */

package/src/lib/proc.ts

@@ -1,3 +1,43 @@
+import type { ChildProcess } from "node:child_process";
+import { once } from "node:events";
+
+/** 子进程是否已结束（正常退出或被信号杀死）。 */
+export function childHasExited(child: ChildProcess): boolean {
+  return child.exitCode !== null || child.signalCode !== null;
+}
+
+/**
+ * 向自己 spawn 的子进程强杀。已结束（Node 已回收）的子进程不会再收到信号。
+ *
+ * 注意这不是「保证不会误杀」的手段：子进程可能在我们检查之后、发信号之前退出，
+ * 而 Node 最终仍按 pid 调 kill(2)（libuv 的 uv_process_kill），此时该 pid 可能已被
+ * 内核复用给无关进程。只应作为「进程卡死」时的最后手段，常规终止请走不依赖 pid 的
+ * 通道（例如关闭子进程持有的管道写端让它自行退出）。
+ */
+export function killChild(child: ChildProcess, signal: NodeJS.Signals = "SIGTERM"): boolean {
+  if (childHasExited(child)) {
+    return false;
+  }
+  return child.kill(signal);
+}
+
+/** 等待子进程结束，返回是否在超时内结束；已结束的立即返回 true。 */
+export async function waitForChildExit(child: ChildProcess, timeoutMs: number): Promise<boolean> {
+  if (childHasExited(child)) {
+    return true;
+  }
+  // AbortSignal.timeout 的定时器不保持事件循环活跃，子进程先退出时它自行失效
+  const timeout = AbortSignal.timeout(timeoutMs);
+  const timedOut = new Promise<false>((resolve) => {
+    timeout.addEventListener("abort", () => resolve(false), { once: true });
+  });
+  // spawn 失败（error 事件）也算「已经结束」，避免把失败挂成未处理的 rejection
+  const exited = once(child, "exit")
+    .then(() => true)
+    .catch(() => true);
+  return Promise.race([exited, timedOut]);
+}
+
 /**
  * 按行消费输出流：data 事件按 buffer 边界切分，行可能跨多个 chunk，
  * 这里拼接缓冲后按 \n 逐行回调（回调不含换行符）。