@trim21/personal-pi-extensions 0.1.613 → 0.1.621

package/README.md

@@ -52,7 +52,7 @@ fs（文件系统）与 network（网络）各自独立取值，可任意组合
 | `network` | `limited`         | 仅白名单可达：deny-by-default 过滤，`network.allowlist` 之外全部拒绝    |
 | `network` | `allow-all`       | 网络不受限                                                              |
 
-默认 `fs: workspace-write` + `network: block`。两者都 `allow-all` 时完全不经 bwrap、直接执行；其余组合都在 bwrap 里执行：`block` 用 `--unshare-net` 断网，`limited` 叠一层 mihomo TUN（fakeip DNS）+ slirp4netns egress NAT，只有 allowlist 里的域名 / IP / CIDR 可达，未命中流量在连接层被拒（allowlist 为空 = 全部拒绝）。进程模型、生命周期与设计约束见 `src/bwrap/README.md`。
+默认 `fs: workspace-write` + `network: block`。两者都 `allow-all` 时完全不经 bwrap、直接执行；其余组合都在 bwrap 里执行：`block` 用 `--unshare-net` 断网，`limited` 叠一层 mihomo TUN（白名单 fakeip DNS）+ slirp4netns egress NAT，只有 allowlist 里的域名 / IP / CIDR 可达：未允许域名在 DNS 层即解析失败，裸 IP 连接在连接层被拒（allowlist 为空 = 全部拒绝）。条目匹配语义（精确 / `*.` 子域名）见 `src/bwrap/README.md`，进程模型与设计约束见同一文档。
 
 ### 提权机制
 
@@ -104,7 +104,8 @@ bash 工具（opencode 风格 `bash`、Claude Code 风格 `Bash`）注册了 `da
   "network": {
     "mode": "block",
     // limited 模式允许直连的域名 / IP / CIDR，可带 :port；空 = 全部拒绝
-    "allowlist": ["github.com", "*.githubassets.com"],
+    // 域名精确匹配，需要子域名时加 "*." 前缀（"*.github.com" 不含 github.com 本身）
+    "allowlist": ["github.com", "*.github.com", "*.githubassets.com"],
     // mihomo / slirp4netns 可执行文件路径（可选，缺省走 PATH）
     "mihomoPath": "/usr/local/bin/mihomo",
     "slirp4netnsPath": "/usr/bin/slirp4netns",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.613",
+  "version": "0.1.621",
   "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,22 +29,48 @@ nsenter -U -n --preserve-credentials -t <①的pid> \
 ```
 
 nsenter 进入 holder 的 userns/netns，bwrap 在里面再嵌套创建自己的 user/pid
-ns 跑命令。一个 session 内 N 条命令复用同一套常驻栈。
+ns 跑命令。网络栈是每条命令现建现停（起栈 ~40ms、停栈 ~100ms），不跨命令复用：
+allowlist 变更因此即时生效，代价是每条命令重新启动一次 mihomo。
 
 ## 网络路径
 
-- **mihomo（③）**：TUN（`auto-route` + `strict-route`）+ fakeip +
-  deny-by-default。`network.allowlist` 域名进 `fake-ip-filter`（真实解析），DNS 层
-  `DOMAIN-SUFFIX,…,DIRECT`；连接层未命中 allowlist 的流量 `MATCH,REJECT`。
-  注意：fakeip 对不在 filter 里的域名**直接本地应答**，不会走到
-  `dns.rules` 的 REJECT——未允许域名是先拿 fakeip、连接层再被拒。
+- **mihomo（③）**：TUN（`auto-route` + `strict-route`）+ **白名单 fakeip** +
+  deny-by-default。`network.allowlist` 的域名进 `fake-ip-filter`，配合
+  `fake-ip-filter-mode: whitelist` 即「只有这些域名拿 fake IP」；`dns.nameserver`
+  是 `rcode://name_error` 伪服务器，未命中白名单的域名（即未允许域名）落到它上面
+  即时拿到 NXDOMAIN（客户端报 `Could not resolve host`）；连接层再用 `MATCH,REJECT`
+  兜底裸 IP 连接。`dns.direct-nameserver` 必须指向真实 DNS：连接由 fake IP 还原成
+  域名后，DIRECT 出站要按域名重新解析，否则会解析回 fake-ip 再进 TUN 成环。
+  这样两边都成立：未允许域名在 DNS 层就被拒，allowlist 域名的归属又由 fake IP
+  精确给出（不依赖嗅探、不受 DNS TTL 影响）。
 - **slirp4netns（④）**：egress NAT。它 fork helper 进 netns 创建 tap0 并把
   tapfd 传回主进程，真正的出站 socket 在宿主 netns。
 - **interface-name: tap0**：mihomo 出站静态绑定 slirp 接口。不能用
   `auto-detect-interface` 顶替——启动瞬间 tap0 可能尚未就绪，monitor 事后
   纠正但 DNS 拨号已走错接口，上游查询进自己的 TUN 被 `dns-hijack` 自劫持。
 - **mihomo `-d <uuid 目录>`**：cache.db 等落盘位置，放
