dsh-plugin-shell-selector 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tofu-zyc (TOFU BOX)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,117 @@
+# dsh-plugin-shell-selector
+
+在 Web 界面 **设置 → Shell** 页面选择 AI 执行命令时使用的 shell。
+
+本插件**不实现 shell 执行器**，也不覆盖任何内置行。它只做两件事：读取现有执行器的实时事实，以及通过 `settings.mutate('pwsh-sandbox', …)` 写入执行器**本来就支持**的 `pwshPath` volatile Config 字段。
+
+## 选项与真实状态
+
+| 选项 | 作用 | 本机只读探测结果 |
+| --- | --- | --- |
+| 自动（保留当前默认） | 清除用户层 `pwshPath`，回落到内置解析顺序 | 可用 → `…\WindowsApps\Microsoft.PowerShell_7.6.6.0_x64__8wekyb3d8bbwe\pwsh.exe`（PowerShell 7.6.6） |
+| PowerShell 7 | 写入解析到的 `pwsh.exe` | 可用 → 同上 |
+| Windows PowerShell 5.1 | 写入 `%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe` | 可用（页面显示 5.1 语法兼容提示） |
+| Git Bash | — | **不可选**：已检测到 `C:\Program Files\Git\bin\bash.exe`，但受限运行尚未验证 |
+
+## 为什么改动是真实的
+
+`@deepseek-ai/dsh-pwsh-local` 在 `pwsh-sandbox` profile 条目读取其 volatile `pwshPath`，并在后续 `argv()` 调用时解析该值。因此通过设置表单更新配置后，下一次 AI 命令便使用所选程序，**无需重启、无需替换执行器**。
+
+由此保留的行为全部是内置实现：
+
+- 沙箱（`ctx.sandbox` 经 `dsh-pwsh-sandbox` 包装 argv）、审批、workdir、timeout、取消、退出码、stdout/stderr、后台 jobs 一律不变；
+- 插件不调用 `child_process`，不拼接 shell 字符串，不添加 argv 前缀，不启停任何行；
+- 执行中的进程不受影响：它们的 argv 在启动时已确定，改动只作用于之后启动的命令。
+
+`probe()` 报告的"当前实际执行"直接来自 `ctx.shell.pwshPath`（执行器自己解析出的路径），不是本插件的二次推导。
+
+### 校验
+
+执行器把配置的 `pwshPath` 视为可信、自身不校验，所以校验由本插件在**写入之前**完成：
+
+- 用 `lstat` 判定（与内置 `candidateExists` 同语义），因此 Microsoft Store 执行别名（symlink）被正确接受；
+- 拒绝目录、缺失、空路径；
+- 含空格的路径（如 `C:\Program Files\...`）作为单个 argv 元素传递，不做任何字符串插值。
+
+若清除 `pwshPath`（选"自动"）后内置解析仍失败，`shell.pwshPath` 会回落到按 PATH 解析 `pwsh` —— 与内置行为一致。
+
+### 已知限制：自动档的预览路径
+
+"自动"档的预览由本插件按内置解析顺序推导（`pwsh7Locations` 加 5.1 回落），**没有考虑组合层（composition base）的 `pwshPath`**。若某个部署在 `pwsh-sandbox` 行配置里写死了 `pwshPath`，选"自动"实际会回落到那个组合层值，而预览显示的是探针推导值 —— 两者会不一致，有误导风险。
+
+当前部署未在组合层设置 `pwshPath`，因此两者一致，暂无影响。此问题留待后续修正（例如读取 `describe()` 的 `base` 层并与探针结果区分显示）。
+
+注意页面上的"当前实际执行"始终取自 `ctx.shell.pwshPath`，所以即使预览有偏差，**生效值显示的仍是真值**。
+
+## 语法提示一致性
+
+`pwsh` 工具的名称与描述是静态的，运行期没有接缝可改。本版本提供或允许选择的三档**全部是 PowerShell**，因此工具名 `pwsh`、`pwsh -Command` 与 `$env:NAME` 提示始终成立。
+
+唯一的偏差是 PowerShell 5.1 缺少 `&&`、`||`、三元 `? :` 与 `??`。这一点通过两种方式如实说明，**不修改工具本身**：
+
+1. 页面在 5.1 选项下始终显示兼容提示；
+2. 当生效 shell 确实是 5.1 时，注册一条运行时上下文（`shell-selector/dialect`）告知模型真实方言；其余情况返回空字符串，不产生任何上下文。
+
+## Git Bash：为什么不可选
+
+三条独立事实：
+
+1. **win32 上没有 bash 执行器。** `@deepseek-ai/dsh-base` 的 `bash-sandbox` / `tool-bash` 行在 Windows 上 `disabled`，而 `ctx.shell` 每个 context 只允许一个实现（第二个注册直接抛错）。真要支持必须自写执行器并关掉 `pwsh-sandbox` 行。
+2. **PATH 上的 `bash` 是 WSL 启动器。** 本机 `bash` → `C:\WINDOWS\system32\bash.exe`，它在另一个文件系统命名空间里执行，等于用 WSL VM 边界替换 DSH 文件沙箱。因此本插件**只按 Git for Windows 显式路径解析，从不查 PATH**（有专门的单元测试守住这一点）。
+3. **受限运行未经验证。** Windows runner（`dsh-sandbox-windows-acl`）本身是 argv 无关且 fail-closed 的（`[node, runner.js, --workspace, --temp, --mode, --, <argv…>]`；任何 runner 侧失败打印 `windows-acl-run:` 并 exit 127，绝不无沙箱 spawn），所以它*能*包住 `bash.exe -c`。但受限令牌只授予工作区与私有临时目录写权限，且两种受限模式下程序都无法打开命名管道，而 MSYS2 的 `fork()` 模拟依赖命名管道。
+
+在没有证据之前，Git Bash 保持**禁用并显示原因**，绝不以无沙箱方式运行，也绝不把 `pwshPath` 指向 bash 假装切换。
+
+### 状态：待验证，且当前没有可执行的探测方案
+
+曾有一版独立探测脚本（`tools/gitbash-sandbox-probe.mjs`），**已被删除且从未执行**。它不安全，已确认的问题：
+
+- 以"stderr 里没有 `windows-acl-run` 签名"判定成功不可靠 —— 非零退出、`spawnError`、超时都可能被误判为通过；
+- `child.kill()` 在 Windows 上无法可靠清理整个进程树，并可能跳过 runner 的 DACL 撤销；
+- 它以整个仓库作为 `--workspace`，且未清理临时目录、未把 Bash 的临时目录指向专有 temp。
+
+更关键的是：**`ctx.sandbox` 与 `ctx.subprocess` 只存在于宿主进程内，外部脚本无法安全取得。** 因此不存在安全的独立脚本实现，本仓库不再提供探测脚本，也**不会运行任何裸命令冒充安全验证**。
+
+Git Bash 的状态是**待验证**：既不是"不可用"，也不是"已完成"。
+
+将来若要真正验证，必须在宿主内走生产 API（此处仅记录约束，**未实现、未验证**）：`ctx.sandbox.confine(['<gitBash>', '-c', <script>], policy, signal)` 取得受管 argv（ACL 授权与撤销归沙箱 provider），再交给 `ctx.subprocess.spawn({ argv, cwd: <专用 probe workspace>, stdio, graceMs, signal })`（进程树取消归受管 subprocess，不使用裸 kill）；成功判定必须是 `exitCode === 0` **且**每个阶段的确切 marker 都出现，超时按真实 deadline 标志判定；probe workspace 与 temp 都必须是专用目录，不复用仓库。这需要在插件上增加一个仅用于验证的 Remote，超出当前版本范围。
+
+即使将来探测通过，开放 Git Bash 还需要另一步：**语法诚实性**。`tool-pwsh` 在 `apply()` 时一次性构建 schema，`tool-bash` 行在 win32 被禁用，且换行是组合期决定、无法随设置热切。要让模型拿到 bash 语法，必须新增一个按设置重建 schema 的 tool。
+
+## 界面语言
+
+页面跟随 **设置 → 通用 → 语言** 的当前语言（`@deepseek-ai/dsh-client-locale` 的 active locale），不硬编码中文；`bind` 在调用时读取 active locale，切换语言后页面与菜单项标签都会跟着变。
+
+字典按 **locale id** 注册。浏览器端内置 id 是 `zh` 与 `en`（`LOCALE_IDS`），`bind(ns)` 沿 active locale 的回退链查找（`zh` → `en`）。注册时会枚举实时 catalog，因此语言包引入的 `zh-CN`、`zh-Hans` 等变体同样拿到中文字典。
+
+> **已修复的运行缺陷**：早先版本把中文字典注册在 `zh-CN` 下。active id 实际是 `zh`，该字典不可达，回退链于是落到英文字典，界面整体显示英文。现在以 `zh` 为准。注意 `dsh-client-locale` 内部把 `document.lang` 的 `zh` 映射为 `zh-CN`，那是该插件的 DOM 行为，**不能**当作字典键使用。
+
+## 安装
+
+由 Lead 统一安装（本插件不自行安装）：
+
+```
+plugin_manager action=install_bundle target=D:\program\dsh-plugins\dsh-plugin-shell-selector
+```
+
+依赖 `@deepseek-ai/dsh-typert-protocol`（workspace 内已可解析），无构建脚本、无安装脚本。
+
+## 测试
+
+```sh
+npm test        # node --test tests/*.test.mjs
+```
+
+**已实际执行**：30 个用例全部通过。覆盖候选顺序、含空格路径、目录/缺失/Store 别名判定、WSL 启动器拒绝、显式 PS7 不静默回落 5.1、Git Bash 始终不可选、非 Windows 平台、当前选项派生、四种拒绝路径均不产生写入、`mutate` 参数与 revision、`ctx.shell.pwshPath` 优先于二次推导、方言提示条件、两侧契约（Remote 方法名与客户端寻址一致、`settings.section` 注册参数、中英文字典键完全对齐且覆盖宿主可能发出的每个 key），以及**中文 locale 渲染与回退**（见下）。
+
+这些用例不是静态检查：测试里的 locale 替身复刻了真实的回退规则（内置 id 为 `zh`/`en`，`zh` 回退到 `en`，`bind` 沿 **active** locale 的回退链查找）。把实现改回"只注册 `zh-CN`"会使 6 个用例失败，其中就有"zh 生效时必须渲染中文而非英文"—— 该回归已被实际验证过。
+
+探测脚本已删除，未执行任何探测。
+
+## 尚未验证
+
+- `pwsh-sandbox` 条目已在 `settings.describe()` 中显示，隔离实例 3099 的设置页已通过无头浏览器在 5.1 与自动之间切换并恢复；
+- 生产安装后的实时行为尚需切换后验证：`ctx.shell.pwshPath` 是否立即变化，以及下一条命令是否真的换了可执行文件；
+- 页面在隔离 0.1.7 浏览器中已无 pageerror；中文显示由中英字典单测覆盖。
+
+中文界面已在隔离的 0.1.7-alpha.2 无头浏览器中确认可用。生产切换后仍应抽查下一条命令的实际执行器，不能用界面选择代替执行验证。

