dsh-bash-terminal-ts 0.4.0 → 0.5.0

package/dist/client.core.js

@@ -23,13 +23,24 @@ __export(client_exports, {
   inject: () => inject
 });
 module.exports = __toCommonJS(client_exports);
+var import_react = require("react");
 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 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) {
+  const tag = document.createElement("style");
+  tag.dataset.plugin = "dsh-bash-terminal";
+  tag.dataset.pluginCss = "bash-terminal-row";
+  tag.textContent = ROW_CSS;
+  document.head.appendChild(tag);
+}
 var zh = {
   "shell.title": "\u9ED8\u8BA4\u7EC8\u7AEF",
-  "shell.description": "shell \u5DE5\u5177\u6267\u884C\u547D\u4EE4\u65F6\u4F7F\u7528\u7684\u7EC8\u7AEF\uFF08\u7531\u4F60\u51B3\u5B9A\uFF0CAI \u65E0\u6CD5\u66F4\u6539\uFF09",
+  "shell.description": "shell \u5DE5\u5177\u6267\u884C\u547D\u4EE4\u65F6\u4F7F\u7528\u7684\u7EC8\u7AEF",
   "shell.powershell": "PowerShell",
   "shell.gitbash": "Git Bash",
   "shell.msys2": "MSYS2",
@@ -37,7 +48,7 @@ var zh = {
 };
 var en = {
   "shell.title": "Default terminal",
-  "shell.description": "Terminal used by the shell tool (you control this; the AI cannot change it)",
+  "shell.description": "Terminal used by the shell tool",
   "shell.powershell": "PowerShell",
   "shell.gitbash": "Git Bash",
   "shell.msys2": "MSYS2",
@@ -47,49 +58,45 @@ var inject = ["slots", "locale", "settingsScope"];
 function ShellPreferenceRow({ t, useStore, setShell }) {
   const shell = useStore((s) => s.shell);
   const writable = useStore((s) => s.writable);
-  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
-    "div",
-    {
-      style: {
-        display: "flex",
-        alignItems: "center",
-        justifyContent: "space-between",
-        gap: 16,
-        padding: "12px 0"
-      },
-      children: [
-        /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { style: { minWidth: 0 }, children: [
-          /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { style: { fontSize: 14, fontWeight: 500, lineHeight: "22px", color: "var(--dsw-alias-label-primary, inherit)" }, children: t("shell.title") }),
-          /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { style: { fontSize: 12, lineHeight: "18px", opacity: 0.65 }, children: t("shell.description") })
-        ] }),
-        /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
-          "select",
+  const [open, setOpen] = (0, import_react.useState)(false);
+  const items = SHELLS.map((id) => ({ id, label: t("shell." + id) }));
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "btRow", children: [
+    /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "btRowText", children: [
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "btTitle", children: t("shell.title") }),
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "btDesc", children: t("shell.description") })
+    ] }),
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      import_dsh_client_ui_primitives.Menu,
+      {
+        open,
+        onClose: () => setOpen(false),
+        items,
+        selectedId: shell,
+        onSelect: (id) => {
+          setOpen(false);
+          setShell(id);
+        },
+        align: "end",
+        portal: true,
+        anchor: /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
+          "button",
           {
-            value: shell,
+            type: "button",
+            className: "btSelector",
+            "aria-haspopup": "menu",
+            "aria-expanded": open,
             disabled: !writable,
-            onChange: (e) => setShell(e.target.value),
-            style: {
-              fontSize: 14,
-              padding: "6px 10px",
-              borderRadius: 8,
-              border: "1px solid var(--dsw-alias-line-strong, #ccc)",
-              background: "var(--dsw-alias-bg-layer-2, #fff)",
-              color: "var(--dsw-alias-label-primary, inherit)",
-              outline: "none",
-              cursor: writable ? "pointer" : "not-allowed",
-              maxWidth: 180
-            },
+            onClick: () => setOpen(!open),
+            style: !writable ? { opacity: 0.5, cursor: "not-allowed" } : void 0,
             children: [
-              /* @__PURE__ */ (0, import_jsx_runtime.jsx)("option", { value: "powershell", children: t("shell.powershell") }),
-              /* @__PURE__ */ (0, import_jsx_runtime.jsx)("option", { value: "gitbash", children: t("shell.gitbash") }),
-              /* @__PURE__ */ (0, import_jsx_runtime.jsx)("option", { value: "msys2", children: t("shell.msys2") }),
-              /* @__PURE__ */ (0, import_jsx_runtime.jsx)("option", { value: "wsl", children: t("shell.wsl") })
+              t("shell." + shell),
+              /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_dsh_client_ui_primitives.IconChevronDownOutline14, { className: "btChevron" })
             ]
           }
         )
