@trim21/personal-pi-extensions 0.1.613 → 0.1.619

package/package.json

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

package/src/bwrap/README.md

@@ -6,7 +6,7 @@
 
 ## 进程模型
 
-`network: limited` 模式下，一个沙箱 session 的常驻进程树（宿主侧视角，共 4 个）：
+`network: limited` 模式下，每条命令的网络栈进程树（宿主侧视角，共 4 个）：
 
 ```
 pi 进程（network-stack.ts）
@@ -21,7 +21,7 @@ pi 进程（network-stack.ts）
      必须在宿主 netns 启动（原因见「设计约束」）；持 exit-fd 读端 + tapfd。
 ```
 
-每条命令的短命子树（命令结束即退，与常驻栈无关）：
+每条命令的短命子树（命令结束即退）：
 
 ```
 nsenter -U -n --preserve-credentials -t <①的pid> \
@@ -29,7 +29,8 @@ nsenter -U -n --preserve-credentials -t <①的pid> \
 ```
 
 nsenter 进入 holder 的 userns/netns，bwrap 在里面再嵌套创建自己的 user/pid
-ns 跑命令。一个 session 内 N 条命令复用同一套常驻栈。
+ns 跑命令。网络栈是每条命令现建现停（起栈 ~40ms、停栈 ~100ms），不跨命令复用：
+allowlist 变更因此即时生效，代价是每条命令重新启动一次 mihomo。
 
 ## 网络路径
 
@@ -54,14 +55,16 @@ exit-fd（socketpair）是 slirp4netns 与 holder 之间唯一的生命周期绑
 访问器（`stdio[3].fd` 恒为 undefined），只能经 `_handle.fd` 取原始 fd 再
 dup 给 slirp4netns，且仅在子进程存活期间有效。
 
-| 触发              | 清理链路                                                                                              |
-| ----------------- | ----------------------------------------------------------------------------------------------------- |
-| 正常 `stop()`     | SIGTERM ④（先杀，它 pin 着 netns）→ SIGTERM ① → `--kill-child` 转发给 ② → ② 杀 ③ 退出 → 内核清 pid ns |
-| pi 进程被 SIGKILL | stdin 写端关闭 → ② EOF 自杀 → pid ns 清理 → exit-fd 写端关闭 → ④ HUP 自杀 → tapfd 释放 → netns 销毁   |
-| 单独 kill ①       | PDEATHSIG → ② SIGTERM → 同上；① wait 结束退出 → 写端全关 → ④ 退                                       |
-| 单独 kill ②       | pid-ns init 死 → 内核清 ③；① 退出 → 写端全关 → ④ 退                                                   |
+| 触发                   | 清理链路                                                                                             |
+| ---------------------- | ---------------------------------------------------------------------------------------------------- |
+| 正常 `stop()`          | SIGTERM ④（先杀，它 pin 着 netns）→ SIGKILL ① → PDEATHSIG 给 ② SIGTERM → ② 杀 ③ 退出 → 内核清 pid ns |
+| pi 进程被 SIGKILL      | stdin 写端关闭 → ② EOF 自杀 → pid ns 清理 → exit-fd 写端关闭 → ④ HUP 自杀 → tapfd 释放 → netns 销毁  |
+| 单独 kill ①（SIGKILL） | PDEATHSIG → ② SIGTERM → 同上；① wait 结束退出 → 写端全关 → ④ 退                                      |
+| 单独 kill ②            | pid-ns init 死 → 内核清 ③；① 退出 → 写端全关 → ④ 退                                                  |
 
-四条路径下常驻进程全部收敛、netns 引用归零。
+四条路径下网络栈全部进程收敛、netns 引用归零。注意 `--kill-child` 不是信号转发：
+它的实现是 unshare fork 出的子进程给自己设 PDEATHSIG（unshare 死亡时收到 SIGTERM），
+所以终止 ① 只能靠 SIGKILL（见「设计约束」第 5 条）。
 
 ## 设计约束与教训
 
@@ -81,6 +84,12 @@ dup 给 slirp4netns，且仅在子进程存活期间有效。
    日志；`nsenter -U -n --preserve-credentials -t <holderPid>` 可手动进入
    netns 用 AF_PACKET 抓 tap0 / 检查 `ip rule`（注意：沙盒里看不到宿主机
    进程，宿主机诊断必须在沙盒外做）。
