dsh-bash-terminal-ts 0.4.0 → 0.6.0

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
+  }
+};

package/README.ja.md

@@ -1,196 +0,0 @@
-# dsh-bash-terminal-ts
-
-[![test](https://github.com/drscrewdriver/dsh-bash-terminal-ts/actions/workflows/test.yml/badge.svg)](https://github.com/drscrewdriver/dsh-bash-terminal-ts/actions/workflows/test.yml)
-
-[English](README.en.md) | **日本語** | [한국어](README.ko.md) | [中文](README.md)
-
-DSH（DeepSeek Harness）プラグイン：Windows 上で **PowerShell / Git Bash / MSYS2 / WSL** の 4 種類のターミナルコマンドを 1 つの `shell` ツールに統合して実行します。
-
-ターミナルは**あなたが Web UI で選びます**。モデルは変更できません。一度選べば、以降のすべてのコマンドはそのターミナルで実行されます。
-
-## なぜ使うのか
-
-| 売り | ひとことで |
-|------|--------|
-| **MSYS2 が本当に動く** | 「ドロップダウンの選択肢を 1 つ足した」だけではありません。`bash.exe` の解決、ログインシェル、`MSYSTEM` 環境という 3 点をすべて正しく処理しています —— MSYS2 を選べばそのまま `gcc` や `make` が使えます（後述の「MSYS2 サポート」参照） |
-| **TypeScript ソース** | `strict` + `noUncheckedIndexedAccess`。argv / env の構築は純関数が担当するため単体テスト可能です |
-| **DSH 0.1.2 を主対象** | `engines.dsh: >=0.1.2-rc.1 <0.2.0-0`。0.1.2 の `ctx.subprocess` / `ctx.sandbox` / PTY の接合部に合わせて構築しています |
-| **4 種類のターミナルを 1 つのツールで** | 同じ `shell` ツールが PowerShell / Git Bash / MSYS2 / WSL をカバーするので、モデルは 4 通りもの引数を覚える必要がありません |
-| **サンドボックスは公式準拠** | 公式の `ctx.sandboxPolicy` + `ctx.sandbox` を使用し、fail-closed。拒否時には同一ターン内での昇格案内を返します |
-| **対話型ターミナル** | 本物の PTY セッションツールも用意しています：`open / send / read / signal / close`。Ctrl+C が使え、ターンをまたいで状態を保持します |
-
-## 対応バックエンド
-
-| バックエンド | 実際の実行 | 構文 / パス | 環境変数 |
-|------|----------|-------------|----------|
-| `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` |
-| `msys2` | `C:\msys64\usr\bin\bash.exe -lc <cmd>`（ログインシェル；`MSYSTEM=MINGW64`） | POSIX；完全な GCC / mingw64 ツールチェーンを同梱 | `$NAME` |
-| `wsl` | `wsl [-d <distro>] -e bash -lc <cmd>` | Linux；`/mnt/d/...` | `$NAME`（WSLENV 経由） |
-
-呼び出しごとにまったく新しいシェルが起動します：**状態は保持されません**（cwd / 変数 / エイリアス）。`cd` ではなく `workdir` を渡してください。ターンをまたいで状態を保持したい場合は対話型ターミナルツールを使ってください。
-
-## MSYS2 サポート
-
-MSYS2 は「バックエンドをもう 1 つ足すだけ」に見えますが、実際には 3 つの落とし穴があり、本プラグインはそれを 1 つずつ処理しています。
-
-**1. `msys2.exe` は起動できません。**
-`C:\msys64\msys2.exe` はコンソールウィンドウを割り当てる Cygwin ランチャーです。本プラグインはパイプ stdio で spawn しますが（これが DSH の標準方式です）、その場合これは **exit 0 でゼロバイトの出力を返します** —— コマンドは静かに失敗し、「成功」したように見えて実際には何も行われません。したがって候補の順序は `usr\bin\bash.exe` → `bin\bash.exe` → `msys2.exe` のフォールバックとなり、**利用可能な `bash.exe` が常に優先されます**。
-
-**2. `-lc` は省略できません。**
-`/etc/profile` を読むのはログインシェルだけで、`/usr/bin` と `/mingw64/bin` を PATH に追加するのも `/etc/profile` だけです。裸の `-c` を使うと `tr`、`sed`、`gcc` がすべて `command not found` になります。
-
-**3. `MSYSTEM=MINGW64` を注入する必要があります。**
-そうしないと `/etc/profile` がデフォルトの MSYS 環境として初期化され、`/mingw64/bin` にある gcc や make が使えません。本プラグインは `buildEnv` 経由で注入します（**あなたが明示的に設定した値が優先されます**）。また `shell` ツールと対話型ターミナルは同じ `buildEnv` を通るため、「ツールでは動くのにターミナルでは動かない」といったずれは発生しません。
-
-実測（本物の PTY）：プロンプトが `MSYS` から `MINGW64` に変わり、`command -v gcc` → `/mingw64/bin/gcc` となります。
-
-これら 3 点はすべて回帰テストで守られています。`test/unit.ts` は `bash.exe` が `msys2.exe` より前に並ぶことを断言し、`test/apply.ts` は PTY 環境に `MSYSTEM=MINGW64` が含まれ、かつ gitbash に漏れないことを断言します。
-
-## 設計上の要点
-
-- **ターミナルはユーザーが決め、AI は変更できない**：Web UI の設定画面（設定 → 一般）に「デフォルトターミナル」ドロップダウン（PowerShell / Git Bash / MSYS2 / WSL）が表示されます。`shell` ツールは常にこの設定のみを使用し、モデルにターミナル引数を公開しません。設定は DSH settings システム（settings.yaml）で永続化されます。
-- **`ctx.shell` 能力の接合部を占有しない**：DSH 標準のサンドボックス化された `pwsh` ツールはそのまま利用可能です。本プラグインの `shell` ツールは**追加の**マルチターミナル入口です。
-- 共有された `ctx.subprocess` seam を通じてプロセスを派生させます：プロセスツリーの終了（Windows `taskkill /T`）、SIGTERM→grace→SIGKILL、出力の spill ファイル。公式の `dsh-tool-bash` / `dsh-tool-pwsh` と同じ挙動です。
-- バックグラウンドタスクは共通の `jobs` registry に登録され、`run_in_background` / `job_output` / `job_kill` をサポートします。
-- ツール引数 `shell` は列挙型です（UI ではドロップダウンとして自動レンダリングされます）。モデルは呼び出しごとにターミナルを自身で選択します。
-- 4 つのバックエンドについて、フロントエンドのドロップダウン内の `<option>` と 2 つの言語パックの `shell.<id>` 文言には drift ガードテストがあります —— バックエンドを追加して文言の更新を忘れると、テストがそのまま失敗します。
-
-## インストール
-
-### 標準インストール（npm）
-
-```powershell
-# 1. プラグインパッケージをインストール
-npm install -g dsh-bash-terminal-ts
-dsh plugin --profile web add dsh-bash-terminal-ts
-
-# 2. DSH 設定のホワイトリストを patch（DSH 側の制限。下記の説明を参照。install.ps1 でこの手順だけを単独実行することもできます）
-powershell -ExecutionPolicy Bypass -File install.ps1 install
-
-# 3. dsh web を再起動
-```
-
-### ローカル開発インストール（junction 直結、ソース変更が即時反映）
-
-```powershell
-# 1. プラグインパッケージを profile の node_modules にリンク（junction なのでソース変更が即時反映されます）
-$profile = "$env:USERPROFILE\.dsh\profiles\web"
-New-Item -ItemType Junction -Path "$profile\node_modules\dsh-bash-terminal-ts" -Target "D:\WorkSpace\projects\dsh-bash-terminal-ts" | Out-Null
-
-# 2. プラグインが @deepseek-ai/* 依存を解決できるようにする（profile の依存ツリーへ junction）
-New-Item -ItemType Junction -Path "D:\WorkSpace\projects\dsh-bash-terminal-ts\node_modules\@deepseek-ai" -Target "$profile\..\node_modules\@deepseek-ai" | Out-Null
-
-# 3. cordis.patch.yml にマウント行を追記（下記の patch 断片を参照）
-# 4. （フロントエンドのソースを変更した場合のみ）client bundle を再ビルド:
-#    cd D:\WorkSpace\projects\dsh-bash-terminal-ts && node scripts/build-client.mjs
-# 5. 設定 UI が本プラグインの設定書き込みを受け付けるようにする（DSH 側の制限。下記の説明を参照）
-# 6. dsh web を再起動
-```
-
-> **DSH 設定 UI のホワイトリスト制限**：DSH の api-gateway（dsh-host-apiproxy）は、
-> Web 設定クライアントに公開する settings namespace について**ハードコードされた
-> ホワイトリスト**を持っています（サードパーティ製プラグインの設定はデフォルトで
-> `settings-not-exposed` として拒否され、UI で変更しても反映されません）。
-> install.ps1 はこのホワイトリストを自動で patch します（`bash-terminal` を追加し、
-> 元のファイルは先にバックアップされます）。
-> **DSH をアップグレードした後は install.ps1 を再実行して** patch を復元してください。アンインストール時には install.ps1 が元に戻します。
-
-`cordis.patch.yml` への追記：
-
-```yaml
-- insert:
-    - id: tool-bash-terminal
-      name: 'dsh-bash-terminal-ts'
-```
-
-組み立てツリーの検証（再起動不要）：
-
-```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-ts
-```
-
-## 使い方
-
-**ユーザーは Web UI でデフォルトターミナルを設定します**：設定（歯車）→ 一般 →「デフォルトターミナル」ドロップダウンから、PowerShell / Git Bash / MSYS2 / WSL のいずれかを選びます。変更は即時反映され、永続化されます。
-
-モデルは `shell` ツールを認識すると、コマンド実行時にあなたが選んだターミナルを自動的に使用します（ツールはターミナル引数を公開しないため、モデルはあなたの選択を変更できません）。
-
-- デフォルトターミナル = Git Bash の場合：`shell(command: "git status")` は Git Bash を通ります
-- デフォルトターミナル = MSYS2 の場合：`shell(command: "gcc --version")` は MSYS2 を通ります（ログインシェルで、PATH に `/usr/bin` と `/mingw64/bin` を含み、完全な GCC / mingw64 ツールチェーンを同梱）
-- デフォルトターミナル = WSL の場合：`shell(command: "ls -la /mnt/d/WorkSpace")` は WSL を通ります。`distro: "Ubuntu"` を渡すとディストリビューションを指定できます
-- デフォルトターミナル = PowerShell の場合：`shell(command: "Get-Process node")` は PowerShell を通ります
-
-## 設定
-
-**Web UI 設定**（推奨）：設定 → 一般 →「デフォルトターミナル」。
-
-プラグイン row の `config`（デフォルトを上書きし、設定の composition の基準となります）：
-
-| キー | デフォルト | 説明 |
-|----|------|------|
-| `defaultShell` | `powershell` | 設定で上書きされていない場合のバックエンド |
-| `timeoutMs` | 120000 | デフォルトのタイムアウト |
-| `maxTimeoutMs` | 600000 | 呼び出し側 timeoutMs の上限 |
-| `pwshPath` | 自動検出 | pwsh.exe のパスを固定 |
-| `gitBashPath` | 自動検出 | git bash.exe のパスを固定 |
-| `msys2Path` | 自動検出 | MSYS2 入口パスを固定（`bash.exe` を指す必要があり、`msys2.exe` を指してはいけません。「MSYS2 サポート」参照） |
-| `wslPath` | 自動検出 | wsl.exe のパスを固定 |
-
-## アンインストール
-
-```powershell
-Remove-Item "$env:USERPROFILE\.dsh\profiles\web\node_modules\dsh-bash-terminal-ts" -Force
-# あわせて cordis.patch.yml から insert ブロックを削除し、dsh web を再起動します
-```
-
-## サンドボックス（公式機構との接続）
-
-`shell` ツールは DSH 公式のサンドボックス接合部（`ctx.sandboxPolicy` + `ctx.sandbox`）を通ります：
-
-- 呼び出しごとに現在のサンドボックス方針を解決します。`danger-full-access` のセッションではそのまま実行されます（ラップしません）。
-- PowerShell / Git Bash / MSYS2 の各バックエンドは `ctx.sandbox.confine` を通じて argv をラップします —— 公式 executor と同じ **fail-closed** の意味論です：制限モードを要求したのに利用可能なバックエンドがない場合は `SandboxUnavailableError` を投げ、ラップなしの実行を拒否します。
-- WSL バックエンドはラップしません：WSL の独立した Linux 仮想マシン自体が隔離であるためです（結果は `enforcement: wsl-isolation` を報告します）。
-- 制限モードでサンドボックスに拒否された場合、結果には公式のマーカー `[sandbox: file access denied under <mode> mode]` と同一ターン内での昇格案内が付与されます。モデルは `sandbox_permissions` + `justification` によって 1 回の昇格を申請できます（`ctx.approval` を通じたユーザー承認を経由）。公式の bash/pwsh ツールと完全に同じです。
-- 注意：DSH の Windows ACL サンドボックス launcher（`node-addon-landlock-run-win32-x64`）は現在まだ npm で公開されていないため、本機のサンドボックスバックエンドは当面利用できません。アーキテクチャはすでに整っており、DSH の公開後には自動的に有効になります。
-
-## ⚠️ セキュリティに関する注意
-
-`shell` ツールのコマンドは**DSH サンドボックスの外側**で実行され、dsh プロセスと同じ権限を持ちます（完全アクセスのコマンド実行に相当します）。
-`pwsh` ツールの ConstrainedLanguage 制限は適用されません。DSH のファイル操作ツール（read/write/edit）は引き続きファイルサンドボックスの制約を受けます。
-信頼できるセッションでのみ使用してください。サンドボックスで保護された PowerShell が必要な場合は、引き続き公式の `pwsh` ツールを使用してください。
-
-## 既知の制限
-
-- 本プラグインは `win32` プラットフォームでのみツールを登録します。
-- WSL のバックグラウンドプロセスは、タイムアウトや中断の後、ディストリビューション内に一時的に残ることがあります（WSL インスタンスは最後のプロセスが終了した時点で自動的に終了します）。
-- Git Bash と MSYS2 はどちらも msys2 環境であり、WSL の Linux とは挙動に差があります（パスマッピング、パッケージの可用性）。
-- `C:\msys64` がデフォルト以外の場所にインストールされていて PATH 上にない場合は、`msys2Path` を明示的に設定する必要があります。
-
-## テスト
-
-```powershell
-git clone https://github.com/drscrewdriver/dsh-bash-terminal-ts.git
-cd dsh-bash-terminal-ts
-npm install          # 依存をインストール（typescript を含む）
-npm run build        # tsc でコンパイル src/*.ts → lib/*.js；client.tsx → dist/client.js；test/*.ts → test-dist/
-npm test             # node test-dist/unit.js → apply.js → client.js
-```
-
-CI は `windows-latest` 上で同じ一式を実行します（`.github/workflows/test.yml`）。
-
-## 技術実装
-
-動作要件：**Node.js 22+（24 を推奨）**、DSH 0.1.2+。
-
-ソースは TypeScript（`strict` + `noUncheckedIndexedAccess`）で、コンパイル成果物 `lib/`、`dist/` はリポジトリにコミットされています。DSH は `lib/index.js` をそのまま読み込むため、**インストール不要で使用できます**。
-
-require 側の依存（`@deepseek-ai/*` など 13 パッケージ）はすべて `peerDependencies` + `peerDependenciesMeta.optional` として宣言し、ホストが同梱するコピーとの重複インストールを避けています。
-
-## 謝辞
-
-本プロジェクトは [MAXeaglet/dsh-bash-terminal](https://github.com/MAXeaglet/dsh-bash-terminal) を基に発展させたものです —— オリジナルの `shell` ツール、PowerShell / Git Bash / WSL の 3 バックエンド構成、およびサンドボックス接合部との接続はいずれも原作者によるものです。本バージョンではこれに MSYS2 バックエンド、TypeScript への書き直し、DSH 0.1.2 への適合を加えています。
-
-## ライセンス
-
-MIT