-      ]
-    }
-  );
+      }
+    )
+  ] });
 }
 function apply(ctx) {
   ctx.effect(() => ctx.locale.register(SETTINGS_NS, { zh, en }), "bash-terminal: settings dictionaries");

package/dist/client.js

@@ -1,5 +1,5 @@
 window.__ModuleLoader__.load({
-	id: "dsh-bash-terminal-ts",
+	id: "dsh-bash-terminal",
 	factory: (require) => {
 		var module = { exports: {} };
 		var exports = module.exports;
@@ -28,13 +28,24 @@ __export(client_exports, {
   inject: () => inject
 });
 module.exports = __toCommonJS(client_exports);
+var import_react = require("react");
 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 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) {
+  const tag = document.createElement("style");
+  tag.dataset.plugin = "dsh-bash-terminal";
+  tag.dataset.pluginCss = "bash-terminal-row";
+  tag.textContent = ROW_CSS;
+  document.head.appendChild(tag);
+}
 var zh = {
   "shell.title": "\u9ED8\u8BA4\u7EC8\u7AEF",
-  "shell.description": "shell \u5DE5\u5177\u6267\u884C\u547D\u4EE4\u65F6\u4F7F\u7528\u7684\u7EC8\u7AEF\uFF08\u7531\u4F60\u51B3\u5B9A\uFF0CAI \u65E0\u6CD5\u66F4\u6539\uFF09",
+  "shell.description": "shell \u5DE5\u5177\u6267\u884C\u547D\u4EE4\u65F6\u4F7F\u7528\u7684\u7EC8\u7AEF",
   "shell.powershell": "PowerShell",
   "shell.gitbash": "Git Bash",
   "shell.msys2": "MSYS2",
@@ -42,7 +53,7 @@ var zh = {
 };
 var en = {
   "shell.title": "Default terminal",
-  "shell.description": "Terminal used by the shell tool (you control this; the AI cannot change it)",
+  "shell.description": "Terminal used by the shell tool",
   "shell.powershell": "PowerShell",
   "shell.gitbash": "Git Bash",
   "shell.msys2": "MSYS2",
@@ -52,49 +63,45 @@ var inject = ["slots", "locale", "settingsScope"];
 function ShellPreferenceRow({ t, useStore, setShell }) {
   const shell = useStore((s) => s.shell);
   const writable = useStore((s) => s.writable);
-  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
-    "div",
-    {
-      style: {
-        display: "flex",
-        alignItems: "center",
-        justifyContent: "space-between",
-        gap: 16,
-        padding: "12px 0"
-      },
-      children: [
-        /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { style: { minWidth: 0 }, children: [
-          /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { style: { fontSize: 14, fontWeight: 500, lineHeight: "22px", color: "var(--dsw-alias-label-primary, inherit)" }, children: t("shell.title") }),
-          /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { style: { fontSize: 12, lineHeight: "18px", opacity: 0.65 }, children: t("shell.description") })
-        ] }),
-        /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
-          "select",
+  const [open, setOpen] = (0, import_react.useState)(false);
+  const items = SHELLS.map((id) => ({ id, label: t("shell." + id) }));
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "btRow", children: [
+    /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "btRowText", children: [
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "btTitle", children: t("shell.title") }),
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "btDesc", children: t("shell.description") })
+    ] }),
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      import_dsh_client_ui_primitives.Menu,
+      {
+        open,
+        onClose: () => setOpen(false),
+        items,
+        selectedId: shell,
+        onSelect: (id) => {
+          setOpen(false);
+          setShell(id);
+        },
+        align: "end",
+        portal: true,
+        anchor: /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
+          "button",
           {
-            value: shell,
+            type: "button",
+            className: "btSelector",
+            "aria-haspopup": "menu",
+            "aria-expanded": open,
             disabled: !writable,
-            onChange: (e) => setShell(e.target.value),
-            style: {
-              fontSize: 14,
-              padding: "6px 10px",
-              borderRadius: 8,
-              border: "1px solid var(--dsw-alias-line-strong, #ccc)",
-              background: "var(--dsw-alias-bg-layer-2, #fff)",
-              color: "var(--dsw-alias-label-primary, inherit)",
-              outline: "none",
-              cursor: writable ? "pointer" : "not-allowed",
-              maxWidth: 180
-            },
+            onClick: () => setOpen(!open),
+            style: !writable ? { opacity: 0.5, cursor: "not-allowed" } : void 0,
             children: [
-              /* @__PURE__ */ (0, import_jsx_runtime.jsx)("option", { value: "powershell", children: t("shell.powershell") }),
-              /* @__PURE__ */ (0, import_jsx_runtime.jsx)("option", { value: "gitbash", children: t("shell.gitbash") }),
-              /* @__PURE__ */ (0, import_jsx_runtime.jsx)("option", { value: "msys2", children: t("shell.msys2") }),
-              /* @__PURE__ */ (0, import_jsx_runtime.jsx)("option", { value: "wsl", children: t("shell.wsl") })
+              t("shell." + shell),
+              /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_dsh_client_ui_primitives.IconChevronDownOutline14, { className: "btChevron" })
             ]
           }
         )
