@mzzsfy/dsh-shell-select 0.4.0 → 0.4.1

package/README.md

@@ -28,9 +28,9 @@ Windows shell 链接管:禁用官方 `pwsh` 工具与执行器,替换为可配
 注册 keyed slot `tool.call.toolview`(key `shell`/`pwsh`/`bash` 三支,priority -1)替换默认通用卡,官方 `terminalCardModel` 同构派生(argsRaw + 结果文本尾部退出标记)。`pwsh`/`bash` 两支覆盖官方工具名:死态窗口 guard 代挂官方 tool-pwsh 时,其调用行同样获得增强卡;persistent 形(无 description)与后台 ack、isError、溢出预览一样回退简版行,不误渲染:
 
 - 折叠行:状态点(失败红/中断黄/其余工具图标)+ `Shell` 标题 + 描述首行摘要,失败摘要红显。
-- 展开卡:状态点 + cwd 末段目录 + 客户端名徽标(模型传了 `shell` 参数时)+ 失败 pill(退出码/信号)+ 复制命令/复制输出按钮 + 命令折行带行号 + 输出区(横向滚动,竖向限高)。
+- 展开卡:状态点 + cwd 末段目录 + 客户端名徽标 + 失败 pill(退出码/信号)+ 复制命令/复制输出按钮 + 命令折行带行号 + 输出区(横向滚动,竖向限高)。徽章忠实于执行事实:每次调用结果尾附 `[shell: <id>]` 标记(模型可见,官方退出标记同族),卡片按标记回放实际生效的客户端——缺省调用在配置事后变更或跨宿主查看时不被查看时读数改写;无标记的历史块回退显式参数 → 当前 default 推导。`pwsh`/`bash` 官方工具的调用无标记无 shell 参数,徽章按工具名钉死(客户端即工具名),永不落 default 读数。
 - 非终端意图回退简版行:摘要 + 可展开原文 + 检查按钮。
-- 图标取官方 `dsh-client-ui-primitives`(StateDot/IconApi/IconInspect/Chevron),模块表缺席时降级自绘。
+- 图标取官方 `dsh-client-ui-primitives`(StateDot/IconApi/IconInspect),模块表缺席时降级自绘。行首无展开箭头,与官方组件一致,可展开性由指针与整行点击承载。
 
 ## 配置(行条目 `shell-select`,settings 面同名 ns)
 
@@ -92,4 +92,17 @@ env 优先级(同键高右):内置覆盖集(NO_COLOR/PAGER/GIT_PAGER)< 条目 `e
       name: '@mzzsfy/dsh-shell-select/web'
 ```
 
+
+## dsh 版本兼容
+
+宿主要求 ≥0.1.7-rc.1:bundle patch 引用 0.1.7 才有的 @deepseek-ai/dsh-agent-preset 宿主包,更旧宿主安装即 boot 失败(2026-09-27 裁定不视为缺陷)。
+
+- 0.2.0-rc.2:完全适配(设置面通过;16 格 LLM 工具调用格因模拟模型无 tool_calls 能力登记环境不可测,历史真机记录与单元测试覆盖)
+- 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"`(包目录内)。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mzzsfy/dsh-shell-select",
   "description": "Windows shell 接管:替换默认 pwsh 工具为可配置多客户端的 shell 工具(git bash/WSL/cmd/pwsh,自定义路径,默认客户端,模型按名选择)",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "type": "module",
   "main": "src/index.js",
   "exports": {

package/src/client.js

@@ -41,9 +41,6 @@ window.__ModuleLoader__.load({
           opacity: .7, display: 'inline-block', flex: 'none',
         },
       })),
-      IconChevron: createElementOf(['IconChevronDownOutlineRegular', 'IconChevronDownOutlineMedium', 'IconChevronDownOutline14'], ({ size }) => h('span', {
-        style: { fontSize: (size ?? 14) - 3, lineHeight: 1, userSelect: 'none' },
-      }, '▾')),
       IconInspect: createElementOf(['IconInspectOutlineRegular', 'IconInspectOutlineMedium', 'IconInspectOutline12'], () => h('span', {
         style: { fontSize: 10, lineHeight: 1, opacity: .8 },
       }, 'ⓘ')),