package/client.js

@@ -0,0 +1,263 @@
+window.__ModuleLoader__.load({
+  id: 'dsh-plugin-shell-selector',
+  factory: require => {
+    const React = require('react')
+    const h = React.createElement
+    const NS = 'shell-selector'
+    const SERVICE = 'shellSelector'
+
+    // Every key exists in both dictionaries: the page never renders a missing
+    // translation, and a host-supplied Chinese fallback is only used when the
+    // host reported no key at all.
+    //
+    // Dictionaries are keyed by LOCALE ID. `@deepseek-ai/dsh-client-locale` ships
+    // `zh` and `en` (`LOCALE_IDS`), and `bind(ns)` walks the active locale's
+    // fallback chain — `zh` -> `en`. A dictionary registered only under a region
+    // tag such as `zh-CN` therefore matches nothing, and Chinese silently renders
+    // as English. `zh` is the id that must exist; region variants are covered by
+    // registration-time enumeration below.
+    const CHINESE = {
+        title: 'Shell',
+        intro: '选择 AI 执行命令时使用的 shell。改动会真实作用于之后启动的命令，并影响本机所有会话。',
+        effective: '当前实际执行',
+        sandbox: '沙箱默认模式',
+        refresh: '刷新',
+        unavailable: '不可用',
+        applying: '正在切换…',
+        'notice.applied': '已切换。下一条命令将使用所选 shell。',
+        custom: '当前值由本页之外的配置写入，本页不会覆盖它；选择任一项即可接管。',
+        readonly: '设置存储不可写，无法切换。',
+        absent: '未找到 shell 执行器，请确认 PowerShell 执行器已加载后重启。',
+        retry: '重试',
+        'option.auto': '自动（保留当前默认）',
+        'option.pwsh7': 'PowerShell 7',
+        'option.pwsh5': 'Windows PowerShell 5.1',
+        'option.gitbash': 'Git Bash',
+        'reason.windowsOnly': 'Shell 选择器仅适用于 Windows 部署。',
+        'reason.autoPathLookup': '未找到已知安装位置，将按 PATH 解析 pwsh。',
+        'reason.autoLanded7': '自动优先使用 PowerShell 7。',
+        'reason.autoLanded51': '未安装 PowerShell 7，自动回落到 Windows PowerShell 5.1。',
+        'reason.noPwsh7': '未检测到 PowerShell 7（pwsh.exe）。',
+        'reason.noPwsh5': '未检测到 Windows PowerShell 5.1（%SystemRoot%\\System32\\WindowsPowerShell\\v1.0\\powershell.exe）。',
+        'reason.noGitBash': '未检测到 Git for Windows（%ProgramFiles%\\Git\\bin\\bash.exe）。',
+        'reason.gitBashUnverified': '已安装，但尚未验证它能在 Windows 文件沙箱下受限运行，因此暂不可选。',
+        'reason.wslBash': '解析结果是 WSL 启动器而非 Git Bash，已拒绝。',
+        'reason.pwsh5Dialect': 'PowerShell 5.1 语法与 7 不同，见下方兼容提示。',
+        'note.running': '已在运行的后台命令不受影响：它们仍使用启动时的 shell。改动只作用于之后启动的命令。',
+        'note.pwsh5': '兼容提示（必须阅读）：Windows PowerShell 5.1 不支持 && 与 || 管道链、三元运算符 ? : 和 ?? 空合并运算符。命令与脚本需改用 ; 串联，并用 if (...) { } else { } 分支。',
+        'note.gitbash': '为什么不可选：Windows 文件沙箱以受限令牌运行命令，只授予工作区与私有临时目录写权限，且两种受限模式下程序都无法打开命名管道，而 MSYS2 的 fork 模拟依赖命名管道。另外 PATH 上的 bash 是 WSL 启动器（另一个文件系统命名空间），不是 Git Bash，因此本插件只按 Git for Windows 显式路径解析。在受限运行验证完成之前不会提供该选项，也不会以无沙箱方式运行。',
+    }
+
+    const ENGLISH = {
+        title: 'Shell',
+        intro: 'Choose the shell the AI runs commands in. The change takes effect for commands started afterwards and applies to every session on this machine.',
+        effective: 'Currently executing',
+        sandbox: 'Default sandbox mode',
+        refresh: 'Refresh',
+        unavailable: 'Unavailable',
+        applying: 'Switching…',
+        'notice.applied': 'Switched. The next command uses the selected shell.',
+        custom: 'The current value was written outside this page and is not overwritten here; picking any option takes it over.',
+        readonly: 'The settings store is not writable, so the shell cannot be switched.',
+        absent: 'No shell executor was found. Confirm the PowerShell executor is loaded, then restart.',
+        retry: 'Retry',
+        'option.auto': 'Automatic (keep the current default)',
+        'option.pwsh7': 'PowerShell 7',
+        'option.pwsh5': 'Windows PowerShell 5.1',
+        'option.gitbash': 'Git Bash',
+        'reason.windowsOnly': 'The shell selector applies to Windows deployments only.',
+        'reason.autoPathLookup': 'No known install location was found, so `pwsh` resolves through PATH.',
+        'reason.autoLanded7': 'Automatic prefers PowerShell 7.',
+        'reason.autoLanded51': 'PowerShell 7 is not installed, so automatic falls back to Windows PowerShell 5.1.',
+        'reason.noPwsh7': 'PowerShell 7 (pwsh.exe) was not detected.',
+        'reason.noPwsh5': 'Windows PowerShell 5.1 was not detected (%SystemRoot%\\System32\\WindowsPowerShell\\v1.0\\powershell.exe).',
+        'reason.noGitBash': 'Git for Windows was not detected (%ProgramFiles%\\Git\\bin\\bash.exe).',
+        'reason.gitBashUnverified': 'Installed, but it has not been verified to run confined under the Windows file sandbox, so it is not selectable.',
+        'reason.wslBash': 'The resolved executable was the WSL launcher rather than Git Bash, so it was refused.',
+        'reason.pwsh5Dialect': 'PowerShell 5.1 syntax differs from 7; see the compatibility note below.',
+        'note.running': 'Background commands already running are unaffected: they keep the shell they started with. Only commands started afterwards change.',
+        'note.pwsh5': 'Compatibility note (required reading): Windows PowerShell 5.1 has no `&&` or `||` pipeline chains, no ternary `? :`, and no `??`. Chain with `;` and branch with `if (...) { } else { }`.',
+        'note.gitbash': 'Why this is unavailable: the Windows file sandbox runs commands under a restricted token whose write capabilities cover only the workspace and a private temp directory, and programs cannot open named pipes in either confined mode, while MSYS2 fork emulation depends on them. The `bash` on PATH is also the WSL launcher (a separate filesystem namespace), not Git Bash, so only explicit Git for Windows paths are resolved. The option stays unavailable until confined execution is verified, and it is never run unsandboxed.',
+    }
+
+    /** The locale ids the browser client ships; `zh` is mandatory, not `zh-CN`. */
+    const BUILT_IN_LOCALE_IDS = ['zh', 'en']
+
+    /** Pick the dictionary a locale id should receive, by its primary subtag. */
+    function dictionaryFor(id) {
+      const primary = String(id).toLowerCase().split('-')[0]
+      if (primary === 'zh') return CHINESE
+      if (primary === 'en') return ENGLISH
+      return undefined
+    }
+
+    /**
+     * Register the dictionary pair for the built-in ids plus every id the live
+     * catalog exposes, so a language-pack locale such as `zh-CN` or `zh-Hans`
+     * resolves Chinese instead of falling through to English.
+     * @returns a disposer removing every registration this call made.
+     */
+    function registerDictionaries(locale) {
+      const ids = new Set(BUILT_IN_LOCALE_IDS)
+      for (const definition of locale.getSnapshot().locales) {
+        if (definition !== null && typeof definition === 'object' && typeof definition.id === 'string') ids.add(definition.id)
+      }
+      const disposers = []
+      for (const id of ids) {
+        const dict = dictionaryFor(id)
+        if (dict !== undefined) disposers.push(locale.register(NS, id, dict))
+      }
+      return () => { for (const dispose of disposers) dispose() }
+    }
+
+    const css = `
+.ss-page{display:flex;flex-direction:column;gap:14px;padding:4px 0 24px;color:inherit}
+.ss-page fieldset{border:1px solid #8886;border-radius:10px;padding:14px;min-width:0;display:flex;flex-direction:column;gap:10px}
+.ss-page legend{font-weight:600;padding:0 6px}
+.ss-option{display:flex;gap:10px;align-items:flex-start;padding:10px;border:1px solid #8885;border-radius:8px;cursor:pointer}
+.ss-option-off{opacity:.6;cursor:default}
+.ss-option input{margin-top:4px;flex:none}
+.ss-option-body{display:flex;flex-direction:column;gap:5px;min-width:0;flex:1}
+.ss-option-head{display:flex;align-items:center;gap:8px;flex-wrap:wrap}
+.ss-badge{font-size:11px;border:1px solid #8888;border-radius:999px;padding:1px 7px;opacity:.85}
+.ss-path{font-size:12px;overflow-wrap:anywhere;opacity:.9}
+.ss-note{font-size:12px;opacity:.78;line-height:1.6;margin:0}
+.ss-warn{color:#d5533d}
+.ss-error{color:#d5533d;white-space:pre-wrap;font-size:12px}
+.ss-ok{font-size:12px;opacity:.85}
+.ss-head{display:flex;flex-direction:column;gap:5px}
+.ss-actions{display:flex;gap:8px;flex-wrap:wrap}
+.ss-page button{padding:7px 11px;border:1px solid #8888;border-radius:7px;background:transparent;color:inherit;cursor:pointer;font:inherit}
+.ss-page button:disabled{opacity:.5;cursor:default}
+`
+
+    /**
+     * The Remote envelope: `{ ok: true, value }` or `{ ok: false, error }`.
+     * Unwrapped once here so every caller sees the value or a thrown error.
+     */
+    const unwrap = response => {
+      if (!response || response.ok !== true) throw new Error(response?.error?.message ?? '请求失败')
+      return response.value
+    }
+
+    /**
+     * Re-render on language change and return the current translator. The
+     * snapshot is read through the store so a switch is reflected immediately.
+     */
+    function useTranslate(locale) {
+      const subscribe = React.useCallback(callback => locale.subscribe(callback), [locale])
+      const snapshot = React.useCallback(() => locale.getSnapshot(), [locale])
+      React.useSyncExternalStore(subscribe, snapshot, snapshot)
+      return locale.bind(NS)
+    }
+
+    function Page({ remote, call, locale, close }) {
+      const translate = useTranslate(locale)
+      const t = (key, fallback) => {
+        const value = translate(key)
+        return value === undefined || value === null || value === '' || value === key ? (fallback ?? key) : value
+      }
+      const [view, setView] = React.useState(null)
+      const [error, setError] = React.useState('')
+      const [notice, setNotice] = React.useState('')
+      const [busy, setBusy] = React.useState('')
+
+      const refresh = React.useCallback(async () => {
+        const next = await call('probe', {})
+        setView(next)
+        return next
+      }, [call])
+
+      React.useEffect(() => {
+        let live = true
+        refresh().then(() => { if (live) setError('') }, problem => { if (live) setError(problem.message) })
+        return () => { live = false }
+      }, [refresh])
+
+      async function choose(kind) {
+        if (view === null) return
+        setBusy(kind); setError(''); setNotice('')
+        try {
+          const next = await call('select', { kind, revision: view.revision })
+          setView(next)
+          setNotice(t('notice.applied'))
+        } catch (problem) {
+          setError(problem.message)
+        } finally {
+          setBusy('')
+        }
+      }
+
+      async function retry() {
+        setError(''); setNotice('')
+        try { await refresh() } catch (problem) { setError(problem.message) }
+      }
+
+      if (view === null) {
+        return h('div', { className: 'ss-page' },
+          h('p', { className: 'ss-note' }, error === '' ? t('applying') : error),
+          error === '' ? null : h('div', { className: 'ss-actions' }, h('button', { onClick: () => void retry() }, t('retry'))))
+      }
+
+      const locked = view.writable !== true || busy !== ''
+      const rows = view.options.map(option => {
+        const selected = view.current.kind === option.kind
+        const reason = option.reasonKey ? t(option.reasonKey, option.reason) : option.reason
+        const detail = option.detailKey ? t(option.detailKey) : ''
+        const notes = []
+        if (detail !== '') notes.push(h('p', { className: 'ss-note', key: 'detail' }, detail))
+        if (reason) notes.push(h('p', { className: 'ss-note ss-warn', key: 'reason' }, reason))
+        if (option.kind === 'pwsh5') notes.push(h('p', { className: 'ss-note', key: 'pwsh5' }, t('note.pwsh5')))
+        if (option.kind === 'gitbash') notes.push(h('p', { className: 'ss-note', key: 'gitbash' }, t('note.gitbash')))
+        return h('label', { key: option.kind, className: option.available ? 'ss-option' : 'ss-option ss-option-off' },
+          h('input', {
+            type: 'radio',
+            name: 'shell-kind',
+            checked: selected,
+            disabled: !option.available || locked,
+            onChange: () => void choose(option.kind),
+          }),
+          h('div', { className: 'ss-option-body' },
+            h('div', { className: 'ss-option-head' },
+              h('strong', null, t(option.labelKey, option.kind)),
+              option.available ? null : h('span', { className: 'ss-badge' }, t('unavailable')),
+              option.path ? h('code', { className: 'ss-path' }, option.path) : null),
+            notes.length > 0 ? h('div', null, notes) : null))
+      })
+
+      return h('div', { className: 'ss-page' },
+        h('p', { className: 'ss-note' }, t('intro')),
+        h('div', { className: 'ss-head' },
+          h('p', { className: 'ss-note' }, `${t('effective')}: `, h('code', null, view.executable ?? '—')),
+          h('p', { className: 'ss-note' }, `${t('sandbox')}: `, h('code', null, view.sandboxMode ?? '—')),
+          view.current.kind === 'custom' ? h('p', { className: 'ss-note ss-warn' }, t('custom')) : null,
+          view.namespaceRegistered !== true ? h('p', { className: 'ss-note ss-warn' }, t('absent')) : null,
+          view.writable !== true ? h('p', { className: 'ss-note ss-warn' }, t('readonly')) : null,
+          view.supported !== true ? h('p', { className: 'ss-note ss-warn' }, t('reason.windowsOnly')) : null),
+        h('fieldset', null, h('legend', null, t('title')), ...rows),
+        h('p', { className: 'ss-note' }, t('note.running')),
+        busy === '' ? null : h('p', { className: 'ss-ok' }, t('applying')),
+        notice === '' ? null : h('p', { className: 'ss-ok', role: 'status' }, notice),
+        error === '' ? null : h('p', { className: 'ss-error', role: 'alert' }, error),
+        h('div', { className: 'ss-actions' },
+          h('button', { disabled: busy !== '', onClick: () => void retry() }, t('refresh')),
+          typeof close === 'function' ? h('button', { onClick: () => close() }, t('title')) : null))
+    }
+
+    return {
+      inject: ['slots', 'connection', 'remote', 'remote.settings', 'locale'],
+      apply(ctx) {
+        const style = document.createElement('style')
+        style.textContent = css
+        document.head.appendChild(style)
+        ctx.effect(() => () => style.remove())
+        ctx.effect(() => registerDictionaries(ctx.locale))
+        const t = ctx.locale.bind(NS)
+        const call = async (method, args) => unwrap(await ctx.connection.rpc.call('/api', `${SERVICE}/${method}`, { args }))
+        ctx.slots.inject('settings.section', () => ctx.slots.register(
+          { name: 'settings.section', id: NS, order: 14, label: () => t('title') },
+          props => h(Page, { ...props, remote: ctx.remote, call, locale: ctx.locale })))
+      },
+    }
+  },
+})