-      ]
-    }
-  );
+      }
+    )
+  ] });
 }
 function apply(ctx) {
   ctx.effect(() => ctx.locale.register(SETTINGS_NS, { zh, en }), "bash-terminal: settings dictionaries");

package/dsh.plugin.json

@@ -1,7 +1,7 @@
 {
-  "id": "dsh-bash-terminal-ts",
-  "name": "dsh-bash-terminal-ts",
-  "version": "0.2.5",
+  "id": "dsh-bash-terminal",
+  "name": "dsh-bash-terminal",
+  "version": "0.3.18",
   "description": {
     "en": "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.",
     "zh": "一个 shell 工具，可在 Windows 上通过 PowerShell / Git Bash / MSYS2 / WSL 执行命令，默认终端在 Web UI 设置中选择。"
@@ -13,7 +13,7 @@
   },
   "license": "MIT",
   "engines": {
-    "dsh": ">=0.1.2-rc.1 <0.2.0-0"
+    "dsh": ">=0.1.5-alpha.1 <0.2.0-0"
   },
   "components": {
     "host": "lib/index.js",

package/lib/client.js

@@ -0,0 +1,148 @@
+window.__ModuleLoader__.load({
+	id: "dsh-bash-terminal",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/client.tsx
+var client_exports = {};
+__export(client_exports, {
+  apply: () => apply,
+  inject: () => inject
+});
+module.exports = __toCommonJS(client_exports);
+var import_react = require("react");
+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 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) {
+  const tag = document.createElement("style");
+  tag.dataset.plugin = "dsh-bash-terminal";
+  tag.dataset.pluginCss = "bash-terminal-row";
+  tag.textContent = ROW_CSS;
+  document.head.appendChild(tag);
+}
+var zh = {
+  "shell.title": "\u9ED8\u8BA4\u7EC8\u7AEF",
+  "shell.description": "shell \u5DE5\u5177\u6267\u884C\u547D\u4EE4\u65F6\u4F7F\u7528\u7684\u7EC8\u7AEF",
+  "shell.powershell": "PowerShell",
+  "shell.gitbash": "Git Bash",
+  "shell.msys2": "MSYS2",
+  "shell.wsl": "WSL"
+};
+var en = {
+  "shell.title": "Default terminal",
+  "shell.description": "Terminal used by the shell tool",
+  "shell.powershell": "PowerShell",
+  "shell.gitbash": "Git Bash",
+  "shell.msys2": "MSYS2",
+  "shell.wsl": "WSL"
+};
+var inject = ["slots", "locale", "settingsScope"];
+function ShellPreferenceRow({ t, useStore, setShell }) {
+  const shell = useStore((s) => s.shell);
+  const writable = useStore((s) => s.writable);
+  const [open, setOpen] = (0, import_react.useState)(false);
+  const items = SHELLS.map((id) => ({ id, label: t("shell." + id) }));
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "btRow", children: [
+    /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "btRowText", children: [
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "btTitle", children: t("shell.title") }),
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "btDesc", children: t("shell.description") })
+    ] }),
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      import_dsh_client_ui_primitives.Menu,
+      {
+        open,
+        onClose: () => setOpen(false),
+        items,
+        selectedId: shell,
+        onSelect: (id) => {
+          setOpen(false);
+          setShell(id);
+        },
+        align: "end",
+        portal: true,
+        anchor: /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
+          "button",
+          {
+            type: "button",
+            className: "btSelector",
+            "aria-haspopup": "menu",
+            "aria-expanded": open,
+            disabled: !writable,
+            onClick: () => setOpen(!open),
+            style: !writable ? { opacity: 0.5, cursor: "not-allowed" } : void 0,
+            children: [
+              t("shell." + shell),
+              /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_dsh_client_ui_primitives.IconChevronDownOutline14, { className: "btChevron" })
+            ]
+          }
+        )
+      }
+    )
+  ] });
+}
+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 store = (0, import_dsh_client_store.defineStore)({
+    init: () => ({ shell: "powershell", revision: -1, writable: false }),
+    actions: {
+      sync: (d, shell, revision, writable) => {
+        if (revision !== void 0 && revision <= d.revision) return;
+        if (shell !== void 0) d.shell = shell;
+        if (revision !== void 0) d.revision = revision;
+        if (writable !== void 0) d.writable = writable;
+      }
+    }
+  });
+  let bound;
+  const push = (snap) => {
+    bound?.sync(snap.value?.defaultShell, snap.revision, snap.writable);
+  };
+  ctx.slots.inject(
+    "settings.general.item",
+    () => ctx.slots.register(
+      {
+        name: "settings.general.item",
+        id: "bash-terminal-shell",
+        order: 20,
+        store,
+        locale: SETTINGS_NS,
+        inject: (actions) => {
+          bound = actions;
+          push(scope.getSnapshot());
+          return { setShell: (value) => void scope.set("defaultShell", value) };
+        }
+      },
+      ShellPreferenceRow
+    ),
+    "bash-terminal: settings row"
+  );
+  ctx.effect(() => scope.subscribe(() => push(scope.getSnapshot())), "bash-terminal: settings watch");
+}
+
+		return module.exports;
+	}
+});

