@mzzsfy/dsh-shell-select 0.3.0 → 0.4.0

package/src/client.js

@@ -8,7 +8,8 @@ window.__ModuleLoader__.load({
     const React = require('react')
     const { useState, useEffect } = React
 
-    // 官方 primitives 图标/状态点(运行时模块表解析;dsh.client.inject 声明保证在场)
+    // 官方 primitives 图标/状态点(运行时模块表解析;dsh.client.inject 声明保证在场)。
+    // 0.1.7 起图标名带字重后缀(Regular/Medium),尺寸是 prop 不在名字里
     const primitives = (() => {
       try {
         return require('@deepseek-ai/dsh-client-ui-primitives')
@@ -16,31 +17,34 @@ window.__ModuleLoader__.load({
         return null
       }
     })()
-    const createElementOf = (name, fallback) => {
-      const Component = primitives !== null ? primitives[name] : undefined
-      return typeof Component === 'function' || typeof Component === 'object'
-        ? (props) => React.createElement(Component, props ?? null)
-        : fallback
+    const createElementOf = (names, fallback) => {
+      for (const name of names) {
+        const Component = primitives !== null ? primitives[name] : undefined
+        if (typeof Component === 'function' || typeof Component === 'object') {
+          return (props) => React.createElement(Component, props ?? null)
+        }
+      }
+      return fallback
     }
     const DOT_SVG = { done: '#2e9e5b', error: '#d4553f', warning: '#d9a13b', ongoing: '#7a7f8a' }
     // 降级自绘:模块表缺 primitives 时保持可见性(形态近似官方 StateDot/图标)
     const TOOLVIEW_ICONS = {
-      StateDot: createElementOf('StateDot', ({ state }) => h('span', {
+      StateDot: createElementOf(['StateDot'], ({ state }) => h('span', {
         style: {
           width: 8, height: 8, borderRadius: '50%', background: DOT_SVG[state] ?? DOT_SVG.ongoing,
           display: 'inline-block', flex: 'none',
         },
       })),
-      IconApi: createElementOf('IconApiOutline14', () => h('span', {
+      IconApi: createElementOf(['IconApiOutlineRegular', 'IconApiOutlineMedium', 'IconApiOutline14'], () => h('span', {
         style: {
           width: 12, height: 12, borderRadius: 3, border: '1.5px solid currentColor',
           opacity: .7, display: 'inline-block', flex: 'none',
         },
       })),
-      IconChevron: createElementOf('IconChevronDownOutline14', ({ size }) => h('span', {
+      IconChevron: createElementOf(['IconChevronDownOutlineRegular', 'IconChevronDownOutlineMedium', 'IconChevronDownOutline14'], ({ size }) => h('span', {
         style: { fontSize: (size ?? 14) - 3, lineHeight: 1, userSelect: 'none' },
       }, '▾')),
-      IconInspect: createElementOf('IconInspectOutline12', () => h('span', {
+      IconInspect: createElementOf(['IconInspectOutlineRegular', 'IconInspectOutlineMedium', 'IconInspectOutline12'], () => h('span', {
         style: { fontSize: 10, lineHeight: 1, opacity: .8 },
       }, 'ⓘ')),
     }
@@ -66,7 +70,7 @@ window.__ModuleLoader__.load({
     }
 
     // 工具卡客户端名册缓存:GET /config 单飞拉取,shell 徽章按 id→用户命名解析。
-    // 失败置 null(徽章不渲染),不重试——下次页面加载自然重取
+    // 失败复位单飞(宿主启动窗口路由未就绪的 404 在下次卡渲染自然重试)
     let clientCatalog = null
     let clientCatalogPromise = null
     // LOGIC-BEGIN ensureClientCatalog
@@ -74,9 +78,11 @@ window.__ModuleLoader__.load({
       if (clientCatalogPromise === null) {
         clientCatalogPromise = api(API.config).then((section) => {
           const byId = {}
-          for (const entry of section.resolved?.shells ?? []) byId[entry.id] = entry.name
+          for (const entry of section.resolved?.shells ?? []) byId[entry.id] = entry.id
           clientCatalog = { default: section.resolved?.default, byId }
-        }).catch(() => { })
+        }).catch(() => {
+          clientCatalogPromise = null
+        })
       }
       return clientCatalogPromise
     }
@@ -128,7 +134,16 @@ 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); }',
-      '.sls-tv__chev { opacity:.45; transition:transform .15s ease; }',
+      // 官方 DisclosureRow 同构:icon 与 chevron 同 16px 槽,hover 交叉淡化;
+      // 错误/进行中状态点绝对定位覆盖 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__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; }',
@@ -141,6 +156,10 @@ window.__ModuleLoader__.load({
       '.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; }',
       '.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__pulse { font-size:12px; color:var(--dsw-alias-label-tertiary, inherit); flex:none; 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; }',
       '.sls-tv__copyBtn { padding:2px 8px; border:1px solid rgba(128,128,128,.35); border-radius:6px; background:transparent; color:inherit; cursor:pointer; font-size:12px; }',
@@ -186,7 +205,6 @@ window.__ModuleLoader__.load({
       return {
         shells: entries.map((entry) => ({
           id: entry.id.trim(),
-          name: entry.name.trim(),
           kind: entry.kind,
           path: entry.path.trim(),
           args: entry.argsText.split(/\s+/).filter((item) => item.length > 0),
@@ -243,7 +261,6 @@ window.__ModuleLoader__.load({
     function toEntries(section) {
       return section.shells.map((entry) => ({
         id: entry.id,
-        name: entry.name,
         kind: entry.kind,
         path: entry.path,
         argsText: (entry.args ?? []).join(' '),
@@ -290,7 +307,7 @@ window.__ModuleLoader__.load({
 
       const addEntry = () => {
         setDirty(true)
-        setEntries([...entries, { id: '', name: '', kind: 'bash', path: '', argsText: '', login: false, distro: '', envText: '', available: undefined, resolved: undefined }])
+        setEntries([...entries, { id: '', kind: 'bash', path: '', argsText: '', login: false, distro: '', envText: '', available: undefined, resolved: undefined }])
       }
 
       const removeEntry = (index) => {
@@ -422,16 +439,9 @@ window.__ModuleLoader__.load({
             h('input', {
               className: 'sls-input',
               value: entry.id,
-              placeholder: 'pwsh / git-bash / …(模型看到的 shell 参数值)',
+              placeholder: 'pwsh / git-bash / …(模型看到的 shell 参数值,亦作显示名)',
               onChange: (event) => patchEntry(index, { id: event.target.value }),
             }),
-            h('span', { className: 'sls-grid__label' }, '名称'),
-            h('input', {
-              className: 'sls-input',
-              value: entry.name,
-              placeholder: '显示名,如 Git Bash',
-              onChange: (event) => patchEntry(index, { name: event.target.value }),
-            }),
             h('span', { className: 'sls-grid__label' }, '形态'),
             h('div', { className: 'sls-row' },
               h('select', {
@@ -624,12 +634,12 @@ window.__ModuleLoader__.load({
       const cwdDir = cwdFull !== undefined ? lastSegment(cwdFull) : undefined
       // shell 名 = 用户在配置页起的条目名;args.shell 缺省时按 default 客户端解析(配置当前读数)
       const shellName = clientDisplayName(typeof args?.shell === 'string' ? args.shell : undefined)
-      if (command === '') return { kind: 'generic', command: '', summary: undefined, output: null }
+      if (command === '') return { kind: 'generic', command: '', summary: undefined, output: null, running: !settled, alert: undefined }
 
       if (!settled) {
-        // running persistent(进行中无描述):回退行但状态点用进行中灰,非 warning 黄
-        if (description === undefined) return { kind: 'generic', command, summary: undefined, output: null, running: true }
-        return { kind: 'terminal', status: 'running', command, description, cwdDir, cwdFull, shellName, output: undefined, exitCode: undefined, signal: undefined, code: undefined }
+        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 }
       }
 
       const contentText = (block.content ?? []).map((part) => (part.type === 'text' ? part.text : '')).filter((text) => text !== '').join('\n')
@@ -638,9 +648,11 @@ window.__ModuleLoader__.load({
         const jobId = /started background job (\S+)/.exec(contentText)?.[1]
         return { kind: 'background', status: 'background', command, description, cwdDir, cwdFull, shellName, output: contentText, jobId }
       }
-      // 空结果落 generic:官方 singleResultText 无文本即回通用卡,避免空输出伪 done 终端卡
+      // 空结果落 generic:官方 singleResultText 无文本即回通用卡,避免空输出伪 done 终端卡;
+      // isError/error 块带 alert(错误红点语义),其余(空输出/无描述/截断)中性无状态点
       if (contentText === '' || block.isError === true || block.error !== undefined || description === undefined || hasSpillNotice(contentText)) {
-        return { kind: 'generic', command, summary: description, output: contentText }
+        const alert = block.isError === true || block.error !== undefined ? 'error' : undefined
+        return { kind: 'generic', command, summary: description, output: contentText, running: false, alert }
       }
       const tail = parseExitTail(contentText)
       const status = tail.signal !== undefined ? 'signaled' : tail.exitCode !== 0 ? 'failed' : 'done'
@@ -648,18 +660,49 @@ window.__ModuleLoader__.load({
     }
     // LOGIC-END shellCardModel
 
-    // 官方 leadingFor 同构:失败红点,回退行黄点,进行中灰点,其余工具图标
-    function leadingOf(status, icons) {
-      if (status === 'failed' || status === 'signaled') return icons.StateDot({ state: 'error' })
-      if (status === 'generic-warn') return icons.StateDot({ state: 'warning' })
-      if (status === 'running') return icons.StateDot({ state: 'ongoing' })
+    // 官方 DisclosureRow leading 同构:16px 槽内 icon 与 chevron 同位,
+    // 收起时 chevron hover 才现(交叉淡化),展开时仅 chevron-up;错误态
+    // 红点叠 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
+      if (dot !== null) {
+        return h('span', { className: 'sls-tv__leadStack' },
+          h('span', { className: 'sls-tv__iconIdle' }, icons.IconApi({ size: 14 })),
+          h('span', { className: 'sls-tv__stateCover' }, dot),
+        )
+      }
       return icons.IconApi({ size: 14 })
     }
 
+    // 时长格式:秒 → m:ss;超一小时 → h:mm:ss
+    // LOGIC-BEGIN formatDuration
+    function formatDuration(elapsedMs) {
+      const totalSeconds = Math.max(0, Math.floor(elapsedMs / 1000))
+      const seconds = totalSeconds % 60
+      const minutes = Math.floor(totalSeconds / 60) % 60
+      const hours = Math.floor(totalSeconds / 3600)
+      const two = (value) => (value < 10 ? '0' + value : String(value))
+      return hours > 0 ? `${hours}:${two(minutes)}:${two(seconds)}` : `${minutes}:${two(seconds)}`
+    }
+    // LOGIC-END formatDuration
+
+    // 运行中实时时长:每秒 tick;秒级粒度对"阻塞了多久"足够
+    function RunningDuration({ startedAt, en }) {
+      const [, setTick] = useState(0)
+      useEffect(() => {
+        const timer = setInterval(() => setTick((value) => value + 1), 1000)
+        return () => clearInterval(timer)
+      }, [])
+      const elapsed = startedAt !== undefined ? Date.now() - startedAt : undefined
+      const text = elapsed !== undefined && elapsed >= 0 ? formatDuration(elapsed) : en ? 'running' : '运行中'
+      return h('span', { className: 'sls-tv__duration', title: en ? 'Elapsed' : '已运行' }, text)
+    }
+
     function statusTextOf(status, en) {
       switch (status) {
         case 'running': return en ? 'Running' : '运行中'
-        case 'background': return en ? 'Background' : '后台运行'
+        case 'background': return en ? 'Background' : '后台'
         case 'failed': case 'signaled': return en ? 'Failed' : '失败'
         default: return null
       }
@@ -668,9 +711,10 @@ window.__ModuleLoader__.load({
     function headMetaOf(model, en) {
       switch (model.status) {
         case 'running': return { dot: 'ongoing', label: en ? 'Running' : '运行中', pill: undefined }
+        // ack 块静态不反映 job 生命周期,状态点缺省(后台任务由 bg pill 标识)
         case 'background': return {
-          dot: 'ongoing',
-          label: en ? 'Background' : '后台运行',
+          dot: undefined,
+          label: en ? 'Background' : '后台',
           pill: model.jobId !== undefined ? (en ? `bg ${model.jobId}` : `后台 ${model.jobId}`) : undefined,
           pillTone: 'bg',
         }
@@ -699,13 +743,17 @@ window.__ModuleLoader__.load({
       }, done ? (detectEnglish() ? 'Copied' : '已复制') : label)
     }
 
-    // 非终端意图回退行(后台 ack / isError / 截断):摘要 + 可展开原文
+    // 非终端意图回退行(后台 ack / isError / 截断 / 参数未到):摘要 + 可展开原文。
+    // 状态语义对齐官方:运行中灰 spinner,settled 错误红点,其余中性 icon——
+    // 黄点(warning)仅真实告警,禁止挪用作"进行中"(用户把黄点当卡死)。
+    // 运行中且零信息(参数未到)显示脉冲「运行中…」,给用户活着的感觉。
     function GenericShellRow({ model, inspect, en }) {
       const [open, setOpen] = useState(false)
+      const status = model.running === true ? 'running' : model.alert === 'error' ? 'generic-error' : undefined
       const summary = model.summary !== undefined && model.summary !== ''
         ? model.summary.split('\n')[0]
         : (model.output !== null && model.output !== '' ? model.output.split('\n')[0] : '')
-      const expandable = model.output !== null && model.output !== ''
+      const expandable = (model.output !== null && model.output !== '') || model.command !== ''
       return h('div', { className: 'sls-tv' },
         h('div', {
           className: 'sls-tv__row' + (expandable ? ' sls-tv__row--exp' : ''),
@@ -721,14 +769,15 @@ window.__ModuleLoader__.load({
           } : undefined,
         },
           h('span', { className: 'sls-tv__lead' },
-            leadingOf(model.running === true ? 'running' : 'generic-warn', TOOLVIEW_ICONS),
+            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,
-          summary !== '' ? h('span', { className: 'sls-tv__sum' }, summary) : null,
+          summary !== '' ? h('span', { className: 'sls-tv__sum' + (status === 'generic-error' ? ' sls-tv__sum--err' : '') }, summary) : null,
+          status === 'running' ? h('span', { className: 'sls-tv__pulse' }, en ? 'running…' : '运行中…') : null,
         ),
-        open && expandable ? h('pre', { className: 'sls-tv__out', style: { border: '1px solid rgba(128,128,128,.28)', borderRadius: 8 } }, model.output) : null,
+        open && expandable ? h('pre', { className: 'sls-tv__out', style: { border: '1px solid rgba(128,128,128,.28)', borderRadius: 8 } }, model.command + (model.output !== null && model.output !== '' ? `\n${model.output}` : '')) : null,
         inspect !== undefined ? h('button', { className: 'sls-tv__inspect', onClick: inspect }, TOOLVIEW_ICONS.IconInspect({}), en ? 'Inspect' : '检查') : null,
       )
     }
@@ -748,16 +797,20 @@ window.__ModuleLoader__.load({
       const meta = headMetaOf(model, en)
       const copyCommandLabel = en ? 'Copy command' : '复制命令'
       const copyOutputLabel = en ? 'Copy output' : '复制输出'
+      // 运行中头部 pill = 实时时长(组件,hook 内每秒自刷新)
+      const pill = model.status === 'running'
+        ? h(RunningDuration, { startedAt: model.startedAt, en })
+        : meta.pill
       return h('div', { className: 'sls-tv__body', 'data-status': model.status },
         h('div', { className: 'sls-tv__head' },
           h('span', { style: { display: 'inline-flex', alignItems: 'center', gap: 4 } },
-            TOOLVIEW_ICONS.StateDot({ state: meta.dot }),
+            meta.dot !== undefined ? TOOLVIEW_ICONS.StateDot({ state: meta.dot }) : null,
             h('span', { className: 'sls-tv__sr' }, meta.label),
           ),
           model.cwdDir !== undefined ? h('span', { className: 'sls-tv__cwd', title: 'pwd: ' + (model.cwdFull ?? model.cwdDir) }, model.cwdDir) : null,
           model.shellName !== undefined ? h('span', { className: 'sls-tv__badge', title: en ? 'Shell client' : 'Shell 客户端' }, model.shellName) : null,
           h('span', { className: 'sls-tv__sp' }),
-          meta.pill !== undefined ? h('span', { className: 'sls-tv__pill' + (meta.pillTone === 'bg' ? ' sls-tv__pill--bg' : '') }, meta.pill) : null,
+          pill !== undefined ? h('span', { className: 'sls-tv__pill' + (meta.pillTone === 'bg' ? ' sls-tv__pill--bg' : '') }, pill) : null,
           h('span', { className: 'sls-tv__copy' },
             h(CopyButton, {
               label: copyCommandLabel,
@@ -783,8 +836,10 @@ window.__ModuleLoader__.load({
       const { block, cwd, inspect } = props
       const en = detectEnglish()
       const model = shellCardModel(block, cwd)
-      // 后台 ack 卡默认展开:内容即命令全文,收起只剩一行摘要失去可读性
-      const [open, setOpen] = useState(model.kind === 'background')
+      // hooks 恒序:必须在任何提前 return 之前完整执行(真实 React 的 hooks
+      // 链表按调用序对位,generic 行与 terminal 行的提前 return 分叉会让
+      // 后续 hook 错位,行组件树被整棵卸载——卡片全消失事故根因)
+      const [open, setOpen] = useState(false)
       const [, setCatalogReady] = useState(false)
       useEffect(() => {
         let disposed = false
@@ -812,13 +867,17 @@ window.__ModuleLoader__.load({
           },
         },
           h('span', { className: 'sls-tv__lead' },
-            leadingOf(model.status, TOOLVIEW_ICONS),
+            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'),
           h('span', { className: 'sls-tv__sep', 'aria-hidden': true }),
           h('span', { className: 'sls-tv__sum' + (failed ? ' sls-tv__sum--err' : '') }, summary),
+          model.status === 'running' ? h(RunningDuration, { startedAt: model.startedAt, en }) : null,
+          model.status === 'background' && model.jobId !== undefined
+            ? h('span', { className: 'sls-tv__badge', title: en ? 'Background job' : '后台任务' }, en ? `bg ${model.jobId}` : `后台 ${model.jobId}`)
+            : null,
         ),
         open ? h(ShellCard, { model, inspect, en }) : null,
       )

package/src/config.mjs

@@ -3,6 +3,7 @@
 // cmd /d /s /c 与 wsl --exec 为本包定义的保守形态。
 
 import z from '@deepseek-ai/schemastery'
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 
 // 支持的 shell 形态
 export const KINDS = ['pwsh', 'bash', 'cmd', 'wsl']
@@ -29,7 +30,6 @@ const EXECUTOR_DEFAULTS = {
 
 const shellEntry = z.object({
   id: z.string().required(),
-  name: z.string().required(),
   kind: z.union(KINDS).required(),
   path: z.string().default(RESOLVED_AUTO),
   args: z.array(z.string()).default([]),
@@ -39,27 +39,121 @@ const shellEntry = z.object({
 })
 
 export const Config = z.object({
+  // 0.1.7 设置页写路径(settings.write)只接受 volatile 字段(免重挂载的活
+  // 字段,官方 dsh-bash-local Config 逐字段 volatile 同构);缺声明即
+  // "has no volatile fields" 保存失败
   shells: z.array(shellEntry).default([
-    { id: 'pwsh', name: 'PowerShell', kind: 'pwsh', path: RESOLVED_AUTO, args: [] },
-    { id: 'git-bash', name: 'Git Bash', kind: 'bash', path: RESOLVED_AUTO, args: [] },
-    { id: 'cmd', name: 'CMD', kind: 'cmd', path: RESOLVED_AUTO, args: [] },
-  ]),
-  default: z.string().default('pwsh'),
+    { id: 'pwsh', kind: 'pwsh', path: RESOLVED_AUTO, args: [] },
+    { id: 'git-bash', kind: 'bash', path: RESOLVED_AUTO, args: [] },
+    { id: 'cmd', kind: 'cmd', path: RESOLVED_AUTO, args: [] },
+  ]).volatile(),
+  default: z.string().default('pwsh').volatile(),
   // 命令黑名单(整文本正则,大小写不敏感):命中即拒,deny 绝对无豁免;
   // 精细放行用正则前瞻在模式内表达。空数组 = 不拦截。
   // 护栏防误触,非安全边界(真边界是沙箱与访问模式)
-  deny: z.array(z.string()).default([]),
-  cwd: z.string(),
-  timeoutMs: z.number().default(EXECUTOR_DEFAULTS.timeoutMs),
-  maxTimeoutMs: z.number().default(EXECUTOR_DEFAULTS.maxTimeoutMs),
-  maxOutputBytes: z.number().default(EXECUTOR_DEFAULTS.maxOutputBytes),
-  maxSpillBytes: z.number().default(EXECUTOR_DEFAULTS.maxSpillBytes),
-  graceMs: z.number().default(EXECUTOR_DEFAULTS.graceMs),
+  deny: z.array(z.string()).default([]).volatile(),
+  cwd: z.string().volatile(),
+  timeoutMs: z.number().default(EXECUTOR_DEFAULTS.timeoutMs).volatile(),
+  maxTimeoutMs: z.number().default(EXECUTOR_DEFAULTS.maxTimeoutMs).volatile(),
+  maxOutputBytes: z.number().default(EXECUTOR_DEFAULTS.maxOutputBytes).volatile(),
+  maxSpillBytes: z.number().default(EXECUTOR_DEFAULTS.maxSpillBytes).volatile(),
+  graceMs: z.number().default(EXECUTOR_DEFAULTS.graceMs).volatile(),
 })
 
+// volatile 字段解箱:schema 声明 .volatile() 后(0.1.7 设置页写路径只接受
+// volatile 字段,缺声明即 "has no volatile fields" 拒写),Config 产物字段为
+// boxed ref(读值须 .get(),官方 dsh-bash-local 同构)。统一在此解箱,消费者
+// (executor/web-routes/测试)一律拿普通对象。
+// structuredClone 深拷贝双向:输入侧(sanitize 产物)切断与调用方对象的耦合——
+// volatile ref .get() 产物是 cosmokit snapshot 深冻结对象,schemastery resolve
+// 原地改写入参,冻结 env 直接炸挂载;输出侧:schemastery resolve 会原地改写入参
+// (填默认/键归一)并把产出对象置为不可扩展,二轮 resolve(快照回灌,web 写路径
+// current+patch 合并常态)对不可扩展对象赋值即炸;clone 切断产物与 schema 的原地
+// 耦合,保证 resolveConfig 幂等且对输入不可变。
+export function unwrapConfig(value) {
+  return Object.fromEntries(Object.entries(value).map(([key, field]) => {
+    const raw = typeof field?.get === 'function' ? field.get() : field
+    return [key, raw !== null && typeof raw === 'object' ? structuredClone(raw) : raw]
+  }))
+}
+
+/** schema 应用 + 解箱 + 输入深拷:全部消费者经此入口,不直接触 Config 产物。 */
+export function resolveConfig(entry) {
+  const sanitized = sanitizeConfigEntry(entry ?? {})
+  return unwrapConfig(Config(structuredClone(sanitized)))
+}
+
+// 落盘行 config 的类型防御:设置写路径(原生页/mutate)可能把 volatile 字段
+// 以非预期形态(ref 序列化产物 {})持久化,冷启动 Config 直接抛 → 行死 →
+// settings describe 无此节 → 设置页保存 "no longer configurable" 死锁,
+// 只能手工改 patch 解锁。类型不符的键降级为 schema 默认:行活、设置页活、
+// 数据可经保存覆盖修复(官方 schema default 兜底同语义)。
+// 字段类型契约:与 schema 声明一一对应,清洗按此对账
+const FIELD_TYPES = {
+  shells: 'array',
+  deny: 'array',
+  default: 'string',
+  cwd: 'string',
+  timeoutMs: 'number',
+  maxTimeoutMs: 'number',
+  maxOutputBytes: 'number',
+  maxSpillBytes: 'number',
+  graceMs: 'number',
+}
+export function sanitizeConfigEntry(entry) {
+  if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) return {}
+  const out = {}
+  for (const [key, kind] of Object.entries(FIELD_TYPES)) {
+    const value = entry[key]
+    if (value === undefined) continue
+    const valid = kind === 'array' ? Array.isArray(value) : typeof value === kind
+    if (valid) out[key] = value
+  }
+  return out
+}
+
 /** 出厂默认配置(供文档与测试比对;schema 内 default 为同构静态值)。 */
 export function defaultConfig() {
-  return Config({})
+  return resolveConfig({})
+}
+
+// yaml 无引号标量会把 `\` 字面落盘,任何一层再转义都让路径翻倍(C:\\ 实测):
+// 入口统一归一,保证进 schema 的 path 就是干净值。
+// 仅 Windows 宿主生效:posix 路径以 / 分隔,归一会把合法路径毁成反斜杠字面(CI linux 实测)
+export function normalizeWin32Path(path) {
+  if (process.platform !== 'win32') return path
+  if (typeof path !== 'string' || path.length === 0) return path
+  return path.replace(/\\{2,}/g, '\\').replace(/\//g, '\\')
+}
+
+// 更新负载深归一:shells[].path 与任意层字符串值只处理 path 键,避免误伤 args 模板
+export function normalizeConfigPaths(patch) {
+  if (typeof patch !== 'object' || patch === null || !Array.isArray(patch.shells)) return patch
+  return {
+    ...patch,
+    shells: patch.shells.map((entry) => (typeof entry?.path === 'string' ? { ...entry, path: normalizeWin32Path(entry.path) } : entry)),
+  }
+}
+
+function assertPositiveFinite(name, value) {
+  if (!Number.isFinite(value) || value <= 0) throw new Error(`shell-select: ${name} must be a positive finite number`)
+}
+
+/** 拒绝无法运行的已解析配置节(schema 之外的正数/时限/清单约束,官方 assertServiceable 同构)。 */
+export function assertServiceableConfig(config) {
+  assertPositiveFinite('timeoutMs', config.timeoutMs)
+  assertPositiveFinite('maxTimeoutMs', config.maxTimeoutMs)
+  assertPositiveFinite('maxOutputBytes', config.maxOutputBytes)
+  assertPositiveFinite('maxSpillBytes', config.maxSpillBytes)
+  assertPositiveFinite('graceMs', config.graceMs)
+  if (config.graceMs > MAX_TIMER_DELAY_MS) throw new Error(`shell-select: graceMs must be no greater than ${MAX_TIMER_DELAY_MS}`)
+  if (!Array.isArray(config.shells) || config.shells.length === 0) throw new Error('shell-select: shells must not be empty')
+  const ids = new Set()
+  for (const entry of config.shells) {
+    if (ids.has(entry.id)) throw new Error(`shell-select: duplicate shell id "${entry.id}"`)
+    ids.add(entry.id)
+  }
+  if (!ids.has(config.default)) throw new Error(`shell-select: default "${config.default}" is not a configured shell id`)
 }
 
 /**