package/cordis.patch.yml

@@ -0,0 +1,8 @@
+# One insert over the existing profile composition. This bundle deliberately does
+# NOT override, disable, or replace any shipped row: the shell executor row
+# (`pwsh-sandbox`) keeps providing `ctx.shell`, and this plugin only reads its
+# live facts and writes the already-supported `shell.pwshPath` setting.
+- insert:
+    - id: shell-selector
+      name: dsh-plugin-shell-selector
+      inject: [settings]

package/index.js

@@ -0,0 +1,110 @@
+/**
+ * Host half of the Shell selector.
+ *
+ * This plugin owns no execution path. It reads the live facts off the composed
+ * shell executor (`ctx.shell`) and the settings service, and its only write is
+ * the already-supported `shell.pwshPath` field, which `dsh-pwsh-local` re-resolves
+ * in its own `onChange` hook. Consequently the sandbox, approval, workdir,
+ * timeout, cancellation, exit/stdout/stderr, and background-job behaviour are the
+ * shipped ones, untouched — no `child_process`, no argv prefix, no row override.
+ *
+ * Command syntax stays honest too: the `pwsh` tool schema is correct for every
+ * option this version can select. When the effective shell is Windows PowerShell
+ * 5.1 the executor's own facts no longer match the schema's PowerShell 7
+ * examples, so one runtime-context line states the real dialect. It adds nothing
+ * for PowerShell 7, and it does not modify the tool.
+ *
+ * @module dsh-plugin-shell-selector
+ */
+
+import { RemoteError, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol'
+import { ShellSelectorError, dialectHint, executeSelection, probeShells } from './shells.js'
+
+export const name = 'dsh-plugin-shell-selector'
+
+/** PowerShell sandbox Config is read through the profile-entry settings service; the executor is an optional read. */
+export const inject = ['settings']
+
+/** Remote namespace; the page calls `/api` with `<SERVICE>/<method>`. */
+export const SERVICE = 'shellSelector'
+
+/** Placement of the dialect note among the registered runtime contexts. */
+const DIALECT_CONTEXT_ORDER = 45
+
+/** Map a planning failure onto the Remote envelope the client unwraps. */
+function toRemoteError(error) {
+  if (error instanceof ShellSelectorError) return new RemoteError(error.code, error.message)
+  return new RemoteError('shell-selector/failed', error instanceof Error ? error.message : String(error))
+}
+
+/**
+ * Remote surface behind the settings page. Constructing it registers
+ * `ctx.shellSelector`; the page holds no direct service access.
+ */
+export class ShellSelectorService extends TypertRemoteService {
+  /** @param ctx - the plugin context carrying the `settings` injection. */
+  constructor(ctx) {
+    super(ctx, SERVICE)
+  }
+
+  /**
+   * Live executor facts plus the selectable options.
+   * @returns the page payload; `executable` is the path the next command will use.
+   */
+  probe() {
+    return probeShells({
+      settings: this.ctx.settings,
+      shell: this.ctx.get('shell'),
+      env: process.env,
+      platform: process.platform,
+    })
+  }
+
+  /**
+   * Validate one requested option, write it, and return the refreshed payload.
+   * @param kind - `auto`, `pwsh7`, `pwsh5`, or `gitbash`.
+   * @param revision - the `shell` namespace revision the caller read.
+   * @returns the payload after the write.
+   */
+  async select(kind, revision) {
+    try {
+      await executeSelection({
+        kind,
+        revision,
+        settings: this.ctx.settings,
+        env: process.env,
+        platform: process.platform,
+      })
+    } catch (error) {
+      throw toRemoteError(error)
+    }
+    return this.probe()
+  }
+}
+
+Object.defineProperty(ShellSelectorService.prototype, '@deepseek-ai/dsh-typert-protocol/remote-methods', {
+  value: Object.freeze({
+    version: 1,
+    methods: Object.freeze(['probe', 'select'].map(method =>
+      Object.freeze({ method, invocation: Object.freeze({ kind: 'direct' }) }))),
+  }),
+})
+
+/**
+ * Register the Remote service and the dialect context.
+ * @param ctx - plugin context.
+ */
+export function apply(ctx) {
+  // Constructing the service is the registration; nothing else needs the handle.
+  new ShellSelectorService(ctx)
+
+  const systemPrompt = ctx.get('systemPrompt')
+  if (systemPrompt === undefined) return
+  // An empty string renders as no context at all, so this contributes only while
+  // the effective shell really is Windows PowerShell 5.1.
+  ctx.effect(() => systemPrompt.context({
+    name: 'shell-selector/dialect',
+    order: DIALECT_CONTEXT_ORDER,
+    text: () => dialectHint(ctx.get('shell')?.pwshPath, process.env),
+  }))
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "dsh-plugin-shell-selector",
+  "version": "0.1.0",
+  "description": "在 设置 → Shell 页面选择 AI 命令执行所用的 shell（自动 / PowerShell 7 / Windows PowerShell 5.1 / Git Bash），带真实可用性检测。",
+  "license": "MIT",
+  "keywords": ["dsh-plugin", "deepseek-harness", "dsh", "shell", "powershell"],
+  "publishConfig": { "registry": "https://registry.npmjs.org" },
+  "repository": { "type": "git", "url": "git+https://github.com/tofu-zyc/dsh-plugin-tofu-box.git", "directory": "dsh-plugin-shell-selector" },
+  "bugs": { "url": "https://github.com/tofu-zyc/dsh-plugin-tofu-box/issues" },
+  "homepage": "https://github.com/tofu-zyc/dsh-plugin-tofu-box/tree/main/dsh-plugin-shell-selector",
+  "type": "module",
+  "main": "index.js",
+  "exports": { ".": "./index.js", "./client": "./client.js", "./package.json": "./package.json" },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-typert-protocol": ">=0.1.6-alpha.1"
+  },
+  "dsh": {
+    "bundle": { "patch": "./cordis.patch.yml" },
+    "client": { "platform": "web", "inject": ["@deepseek-ai/dsh-client-ui-settings", "@deepseek-ai/dsh-api-remotes"] }
+  },
+  "scripts": { "test": "node --test tests/*.test.mjs" },
+  "files": ["index.js", "shells.js", "client.js", "cordis.patch.yml", "README.md"]
+}