-  `<agentDir>/tmp/mihomo-<uuid>/`，每次启动独立目录避免并发争抢 bbolt 锁。
+  `<agentDir>/tmp/mihomo-<uuid>/`，每次启动独立目录避免并发争抢 bbolt 锁；
+  停栈时删除，启动失败时保留作诊断材料。
+
+## allowlist 条目
+
+条目形式为「域名 / IPv4 / CIDR（可带 `:port`）」，域名有两档匹配精度——两层
+（DNS 白名单与连接层规则）语义严格一致：
+
+| 条目                    | 匹配                                             | 不匹配                               |
+| ----------------------- | ------------------------------------------------ | ------------------------------------ |
+| `example.com`           | `example.com`                                    | `www.example.com`、`a.b.example.com` |
+| `*.example.com`         | `www.example.com`、`a.b.example.com`（任意深度） | `example.com`、`notexample.com`      |
+| `example.com:443`       | 精确域名 + 仅 443                                | 其它端口                             |
+| `*.example.com:443`     | 子域名 + 仅 443                                  | `example.com`、其它端口              |
+| `1.2.3.4`、`10.0.0.0/8` | 对应 IP / 网段                                   | —                                    |
+
+- 裸域名是**精确匹配**（不是子树），需要「域名本身 + 子域名」同时放行时写两条。
+- `*.` 必须占据完整的最左标签：`*`、`*example.com`、`a.*.example.com` 都是配置错误；
+  通配只对域名有效，IP 范围用 CIDR 表达。
+- 端口只约束连接层（DNS 无端口语义）：`example.com:443` 能解析，但只有 443 能连。
+- 映射到 mihomo：精确条目在 DNS 侧是裸域名、连接层是 `DOMAIN`；通配条目在 DNS 侧
+  是 `.example.com`（dot-wildcard）、连接层是 `DOMAIN-WILDCARD,*.example.com`。
 
 ## 生命周期与清理
 
@@ -54,14 +80,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 条）。
 
 ## 设计约束与教训
 
@@ -74,13 +102,23 @@ dup 给 slirp4netns，且仅在子进程存活期间有效。
    持 tapfd 泄漏 netns。
 2. **tap fd pin 住 netns**：slirp4netns 持有 tapfd 期间 netns 不会销毁，
    所以任何架构下 slirp4netns 的终止都必须显式保证（stop() / exit-fd）。
-3. **fakeip 短路**：`dns.rules` 的 REJECT 拦不住 fakeip 应答，deny-by-default
-   实际由连接层 `MATCH,REJECT` 兜底。诊断时不要把"未允许域名能解析出
-   198.18.x.x"当成 DNS 层放行。
+3. **DNS 层拒绝要靠收窄 fakeip，不能靠 DNS 规则**：mihomo 没有 `dns.rules`
+   这个字段（`config.RawDNS` 里不存在，写进配置会被静默忽略），`fake-ip` 分支
+   也没有按域名拒绝的钩子——命中 fakeip 就直接回合成 IP。要让未允许域名在 DNS
+   层失败，只能把它们排除在 fakeip 白名单之外（`fake-ip-filter-mode: whitelist`），
+   让查询落到 `nameserver`，再由 `rcode://name_error` 即时回 NXDOMAIN。
+   诊断时注意两点：allowlist 域名解析出 `198.18.x.x` 是**正常现象**（fakeip 生效），
+   未允许域名则应当**解析失败**而不是解析出 fakeip。
 4. **诊断手段**：`pnpm sandbox --verbose` 透传 holder（mihomo/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/core.ts