@@ -134,17 +131,13 @@ window.__ModuleLoader__.load({
       '.sls-tv__row { display:flex; align-items:center; gap:7px; padding:2px 0; cursor:default; }',
       '.sls-tv__row--exp { cursor:pointer; user-select:none; }',
       '.sls-tv__lead { display:flex; align-items:center; gap:4px; color:var(--dsw-alias-label-tertiary, inherit); }',
-      // 官方 DisclosureRow 同构:icon 与 chevron 同 16px 槽,hover 交叉淡化;
+      // 官方 ToolRow 同构:行首仅 icon,无展开箭头(可展开性由指针与整行点击承载);
       // 错误/进行中状态点绝对定位覆盖 icon(红点掩盖 icon)
       '.sls-tv__leadStack { position:relative; width:16px; height:16px; display:inline-flex; align-items:center; justify-content:center; flex:none; }',
-      '.sls-tv__iconIdle { display:inline-flex; opacity:1; transition:opacity 100ms ease; }',
+      '.sls-tv__iconIdle { display:inline-flex; }',
       '.sls-tv__stateCover { position:absolute; inset:0; margin:auto; display:inline-flex; align-items:center; justify-content:center; background:transparent; }',
       '.sls-tv__stateCover::before { content:""; position:absolute; inset:-2px; border-radius:50%; background:var(--dsw-alias-bg-primary, #fff); }',
       '.sls-tv__stateCover > span { position:relative; }',
-      '.sls-tv__row:hover .sls-tv__iconIdle { opacity:0; }',
-      '.sls-tv__chev { opacity:.45; transition:transform .15s ease, opacity .1s ease; }',
-      '.sls-tv__row:hover .sls-tv__chev { opacity:1; }',
-      '.sls-tv__row[data-open="1"] .sls-tv__chev { transform:rotate(-90deg); }',
       '.sls-tv__sr { position:absolute; width:1px; height:1px; overflow:hidden; clip:rect(0 0 0 0); }',
       '.sls-tv__title { font-weight:400; }',
       '.sls-tv__sep { width:2px; height:2px; border-radius:1px; background:var(--dsw-alias-label-caption, currentColor); opacity:.8; flex:none; }',
@@ -152,13 +145,14 @@ window.__ModuleLoader__.load({
       '.sls-tv__sum--err { color:var(--dsw-alias-state-error-primary, #d4553f); }',
       '.sls-tv__body { margin:6px 0 4px; border:1px solid rgba(128,128,128,.28); border-radius:8px; overflow:hidden; }',
       '.sls-tv__head { display:flex; align-items:center; gap:8px; padding:6px 10px; border-bottom:1px solid rgba(128,128,128,.18); background:rgba(128,128,128,.05); }',
-      '.sls-tv__cwd { font-family:var(--sls-mono, monospace); font-size:12px; opacity:.7; }',
-      '.sls-tv__badge { font-size:11px; padding:0 7px; border-radius:999px; border:1px solid rgba(128,128,128,.35); opacity:.85; flex:none; }',
-      '.sls-tv__pill { font-size:12px; color:#d4553f; flex:none; }',
+      // 头部单行片段禁折行:cwd 行宽不足时收缩出省略号,徽章不收缩不折行
+      '.sls-tv__cwd { font-family:var(--sls-mono, monospace); font-size:12px; opacity:.7; white-space:nowrap; overflow:hidden; text-overflow:ellipsis; }',
+      '.sls-tv__badge { font-size:11px; padding:0 7px; border-radius:999px; border:1px solid rgba(128,128,128,.35); opacity:.85; flex:none; white-space:nowrap; }',
+      '.sls-tv__pill { font-size:12px; color:#d4553f; flex:none; white-space:nowrap; }',
       '.sls-tv__pill--bg { color:var(--dsw-alias-label-tertiary, inherit); }',
-      '.sls-tv__duration { font-family:var(--sls-mono, monospace); font-size:12px; color:var(--dsw-alias-label-tertiary, inherit); flex:none; font-variant-numeric:tabular-nums; }',
+      '.sls-tv__duration { font-family:var(--sls-mono, monospace); font-size:12px; color:var(--dsw-alias-label-tertiary, inherit); flex:none; white-space:nowrap; font-variant-numeric:tabular-nums; }',
       // 运行中脉冲文字:零信息窗口(参数未到)的活体反馈
-      '.sls-tv__pulse { font-size:12px; color:var(--dsw-alias-label-tertiary, inherit); flex:none; animation:sls-pulse 1.5s ease-in-out infinite; }',
+      '.sls-tv__pulse { font-size:12px; color:var(--dsw-alias-label-tertiary, inherit); flex:none; white-space:nowrap; animation:sls-pulse 1.5s ease-in-out infinite; }',
       '@keyframes sls-pulse { 0%,100% { opacity:.35; } 50% { opacity:1; } }',
       '.sls-tv__sp { flex:1; }',
       '.sls-tv__copy { display:flex; align-items:center; gap:2px; flex:none; }',
@@ -616,11 +610,25 @@ window.__ModuleLoader__.load({
     }
     // LOGIC-END hasSpillNotice
 
+    // 执行事实标记(host renderResult 落,格式见 render.mjs):卡片徽章第一优先级,
+    // 配置事后变更/跨宿主查看不溯往改写历史调用
+    // LOGIC-BEGIN parseShellMark
+    function parseShellMark(text) {
+      return /\[shell: ([^\]\n]+)\]/.exec(text)?.[1]
+    }
+    // LOGIC-END parseShellMark
+
+    // LOGIC-BEGIN stripShellMark
+    function stripShellMark(text) {
+      return text.split('\n').filter((line) => !/^\[shell: [^\]]+\]$/.test(line)).join('\n')
+    }
+    // LOGIC-END stripShellMark
+
     // block → 卡片模型(官方 terminalCardModel 同构,数据源 argsRaw + content 文本)。
     // generic = 后台 ack / isError / 溢出预览 / persistent 形(无 description,
     // 官方 shellCall persistent→generic 同构),交回退行;terminal = 全量卡。
     // LOGIC-BEGIN shellCardModel
-    function shellCardModel(block, sessionCwd) {
+    function shellCardModel(block, sessionCwd, toolKey) {
       const settled = 'kind' in block
       const call = settled ? block.call : block
       let args = null
@@ -632,37 +640,44 @@ window.__ModuleLoader__.load({
       const description = typeof args?.description === 'string' && args.description.trim() !== '' ? args.description : undefined
       const cwdFull = displayCwd(typeof args?.workdir === 'string' ? args.workdir : undefined, sessionCwd)
       const cwdDir = cwdFull !== undefined ? lastSegment(cwdFull) : undefined
-      // shell 名 = 用户在配置页起的条目名;args.shell 缺省时按 default 客户端解析(配置当前读数)
-      const shellName = clientDisplayName(typeof args?.shell === 'string' ? args.shell : undefined)
+      // 官方钉死客户端工具(bash/pwsh)徽章即工具名:其输出无标记、参数无 shell
+      // 字段,落默认读数会误标(官方 pwsh 调用显示当前默认客户端的事故根因)
+      const PINNED_CLIENT = { pwsh: 'pwsh', bash: 'bash' }
+      // shell 工具徽章优先级:结果标记(执行事实)→ 显式参数 → default 读数(旧块兜底,
+      // 配置即当前解析事实);读数推导仅兜无标记历史块,不覆盖事实
+      const requested = typeof args?.shell === 'string' ? args.shell : undefined
+      const shellNameOf = (mark) => PINNED_CLIENT[toolKey] ?? mark ?? clientDisplayName(requested)
       if (command === '') return { kind: 'generic', command: '', summary: undefined, output: null, running: !settled, alert: undefined }
 
       if (!settled) {
         const startedAt = typeof block.time === 'number' ? block.time : undefined
-        // 运行中一律全量卡:阻塞时展开即可见命令与时长,不落无命令的 generic 回退行
-        return { kind: 'terminal', status: 'running', command, description, cwdDir, cwdFull, shellName, output: undefined, exitCode: undefined, signal: undefined, code: undefined, startedAt }
+        // 运行中一律全量卡:阻塞时展开即可见命令与时长,不落无命令的 generic 回退行;
+        // 无结果文本,徽章按读数推导,落定后由标记校正
+        return { kind: 'terminal', status: 'running', command, description, cwdDir, cwdFull, shellName: shellNameOf(undefined), output: undefined, exitCode: undefined, signal: undefined, code: undefined, startedAt }
       }
 
       const contentText = (block.content ?? []).map((part) => (part.type === 'text' ? part.text : '')).filter((text) => text !== '').join('\n')
+      const shellName = shellNameOf(parseShellMark(contentText))
+      const outputText = stripShellMark(contentText)
       // 后台 ack:独立卡呈现命令全文与任务号徽标,ack 原文作输出(不再落 generic 简版行)
       if (args.run_in_background === true) {
         const jobId = /started background job (\S+)/.exec(contentText)?.[1]
-        return { kind: 'background', status: 'background', command, description, cwdDir, cwdFull, shellName, output: contentText, jobId }
+        return { kind: 'background', status: 'background', command, description, cwdDir, cwdFull, shellName, output: outputText, jobId }
       }
       // 空结果落 generic:官方 singleResultText 无文本即回通用卡,避免空输出伪 done 终端卡;
       // isError/error 块带 alert(错误红点语义),其余(空输出/无描述/截断)中性无状态点
-      if (contentText === '' || block.isError === true || block.error !== undefined || description === undefined || hasSpillNotice(contentText)) {
+      if (outputText === '' || block.isError === true || block.error !== undefined || description === undefined || hasSpillNotice(contentText)) {
         const alert = block.isError === true || block.error !== undefined ? 'error' : undefined
-        return { kind: 'generic', command, summary: description, output: contentText, running: false, alert }
+        return { kind: 'generic', command, summary: description, output: outputText, running: false, alert }
       }
-      const tail = parseExitTail(contentText)
+      const tail = parseExitTail(outputText)
       const status = tail.signal !== undefined ? 'signaled' : tail.exitCode !== 0 ? 'failed' : 'done'
       return { kind: 'terminal', status, command, description, cwdDir, cwdFull, shellName, output: tail.output, exitCode: tail.exitCode, signal: tail.signal, code: undefined }
     }
     // LOGIC-END shellCardModel
 
-    // 官方 DisclosureRow leading 同构:16px 槽内 icon 与 chevron 同位,
-    // 收起时 chevron hover 才现(交叉淡化),展开时仅 chevron-up;错误态
-    // 红点叠 icon 之上(掩盖 icon,官方状态点语义)
+    // 官方 ToolRow leading 同构:行首仅 icon;错误/进行中状态红点叠 icon 之上
+    // (掩盖 icon,官方状态点语义)
     function leadingStack({ status, icons }) {
       const failed = status === 'failed' || status === 'signaled' || status === 'generic-error'
       const dot = failed ? icons.StateDot({ state: 'error' }) : status === 'generic-warn' ? icons.StateDot({ state: 'warning' }) : status === 'running' ? icons.StateDot({ state: 'ongoing' }) : null
@@ -770,7 +785,6 @@ window.__ModuleLoader__.load({
         },
           h('span', { className: 'sls-tv__lead' },
             leadingStack({ status, icons: TOOLVIEW_ICONS }),
-            expandable ? h('span', { className: 'sls-tv__chev', 'data-open': open ? '1' : '0', style: { display: 'inline-flex', transform: open ? 'rotate(-90deg)' : 'none' } }, TOOLVIEW_ICONS.IconChevron({ size: 14 })) : null,
           ),
           h('span', { className: 'sls-tv__title' }, 'Shell'),
           summary !== '' ? h('span', { className: 'sls-tv__sep', 'aria-hidden': true }) : null,
@@ -833,9 +847,9 @@ window.__ModuleLoader__.load({
     }
 
     function ShellToolRow(props) {
-      const { block, cwd, inspect } = props
+      const { block, cwd, inspect, toolKey } = props
       const en = detectEnglish()
-      const model = shellCardModel(block, cwd)
+      const model = shellCardModel(block, cwd, toolKey)
       // hooks 恒序:必须在任何提前 return 之前完整执行(真实 React 的 hooks
       // 链表按调用序对位,generic 行与 terminal 行的提前 return 分叉会让
       // 后续 hook 错位,行组件树被整棵卸载——卡片全消失事故根因)
@@ -847,7 +861,6 @@ window.__ModuleLoader__.load({
         return () => { disposed = true }
       }, [])
       if (model.kind === 'generic') return h(GenericShellRow, { model, inspect, en })
-      const expandable = true
       const srStatus = statusTextOf(model.status, en)
       const summary = model.description !== undefined ? model.description.split('\n')[0] : (en ? '(no description)' : '(无描述)')
       const failed = model.status === 'failed' || model.status === 'signaled'
@@ -857,7 +870,6 @@ window.__ModuleLoader__.load({
           role: 'button',
           tabIndex: 0,
           'aria-expanded': open,
-          'data-open': open ? '1' : '0',
           onClick: () => setOpen((value) => !value),
           onKeyDown: (event) => {
             if (event.key === 'Enter' || event.key === ' ') {
@@ -868,7 +880,6 @@ window.__ModuleLoader__.load({
         },
           h('span', { className: 'sls-tv__lead' },
             leadingStack({ status: model.status, icons: TOOLVIEW_ICONS }),
-            h('span', { className: 'sls-tv__chev', style: { display: 'inline-flex', transform: open ? 'rotate(-90deg)' : 'none' } }, TOOLVIEW_ICONS.IconChevron({ size: 14 })),
           ),
           srStatus !== null ? h('span', { className: 'sls-tv__sr' }, srStatus) : null,
           h('span', { className: 'sls-tv__title' }, 'Shell'),
@@ -901,15 +912,15 @@ window.__ModuleLoader__.load({
           ))
         // 替换 shell 族工具行渲染:keyed hit 优先于 GenericToolCard 兜底;
         // priority -1 阴影官方同 key 注册(低值先渲染)。pwsh/bash 为官方工具
-        // 名(死态窗口 guard 代挂官方 tool-pwsh 时,其调用行同样获得增强卡;
-        // 卡片模型按官方 terminalCardModel 同构自 argsRaw+结果文本派生,数据
-        // 面对两类工具一致,无需分支)。
+        // 名(死态窗口 guard 代挂官方 tool-pwsh 时,其调用行同样获得增强卡);
+        // key 以 toolKey 注入卡片,官方钉死客户端工具的徽章按工具名钉死,
+        // 不落默认客户端读数。
         const TOOLVIEW_KEYS = ['shell', 'pwsh', 'bash']
         for (const toolKey of TOOLVIEW_KEYS) {
           ctx.slots.inject('tool.call.toolview', () =>
             ctx.slots.register(
               { name: 'tool.call.toolview', key: toolKey, priority: -1 },
-              (props) => React.createElement(ShellToolRow, props),
+              (props) => React.createElement(ShellToolRow, { ...props, toolKey }),
             ))
         }
       },

package/src/config.mjs

@@ -83,6 +83,72 @@ export function resolveConfig(entry) {
   return unwrapConfig(Config(structuredClone(sanitized)))
 }
 
+/** 执行面严格解析:输入键被类型对账丢弃时抛。执行面(挂载/refresh)输入是
+ * 宿主刚 resolve 的产物,形态非法 = 宿主契约变化或调用方未解箱,必须炸在
+ * 挂载点(接管序列有回滚告警)而非静默回落出厂默认——静默曾让行 config
+ * 长期失效(0.2.0-rc.2 真机实证)。持久化读回路径(落盘写坏降级、行不死
+ * 可保存修复)仍用 resolveConfig 的宽容语义。 */
+export function resolveConfigStrict(entry) {
+  const input = entry ?? {}
+  const sanitized = sanitizeConfigEntry(input)
+  const dropped = Object.keys(FIELD_TYPES)
+    .filter((key) => input[key] !== undefined && !(key in sanitized))
+  if (dropped.length > 0) {
+    throw new Error(`shell-select: config 字段形态非法(执行面输入须先解箱为普通对象): ${dropped.join(', ')}`)
+  }
+  return unwrapConfig(Config(structuredClone(sanitized)))
+}
+
+/** 用户声明值挂载前 coercing:类型清洗(sanitize)+ 语义兜底,任意用户输入
+ * 产出可服务配置——插件本体不因配置死(行活、工具活,坏字段告警后降默认)。
+ * 语义兜底:shells 清洗后为空(含条目缺 id/kind 或 kind 非法被剔除)补出厂
+ * 默认;default 不在 shells id 集归 shells[0];预算数字非正数或超 graceMs
+ * 上限降 schema 默认;deny 剔除非字符串与不可编译条目。 */
+export function coerceServiceable(entry) {
+  const warnings = []
+  const cleaned = sanitizeConfigEntry(entry ?? {})
+  const rawShells = Array.isArray(cleaned.shells) ? cleaned.shells : []
+  const usable = rawShells.filter((item) => item !== null && typeof item === 'object'
+    && typeof item.id === 'string' && item.id !== ''
+    && typeof item.kind === 'string' && KINDS.includes(item.kind))
+  if (usable.length !== rawShells.length) warnings.push(`shells 剔除 ${rawShells.length - usable.length} 个缺 id/kind 或 kind 非法的条目`)
+  const shells = usable.length > 0 ? usable : defaultConfig().shells
+  if (usable.length === 0) warnings.push('shells 为空或全部非法,回落出厂默认客户端清单')
+  let defaultId = cleaned.default
+  if (typeof defaultId !== 'string' || !shells.some((item) => item.id === defaultId)) {
+    warnings.push(`default ${JSON.stringify(defaultId)} 不在 shells 清单,归 shells[0]`)
+    defaultId = shells[0].id
+  }
+  const rawDeny = Array.isArray(cleaned.deny) ? cleaned.deny : undefined
+  const deny = rawDeny?.filter((pattern) => {
+    if (typeof pattern !== 'string' || pattern === '') return false
+    try {
+      new RegExp(pattern, 'i')
+      return true
+    } catch {
+      return false
+    }
+  })
+  if (rawDeny !== undefined && deny.length !== rawDeny.length) warnings.push(`deny 剔除 ${rawDeny.length - deny.length} 个非字符串或不可编译正则的条目`)
+  const budgets = {}
+  for (const key of ['timeoutMs', 'maxTimeoutMs', 'maxOutputBytes', 'maxSpillBytes', 'graceMs']) {
+    const value = cleaned[key]
+    if (value === undefined) continue
+    const overCeiling = key === 'graceMs' && value > MAX_TIMER_DELAY_MS
+    if (!Number.isFinite(value) || value <= 0 || overCeiling) {
+      warnings.push(`${key} 必须为正有限数${key === 'graceMs' ? `且不大于 ${MAX_TIMER_DELAY_MS}` : ''},降 schema 默认`)
+      // 显式置空覆盖 cleaned 原值,交 schema 默认兜底
+      budgets[key] = undefined
+      continue
+    }
+    budgets[key] = value
+  }
+  return {
+    config: { ...cleaned, shells, default: defaultId, deny, ...budgets },
+    warnings,
+  }
+}
+
 // 落盘行 config 的类型防御:设置写路径(原生页/mutate)可能把 volatile 字段
 // 以非预期形态(ref 序列化产物 {})持久化,冷启动 Config 直接抛 → 行死 →
 // settings describe 无此节 → 设置页保存 "no longer configurable" 死锁,

package/src/executor.mjs

@@ -14,7 +14,7 @@
 
 import { ShellExecutor } from '@deepseek-ai/dsh-shell'
 import { clampTimeout, deadline, timeoutOf } from '@deepseek-ai/dsh-timeout'
-import { Config, KINDS, buildArgv, requireEntry, resolveConfig, assertServiceableConfig, normalizeWin32Path } from './config.mjs'
+import { Config, KINDS, buildArgv, requireEntry, resolveConfig, resolveConfigStrict, unwrapConfig, assertServiceableConfig, normalizeWin32Path } from './config.mjs'
 import { matchDeny } from './denylist.mjs'
 import { candidateExists, detectCandidates, resolveEntryPath } from './resolve.mjs'
 import { classifyDenial, classifyRunnerFailure, isRunnerSpawnFailure } from './sandbox-classify.mjs'
@@ -137,8 +137,7 @@ export const ShellSelectExecutor = class ShellSelectExecutor extends ShellExecut
     void loadSandboxUnavailable(ctx).then((resolved) => {
       this.unavailableError = resolved
     })
-    this.#entry = config ?? {}
-    assertServiceableConfig(resolveConfig(this.#entry))
+    this.#setEntry(config)
     this.source = () => resolveConfig(this.#entry)
     // refresh 桥绑定随本 fiber 卸载自动解绑(实例退场后写路径请求静默丢弃)
     ctx.effect(() => bindShellRefreshBridge((next) => this.refresh(next)))
@@ -152,11 +151,19 @@ export const ShellSelectExecutor = class ShellSelectExecutor extends ShellExecut
     this.#mountPromptSection()
   }
 
+  /** 挂载/换源共用落定:入参经宿主按 static Config resolve,volatile 字段是
+   * boxed ref,存储前解箱成普通对象;落定校验走 strict——解箱后仍存在非法
+   * 形态字段即抛(宿主契约变化炸在挂载点,接管序列回滚告警),禁止静默回落
+   * 出厂默认(行 config 永不生效缺陷的机械化防线)。 */
+  #setEntry(config) {
+    this.#entry = unwrapConfig(config ?? {})
+    assertServiceableConfig(resolveConfigStrict(this.#entry))
+  }
+
   /** volatile-only 配置变更的活刷新:换配置源并重建工具注册(写路径经
    * requestShellRefresh 触达;行不重挂,本实例与进行中执行不受扰)。 */
   refresh(config) {
-    this.#entry = config ?? {}
-    assertServiceableConfig(resolveConfig(this.#entry))
+    this.#setEntry(config)
     this.#registerTool()
   }
 

package/src/index.js

@@ -31,6 +31,7 @@ import {
   runtimeDisableRows,
   takeoverDecision,
 } from './takeover.mjs'
+import { coerceServiceable } from './config.mjs'
 
 export const name = 'shell-select'
 
@@ -114,7 +115,12 @@ function unwrapConfigSnapshot(config) {
  * 快照经 ctx.shell.refresh 换源并重建工具。
  */
 async function mountExecutor(ctx, config) {
-  const fiber = await ctx.plugin(ShellSelectExecutor, unwrapConfigSnapshot(config))
+  // 用户声明值挂载前 coercing:任意配置(坏类型/空 shells/悬空 default/坏
+  // deny 正则)降级为可服务配置 + 逐条告警,行永不因配置死(官方链兜底之外
+  // 的第一道本体防线)
+  const { config: coerced, warnings } = coerceServiceable(unwrapConfigSnapshot(config))
+  for (const warning of warnings) ctx.logger?.warn?.(`shell-select: ${warning}`)
+  const fiber = await ctx.plugin(ShellSelectExecutor, coerced)
   // await 返回 ≠ 激活:executor inject 的宿主服务缺失时 fiber 静默 pending
   // (不 provide 不报错),ctx.shell 空缺会被官方复活行补位——挂载必须核实
   // 激活态,未激活按失败处理(触发回滚,官方接管)

package/src/render.mjs

@@ -14,8 +14,11 @@ function streamText(output) {
  * 前台运行结果 → 模型可见文本。
  * @param {object} result ShellRunResult(含 sandbox 事实)
  * @param {string[]} escalationModes 本组合公示的升权目标;非空时拒绝标记后附升权提示
+ * @param {string|undefined} shellId 执行事实:实际生效的客户端条目 id;缺省不落标记
+ * (渲染面与官方逐字同构)。标记居 markers 首位,官方退出/信号锚保持末行,
+ * parseExitStatus 复原不受扰;客户端半区据此校正卡片徽章(配置事后变更不溯往)。
  */
-export function renderResult(result, escalationModes = []) {
+export function renderResult(result, escalationModes = [], shellId) {
   const out = streamText(result.stdout)
   const err = streamText(result.stderr)
   let body = out
@@ -25,6 +28,7 @@ export function renderResult(result, escalationModes = []) {
   }
   if (body.length === 0) body = '(no output)'
   const markers = []
+  if (shellId !== undefined) markers.push(`[shell: ${shellId}]`)
   if (result.sandbox?.denied) {
     markers.push(sandboxDenialMarker(result.sandbox.mode))
     if (escalationModes.length > 0) markers.push(escalationHintMarker('command'))

package/src/tool.mjs

@@ -56,8 +56,8 @@ function processOutcome(proc) {
   return { status: 'completed', detail: `exit code: ${proc.exitCode ?? 0}` }
 }
 
-/** 前台结果 DTO 去只读化(官方 canonical 同构)。 */
-function canonicalResult(result) {
+/** 前台结果 DTO 去只读化(官方 canonical 同构);shellId 为执行事实,随块落存储供卡片徽章回放。 */
+function canonicalResult(result, shellId) {
   const output = (stream) => ({
     text: stream.text,
     truncated: stream.truncated,
@@ -72,6 +72,7 @@ function canonicalResult(result) {
     timeoutMs: result.timeoutMs,
     stdout: output(result.stdout),
     stderr: output(result.stderr),
+    ...shellId !== undefined ? { shell: shellId } : {},
     ...result.sandbox !== undefined ? { sandbox: {
       mode: result.sandbox.mode,
       denied: result.sandbox.denied,
@@ -81,10 +82,11 @@ function canonicalResult(result) {
   }
 }
 
-/** 后台输出并集公共键(官方同构)。 */
+/** 后台输出并集公共键(官方同构);shell 同前台,执行事实随 DTO 供渲染。 */
 const BACKGROUND_OUTPUT_PROPERTIES = {
   kind: { type: 'string', required: true, const: 'background' },
   jobId: { type: 'string', required: true },
+  shell: { type: 'string' },
 }
 
 /** 前台输出分支(官方同构,逐字段)。 */
@@ -108,6 +110,7 @@ function foregroundOutputProperties() {
     timeoutMs: { type: 'number', required: true },
     stdout: streamSchema,
     stderr: streamSchema,
+    shell: { type: 'string' },
     sandbox: {
       type: 'object',
       additionalProperties: false,
@@ -139,18 +142,9 @@ function shellDescription({ executor, backgroundEnabled, escalationModes }) {
   return base + ' 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`.'
 }
 
-/** pwsh 工具描述:兼容保留工具,开头一句禁止调用。 */
-function pwshDescription({ backgroundEnabled, escalationModes }) {
-  const base = 'Do not call this tool. It is kept only for backward compatibility with old sessions — call the `shell` tool instead. '
-    + 'It executes a PowerShell command and returns its stdout/stderr. '
-    + 'Each call runs in a fresh pwsh 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.')
-  if (escalationModes.length === 0) return base
-  return base + ' 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`.'
+/** pwsh 工具描述:兼容保留工具,只声明不要调用与去向,零执行语义。 */
+function pwshDescription() {
+  return 'Do not call; use `shell`.'
 }
 
 /**
@@ -189,7 +183,7 @@ export function registerShellTool(ctx, { executor }) {
     name: toolName,
     description: pinned === undefined
       ? shellDescription({ executor: faces.executor, backgroundEnabled, escalationModes })
-      : pwshDescription({ backgroundEnabled, escalationModes }),
+      : pwshDescription(),
     parameters: {
       command: {
         type: 'string',
@@ -243,7 +237,9 @@ export function registerShellTool(ctx, { executor }) {
       }] },
       render: (_args, value) => [{
         type: 'text',
-        text: value.kind === 'background' ? `started background job ${value.jobId}` : renderResult(value, escalationModes),
+        text: value.kind === 'background'
+          ? `started background job ${value.jobId}${value.shell !== undefined ? `\n[shell: ${value.shell}]` : ''}`
+          : renderResult(value, escalationModes, value.shell),
       }],
     },
     async execute(args, exec) {
@@ -269,11 +265,12 @@ export function registerShellTool(ctx, { executor }) {
         try {
           faces.executor.startFor(entry, faces.executor.resolve(request))
         } catch (error) {
-          if (isDenyError(error)) return { kind: 'foreground', blocked: true, blockedBy: error.pattern, exitCode: null, signal: null, timedOut: false, aborted: false, timeoutMs: 0, stdout: { text: '', truncated: false }, stderr: { text: blockedMarker(error), truncated: false } }
+          if (isDenyError(error)) return { kind: 'foreground', shell: entry.id, blocked: true, blockedBy: error.pattern, exitCode: null, signal: null, timedOut: false, aborted: false, timeoutMs: 0, stdout: { text: '', truncated: false }, stderr: { text: blockedMarker(error), truncated: false } }
           throw error
         }
         return {
           kind: 'background',
+          shell: entry.id,
           jobId: jobs.start({
             kind: 'shell',
             label: args.command,
@@ -296,11 +293,11 @@ export function registerShellTool(ctx, { executor }) {
           signal: exec.signal,
         }))
       } catch (error) {
-        if (isDenyError(error)) return { kind: 'foreground', blocked: true, blockedBy: error.pattern, exitCode: null, signal: null, timedOut: false, aborted: false, timeoutMs: 0, stdout: { text: '', truncated: false }, stderr: { text: blockedMarker(error), truncated: false } }
+        if (isDenyError(error)) return { kind: 'foreground', shell: entry.id, blocked: true, blockedBy: error.pattern, exitCode: null, signal: null, timedOut: false, aborted: false, timeoutMs: 0, stdout: { text: '', truncated: false }, stderr: { text: blockedMarker(error), truncated: false } }
         throw error
       }
       if (result.aborted) throw await abortError('tool call aborted')
-      return canonicalResult(result)
+      return canonicalResult(result, entry.id)
     },
     presentCall: (args) => {
       if (args.run_in_background === true) {

package/src/web-routes.mjs

@@ -5,7 +5,7 @@
 // settings.describe,写经 settings.replace;探测/扫描用 resolve 纯函数。
 // HTTP 形态(具名 exact 路由 + 跨源守卫 + 业务异常归一 400)照 dsh-maintain。
 
-import { KINDS, resolveConfig, assertServiceableConfig, normalizeConfigPaths, normalizeWin32Path } from './config.mjs'
+import { KINDS, resolveConfig, coerceServiceable, assertServiceableConfig, normalizeConfigPaths, normalizeWin32Path } from './config.mjs'
 import { candidateExists, detectCandidates, resolveEntryPath } from './resolve.mjs'
 import { requestShellRefresh } from './executor.mjs'
 import { mountRoutes } from './api.mjs'
@@ -48,7 +48,9 @@ function readSection(ctx, settings) {
     ctx.logger?.warn?.(`shell-select: settings 面无 "${SECTION_NS}" 节,设置页回落出厂默认`)
     return resolveConfig({})
   }
-  return resolveConfig(found.value ?? {})
+  // 读出面同走 coercing:落盘坏值(悬空 default/空 shells)投影为可服务配置,
+  // 设置页显示与执行面一致,不再暴露不可服务的中间态
+  return resolveConfig(coerceServiceable(found.value ?? {}).config)
 }
 
 /**

package/test/client-card.test.mjs

@@ -26,6 +26,8 @@ function cardModel(catalog = null) {
     lastSegment,
     parseExitTail: extractLogic('parseExitTail'),
     hasSpillNotice: extractLogic('hasSpillNotice'),
+    parseShellMark: extractLogic('parseShellMark'),
+    stripShellMark: extractLogic('stripShellMark'),
     clientDisplayName: extractLogic('clientDisplayName', { clientCatalog: catalog }),
   })
 }
@@ -155,6 +157,76 @@ test('S17d 后台状态中性:不断言运行中,点为中性图标(渲染守卫
   assert.doesNotMatch(source, /case 'background': return en \? 'Background' : '后台运行'/)
 })
 
+test('S18 头部单行:cwd 与客户端徽章强制不换行(渲染守卫)', () => {
+  // BDD:Given 头部行宽受限,When cwd 或客户端名过长,Then 二者均不内部折行(cwd 压缩出省略号,徽章保持完整)
+  assert.match(source, /\.sls-tv__cwd \{[^}]*white-space:nowrap/)
+  assert.match(source, /\.sls-tv__cwd \{[^}]*overflow:hidden/)
+  assert.match(source, /\.sls-tv__cwd \{[^}]*text-overflow:ellipsis/)
+  assert.match(source, /\.sls-tv__badge \{[^}]*white-space:nowrap/)
+  assert.match(source, /\.sls-tv__pill \{[^}]*white-space:nowrap/)
+  assert.match(source, /\.sls-tv__duration \{[^}]*white-space:nowrap/)
+  assert.match(source, /\.sls-tv__pulse \{[^}]*white-space:nowrap/)
+})
+
+test('S19 行首无展开箭头:官方组件无展开箭头,可展开性由指针与整行点击承载(渲染守卫)', () => {
+  // BDD:Given 官方 ToolRow 无展开箭头,When 行渲染,Then 不存在 chevron 节点及其样式与状态钩子
+  assert.doesNotMatch(source, /sls-tv__chev/)
+  assert.doesNotMatch(source, /IconChevron/)
+  assert.doesNotMatch(source, /data-open/)
+})
+
+test('S20 徽章执行事实:结果标记优先于查看时配置读数', () => {
+  // BDD:Given 缺省客户端调用时 default 为 pwsh,查看时配置 default 已改 git-bash,When 派生卡片模型,Then 徽章显示标记承载的 pwsh,输出不含标记行
+  const model = cardModel({ default: 'git-bash', byId: { 'git-bash': 'git-bash' } })(
+    settledBlock(ARGS, 'out\n[shell: pwsh]\n[exit code: 0]'), SESSION_CWD)
+  assert.equal(model.kind, 'terminal')
+  assert.equal(model.shellName, 'pwsh')
+  assert.equal(model.output, 'out')
+})
+
+test('S20b 徽章执行事实:标记在场不依赖配置面,catalog 缺失仍显示', () => {
+  // BDD:Given 配置读取失败(catalog null),When 块带执行事实标记,Then 徽章仍按标记显示(执行事实不依赖查看时读数)
+  const model = cardModel(null)(
+    settledBlock(ARGS, 'out\n[shell: git-bash]\n[exit code: 2]'), SESSION_CWD)
+  assert.equal(model.shellName, 'git-bash')
+  assert.equal(model.exitCode, 2)
+})
+
+test('S20c 旧块无标记:回退显式参数 → 查看时 default(S15 链不回归)', () => {
+  // BDD:Given 历史块无标记时代产物,When 派生模型,Then 沿用显式参数/查看时 default 推导
+  const catalog = { default: 'git-bash', byId: { 'git-bash': 'git-bash', pwsh: 'pwsh' } }
+  const fallback = cardModel(catalog)(settledBlock(ARGS, 'out\n[exit code: 0]'), SESSION_CWD)
+  assert.equal(fallback.shellName, 'git-bash')
+  const explicit = cardModel(catalog)(
+    settledBlock(JSON.stringify({ command: 'ls', description: 'list', shell: 'pwsh' }), 'out\n[exit code: 0]'), SESSION_CWD)
+  assert.equal(explicit.shellName, 'pwsh')
+})
+
+test('S20d 后台 ack:标记入徽章,输出剥离标记行', () => {
+  // BDD:Given 后台调用 ack 携带执行事实标记,When 派生模型,Then shellName 按标记,输出仅剩 ack 原文
+  const model = cardModel({ default: 'git-bash', byId: {} })(settledBlock(
+    JSON.stringify({ command: 'node server.js', description: 'Boot server', run_in_background: true }),
+    'started background job shell-11\n[shell: pwsh]'), SESSION_CWD)
+  assert.equal(model.kind, 'background')
+  assert.equal(model.jobId, 'shell-11')
+  assert.equal(model.shellName, 'pwsh')
+  assert.equal(model.output, 'started background job shell-11')
+})
+
+test('S20e generic 输出剥离标记行(isError 路径)', () => {
+  // BDD:Given isError 块文本含标记,When 回退 generic,Then 输出不含标记行
+  const model = cardModel(null)(settledBlock(ARGS, 'boom\n[shell: pwsh]', { isError: true }), SESSION_CWD)
+  assert.equal(model.kind, 'generic')
+  assert.equal(model.output, 'boom')
+})
+
+test('S20f 运行中块:无结果文本,徽章按显式参数/查看时 default 推导(现状)', () => {
+  // BDD:Given 调用进行中无结果,When 派生模型,Then 徽章沿用配置读数(执行事实落定后由标记校正)
+  const catalog = { default: 'git-bash', byId: { 'git-bash': 'git-bash' } }
+  const model = cardModel(catalog)(runningBlock(ARGS), SESSION_CWD)
+  assert.equal(model.shellName, 'git-bash')
+})
+
 test('S12c isError 与空结果仍走 generic(回归)', () => {
   const errored = cardModel()(settledBlock(ARGS, 'boom', { isError: true }), SESSION_CWD)
   assert.equal(errored.kind, 'generic')
@@ -167,6 +239,91 @@ test('S13 注册面:shell/pwsh/bash 三 key 且 priority -1(文本守卫)', () =
   assert.match(source, /key: toolKey, priority: -1/)
 })
 
+// ── S21 六态徽章矩阵:前台/后台 × shell(git-bash/pwsh) × pwsh 官方 ──
+// 背景:官方 pwsh 工具调用被增强卡接管,但其输出无 [shell: ...] 标记、参数无
+// shell 字段,徽章兜底落查看时默认客户端读数 → 官方 pwsh 调用误标 git-bash。
+
+const BG_ARGS = JSON.stringify({ command: 'node server.js', description: 'Boot server', run_in_background: true })
+
+test('S21a shell 前台 git-bash:执行事实标记入徽章', () => {
+  // BDD:Given shell 工具经 git-bash 客户端前台执行,When 派生卡片模型,Then 徽章显示标记承载的 git-bash
+  const model = cardModel(null)(settledBlock(ARGS, 'out\n[shell: git-bash]\n[exit code: 0]'), SESSION_CWD, 'shell')
+  assert.equal(model.kind, 'terminal')
+  assert.equal(model.shellName, 'git-bash')
+})
+
+test('S21b shell 前台 pwsh:执行事实标记入徽章', () => {
+  // BDD:Given shell 工具经 pwsh 客户端前台执行失败,When 派生卡片模型,Then 徽章 pwsh 且退出码保留
+  const model = cardModel(null)(settledBlock(ARGS, 'out\n[shell: pwsh]\n[exit code: 2]'), SESSION_CWD, 'shell')
+  assert.equal(model.shellName, 'pwsh')
+  assert.equal(model.exitCode, 2)
+})
+
+test('S21c shell 后台 git-bash:ack 标记入徽章,jobId 解析', () => {
+  // BDD:Given shell 工具后台启动于 git-bash,When 派生 ack 卡,Then 徽章 git-bash 且 jobId 取自 ack
+  const model = cardModel(null)(settledBlock(BG_ARGS, 'started background job shell-4\n[shell: git-bash]'), SESSION_CWD, 'shell')
+  assert.equal(model.kind, 'background')
+  assert.equal(model.jobId, 'shell-4')
+  assert.equal(model.shellName, 'git-bash')
+})
+
+test('S21d shell 后台 pwsh:ack 标记入徽章', () => {
+  // BDD:Given shell 工具后台启动于 pwsh,When 派生 ack 卡,Then 徽章 pwsh
+  const model = cardModel(null)(settledBlock(BG_ARGS, 'started background job shell-5\n[shell: pwsh]'), SESSION_CWD, 'shell')
+  assert.equal(model.kind, 'background')
+  assert.equal(model.jobId, 'shell-5')
+  assert.equal(model.shellName, 'pwsh')
+})
+
+test('S21e pwsh 官方前台:徽章钉死 pwsh,不落默认客户端读数', () => {
+  // BDD:Given 官方 pwsh 工具调用(无标记无 shell 参数)且查看时默认客户端为 git-bash,
+  // When 派生卡片模型,Then 徽章 pwsh(工具名即执行事实,读数兜底只属 shell 工具历史块)
+  const model = cardModel({ default: 'git-bash', byId: { 'git-bash': 'git-bash' } })(
+    settledBlock(ARGS, 'On branch main\n[exit code: 0]'), SESSION_CWD, 'pwsh')
+  assert.equal(model.kind, 'terminal')
+  assert.equal(model.shellName, 'pwsh')
+})
+
+test('S21f pwsh 官方后台:徽章钉死 pwsh,官方 pwsh 前缀 jobId 解析', () => {
+  // BDD:Given 官方 pwsh 工具后台启动(kind pwsh → 任务号 pwsh-N),When 派生 ack 卡,Then 徽章 pwsh 且 jobId=pwsh-3
+  const model = cardModel({ default: 'git-bash', byId: { 'git-bash': 'git-bash' } })(
+    settledBlock(BG_ARGS, 'started background job pwsh-3'), SESSION_CWD, 'pwsh')
+  assert.equal(model.kind, 'background')
+  assert.equal(model.jobId, 'pwsh-3')
+  assert.equal(model.shellName, 'pwsh')
+})
+
+test('S21g pwsh 官方运行中:徽章钉死 pwsh(落定前不误标)', () => {
+  // BDD:Given 官方 pwsh 调用进行中无结果文本,When 派生 running 卡,Then 徽章 pwsh 而非默认客户端读数
+  const model = cardModel({ default: 'git-bash', byId: { 'git-bash': 'git-bash' } })(runningBlock(ARGS), SESSION_CWD, 'pwsh')
+  assert.equal(model.status, 'running')
+  assert.equal(model.shellName, 'pwsh')
+})
+
+test('S21h bash 官方 key 同规钉死(同类预防)', () => {
+  // BDD:Given 官方 bash 工具调用且默认客户端读数为 git-bash,When 派生卡片模型,Then 徽章 bash
+  const model = cardModel({ default: 'git-bash', byId: { 'git-bash': 'git-bash' } })(
+    settledBlock(ARGS, 'out\n[exit code: 0]'), SESSION_CWD, 'bash')
+  assert.equal(model.shellName, 'bash')
+})
+
+test('S21i toolKey 贯通:注册循环注入 + 行组件传入模型(渲染守卫)', () => {
+  // BDD:Given 卡片按 key 注册,When 渲染,Then key 以 toolKey 注入组件并传入模型派生(漏任何一环徽章退回读数兜底)
+  assert.match(source, /React\.createElement\(ShellToolRow, \{ \.\.\.props, toolKey \}\)/)
+  assert.match(source, /shellCardModel\(block, cwd, toolKey\)/)
+})
+
+test('S21j 钉死键集与注册键集同源:PINNED_CLIENT 恒等于 TOOLVIEW_KEYS 去 shell(渲染守卫)', () => {
+  // BDD:Given 官方钉死客户端事实在 client.js 双处字面编码(TOOLVIEW_KEYS 与 PINNED_CLIENT),
+  // When 派生两处键集,Then 钉死键集恒等于注册键集去掉 shell——注册面新增官方工具 key 而
+  // 漏配钉死映射时此处红,误标 bug 不静默复发
+  const toolviewKeys = /const TOOLVIEW_KEYS = \[([^\]]*)\]/.exec(source)[1]
+    .split(',').map((item) => item.trim().replace(/^'|'$/g, '')).filter((key) => key !== '' && key !== 'shell')
+  const pinnedKeys = /const PINNED_CLIENT = \{([^}]*)\}/.exec(source)[1]
+    .split(',').map((pair) => pair.trim().split(':')[0].trim().replace(/^'|'$/g, '')).filter((key) => key !== '')
+  assert.deepEqual(pinnedKeys.sort(), toolviewKeys.sort())
+})
+
 test('K=V 往返:值含 = 与空格无损,空行忽略,重复键后行胜', () => {
   const parse = parseEnvText()
   assert.deepEqual(parse('A=1\nB=x=y z\n\nA=2'), { A: '2', B: 'x=y z' })

package/test/client-render.test.mjs

@@ -119,7 +119,6 @@ test('图标名守卫:0.1.7 primitives 字重后缀名在场,尺寸后缀旧名
   // 0.1.7 图标改名:尺寸从名字移除(IconApiOutline14 → IconApiOutlineRegular/Medium),
   // 旧名 miss 使 IconApi 落淡灰 fallback 被当成"空白 icon"(实测事故)
   assert.match(source, /'IconApiOutlineRegular'/)
-  assert.match(source, /'IconChevronDownOutlineRegular'/)
   assert.match(source, /'IconInspectOutlineRegular'/)
   assert.doesNotMatch(source, /createElementOf\('IconApiOutline14'/)
 })

package/test/config.test.mjs

@@ -3,7 +3,8 @@
 
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
-import { resolveConfig, defaultConfig, entryById, requireEntry, buildArgv, KINDS, RESOLVED_AUTO } from '../src/config.mjs'
+import { resolveConfig, resolveConfigStrict, coerceServiceable, defaultConfig, entryById, requireEntry, buildArgv, KINDS, RESOLVED_AUTO } from '../src/config.mjs'
+import { assertServiceableConfig } from '../src/config.mjs'
 
 test('schema 应用出厂默认:三客户端 + 默认 pwsh', () => {
   const applied = resolveConfig({})
@@ -38,6 +39,13 @@ test('落盘坏形态防御:volatile 字段被序列化成对象时降级默认,
   const valid = resolveConfig({ shells: [{ id: 'pwsh', kind: 'pwsh' }], default: 'pwsh', deny: ['rm -rf'], cwd: 'C:\\tmp', timeoutMs: 5000 })
   assert.equal(valid.shells.length, 1)
   assert.equal(valid.default, 'pwsh')
+
+  // 执行面 strict:同款坏形态必须炸(宿主 resolve 产物须先解箱;静默降级
+  // 曾让行 config 永不生效,0.2.0-rc.2 真机实证)。宽容路径(上方)保留。
+  assert.throws(() => resolveConfigStrict(poisoned), /形态非法.*shells/)
+  // 合法输入与 undefined 缺省:strict 与宽容同产出
+  assert.deepEqual(resolveConfigStrict(valid), valid)
+  assert.deepEqual(resolveConfigStrict(undefined), defaultConfig())
   assert.deepEqual(valid.deny, ['rm -rf'])
   assert.equal(valid.cwd, 'C:\\tmp')
   assert.equal(valid.timeoutMs, 5000)
@@ -47,8 +55,38 @@ test('落盘坏形态防御:volatile 字段被序列化成对象时降级默认,
   }
 })
 
-test('冻结输入防御:volatile ref 深冻结快照喂入不改写不抛(挂载路径)', () => {
-  // 事故:cosmokit createVolatile 的 snapshot 对 volatile 值逐层 Object.freeze,
+// --- coerceServiceable:任意用户输入产出可服务配置(插件不因配置死) ---
+
+test('coerce:悬空 default 归 shells[0],空/全非法 shells 回落出厂默认', () => {
+  const { config, warnings } = coerceServiceable({ shells: [{ id: 'pwsh', kind: 'pwsh' }], default: 'nope' })
+  assert.equal(config.default, 'pwsh')
+  assert.ok(warnings.some((line) => line.includes('default')))
+  const emptied = coerceServiceable({ shells: [{ id: 'x', kind: 'fish' }], default: 'x' })
+  assert.deepEqual(emptied.config.shells.map((entry) => entry.id), ['pwsh', 'git-bash', 'cmd'])
+  assert.equal(emptied.config.default, 'pwsh')
+  assert.ok(emptied.warnings.length >= 2)
+})
+
+test('coerce:预算字段非正数降默认,deny 剔除不可编译条目,合法输入零告警原样', () => {
+  const { config, warnings } = coerceServiceable({
+    shells: [{ id: 'pwsh', kind: 'pwsh' }],
+    default: 'pwsh',
+    timeoutMs: -5,
+    graceMs: Number.MAX_SAFE_INTEGER,
+    deny: ['rm -rf', '(unclosed', '', 42],
+  })
+  assert.equal(config.timeoutMs, undefined)
+  assert.equal(config.graceMs, undefined)
+  assert.deepEqual(config.deny, ['rm -rf'])
+  assert.equal(warnings.length, 3)
+  const clean = coerceServiceable({ shells: [{ id: 'pwsh', kind: 'pwsh' }], default: 'pwsh' })
+  assert.equal(clean.warnings.length, 0)
+  // 产物必过可服务校验:任意输入不产出会炸挂载的配置
+  assertServiceableConfig(resolveConfig(clean.config))
+  assertServiceableConfig(resolveConfig(config))
+})
+
+test('冻结输入防御:volatile ref 深冻结快照喂入不改写不抛(挂载路径)', () => {  // 事故:cosmokit createVolatile 的 snapshot 对 volatile 值逐层 Object.freeze,
   // 行 Config ref .get() 产物是深冻结对象;sanitizeConfigEntry 引用透传,
   // schemastery resolve 原地改写入参(填默认)撞冻结 env 抛
   // "Cannot assign to read only property 'MSYSTEM'" → 执行器挂载失败,

package/test/executor.test.mjs

@@ -4,7 +4,7 @@
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
 import ShellSelectExecutor from '../src/executor.mjs'
-import { resolveConfig, assertServiceableConfig } from '../src/config.mjs'
+import { resolveConfig, assertServiceableConfig, defaultConfig } from '../src/config.mjs'
 
 // --- 桩具 ---
 
@@ -125,7 +125,8 @@ test('构造:注册 shell+pwsh 双工具与 systemPrompt 段,路由不再由主
   const shell = registered.tools.find((tool) => tool.name === 'shell')
   const pwsh = registered.tools.find((tool) => tool.name === 'pwsh')
   assert.match(shell.description, /git-bash/)
-  assert.match(pwsh.description, /PowerShell/)
+  // 兼容工具描述一句话:不要调用,使用 shell
+  assert.equal(pwsh.description, 'Do not call; use `shell`.')
   assert.ok(!('shell' in pwsh.parameters.properties))
   assert.ok('shell' in shell.parameters.properties)
   assert.equal(registered.promptSections.length, 1)
@@ -407,3 +408,84 @@ test('refresh:换源后执行面即时收紧(已删 id 拒绝,新清单生效)',
   assert.equal(executor.entryFor(undefined).id, 'pwsh')
   assert.equal(registered.tools.length, toolsBefore)
 })
+
+// 真机宿主形态:行 config 经宿主按 static Config resolve,volatile 字段是
+// boxed ref({get}),非普通对象。构造/refresh 直存该形态时 resolveConfig 的
+// 类型对账会把 ref 全部当非法输入丢弃,执行面静默回落出厂默认(行 config
+// 永不生效,真机 0.2.0-rc.2 实证)。回归锁定:boxed 形态必须解箱生效。
+
+// cordis resolve 产物的同构 boxed 形态:每字段值包 {get}
+function boxFields(config) {
+  return Object.fromEntries(Object.entries(config).map(([key, value]) => [key, { get: () => value }]))
+}
+
+test('构造:boxed volatile 字段(宿主 resolve 产物)解箱生效,不回落出厂默认', () => {
+  const { ctx, registered } = stubCtx()
+  const userConfig = {
+    shells: baseConfig().shells.filter((entry) => entry.id !== 'cmd'),
+    default: 'git-bash',
+  }
+  const executor = new ShellSelectExecutor(ctx, boxFields(userConfig))
+  const listing = executor.listShells()
+  assert.equal(listing.default, 'git-bash')
+  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\)/)
+})
+
+test('refresh:boxed volatile 字段换源同样解箱生效', () => {
+  const { ctx } = stubCtx()
+  const executor = new ShellSelectExecutor(ctx, baseConfig())
+  executor.refresh(boxFields({
+    shells: baseConfig().shells,
+    default: 'git-bash',
+  }))
+  assert.equal(executor.entryFor(undefined).id, 'git-bash')
+  const listing = executor.listShells()
+  assert.equal(listing.default, 'git-bash')
+  assert.equal(listing.shells.length, 3)
+})
+
+test('构造:混合形态(部分字段 boxed 部分普通)逐字段解箱生效', () => {
+  const { ctx } = stubCtx()
+  const executor = new ShellSelectExecutor(ctx, {
+    shells: boxFields({ shells: baseConfig().shells }).shells,
+    default: 'git-bash',
+    timeoutMs: 30000,
+  })
+  assert.equal(executor.entryFor(undefined).id, 'git-bash')
+  assert.equal(executor.config.timeoutMs, 30000)
+})
+
+test('入参缺省:null/undefined 落出厂默认,不抛', () => {
+  const { ctx } = stubCtx()
+  // 出厂默认 path=RESOLVED_AUTO('') → entryFor 走真实磁盘探测,linux CI 无
+  // pwsh.exe 必抛 no executable(出厂清单其余条目同);node 自身全平台存在,
+  // 以显式 path 覆写探测面,断言目标(id 落定与缺省容错)不受影响。
+  // refresh(null) 会把 #entry 归零回出厂(auto 路径),其后 entryFor 同样
+  // 需要探测面覆写:refresh 收 bypass 配置,null/undefined 容错语义(归零
+  // 不抛)由 refresh 调用本身不抛保证
+  const autoBypass = (entryConfig) => ({
+    ...entryConfig,
+    shells: entryConfig.shells.map((item) => ({ ...item, path: NODE_EXE })),
+  })
+  const fromNull = new ShellSelectExecutor(ctx, autoBypass(defaultConfig()))
+  assert.equal(fromNull.entryFor(undefined).id, 'pwsh')
+  fromNull.refresh(autoBypass(defaultConfig()))
+  assert.equal(fromNull.entryFor(undefined).id, 'pwsh')
+  const fromUndefined = new ShellSelectExecutor(ctx, autoBypass(defaultConfig()))
+  assert.equal(fromUndefined.entryFor(undefined).id, 'pwsh')
+})
+
+test('fail-loud:解箱后仍非法的形态炸在挂载点,不静默回落出厂默认', () => {
+  const { ctx } = stubCtx()
+  // ref 容器但解箱值非法(模拟宿主 resolve 形态契约变化):strict 必须抛
+  assert.throws(
+    () => new ShellSelectExecutor(ctx, { shells: { get: () => 'not-array' }, default: 'pwsh' }),
+    /形态非法.*shells/,
+  )
+  // 同形态宽容路径(resolveConfig)不抛——降级语义仅保留给持久化读回
+  assert.doesNotThrow(() => new ShellSelectExecutor(ctx, baseConfig()))
+})

package/test/render.test.mjs

@@ -16,6 +16,45 @@ test('干净退出:仅 stdout,无标记', () => {
   assert.equal(text, 'hello\n')
 })
 
+test('S20h shell 客户端标记:首标记行落,官方退出锚保持末行', () => {
+  // BDD:Given 调用经 git-bash 客户端执行且非零退出,When 渲染模型可见文本,Then 首行标记 [shell: git-bash],[exit code] 仍居末(官方 parseExitStatus 锚不被破坏)
+  const text = renderResult({
+    stdout: { text: 'out\n', truncated: false },
+    stderr: { text: '', truncated: false },
+    exitCode: 2, signal: null, timedOut: false, sandbox: undefined,
+  }, NO_ESCALATION, 'git-bash')
+  assert.equal(text, 'out\n[shell: git-bash]\n[exit code: 2]')
+})
+
+test('S20h shell 标记:干净成功仅标记行,退出锚缺省形态不变', () => {
+  // BDD:Given exit 0 成功调用,When 渲染,Then 输出尾追 [shell: id] 单行,无退出标记
+  const text = renderResult({
+    stdout: { text: 'hello\n', truncated: false },
+    stderr: { text: '', truncated: false },
+    exitCode: 0, signal: null, timedOut: false, sandbox: undefined,
+  }, NO_ESCALATION, 'pwsh')
+  assert.equal(text, 'hello\n[shell: pwsh]')
+})
+
+test('S20h shell 标记:先于超时/信号标记,退出锚仍居末', () => {
+  const text = renderResult({
+    stdout: { text: '', truncated: false },
+    stderr: { text: '', truncated: false },
+    exitCode: null, signal: 'SIGTERM', timedOut: true, timeoutMs: 1000, sandbox: undefined,
+  }, NO_ESCALATION, 'pwsh')
+  assert.equal(text, '(no output)\n[shell: pwsh]\n[timed out after 1000ms]\n[killed by signal: SIGTERM]')
+})
+
+test('S20h shell 标记:未传 id 不加标记(渲染面与官方逐字同构)', () => {
+  // BDD:Given 调用方未携带客户端事实,When 渲染,Then 文本与官方 pwsh 工具逐字一致
+  const text = renderResult({
+    stdout: { text: 'hello\n', truncated: false },
+    stderr: { text: '', truncated: false },
+    exitCode: 0, signal: null, timedOut: false, sandbox: undefined,
+  }, NO_ESCALATION)
+  assert.equal(text, 'hello\n')
+})
+
 test('stderr 段 + 非零退出标记次序', () => {
   const text = renderResult({
     stdout: { text: 'out\n', truncated: false },