dsh-bash-terminal-ts 0.5.1 → 0.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-bash-terminal-ts",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public",

package/screenshots.json

@@ -1,5 +1,5 @@
-{
-  "screenshots": [
-    "assets/shells.png"
-  ]
-}
+{
+  "screenshots": [
+    "assets/shells.png"
+  ]
+}

package/scripts/build-client.mjs

@@ -1,4 +1,4 @@
-// Build the browser client bundle for dsh-bash-terminal.
+// Build the browser client bundle for dsh-bash-terminal-ts.
 // Output: lib/client.js (primary, consumed by DSH loader/reload precheck) and
 // dist/client.js (legacy compatibility) — a __ModuleLoader__.load({ id, factory })
 // wrapper around the esbuild CJS bundle; shared deps (react, @deepseek-ai/*)
@@ -33,7 +33,7 @@ await build({
 
 const core = readFileSync(join(root, "dist", "client.core.js"), "utf8");
 const wrapper = `window.__ModuleLoader__.load({
-	id: "dsh-bash-terminal",
+	id: "dsh-bash-terminal-ts",
 	factory: (require) => {
 		var module = { exports: {} };
 		var exports = module.exports;

package/src/client.tsx

@@ -1,4 +1,4 @@
-// dsh-bash-terminal client plugin: a "Default terminal" preference row in the
+// dsh-bash-terminal-ts client plugin: a "Default terminal" preference row in the
 // Web UI General settings, mirroring the shipped EnterBehaviorRow grammar
 // (row layout, capsule selector with chevron, --dsw-* tokens).
 //
@@ -32,7 +32,7 @@ const ROW_CSS =
   ".btChevron{flex:none}";
 if (typeof document !== "undefined" && document.querySelector("style[data-plugin-css=\"bash-terminal-row\"]") === null) {
   const tag = document.createElement("style");
-  tag.dataset.plugin = "dsh-bash-terminal";
+  tag.dataset.plugin = "dsh-bash-terminal-ts";
   tag.dataset.pluginCss = "bash-terminal-row";
   tag.textContent = ROW_CSS;
   document.head.appendChild(tag);

package/src/dsh-types.ts

@@ -294,7 +294,7 @@ export interface ApprovalSeam {
 // ---- plugin context (server side) ----------------------------------------------
 
 /**
- * The structural context face dsh-bash-terminal programs against: the union
+ * The structural context face dsh-bash-terminal-ts programs against: the union
  * of every `ctx.*` member touched by src/index.ts and src/terminal.ts.
  */
 export interface BashTerminalContext {

package/src/index.ts

@@ -1,4 +1,4 @@
-// dsh-bash-terminal - one shell tool, four Windows terminals.
+// dsh-bash-terminal-ts - one shell tool, four Windows terminals.
 //
 // Registers a model-facing shell tool. The terminal backend (powershell /
 // gitbash / msys2 / wsl) is chosen by the USER in the Web UI settings (default
@@ -321,7 +321,7 @@ function spawnSpec(resolved: SpawnResolution, argv: string[], env: Record<string
 function collectedOutput(handle: { collected: { stdout: unknown; stderr: unknown } }) {
   const { stdout, stderr } = handle.collected;
   if (!isCollectedStream(stdout) || !isCollectedStream(stderr)) {
-    throw new Error("dsh-bash-terminal: subprocess implementation dropped a requested collect stream");
+    throw new Error("dsh-bash-terminal-ts: subprocess implementation dropped a requested collect stream");
   }
   return { stdout, stderr };
 }
@@ -392,7 +392,7 @@ async function runForeground(
 function requireSubprocess(ctx: BashTerminalContext) {
   const subprocess = ctx.subprocess;
   if (subprocess === null) {
-    throw new Error("dsh-bash-terminal: ctx.subprocess seam unavailable (missing inject service)");
+    throw new Error("dsh-bash-terminal-ts: ctx.subprocess seam unavailable (missing inject service)");
   }
   return subprocess;
 }
@@ -666,14 +666,14 @@ const BACKGROUND_OUTPUT_PROPERTIES: Record<string, JsonSchemaNode> = {
 
 export function apply(ctx: BashTerminalContext, config: Partial<ConfigValues> = {}): void {
   if (process.platform !== "win32") {
-    ctx.logger?.info?.("dsh-bash-terminal: only meaningful on win32; skipping tool registration");
+    ctx.logger?.info?.("dsh-bash-terminal-ts: only meaningful on win32; skipping tool registration");
     return;
   }
   const backgroundEnabled = true;
   const paths = resolveAllPaths(config);
   const defaultShell = config.defaultShell ?? DEFAULT_SHELL;
   if (!(SHELLS as readonly string[]).includes(defaultShell)) {
-    throw new Error(`dsh-bash-terminal: invalid defaultShell ${JSON.stringify(defaultShell)}`);
+    throw new Error(`dsh-bash-terminal-ts: invalid defaultShell ${JSON.stringify(defaultShell)}`);
   }
   const settingsScope = ctx.settings.register(
     SETTINGS_NAMESPACE,
@@ -829,7 +829,7 @@ export function apply(ctx: BashTerminalContext, config: Partial<ConfigValues> =
       const shell = settingsScope.get().defaultShell;
       const argv0 = buildArgv(shell, v.command, paths, v.distro);
       if (argv0[0] === undefined) {
-        throw new Error(`dsh-bash-terminal: ${shell} backend unavailable - executable not found. Install it or set the corresponding *Path config.`);
+        throw new Error(`dsh-bash-terminal-ts: ${shell} backend unavailable - executable not found. Install it or set the corresponding *Path config.`);
       }
       // Only element 0 (the resolved executable) can be undefined; guarded above.
       const argv = argv0 as string[];

package/src/terminal.ts

@@ -1,4 +1,4 @@
-// dsh-bash-terminal: interactive terminal tool over the official PTY seam.
+// dsh-bash-terminal-ts: interactive terminal tool over the official PTY seam.
 // ctx.subprocess.spawnTerminal (node-pty under the hood) allocates a real
 // terminal; this module owns model-facing sessions: open / send / read /
 // signal (Ctrl+C etc.) / close. The backend follows the user's default

package/template/README.md

@@ -1,82 +0,0 @@
-# 终端适配模式模板
-
-把 `dsh-bash-terminal-ts` 里那套「一个 `shell` 工具、多种本地终端」的做法抽出来，供你直接复用。
-
-- [`terminal-adapter.ts`](./terminal-adapter.ts) — 四种模式已填好的适配器模块，零依赖（只用 `node:fs` / `node:path`），整份复制或只挑一种都行。
-- 本文件 — 每种模式的要点、踩过的坑，以及怎么加第五种。
-
-> **本目录已做过分发前清理**：不含作者本机路径、主机名、凭据。示例路径统一写成 `D:\workspace\your-plugin` 这类占位形式。
-> 拷进你自己仓库前，请照做一遍。
-
-## 四种模式
-
-| 模式 | 实际执行 | 语法 / 路径 | 环境变量 | 可沙箱封闭 |
-|------|----------|-------------|----------|------------|
-| `powershell`（默认） | `pwsh -NoLogo -NoProfile -NonInteractive -Command <cmd>` | PowerShell；`C:\...` | `$env:NAME` | ✅ |
-| `gitbash` | Git for Windows `bash -lc <cmd>` | POSIX；`/d/...`；PATH 含 `/usr/bin`、`/mingw64/bin` | `$NAME` | ❌ |
-| `msys2` | MSYS2 `bash -lc <cmd>`（`C:\msys64\usr\bin\bash.exe`） | POSIX；`/c/...`；PATH 含 `/usr/bin`、`/mingw64/bin`（gcc / make） | `$NAME`（自动注入 `MSYSTEM=MINGW64`） | ❌ |
-| `wsl` | `wsl [-d <distro>] -e bash -lc <cmd>` | Linux；`/mnt/d/...` | `$NAME`（经 `WSLENV`） | ❌（隔离即沙箱） |
-
-## 每种模式的要点
-
-### 1. Windows 标准模式（PowerShell）
-
-- **探测顺序**：`%ProgramFiles%\PowerShell\7\pwsh.exe` → PATH 里各目录的 `pwsh.exe` → `%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe`。PowerShell 7 优先，5.1 只作兜底。
-- **必须带 `-NonInteractive`**：否则命令里任何一处隐含提示都会把采集挂死。工具收到的是一条完整脚本，不是 REPL 会话。
-- **唯一可被沙箱封闭的模式**。走你平台的沙箱门面包装 spawn argv；封闭模式拿不到可用后端时要 **fail-closed 抛错**，不要降级成不封闭。
-
-### 2. Git Bash
-
-- **`-lc` 不是 `-c`**：`-l` 会 source `/etc/profile`，`/usr/bin`、`/mingw64/bin` 才进 PATH。用裸 `-c`，`git`、`ssh`、`tr`、`sed` 全是 command not found。
-- **必须排除 System32 的 `bash.exe`** —— 这是这套适配里最容易踩的坑。装了 WSL 的机器上 `C:\Windows\System32\bash.exe` 也存在，但它是 **WSL 转发器**，不是 Git Bash。一旦选中，Git Bash 模式的命令会被静默送进 Linux VM，`/d/...` 路径和 Git for Windows 的工具链全都不存在，而报错信息完全指不到根因。
-- **不可沙箱封闭**：DSH 的 Windows ACL restricted-token runner 起不了 Cygwin/MSYS2 进程，bash 启动阶段就 `CreateFileMapping ... Win32 error 5` 中止。硬套沙箱 = 每条命令都失败。
-- 安装位置：`%ProgramFiles%\Git\bin\bash.exe`、`%ProgramFiles%\Git\usr\bin\bash.exe`、`%LOCALAPPDATA%\Programs\Git\bin\bash.exe`（按用户安装）。
-
-### 3. MSYS2
-
-- **`-lc` 同 Git Bash**，理由一致。
-- **`MSYSTEM=MINGW64` 要自动补上**：`/etc/profile` 靠它把 `/mingw64/bin`（gcc / make）挂进 PATH。不设的话 MSYS2 落在裸 MSYS 环境，工具链整个看不见。调用方显式传了值就尊重调用方。
-- **`msys2.exe` 不能当后端**：它是分配控制台的 Cygwin 启动器，用管道 stdio spawn 出来会**退出码 0、stdout/stderr 都是零字节**——每条命令都"成功且无输出"。模板里把它留在候选表最后只作兜底，正常 `bash.exe` 永远优先。
-- **不可沙箱封闭**，原因同 Git Bash（同一套 Cygwin/MSYS2 运行时）。
-
-### 4. WSL
-
-- **`-e bash -lc <cmd>`**：`-e` 直接执行、不经额外的 shell 包装，引号能原样穿过边界。指定发行版时插 `-d <distro>`。
-- **`WSLENV` 是白名单，只能叠加、不能重建**：只有列在 `WSLENV` 里的变量才进得了 WSL。宿主本来可能已经有值（Windows Terminal 会导出 `WT_SESSION:WT_PROFILE_ID:`），重建会把这些静默丢掉，用户的终端会话变量就断了。
-- **叠加时要按 `:` 切分再拼**，不能字符串直接拼——宿主值结尾带一个 `:`，直接拼会多出一个空条目。同时要把 `WSLENV` 这个 key 自己排除，否则会再加一条无意义条目。
-- **`wsl.exe` 不用探测**：它是 Windows 组件，固定位置 `%SystemRoot%\System32\wsl.exe`，视为恒存在。
-- **它的隔离本身就是沙箱**，再包一层是多余的；如实上报 `wsl-isolation`。
-
-## 加第五种模式
-
-以加一个 `cmd.exe` 为例：
-
-1. 在 `SHELLS` 里加 id，`ShellId` 会自动带上它（`as const` 联合）。
-2. 在 `ADAPTERS` 里补一条：`label`、`summary`、`toolDescription`、`candidates()`、`configKey`、`confinable`。
-3. 在 `buildArgv` 里加一个 `case`。**保留 `default` 分支的 `never` 穷尽检查**——漏了分支会在编译期报错，而不是运行时掉进某个诡异的默认行为。
-4. 在 `buildEnv` 里加该模式需要的环境修正（有就加，没有就跳过）。
-5. 在 `confinementFor` / `shouldConfine` 里表个态：能不能封闭，不能的话上报哪个 `*-unconfined` 标签。
-6. 配置 schema 里补对应的 `*Path` 覆盖项（可为空串 = 自动探测）。
-7. 设置面板下拉里加一项，**顺序与 `SHELLS` 保持一致**。
-8. 补测试：探测顺序、argv 组装、env 修正各至少一条。
-
-## 接进 DSH
-
-模板本身不依赖 DSH，接线时用到这几个接缝：
-
-| 接缝 | 用途 |
-|------|------|
-| `ctx.subprocess.spawn` / `spawnTerminal` | 派生进程；进程树终止、SIGTERM→grace→SIGKILL、输出 spill |
-| `ctx.jobs` | 后台任务句柄（`run_in_background` / `job_output` / `job_kill`） |
-| `ctx.sandboxPolicy.resolve` | 每次调用解析当次沙箱策略 |
-| `ctx.sandbox.confine` | 仅 PowerShell 走这里；失败要 fail-closed |
-| `ctx.shellEnv.collect` | 采集要下发的环境变量 |
-| `ctx.settings` + `settings.general.item` 槽 | 「默认终端」设置行 |
-
-**设计上的一个刻意选择**：这套实现**不占用 `ctx.shell` 能力接缝**。平台自带的沙箱化 `pwsh` 工具保持原样可用，本工具是一个**额外的**、由用户选择的终端入口，两者并存。
-
-**另一条硬规矩**：终端由**用户**在 Web UI 里选，模型不能改。工具不把终端参数暴露给模型——否则「用户设定」形同虚设。
-
-## 许可
-
-与仓库一致：MIT。

package/template/terminal-adapter.ts

@@ -1,343 +0,0 @@
-// Terminal adapter templates — four Windows terminal backends, ready to copy.
-//
-// Extracted from dsh-bash-terminal-ts `src/index.ts` and sanitised for reuse:
-// no author-local paths, no host-specific values. Copy this file — or just the
-// one adapter you need — into your own DSH plugin, then wire the seams listed
-// under "Wiring into DSH" in ./README.md.
-//
-//   powershell  pwsh -NoLogo -NoProfile -NonInteractive -Command <cmd>
-//   gitbash     Git for Windows bash -lc <cmd>       POSIX; /d/... paths
-//   msys2       MSYS2 bash -lc <cmd>                 POSIX; /c/... paths, GCC/mingw64
-//   wsl         wsl [-d <distro>] -e bash -lc <cmd>  Linux; /mnt/d/... paths
-//
-// The flag choices here are not guesses: each non-obvious one was measured on
-// Windows and carries its reason inline. Read the comment before changing a
-// flag — several of them look arbitrary and are not.
-//
-// Node >= 22. No runtime dependencies beyond node:fs / node:path.
-
-import { lstatSync } from "node:fs";
-import { join } from "node:path";
-
-/** The four backends, in the order they appear in the settings dropdown. */
-export const SHELLS = ["powershell", "gitbash", "msys2", "wsl"] as const;
-export type ShellId = (typeof SHELLS)[number];
-
-/** Chosen when the user has never touched the setting. */
-export const DEFAULT_SHELL: ShellId = "powershell";
-
-/**
- * Forced into every child process. A shell tool feeds its output to a model, so
- * pagers and colour codes are pure noise: `PAGER=cat` and `NO_COLOR=1` keep the
- * captured stdout byte-for-byte the command's actual output.
- */
-export const ENV_OVERRIDES: Record<string, string> = {
-  NO_COLOR: "1",
-  TERM: "dumb",
-  PAGER: "cat",
-  GIT_PAGER: "cat"
-};
-
-// ---- executable resolution -------------------------------------------------
-
-function candidateExists(candidate: string): boolean {
-  try {
-    const stat = lstatSync(candidate);
-    return stat.isFile() || stat.isSymbolicLink();
-  } catch {
-    return false;
-  }
-}
-
-/** First candidate that exists on disk, or undefined when none does. */
-export function resolveFromCandidates(candidates: readonly string[]): string | undefined {
-  for (const candidate of candidates) {
-    if (candidateExists(candidate)) return candidate;
-  }
-  return undefined;
-}
-
-/** Well-known PowerShell install locations, then PATH entries. Newest first. */
-export function candidatePwshPaths(env: NodeJS.ProcessEnv = process.env): string[] {
-  const programFiles = env.ProgramFiles ?? "C:\\Program Files";
-  const systemRoot = env.SystemRoot ?? "C:\\Windows";
-  // PowerShell 7 first: pwsh.exe is the cross-platform one and is what the
-  // -NoLogo/-NoProfile/-NonInteractive flag set is written against.
-  const candidates = [join(programFiles, "PowerShell", "7", "pwsh.exe")];
-  for (const entry of (env.PATH ?? "").split(";")) {
-    const trimmed = entry.trim().replace(/^"|"$/g, "");
-    if (trimmed.length === 0) continue;
-    candidates.push(join(trimmed, "pwsh.exe"));
-  }
-  // Windows PowerShell 5.1 as the floor — present on every Windows install.
-  candidates.push(join(systemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe"));
-  return candidates;
-}
-
-/**
- * Git for Windows locations, then PATH `bash.exe` entries EXCLUDING the
- * System32 launcher.
- *
- * That exclusion is the whole point of this function: `C:\Windows\System32\
- * bash.exe` also exists on machines with WSL and is the **WSL forwarder**, not
- * a Git Bash shell. Picking it up silently sends Git Bash commands into a Linux
- * VM, where `/d/...` paths and the Git for Windows toolchain do not exist.
- */
-export function candidateGitBashPaths(env: NodeJS.ProcessEnv = process.env): string[] {
-  const programFiles = env.ProgramFiles ?? "C:\\Program Files";
-  const systemRoot = (env.SystemRoot ?? "C:\\Windows").toLowerCase();
-  const localAppData = env.LOCALAPPDATA ?? "";
-  const candidates = [
-    join(programFiles, "Git", "bin", "bash.exe"),
-    // usr\bin\bash.exe is the MSYS-rooted twin; some installs only expose this one.
-    join(programFiles, "Git", "usr", "bin", "bash.exe")
-  ];
-  // Per-user installs land here.
-  if (localAppData.length > 0) candidates.push(join(localAppData, "Programs", "Git", "bin", "bash.exe"));
-  for (const entry of (env.PATH ?? "").split(";")) {
-    const trimmed = entry.trim().replace(/^"|"$/g, "");
-    if (trimmed.length === 0) continue;
-    if (trimmed.toLowerCase().includes(systemRoot)) continue; // ← the WSL forwarder
-    candidates.push(join(trimmed, "bash.exe"));
-  }
-  return candidates;
-}
-
-/**
- * MSYS2 locations, in preference order: the real `bash.exe` under usr\bin
- * first, then bin\bash.exe, and `msys2.exe` dead last.
- *
- * `msys2.exe` is NOT a usable backend for piped execution. It is the
- * console-allocating Cygwin launcher: spawned with piped stdio it returns exit
- * 0 with zero bytes on both stdout and stderr, so every command looks like it
- * succeeded and printed nothing. It stays in the list only as a last resort;
- * a working `bash.exe` always wins.
- */
-export function candidateMsys2Paths(env: NodeJS.ProcessEnv = process.env): string[] {
-  const candidates = [
-    "C:\\msys64\\usr\\bin\\bash.exe",
-    "C:\\msys64\\bin\\bash.exe"
-  ];
-  for (const entry of (env.PATH ?? "").split(";")) {
-    const trimmed = entry.trim().replace(/^"|"$/g, "");
-    if (trimmed.length === 0) continue;
-    const lower = trimmed.toLowerCase();
-    if (lower.includes("msys64") || lower.includes("mingw64")) {
-      candidates.push(join(trimmed, "bash.exe"));
-    }
-  }
-  candidates.push("C:\\msys64\\msys2.exe"); // last resort — see the note above
-  return candidates;
-}
-
-/** `wsl.exe` always ships at this fixed location; it is never "not installed". */
-export function defaultWslPath(env: NodeJS.ProcessEnv = process.env): string {
-  const systemRoot = env.SystemRoot ?? "C:\\Windows";
-  return join(systemRoot, "System32", "wsl.exe");
-}
-
-export interface ResolvedPaths {
-  pwsh?: string;
-  gitbash?: string;
-  msys2?: string;
-  wsl?: string;
-}
-
-/** Per-backend executable overrides; an empty string means "auto-detect". */
-export interface PathConfig {
-  pwshPath?: string;
-  gitBashPath?: string;
-  msys2Path?: string;
-  wslPath?: string;
-}
-
-/**
- * Resolve all four executables. A backend resolves to `undefined` when it is
- * not installed — surface that as a loud per-call error rather than a silent
- * fallback to another shell, or the user's explicit choice gets ignored.
- */
-export function resolveAllPaths(config: PathConfig = {}, env: NodeJS.ProcessEnv = process.env): ResolvedPaths {
-  const pick = (override: string | undefined, candidates: readonly string[]): string | undefined =>
-    override !== undefined && override.trim().length > 0 ? override : resolveFromCandidates(candidates);
-  return {
-    pwsh: pick(config.pwshPath, candidatePwshPaths(env)),
-    gitbash: pick(config.gitBashPath, candidateGitBashPaths(env)),
-    msys2: pick(config.msys2Path, candidateMsys2Paths(env)),
-    // wsl.exe is not probed: it is a Windows component, so treat it as present.
-    wsl: config.wslPath !== undefined && config.wslPath.trim().length > 0 ? config.wslPath : defaultWslPath(env)
-  };
-}
-
-// ---- argv construction -----------------------------------------------------
-
-/** Prepend the backend-specific command flags. `command` always goes last. */
-export function buildArgv(
-  shell: ShellId,
-  command: string,
-  paths: ResolvedPaths,
-  distro?: string
-): Array<string | undefined> {
-  switch (shell) {
-    case "powershell":
-      // -NonInteractive so a stray prompt can never hang the capture; the
-      // model's command is one complete script, not a REPL session.
-      return [paths.pwsh, "-NoLogo", "-NoProfile", "-NonInteractive", "-Command", command];
-    case "gitbash":
-      // -l (login shell) matters: it sources /etc/profile, which is what puts
-      // /usr/bin and /mingw64/bin on PATH. With a bare -c, `git`, `ssh` and
-      // friends are "command not found".
-      return [paths.gitbash, "-lc", command];
-    case "msys2":
-      // Same -l reasoning as gitbash, and it also picks up /etc/profile's
-      // MSYSTEM handling that puts gcc/make on PATH.
-      return [paths.msys2, "-lc", command];
-    case "wsl": {
-      const distroArg = distro !== undefined && distro.trim().length > 0 ? ["-d", distro.trim()] : [];
-      // `-e bash -lc` — not `wsl bash -lc`: `-e` runs the command directly and
-      // without a shell wrapper, so quoting survives intact.
-      return [paths.wsl, ...distroArg, "-e", "bash", "-lc", command];
-    }
-    default: {
-      const exhaustive: never = shell;
-      throw new Error(`invalid shell: ${JSON.stringify(exhaustive)} (expected one of ${SHELLS.join(", ")})`);
-    }
-  }
-}
-
-// ---- environment -----------------------------------------------------------
-
-/**
- * Merge the host environment with per-backend fixups.
- *
- * @param inheritedWslenv - the ambient WSLENV to layer onto. Callers that
- *   replace the child environment wholesale (a PTY path, say) must pass
- *   `process.env.WSLENV` explicitly, because the ambient value is not visible
- *   through `dshEnv`.
- */
-export function buildEnv(
-  shell: ShellId,
-  hostEnv?: Record<string, string>,
-  inheritedWslenv: string | undefined = process.env.WSLENV
-): Record<string, string | undefined> {
-  const env: Record<string, string | undefined> = { ...ENV_OVERRIDES, ...hostEnv };
-  if (shell === "msys2") {
-    // Selects the MINGW64 environment, so /mingw64/bin (gcc, make, ...) joins
-    // PATH via /etc/profile. Without it MSYS2 defaults to the bare MSYS
-    // environment and the toolchain is invisible. An explicit caller value wins.
-    if (env.MSYSTEM === undefined) env.MSYSTEM = "MINGW64";
-  }
-  if (shell === "wsl") {
-    const keys = Object.keys(hostEnv ?? {});
-    if (keys.length > 0) {
-      // WSLENV is an allow-list: only the variables named in it cross into WSL.
-      // LAYER onto the inherited value, never rebuild it — dropping inherited
-      // entries (Windows Terminal exports e.g. `WT_SESSION:WT_PROFILE_ID:`)
-      // would silently stop them crossing.
-      //
-      // The base is SPLIT on ":" rather than concatenated because the host
-      // value ends with a trailing ":", so string concatenation would produce a
-      // malformed empty entry.
-      const declared = Object.prototype.hasOwnProperty.call(hostEnv ?? {}, "WSLENV");
-      const base = declared
-        ? env.WSLENV
-        : (typeof inheritedWslenv === "string" && inheritedWslenv.length > 0 ? inheritedWslenv : env.WSLENV);
-      const parts = typeof base === "string" ? base.split(":") : [];
-      env.WSLENV = [...parts, ...keys.filter((k) => k !== "WSLENV").flatMap((k) => k.split(":"))]
-        .map((p) => p.trim())
-        .filter((p) => p.length > 0)
-        .join(":");
-    }
-  }
-  return env;
-}
-
-// ---- sandbox confinement ---------------------------------------------------
-
-export type SandboxMode = "read-only" | "workspace-write" | "danger-full-access";
-
-/**
- * Whether a backend can be wrapped by your sandbox seam, and what to report
- * when it cannot.
- *
- * Only PowerShell is confinable on Windows. Git Bash and MSYS2 must NOT be
- * wrapped: DSH's Windows ACL restricted-token runner cannot start a
- * Cygwin/MSYS2 process — bash aborts during startup with
- * `CreateFileMapping ... Win32 error 5` — so wrapping them would abort every
- * command instead of confining it. WSL is its own Linux VM; that isolation IS
- * the sandbox, so wrapping it is redundant.
- *
- * Publish this honestly: report `*-unconfined` rather than claiming a
- * confinement that did not happen.
- */
-export function confinementFor(mode: SandboxMode, shell: ShellId): string {
-  if (shell === "wsl") return "wsl-isolation";
-  if (shell === "gitbash") return "gitbash-unconfined";
-  if (shell === "msys2") return "msys2-unconfined";
-  return mode === "danger-full-access" ? "none" : "powershell-confined";
-}
-
-/** True when the spawn argv must be passed through the sandbox facade. */
-export function shouldConfine(mode: SandboxMode, shell: ShellId): boolean {
-  return mode !== "danger-full-access" && shell === "powershell";
-}
-
-// ---- the adapter table -----------------------------------------------------
-
-export interface TerminalAdapter {
-  readonly id: ShellId;
-  /** Shown in the settings dropdown. */
-  readonly label: string;
-  /** One line describing the backend, suitable for a settings-row caption. */
-  readonly summary: string;
-  /** Model-facing tool description when this backend is active. */
-  readonly toolDescription: string;
-  /** Candidate executables, best first. */
-  candidates(env?: NodeJS.ProcessEnv): string[];
-  /** Path key in your config schema, or undefined when there is nothing to override. */
-  readonly configKey?: keyof PathConfig;
-  /** Whether this backend's spawn argv may be confined. */
-  readonly confinable: boolean;
-}
-
-export const ADAPTERS: Record<ShellId, TerminalAdapter> = {
-  powershell: {
-    id: "powershell",
-    label: "PowerShell",
-    summary: "PowerShell 7 (pwsh), the Windows default",
-    toolDescription:
-      "Execute a PowerShell command (pwsh -NoLogo -NoProfile -NonInteractive -Command <command>) and return its stdout/stderr. PowerShell syntax; native Windows paths (C:\\...); environment variables via $env:NAME.",
-    candidates: candidatePwshPaths,
-    configKey: "pwshPath",
-    confinable: true
-  },
-  gitbash: {
-    id: "gitbash",
-    label: "Git Bash",
-    summary: "Git for Windows bash — POSIX syntax, /d/... paths",
-    toolDescription:
-      "Execute a bash command (Git for Windows bash -lc <command>) and return its stdout/stderr. POSIX syntax; paths like /d/workspace; PATH includes /usr/bin and /mingw64/bin so git, npm, ssh etc. work; environment variables via $NAME.",
-    candidates: candidateGitBashPaths,
-    configKey: "gitBashPath",
-    confinable: false
-  },
-  msys2: {
-    id: "msys2",
-    label: "MSYS2",
-    summary: "MSYS2 bash — POSIX syntax, /c/... paths, full GCC/mingw64 toolchain",
-    toolDescription:
-      "Execute a bash command (MSYS2 bash -lc <command>) and return its stdout/stderr. POSIX syntax; paths like /c/...; PATH includes /usr/bin and /mingw64/bin so git, npm, gcc, make etc. work; environment variables via $NAME. MSYS2 provides a full GCC/mingw64 toolchain.",
-    candidates: candidateMsys2Paths,
-    configKey: "msys2Path",
-    confinable: false
-  },
-  wsl: {
-    id: "wsl",
-    label: "WSL",
-    summary: "WSL Linux — /mnt/d/... paths, optional distro",
-    toolDescription:
-      "Execute a bash command in WSL (wsl [-d <distro>] -e bash -lc <command>) and return its stdout/stderr. Linux syntax; paths like /mnt/d/workspace; environment variables via $NAME (crossing the boundary through WSLENV).",
-    candidates: (env = process.env) => [defaultWslPath(env)],
-    configKey: "wslPath",
-    confinable: false
-  }
-};