@@ -58,7 +58,10 @@ const fsConfigProperties = {
 const networkConfigProperties = {
   mode: StringEnum(NETWORK_MODES),
   allowlist: Type.Array(
-    Type.String({ description: "limited 模式允许直连的域名 / IP / CIDR，可带 :port" }),
+    Type.String({
+      description:
+        'limited 模式允许直连的域名 / IP / CIDR，可带 :port；域名默认精确匹配，加 "*." 前缀表示其全部子域名（任意深度，不含该域名本身），如 "*.example.com"',
+    }),
   ),
   mihomoPath: Type.Optional(Type.String()),
   slirp4netnsPath: Type.Optional(Type.String()),

package/src/bwrap/mihomo-config.ts

@@ -1,4 +1,6 @@
 const FAKEIP_RANGE = "198.18.0.1/16";
+/** mihomo 的拒绝伪 DNS 服务器：即时返回 NXDOMAIN，不查上游、不等超时。 */
+const REJECT_NAMESERVER = "rcode://name_error";
 /** TUN 与 slirp4netns tap0 共用；不对齐时大包会在 slirp NAT 后 PMTU blackhole。 */
 export const TUN_MTU = 1500;
 
@@ -12,6 +14,8 @@ export interface MihomoConfigOptions {
 interface AllowlistEntry {
   readonly host: string;
   readonly port?: number;
+  /** `*.host` 条目：匹配 host 的全部子域名（任意深度），不含 host 本身。 */
+  readonly subdomains: boolean;
 }
 
 /** mihomo 配置以 JSON 序列化输出（JSON 是 YAML 子集，-f 加载无差别）。 */
@@ -27,11 +31,15 @@ export interface MihomoConfig {
     ipv6: false;
     "enhanced-mode": "fake-ip";
     "fake-ip-range": string;
+    /** whitelist：只有 fake-ip-filter 命中的域名才拿 fake IP，其余走 nameserver。 */
+    "fake-ip-filter-mode": "whitelist";
+    /** fake IP 白名单：allowlist 里的域名（带端口条目的域名也进）。 */
+    "fake-ip-filter"?: string[];
+    /** 默认解析服务器：拒绝伪服务器，未命中白名单的域名（即未允许域名）即时 NXDOMAIN。 */
     nameserver: string[];
     "default-nameserver": string[];
-    "fake-ip-filter"?: string[];
-    /** 域名级 DNS 规则（mihomo >= 1.18）：allowlist 域名 DIRECT，其余 REJECT。 */
-    rules: string[];
+    /** DIRECT 出站按域名解析用；不指定会解析回 fake-ip 再进 TUN 成环。 */
+    "direct-nameserver": string[];
   };
   tun: {
     enable: true;
@@ -46,6 +54,8 @@ export interface MihomoConfig {
 }
 
 const IPV4_PATTERN = /^\d{1,3}(?:\.\d{1,3}){3}(?:\/\d{1,2})?$/;
+/** 子域名条目前缀：`*.example.com` 表示 example.com 的全部子域名（不含它本身）。 */
+const WILDCARD_PREFIX = "*.";
 /** 合法 DNS 主机名（标签 1-63 字符，字母数字加连字符，不得以连字符开头/结尾）。 */
 const DOMAIN_PATTERN =
   /^(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)*[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$/;
@@ -73,14 +83,32 @@ function parsePort(value: string): number {
 }
 
 /**
- * 解析 allowlist 条目：域名 / IPv4 / CIDR，可带 :port；IPv6 必须用 [] 包裹
- * （如 `[::1]:80`），裸 IPv6 会报错提示补方括号。
+ * 解析 allowlist 条目：域名 / IPv4 / CIDR，可带 :port；域名可加 `*.` 前缀表示
+ * 「它的全部子域名（任意深度，不含它本身）」；IPv6 必须用 [] 包裹（如 `[::1]:80`），
+ * 裸 IPv6 会报错提示补方括号。
  */
 function parseAllowlistEntry(entry: string): AllowlistEntry {
+  if (entry === "*") {
+    throw new Error(
+      `Invalid allowlist entry "${entry}": "*" must be followed by a domain, e.g. "*.example.com"`,
+    );
+  }
+  if (entry.startsWith("*") && !entry.startsWith(WILDCARD_PREFIX)) {
+    throw new Error(
+      `Invalid allowlist entry "${entry}": "*" must occupy the whole leftmost label, e.g. "*.example.com"`,
+    );
+  }
+  const subdomains = entry.startsWith(WILDCARD_PREFIX);
+  const body = subdomains ? entry.slice(WILDCARD_PREFIX.length) : entry;
+  if (body.length === 0) {
+    throw new Error(
+      `Invalid allowlist entry "${entry}": "*" must be followed by a domain, e.g. "*.example.com"`,
+    );
+  }
   let host: string;
   let port: number | undefined;
-  if (entry.startsWith("[")) {
-    const match = /^\[(.+)\](?::(\d+))?$/.exec(entry);
+  if (body.startsWith("[")) {
+    const match = /^\[(.+)\](?::(\d+))?$/.exec(body);
     if (match?.[1] === undefined) {
       throw new Error(`Invalid allowlist entry "${entry}"`);
     }
@@ -89,18 +117,15 @@ function parseAllowlistEntry(entry: string): AllowlistEntry {
     const portPart = match.at(2);
     port = portPart === undefined ? undefined : parsePort(portPart);
   } else {
-    const colon = entry.lastIndexOf(":");
+    const colon = body.lastIndexOf(":");
     if (colon === -1) {
-      if (entry.length === 0) {
-        throw new Error(`Invalid allowlist entry ""`);
-      }
-      host = entry;
+      host = body;
     } else {
-      const portPart = entry.slice(colon + 1);
+      const portPart = body.slice(colon + 1);
       if (!/^\d+$/.test(portPart)) {
         throw new Error(`Invalid allowlist entry "${entry}"`);
       }
-      host = entry.slice(0, colon);
+      host = body.slice(0, colon);
       if (host.length === 0) {
         throw new Error(`Invalid allowlist entry "${entry}"`);
       }
@@ -110,14 +135,24 @@ function parseAllowlistEntry(entry: string): AllowlistEntry {
       port = parsePort(portPart);
     }
   }
+  if (host.includes("*")) {
+    throw new Error(
+      `Invalid allowlist entry "${entry}": "*" is only allowed as the leftmost label, e.g. "*.example.com"`,
+    );
+  }
   if (isIp(host)) {
+    if (subdomains) {
+      throw new Error(
+        `Invalid allowlist entry "${entry}": "*" applies to domains only, use a CIDR entry for IP ranges`,
+      );
+    }
     if (!IP_CHARS_PATTERN.test(host)) {
       throw new Error(`Invalid allowlist entry "${entry}"`);
     }
   } else if (!DOMAIN_PATTERN.test(host)) {
     throw new Error(`Invalid allowlist entry "${entry}"`);
   }
-  return { host, port };
+  return { host, port, subdomains };
 }
 
 /** IP 条目的 mihomo 规则（IPv6 用 IP-CIDR6；no-resolve 跳过反向解析）。 */
@@ -129,35 +164,38 @@ function ipRule(host: string): string {
 
 interface BuiltRules {
   rules: string[];
-  fakeIpFilter: string[];
-  /** DNS 层规则：allowlist 域名正常解析，未允许域名直接拒绝（解析失败而非 fake-ip 后连接失败）。 */
-  dnsRules: string[];
+  /** 拿 fake IP 的域名：只有它们会进 fakeip 分支，其余域名落到默认解析（拒绝）。 */
+  fakeIpWhitelist: string[];
 }
 
 /**
  * allowlist 条目 → mihomo 规则：
- * - 域名（含 :port 条目里的域名）进 fake-ip-filter，真实解析避免 DIRECT 出站
- *   拿到 fakeip 再进 TUN 形成环（loopback detector 会拒绝）；
+ * - 域名（含 :port 条目里的域名）进 fake-ip-filter（配合 filter-mode: whitelist，
+ *   即「只有这些域名拿 fake IP」）：fake IP 与域名一一对应，连接到达时凭它精确还原
+ *   域名再匹配规则，不依赖嗅探、也不受 DNS TTL 影响；
+ * - 匹配精度两档：裸域名只匹配该域名本身（DOMAIN / 白名单里的裸域名），
+ *   `*.` 前缀匹配它的全部子域名、不含它本身（DOMAIN-WILDCARD / dot-wildcard）；
  * - 无端口条目直接匹配；带端口条目用 AND 组合（域名/IP + DST-PORT）精确放行；
- * - 最后以 MATCH,REJECT 兜底实现 deny-by-default。
- * dns.rules 同步构建：allowlist 域名 DIRECT，其余 MATCH,REJECT——未允许域名
- * 在 DNS 层即被拒绝（curl 报 Could not resolve host），而不是先拿 fake-ip、
- * 到连接层才断（报 TLS decode error，容易误判为网络故障）。
+ * - 最后以 MATCH,REJECT 兜底实现 deny-by-default（裸 IP 连接、绕过 DNS 的客户端）。
+ *
+ * 未进白名单的域名（即未允许域名）不拿 fake IP，直接落到 nameserver，被
+ * rcode://name_error 即时拒绝（客户端报 Could not resolve host）——mihomo 的 fakeip
+ * 分支本身没有按域名拒绝的钩子，收窄白名单是唯一能让拒绝发生在 DNS 层的办法。
  */
 function buildRules(allowlist: readonly string[]): BuiltRules {
   const rules: string[] = [];
-  const fakeIpFilter: string[] = [];
-  const dnsRules: string[] = [];
+  const fakeIpWhitelist: string[] = [];
   for (const entry of allowlist) {
-    const { host, port } = parseAllowlistEntry(entry);
+    const { host, port, subdomains } = parseAllowlistEntry(entry);
     if (!isIp(host)) {
-      fakeIpFilter.push(`+.${host}`);
-      // DNS 层按域名放行（端口无关）；连接层规则保留端口语义
-      dnsRules.push(`DOMAIN-SUFFIX,${host},DIRECT`);
+      // DNS 侧与连接层必须表达同一集合：精确条目用裸域名 / DOMAIN，
+      // 子域名条目用 dot-wildcard（任意深度子域名，不含 apex）/ DOMAIN-WILDCARD
+      fakeIpWhitelist.push(subdomains ? `.${host}` : host);
+      const domainRule = subdomains ? `DOMAIN-WILDCARD,*.${host},DIRECT` : `DOMAIN,${host},DIRECT`;
       if (port === undefined) {
-        rules.push(`DOMAIN-SUFFIX,${host},DIRECT`);
+        rules.push(domainRule);
       } else {
-        rules.push(`AND,(DOMAIN-SUFFIX,${host},DIRECT),(DST-PORT,${port},DIRECT),DIRECT`);
+        rules.push(`AND,(${domainRule}),(DST-PORT,${port},DIRECT),DIRECT`);
       }
     } else if (port === undefined) {
       rules.push(ipRule(host));
@@ -166,24 +204,26 @@ function buildRules(allowlist: readonly string[]): BuiltRules {
     }
   }
   rules.push("MATCH,REJECT");
-  dnsRules.push("MATCH,REJECT");
-  return { rules, fakeIpFilter, dnsRules };
+  return { rules, fakeIpWhitelist };
 }
 
 /**
- * 生成 mihomo（Clash Meta）配置对象：TUN + fakeip + deny-by-default allowlist。
+ * 生成 mihomo（Clash Meta）配置对象：TUN + 白名单 fakeip + deny-by-default allowlist。
  *
  * - auto-detect-interface 让 mihomo 出站绑定 slirp4netns 的 tap0，否则它自己的
  *   DNS 查询会被 auto_route 送回 TUN 形成环；
  * - TUN mtu 与 slirp4netns `--mtu` 共用 TUN_MTU，避免依赖各自默认值；
- * - allowlist 域名走 fake-ip-filter 真实解析（见 buildRules 注释）。
+ * - fakeip 只服务 allowlist 域名（filter-mode: whitelist，见 buildRules 注释）：
+ *   域名归属因此精确且不随 TTL 失效；
+ * - direct-nameserver 必须指向真实 DNS：连接由 fake IP 还原成域名后，DIRECT 出站要
+ *   按域名重新解析，不指定就会解析回 fake-ip 再进 TUN 成环。
  */
 export function generateMihomoConfig(options: MihomoConfigOptions): MihomoConfig {
   const { allowlist, dnsServers } = options;
   if (dnsServers.length === 0) {
     throw new Error("At least one DNS server is required");
   }
-  const { rules, fakeIpFilter, dnsRules } = buildRules(allowlist);
+  const { rules, fakeIpWhitelist } = buildRules(allowlist);
   return {
     "mixed-port": 0,
     mode: "rule",
@@ -199,10 +239,11 @@ export function generateMihomoConfig(options: MihomoConfigOptions): MihomoConfig
       ipv6: false,
       "enhanced-mode": "fake-ip",
       "fake-ip-range": FAKEIP_RANGE,
-      nameserver: [...dnsServers],
+      "fake-ip-filter-mode": "whitelist",
+      ...(fakeIpWhitelist.length > 0 && { "fake-ip-filter": fakeIpWhitelist }),
+      nameserver: [REJECT_NAMESERVER],
       "default-nameserver": [...dnsServers],
-      ...(fakeIpFilter.length > 0 && { "fake-ip-filter": fakeIpFilter }),
-      rules: dnsRules,
+      "direct-nameserver": [...dnsServers],
     },
     tun: {
       enable: true,

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) {