dsh-bash-terminal-ts 0.5.0 → 0.6.0

package/README.en.md

@@ -20,7 +20,7 @@ A DeepSeek Harness (DSH) plugin: one `shell` tool that runs commands through **P
 | Backend | Runs | Syntax / paths | Env vars |
 |---------|------|----------------|----------|
 | `powershell` (default) | `pwsh -NoLogo -NoProfile -NonInteractive -Command <cmd>` | PowerShell; `C:\\...` | `$env:NAME` |
-| `gitbash` | Git for Windows `bash -lc <cmd>` | POSIX; `/d/WorkSpace`; PATH includes `/usr/bin` and `/mingw64/bin` | `$NAME` |
+| `gitbash` | Git for Windows `bash -lc <cmd>` | POSIX; `/d/workspace`; PATH includes `/usr/bin` and `/mingw64/bin` | `$NAME` |
 | `msys2` | MSYS2 `bash -lc <cmd>` (`C:\msys64\usr\bin\bash.exe`) | POSIX; `/c/...`; PATH includes `/usr/bin` and `/mingw64/bin` (gcc / make) | `$NAME` (MSYSTEM=MINGW64 injected) |
 | `wsl` | `wsl [-d <distro>] -e bash -lc <cmd>` | Linux; `/mnt/d/...` | `$NAME` (via WSLENV) |
 
@@ -29,6 +29,12 @@ A DeepSeek Harness (DSH) plugin: one `shell` tool that runs commands through **P
 - **Interactive terminal**: the `terminal` tool opens persistent real-PTY sessions over node-pty — on non-Windows via the official `ctx.subprocess.spawnTerminal` seam, on Windows directly through node-pty because the upstream seam's process inspector is POSIX-only. Actions `open` / `send` / `read` / `signal` / `close`; shell state persists across calls; sessions are managed as background jobs and auto-close when idle.
 - **Background execution** via the generic jobs registry (`run_in_background` / `job_output` / `job_kill`).
 
+## Screenshots
+
+The **Default terminal** row in Settings -> General: the user picks PowerShell / Git Bash / MSYS2 / WSL, and the `shell` tool obeys that choice — the model cannot override it.
+
+![Default terminal setting row](assets/shells.png)
+
 ## Install
 
 The package ships the official `dsh.bundle` manifest (its own `cordis.patch.yml`): listing `dsh-bash-terminal` in a profile's `dsh.profile.bundles` auto-applies the mount — no manual profile edits.

package/README.md

@@ -18,12 +18,18 @@ DSH（DeepSeek Harness）插件：一个 `shell` 工具，在 Windows 上统一
 | 后端 | 实际执行 | 语法 / 路径 | 环境变量 |
 |------|----------|-------------|----------|
 | `powershell`（默认） | `pwsh -NoLogo -NoProfile -NonInteractive -Command <cmd>` | PowerShell；`C:\...` | `$env:NAME` |
-| `gitbash` | Git for Windows `bash -lc <cmd>` | POSIX；`/d/WorkSpace`；PATH 含 `/usr/bin`、`/mingw64/bin` | `$NAME` |
+| `gitbash` | Git for Windows `bash -lc <cmd>` | POSIX；`/d/workspace`；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） |
 
 每次调用都启动全新 shell：**不保留状态**（cwd / 变量 / 别名）——请传 `workdir` 而不是用 `cd`。
 
+## 界面预览
+
+设置 → 通用 里的「默认终端」行：用户在 PowerShell / Git Bash / MSYS2 / WSL 之间选择，`shell` 工具只按这个设置执行，模型无法覆盖：
+
+![默认终端设置行](assets/shells.png)
+
 ## 设计要点
 
 - **终端由用户决定，AI 无法更改**：Web UI 设置页（设置 → 通用）出现"默认终端"下拉（PowerShell / Git Bash / MSYS2 / WSL）；`shell` 工具永远只使用该设置，不暴露终端参数给模型。设置通过 DSH settings 系统持久化（settings.yaml）。
