dsh-pwsh-plugin 0.0.0-stage → 0.2.13

package/wsl/acceptance.sh

@@ -0,0 +1,155 @@
+#!/bin/bash
+# llrun 验收矩阵 —— 长期回归脚本（缺目录的条目自动 SKIP）
+# 用法：bash wsl/acceptance.sh            （在 WSL 里跑，需要 llrun 可执行）
+#       LLRUN=/usr/local/bin/llrun bash wsl/acceptance.sh
+# 只读检查，全部探针文件用完即删；每个断言末尾都会做磁盘复核。
+
+HERE=$(cd "$(dirname "$0")" && pwd)
+WS=$(cd "$HERE/.." && pwd)
+LL=${LLRUN:-$HERE/llrun}
+
+# 工作区所在的盘符挂载点，例如 /mnt/d
+DRIVE=$(printf '%s' "$WS" | cut -d/ -f1-3)
+PARENT=$(dirname "$WS")
+
+# Windows 用户目录：取 /mnt/<盘符>/Users 下第一个真实用户目录。
+WINHOME=
+for candidate in /mnt/*/Users/*/; do
+  case "$candidate" in
+    */All\ Users/*|*/Default/*|*/Default\ User/*|*/Public/*) continue ;;
+  esac
+  WINHOME=${candidate%/}
+  break
+done
+
+# 「工作区外」的目标：存在的才算，逐个验证写不进去。
+OUTSIDE=()
+for dir in "$PARENT" "$DRIVE" "$WINHOME" "$(dirname "$WINHOME")/Users"; do
+  [ -n "$dir" ] && [ -d "$dir" ] && OUTSIDE+=("$dir")
+done
+
+pass=0; fail=0; skip=0
+chk() { if [ "$2" = "$3" ]; then echo "  PASS  $1"; pass=$((pass+1)); else echo "  FAIL  $1 (got=$2 want=$3)"; fail=$((fail+1)); fi; }
+
+echo "llrun      = $LL"
+echo "workspace  = $WS"
+echo "drive root = $DRIVE"
+echo "win home   = ${WINHOME:-<none>}"
+echo
+
+echo '== 写边界：工作区外一律拒绝 =='
+i=0
+for dir in "${OUTSIDE[@]}"; do
+  i=$((i+1))
+  target="$dir/_lacc_$i.txt"
+  chk "写不进 $dir" "$($LL "$WS" /bin/bash -c "touch '$target' 2>/dev/null && echo W || echo D")" 'D'
+done
+chk '写不进 /var/tmp' "$($LL "$WS" /bin/bash -c 'touch /var/tmp/_lacc_v 2>/dev/null && echo W || echo D')" 'D'
+chk '/var/tmp 可读' "$($LL "$WS" /bin/bash -c 'ls /var/tmp >/dev/null && echo R || echo N')" 'R'
+chk '工作区内可写' "$(WSX="$WS" $LL "$WS" /bin/bash -c 'touch "$WSX"/_lacc_ws.txt 2>/dev/null && echo W || echo D; rm -f "$WSX"/_lacc_ws.txt')" 'W'
+chk '/tmp 可写' "$($LL "$WS" /bin/bash -c 'touch /tmp/_lacc_t.txt 2>/dev/null && echo W || echo D; rm -f /tmp/_lacc_t.txt')" 'W'
+chk '/home（本用户）可写' "$($LL "$WS" /bin/bash -c 'touch ~/_lacc_h.txt 2>/dev/null && echo W || echo D; rm -f ~/_lacc_h.txt')" 'W'
+chk '工作区外可读' "$($LL "$WS" /bin/bash -c "ls '$PARENT' >/dev/null && echo R || echo N")" 'R'
+chk '/dev/shm 默认可写' "$($LL "$WS" /bin/bash -c 'touch /dev/shm/_lacc_s 2>/dev/null && echo W || echo D; rm -f /dev/shm/_lacc_s')" 'W'
+
+echo '== Windows exe 全封（landlock 白名单不含 /init）=='
+chk 'cmd.exe' "$($LL "$WS" /bin/bash -c '/mnt/c/Windows/System32/cmd.exe /c echo x >/dev/null 2>&1 && echo RAN || echo BLOCKED')" 'BLOCKED'
+chk 'powershell.exe' "$($LL "$WS" /bin/bash -c '/mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe -c "echo x" >/dev/null 2>&1 && echo RAN || echo BLOCKED')" 'BLOCKED'
+chk 'notepad.exe' "$($LL "$WS" /bin/bash -c '/mnt/c/Windows/System32/notepad.exe >/dev/null 2>&1 && echo RAN || echo BLOCKED')" 'BLOCKED'
+chk '/init 直调' "$($LL "$WS" /bin/bash -c '/init /mnt/c/Windows/System32/cmd.exe /c echo x >/dev/null 2>&1 && echo RAN || echo BLOCKED')" 'BLOCKED'
+
+echo '== docker 逃逸 =='
+chk 'docker ps' "$($LL "$WS" /bin/bash -c 'timeout 6 docker ps >/dev/null 2>&1 && echo CONNECTED || echo BLOCKED')" 'BLOCKED'
+chk '--no-isolate 时 docker（反向对照）' "$($LL --no-isolate "$WS" /bin/bash -c 'timeout 6 docker ps >/dev/null 2>&1 && echo CONNECTED || echo BLOCKED')" 'CONNECTED'
+chk 'socket 直连' "$($LL "$WS" /bin/bash -c 'timeout 5 python3 -c "
+import socket
+try:
+    socket.socket(socket.AF_UNIX).connect(chr(47)+chr(118)+chr(97)+chr(114)+chr(47)+chr(114)+chr(117)+chr(110)+chr(47)+chr(100)+chr(111)+chr(99)+chr(107)+chr(101)+chr(114)+chr(46)+chr(115)+chr(111)+chr(99)+chr(107))
+    print(\"CONNECTED\")
+except Exception:
+    print(\"BLOCKED\")
+"' | tail -1)" 'BLOCKED'
+
+echo '== 开发者工具链 =='
+chk 'git' "$($LL "$WS" /bin/bash -c 'git --version >/dev/null && echo OK')" 'OK'
+chk 'node' "$($LL "$WS" /bin/bash -c 'node -e 1 && echo OK')" 'OK'
+chk 'python3' "$($LL "$WS" /bin/bash -c 'python3 -c "print(7*6)"')" '42'
+chk 'gcc' "$($LL "$WS" /bin/bash -c 'echo "int main(){return 0;}" > /tmp/_lacc.c && gcc -o /tmp/_lacc /tmp/_lacc.c && echo OK; rm -f /tmp/_lacc /tmp/_lacc.c')" 'OK'
+HOST_PKG=$(dpkg -l 2>/dev/null | wc -l)
+chk 'dpkg 只读查询' "$($LL "$WS" /bin/bash -c 'dpkg -l 2>/dev/null | wc -l')" "$HOST_PKG"
+chk 'curl 网络' "$($LL "$WS" /bin/bash -c 'curl -s -o /dev/null -w "%{http_code}" https://www.bing.com')" '200'
+chk 'ssh 不报属主错误' "$($LL "$WS" /bin/bash -c 'ssh -G github.com 2>&1 | grep -c "Bad owner"')" '0'
+
+echo '== -r 严格只读：写入一律拒绝 =='
+chk '-r 写工作区' "$(WSX="$WS" $LL -r "$WS" /bin/bash -c 'touch "$WSX"/_lacc_r0.txt 2>/dev/null && echo W || echo D')" 'D'
+chk '-r 写 /tmp' "$($LL -r "$WS" /bin/bash -c 'touch /tmp/_lacc_r1 2>/dev/null && echo W || echo D')" 'D'
+chk '-r 写 /home' "$($LL -r "$WS" /bin/bash -c 'touch ~/_lacc_r2 2>/dev/null && echo W || echo D')" 'D'
+chk '-r 写 /dev/shm' "$($LL -r "$WS" /bin/bash -c 'touch /dev/shm/_lacc_r3 2>/dev/null && echo W || echo D')" 'D'
+chk '-r 写 /var/tmp' "$($LL -r "$WS" /bin/bash -c 'touch /var/tmp/_lacc_r4 2>/dev/null && echo W || echo D')" 'D'
+chk '-r 写 /etc' "$($LL -r "$WS" /bin/bash -c 'touch /etc/_lacc_r5 2>/dev/null && echo W || echo D')" 'D'
+chk '-r 写 /var/log' "$($LL -r "$WS" /bin/bash -c 'touch /var/log/_lacc_r6 2>/dev/null && echo W || echo D')" 'D'
+chk '-r mktemp' "$($LL -r "$WS" /bin/bash -c 'mktemp -d >/dev/null 2>&1 && echo OK || echo NO')" 'NO'
+
+echo '== -r 严格只读：读取照常 =='
+chk '-r 读工作区' "$(WSX="$WS" $LL -r "$WS" /bin/bash -c 'ls "$WSX" >/dev/null && echo R || echo N')" 'R'
+chk '-r 读 /tmp' "$($LL -r "$WS" /bin/bash -c 'ls /tmp >/dev/null && echo R || echo N')" 'R'
+chk '-r 读 /home' "$($LL -r "$WS" /bin/bash -c 'ls ~ >/dev/null && echo R || echo N')" 'R'
+chk '-r 读 /etc' "$($LL -r "$WS" /bin/bash -c 'cat /etc/hostname >/dev/null && echo R || echo N')" 'R'
+chk '-r 读工作区外' "$($LL -r "$WS" /bin/bash -c "ls '$PARENT' >/dev/null && echo R || echo N")" 'R'
+chk '-r 写 /dev/null' "$($LL -r "$WS" /bin/bash -c 'echo x > /dev/null && echo OK')" 'OK'
+
+echo '== -r 严格只读：工具链存活（无 /tmp 可写的代价见 README）=='
+chk '-r python3' "$($LL -r "$WS" /bin/bash -c 'python3 -c "print(7*6)"')" '42'
+chk '-r git' "$($LL -r "$WS" /bin/bash -c 'git --version >/dev/null && echo OK')" 'OK'
+chk '-r curl' "$($LL -r "$WS" /bin/bash -c 'curl -s -o /dev/null -w "%{http_code}" https://www.bing.com')" '200'
+chk '-r dpkg' "$($LL -r "$WS" /bin/bash -c 'dpkg -l 2>/dev/null | wc -l')" "$(dpkg -l 2>/dev/null | wc -l)"
+chk '-r ssh' "$($LL -r "$WS" /bin/bash -c 'ssh -G github.com 2>&1 | grep -c "Bad owner"')" '0'
+chk '-r gcc 不可用（/tmp 只读，符合预期）' "$($LL -r "$WS" /bin/bash -c 'gcc -x c -o /dev/null - <<< "int main(){return 0;}" >/dev/null 2>&1 && echo OK || echo NO')" 'NO'
+
+echo '== -r 严格只读：删除/重命名同样拒绝 =='
+# 先在工作区内建好目标文件（-r 档建不出来），再在 -r 档里删它
+printf x > "$WS"/_lacc_rd
+chk '-r 删工作区文件' "$(WSX="$WS" $LL -r "$WS" /bin/bash -c 'rm -f "$WSX"/_lacc_rd 2>/dev/null && echo DONE || echo D')" 'D'
+chk '-r 删除后文件仍在' "$([ -e "$WS"/_lacc_rd ] && echo STILL || echo GONE)" 'STILL'
+rm -f "$WS"/_lacc_rd
+chk '-r 建目录' "$(WSX="$WS" $LL -r "$WS" /bin/bash -c 'mkdir -p "$WSX"/_lacc_md 2>/dev/null && echo MADE || echo D')" 'D'
+
+echo '== 开关 =='
+chk '-C /tmp' "$($LL -C /tmp - /bin/bash -c 'pwd')" '/tmp'
+chk '--no-seal 放开 /var/tmp' "$($LL --no-seal "$WS" /bin/bash -c 'touch /var/tmp/_lacc_ns 2>/dev/null && echo W || echo D; rm -f /var/tmp/_lacc_ns')" 'W'
+chk '--no-isolate 同时失去封印' "$($LL --no-isolate "$WS" /bin/bash -c 'touch /var/tmp/_lacc_ni 2>/dev/null && echo W || echo D; rm -f /var/tmp/_lacc_ni')" 'W'
+
+echo '== 原样传递 =='
+cat > /tmp/_lacc_sd.sh <<'OUTER'
+cat <<'INNER'
+lit $HOME $(cmd) 'single' "double" \ back
+INNER
+OUTER
+chk 'stdin heredoc 字面量' "$($LL "$WS" /bin/bash -s < /tmp/_lacc_sd.sh)" 'lit $HOME $(cmd) '\''single'\'' "double" \ back'
+rm -f /tmp/_lacc_sd.sh
+chk '退出码 42' "$($LL "$WS" /bin/bash -c 'exit 42'; echo $?)" '42'
+chk '中文' "$($LL "$WS" /bin/bash -c 'echo 你好世界')" '你好世界'
+chk 'workspace=/' "$($LL / /bin/bash -c 'echo x' 2>/dev/null; echo $?)" '126'
+
+echo
+echo "TOTAL pass=$pass fail=$fail skip=$skip"
+echo '--- 磁盘复核 ---'
+leaks=0
+for dir in "${OUTSIDE[@]}"; do
+  for f in "$dir"/_lacc_*.txt; do
+    [ -e "$f" ] || continue
+    echo "  LEAK  $f"; leaks=$((leaks+1))
+  done
+done
+for f in /var/tmp/_lacc_v /var/tmp/_lacc_r4 /tmp/_lacc_r1 /dev/shm/_lacc_r3 \
+         /etc/_lacc_r5 /var/log/_lacc_r6 "$WS"/_lacc_md "$WS"/_lacc_rd \
+         "$WS"/_lacc_r0.txt "$WS"/_lacc_ws.txt "$WS"/_lacc_t.txt; do
+  [ -e "$f" ] && { echo "  LEAK  $f"; leaks=$((leaks+1)); }
+done
+echo "  leaks=$leaks"
+
+# 已存在的属主/能力快照，便于发现回归
+echo '--- 能力快照 ---'
+$LL "$WS" /bin/bash -c 'printf "  sudo: %s\n" "$(sudo -n true 2>&1 | head -1)"; printf "  dbus: %s\n" "$(timeout 5 dbus-send --session --dest=org.freedesktop.DBus --type=method_call /org/freedesktop/DBus org.freedesktop.DBus.ListNames 2>&1 | grep -qi "Failed to open connection" && echo UNREACHABLE || echo OK)"'
+
+exit $([ "$fail" -eq 0 ] && echo 0 || echo 1)

package/wsl/compaction-epoch.mjs

@@ -0,0 +1,115 @@
+// 这个文件是 `presets/shared/compaction-epoch.mjs` 的源：部署时复制进 DSH profile，
+// 这里保留一份供 `wsl/custom-bash.mjs` import 与测试。**改这里，再同步到 profile。**
+/**
+ * compaction-epoch —— 感知压缩边界的「晋升」状态跟踪器（共享模块，不是插件行）
+ *
+ * 用途
+ *   tool-bootstrap / instruction-hint / router-bootstrap 都需要回答同一个问题：
+ *   「这个会话现在算不算已经晋升？」本模块给出唯一答案，三者共用，口径一致。
+ *
+ * 规则
+ *   - 晋升信号 = 调用方指定的持久事件类型（`tool/call` 和/或 `assistant/message`）。
+ *   - 压缩会把整段可见上下文重写成一条摘要，压缩后的第一次请求等同于「第二个首请求」，
+ *     所以晋升按「纪元」计算：只有落在最近一次 `compaction/end` 之后的晋升信号才算数。
+ *   - 从未压缩过时边界为 -1，行为与「一次性晋升」完全相同。
+ *   - 子智能体（delegationDepth > 0）默认视为已晋升，首请求就能用工具；
+ *     传 `includeSubagents: true` 可让子智能体也走锚定相位。
+ *
+ * 实现
+ *   - 每个会话的状态按 session id 记忆；冷启动 / 恢复会话时扫描一次持久日志重建相位，
+ *     之后靠 `observe()` 增量更新，O(1)。
+ *   - 持久日志只能经 `session.snapshotEvents()` 读取。`Session` 上没有 `events`
+ *     属性（0.1.3 起一直如此）；读不存在的属性曾让锚定相位悄悄失效（首请求带了 197 个工具）。
+ */
+
+/**
+ * 创建一个跟踪器。
+ * @param {string[]} promoteEvents 计为晋升信号的持久事件类型
+ * @param {{ includeSubagents?: boolean }} [options]
+ */
+export function createEpochPromotion(promoteEvents, options = {}) {
+  const includeSubagents = options.includeSubagents === true
+  const promote = new Set(promoteEvents)
+  /** session id -> { boundary, promoted } */
+  const state = new Map()
+
+  /** 从头扫描一次持久日志（冷启动 / 恢复会话）。 */
+  const scan = (session) => {
+    let boundary = -1
+    let promoted = false
+    const events = typeof session.snapshotEvents === 'function' ? session.snapshotEvents() : []
+    for (const event of events) {
+      // 没有 seq 的事件按「边界之后」处理。
+      const seq = event.seq ?? 0
+      if (event.type === 'compaction/end') {
+        boundary = seq
+        promoted = false
+        continue
+      }
+      if (promote.has(event.type) && seq > boundary) promoted = true
+    }
+    const entry = { boundary, promoted }
+    state.set(session.id, entry)
+    return entry
+  }
+
+  return {
+    /**
+     * 查询某个 agent 所在会话的当前相位。
+     * @returns {{ boundary: number, promoted: boolean }}
+     *   boundary：最近一次 compaction/end 的 seq（未压缩过为 -1）；
+     *   promoted：边界之后是否已有晋升信号。
+     *   没有 agent / session 时一律视为已晋升（宁可多给工具，也不卡死请求）。
+     */
+    status(agent) {
+      if (agent === undefined) return { boundary: -1, promoted: true }
+      const session = agent.session
+      if (session === undefined) return { boundary: -1, promoted: true }
+      if (!includeSubagents && (session.header?.delegationDepth ?? 0) > 0) return { boundary: -1, promoted: true }
+      return state.get(session.id) ?? scan(session)
+    },
+
+    /** 增量喂入：在每个 `session/event` 上调用。尚未被查询过的会话直接忽略，等首次查询时再扫描。 */
+    observe(session, event) {
+      const entry = state.get(session.id)
+      if (entry === undefined) return
+      const seq = event.seq ?? 0
+      if (event.type === 'compaction/end') {
+        state.set(session.id, { boundary: seq, promoted: false })
+        return
+      }
+      if (promote.has(event.type) && seq > entry.boundary && !entry.promoted) {
+        state.set(session.id, { ...entry, promoted: true })
+      }
+    },
+  }
+}
+
+/**
+ * 读取 `user/message` 持久事件里的消息来源。
+ * V4 会话格式把 source 放在 `event.data.source`；早期本地代码误读成
+ * `event.data.message.source`，导致「是否已注入过」的去重永远判否。两种形状都兼容。
+ */
+export function eventSource(event) {
+  return event?.data?.source ?? event?.data?.message?.source
+}
+
+/** 读取 `user/message` 持久事件里的消息 id（两种形状都兼容，理由同上）。 */
+export function eventMessageId(event) {
+  return event?.data?.id ?? event?.data?.message?.id
+}
+
+/**
+ * 解析会话当前工作目录。
+ * 上游已把工作目录交给 `workingDirectory` 服务管理（会话中途 cd 之后 header.cwd 不会更新），
+ * 所以优先问服务；服务不存在（旧宿主）时退回 header.cwd，再退回进程 cwd。
+ */
+export async function resolveCwd(ctx, agent, signal) {
+  try {
+    const service = ctx.get('workingDirectory')
+    if (service !== undefined && agent !== undefined) return await service.ensure(agent, signal)
+  } catch {
+    // 服务异常时退回旧路径，不让一次目录查询拖垮工具调用。
+  }
+  return agent?.session?.header?.cwd ?? process.cwd()
+}