package/shells.js

@@ -0,0 +1,404 @@
+/**
+ * Shell catalogue, executable resolution, and selection planning for the
+ * settings-page Shell selector.
+ *
+ * The feature has exactly ONE source of truth: the shipped PowerShell executor's
+ * `pwshPath` field in the `pwsh-sandbox` profile entry. The shipped executor
+ * reads its volatile `pwshPath` reference before each new command, so writing
+ * this one field changes the next spawned shell without touching the sandbox,
+ * approval, jobs, timeouts, or other shipped rows.
+ *
+ * Nothing here guesses the live value: `probeShells` reports
+ * `ctx.shell.pwshPath`, the executor's own resolved executable. The candidate
+ * lists below only describe what each option WOULD resolve to.
+ *
+ * Windows-only by construction; paths are built with `win32` so the split and
+ * join rules match the platform being targeted rather than the host running the
+ * tests.
+ *
+ * @module dsh-plugin-shell-selector/shells
+ */
+
+import { lstatSync } from 'node:fs'
+import { win32 } from 'node:path'
+
+/** The PowerShell sandbox profile entry whose Config owns `pwshPath`. */
+export const SHELL_NAMESPACE = process.platform === 'win32' ? 'pwsh-sandbox' : 'bash-sandbox'
+
+/** The one field this plugin writes. */
+export const SHELL_PATH_FIELD = 'pwshPath'
+
+/** The four selectable shells, in page order. */
+export const SHELL_KINDS = Object.freeze(['auto', 'pwsh7', 'pwsh5', 'gitbash'])
+
+/** Locale dictionary keys used as the stable option labels. */
+export const SHELL_LABEL_KEYS = Object.freeze({
+  auto: 'option.auto',
+  pwsh7: 'option.pwsh7',
+  pwsh5: 'option.pwsh5',
+  gitbash: 'option.gitbash',
+})
+
+/**
+ * A selection failure that the Remote half maps onto a `RemoteError`. The `code`
+ * is a stable identifier; `message` is already user-facing.
+ */
+export class ShellSelectorError extends Error {
+  /**
+   * @param code - stable failure identifier, e.g. `shell-selector/readonly`.
+   * @param message - user-facing explanation.
+   */
+  constructor(code, message) {
+    super(message)
+    this.name = 'ShellSelectorError'
+    this.code = code
+  }
+}
+
+/** Whether a path names the same executable, ignoring case and separators. */
+function samePath(left, right) {
+  if (typeof left !== 'string' || typeof right !== 'string') return false
+  const normalize = value => win32.normalize(value).replace(/[\\/]+$/, '').toLowerCase()
+  return normalize(left) === normalize(right)
+}
+
+/** Split a Windows `PATH` value into usable directory entries. */
+function pathEntries(env) {
+  const entries = []
+  for (const entry of String(env.PATH ?? '').split(';')) {
+    const trimmed = entry.trim().replace(/^"|"$/g, '')
+    if (trimmed.length > 0) entries.push(trimmed)
+  }
+  return entries
+}
+
+/**
+ * The PowerShell 7 locations the shipped executor probes, in its order: the
+ * machine-wide PowerShell 7 install, then every `PATH` entry.
+ *
+ * Mirrors `candidatePwshPaths` in `@deepseek-ai/dsh-pwsh-local` so the
+ * "automatic" option previews the same executable the executor would pick.
+ *
+ * @param env - environment to probe; defaults to the process environment.
+ * @returns candidate `pwsh.exe` paths in resolution order.
+ */
+export function pwsh7Locations(env = process.env) {
+  const programFiles = env.ProgramFiles ?? 'C:\\Program Files'
+  const candidates = [win32.join(programFiles, 'PowerShell', '7', 'pwsh.exe')]
+  for (const entry of pathEntries(env)) candidates.push(win32.join(entry, 'pwsh.exe'))
+  return candidates
+}
+
+/**
+ * An additional PowerShell 7 location: the per-user Microsoft Store execution
+ * alias. The shipped probe reaches it only when its directory is on `PATH`,
+ * which is not guaranteed; an EXPLICIT "PowerShell 7" choice should still find a
+ * Store install, so this candidate is appended for that option alone.
+ *
+ * @param env - environment to probe.
+ * @returns the Store alias path, or `undefined` without a `LOCALAPPDATA`.
+ */
+export function pwsh7StoreAlias(env = process.env) {
+  const localAppData = env.LOCALAPPDATA
+  if (typeof localAppData !== 'string' || localAppData.length === 0) return undefined
+  return win32.join(localAppData, 'Microsoft', 'WindowsApps', 'pwsh.exe')
+}
+
+/**
+ * The canned Windows PowerShell 5.1 executable shipped inside Windows.
+ *
+ * @param env - environment to probe.
+ * @returns the absolute `powershell.exe` path.
+ */
+export function pwsh5Path(env = process.env) {
+  const systemRoot = env.SystemRoot ?? 'C:\\Windows'
+  return win32.join(systemRoot, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe')
+}
+
+/**
+ * Git for Windows install locations, most specific first.
+ *
+ * `PATH` is deliberately NOT consulted. On a machine with WSL enabled, the
+ * `bash` on `PATH` is `%SystemRoot%\System32\bash.exe`, the WSL launcher, which
+ * executes inside a separate Linux filesystem namespace. Using it would silently
+ * replace the harness file sandbox with the WSL VM boundary, so only explicit
+ * Git for Windows install roots are considered.
+ *
+ * @param env - environment to probe.
+ * @returns candidate Git Bash paths in resolution order.
+ */
+export function gitBashLocations(env = process.env) {
+  const programFiles = env.ProgramFiles ?? 'C:\\Program Files'
+  const candidates = [win32.join(programFiles, 'Git', 'bin', 'bash.exe')]
+  const programFilesX86 = env['ProgramFiles(x86)']
+  if (typeof programFilesX86 === 'string' && programFilesX86.length > 0) {
+    candidates.push(win32.join(programFilesX86, 'Git', 'bin', 'bash.exe'))
+  }
+  const localAppData = env.LOCALAPPDATA
+  if (typeof localAppData === 'string' && localAppData.length > 0) {
+    candidates.push(win32.join(localAppData, 'Programs', 'Git', 'bin', 'bash.exe'))
+  }
+  return candidates
+}
+
+/**
+ * Whether a path is the WSL launcher rather than a Git for Windows executable.
+ *
+ * @param path - path to classify.
+ * @param env - environment supplying `SystemRoot`.
+ * @returns whether `path` is `%SystemRoot%\System32\bash.exe`.
+ */
+export function isWslLauncher(path, env = process.env) {
+  return samePath(path, win32.join(env.SystemRoot ?? 'C:\\Windows', 'System32', 'bash.exe'))
+}
+
+/**
+ * Whether a path is Windows PowerShell 5.1 rather than PowerShell 7.
+ *
+ * @param path - an executor executable path.
+ * @param env - environment supplying `SystemRoot`.
+ * @returns whether the path names the in-box 5.1 executable.
+ */
+export function isWindowsPowerShell51(path, env = process.env) {
+  if (typeof path !== 'string' || path.length === 0) return false
+  const lowered = win32.normalize(path).toLowerCase()
+  return lowered.endsWith(win32.join('windowspowershell', 'v1.0', 'powershell.exe').toLowerCase())
+    || samePath(path, pwsh5Path(env))
+}
+
+/**
+ * Classify one candidate path the way the shipped executor does.
+ *
+ * `lstat` deliberately does not follow reparse points, so a Microsoft Store
+ * execution alias is seen as the link it is instead of failing on the target's
+ * ACL — the same reason `dsh-pwsh-local` uses `lstatSync`.
+ *
+ * @param path - candidate executable path.
+ * @param lstat - stat function; injectable for tests.
+ * @returns `executable`, `directory`, `missing`, or `other`.
+ */
+export function executableState(path, lstat = lstatSync) {
+  try {
+    const info = lstat(path)
+    if (info.isDirectory()) return 'directory'
+    return info.isFile() || info.isSymbolicLink() ? 'executable' : 'other'
+  } catch {
+    return 'missing'
+  }
+}
+
+/** First candidate that exists as a spawnable file, or `undefined`. */
+function firstExecutable(candidates, lstat) {
+  for (const candidate of candidates) if (executableState(candidate, lstat) === 'executable') return candidate
+  return undefined
+}
+
+/**
+ * Resolve one option into the executable it would use and whether it is usable.
+ *
+ * @param kind - one of {@link SHELL_KINDS}.
+ * @param env - environment to probe.
+ * @param lstat - stat function; injectable for tests.
+ * @param platform - target platform; defaults to the process platform.
+ * @returns the option's preview: kind, availability, resolved path, reasons.
+ */
+export function describeOption(kind, env = process.env, lstat = lstatSync, platform = process.platform) {
+  const labelKey = SHELL_LABEL_KEYS[kind]
+  if (platform !== 'win32') {
+    return { kind, labelKey, available: false, path: null, detailKey: null, reasonKey: 'reason.windowsOnly', reason: 'Shell 选择器仅适用于 Windows 部署。' }
+  }
+  if (kind === 'auto') {
+    const candidates = [...pwsh7Locations(env), pwsh5Path(env)]
+    const found = firstExecutable(candidates, lstat)
+    if (found === undefined) {
+      // Matches the shipped fallback: no known location, so `pwsh` resolves via PATH.
+      return { kind, labelKey, available: true, path: 'pwsh', detailKey: 'reason.autoPathLookup', reasonKey: null, reason: null }
+    }
+    const landedOn51 = isWindowsPowerShell51(found, env)
+    return {
+      kind,
+      labelKey,
+      available: true,
+      path: found,
+      detailKey: landedOn51 ? 'reason.autoLanded51' : 'reason.autoLanded7',
+      reasonKey: null,
+      reason: null,
+    }
+  }
+  if (kind === 'pwsh7') {
+    const alias = pwsh7StoreAlias(env)
+    const candidates = alias === undefined ? pwsh7Locations(env) : [...pwsh7Locations(env), alias]
+    const found = firstExecutable(candidates, lstat)
+    if (found === undefined) {
+      // An explicit choice must never silently become a different shell.
+      return { kind, labelKey, available: false, path: null, detailKey: null, reasonKey: 'reason.noPwsh7', reason: '未检测到 PowerShell 7（pwsh.exe）。' }
+    }
+    return { kind, labelKey, available: true, path: found, detailKey: null, reasonKey: null, reason: null }
+  }
+  if (kind === 'pwsh5') {
+    const found = pwsh5Path(env)
+    if (executableState(found, lstat) !== 'executable') {
+      return { kind, labelKey, available: false, path: null, detailKey: null, reasonKey: 'reason.noPwsh5', reason: '未检测到 Windows PowerShell 5.1。' }
+    }
+    return { kind, labelKey, available: true, path: found, detailKey: 'reason.pwsh5Dialect', reasonKey: null, reason: null }
+  }
+  // Git Bash. Installed is not the same as usable: the Windows sandbox runs the
+  // command under a WRITE_RESTRICTED token whose write capabilities cover only
+  // the workspace and a private temp directory, and named pipes are unavailable
+  // in both confined modes while MSYS2's fork emulation depends on them. Until
+  // the confinement probe has actually been executed and reviewed, this option
+  // stays unavailable rather than being offered as a working choice.
+  const found = firstExecutable(gitBashLocations(env), lstat)
+  if (found === undefined) {
+    return { kind, labelKey, available: false, path: null, detailKey: null, reasonKey: 'reason.noGitBash', reason: '未检测到 Git for Windows（Program Files\\Git\\bin\\bash.exe）。' }
+  }
+  if (isWslLauncher(found, env)) {
+    // Unreachable through the explicit candidate list; kept as a hard guard so a
+    // future change to that list can never hand the AI a WSL shell.
+    return { kind, labelKey, available: false, path: null, detailKey: null, reasonKey: 'reason.wslBash', reason: '解析结果是 WSL 启动器而非 Git Bash，已拒绝。' }
+  }
+  return {
+    kind,
+    labelKey,
+    available: false,
+    path: found,
+    detailKey: 'reason.gitBashUnverified',
+    reasonKey: 'reason.gitBashUnverified',
+    reason: '已安装，但尚未验证它能在 Windows 文件沙箱下受限运行，因此暂不可选。',
+  }
+}
+
+/**
+ * Build the full option list.
+ *
+ * @param env - environment to probe.
+ * @param lstat - stat function; injectable for tests.
+ * @param platform - target platform.
+ * @returns one entry per {@link SHELL_KINDS} member, in page order.
+ */
+export function buildCatalog(env = process.env, lstat = lstatSync, platform = process.platform) {
+  return SHELL_KINDS.map(kind => describeOption(kind, env, lstat, platform))
+}
+
+/** Find this plugin's PowerShell sandbox profile section among the described entries. */
+function findShellSection(settings) {
+  if (settings === undefined || settings === null || typeof settings.describe !== 'function') return undefined
+  const described = settings.describe({ redactSecrets: true })
+  if (!Array.isArray(described)) return undefined
+  return described.find(entry => entry !== null && typeof entry === 'object' && entry.ns === SHELL_NAMESPACE)
+}
+
+/**
+ * Derive which option the current stored user layer represents.
+ *
+ * "Automatic" is the absence of a user-layer `pwshPath`, not a value that
+ * happens to equal what automatic would resolve to, so the page can keep
+ * showing the shipped default after an unrelated value changes.
+ *
+ * @param section - the described `shell` namespace, or `undefined`.
+ * @param env - environment to probe.
+ * @param lstat - stat function.
+ * @returns `{ kind, source, path? }`.
+ */
+export function currentSelection(section, env = process.env, lstat = lstatSync) {
+  const user = section?.user
+  const hasUser = user !== null && typeof user === 'object' && Object.hasOwn(user, SHELL_PATH_FIELD)
+  if (!hasUser) return { kind: 'auto', source: 'default' }
+  const declared = user[SHELL_PATH_FIELD]
+  if (typeof declared !== 'string') return { kind: 'custom', source: 'user' }
+  if (samePath(declared, pwsh5Path(env))) return { kind: 'pwsh5', source: 'user' }
+  const alias = pwsh7StoreAlias(env)
+  const candidates = alias === undefined ? pwsh7Locations(env) : [...pwsh7Locations(env), alias]
+  const ps7 = firstExecutable(candidates, lstat)
+  if (ps7 !== undefined && samePath(declared, ps7)) return { kind: 'pwsh7', source: 'user' }
+  return { kind: 'custom', source: 'user', path: declared }
+}
+
+/**
+ * Read the live executor facts and the selectable options.
+ *
+ * `executable` is authoritative: it is the path the executor will spawn on the
+ * next command, read from `ctx.shell.pwshPath` rather than re-derived here.
+ *
+ * @param input - settings service, optional shell service, environment, platform.
+ * @returns the page payload.
+ */
+export function probeShells({ settings, shell, env = process.env, platform = process.platform, lstat = lstatSync }) {
+  const section = findShellSection(settings)
+  return {
+    platform,
+    supported: platform === 'win32',
+    writable: settings?.writable === true,
+    namespaceRegistered: section !== undefined,
+    executableBound: shell !== undefined && shell !== null,
+    executable: shell?.pwshPath ?? null,
+    sandboxMode: shell?.sandboxMode ?? null,
+    revision: section?.revision ?? null,
+    current: currentSelection(section, env, lstat),
+    options: buildCatalog(env, lstat, platform),
+  }
+}
+
+/**
+ * Validate one requested option and produce the settings edit it requires.
+ *
+ * Validation happens here, before any write, because the executor trusts a
+ * configured `pwshPath` as-is and never checks it itself.
+ *
+ * @param input - the requested kind plus settings service, environment, platform.
+ * @returns the `mutate` operations and the validated option.
+ * @throws {ShellSelectorError} when the request cannot be honoured.
+ */
+export function planSelection({ kind, settings, env = process.env, platform = process.platform, lstat = lstatSync }) {
+  if (!SHELL_KINDS.includes(kind)) {
+    throw new ShellSelectorError('shell-selector/invalid', `未知的 Shell 选项：${String(kind)}`)
+  }
+  if (settings === undefined || settings === null) {
+    throw new ShellSelectorError('shell-selector/unavailable', '设置服务不可用。')
+  }
+  if (findShellSection(settings) === undefined) {
+    throw new ShellSelectorError('shell-selector/absent', '未注册 shell 设置命名空间，请确认 shell 执行器已加载。')
+  }
+  if (settings.writable !== true) {
+    throw new ShellSelectorError('shell-selector/readonly', '当前设置存储不可写。')
+  }
+  const option = describeOption(kind, env, lstat, platform)
+  if (!option.available) {
+    throw new ShellSelectorError('shell-selector/unavailable', option.reason ?? '该选项当前不可用。')
+  }
+  const ops = kind === 'auto'
+    // Unset, never `set(undefined)`: removing the user-layer field re-inherits the
+    // composition base, which is exactly "keep the current default".
+    ? [{ op: 'unset', path: [SHELL_PATH_FIELD] }]
+    : [{ op: 'set', path: [SHELL_PATH_FIELD], value: option.path }]
+  return { ops, option }
+}
+
+/**
+ * Apply one selection through path-addressed settings edits, so fields this
+ * plugin does not own (timeouts, output caps, `cwd`) are never restated.
+ *
+ * @param input - the requested kind, the revision the caller read, and services.
+ * @returns the validated option.
+ * @throws {ShellSelectorError} when the request cannot be honoured.
+ */
+export async function executeSelection(input) {
+  const { ops, option } = planSelection(input)
+  await input.settings.mutate(SHELL_NAMESPACE, ops, input.revision ?? undefined)
+  return option
+}
+
+/**
+ * The dialect note the model needs when the effective shell is not the one the
+ * `pwsh` tool's schema describes. Empty for PowerShell 7 and for every
+ * non-PowerShell path, so nothing is added unless it is true.
+ *
+ * @param executable - the executor's live executable path.
+ * @param env - environment supplying `SystemRoot`.
+ * @returns a model-facing sentence, or an empty string.
+ */
+export function dialectHint(executable, env = process.env) {
+  if (!isWindowsPowerShell51(executable, env)) return ''
+  return 'The command shell is Windows PowerShell 5.1, not PowerShell 7. It has no `&&`, `||`, ternary `? :`, '
+    + 'or `??`. Chain commands with `;` and branch with `if (...) { } else { }`.'
+}