@@ -56,14 +62,14 @@ powershell -ExecutionPolicy Bypass -File install.ps1 install
 ```powershell
 # 1. 链接插件包到 profile 的 node_modules（junction，改源码即时生效）
 $profile = "$env:USERPROFILE\.dsh\profiles\web"
-New-Item -ItemType Junction -Path "$profile\node_modules\dsh-bash-terminal" -Target "D:\WorkSpace\projects\dsh-bash-terminal" | Out-Null
+New-Item -ItemType Junction -Path "$profile\node_modules\dsh-bash-terminal" -Target "D:\workspace\projects\dsh-bash-terminal" | Out-Null
 
 # 2. 让插件能解析 @deepseek-ai/* 依赖（junction 到 profile 的依赖树，插件与宿主共用同一份模块实例）
-New-Item -ItemType Junction -Path "D:\WorkSpace\projects\dsh-bash-terminal\node_modules\@deepseek-ai" -Target "$profile\..\node_modules\@deepseek-ai" | Out-Null
+New-Item -ItemType Junction -Path "D:\workspace\projects\dsh-bash-terminal\node_modules\@deepseek-ai" -Target "$profile\..\node_modules\@deepseek-ai" | Out-Null
 
 # 3. 让 profile 通过官方 bundle 挂载插件（install.ps1 install 会自动做；等价于在 dsh.profile.bundles 加 "dsh-bash-terminal"）
 # 4. （仅修改前端源码后）重新打包 client bundle:
-#    cd D:\WorkSpace\projects\dsh-bash-terminal && node scripts/build-client.mjs
+#    cd D:\workspace\projects\dsh-bash-terminal && node scripts/build-client.mjs
 # 5. 重启 dsh web
 ```
 
@@ -83,7 +89,7 @@ New-Item -ItemType Junction -Path "D:\WorkSpace\projects\dsh-bash-terminal\node_
 验证组合树（无需重启）：
 
 ```powershell
-node "$env:APPDATA\nvm\v24.16.0\node_modules\@deepseek-ai\dsh\lib\bin.js" --profile web --dump-config | Select-String dsh-bash-terminal
+node "$env:APPDATA\nvm\<node-version>\node_modules\@deepseek-ai\dsh\lib\bin.js" --profile web --dump-config | Select-String dsh-bash-terminal
 ```
 
 ## 使用
@@ -94,7 +100,7 @@ node "$env:APPDATA\nvm\v24.16.0\node_modules\@deepseek-ai\dsh\lib\bin.js" --prof
 
 - 默认终端 = Git Bash 时：`shell(command: "git status")` 走 Git Bash
 - 默认终端 = MSYS2 时：`shell(command: "gcc --version")` 走 MSYS2（MINGW64 环境，`/mingw64/bin` 的 gcc、make 可用）
-- 默认终端 = WSL 时：`shell(command: "ls -la /mnt/d/WorkSpace")` 走 WSL；传 `distro: "Ubuntu"` 可指定发行版
+- 默认终端 = WSL 时：`shell(command: "ls -la /mnt/d/workspace")` 走 WSL；传 `distro: "Ubuntu"` 可指定发行版
 - 默认终端 = PowerShell 时：`shell(command: "Get-Process node")` 走 PowerShell
 
 ## 模型使用示例
@@ -126,7 +132,7 @@ node "$env:APPDATA\nvm\v24.16.0\node_modules\@deepseek-ai\dsh\lib\bin.js" --prof
 npm 账号已启用 2FA 发布验证，需一次性验证码：
 
 ```powershell
-cd D:\WorkSpace\projects\dsh-bash-terminal
+cd D:\workspace\projects\dsh-bash-terminal
 npm publish --otp <验证码>   # 验证码来自你的认证器
 ```
 