package/wsl/custom-bash.mjs

@@ -0,0 +1,355 @@
+/**
+ * custom-bash —— Windows 上的 `bash` 工具（插件行，可在多个 agent 预设里各挂一份）
+ *
+ * 为什么需要它
+ *   官方 persistent bash 依赖 PTY，而 DSH 的 PTY 后端只支持 linux/darwin，
+ *   在 win32 上会直接报 "terminal inspection is unsupported"。本工具注册同名 `bash`、
+ *   使用与 Minimal 相近的描述，但通过跨平台的 `ctx.subprocess.spawn` 起进程，
+ *   从而在 Windows 上保留「首请求只有 bash」这一锚定 schema（issue #11）。
+ *
+ * Windows 适配
+ *   Windows 上没有 Git Bash 时，PATH 上的 `bash` 通常是 WSL 垫片；
+ *   组合里因此把 `bashPath` 指向 `C:\Windows\System32\bash.exe`，描述写明「WSL Debian」。
+ *
+ * 配置
+ *   bashPath        可执行文件：绝对路径，或 `bash`（经 PATH 解析）。默认 `bash`，
+ *                   解不到时再试 win32 上的 C:\Windows\System32\bash.exe（同一个 WSL 垫片），
+ *                   免得 PATH 少一项整个工具就废掉。显式给绝对路径则只认那一个。
+ *   timeoutMs       单次命令超时，默认 120000。超时会终止进程并返回已收集的输出。
+ *   maxOutputBytes  stdout / stderr 各自的收集上限，默认 64000。
+ *   llrunPath       WSL 侧的 llrun 二进制（POSIX 路径）。默认按顺序探测 $LLRUN、
+ *                   <DSH_HOME>/bin/llrun、/usr/local/bin/llrun、~/.local/bin/llrun，
+ *                   最后才用包内自带的 wsl/llrun —— 显式安装的优先，包里那份只负责开箱可用。
+ *                   取第一个可执行的；探测结果缓存，装好即生效，不必重启。
+ *   fence           是否按 sandbox 权限档挂围栏，默认 true。
+ *
+ * 沙箱（2026-10-23）
+ *   workspace-write / read-only 下经 `wsl/llrun` 起 bash：userns socket 掩蔽（docker 等）
+ *   + landlock ABI 7 + /var/tmp 封印；read-only 走 `-r` 严格只读档（写入全拒、读取全留）。
+ *   danger-full-access 走裸 bash —— 这是 DSH 既定语义（该档 bypasses confinement），不是缺口。
+ *   llrun 缺失时 fail-closed 抛错，不会静默降级成无围栏。
+ *
+ * 语义
+ *   每次调用都是全新进程，状态不跨调用保留。命令经 **stdin 送入 `bash -s`**，
+ *   不再拼进 `bash -c` 字符串 —— 避开 Windows bash.exe 的 argv 引号怪癖（事故根因之一）。
+ *   非零退出码不抛异常，而是在输出末尾注明退出码（与官方 bash 工具一致）；
+ *   只有进程根本起不来时才抛错。
+ *
+ * 几处容易踩反的细节
+ *   - `timeoutMs` 必须真落成 timer：只解析不使用会让长命令无限挂住整个工具调用。
+ *   - POSIX 路径的 `workdir` 不能当 Windows 进程 cwd（spawn 直接失败）；
+ *     有围栏时交给 llrun 的 `-C`（在 landlock 之后 chdir），无围栏时退化为命令内 `cd`。
+ *   - 默认工作目录取自 workingDirectory 服务而非 header.cwd：会话中途切目录后 header 不更新。
+ */
+
+import { fileURLToPath } from 'node:url'
+
+import { resolveCwd } from './compaction-epoch.mjs'
+
+/** 加载器诊断里显示的插件名。 */
+export const name = 'custom-bash'
+
+/** 注册前必须已有的服务。 */
+export const inject = ['subprocess', 'tools']
+
+/**
+ * `bash` 解不出来时的后备可执行文件。
+ * PATH 上缺 System32 是真实会发生的（进程环境块可能停在旧快照上），
+ * 而 WSL 垫片的位置是固定的，写死它比让整个工具报 "not found on PATH" 划算。
+ * 只在配置给的是裸名时启用；给了绝对路径就只认那一个。
+ */
+const WINDOWS_BASH_FALLBACKS = ['C:\\Windows\\System32\\bash.exe']
+
+const DEFAULT_TIMEOUT_MS = 120000
+const DEFAULT_MAX_OUTPUT_BYTES = 64000
+const PROBE_TIMEOUT_MS = 8000
+
+/**
+ * 本文件同目录的 llrun，也就是随插件包一起发布的那份。
+ * 从包加载时它是真的存在（bundle 把这一行指进 node_modules），
+ * 所以「装完就能用」不依赖用户往系统目录里放东西。
+ * 非 file: 协议加载（测试里的 data: URL 之类）时拿不到路径，返回 undefined。
+ */
+function packagedLlrunPath() {
+  try {
+    // 目录 URL 带尾分隔符，去掉再转，免得拼出双斜杠。
+    const dir = fileURLToPath(new URL('.', import.meta.url)).replace(/[\\/]$/, '')
+    // 包本身就在 POSIX 文件系统上时（非 Windows 宿主，或从 WSL 侧加载），
+    // 它已经是可直接用的路径，不必也无法转成 /mnt/<drive>。
+    return dir.startsWith('/') ? dir : toWslPath(dir)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * llrun 的候选位置。显式配置 llrunPath 时只用那一个；否则按顺序探测第一个可执行的。
+ * 用户自己装的排在包内那份前面：系统级的 llrun 可能更新，包内的只保证可用。
+ * /usr/local/bin 在多数发行版属于 root，普通用户装不进去，所以用户可写的位置也要列上。
+ */
+function defaultLlrunCandidates() {
+  const candidates = []
+  const fromEnv = process.env.LLRUN ?? process.env.DSH_LLRUN
+  if (typeof fromEnv === 'string' && fromEnv.length > 0) candidates.push(fromEnv)
+  // DSH_HOME 是 Windows 路径，转成 WSL 视角后才能 test -x。
+  const posixHome = toWslPath(process.env.DSH_HOME)
+  if (posixHome !== undefined) candidates.push(posixHome + '/bin/llrun')
+  candidates.push('/usr/local/bin/llrun', '~/.local/bin/llrun')
+  const packaged = packagedLlrunPath()
+  if (packaged !== undefined) candidates.push(packaged + '/llrun')
+  return [...new Set(candidates)]
+}
+
+/**
+ * 构造探测脚本，经 stdin 送给 `bash -s`。
+ * 不能走 `bash -c`：Windows 上的 WSL 垫片 bash.exe 会把 `-c` 的正文里
+ * 单字母变量赋值 `x=abc` 整个吃掉（实测 `x=abc; echo "x=$x"` 输出 `x=`），
+ * 探测会因此算出错误的候选序号。走 stdin 完全避开这层改写。
+ * 结果只走退出码：0 = 一个都没有，N = 第 N 个候选可执行；不读 stdout，
+ * 因为收集缓冲区只在 stdio 声明为 collect 时才存在，不该把可用性押在它上面。
+ * 候选里的 ~ 在这里展开：用引号包起来的路径不会被 bash 做 tilde 展开。
+ */
+export function llrunProbeScript(candidates) {
+  // ~ 在生成时展开成 $HOME，留给 bash 自己解析，不写死探测时的家目录。
+  const posix = candidates.map((candidate) => candidate.startsWith('~/') ? '$HOME/' + candidate.slice(2) : candidate)
+  const lines = []
+  // 第一遍只看能不能跑：任何一个可用就定下来，顺序即优先级。
+  const first = ['index=0']
+  posix.forEach((path) => {
+    first.push('index=$((index + 1))')
+    first.push('if [ -x "' + path + '" ]; then exit "$index"; fi')
+    // npm 打包在 Windows 上会把文件权限写成 644（那里没有执行位概念），
+    // 装到真实 Linux 后这份 llrun 就不可执行。它是我们发的、属主是装包的人，
+    // 所以可以就地补上执行位；别人的文件（-O 为假）不碰。
+    first.push('if [ -f "' + path + '" ] && [ -O "' + path + '" ] && chmod +x "' + path + '" 2>/dev/null && [ -x "' + path + '" ]; then exit "$index"; fi')
+  })
+  lines.push(...first)
+  // 第二遍才看「在但不是可执行」：要等所有候选都否定过，否则一个无关的文件
+  // 会让后面本来能用的那几份没机会。退出码 100+N 让上层能说清是哪一份。
+  const second = ['index=0']
+  posix.forEach((path) => {
+    second.push('index=$((index + 1))')
+    second.push('if [ -e "' + path + '" ]; then exit "$((100 + index))"; fi')
+  })
+  lines.push(...second)
+  lines.push('exit 0')
+  return lines.join('\n')
+}
+
+/**
+ * 把命中路径变成可以安全跟在 `exec` 后面的词。
+ * `~/` 开头的候选由 bash 自己的 $HOME 展开，所以这一支不能加单引号。
+ */
+function llrunExecWord(path) {
+  if (path.startsWith('~/')) return '"$HOME/' + path.slice(2) + '"'
+  return shellQuote(path)
+}
+
+/** 面向模型的参数 schema。 */
+const commandSchema = {
+  type: 'object',
+  properties: {
+    command: {
+      type: 'string',
+      description: 'The bash command to execute (`bash` script domain, fed through stdin — no argument quoting involved).',
+    },
+    workdir: {
+      type: 'string',
+      description: 'Optional working directory (Windows path or WSL path such as /mnt/d/...); defaults to the session working directory.',
+    },
+  },
+  required: ['command'],
+  additionalProperties: false,
+}
+
+/** 单引号转义，用于把 POSIX 路径安全拼进 shell 片段。 */
+const shellQuote = (value) => `'${String(value).replaceAll("'", "'\\''")}'`
+
+/** 合并调用方的取消信号与本工具的超时信号。 */
+function withTimeout(signal, timeoutMs) {
+  const timeout = AbortSignal.timeout(timeoutMs)
+  return signal === undefined ? timeout : AbortSignal.any([signal, timeout])
+}
+
+/** Windows 绝对路径 → WSL 视角的 /mnt/<drive>/...；无法映射时返回 undefined。 */
+function toWslPath(path) {
+  if (typeof path !== 'string') return undefined
+  const matched = /^([A-Za-z]):[\\/](.*)$/.exec(path)
+  if (matched === null) return undefined
+  return `/mnt/${matched[1].toLowerCase()}/${matched[2].replaceAll('\\', '/')}`
+}
+
+export function apply(ctx, config) {
+  const bashPath = typeof config?.bashPath === 'string' && config.bashPath.length > 0 ? config.bashPath : 'bash'
+  // 裸名才允许走后备：显式绝对路径是用户的明确选择，替他改路径反而掩盖配置错误。
+  const bashCandidates = bashPath === 'bash' && process.platform === 'win32'
+    ? ['bash', ...WINDOWS_BASH_FALLBACKS]
+    : [bashPath]
+  const timeoutMs = Number.isSafeInteger(config?.timeoutMs) && config.timeoutMs > 0 ? config.timeoutMs : DEFAULT_TIMEOUT_MS
+  const maxOutputBytes = Number.isSafeInteger(config?.maxOutputBytes) && config.maxOutputBytes > 0 ? config.maxOutputBytes : DEFAULT_MAX_OUTPUT_BYTES
+  // 显式配置时只认那一个；否则探测候选。解析结果跨调用缓存，失败不缓存。
+  const configuredLlrun = typeof config?.llrunPath === 'string' && config.llrunPath.length > 0 ? config.llrunPath : undefined
+  const llrunCandidates = configuredLlrun === undefined ? defaultLlrunCandidates() : [configuredLlrun]
+  const fenceEnabled = config?.fence !== false
+
+  /**
+   * bash 解析：按 bashCandidates 顺序问 subprocess 服务，第一个解出来的胜出。
+   * 缓存成功结果、不缓存失败 —— PATH 修好之后下一次调用立刻能用，不必重启 DSH。
+   * 全都解不出来时把最后一个错误抛出去：它带的是 "was not found on PATH"，
+   * 只有一次 resolve 时也就是原来的行为，文案不变。
+   */
+  let resolvedShell
+  async function resolveShell(signal) {
+    if (resolvedShell !== undefined) return resolvedShell
+    let lastError
+    for (const candidate of bashCandidates) {
+      try {
+        resolvedShell = await ctx.subprocess.resolveExecutable(candidate, undefined, signal)
+        return resolvedShell
+      } catch (error) {
+        lastError = error
+      }
+    }
+    throw lastError
+  }
+
+  /**
+   * llrun 解析：返回真正可执行的那个路径，探测不到返回 undefined。
+   * 成功结果跨调用缓存（同一进程里 llrun 不会凭空消失），失败不缓存，
+   * 这样用户装好之后下一次调用就能直接用，不必重启 DSH。
+   */
+  let resolvedLlrun
+  // 探测到「文件存在但用不了」的候选，供错误文案区分两种情况。
+  let unusableLlrun
+  async function resolveLlrun(shell, cwd) {
+    if (resolvedLlrun !== undefined) return resolvedLlrun
+    const handle = ctx.subprocess.spawn({
+      argv: [shell, '-s'],
+      ...cwd !== undefined ? { cwd } : {},
+      stdio: { stdin: { data: llrunProbeScript(llrunCandidates) }, stdout: { maxBytes: 4096 }, stderr: { maxBytes: 4096 } },
+      signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+      graceMs: 3000,
+    })
+    const outcome = await handle.done.catch(() => undefined)
+    const index = outcome?.exitCode
+    if (!Number.isInteger(index)) return undefined
+    if (index > 100 && index <= 100 + llrunCandidates.length) {
+      unusableLlrun = llrunCandidates[index - 101]
+      return undefined
+    }
+    if (index < 1 || index > llrunCandidates.length) return undefined
+    resolvedLlrun = llrunCandidates[index - 1]
+    return resolvedLlrun
+  }
+
+  ctx.tools.register({
+    name: 'bash',
+    description: [
+      'Run commands in a bash shell (WSL Debian on Windows)',
+      '* When invoking this tool, the contents of the "command" parameter does NOT need to be XML-escaped.',
+      '* Network access depends on the task environment. Prefer configured mirrors/proxies when they are available.',
+      '* State does NOT persist across command calls: each call runs in a fresh shell.',
+      "* To inspect a particular line range of a file, e.g. lines 10-25, try 'sed -n 10,25p /path/to/the/file'.",
+      '* Please avoid commands that may produce a very large amount of output.',
+      `* Each call times out after ${Math.round(timeoutMs / 1000)}s; detach long-lived processes (e.g. 'nohup cmd >log 2>&1 &').`,
+      '* OS sandbox: in workspace-write and read-only sessions this shell runs under llrun (landlock + unix-socket masking + /var/tmp sealed; read-only additionally refuses every write). Writes outside the session workspace are denied in those modes. In danger-full-access no fence is applied.',
+      '* Do not operate on Windows files from here — that is a workaround, not the intended path. Use `write` / `edit` / `pwsh_run` for anything on the Windows side.',
+      '* Deleting files: send them to the Recycle Bin instead of a permanent delete. WSL-internal paths (/home/...) use `gio trash <path>`; /mnt/c and /mnt/d Windows files must go through `pwsh_run` with Microsoft.VisualBasic.FileIO.FileSystem SendToRecycleBin — gio trash there only creates a freedesktop dot-Trash-1000 folder per drive, which the Windows Explorer Recycle Bin cannot see or restore. Never `rm -rf` a path you have not verified.',
+    ].join('\n'),
+    parameters: commandSchema,
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: { text: { type: 'string' } },
+        required: ['text'],
+      },
+      render: (_args, value) => [{ type: 'text', text: value.text }],
+    },
+    async execute(args, exec) {
+      const signal = withTimeout(exec?.signal, timeoutMs)
+      const shell = await resolveShell(exec?.signal)
+
+      // POSIX 路径（WSL 视角）不能作为 Windows 进程 cwd；
+      // 有围栏时交给 llrun 的 `-C`（在 landlock 之后 chdir），无围栏时退化为命令内 cd。
+      const requested = typeof args.workdir === 'string' && args.workdir.length > 0 ? args.workdir : undefined
+      const posixDir = requested !== undefined && requested.startsWith('/') ? requested : undefined
+      const baseCwd = requested !== undefined && posixDir === undefined
+        ? requested
+        : await resolveCwd(ctx, exec?.agent, exec?.signal)
+
+      // 权限档。resolve 必须带 session —— 缺了它会静默退回部署默认值（workspaceRoot 指向 profile 目录）。
+      const session = exec?.agent?.session
+      const policy = ctx.get('sandboxPolicy')?.resolve(session === undefined ? {} : { session })
+      if (fenceEnabled && policy === undefined) {
+        throw new Error('bash fence requested but ctx.sandboxPolicy is absent — refusing to run unsandboxed;'
+          + ' set the `fence: false` config to accept an unbounded shell.')
+      }
+      const mode = typeof policy?.mode === 'string' ? policy.mode : undefined
+      const needFence = fenceEnabled && mode !== 'danger-full-access'
+
+      let argv
+      let script = args.command
+      if (needFence) {
+        const llrunPath = await resolveLlrun(shell, baseCwd)
+        if (llrunPath === undefined) {
+          const detail = unusableLlrun === undefined
+            ? `looked for: ${llrunCandidates.join(', ')}`
+            : `${unusableLlrun} exists but is not executable`
+          throw new Error(`bash fence is required in ${mode} mode but llrun was not found; ${detail}`
+            + ' — deploy wsl/llrun to one of them (see README), set the `llrunPath` config, or disable the fence'
+            + ' explicitly with the `fence: false` config.')
+        }
+        const workspace = toWslPath(policy?.workspaceRoot) ?? toWslPath(baseCwd) ?? '-'
+        const fenceArgs = []
+        if (mode === 'read-only') fenceArgs.push('-r')
+        if (posixDir !== undefined) fenceArgs.push('-C', shellQuote(posixDir))
+        fenceArgs.push(shellQuote(workspace), '/bin/bash', '-s')
+        argv = [shell, '-c', `exec ${llrunExecWord(llrunPath)} ${fenceArgs.join(' ')}`]
+      } else {
+        if (posixDir !== undefined) script = `cd ${shellQuote(posixDir)} && ${args.command}`
+        argv = [shell, '-s']
+      }
+
+      const handle = ctx.subprocess.spawn({
+        argv,
+        cwd: baseCwd,
+        stdio: {
+          stdin: { data: script },
+          stdout: { maxBytes: maxOutputBytes },
+          stderr: { maxBytes: maxOutputBytes },
+        },
+        signal,
+        graceMs: 3000,
+      })
+
+      let outcome
+      try {
+        outcome = await handle.done
+      } catch (error) {
+        if (signal.aborted && exec?.signal?.aborted !== true) {
+          outcome = { exitCode: null, timedOut: true }
+        } else {
+          throw new Error(`bash spawn failed: ${String(error)}`)
+        }
+      }
+
+      let stdout = ''
+      let stderr = ''
+      try {
+        stdout = handle.collected.stdout.readFrom(0).text
+        stderr = handle.collected.stderr.readFrom(0).text
+      } catch {
+        // 收集缓冲区读取失败时按「无输出」处理。
+      }
+      const body = [stdout, stderr].filter((part) => part.length > 0).join('\n')
+      const notes = []
+      if (outcome?.timedOut === true || (signal.aborted && exec?.signal?.aborted !== true)) {
+        notes.push(`[timed out after ${Math.round(timeoutMs / 1000)}s]`)
+      }
+      if (outcome?.exitCode !== undefined && outcome.exitCode !== 0) notes.push(`exit code: ${outcome.exitCode}`)
+      const text = [body, ...notes].filter((part) => part.length > 0).join('\n')
+      return { text: text.length > 0 ? text : 'exit code: 0 (no output)' }
+    },
+  })
+}