package/lib/dsh-types.d.ts

@@ -241,7 +241,7 @@ export interface ApprovalSeam {
     request(input: unknown): Promise<unknown>;
 }
 /**
- * The structural context face dsh-bash-terminal-ts programs against: the union
+ * The structural context face dsh-bash-terminal programs against: the union
  * of every `ctx.*` member touched by src/index.ts and src/terminal.ts.
  */
 export interface BashTerminalContext {

package/lib/index.d.ts

@@ -31,17 +31,18 @@ export declare function candidatePwshPaths(env?: NodeJS.ProcessEnv): string[];
  */
 export declare function candidateGitBashPaths(env?: NodeJS.ProcessEnv): string[];
 /**
- * MSYS2 locations, in preference order: the real `bash.exe` under usr\bin first,
- * then bin\bash.exe, and `msys2.exe` dead last.
+ * 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, so a spawn with piped stdio returns exit 0 with
- * zero bytes on both stdout and stderr (measured on MSYS2 with bash 5.3.15).
- * Keeping it in the list only as a last-resort fallback preserves the path the
- * config docs reference, but a working bash.exe always wins.
+ * zero bytes on both stdout and stderr (measured on this machine against
+ * MSYS2 with bash 5.3.15). Keeping it in the list only as a last-resort
+ * fallback preserves the path the config docs reference, but a working
+ * bash.exe always wins.
  *
- * MSYS2 uses the same Cygwin/MSYS2 runtime as Git Bash, so it cannot run under
- * the DSH Windows ACL restricted-token sandbox.
+ * MSYS2 uses the same Cygwin/MSYS2 runtime as Git Bash, so it cannot run
+ * under the DSH Windows ACL restricted-token sandbox.
  */
 export declare function candidateMsys2Paths(env?: NodeJS.ProcessEnv): string[];
 export declare function defaultWslPath(env?: NodeJS.ProcessEnv): string;
@@ -52,16 +53,16 @@ export declare function resolveAllPaths(config?: PathConfig, env?: NodeJS.Proces
 export declare function buildArgv(shell: string, command: string, paths: ResolvedPaths, distro?: string): Array<string | undefined>;
 /**
  * Merge the DSH_* environment over the process environment. For WSL, only
- * variables explicitly listed in WSLENV cross the boundary, so every DSH_* key is
- * appended to it (WSLENV is a `:` separated VAR[/flag] list).
+ * variables explicitly listed in WSLENV cross the boundary, so every DSH_*
+ * key is appended there — and the list is *layered onto* whatever WSLENV the
+ * host already had (Windows Terminal exports e.g. `WT_SESSION:WT_PROFILE_ID:`),
+ * never rebuilt from scratch: WSLENV is an allow-list, so dropping the
+ * inherited entries would silently stop them crossing into WSL.
  *
- * WSLENV usually already exists for reasons unrelated to us -- Windows Terminal
- * exports e.g. `WT_SESSION:WT_PROFILE_ID:` -- so the list is layered rather than
- * rebuilt, or those entries would be silently dropped from every WSL call.
- * Callers that spawn through a seam which replaces the parent environment
- * wholesale (the PTY path) must pass the inherited value explicitly.
- *
- * @param inheritedWslenv - the WSLENV the child would otherwise inherit.
+ * @param inheritedWslenv - the ambient WSLENV to layer onto. Callers that
+ *   replace the child environment wholesale (the PTY path) must pass
+ *   `process.env.WSLENV` explicitly, because the ambient value is not visible
+ *   through `dshEnv`.
  */
 export declare function buildEnv(shell: string, dshEnv?: Record<string, string>, inheritedWslenv?: string | undefined): Record<string, string | undefined>;
 export interface SpawnResolution {