@@ -188,7 +194,7 @@ powershell -ExecutionPolicy Bypass -File install.ps1 uninstall
 ## 测试
 
 ```powershell
-cd D:\WorkSpace\projects\dsh-bash-terminal
+cd D:\workspace\projects\dsh-bash-terminal
 npm install          # 安装依赖（含 typescript）
 npm run build        # tsc 编译 src/*.ts → lib/*.js；client.tsx → lib/client.js + dist/client.js；test/*.ts → test-dist/
 npm test             # node test-dist/unit.js → apply.js → client.js → terminal.js

package/dist/client.core.js

@@ -28,7 +28,7 @@ var import_dsh_client_store = require("@deepseek-ai/dsh-client-store");
 var import_dsh_client_ui_primitives = require("@deepseek-ai/dsh-client-ui-primitives");
 var import_jsx_runtime = require("react/jsx-runtime");
 var SETTINGS_NS = "settings.bash-terminal";
-var SETTINGS_NAMESPACE = "bash-terminal";
+var ENTRY_ID = "tool-bash-terminal";
 var SHELLS = ["powershell", "gitbash", "msys2", "wsl"];
 var ROW_CSS = ".btRow{border-bottom:1px solid var(--dsw-alias-border-l2);align-items:center;gap:8px;padding:16px 0;display:flex}.btRowText{flex-direction:column;flex:1;gap:4px;min-width:0;padding-right:48px;display:flex}.btTitle{color:var(--dsw-alias-label-primary);font-size:14px;font-weight:400;line-height:22px}.btDesc{color:var(--dsw-alias-label-tertiary);font-size:12px;font-weight:400;line-height:18px}.btSelector{background:var(--dsw-alias-bg-module-platform);height:36px;font:inherit;color:var(--dsw-alias-label-primary);cursor:pointer;border:none;border-radius:18px;align-items:center;gap:12px;padding:0 14px;font-size:14px;line-height:22px;display:inline-flex}.btSelector:hover{background:var(--dsw-alias-interactive-bg-hover)}.btChevron{flex:none}";
 if (typeof document !== "undefined" && document.querySelector('style[data-plugin-css="bash-terminal-row"]') === null) {
@@ -54,7 +54,7 @@ var en = {
   "shell.msys2": "MSYS2",
   "shell.wsl": "WSL"
 };
-var inject = ["slots", "locale", "settingsScope"];
+var inject = ["slots", "locale", "configForms"];
 function ShellPreferenceRow({ t, useStore, setShell }) {
   const shell = useStore((s) => s.shell);
   const writable = useStore((s) => s.writable);
@@ -100,7 +100,7 @@ function ShellPreferenceRow({ t, useStore, setShell }) {
 }
 function apply(ctx) {
   ctx.effect(() => ctx.locale.register(SETTINGS_NS, { zh, en }), "bash-terminal: settings dictionaries");
-  const scope = ctx.settingsScope.bind({ namespace: SETTINGS_NAMESPACE });
+  const scope = ctx.configForms.get(ENTRY_ID);
   const store = (0, import_dsh_client_store.defineStore)({
     init: () => ({ shell: "powershell", revision: -1, writable: false }),
     actions: {

package/dist/client.js

@@ -33,7 +33,7 @@ var import_dsh_client_store = require("@deepseek-ai/dsh-client-store");
 var import_dsh_client_ui_primitives = require("@deepseek-ai/dsh-client-ui-primitives");
 var import_jsx_runtime = require("react/jsx-runtime");
 var SETTINGS_NS = "settings.bash-terminal";
-var SETTINGS_NAMESPACE = "bash-terminal";
+var ENTRY_ID = "tool-bash-terminal";
 var SHELLS = ["powershell", "gitbash", "msys2", "wsl"];
 var ROW_CSS = ".btRow{border-bottom:1px solid var(--dsw-alias-border-l2);align-items:center;gap:8px;padding:16px 0;display:flex}.btRowText{flex-direction:column;flex:1;gap:4px;min-width:0;padding-right:48px;display:flex}.btTitle{color:var(--dsw-alias-label-primary);font-size:14px;font-weight:400;line-height:22px}.btDesc{color:var(--dsw-alias-label-tertiary);font-size:12px;font-weight:400;line-height:18px}.btSelector{background:var(--dsw-alias-bg-module-platform);height:36px;font:inherit;color:var(--dsw-alias-label-primary);cursor:pointer;border:none;border-radius:18px;align-items:center;gap:12px;padding:0 14px;font-size:14px;line-height:22px;display:inline-flex}.btSelector:hover{background:var(--dsw-alias-interactive-bg-hover)}.btChevron{flex:none}";
 if (typeof document !== "undefined" && document.querySelector('style[data-plugin-css="bash-terminal-row"]') === null) {
@@ -59,7 +59,7 @@ var en = {
   "shell.msys2": "MSYS2",
   "shell.wsl": "WSL"
 };
-var inject = ["slots", "locale", "settingsScope"];
+var inject = ["slots", "locale", "configForms"];
 function ShellPreferenceRow({ t, useStore, setShell }) {
   const shell = useStore((s) => s.shell);
   const writable = useStore((s) => s.writable);
@@ -105,7 +105,7 @@ function ShellPreferenceRow({ t, useStore, setShell }) {
 }
 function apply(ctx) {
   ctx.effect(() => ctx.locale.register(SETTINGS_NS, { zh, en }), "bash-terminal: settings dictionaries");
-  const scope = ctx.settingsScope.bind({ namespace: SETTINGS_NAMESPACE });
+  const scope = ctx.configForms.get(ENTRY_ID);
   const store = (0, import_dsh_client_store.defineStore)({
     init: () => ({ shell: "powershell", revision: -1, writable: false }),
     actions: {

package/lib/client.js

@@ -33,7 +33,7 @@ var import_dsh_client_store = require("@deepseek-ai/dsh-client-store");
 var import_dsh_client_ui_primitives = require("@deepseek-ai/dsh-client-ui-primitives");
 var import_jsx_runtime = require("react/jsx-runtime");
 var SETTINGS_NS = "settings.bash-terminal";
-var SETTINGS_NAMESPACE = "bash-terminal";
+var ENTRY_ID = "tool-bash-terminal";
 var SHELLS = ["powershell", "gitbash", "msys2", "wsl"];
 var ROW_CSS = ".btRow{border-bottom:1px solid var(--dsw-alias-border-l2);align-items:center;gap:8px;padding:16px 0;display:flex}.btRowText{flex-direction:column;flex:1;gap:4px;min-width:0;padding-right:48px;display:flex}.btTitle{color:var(--dsw-alias-label-primary);font-size:14px;font-weight:400;line-height:22px}.btDesc{color:var(--dsw-alias-label-tertiary);font-size:12px;font-weight:400;line-height:18px}.btSelector{background:var(--dsw-alias-bg-module-platform);height:36px;font:inherit;color:var(--dsw-alias-label-primary);cursor:pointer;border:none;border-radius:18px;align-items:center;gap:12px;padding:0 14px;font-size:14px;line-height:22px;display:inline-flex}.btSelector:hover{background:var(--dsw-alias-interactive-bg-hover)}.btChevron{flex:none}";
 if (typeof document !== "undefined" && document.querySelector('style[data-plugin-css="bash-terminal-row"]') === null) {
@@ -59,7 +59,7 @@ var en = {
   "shell.msys2": "MSYS2",
   "shell.wsl": "WSL"
 };
-var inject = ["slots", "locale", "settingsScope"];
+var inject = ["slots", "locale", "configForms"];
 function ShellPreferenceRow({ t, useStore, setShell }) {
   const shell = useStore((s) => s.shell);
   const writable = useStore((s) => s.writable);
@@ -105,7 +105,7 @@ function ShellPreferenceRow({ t, useStore, setShell }) {
 }
 function apply(ctx) {
   ctx.effect(() => ctx.locale.register(SETTINGS_NS, { zh, en }), "bash-terminal: settings dictionaries");
-  const scope = ctx.settingsScope.bind({ namespace: SETTINGS_NAMESPACE });
+  const scope = ctx.configForms.get(ENTRY_ID);
   const store = (0, import_dsh_client_store.defineStore)({
     init: () => ({ shell: "powershell", revision: -1, writable: false }),
     actions: {

package/lib/dsh-types.d.ts

@@ -250,7 +250,6 @@ export interface BashTerminalContext {
     tools: ToolsSeam;
     on(event: "system-prompt/assemble", handler: AssembleHandler): void;
     shellEnv: ShellEnvSeam;
-    settings: SettingsSeam;
     sandboxPolicy: SandboxPolicySeam;
     sandbox: SandboxSeam;
     get(key: string): unknown;

package/lib/dsh.d.ts

@@ -20,6 +20,8 @@ export declare const escalationHintMarker: (subject: string) => string;
 /** Runtime config schema factory (schemastery fork). */
 export interface SchemasterySchema {
     default(value: unknown): SchemasterySchema;
+    /** 0.1.7+: expose the field on the auto-generated settings form. */
+    volatile(): SchemasterySchema;
 }
 export interface Schemastery {
     object(fields: Record<string, SchemasterySchema>): SchemasterySchema;

package/lib/index.d.ts

@@ -7,8 +7,6 @@ export declare const inject: string[];
 export declare const SHELLS: readonly ["powershell", "gitbash", "msys2", "wsl"];
 /** The backend used when the caller does not name one. */
 export declare const DEFAULT_SHELL: ShellId;
-/** Settings namespace backing the user-chosen default terminal. */
-export declare const SETTINGS_NAMESPACE = "bash-terminal";
 /** Static shape of the runtime configuration schema. */
 export interface ConfigValues {
     defaultShell: string;

package/lib/index.js

@@ -33,8 +33,6 @@ export const inject = ["tools", "systemPrompt", "shellEnv", "subprocess", "setti
 export const SHELLS = ["powershell", "gitbash", "msys2", "wsl"];
 /** The backend used when the caller does not name one. */
 export const DEFAULT_SHELL = "powershell";
-/** Settings namespace backing the user-chosen default terminal. */
-export const SETTINGS_NAMESPACE = "bash-terminal";
 /** Default per-command timeout (ms). */
 const DEFAULT_TIMEOUT_MS = 120000;
 /** Upper bound a caller's timeoutMs is capped to. */
@@ -56,7 +54,7 @@ const ENV_OVERRIDES = {
 };
 /** Runtime configuration schema. */
 export const Config = z.object({
-    defaultShell: z.string().default(DEFAULT_SHELL),
+    defaultShell: z.string().default(DEFAULT_SHELL).volatile(),
     timeoutMs: z.number().default(DEFAULT_TIMEOUT_MS),
     maxTimeoutMs: z.number().default(MAX_TIMEOUT_MS),
     pwshPath: z.string().default(""),
@@ -500,11 +498,19 @@ export function apply(ctx, config = {}) {
     }
     const backgroundEnabled = true;
     const paths = resolveAllPaths(config);
-    const defaultShell = config.defaultShell ?? DEFAULT_SHELL;
-    if (!SHELLS.includes(defaultShell)) {
-        throw new Error(`dsh-bash-terminal: invalid defaultShell ${JSON.stringify(defaultShell)}`);
+    // 0.1.7: `defaultShell` is a `.volatile()` config field — the loader hands
+    // `apply` a live ref and the latest value is resolved on every read; there
+    // is no settings registration call anymore (removed with the 0.1.7 host).
+    const currentShell = () => {
+        const v = config.defaultShell;
+        if (typeof v === "string")
+            return v;
+        const got = typeof v?.get === "function" ? v.get() : undefined;
+        return typeof got === "string" ? got : DEFAULT_SHELL;
+    };
+    if (!SHELLS.includes(currentShell())) {
+        throw new Error(`dsh-bash-terminal: invalid defaultShell ${JSON.stringify(currentShell())}`);
     }
-    const settingsScope = ctx.settings.register(SETTINGS_NAMESPACE, z.object({ defaultShell: z.union(SHELLS.map((s) => z.const(s))).default(defaultShell) }), { base: { defaultShell } });
     /** Official sandbox-escalation surface (mirrors tool-bash): advertise the
      * escalation modes whenever the deployment confines. */
     const escalationModes = ESCALATION_TARGETS;
@@ -529,7 +535,7 @@ export function apply(ctx, config = {}) {
     });
     const toolName = "shell";
     const terminalRegistry = createTerminalRegistry(ctx);
-    ctx.tools.register(terminalTool(ctx, terminalRegistry, paths, () => settingsScope.get().defaultShell));
+    ctx.tools.register(terminalTool(ctx, terminalRegistry, paths, () => currentShell()));
     // The model-facing description must track the user's chosen default
     // terminal: a static description listing every backend leaves the model
     // guessing which syntax applies. Re-render it on every prompt assembly —
@@ -537,7 +543,7 @@ export function apply(ctx, config = {}) {
     // without a restart.
     ctx.on("system-prompt/assemble", async (_assembly, _context, next) => {
         const assembled = await next();
-        const description = toolDescription(backgroundEnabled, settingsScope.get().defaultShell);
+        const description = toolDescription(backgroundEnabled, currentShell());
         const tools = Array.isArray(assembled.tools)
             ? assembled.tools.map((tool) => (tool.name === toolName ? { ...tool, description } : tool))
             : assembled.tools;
@@ -545,7 +551,7 @@ export function apply(ctx, config = {}) {
     });
     ctx.tools.register(defineTool({
         name: toolName,
-        description: toolDescription(backgroundEnabled, settingsScope.get().defaultShell),
+        description: toolDescription(backgroundEnabled, currentShell()),
         parameters: {
             command: {
                 type: "string",
@@ -644,7 +650,7 @@ export function apply(ctx, config = {}) {
         },
         async execute(args, exec) {
             const v = validateArgs(args);
-            const shell = settingsScope.get().defaultShell;
+            const shell = currentShell();
             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.`);

