@mzzsfy/dsh-shell-select 0.4.3 → 0.4.5

package/README.md

@@ -7,7 +7,7 @@ Windows 宿主 shell 链接管:接管根组合中的官方 `pwsh` 工具与执
 ## 工作方式
 
 - **运行时接管**:bundle 补丁不静态禁用官方 `tool-pwsh`、`pwsh-sandbox` 两行——boot 期官方 pwsh 链先服务,主行(`ctx.shell` 执行器 + `shell` 工具 + systemPrompt 段)apply 落定后经 `entry.update` 运行时禁用官方两行(dsh-market 同款,内存态不持久),再挂载执行器接管。本包任意死法(import 崩/apply 崩/被禁/卸载)下官方行保持启用,官方 pwsh 链自服务,系统不出现 shell 全灭窗口;重启后由行树声明态收敛。web 行(`/api/shell-select/*` 数据通道,`inject: ['webServer', 'settings']` 声明式门控——服务就绪才激活)与 guard 哨兵行同 patch 插入。
-- 配置事实源 = 主行 Config(dsh 0.1.7 settings 面以 profile 条目为存储,ns `shell-select`);配置仅经宿主 settings JSON(settings.yaml / settings 面)读写,浏览器侧不注入宿主设置页 UI,写路径 `settings.replace`,配置变更由 cordis 行重载活生效(工具描述随行重建即时更新)。
+- 配置事实源 = 主行 Config(dsh 0.1.7 settings 面以 profile 条目为存储,ns `shell-select`);设置中的 **Shell 管理** 页面经现有 API 读写宿主 settings,写路径 `settings.replace` 后刷新执行面(工具描述与默认客户端即时更新),也可通过宿主配置编辑器维护。
 - client 半区 `dsh.client.inject` 声明(官方机制,dsh-client-file-upload 等官方包同款):保证 client 运行时模块表中 `primitives`/`slots` 面在场;primitives 另有 try/catch 降级自绘兜底。
 - 本包执行器完整实现官方 `ctx.shell` seam(`resolve`/`run`/`start`/`runFor`/`startFor`/`entryFor`/`sandboxMode`),结构官方 PwshLocalExecutor 同构(实例状态/方法全公有——cordis 服务代理会把经 `ctx.shell` 调用的方法 `this` 重定向到阴影对象,`#` 私有触发品牌检查错误)。
 - **不管理会话预设**:bundle 补丁仅插入主行、guard、web，不声明 `shell-select` 预设，不覆写 `agent-preset-registry` 默认值。宿主及用户选择的预设保持原样，已存活代理及其子代理可继续持有旧预设修订；部署若显式指定已删除的 `shell-select` 预设，应通过宿主预设选择入口改选现存预设，本包不保留别名或迁移路径。
@@ -22,6 +22,7 @@ Windows 宿主 shell 链接管:接管根组合中的官方 `pwsh` 工具与执
 `shell` 工具(官方 `pwsh` 工具逐调用镜像):
 
 - 参数:`command`、`description`、`shell`(客户端 id,缺省用默认)、`timeoutMs`、`workdir`、`run_in_background`,沙箱升权面与官方一致。
+- 模型主描述先说明当前默认 `shell`,再按配置逐项列出客户端 id 与工作环境(WSL 附已配置发行版,不可用项标记 `unavailable`);存在可用 Bash 时统一追加 Windows 路径提示。主描述只讲常规调用,不包含拒绝重试流程;系统提示保留退出失败与 Windows 中断处理纪律,不重复客户端选择和独立进程说明。拒绝返回及权限执行契约不变。
 - 输出标记与官方逐字同构:`[exit code: N]`、`[killed by signal: X]`、`[timed out after …]`、`[sandbox: …]`、截断 spill 提示;terminal 卡退出 pill 照常复原。
 
 ## 会话卡(tool.call.toolview)
@@ -58,7 +59,7 @@ shell-select:
   default: pwsh
 ```
 
-出厂默认即上述三客户端。配置仅经 settings JSON 编辑(本包不向宿主设置页注入任何 UI);浏览器侧仅保留 `GET /api/shell-select/config` 名册读取,供会话卡徽章解析客户端命名。第三方实现:任意可执行文件 + 自定义 args 模板。
+出厂默认即上述三客户端。设置中的 **Shell 管理** 沿用客户端卡片：在卡片内单选默认客户端，可添加/移除条目、探测路径及扫描本机、配置登录壳与 WSL 发行版。参数为空格分隔的文本，含空格的单项用引号包裹，例如 `-c "echo hello" {command}`，普通引号中的 Windows 反斜线不解码为控制字符，控制字符参数使用显式 `$'…'` 转义。环境按每行 `K=V` 编辑，普通值可含空格、等号和反斜线；含换行或以双引号开头的值显示为双引号字符串，仅此形式解析 `\n` 等转义。命令黑名单逐条添加/删除并显示行级正则错误，非法正则阻止保存；保留模式原有空白与换行，空字符串规则不参与拦截。没有编辑时保存按钮禁用；保存不会拆分未编辑的参数、改写正则或把自动探测路径写回声明值。保存后回读完整配置，执行预算保持不变，回读失败明确提示已保存但刷新失败。第三方实现:任意可执行文件 + 自定义 args 模板。
 
 env 优先级(同键高右):内置覆盖集(NO_COLOR/PAGER/GIT_PAGER)< 条目 `env` < 调用方环境(spec.env + 会话 `DSH_*` 事实)。wsl 形把条目 env 与调用方环境全部键(WSLENV 本身除外)追加进 WSLENV 白名单,过 WSL 边界不静默失效。
 
@@ -97,14 +98,4 @@ env 优先级(同键高右):内置覆盖集(NO_COLOR/PAGER/GIT_PAGER)< 条目 `e
 
 ## dsh 版本兼容
 
