dsh-bash-terminal-ts 0.4.0 → 0.6.0

package/src/terminal.ts

@@ -1,23 +1,36 @@
-// dsh-bash-terminal-ts: interactive terminal tool over the official PTY seam.
+// dsh-bash-terminal: 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
 // terminal setting, exactly like the shell tool.
+//
+// Windows note: the official seam's process inspector is POSIX-only
+// (createProcessInspector throws on win32), so on Windows the PTY is
+// allocated directly through node-pty. Session readiness here is
+// output-quiet based (waitSettled), which needs no process inspection.
 
 import { randomUUID } from "node:crypto";
 import { isAbsolute, resolve } from "node:path";
+import { PassThrough } from "node:stream";
 import { TOOL_ABORTED, defineTool, HarnessError } from "./dsh.js";
+// Single source of truth for backend env (msys2 MSYSTEM injection, WSL WSLENV).
+// The cycle with ./index.js is safe: buildEnv is a hoisted function declaration
+// and is only called at tool-execution time, never during module evaluation.
 import { buildEnv } from "./index.js";
 import type {
   BashTerminalContext,
+  JobsRegistry,
   ResolvedPaths,
-  TerminalHandle
+  TerminalHandle,
+  TerminalSpawnSpec,
+  ToolRunContext
 } from "./dsh-types.js";
 
 const MAX_BUFFER_BYTES = 1024 * 1024;
-const READ_SETTLE_MS = 800;
 const DEFAULT_ROWS = 30;
 const DEFAULT_COLS = 110;
+const DEFAULT_IDLE_MS = 10 * 60 * 1000;
+const MAX_SESSIONS = 8;
 const TERMINAL_SIGNALS = ["SIGINT", "SIGTERM", "SIGKILL", "SIGTSTP", "SIGHUP"] as const;
 
 export type TerminalSignal = (typeof TERMINAL_SIGNALS)[number];