package/package.json

@@ -1,116 +1,115 @@
-{
-  "name": "dsh-bash-terminal-ts",
-  "version": "0.5.0",
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org",
-    "access": "public",
-    "tag": "dsh-0.1.5"
-  },
-  "description": "DSH plugin: one shell tool that runs commands through PowerShell, Git Bash, MSYS2, or WSL on Windows, with a user-chosen default terminal in the Web UI settings. TypeScript rewrite of MAXeaglet/dsh-bash-terminal with working MSYS2/MINGW64 support.",
-  "author": "drscrewdriver",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/drscrewdriver/dsh-bash-terminal-ts.git"
-  },
-  "bugs": {
-    "url": "https://github.com/drscrewdriver/dsh-bash-terminal-ts/issues"
-  },
-  "homepage": "https://github.com/drscrewdriver/dsh-bash-terminal-ts#readme",
-  "keywords": [
-    "deepseek-harness",
-    "dsh",
-    "plugin",
-    "terminal",
-    "shell",
-    "powershell",
-    "git-bash",
-    "wsl",
-    "windows",
-    "typescript"
-  ],
-  "engines": {
-    "node": ">=22",
-    "dsh": ">=0.1.5-alpha.1 <0.2.0-0"
-  },
-  "type": "module",
-  "main": "lib/index.js",
-  "exports": {
-    ".": "./lib/index.js",
-    "./client": "./lib/client.js",
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "lib",
-    "dist",
-    "src",
-    "scripts",
-    "tsconfig.json",
-    "tsconfig.client.json",
-    "tsconfig.test.json",
-    "README.md",
-    "LICENSE",
-    "cordis.patch.yml",
-    "dsh.plugin.json",
-    "screenshots.json"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json && tsc -p tsconfig.client.json && node scripts/build-client.mjs && tsc -p tsconfig.test.json",
-    "build:client": "node scripts/build-client.mjs",
-    "test": "node test-dist/unit.js && node test-dist/apply.js && node test-dist/client.js && node test-dist/terminal.js"
-  },
-  "dsh": {
-    "bundle": {
-      "patch": "./cordis.patch.yml"
-    },
-    "client": {
-      "platform": "web",
-      "immediately": true,
-      "inject": [
-        "@deepseek-ai/dsh-client-locale",
-        "@deepseek-ai/dsh-client-ui-settings",
-        "@deepseek-ai/dsh-api-remotes"
-      ]
-    }
-  },
-  "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-tools": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-settings": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-llm": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-shell": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-sandbox": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-timeout": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-client-store": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-client-locale": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.5-rc.1",
-    "react": "^18.2.0"
-  },
-  "dependencies": {
-    "@deepseek-ai/schemastery": "^3.18.1",
-    "node-pty": "^1.1.0"
-  },
-  "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-client-locale": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-client-store": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-client-ui-primitives": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-client-ui-settings": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-client-ui-slots": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-llm": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-sandbox": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-settings": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-shell": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-timeout": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-tools": "0.1.5-rc.2",
-    "@types/node": "^22.10.0",
-    "@types/react": "^18.2.0",
-    "@types/react-dom": "^18.2.0",
-    "esbuild": "^0.28.2",
-    "react": "^18.2.0",
-    "react-dom": "^18.2.0",
-    "typescript": "^5.9.0"
-  }
-}
+{
+  "name": "dsh-bash-terminal-ts",
+  "version": "0.6.0",
+  "publishConfig": {
+    "tag": "dsh-0.1.7"
+  },
+  "description": "DSH plugin: one shell tool that runs commands through PowerShell, Git Bash, MSYS2, or WSL on Windows, with a user-chosen default terminal in the Web UI settings. TypeScript rewrite of MAXeaglet/dsh-bash-terminal with working MSYS2/MINGW64 support.",
+  "author": "drscrewdriver",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/drscrewdriver/dsh-bash-terminal-ts.git"
+  },
+  "bugs": {
+    "url": "https://github.com/drscrewdriver/dsh-bash-terminal-ts/issues"
+  },
+  "homepage": "https://github.com/drscrewdriver/dsh-bash-terminal-ts#readme",
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "plugin",
+    "terminal",
+    "shell",
+    "powershell",
+    "git-bash",
+    "wsl",
+    "windows",
+    "typescript"
+  ],
+  "engines": {
+    "node": ">=22",
+    "dsh": ">=0.1.7-rc.1 <0.2.0-0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "dist",
+    "src",
+    "scripts",
+    "template",
+    "tsconfig.json",
+    "tsconfig.client.json",
+    "tsconfig.test.json",
+    "README.md",
+    "LICENSE",
+    "cordis.patch.yml",
+    "dsh.plugin.json",
+    "screenshots.json"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && tsc -p tsconfig.client.json && node scripts/build-client.mjs && tsc -p tsconfig.test.json",
+    "build:client": "node scripts/build-client.mjs",
+    "test": "node test-dist/unit.js && node test-dist/apply.js && node test-dist/client.js && node test-dist/terminal.js"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-api-remotes"
+      ]
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-tools": ">=0.1.7-rc.1 <0.2.0-0",
+    "@deepseek-ai/dsh-settings": ">=0.1.7-rc.1 <0.2.0-0",
+    "@deepseek-ai/dsh-llm": ">=0.1.7-rc.1 <0.2.0-0",
+    "@deepseek-ai/dsh-shell": ">=0.1.7-rc.1 <0.2.0-0",
+    "@deepseek-ai/dsh-sandbox": ">=0.1.7-rc.1 <0.2.0-0",
+    "@deepseek-ai/dsh-timeout": ">=0.1.7-rc.1 <0.2.0-0",
+    "@deepseek-ai/dsh-client-store": ">=0.1.7-rc.1 <0.2.0-0",
+    "@deepseek-ai/dsh-client-locale": ">=0.1.7-rc.1 <0.2.0-0",
+    "@deepseek-ai/dsh-client-ui-settings": ">=0.1.7-rc.1 <0.2.0-0",
+    "@deepseek-ai/dsh-client-ui-slots": ">=0.1.7-rc.1 <0.2.0-0",
+    "@deepseek-ai/dsh-client-ui-primitives": ">=0.1.7-rc.1 <0.2.0-0",
+    "react": "^18.2.0"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.4",
+    "node-pty": "^1.1.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-client-locale": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-client-store": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-client-ui-primitives": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-llm": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-sandbox": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-settings": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-shell": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-timeout": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-tools": "0.1.5-rc.2",
+    "@types/node": "^22.10.0",
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "esbuild": "^0.28.2",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "typescript": "^5.9.0"
+  }
+}