+5. **终止 unshare 只能用 SIGKILL**。util-linux 的 unshare 在 fork 前
+   `sigprocmask(SIG_BLOCK, {SIGINT, SIGTERM})`，且只在子进程里恢复掩码：
+   父进程永久阻塞这两个信号且不装 handler，发给它的 SIGTERM 只会 pending
+   永不投递（实测 3s 后仍存活）。曾因此在 `stop()` 里白等 `waitForExit`
+   的 2000ms 默认超时，把每条命令的沙箱开销从 ~180ms 抬到 ~2.09s。SIGKILL
+   立即生效，PDEATHSIG 再把 SIGTERM 交给 ② 走优雅退出。
 
 ## 调试入口
 

package/src/bwrap/network-stack.ts

@@ -1,6 +1,6 @@
 import { type ChildProcess, spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { mkdir, readFile, readlink, writeFile } from "node:fs/promises";
+import { mkdir, readFile, readlink, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -94,6 +94,17 @@ function killProcess(pid: number | undefined, signal: NodeJS.Signals = "SIGTERM"
   }
 }
 
+/**
+ * 终止 holder（unshare 包装进程）必须用 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, timeoutMs = 2000): Promise<void> {
   const deadline = Date.now() + timeoutMs;
@@ -107,7 +118,7 @@ async function waitForExit(pid: number, timeoutMs = 2000): Promise<void> {
   }
 }
 
-/** 读取进程的直接子进程 pid：--kill-child 只转发信号给 fork 的子进程，兜底直接 SIGKILL 用。 */
+/** 读取 holder 的直接子进程 pid（pid ns 的 init）：PDEATHSIG 未生效时的 SIGKILL 兜底用。 */
 async function readChildPids(pid: number): Promise<number[]> {
   try {
     const content = await readFile(`/proc/${pid}/task/${pid}/children`, "utf8");
@@ -235,14 +246,19 @@ export interface NetworkStack {
 interface NetworkStackState {
   holderPid: number;
   slirpPid: number;
+  /** 过滤进程的工作目录：GC 兜底路径也要把它删掉。 */
+  mihomoHome: string;
 }
 
-/** 兜底：调用方忘记 stop() 时，对象被 GC 回收后 kill 残留进程。 */
+/** 兜底：调用方忘记 stop() 时，对象被 GC 回收后 kill 残留进程并清掉工作目录。 */
 const stackFinalizer = new FinalizationRegistry<NetworkStackState>((state) => {
-  // SIGTERM 经 unshare --kill-child 转发给 init，内核清理 pid ns 内全部进程；
+  // holder 退出触发内核清理 pid ns 内全部进程；
   // slirp4netns 在宿主侧持有 tap fd，单独终止
-  killProcess(state.holderPid);
+  killHolder(state.holderPid);
   killProcess(state.slirpPid);
+  // FinalizationRegistry 回调不能 await：尽力而为，删不掉就留下（宿主崩溃时同样如此）
+  // eslint-disable-next-line unicorn/no-useless-undefined
+  void rm(state.mihomoHome, { recursive: true, force: true }).catch(() => undefined);
 });
 
 /**
@@ -264,7 +280,8 @@ export async function startNetworkStack(options: NetworkStackOptions): Promise<N
 
   // mihomo 工作目录（-d）：cache.db 等落在这里，而不是它默认的 ~/.config/mihomo/
   //（后者不存在时 mihomo 每次启动都告警且 fakeip 映射无持久化）。每次启动用独立
-  // uuid 目录，避免并发的多个 holder 争抢 bbolt 文件锁。
+  // uuid 目录，避免并发的多个 holder 争抢 bbolt 文件锁；正常停栈与 GC 兜底删除该
+  // 目录（见 stop / stackFinalizer），启动失败时保留作诊断材料（见 catch）。
   const mihomoHome = join(getAgentDir(), "tmp", `mihomo-${randomUUID()}`);
   await mkdir(mihomoHome, { recursive: true });
 
@@ -275,7 +292,8 @@ export async function startNetworkStack(options: NetworkStackOptions): Promise<N
   try {
     // unshare -p --fork：node 成为 pid namespace 的 init，任何方式退出（含 SIGKILL）
     // 内核都会清理 pid ns 内全部进程（mihomo），ns 引用随之归零；
-    // --kill-child=SIGTERM：宿主侧 SIGTERM unshare 时转发给 init 走优雅退出
+    // --kill-child=SIGTERM：init 拿到 PR_SET_PDEATHSIG，unshare 死亡时收到 SIGTERM
+    // 走优雅退出（注意 unshare 自身阻塞 SIGINT/SIGTERM，终止它只能靠 SIGKILL，见 killHolder）
     holder = spawn(
       "unshare",
       [
@@ -371,7 +389,7 @@ export async function startNetworkStack(options: NetworkStackOptions): Promise<N
       mihomoReady.catch(() => undefined);
     });
 
-    const state: NetworkStackState = { holderPid, slirpPid: slirp.pid };
+    const state: NetworkStackState = { holderPid, slirpPid: slirp.pid, mihomoHome };
     const stack: NetworkStack = {
       exec: async (execOptions: NetworkStackExecOptions) => {
         const child = spawn(
@@ -452,35 +470,42 @@ export async function startNetworkStack(options: NetworkStackOptions): Promise<N
         // slirp4netns 持有 tap fd（pin 住 netns），必须随 holder 一起显式终止；
         // 先杀它再杀 holder，避免 stop() 与 exit-fd HUP 的收尾时序竞争
         killProcess(state.slirpPid);
-        // SIGTERM unshare → --kill-child 转发 SIGTERM 给 init（pid ns 的 pid 1），
-        // init 优雅停 mihomo 后退出，内核清理 pid ns 内全部进程，ns 引用随之归零
-        killProcess(state.holderPid);
+        // 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");
         }
+        // 工作目录只服务本次实例（mihomo 的 cache.db 等运行时缓存），随停栈删除；
+        // best-effort：删除失败不外抛，避免掩盖命令结果
+        // eslint-disable-next-line unicorn/no-useless-undefined
+        await rm(state.mihomoHome, { recursive: true, force: true }).catch(() => undefined);
       },
       holderPid,
     };
     stackFinalizer.register(stack, state);
     return stack;
   } catch (error) {
-    // 失败清理：holder（unshare）的 SIGTERM 经 --kill-child 转发给 init，
-    // init 退出时内核清理 pid ns 内全部进程；slirp4netns 在宿主侧，需单独终止
+    // 失败清理：SIGKILL holder（unshare）→ init 经 PDEATHSIG 收到 SIGTERM 后退出，
+    // 内核清理 pid ns 内全部进程；slirp4netns 在宿主侧，需单独终止
     //（exit-fd 写端也会随 holder 死亡关闭，这里主动杀只是不等到 HUP 轮询）
     if (slirp?.pid) {
       killProcess(slirp.pid);
     }
     if (holder?.pid) {
       const children = await readChildPids(holder.pid);
-      killProcess(holder.pid);
+      killHolder(holder.pid);
       await waitForExit(holder.pid);
       for (const pid of children) {
         killProcess(pid, "SIGKILL");
       }
     }
+    // 这里刻意不删 mihomoHome：启动失败时它属于现场材料，与下面落盘的诊断日志
+    //（holder / slirp 输出 + 错误本身）配套保留，便于事后排查；失败路径罕见，
+    // 留一个目录不构成泄漏
     const logPath = await writeFailureLog(error, [holderLog.join(""), slirpLog.join("")]);
     if (logPath !== undefined && error instanceof Error) {
       throw new Error(`${error.message}\n(sandbox startup diagnostics: ${logPath})`, {

package/src/bwrap/sandbox.ts

@@ -117,7 +117,7 @@ export async function runInSandbox(
   const workspace = expandHome(options.workspace);
   const commandCwd = expandHome(options.commandCwd ?? workspace);
   const local = options.unsandboxed === true || !resolved.bwrapEnabled;
-  // 每次执行现建网络栈（启动约 140ms），作用域结束即停栈：allowlist 变更即时生效
+  // 每次执行现建现停网络栈（起栈 ~40ms、停栈 ~100ms），作用域结束即停栈：allowlist 变更即时生效
   const stack = local ? undefined : await createNetworkStack(resolved, options.log);
   try {
     if (stack) {