@@ -29,12 +42,34 @@ function delay(ms: number): Promise<void> {
 interface TerminalBufferRead {
   delta: string;
   nextOffset: number;
+  truncated: boolean;
 }
 
 interface TerminalBuffer {
   append(chunk: string): void;
   readFrom(offset: number): TerminalBufferRead;
   snapshot(): string;
+  wasTruncated(): boolean;
+  lastAppendAt(): number;
+}
+
+/**
+ * Wait until the terminal output goes quiet (no new bytes for quietMs) or the
+ * cap elapses. Reads after interactive input then return the complete reply
+ * instead of a fixed-delay slice.
+ */
+async function waitSettled(buffer: TerminalBuffer, quietMs = 300, timeoutMs = 5000): Promise<void> {
+  const start = Date.now();
+  let last = buffer.lastAppendAt();
+  while (Date.now() - start < timeoutMs) {
+    await delay(80);
+    const now = buffer.lastAppendAt();
+    if (now > last) {
+      last = now;
+      continue;
+    }
+    if (Date.now() - last >= quietMs) return;
+  }
 }
 
 /** Interactive-shell argv (no -c: the terminal itself is the session). */
@@ -46,10 +81,21 @@ export function terminalArgv(
   switch (shell) {
     case "powershell": return [paths.pwsh, "-NoLogo", "-NoProfile"];
     case "gitbash": return [paths.gitbash, "-i"];
-    case "msys2": return [paths.msys2, "-l"];
+    case "msys2":
+      // -l, NOT -lc: this argv carries no command (the PTY itself is the
+      // session), and `bash -lc` with no operand dies immediately with
+      // "-c: option requires an argument" (measured: exit 2). A login shell is
+      // also what sources /etc/profile, putting /usr/bin and /mingw64/bin on
+      // PATH for the interactive session.
+      return [paths.msys2, "-l"];
     case "wsl": {
-      const distroArg = distro !== undefined && distro.trim().length > 0 ? ["-d", distro.trim()] : [];
-      return [paths.wsl, ...distroArg, "-e", "bash", "-i"];
+      // Verified under ConPTY: 'wsl -e bash -i' on the DEFAULT distro fails with
+      // a WSL service RPC error (0x8007072c), while 'wsl -- bash -i' works;
+      // with an explicit -d distro, '-e bash -i' also works.
+      if (distro !== undefined && distro.trim().length > 0) {
+        return [paths.wsl, "-d", distro.trim(), "-e", "bash", "-i"];
+      }
+      return [paths.wsl, "--", "bash", "-i"];
     }
     default: throw new Error("invalid shell: " + JSON.stringify(shell));
   }
@@ -58,19 +104,86 @@ export function terminalArgv(
 /** In-memory output ring for one session (drop-oldest at the cap). */
 function createBuffer(): TerminalBuffer {
   let text = "";
+  let truncated = false;
+  let lastAppendAt = Date.now();
   return {
     append(chunk: string) {
       text += chunk;
-      if (text.length > MAX_BUFFER_BYTES) text = text.slice(text.length - MAX_BUFFER_BYTES);
+      lastAppendAt = Date.now();
+      if (text.length > MAX_BUFFER_BYTES) {
+        text = text.slice(text.length - MAX_BUFFER_BYTES);
+        truncated = true;
+      }
     },
     readFrom(offset: number): TerminalBufferRead {
       const delta = offset >= text.length ? "" : text.slice(offset);
-      return { delta, nextOffset: text.length };
+      return { delta, nextOffset: text.length, truncated };
     },
-    snapshot: () => text
+    snapshot: () => text,
+    wasTruncated: () => truncated,
+    lastAppendAt: () => lastAppendAt
   };
 }
 
+/** Minimal node-pty face used by the direct-win32 path (shape-cast at import). */
+interface NodePtyTerm {
+  pid: number;
+  write(data: string): void;
+  kill(signal?: string): void;
+  onData(callback: (chunk: string) => void): void;
+  onExit(callback: (event: { exitCode: number; signal: unknown }) => void): void;
+}
+
+type NodePtySpawn = (
+  file: string,
+  args: readonly string[],
+  options: { name: string; cols: number; rows: number; cwd: string; env: Record<string, string | undefined> }
+) => NodePtyTerm;
+
+/**
+ * Direct node-pty handle with the same surface the official seam returns:
+ * output (stream), pid, done, write / signalForeground / terminate. Used on
+ * win32 where the official spawnTerminal's process inspector is unsupported.
+ */
+async function spawnPtyHandle(spec: TerminalSpawnSpec): Promise<TerminalHandle> {
+  const { argv, cwd, env, rows, cols } = spec;
+  const mod = (await import("node-pty")) as unknown as { default?: { spawn: NodePtySpawn }; spawn: NodePtySpawn };
+  const nodePty = mod.default ?? mod;
+  const term = nodePty.spawn(argv[0]!, argv.slice(1), {
+    name: "dumb",
+    cols,
+    rows,
+    cwd,
+    env: { ...env, TERM: "dumb", NO_COLOR: "1" }
+  });
+  const output = new PassThrough();
+  term.onData((chunk) => output.write(Buffer.from(chunk, "utf8")));
+  const done = new Promise<{ exitCode: number; signal: string | null }>((resolveDone) => {
+    term.onExit(({ exitCode, signal }) => resolveDone({ exitCode, signal: typeof signal === "string" ? signal : null }));
+  });
+  return {
+    pid: term.pid,
+    output,
+    done,
+    write: (data) => term.write(data),
+    // node-pty accepts no named signals on Windows: Ctrl+C is the \x03 byte
+    // (ConPTY delivers it to the foreground process), other signals degrade
+    // to terminating the session.
+    signalForeground: (sig) => {
+      if (sig === "SIGINT") { term.write("\x03"); return; }
+      term.kill();
+    },
+    terminate: async () => { try { term.kill(); } catch { /* already dead */ } }
+  };
+}
+
+export interface TerminalSessionInfo {
+  sessionId: string;
+  shell: string;
+  pid: number;
+  closed: boolean;
+}
+
 interface TerminalSession {
   id: string;
   handle: TerminalHandle;
@@ -78,6 +191,9 @@ interface TerminalSession {
   shell: string;
   distro?: string;
   closed: boolean;
+  idleMs: number;
+  idleTimer?: NodeJS.Timeout;
+  touch: () => void;
 }
 
 export interface TerminalOpenOptions {
@@ -89,6 +205,7 @@ export interface TerminalOpenOptions {
   cols: number;
   distro?: string;
   initial?: string;
+  idleMs?: number;
 }
 
 export interface TerminalRegistry {
@@ -98,6 +215,7 @@ export interface TerminalRegistry {
   read(id: string): TerminalBufferRead;
   signal(id: string, sig: string): Promise<TerminalBufferRead>;
   close(id: string): Promise<boolean>;
+  list(): TerminalSessionInfo[];
 }
 
 /**
@@ -115,19 +233,20 @@ export function createTerminalRegistry(ctx: BashTerminalContext): TerminalRegist
   }, "bash-terminal: terminal sessions teardown");
 
   async function open(options: TerminalOpenOptions): Promise<TerminalSession> {
-    const { argv, shell, cwd, env, rows, cols, distro, initial } = options;
-    const spawnTerminal = ctx.subprocess?.spawnTerminal;
-    if (spawnTerminal === undefined) {
-      throw new Error("terminal: ctx.subprocess.spawnTerminal seam unavailable");
+    const { argv, shell, cwd, env, rows, cols, distro, initial, idleMs } = options;
+    if (sessions.size >= MAX_SESSIONS) {
+      throw new Error("terminal: too many open sessions (" + MAX_SESSIONS + "); close one before opening another");
+    }
+    let handle: TerminalHandle;
+    if (process.platform === "win32") {
+      handle = await spawnPtyHandle({ argv, cwd, env, rows, cols });
+    } else {
+      const spawnTerminal = ctx.subprocess?.spawnTerminal;
+      if (spawnTerminal === undefined) {
+        throw new Error("terminal: ctx.subprocess.spawnTerminal seam unavailable");
+      }
+      handle = await spawnTerminal({ argv, cwd, env, rows, cols, graceMs: 3000 });
     }
-    const handle = await spawnTerminal({
-      argv,
-      cwd,
-      env,
-      rows,
-      cols,
-      graceMs: 3000
-    });
     const buffer = createBuffer();
     handle.output.on("data", (chunk: unknown) => buffer.append(typeof chunk === "string" ? chunk : String(chunk)));
     const session: TerminalSession = {
@@ -136,12 +255,28 @@ export function createTerminalRegistry(ctx: BashTerminalContext): TerminalRegist
       buffer,
       shell,
       distro,
-      closed: false
+      closed: false,
+      idleMs: idleMs ?? DEFAULT_IDLE_MS,
+      touch: () => { /* replaced below */ }
     };
+    // Idle guard: any read/send/signal touches the timer; expiry terminates the
+    // session so an abandoned PTY never leaks a process tree.
+    const touch = (): void => {
+      if (session.closed) return;
+      clearTimeout(session.idleTimer);
+      session.idleTimer = setTimeout(() => {
+        if (session.closed) return;
+        session.closed = true;
+        sessions.delete(session.id);
+        void session.handle.terminate().catch(() => { /* already dead */ });
+      }, session.idleMs);
+    };
+    session.touch = touch;
+    touch();
     sessions.set(session.id, session);
     if (initial !== undefined && initial.length > 0) {
       await handle.write(initial);
-      await delay(READ_SETTLE_MS);
+      await waitSettled(buffer);
     }
     return session;
   }
@@ -150,55 +285,67 @@ export function createTerminalRegistry(ctx: BashTerminalContext): TerminalRegist
     const session = sessions.get(id);
     if (session === undefined) throw new Error("terminal session not found: " + JSON.stringify(id));
     if (session.closed) throw new Error("terminal session is closed: " + JSON.stringify(id));
+    session.touch();
     return session;
   }
 
   async function send(id: string, input: string): Promise<TerminalBufferRead> {
     const session = get(id);
     await session.handle.write(input);
-    await delay(READ_SETTLE_MS);
+    await waitSettled(session.buffer);
     return read(id);
   }
 
-  function read(id: string): TerminalBufferRead {
-    const session = get(id);
-    const { delta, nextOffset } = session.buffer.readFrom(0);
-    return { delta, nextOffset };
-  }
-
   async function signal(id: string, sig: string): Promise<TerminalBufferRead> {
     const session = get(id);
     if (!(TERMINAL_SIGNALS as readonly string[]).includes(sig)) {
       throw new Error("invalid terminal signal: " + JSON.stringify(sig));
     }
     await session.handle.signalForeground(sig);
-    await delay(READ_SETTLE_MS);
+    await waitSettled(session.buffer);
     return read(id);
   }
 
+  function read(id: string): TerminalBufferRead {
+    const session = get(id);
+    const { delta, nextOffset, truncated } = session.buffer.readFrom(0);
+    return { delta, nextOffset, truncated };
+  }
+
   async function close(id: string): Promise<boolean> {
     const session = get(id);
     session.closed = true;
+    clearTimeout(session.idleTimer);
     sessions.delete(id);
     await session.handle.terminate();
     return true;
   }
 
-  return { open, get, send, read, signal, close };
+  function list(): TerminalSessionInfo[] {
+    return [...sessions.values()].map((session) => ({
+      sessionId: session.id,
+      shell: session.shell,
+      pid: session.handle.pid,
+      closed: session.closed
+    }));
+  }
+
+  return { open, get, send, read, signal, close, list };
 }
 
 /** The terminal tool's arguments after runtime validation (discriminated by action). */
 export type ValidatedTerminalArgs =
-  | { action: "open"; sessionId?: string; command?: string; distro?: string; workdir?: string }
+  | { action: "open"; sessionId?: string; command?: string; distro?: string; workdir?: string; idleMs?: number }
   | { action: "send"; sessionId: string; input: string }
   | { action: "read"; sessionId: string }
   | { action: "signal"; sessionId: string; signal: TerminalSignal }
-  | { action: "close"; sessionId: string };
+  | { action: "close"; sessionId: string }
+  | { action: "list" };
 
 export function validateArgs(args: Record<string, unknown>): asserts args is ValidatedTerminalArgs {
   const action = args.action;
-  if (typeof action !== "string" || ["open", "send", "read", "signal", "close"].indexOf(action) === -1) {
-    throw new Error("invalid action: expected open, send, read, signal, or close");
+  if (typeof action !== "string" || ["open", "send", "read", "signal", "close", "list"].indexOf(action) === -1) {
+    throw new Error("invalid action: expected open, send, read, signal, close, or list");
   }
   if ((action === "send" || action === "read" || action === "signal" || action === "close") && (typeof args.sessionId !== "string" || args.sessionId.length === 0)) {
     throw new Error("invalid sessionId: required for " + action);
@@ -214,6 +361,7 @@ export function validateArgs(args: Record<string, unknown>): asserts args is Val
 export interface TerminalOpenResult {
   kind: "open";
   sessionId: string;
+  jobId?: string;
   pid: number;
   shell: string;
   output: string;
@@ -222,6 +370,7 @@ export interface TerminalOpenResult {
 export interface TerminalSessionResult {
   kind: "session";
   output: string;
+  truncated?: boolean;
 }
 
 export interface TerminalClosedResult {
@@ -229,7 +378,12 @@ export interface TerminalClosedResult {
   sessionId: string;
 }
 
-export type TerminalToolResult = TerminalOpenResult | TerminalSessionResult | TerminalClosedResult;
+export interface TerminalListResult {
+  kind: "list";
+  sessions: TerminalSessionInfo[];
+}
+
+export type TerminalToolResult = TerminalOpenResult | TerminalSessionResult | TerminalClosedResult | TerminalListResult;
 
 export function terminalTool(
   ctx: BashTerminalContext,
@@ -239,13 +393,13 @@ export function terminalTool(
 ) {
   return defineTool<TerminalToolResult>({
     name: "terminal",
-    description: "Interactive terminal session over the user's default terminal (Settings -> General -> Default terminal: powershell / gitbash / msys2 / wsl). A real PTY hosts a persistent shell: open a session, send input and read output across turns, deliver signals (Ctrl+C = SIGINT) to the foreground process, and close when done. Backend and env follow the shell tool exactly; the session survives between calls until closed. Use this for interactive programs (REPLs, ssh, databases, TUI tools) or when you need shell state (cwd, variables, aliases) to persist across calls.",
+    description: "Interactive terminal session over the user's default terminal (Settings -> General -> Default terminal: powershell / gitbash / msys2 / wsl). A real PTY hosts a persistent shell: open a session, send input and read output across turns, deliver signals (Ctrl+C = SIGINT) to the foreground process, and close when done. Backend and env follow the shell tool exactly; the session survives between calls until closed and is managed as a background job (job_kill / job_output work on it); idle sessions close automatically. Use this for interactive programs (REPLs, ssh, databases, TUI tools) or when you need shell state (cwd, variables, aliases) to persist across calls.",
     parameters: {
       action: {
         type: "string",
-        enum: ["open", "send", "read", "signal", "close"],
+        enum: ["open", "send", "read", "signal", "close", "list"],
         required: true,
-        description: "open: create a session and return its id. send: write input and read new output. read: read new output without writing. signal: send a signal to the foreground process (SIGINT for Ctrl+C). close: terminate the session."
+        description: "open: create a session and return its id. send: write input and read new output. read: read new output without writing. signal: send a signal to the foreground process (SIGINT for Ctrl+C). close: terminate the session. list: list live sessions."
       },
       sessionId: {
         type: "string",
@@ -271,6 +425,10 @@ export function terminalTool(
       workdir: {
         type: "string",
         description: "Working directory for the session (open only). Defaults to the session workspace."
+      },
+      idleMs: {
+        type: "number",
+        description: "Idle timeout in ms (open only): the session closes automatically after this long without send/read/signal. Default 600000 (10 min)."
       }
     },
     output: {
@@ -282,6 +440,7 @@ export function terminalTool(
             properties: {
               kind: { type: "string", required: true, const: "open" },
               sessionId: { type: "string", required: true },
+              jobId: { type: "string" },
               pid: { type: "integer", required: true },
               shell: { type: "string", required: true },
               output: { type: "string" }
@@ -292,7 +451,8 @@ export function terminalTool(
             additionalProperties: false,
             properties: {
               kind: { type: "string", required: true, const: "session" },
-              output: { type: "string", required: true }
+              output: { type: "string", required: true },
+              truncated: { type: "boolean" }
             }
           },
           {
@@ -302,6 +462,26 @@ export function terminalTool(
               kind: { type: "string", required: true, const: "closed" },
               sessionId: { type: "string", required: true }
             }
+          },
+          {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+              kind: { type: "string", required: true, const: "list" },
+              sessions: {
+                type: "array",
+                items: {
+                  type: "object",
+                  additionalProperties: false,
+                  properties: {
+                    sessionId: { type: "string", required: true },
+                    shell: { type: "string", required: true },
+                    pid: { type: "integer", required: true },
+                    closed: { type: "boolean" }
+                  }
+                }
+              }
+            }
           }
         ]
       },
@@ -311,7 +491,11 @@ export function terminalTool(
           ? "terminal session " + value.sessionId + " (pid " + value.pid + ", " + value.shell + ")" + (value.output ? "\n" + value.output : "")
           : value.kind === "closed"
             ? "terminal session " + value.sessionId + " closed"
-            : value.output
+            : value.kind === "list"
+              ? (value.sessions.length === 0 ? "no open terminal sessions" : value.sessions.map((s) => s.sessionId + " (" + s.shell + ", pid " + s.pid + ")").join("\n"))
+              : value.truncated === true
+                ? (value.output.length === 0 ? "[terminal buffer overflowed; oldest output dropped]" : value.output + "\n[terminal buffer overflowed; oldest output dropped]")
+                : value.output
       }]
     },
     async execute(args, exec): Promise<TerminalToolResult> {
@@ -333,30 +517,46 @@ export function terminalTool(
           // buildEnv, not an inline duplicate: the msys2 backend needs its
           // MSYSTEM=MINGW64 injection here too, or the login shell sources
           // /etc/profile with the default MSYS environment and /mingw64/bin
-          // (gcc, make) never joins PATH. DSH's spawnTerminal replaces the child
-          // environment with exactly this object (childEnv(spec.env)), so the
-          // inherited WSLENV is passed through explicitly for the WSL allow-list;
-          // for every other backend buildEnv ignores the third argument.
+          // (gcc, make) never joins PATH. It also owns the WSL WSLENV layering,
+          // so a terminal session's env follows the shell tool exactly.
+          // process.env.WSLENV is passed explicitly: spawnTerminal replaces the
+          // child environment wholesale (childEnv(spec.env)), so the ambient
+          // allow-list is not otherwise visible and inherited entries such as
+          // WT_SESSION / WT_PROFILE_ID would be dropped.
           const env = buildEnv(shell, ctx.shellEnv.collect(exec), process.env.WSLENV);
-          const session = await registry.open({ argv, shell, cwd, env, rows: DEFAULT_ROWS, cols: DEFAULT_COLS, distro: args.distro, initial: args.command !== undefined ? args.command + "\r" : undefined });
-          return { kind: "open", sessionId: session.id, pid: session.handle.pid, shell, output: session.buffer.snapshot() };
+          const session = await registry.open({ argv, shell, cwd, env, rows: DEFAULT_ROWS, cols: DEFAULT_COLS, distro: args.distro, initial: args.command !== undefined ? args.command + "\r" : undefined, idleMs: args.idleMs });
+          const jobs = ctx.get("jobs") as JobsRegistry | undefined;
+          const jobId = jobs === undefined ? undefined : jobs.start({
+            kind: "terminal/session",
+            label: "terminal " + session.id.slice(0, 8) + " (" + shell + ")",
+            ...(exec.agent ? { owner: exec.agent } : {}),
+            run: () => ({
+              cancel: () => { void session.handle.terminate().catch(() => { /* already dead */ }); },
+              done: session.handle.done,
+              readOutput: () => registry.read(session.id).delta
+            })
+          });
+          return { kind: "open", sessionId: session.id, ...(jobId !== undefined ? { jobId } : {}), pid: session.handle.pid, shell, output: session.buffer.snapshot() };
         }
         case "send": {
-          const { delta } = await registry.send(args.sessionId, args.input);
-          return { kind: "session", output: delta };
+          const { delta, truncated } = await registry.send(args.sessionId, args.input);
+          return { kind: "session", output: delta, ...(truncated ? { truncated } : {}) };
         }
         case "read": {
-          const { delta } = registry.read(args.sessionId);
-          return { kind: "session", output: delta };
+          const { delta, truncated } = registry.read(args.sessionId);
+          return { kind: "session", output: delta, ...(truncated ? { truncated } : {}) };
         }
         case "signal": {
-          const { delta } = await registry.signal(args.sessionId, args.signal);
-          return { kind: "session", output: delta };
+          const { delta, truncated } = await registry.signal(args.sessionId, args.signal);
+          return { kind: "session", output: delta, ...(truncated ? { truncated } : {}) };
         }
         case "close": {
           await registry.close(args.sessionId);
           return { kind: "closed", sessionId: args.sessionId };
         }
+        case "list": {
+          return { kind: "list", sessions: registry.list() };
+        }
       }
     },
     presentCall: (args) => ({

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。