package/screenshots.json

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

package/src/client.tsx

@@ -16,7 +16,8 @@ import { defineStore } from "@deepseek-ai/dsh-client-store";
 import { IconChevronDownOutline14, Menu } from "@deepseek-ai/dsh-client-ui-primitives";
 
 const SETTINGS_NS = "settings.bash-terminal";
-const SETTINGS_NAMESPACE = "bash-terminal";
+/** Entry id of this plugin in the active profile (cordis.patch.yml). */
+const ENTRY_ID = "tool-bash-terminal";
 const SHELLS = ["powershell", "gitbash", "msys2", "wsl"] as const;
 
 type ShellOption = (typeof SHELLS)[number];
@@ -55,7 +56,7 @@ const en: Record<string, string> = {
   "shell.wsl": "WSL"
 };
 
-export const inject = ["slots", "locale", "settingsScope"];
+export const inject = ["slots", "locale", "configForms"];
 
 /** Row state snapshot served through the settings store. */
 interface RowState {
@@ -112,23 +113,23 @@ function ShellPreferenceRow({ t, useStore, setShell }: ShellPreferenceRowProps)
 }
 
 interface SettingsSnapshot {
-  status: string;
+  status: "loading" | "ready" | "unavailable";
   value?: { defaultShell?: string };
-  revision: number;
+  revision: number | undefined;
   writable: boolean;
 }
 