-宿主要求仍为 ≥0.1.7-rc.1；当前补丁不再引用预设声明模块。以下为历史兼容验收记录，删除预设后的行为以当前「工作方式」为准。
-
-- 0.2.0-rc.2:完全适配(设置面通过;LLM 工具调用格 2026-10-08 经 echo-upstream -tool 场景真机解锁:放行路径 [shell: <id>] 尾标 ✓,deny 拦截 spawn 未发生 ✓——拦截文案被宿主工具输出校验吞为 INVALID_TOOL_OUTPUT,登记 FIND-020-3 P3 不修)
-- 0.1.7-rc.2:不崩溃底线通过(全家桶 crash-only)
-- 0.1.5-rc.3:未承诺(本包宿主要求 ≥0.1.7-rc.1,该版本不安装;全家桶在该版本不启动,详见仓库 docs/兼容性测试/逐包测试进度.md)
-
-历史验收(Round 30,2026-09-27):0.1.7-rc.2 设置面 7 格过(自动探测/自定义路径/坏路径徽标/黑名单往返含行号拦截/默认热更落盘/preset 接管入册);运行时接管(Round 29)9291 keep 宿主实证 runtime-disable→fiber 激活+INV-6 残影稳定。
-
-更细的逐包结论见仓库 `docs/兼容性测试/逐包测试进度.md` 与本包 `兼容性测试.md`。
-
-测试:`node --test "test/*.test.mjs"`(包目录内)。
+按仓库动态窗口验证(scripts/compat/window.mjs),不预置任何固定版本槽:主测 = 渠道 dist-tag 最新 rc,完全适配口径;基线 = npm latest,不崩溃底线口径;主测与基线同版时收敛单槽。本包声明 `dsh.hostMin = "0.1.7-rc.1"`:低于该代际的宿主 API 面未验证,compat 装载层自动排除。逐轮实测结论见 `docs/兼容性测试/逐包测试进度.md` 与本包 `兼容性测试.md`。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mzzsfy/dsh-shell-select",
   "description": "Windows shell 接管:替换默认 pwsh 工具为可配置多客户端的 shell 工具(git bash/WSL/cmd/pwsh,自定义路径,默认客户端,模型按名选择);支持命令 deny 黑名单、会话终端卡增强和直接 pwsh 接管徽章,接管失败自动回退官方 pwsh 链",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "type": "module",
   "main": "src/index.js",
   "exports": {

package/src/client.js

@@ -1,8 +1,7 @@
 // dsh-shell-select Client 半区:tool.call.toolview shell 族卡片(官方 BashRow/
 // terminalCardModel 同构 + 复制/折行/客户端徽章增强)。
 // 以 DSH client-modules 自注册格式发布:__ModuleLoader__.load({id, factory});
-// 客户端名册经 webServer 路由 /api/shell-select/config 读取(配置写入走宿主
-// settings JSON,浏览器侧无设置页)。
+// 客户端名册与 Shell 管理设置页经 /api/shell-select/* 读写宿主配置。
 
 window.__ModuleLoader__.load({
   id: '@mzzsfy/dsh-shell-select',
@@ -50,6 +49,8 @@ window.__ModuleLoader__.load({
 
     const API = {
       config: '/api/shell-select/config',
+      probe: '/api/shell-select/probe',
+      detect: '/api/shell-select/detect',
     }
 
     async function api(path, options) {
@@ -158,7 +159,7 @@ window.__ModuleLoader__.load({
         })
         .catch((error) => {
           pathMapRequested = false
-          console.warn('shell-select: pathmap fetch failed', error)
+          console.warn('shell-select: pathmap fetch failed: ' + (error instanceof Error ? error.message : String(error)))
         })
     }
     // LOGIC-END loadPathMap
@@ -202,6 +203,44 @@ window.__ModuleLoader__.load({
     }
 
     const CSS = [
+      '.sls-card { display:flex; flex-direction:column; gap:10px; }',
+      '.sls-row { display:flex; align-items:center; gap:8px; flex-wrap:wrap; }',
+      '.sls-entry { display:flex; flex-direction:column; gap:6px; padding:10px; border:1px solid var(--sls-border, rgba(128,128,128,.35)); border-radius:8px; }',
+      '.sls-entry__head { display:flex; align-items:center; gap:8px; }',
+      '.sls-grid { display:grid; grid-template-columns: 90px 1fr; gap:4px 8px; align-items:center; }',
+      '.sls-grid__label { opacity:.75; font-size:12px; }',
+      '.sls-input { padding:4px 8px; border-radius:6px; border:1px solid var(--sls-border, rgba(128,128,128,.35)); background:transparent; color:inherit; min-width:0; }',
+      '.sls-input--wide { width:100%; box-sizing:border-box; }',
+      '.sls-btn { padding:3px 10px; border-radius:6px; border:1px solid var(--sls-border, rgba(128,128,128,.35)); background:transparent; color:inherit; cursor:pointer; font-size:12px; }',
+      '.sls-btn:disabled { opacity:.5; cursor:default; }',
+      '.sls-btn--primary { border-color: transparent; background: var(--sls-accent, #4b7bcc); color:#fff; }',
+      '.sls-badge { font-size:11px; padding:1px 8px; border-radius:999px; border:1px solid var(--sls-border, rgba(128,128,128,.35)); opacity:.85; }',
+      '.sls-badge--ok { color:#2e9e5b; border-color:#2e9e5b; }',
+      '.sls-badge--bad { color:#c44; border-color:#c44; }',
+      '.sls-badge--default { color:#fff; background:var(--sls-accent, #4b7bcc); border-color:transparent; }',
+      '.sls-hint { font-size:12px; opacity:.7; white-space:pre-wrap; overflow-wrap:anywhere; }',
+      '.sls-error { font-size:12px; color:#c44; white-space:pre-wrap; }',
+      '.sls-args { font-size:12px; font-family:var(--sls-mono, monospace); }',
+      '.sls-rules { display:flex; flex-direction:column; gap:6px; padding:10px; border:1px solid var(--sls-border, rgba(128,128,128,.35)); border-radius:8px; }',
+      '.sls-rules__head { display:flex; align-items:center; gap:8px; }',
+      '.sls-rules__title { font-weight:500; }',
+      '.sls-rules__note { font-size:12px; opacity:.7; }',
+      '.sls-rule { display:flex; align-items:center; gap:6px; }',
+      '.sls-rule__no { flex:none; width:18px; text-align:right; font-size:12px; opacity:.45; user-select:none; }',
+      '.sls-rule__input { flex:1; min-width:0; padding:4px 8px; border-radius:6px; border:1px solid var(--sls-border, rgba(128,128,128,.35)); background:transparent; color:inherit; font-size:12px; font-family:var(--sls-mono, monospace); resize:vertical; }',
+      '.sls-rule__input:focus-visible { outline:2px solid var(--sls-accent, #4b7bcc); outline-offset:1px; }',
+      '.sls-rule--bad .sls-rule__input { border-color:#c44; }',
+      '.sls-rule__err { flex:none; max-width:40%; font-size:11px; color:#c44; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }',
+      '.sls-rule__del { flex:none; padding:2px 8px; }',
+      '.sls-switch { display:inline-flex; align-items:center; cursor:pointer; }',
+      '.sls-switch input[type="checkbox"] { position:absolute; opacity:0; width:1px; height:1px; }',
+      '.sls-switch__track { position:relative; width:34px; height:19px; border-radius:999px; box-sizing:border-box; background:var(--sls-track, rgba(128,128,128,.35)); border:1px solid var(--sls-border, rgba(128,128,128,.35)); transition:background .15s, border-color .15s; }',
+      '.sls-switch__thumb { position:absolute; top:50%; left:2px; width:13px; height:13px; border-radius:50%; background:var(--sls-thumb, rgba(128,128,128,.6)); transform:translateY(-50%); transition:left .15s, background .15s; }',
+      '.sls-switch:hover .sls-switch__track { border-color:var(--sls-accent, #4b7bcc); }',
+      '.sls-switch input[type="checkbox"]:checked + .sls-switch__track { background:var(--sls-accent, #4b7bcc); border-color:var(--sls-accent, #4b7bcc); }',
+      '.sls-switch input[type="checkbox"]:checked + .sls-switch__track .sls-switch__thumb { left:17px; background:var(--sls-bg-base, #fff); }',
+      '.sls-switch input[type="checkbox"]:focus-visible + .sls-switch__track { outline:2px solid var(--sls-accent, #4b7bcc); outline-offset:1px; }',
+      '.sls-switch input[type="checkbox"]:disabled + .sls-switch__track { opacity:.5; }',
       // tool.call.toolview 卡片(key 'shell'):官方 terminal 行同构 + 复制/折行增强。
       // 色彩对齐官方 ToolRow:标题 label-secondary、icon 盒 label-tertiary(实证自
       // 官方行 computed style);token 缺失时回退 inherit 不致不可读
@@ -614,9 +653,304 @@ window.__ModuleLoader__.load({
       )
     }
 
+    const SHELL_KINDS = { pwsh: 'PowerShell', bash: 'POSIX bash(git bash / msys2 / cygwin)', cmd: 'CMD', wsl: 'WSL bash' }
+
+    function argsTextOf(args) {
+      return args.map((arg) => {
+        if (/[\u0000-\u001f\u007f]/.test(arg)) {
+          const body = arg.replace(/[\u0000-\u001f\u007f'\\]/g, (char) => {
+            if (char === "'" || char === '\\') return '\\' + char
+            return '\\u' + char.charCodeAt(0).toString(16).padStart(4, '0')
+          })
+          return "$'" + body + "'"
+        }
+        return arg !== '' && !/[\s'"\\]/.test(arg) ? arg : '"' + arg.replace(/["\\]/g, (char) => '\\' + char) + '"'
+      }).join(' ')
+    }
+
+    // 普通引号只转义当前引号与反斜线；控制字符仅在显式 ANSI-C 引号内解码，不执行 shell。
+    function parseArgsText(text) {
+      const args = []
+      const controls = { n: '\n', r: '\r', t: '\t', b: '\b', f: '\f', v: '\v' }
+      let token = '', started = false
+      for (let index = 0; index < text.length; index += 1) {
+        const char = text[index]
+        if (/\s/.test(char)) {
+          if (started) args.push(token)
+          token = ''
+          started = false
+          continue
+        }
+        started = true
+        const ansi = char === '$' && text[index + 1] === "'"
+        if (!ansi && char !== '"' && char !== "'") {
+          token += char
+          continue
+        }
+        if (ansi) index += 1
+        const quote = text[index]
+        index += 1
+        for (; index < text.length && text[index] !== quote; index += 1) {
+          const current = text[index]
+          const next = text[index + 1]
+          if (current === '\\' && (next === quote || next === '\\')) {
+            token += next
+            index += 1
+          } else if (ansi && current === '\\' && Object.hasOwn(controls, next)) {
+            token += controls[next]
+            index += 1
+          } else if (ansi && current === '\\' && next === 'u' && /^[\da-f]{4}$/i.test(text.slice(index + 2, index + 6))) {
+            token += String.fromCharCode(parseInt(text.slice(index + 2, index + 6), 16))
+            index += 5
+          } else {
+            token += current
+          }
+        }
+        if (index >= text.length) throw new Error('参数引号未闭合')
+      }
+      if (started) args.push(token)
+      return args
+    }
+
+    function envTextOf(env) {
+      return Object.entries(env).map(([key, value]) => `${key}=${/[\r\n]|^"/.test(value) ? JSON.stringify(value) : value}`).join('\n')
+    }
+
+    function parseEnvText(text) {
+      const pairs = []
+      for (const line of text.split('\n')) {
+        if (line.trim() === '') continue
+        const separator = line.indexOf('=')
+        const key = separator < 0 ? '' : line.slice(0, separator).trim()
+        if (key === '') throw new Error('环境变量每行必须为 K=V')
+        const value = line.slice(separator + 1)
+        const parsed = value.startsWith('"') ? JSON.parse(value) : value
+        if (typeof parsed !== 'string') throw new Error('环境变量双引号值必须是字符串')
+        pairs.push([key, parsed])
+      }
+      return Object.fromEntries(pairs)
+    }
+
+    function denyPatternIssue(rule) {
+      if (rule === '') return undefined
+      try { new RegExp(rule, 'i') } catch (error) { return error.message }
+      return undefined
+    }
+
+    function editableSection(section) {
+      const { resolved, ...config } = section
+      return {
+        config,
+        entries: config.shells.map((entry, index) => {
+          const argsText = argsTextOf(entry.args ?? [])
+          const envText = envTextOf(entry.env ?? {})
+          const fact = resolved?.shells.find((item) => item.id === entry.id)
+          return { ...entry, key: `loaded-${index}`, argsText, originalArgsText: argsText,
+            envText, originalEnvText: envText, available: fact?.available, resolved: fact?.path }
+        }),
+        nextKey: config.shells.length,
+        defaultId: config.default,
+        rules: (config.deny ?? []).map((value, index) => ({ key: `rule-${index}`, value })),
+        nextRuleKey: (config.deny ?? []).length,
+        dirty: false,
+      }
+    }
+
+    function ShellSelectApp() {
+      const [form, setForm] = useState(null)
+      const [busy, setBusy] = useState(false)
+      const [notice, setNotice] = useState('')
+      const [revision, setRevision] = useState(0)
+
+      useEffect(() => {
+        let disposed = false
+        setNotice('')
+        api(API.config).then((section) => {
+          if (!disposed) setForm(editableSection(section))
+        }).catch((error) => { if (!disposed) setNotice('加载失败：' + error.message) })
+        return () => { disposed = true }
+      }, [revision])
+
+      const editForm = (update) => {
+        if (busy) return
+        setForm((current) => ({ ...update(current), dirty: true }))
+      }
+      const patchEntry = (key, changes) => editForm((current) => ({
+        ...current,
+        defaultId: changes.id !== undefined && current.entries.find((entry) => entry.key === key)?.id === current.defaultId
+          ? changes.id : current.defaultId,
+        entries: current.entries.map((entry) => entry.key === key ? { ...entry, ...changes, available: undefined, resolved: undefined } : entry),
+      }))
+      const removeEntry = (key) => editForm((current) => {
+        const entries = current.entries.filter((entry) => entry.key !== key)
+        return { ...current, entries, defaultId: entries.some((entry) => entry.id === current.defaultId) ? current.defaultId : entries[0]?.id ?? '' }
+      })
+      const addEntry = () => editForm((current) => ({
+        ...current, nextKey: current.nextKey + 1,
+        entries: [...current.entries, { key: `added-${current.nextKey}`, id: '', kind: 'bash', path: '', argsText: '', envText: '', login: false, distro: '' }],
+      }))
+      const patchRule = (key, value) => editForm((current) => ({ ...current,
+        rules: current.rules.map((rule) => rule.key === key ? { ...rule, value } : rule),
+      }))
+      const addRule = () => editForm((current) => ({ ...current, nextRuleKey: current.nextRuleKey + 1,
+        rules: [...current.rules, { key: `rule-${current.nextRuleKey}`, value: '' }],
+      }))
+      const removeRule = (key) => editForm((current) => ({ ...current, rules: current.rules.filter((rule) => rule.key !== key) }))
+      const save = async () => {
+        if (busy || !form.dirty) return
+        setBusy(true)
+        setNotice('')
+        try {
+          const shells = form.entries.map((entry) => {
+            // 显示未变时直接复用原值，避免表单控件归一换行等行为改写已有配置。
+            const args = entry.argsText === entry.originalArgsText ? entry.args ?? [] : parseArgsText(entry.argsText)
+            const env = entry.envText === entry.originalEnvText ? entry.env ?? {} : parseEnvText(entry.envText)
+            return { id: entry.id.trim(), kind: entry.kind, path: entry.path.trim(), args, login: entry.login === true, distro: entry.distro ?? '', env }
+          })
+          const ids = shells.map((entry) => entry.id)
+          if (ids.length === 0 || ids.some((id) => id === '')) throw new Error('至少保留一个客户端，id 不能为空')
+          if (new Set(ids).size !== ids.length) throw new Error('客户端 id 重复')
+          const defaultId = form.defaultId.trim()
+          if (!ids.includes(defaultId)) throw new Error('默认客户端不在列表中')
+          for (const [index, rule] of form.rules.entries()) {
+            const issue = denyPatternIssue(rule.value)
+            if (issue !== undefined) throw new Error(`第 ${index + 1} 条正则非法：${issue}`)
+          }
+          const deny = form.rules.map((rule) => rule.value).filter((rule) => rule !== '')
+          const result = await api(API.config, { method: 'POST', body: JSON.stringify({ ...form.config, shells, default: defaultId, deny }) })
+          clientCatalog = { default: result.resolved.default, byId: Object.fromEntries(result.resolved.shells.map((entry) => [entry.id, entry.id])) }
+          setForm((current) => ({ ...current, dirty: false }))
+          setNotice('已保存，默认客户端与工具描述即时生效')
+          try {
+            const section = await api(API.config)
+            setForm(editableSection(section))
+          } catch (error) { setNotice('已保存，但刷新失败：' + error.message + '；请重新加载') }
+        } catch (error) {
+          setNotice('保存失败：' + error.message)
+        } finally { setBusy(false) }
+      }
+      const probe = async (entry) => {
+        if (busy) return
+        setBusy(true)
+        setNotice('')
+        try {
+          const result = await api(API.probe, { method: 'POST', body: JSON.stringify({ path: entry.path }) })
+          setForm((current) => ({ ...current, entries: current.entries.map((item) => item.key === entry.key
+            ? { ...item, available: result.exists, resolved: entry.path } : item) }))
+          setNotice(result.exists ? '路径存在' : '路径不存在')
+        } catch (error) { setNotice('探测失败：' + error.message) }
+        finally { setBusy(false) }
+      }
+      const detect = async (kind) => {
+        if (busy) return
+        setBusy(true)
+        setNotice('')
+        try {
+          const result = await api(API.detect, { method: 'POST', body: JSON.stringify({ kinds: [kind] }) })
+          setNotice(result.found.length > 0 ? kind + ' 候选:' + result.found.map((item) => item.path).join(' ; ') : kind + ' 未发现候选')
+        } catch (error) { setNotice('探测失败：' + error.message) }
+        finally { setBusy(false) }
+      }
+      const reload = h('button', { type: 'button', className: 'sls-btn', disabled: busy, onClick: () => {
+        if (busy) return
+        setForm(null)
+        setNotice('')
+        setRevision((value) => value + 1)
+      } }, '重新加载')
+      if (form === null) return h('div', { className: 'sls-card', 'aria-busy': !notice },
+        h('div', { role: notice ? 'alert' : 'status', className: 'sls-hint' }, notice || '加载中…'), notice ? reload : null)
+
+      const activeRules = form.rules.filter((rule) => rule.value !== '').length
+      return h('div', { className: 'sls-card', 'aria-busy': busy },
+        h('div', { className: 'sls-row' }, h('span', { className: 'sls-hint' },
+          '命令行客户端清单。路径留空自动探测;模型可通过工具的 shell 参数选择任一条目,缺省用默认。')),
+        form.entries.map((entry, index) => {
+          const input = (label, name, placeholder, type = 'input') => h(type, {
+            className: 'sls-input sls-input--wide' + (name === 'argsText' || name === 'envText' ? ' sls-args' : ''),
+            'aria-label': `客户端 ${index + 1} ${label}`, value: entry[name] ?? '', disabled: busy,
+            rows: type === 'textarea' ? 2 : undefined, placeholder,
+            onChange: (event) => patchEntry(entry.key, { [name]: event.target.value }),
+          })
+          return h('div', { className: 'sls-entry', key: entry.key },
+            h('div', { className: 'sls-entry__head' },
+              h('label', { className: 'sls-row' },
+                h('input', { type: 'radio', name: 'sls-default', 'aria-label': `客户端 ${index + 1} 默认`,
+                  checked: form.defaultId === entry.id && entry.id.length > 0, disabled: busy || entry.id.trim() === '',
+                  title: '设为默认客户端(模型缺省 shell 参数时使用)',
+                  onChange: () => editForm((current) => ({ ...current, defaultId: entry.id })),
+                }), h('span', { className: 'sls-hint' }, '默认')),
+              h('span', { className: 'sls-badge' + (entry.available === true ? ' sls-badge--ok' : entry.available === false ? ' sls-badge--bad' : ''),
+                title: entry.resolved ? '解析路径:' + entry.resolved : '路径尚未解析',
+              }, entry.available === true ? '可用' : entry.available === false ? '不可用' : '未知'),
+              entry.id === form.defaultId && entry.id !== '' ? h('span', { className: 'sls-badge sls-badge--default' }, '默认') : null,
+              h('span', { style: { flex: 1 } }),
+              h('button', { type: 'button', className: 'sls-btn', disabled: busy || entry.path.trim() === '', title: '检查该路径是否存在', onClick: () => probe(entry) }, '探测路径'),
+              h('button', { type: 'button', className: 'sls-btn', disabled: busy, 'aria-label': `移除客户端 ${index + 1}`, title: '移除该条目', onClick: () => removeEntry(entry.key) }, '移除')),
+            h('div', { className: 'sls-grid' },
+              h('span', { className: 'sls-grid__label' }, 'id'),
+              input('id', 'id', 'pwsh / git-bash / …(模型看到的 shell 参数值,亦作显示名)'),
+              h('span', { className: 'sls-grid__label' }, '形态'),
+              h('div', { className: 'sls-row' },
+                h('select', { className: 'sls-input', 'aria-label': `客户端 ${index + 1} 形态`, value: entry.kind, disabled: busy,
+                  onChange: (event) => patchEntry(entry.key, { kind: event.target.value }),
+                }, Object.entries(SHELL_KINDS).map(([kind, label]) => h('option', { key: kind, value: kind }, label))),
+                h('button', { type: 'button', className: 'sls-btn', disabled: busy, title: '扫描本机常见安装位置', onClick: () => detect(entry.kind) }, '扫描本机')),
+              h('span', { className: 'sls-grid__label' }, '路径'),
+              input('路径', 'path', '留空自动探测,如 C:\\Program Files\\Git\\bin\\bash.exe'),
+              h('span', { className: 'sls-grid__label' }, '参数'),
+              input('参数', 'argsText', '留空用形态默认;空格分隔,引号包住含空格参数,{command} 为命令占位'),
+              h('span', { className: 'sls-hint', style: { gridColumn: '2' } }, "空格参数加引号；控制字符用 $'…' 转义，仅解析不执行。"),
+              ...(entry.kind === 'bash' ? [
+                h('span', { className: 'sls-grid__label' }, '登录壳'),
+                h('label', { className: 'sls-row sls-switch', title: '-lc 登录壳拉起 /etc/profile(只注入 /usr/bin;/mingw64/bin 需在下方的环境里配 MSYSTEM=MINGW64)' },
+                  h('input', { type: 'checkbox', 'aria-label': `客户端 ${index + 1} 登录壳`, checked: entry.login === true, disabled: busy,
+                    onChange: (event) => patchEntry(entry.key, { login: event.target.checked }),
+                  }), h('span', { className: 'sls-switch__track' }, h('span', { className: 'sls-switch__thumb' })),
+                  h('span', { className: 'sls-hint' }, '-lc 登录壳')),
+              ] : []),
+              ...(entry.kind === 'wsl' ? [h('span', { className: 'sls-grid__label' }, '发行版'), input('发行版', 'distro', '留空用默认发行版,如 Ubuntu-22.04')] : []),
+              h('span', { className: 'sls-grid__label' }, '环境'),
+              input('环境', 'envText', '每行 K=V,如 MSYSTEM=MINGW64;wsl 形自动经 WSLENV 透传', 'textarea'),
+              h('span', { className: 'sls-hint', style: { gridColumn: '2' } }, '每行 K=V；换行值用双引号及 \\n，双引号内反斜线写 \\\\。')))
+        }),
+        h('div', { className: 'sls-rules' },
+          h('div', { className: 'sls-rules__head' }, h('span', { className: 'sls-rules__title' }, '命令黑名单'),
+            h('span', { className: 'sls-badge' + (activeRules > 0 ? ' sls-badge--ok' : ' sls-badge--bad') }, activeRules > 0 ? activeRules + ' 条规则' : '未生效')),
+          h('span', { className: 'sls-rules__note' }, '每条规则为一条正则,对整条命令全文匹配(大小写不敏感),命中即拒,无豁免;精细放行写在模式内用前瞻,如 rm -rf\\s+(?!\\S*node_modules)。'),
+          form.rules.length === 0 ? h('span', { className: 'sls-rules__note' }, '未配置,命中拦截不生效,模型可执行任意命令。') : form.rules.map((rule, index) => {
+            const issue = denyPatternIssue(rule.value)
+            const errorId = `sls-${rule.key}-error`
+            return h('div', { className: 'sls-rule' + (issue !== undefined ? ' sls-rule--bad' : ''), key: rule.key },
+              h('span', { className: 'sls-rule__no' }, index + 1),
+              h('textarea', { className: 'sls-rule__input', rows: Math.max(1, rule.value.split('\n').length), 'aria-label': `黑名单第 ${index + 1} 条`,
+                'aria-invalid': issue !== undefined, 'aria-describedby': issue !== undefined ? errorId : undefined,
+                value: rule.value, disabled: busy, placeholder: '正则,如 ^format\\s', onChange: (event) => patchRule(rule.key, event.target.value),
+              }),
+              issue !== undefined ? h('span', { id: errorId, className: 'sls-rule__err', title: issue }, issue) : null,
+              h('button', { type: 'button', className: 'sls-btn sls-rule__del', disabled: busy, 'aria-label': `删除规则 ${index + 1}`, title: '删除该条规则', onClick: () => removeRule(rule.key) }, '删除'))
+          }),
+          h('div', { className: 'sls-row' }, h('button', { type: 'button', className: 'sls-btn', disabled: busy, onClick: addRule }, '添加规则'))),
+        h('div', { className: 'sls-row' },
+          h('button', { type: 'button', className: 'sls-btn', disabled: busy, onClick: addEntry }, '添加客户端'),
+          h('span', { style: { flex: 1 } }),
+          form.dirty ? h('span', { className: 'sls-hint' }, '有未保存改动') : null,
+          reload,
+          h('button', { type: 'button', className: 'sls-btn sls-btn--primary', disabled: busy || !form.dirty, onClick: save }, '保存')),
+        notice ? h('div', { role: notice.includes('失败') ? 'alert' : 'status', className: 'sls-hint' }, notice) : null,
+      )
+    }
+
     return {
       inject: ['slots'],
       apply(ctx) {
+        const NAV_ICON = { 'Shell 管理': 'terminal' }
+        if (window.__navicIcons !== undefined) window.__navicIcons.register(NAV_ICON)
+        else if (Array.isArray(window.__navicIconQueue)) window.__navicIconQueue.push(NAV_ICON)
+        else window.__navicIconQueue = [NAV_ICON]
+        ctx.slots.inject('settings.section', () => ctx.slots.register(
+          { name: 'settings.section', id: 'shell-select', order: 82, label: 'Shell 管理' },
+          () => React.createElement(ShellSelectApp),
+        ))
         installPathRescue(ctx)
         ctx.effect(() => {
           const style = document.createElement('style')

package/src/executor.mjs

@@ -255,7 +255,7 @@ export const ShellSelectExecutor = class ShellSelectExecutor extends ShellExecut
     this.ctx.systemPrompt.section({
       name: 'tool:shell',
       order: this.ctx.systemPrompt.getSectionOrder('TOOL_PWSH'),
-      text: 'Non-zero exits are reported as `[exit code: N]` markers; investigate failures before moving on. On Windows a killed process settles as `[exit code: 1]` without a signal marker; treat a bare exit 1 after an interruption as a termination, not a command failure. Commands run in fresh processes: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Pass the `shell` argument only when the default client cannot run the command; the available clients are listed in the tool description.',
+      text: 'Non-zero exits are reported as `[exit code: N]` markers; investigate failures before moving on. On Windows a killed process settles as `[exit code: 1]` without a signal marker; treat a bare exit 1 after an interruption as a termination, not a command failure.',
     })
   }
 

package/src/guard.js

@@ -208,6 +208,9 @@ export async function installGuard(ctx, {
       const dead = detectDeadState(ctx.loader, { applyState: shellSelectApplyState })
       if (dead === true && mounted.size === 0 && mounting === null) await mountOfficial()
       else if (dead === false && (mounted.size > 0 || mounting !== null)) await unmountOfficial()
+    } catch {
+      // 停机竞态:fiber 已停而末次 tick 先于 effect 清理触发,loader 访问必抛;
+      // rejection 逃逸会被宿主 fail-loud 判 fatal load failure 杀进程,静默放行
     } finally {
       sweeping = false
     }
@@ -246,10 +249,15 @@ export async function installGuard(ctx, {
   ctx.logger.info?.(`shell-select/guard: 初始判定 dead=${initial}`)
   if (initial === true) await mountOfficial()
 
-  const timer = setInterval(() => {
-    void sweep()
-  }, sweepIntervalMs)
-  timer.unref?.()
+  // 定时器随 fiber 清理:裸 setInterval 会在行停用后残留 tick,停机序列中
+  // 访问 loader 抛错并经宿主 fail-loud 升级为进程级 fatal
+  ctx.effect(() => {
+    const timer = setInterval(() => {
+      void sweep()
+    }, sweepIntervalMs)
+    timer.unref?.()
+    return () => clearInterval(timer)
+  }, 'shell-select/guard sweep timer')
   return undefined
 }
 

package/src/tool.mjs

@@ -144,27 +144,34 @@ function foregroundOutputProperties() {
   }
 }
 
-/** bash 路径措辞:bash 输出的 MSYS 拼写不得回流进工具参数(宿主文件面只认 Windows 形式)。 */
-const BASH_PATH_GUIDANCE = 'Bash clients accept Windows-style paths (C:/...): use that form for `workdir` and file-tool arguments — MSYS spellings like `/c/Users/...` or `/tmp` only work inside the bash command itself, never in tool arguments.'
+/** Bash 命令内路径与宿主工具参数使用不同拼写。 */
+const BASH_PATH_GUIDANCE = 'Use Windows-style paths (C:/...) in workdir and file-tool arguments; MSYS paths (/c/..., /tmp) are valid only inside Bash commands.'
+const SHELL_ENVIRONMENTS = { pwsh: 'PowerShell', bash: 'Bash', cmd: 'Windows cmd.exe', wsl: 'WSL' }
 
-/** 工具描述:客户端清单与方言随配置动态变化。 */
-export function shellDescription({ executor, backgroundEnabled, escalationModes }) {
+/** 工具描述只展示当前配置与常规调用方式。 */
+export function shellDescription({ executor, backgroundEnabled }) {
   const listing = executor.listShells()
-  const lines = listing.shells
-    .map((entry) => `${entry.id} (${entry.kind}${entry.available ? '' : ', executable not found'})`)
-    .join(', ')
-  const base = 'Execute a command in one of the configured shell clients and return its stdout/stderr. '
-    + `Available clients: ${lines}. The default client is "${listing.default}"; pass \`shell\` only when this command needs a different client (dialects differ: pwsh = PowerShell, bash/wsl = POSIX, cmd = cmd.exe). `
-    + 'Each call runs in a fresh process: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. '
-    + 'Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed environment variables (`DSH_*`); inspect them when needed. '
-    + 'Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. '
-    + (backgroundEnabled
-      ? 'Set `run_in_background: true` for long-running commands: the call returns a job id immediately; read its output with `job_output` and stop it with `job_kill`.'
-      : 'Background execution is not available; long-running commands must finish within the timeout.')
-  const bashPresent = listing.shells.some((candidate) => candidate.kind === 'bash' && candidate.available)
-  const text = bashPresent ? `${base} ${BASH_PATH_GUIDANCE}` : base
-  if (escalationModes.length === 0) return text
-  return text + ' Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. When a command is denied and a wider mode would let it succeed, escalate immediately in the same turn: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Never escalate speculatively: ground the request in a real denial. If the session states approval prompts are disabled, a denial is final — do not set `sandbox_permissions`.'
+  const clients = listing.shells.map((entry) => {
+    const distro = entry.kind === 'wsl' && entry.distro ? ` (${entry.distro})` : ''
+    const availability = entry.available ? '' : ' (unavailable)'
+    return `- ${entry.id} — ${SHELL_ENVIRONMENTS[entry.kind]}${distro}${availability}`
+  }).join('\n')
+  const bashPresent = listing.shells.some((entry) => entry.kind === 'bash' && entry.available)
+  return [
+    `Execute commands using shell=${JSON.stringify(listing.default)} by default and return stdout/stderr.`,
+    'Omit shell to use the default; set it to one of:',
+    clients,
+    '',
+    'Each call starts a fresh process; cwd, variables, and functions do not persist.',
+    'Use workdir to set the working directory.',
+    ...bashPresent ? [BASH_PATH_GUIDANCE] : [],
+    '',
+    ...backgroundEnabled ? [
+      'For long-running commands, set run_in_background=true.',
+      'Use job_output to read background output and job_kill to stop the job.',
+    ] : ['Background execution is not available; long-running commands must finish within the timeout.'],
+    'Long output is truncated; the full-output file path is reported when available.',
+  ].join('\n')
 }
 
 /** pwsh 工具描述:兼容保留工具,只声明不要调用与去向,零执行语义。 */
@@ -207,7 +214,7 @@ export function registerShellTool(ctx, { executor }) {
   const makeDefinition = (toolName, pinned) => (faces) => defineTool({
     name: toolName,
     description: pinned === undefined
-      ? shellDescription({ executor: faces.executor, backgroundEnabled, escalationModes })
+      ? shellDescription({ executor: faces.executor, backgroundEnabled })
       : pwshDescription(),
     parameters: {
       command: {
@@ -224,7 +231,7 @@ export function registerShellTool(ctx, { executor }) {
       },
       ...pinned === undefined ? { shell: {
         type: 'string',
-        description: 'Shell client id from the tool description list (e.g. pwsh, git-bash, cmd). Omit to use the configured default client.',
+        description: 'Override the default shell using an id listed above.',
       } } : {},
       timeoutMs: {
         type: 'number',
@@ -242,7 +249,7 @@ export function registerShellTool(ctx, { executor }) {
         sandbox_permissions: {
           type: 'string',
           enum: [...escalationModes],
-          description: 'The wider sandbox mode this command needs. Only valid as a one-shot retry of a command the sandbox just denied; requires justification and user approval.',
+          description: 'Wider sandbox access mode for this command; requires justification and user approval.',
         },
         justification: {
           type: 'string',

package/test/client-settings.test.mjs

@@ -0,0 +1,251 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+
+const source = readFileSync(new URL('../src/client.js', import.meta.url), 'utf8')
+const section = () => ({
+  default: 'git-bash', deny: ['^format\\s', ' foo ', ' ', 'echo\nsecret'], timeoutMs: 120000,
+  shells: [
+    { id: 'git-bash', kind: 'bash', path: '', args: ['-c', 'echo two words', '{command}', '', 'a"b', "a'b", 'C:\\path', 'line\nbreak', 'tab\tcr\r', "$'literal'", 'C:\\tail\\'], env: { NOTE: 'a=b c', MULTI: 'line1\nOTHER=two', PATH: 'C:\\temp\\file', LITERAL: '\\n', QUOTED: '"literal"', CR: 'first\rsecond', TRAIL: 'C:\\temp\\' }, login: true, distro: '' },
+    { id: 'pwsh', kind: 'pwsh', path: '', args: [], env: {}, login: false, distro: '' },
+  ],
+  resolved: { default: 'git-bash', shells: [{ id: 'git-bash', available: true, path: 'C:/Git/bash.exe' }, { id: 'pwsh', available: true }] },
+})
+
+async function page({ failLoad = false, failSave = false, failReadBack = false } = {}) {
+  const state = [], effects = [], registrations = [], requests = []
+  let cursor = 0, effectCursor = 0, loaded
+  const React = {
+    createElement: (type, props, ...children) => typeof type === 'function' ? type(props ?? {}) : { type, props: props ?? {}, children },
+    useState(initial) {
+      const at = cursor++
+      if (!(at in state)) state[at] = typeof initial === 'function' ? initial() : initial
+      return [state[at], (next) => { state[at] = typeof next === 'function' ? next(state[at]) : next }]
+    },
+    useEffect(fn, deps) {
+      const at = effectCursor++
+      const prior = effects[at]
+      if (!prior || deps.some((value, index) => value !== prior.deps[index])) {
+        prior?.cleanup?.()
+        effects[at] = { fn, deps, pending: true }
+      }
+    },
+  }
+  const window = { __ModuleLoader__: { load: (value) => { loaded = value } } }
+  const document = { documentElement: { lang: 'zh' }, createElement: () => ({ setAttribute() {}, remove() {} }), head: { appendChild() {} } }
+  let current = section()
+  const fetch = async (path, options = {}) => {
+    requests.push({ path, ...options })
+    if (path.endsWith('/probe')) return { ok: true, json: async () => ({ exists: true }) }
+    if (path.endsWith('/detect')) return { ok: true, json: async () => ({ found: [{ path: 'C:/Git/bash.exe' }] }) }
+    if (failReadBack && options.method !== 'POST' && requests.some((row) => row.method === 'POST')) return { ok: false, status: 503, json: async () => ({ error: '回读故障' }) }
+    if (failLoad && options.method !== 'POST') return { ok: false, status: 503, json: async () => ({ error: '加载故障' }) }
+    if (options.method === 'POST') {
+      if (failSave) return { ok: false, status: 400, json: async () => ({ error: '写入故障' }) }
+      current = { ...JSON.parse(options.body), resolved: current.resolved }
+      return { ok: true, json: async () => ({ ok: true, resolved: current.resolved }) }
+    }
+    return { ok: true, json: async () => structuredClone(current) }
+  }
+  new Function('window', 'document', 'navigator', 'fetch', source)(window, document, {}, fetch)
+  loaded.factory((name) => { if (name === 'react') return React; throw new Error(name) }).apply({
+    effect: (fn) => fn(), slots: { inject: (_name, fn) => fn(), register: (meta, component) => { const entry = { meta, component }; registrations.push(entry); return () => registrations.splice(registrations.indexOf(entry), 1) } },
+  })
+  const view = registrations.find(({ meta }) => meta.name === 'settings.section' && meta.id === 'shell-select')
+  assert.ok(view, '设置导航缺少 shell-select 页面')
+  assert.equal(view.meta.label, 'Shell 管理')
+  const render = () => { cursor = 0; effectCursor = 0; return view.component() }
+  const flush = async () => {
+    for (const effect of effects) if (effect.pending) { effect.pending = false; effect.cleanup = effect.fn() }
+    await new Promise(setImmediate)
+  }
+  const initial = render()
+  await flush()
+  const nodes = (tree) => {
+    const found = []
+    const walk = (node) => { if (Array.isArray(node)) return node.forEach(walk); if (!node || typeof node !== 'object') return; found.push(node); node.children?.forEach(walk) }
+    walk(tree)
+    return found
+  }
+  const button = (tree, label) => nodes(tree).find((node) => node.type === 'button' && node.children.includes(label))
+  const field = (tree, label) => nodes(tree).find((node) => node.props['aria-label'] === label)
+  const dirty = () => {
+    const input = field(render(), '客户端 1 id')
+    input.props.onChange({ target: { value: input.props.value } })
+  }
+  return { initial, render, flush, nodes, button, field, dirty, requests, restoreLoad: () => { failLoad = false } }
+}
+
+// Given 插件启用；When 打开设置；Then 页面注册并加载当前配置而非出厂值。
+test('设置入口:注册 Shell 管理并展示当前客户端、默认值与加载状态', async () => {
+  const p = await page()
+  assert.match(JSON.stringify(p.initial), /加载中/)
+  const tree = p.render()
+  assert.equal(p.field(tree, '客户端 1 默认').props.checked, true)
+  assert.equal(p.field(tree, '客户端 1 默认').props.type, 'radio')
+  assert.equal(p.field(tree, '客户端 1 id').props.value, 'git-bash')
+  assert.equal(p.button(tree, '保存').props.disabled, true)
+  assert.equal(p.field(tree, '客户端 1 参数').type, 'input')
+  assert.match(p.field(tree, '客户端 1 环境').props.value, /^NOTE=a=b c\nMULTI=/)
+  assert.equal(p.field(tree, '黑名单第 2 条').props.value, ' foo ')
+  assert.equal(p.field(tree, '默认客户端'), undefined)
+  p.field(tree, '客户端 2 默认').props.onChange()
+  assert.equal(p.field(p.render(), '客户端 2 默认').props.checked, true)
+  assert.equal(p.button(p.render(), '保存').props.disabled, false)
+})
+
+// Given 已有含空格参数和环境值；When 保存；Then 完整保留客户端字段、deny 与顶层配置。
+test('保存:参数、环境、黑名单及预算字段无损往返', async () => {
+  const p = await page()
+  p.dirty()
+  await p.button(p.render(), '保存').props.onClick()
+  assert.equal(p.button(p.render(), '保存').props.disabled, true)
+  const written = JSON.parse(p.requests.find((row) => row.method === 'POST').body)
+  assert.deepEqual(written.shells, section().shells)
+  assert.deepEqual(written.deny, section().deny)
+  assert.equal(written.timeoutMs, 120000)
+  assert.equal(written.default, 'git-bash')
+  assert.ok(!('resolved' in written))
+  assert.match(JSON.stringify(p.render()), /已保存/)
+})
+
+// Given 多个客户端；When 改默认 id 或删除默认项；Then 默认值始终指向现有客户端。
+test('编辑:重命名及删除默认客户端同步更新默认值', async () => {
+  const p = await page()
+  p.field(p.render(), '客户端 1 id').props.onChange({ target: { value: 'bash-local' } })
+  assert.equal(p.field(p.render(), '客户端 1 默认').props.checked, true)
+  p.nodes(p.render()).find((node) => node.props['aria-label'] === '移除客户端 1').props.onClick()
+  assert.equal(p.field(p.render(), '客户端 1 默认').props.checked, true)
+})
+
+test('编辑:多个同类客户端可新增并保存独立 id', async () => {
+  const p = await page()
+  p.button(p.render(), '添加客户端').props.onClick()
+  p.field(p.render(), '客户端 3 id').props.onChange({ target: { value: 'bash-extra' } })
+  await p.button(p.render(), '保存').props.onClick()
+  const payload = JSON.parse(p.requests.find((row) => row.method === 'POST').body)
+  assert.deepEqual(payload.shells.map((entry) => entry.id), ['git-bash', 'pwsh', 'bash-extra'])
+})
+
+// Given 非法配置；When 保存；Then 错误可见且不发写请求。
+for (const [label, value, error] of [
+  ['客户端 2 id', 'git-bash', '重复'],
+  ['客户端 1 参数', '"unterminated', '引号'],
+  ['客户端 1 环境', 'invalid', '环境'],
+  ['黑名单第 1 条', '[', '正则'],
+]) test('非法输入阻止保存: ' + label, async () => {
+  const p = await page()
+  p.field(p.render(), label).props.onChange({ target: { value } })
+  await p.button(p.render(), '保存').props.onClick()
+  assert.equal(p.requests.filter((row) => row.method === 'POST').length, 0)
+  assert.match(JSON.stringify(p.render()), new RegExp(error))
+})
+
+test('加载失败:显示错误及重新加载操作', async () => {
+  const p = await page({ failLoad: true })
+  assert.match(JSON.stringify(p.render()), /加载故障/)
+  assert.ok(p.button(p.render(), '重新加载'))
+  p.restoreLoad()
+  p.button(p.render(), '重新加载').props.onClick()
+  p.render()
+  await p.flush()
+  assert.equal(p.field(p.render(), '客户端 1 默认').props.checked, true)
+})
+
+test('原规则交互:添加空行不生成空正则,逐行删除与编辑可保存', async () => {
+  const p = await page()
+  p.button(p.render(), '添加规则').props.onClick()
+  assert.equal(p.field(p.render(), '黑名单第 5 条').props.value, '')
+  p.field(p.render(), '黑名单第 1 条').props.onChange({ target: { value: '^danger' } })
+  p.field(p.render(), '删除规则 2').props.onClick()
+  await p.button(p.render(), '保存').props.onClick()
+  const payload = JSON.parse(p.requests.find((row) => row.method === 'POST').body)
+  assert.deepEqual(payload.deny, ['^danger', ' ', 'echo\nsecret'])
+})
+
+test('原参数环境文本:引号内空格与 K=V 值可编辑,不暴露 JSON', async () => {
+  const p = await page()
+  p.field(p.render(), '客户端 1 参数').props.onChange({ target: { value: '-c "echo new words" {command}' } })
+  p.field(p.render(), '客户端 1 环境').props.onChange({ target: { value: 'NOTE=a=b c\nOTHER= two words ' } })
+  await p.button(p.render(), '保存').props.onClick()
+  const shell = JSON.parse(p.requests.find((row) => row.method === 'POST').body).shells[0]
+  assert.deepEqual(shell.args, ['-c', 'echo new words', '{command}'])
+  assert.deepEqual(shell.env, { NOTE: 'a=b c', OTHER: ' two words ' })
+})
+
+test('编辑再还原:参数与环境原始数组和换行值仍无损', async () => {
+  const p = await page()
+  for (const label of ['客户端 1 参数', '客户端 1 环境']) {
+    const original = p.field(p.render(), label).props.value
+    p.field(p.render(), label).props.onChange({ target: { value: 'temporary' } })
+    p.field(p.render(), label).props.onChange({ target: { value: original } })
+  }
+  await p.button(p.render(), '保存').props.onClick()
+  const shell = JSON.parse(p.requests.find((row) => row.method === 'POST').body).shells[0]
+  assert.deepEqual(shell.args, section().shells[0].args)
+  assert.deepEqual(shell.env, section().shells[0].env)
+})
+
+test('修改单个环境变量:其他含换行与反斜线的值保持不变', async () => {
+  const p = await page()
+  const original = p.field(p.render(), '客户端 1 环境').props.value
+  p.field(p.render(), '客户端 1 环境').props.onChange({ target: { value: original.replace('NOTE=a=b c', 'NOTE=changed value') } })
+  await p.button(p.render(), '保存').props.onClick()
+  const posted = p.requests.find((row) => row.method === 'POST')
+  assert.ok(posted, '编辑普通变量不应使已有多行值阻止保存')
+  assert.deepEqual(JSON.parse(posted.body).shells[0].env, { ...section().shells[0].env, NOTE: 'changed value' })
+})
+
+test('双引号 Windows 参数:路径反斜线不能被当成 JSON 控制字符', async () => {
+  const p = await page()
+  const path = 'C:\\Program Files\\Git\\bin\\bash.exe'
+  p.field(p.render(), '客户端 1 参数').props.onChange({ target: { value: '-c "' + path + '" {command}' } })
+  await p.button(p.render(), '保存').props.onClick()
+  const posted = p.requests.find((row) => row.method === 'POST')
+  assert.ok(posted)
+  assert.deepEqual(JSON.parse(posted.body).shells[0].args, ['-c', path, '{command}'])
+})
+
+test('参数修改保真:只追加参数仍保留原有空项、引号、反斜线与控制字符', async () => {
+  const p = await page()
+  const original = p.field(p.render(), '客户端 1 参数').props.value
+  p.field(p.render(), '客户端 1 参数').props.onChange({ target: { value: original + ' extra' } })
+  await p.button(p.render(), '保存').props.onClick()
+  const posted = p.requests.find((row) => row.method === 'POST')
+  assert.ok(posted)
+  assert.deepEqual(JSON.parse(posted.body).shells[0].args, [...section().shells[0].args, 'extra'])
+})
+
+test('扫描不产生未保存改动:保存仍禁用', async () => {
+  const p = await page()
+  await p.button(p.render(), '扫描本机').props.onClick()
+  assert.equal(p.button(p.render(), '保存').props.disabled, true)
+})
+
+test('探测:独立调用路径与扫描接口,不提交配置', async () => {
+  const p = await page()
+  p.field(p.render(), '客户端 1 路径').props.onChange({ target: { value: 'C:/Git/bash.exe' } })
+  await p.button(p.render(), '探测路径').props.onClick()
+  assert.match(JSON.stringify(p.render()), /路径存在/)
+  await p.button(p.render(), '扫描本机').props.onClick()
+  assert.match(JSON.stringify(p.render()), /C:\/Git\/bash.exe/)
+  assert.equal(p.requests.filter((row) => row.path.endsWith('/config') && row.method === 'POST').length, 0)
+})
+
+test('提交成功但回读失败:明确已保存,不误报提交失败', async () => {
+  const p = await page({ failReadBack: true })
+  p.dirty()
+  await p.button(p.render(), '保存').props.onClick()
+  assert.equal(p.requests.filter((row) => row.method === 'POST').length, 1)
+  const text = JSON.stringify(p.render())
+  assert.match(text, /已保存.*刷新失败.*回读故障/)
+  assert.doesNotMatch(text, /保存失败/)
+})
+
+test('保存失败:保留输入并显示服务端错误', async () => {
+  const p = await page({ failSave: true })
+  p.field(p.render(), '客户端 1 id').props.onChange({ target: { value: 'edited' } })
+  await p.button(p.render(), '保存').props.onClick()
+  assert.equal(p.field(p.render(), '客户端 1 id').props.value, 'edited')
+  assert.match(JSON.stringify(p.render()), /写入故障/)
+})

package/test/executor.test.mjs

@@ -443,12 +443,18 @@ test('构造:boxed volatile 字段(宿主 resolve 产物)解箱生效,不回落
   assert.deepEqual(listing.shells.map((entry) => entry.id), ['pwsh', 'git-bash'])
   assert.equal(executor.entryFor(undefined).id, 'git-bash')
   const shell = registered.tools.find((tool) => tool.name === 'shell')
-  assert.match(shell.description, /git-bash \(bash\)$|default client is "git-bash"/)
-  assert.doesNotMatch(shell.description, /cmd \(cmd\)/)
+  assert.match(shell.description, /^Execute commands using shell="git-bash" by default/)
+  assert.doesNotMatch(shell.description, /^- cmd —/m)
+  assert.equal(shell.parameters.properties.shell.description, 'Override the default shell using an id listed above.')
+  assert.doesNotMatch(shell.parameters.properties.sandbox_permissions.description, /retry/)
+  const prompt = registered.promptSections.find((section) => section.name === 'tool:shell').text
+  assert.match(prompt, /investigate failures/)
+  assert.match(prompt, /after an interruption/)
+  assert.doesNotMatch(prompt, /fresh processes|default client|Pass the `shell`/)
 })
 
 test('refresh:boxed volatile 字段换源同样解箱生效', () => {
-  const { ctx } = stubCtx()
+  const { ctx, registered } = stubCtx()
   const executor = new ShellSelectExecutor(ctx, baseConfig())
   executor.refresh(boxFields({
     shells: baseConfig().shells,
@@ -458,6 +464,8 @@ test('refresh:boxed volatile 字段换源同样解箱生效', () => {
   const listing = executor.listShells()
   assert.equal(listing.default, 'git-bash')
   assert.equal(listing.shells.length, 3)
+  assert.match(registered.tools.findLast((tool) => tool.name === 'shell').description,
+    /^Execute commands using shell="git-bash" by default/)
 })
 
 test('构造:混合形态(部分字段 boxed 部分普通)逐字段解箱生效', () => {

package/test/guard-entry.test.mjs

@@ -45,6 +45,9 @@ function stubCtx({ rows, importOfficial }) {
         },
       })
     },
+    effect(execute) {
+      return execute()
+    },
   }
   return { ctx, log, mounts, listeners }
 }

package/test/guard-lifecycle.test.mjs

@@ -0,0 +1,110 @@
+// guard 生命周期:定时器随 fiber 清理(effect),停机竞态异常不逃逸为
+// unhandledRejection——宿主 fail-loud 会把这类逃逸判为 fatal load failure
+// 杀掉整个进程(dsh-maintain 重启停机窗口实测事故)。
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { setTimeout as sleep } from 'node:timers/promises'
+import { installGuard } from '../src/guard.js'
+import { MAIN_ROW_ID } from '../src/guard-state.mjs'
+
+const OFFICIAL_MODULE = (name) => ({ __name: name, name, apply() {} })
+const makeImport = async (packageName) => OFFICIAL_MODULE(packageName)
+
+function row({ id, disabled = false, running = false }) {
+  return {
+    options: { id },
+    get disabled() {
+      return disabled
+    },
+    fiber: running ? { uid: 'f' } : undefined,
+  }
+}
+
+function deadWorld() {
+  return [
+    row({ id: MAIN_ROW_ID, disabled: true }),
+    row({ id: 'tool-pwsh', disabled: true }),
+    row({ id: 'pwsh-sandbox', disabled: true }),
+  ]
+}
+
+function stubCtx({ rows, resolveCount = { value: 0 } }) {
+  const log = []
+  const mounts = []
+  const effects = []
+  const listeners = new Map()
+  const ctx = {
+    logger: {
+      warn: (msg) => log.push(['warn', msg]),
+      error: (msg) => log.push(['error', msg]),
+      info: (msg) => log.push(['info', msg]),
+    },
+    get loader() {
+      return {
+        resolve(id) {
+          resolveCount.value += 1
+          const found = rows.find((candidate) => candidate.options.id === id)
+          if (found) return found
+          throw new Error('not found')
+        },
+      }
+    },
+    on(event, handler) {
+      listeners.set(event, handler)
+    },
+    effect(execute, label) {
+      const dispose = execute()
+      effects.push({ label, dispose })
+      return dispose
+    },
+    plugin(module, config) {
+      mounts.push({ moduleName: module.__name, config })
+      return Promise.resolve({
+        dispose: () => {
+          mounts.length = 0
+          return Promise.resolve()
+        },
+      })
+    },
+  }
+  return { ctx, log, mounts, effects, resolveCount }
+}
+
+test('定时器随 fiber 清理:effect dispose 后不再扫描', async () => {
+  const sweepIntervalMs = 20
+  const { ctx, mounts, effects, resolveCount } = stubCtx({ rows: deadWorld() })
+  await installGuard(ctx, { importOfficial: makeImport, sweepIntervalMs })
+  assert.equal(mounts.length, 2)
+  const timerEffect = effects.find((entry) => entry.label.includes('sweep'))
+  assert.ok(timerEffect, 'sweep 定时器必须注册为 effect')
+  assert.equal(typeof timerEffect.dispose, 'function')
+  timerEffect.dispose()
+  await sleep(sweepIntervalMs * 3)
+  const settled = resolveCount.value
+  await sleep(sweepIntervalMs * 3)
+  assert.equal(resolveCount.value, settled, 'dispose 后不得再有 sweep 扫描')
+})
+
+test('sweep 异常不逃逸:停机竞态下 loader 抛错不产生 unhandledRejection', async () => {
+  const sweepIntervalMs = 20
+  const { ctx, mounts } = stubCtx({ rows: deadWorld() })
+  await installGuard(ctx, { importOfficial: makeImport, sweepIntervalMs })
+  assert.equal(mounts.length, 2)
+  // 模拟 fiber 停用后 ctx.loader 访问抛 inactive context 错误
+  Object.defineProperty(ctx, 'loader', {
+    get() {
+      throw new Error('cannot get required service "loader" in inactive context')
+    },
+  })
+  const rejections = []
+  const onRejection = (error) => rejections.push(error)
+  process.on('unhandledRejection', onRejection)
+  try {
+    await sleep(sweepIntervalMs * 4)
+    assert.equal(mounts.length, 2, '异常不得破坏已挂载状态')
+    assert.deepEqual(rejections, [])
+  } finally {
+    process.off('unhandledRejection', onRejection)
+  }
+})

package/test/path-guidance.test.mjs

@@ -6,13 +6,62 @@ import assert from 'node:assert/strict'
 import { shellDescription } from '../src/tool.mjs'
 
 const FACES = { backgroundEnabled: true, escalationModes: [] }
-const entry = (id, kind, available) => ({ id, kind, available })
+const entry = (id, kind, available, distro = '') => ({ id, kind, available, distro })
+
+// Given 用户自定义多个客户端且删除 pwsh；When 生成描述；Then 默认值优先，各 id 独立呈现环境。
+test('动态客户端:默认值优先,多个 Bash 与 WSL 发行版独立列出', () => {
+  const executor = { listShells: () => ({ default: 'bash-alt', shells: [
+    entry('git-bash', 'bash', true), entry('bash-alt', 'bash', true),
+    entry('ubuntu', 'wsl', true, 'Ubuntu'), entry('linux', 'wsl', true),
+    entry('legacy', 'cmd', false),
+  ] }) }
+  const text = shellDescription({ executor, ...FACES })
+  assert.ok(text.startsWith('Execute commands using shell="bash-alt" by default and return stdout/stderr.'))
+  assert.match(text, /Omit shell to use the default; set it to one of:/)
+  assert.match(text, /^- git-bash — Bash$/m)
+  assert.match(text, /^- bash-alt — Bash$/m)
+  assert.match(text, /^- ubuntu — WSL \(Ubuntu\)$/m)
+  assert.match(text, /^- linux — WSL$/m)
+  assert.match(text, /^- legacy — Windows cmd\.exe \(unavailable\)$/m)
+  assert.doesNotMatch(text, /pwsh|PowerShell/)
+})
+
+// Given 仅有一个 PowerShell 客户端；When 配置默认值更新；Then 描述同步变化且无额外客户端。
+test('单客户端:默认值及工作环境来自当前配置', () => {
+  let listing = { default: 'office', shells: [entry('office', 'pwsh', true)] }
+  const executor = { listShells: () => listing }
+  assert.match(shellDescription({ executor, ...FACES }), /shell="office"[\s\S]*^- office — PowerShell$/m)
+  listing = { default: 'console', shells: [entry('console', 'cmd', true)] }
+  const text = shellDescription({ executor, ...FACES })
+  assert.match(text, /shell="console"[\s\S]*^- console — Windows cmd\.exe$/m)
+  assert.doesNotMatch(text, /office|PowerShell/)
+})
+
+// Given 升权面存在；When 生成模型主描述；Then 只讲常规调用，不注入拒绝重试流程。
+test('主描述:常规调用说明不随升权面增加拒绝流程', () => {
+  const executor = { listShells: () => ({ default: 'ps', shells: [entry('ps', 'pwsh', true)] }) }
+  const text = shellDescription({ executor, ...FACES, escalationModes: ['workspace-write'] })
+  assert.equal(text, shellDescription({ executor, ...FACES }))
+  assert.match(text, /fresh process/)
+  assert.match(text, /run_in_background=true/)
+  assert.match(text, /job_output.*job_kill/)
+  assert.match(text, /full-output file path/)
+  assert.doesNotMatch(text, /retry|denial|sandbox_permissions|DSH_\*|exit code/)
+})
+
+// Given 后台执行未启用；When 生成描述；Then 不建议后台调用。
+test('后台不可用:不展示后台参数或任务工具', () => {
+  const executor = { listShells: () => ({ default: 'ps', shells: [entry('ps', 'pwsh', true)] }) }
+  const text = shellDescription({ executor, ...FACES, backgroundEnabled: false })
+  assert.doesNotMatch(text, /run_in_background|job_output|job_kill/)
+  assert.match(text, /within the timeout/)
+})
 
 test('A1 含可用 bash 条目:描述含 Windows-style 路径措辞', () => {
   const executor = { listShells: () => ({ default: 'pwsh', shells: [entry('pwsh', 'pwsh', true), entry('git-bash', 'bash', true)] }) }
   const text = shellDescription({ executor, ...FACES })
   assert.match(text, /Windows-style paths/)
-  assert.match(text, /`workdir`/)
+  assert.match(text, /Windows-style paths \(C:\/\.\.\.\) in workdir and file-tool arguments/)
 })
 
 test('A2 仅 pwsh/cmd:不含措辞', () => {