-interface SettingsScopeBinding {
+interface ConfigFormBinding {
   getSnapshot(): SettingsSnapshot;
   subscribe(fn: () => void): () => void;
-  set(field: string, value: string): void;
-  unset(): void;
+  set(field: string, value: string): Promise<boolean>;
+  unset(field: string): Promise<boolean>;
 }
 
 interface ClientContext {
   effect(fn: () => unknown, name?: string): unknown;
   locale: { register(ns: string, dicts: Record<string, Record<string, string>>): unknown };
-  settingsScope: { bind(options: { namespace: string }): SettingsScopeBinding };
+  configForms: { get(entryId: string): ConfigFormBinding };
   slots: {
     inject(slot: string, fn: () => unknown, name?: string): void;
     register(options: Record<string, unknown>, Component: unknown): Record<string, unknown>;
@@ -145,7 +146,7 @@ interface RowStore {
 
 export function apply(ctx: ClientContext): void {
   ctx.effect(() => ctx.locale.register(SETTINGS_NS, { zh, en }), "bash-terminal: settings dictionaries");
-  const scope = ctx.settingsScope.bind({ namespace: SETTINGS_NAMESPACE });
+  const scope = ctx.configForms.get(ENTRY_ID);
   const store = defineStore<RowState, { sync: (draft: RowState, shell?: string, revision?: number, writable?: boolean) => void }>({
     init: (): RowState => ({ shell: "powershell", revision: -1, writable: false }),
     actions: {

package/src/dsh-types.ts

@@ -303,7 +303,6 @@ export interface BashTerminalContext {
   tools: ToolsSeam;
   on(event: "system-prompt/assemble", handler: AssembleHandler): void;
   shellEnv: ShellEnvSeam;
-  settings: SettingsSeam;
   sandboxPolicy: SandboxPolicySeam;
   sandbox: SandboxSeam;
   get(key: string): unknown;

package/src/dsh.ts

@@ -52,6 +52,8 @@ export const escalationHintMarker = sandboxNs.escalationHintMarker as unknown as
 /** Runtime config schema factory (schemastery fork). */
 export interface SchemasterySchema {
   default(value: unknown): SchemasterySchema;
+  /** 0.1.7+: expose the field on the auto-generated settings form. */
+  volatile(): SchemasterySchema;
 }
 
 export interface Schemastery {

package/src/index.ts

@@ -61,8 +61,6 @@ export const inject = ["tools", "systemPrompt", "shellEnv", "subprocess", "setti
 export const SHELLS = ["powershell", "gitbash", "msys2", "wsl"] as const;
 /** The backend used when the caller does not name one. */
 export const DEFAULT_SHELL: ShellId = "powershell";
-/** Settings namespace backing the user-chosen default terminal. */
-export const SETTINGS_NAMESPACE = "bash-terminal";
 /** Default per-command timeout (ms). */
 const DEFAULT_TIMEOUT_MS = 120000;
 /** Upper bound a caller's timeoutMs is capped to. */
@@ -84,6 +82,11 @@ const ENV_OVERRIDES: Record<string, string> = {
   GIT_PAGER: "cat"
 };
 
+/** Live reference the 0.1.7 loader hands `apply` for `.volatile()` config fields. */
+interface VolatileRef<T> {
+  get(): T;
+}
+
 /** Static shape of the runtime configuration schema. */
 export interface ConfigValues {
   defaultShell: string;
@@ -97,7 +100,7 @@ export interface ConfigValues {
 
 /** Runtime configuration schema. */
 export const Config = z.object({
-  defaultShell: z.string().default(DEFAULT_SHELL),
+  defaultShell: z.string().default(DEFAULT_SHELL).volatile(),
   timeoutMs: z.number().default(DEFAULT_TIMEOUT_MS),
   maxTimeoutMs: z.number().default(MAX_TIMEOUT_MS),
   pwshPath: z.string().default(""),
@@ -671,15 +674,18 @@ export function apply(ctx: BashTerminalContext, config: Partial<ConfigValues> =
   }
   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)}`);
+  // 0.1.7: `defaultShell` is a `.volatile()` config field — the loader hands
+  // `apply` a live ref and the latest value is resolved on every read; there
+  // is no settings registration call anymore (removed with the 0.1.7 host).
+  const currentShell = (): string => {
+    const v = config.defaultShell as string | VolatileRef<string> | undefined;
+    if (typeof v === "string") return v;
+    const got = typeof v?.get === "function" ? v.get() : undefined;
+    return typeof got === "string" ? got : DEFAULT_SHELL;
+  };
+  if (!(SHELLS as readonly string[]).includes(currentShell())) {
+    throw new Error(`dsh-bash-terminal: invalid defaultShell ${JSON.stringify(currentShell())}`);
   }
-  const settingsScope = ctx.settings.register(
-    SETTINGS_NAMESPACE,
-    z.object({ defaultShell: z.union(SHELLS.map((s) => z.const(s))).default(defaultShell) }),
-    { base: { defaultShell } }
-  );
   /** Official sandbox-escalation surface (mirrors tool-bash): advertise the
    * escalation modes whenever the deployment confines. */
   const escalationModes = ESCALATION_TARGETS;
@@ -711,7 +717,7 @@ export function apply(ctx: BashTerminalContext, config: Partial<ConfigValues> =
 
   const toolName = "shell";
   const terminalRegistry = createTerminalRegistry(ctx);
-  ctx.tools.register(terminalTool(ctx, terminalRegistry, paths, () => settingsScope.get().defaultShell));
+  ctx.tools.register(terminalTool(ctx, terminalRegistry, paths, () => currentShell()));
 
   // The model-facing description must track the user's chosen default
   // terminal: a static description listing every backend leaves the model
@@ -720,7 +726,7 @@ export function apply(ctx: BashTerminalContext, config: Partial<ConfigValues> =
   // without a restart.
   ctx.on("system-prompt/assemble", async (_assembly, _context, next) => {
     const assembled = await next();
-    const description = toolDescription(backgroundEnabled, settingsScope.get().defaultShell);
+    const description = toolDescription(backgroundEnabled, currentShell());
     const tools = Array.isArray(assembled.tools)
       ? assembled.tools.map((tool) => (tool.name === toolName ? { ...tool, description } : tool))
       : assembled.tools;
@@ -729,7 +735,7 @@ export function apply(ctx: BashTerminalContext, config: Partial<ConfigValues> =
 
   ctx.tools.register(defineTool<ShellToolResult>({
     name: toolName,
-    description: toolDescription(backgroundEnabled, settingsScope.get().defaultShell),
+    description: toolDescription(backgroundEnabled, currentShell()),
     parameters: {
       command: {
         type: "string",
@@ -826,7 +832,7 @@ export function apply(ctx: BashTerminalContext, config: Partial<ConfigValues> =
     },
     async execute(args, exec) {
       const v = validateArgs(args);
-      const shell = settingsScope.get().defaultShell;
+      const shell = currentShell();
       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.`);

package/template/README.md

@@ -0,0 +1,82 @@
+# 终端适配模式模板
+
+把 `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

@@ -0,0 +1,343 @@
+// 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
+  }
+};