@mzzsfy/dsh-shell-select 0.4.0 → 0.4.3

package/test/background-owner.test.mjs

@@ -0,0 +1,14 @@
+// 后台 job owner 必须传 agent id(场景:run_in_background 报 "[object Object] has no live agent"):源级守卫
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const source = readFileSync(join(here, '..', 'src', 'tool.mjs'), 'utf8')
+
+test('后台 job owner 传 agent id 而非 agent 对象', () => {
+  assert.match(source, /owner: exec\.agent\.id/)
+  assert.doesNotMatch(source, /owner: exec\.agent \}/)
+})

package/test/client-card.test.mjs

@@ -26,14 +26,12 @@ function cardModel(catalog = null) {
     lastSegment,
     parseExitTail: extractLogic('parseExitTail'),
     hasSpillNotice: extractLogic('hasSpillNotice'),
+    parseShellMark: extractLogic('parseShellMark'),
+    stripShellMark: extractLogic('stripShellMark'),
     clientDisplayName: extractLogic('clientDisplayName', { clientCatalog: catalog }),
   })
 }
 
-function parseEnvText() {
-  return extractLogic('parseEnvText')
-}
-
 test('运行时长格式:秒→m:ss,一小时以上→h:mm:ss,负值钳 0', () => {
   const formatDuration = extractLogic('formatDuration')
   assert.equal(formatDuration(0), '0:00')
@@ -44,10 +42,6 @@ test('运行时长格式:秒→m:ss,一小时以上→h:mm:ss,负值钳 0', () =
   assert.equal(formatDuration(-5), '0:00')
 })
 
-function invalidEnvLines() {
-  return extractLogic('invalidEnvLines')
-}
-
 // 运行中调用块(官方形态:无 kind 字段)
 function runningBlock(argsRaw) {
   return { callId: 'c1', name: 'shell', argsRaw }
@@ -155,6 +149,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,15 +231,87 @@ test('S13 注册面:shell/pwsh/bash 三 key 且 priority -1(文本守卫)', () =
   assert.match(source, /key: toolKey, priority: -1/)
 })
 
-test('K=V 往返:值含 = 与空格无损,空行忽略,重复键后行胜', () => {
-  const parse = parseEnvText()
-  assert.deepEqual(parse('A=1\nB=x=y z\n\nA=2'), { A: '2', B: 'x=y z' })
-  assert.deepEqual(parse(''), {})
-  assert.deepEqual(parse(undefined), {})
+// ── 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('invalidEnvLines:缺 = 行报出,空行不报', () => {
-  const invalid = invalidEnvLines()
-  assert.deepEqual(invalid('A=1\nbroken\n\n  noSep  '), ['broken', 'noSep'])
-  assert.deepEqual(invalid('A=1'), [])
+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())
 })

package/test/client-id.test.mjs

@@ -23,11 +23,6 @@ test('标记值为完整 npm 包名', () => {
   assert.match(source, /setAttribute\('data-plugin', '@mzzsfy\/dsh-shell-select'\)/)
 })
 
-test('settings.section 注册与 id', () => {
-  assert.match(source, /settings\.section/)
-  assert.match(source, /id: 'shell-select'/)
-})
-
 test('tool.call.toolview 注册:shell 族三 key + priority -1', () => {
   assert.match(source, /'tool\.call\.toolview'/)
   assert.match(source, /const TOOLVIEW_KEYS = \['shell', 'pwsh', 'bash'\]/)
@@ -43,55 +38,4 @@ test('卡片数据链:官方同构派生(argsRaw + content 尾部退出标记)+
 test('primitives 缺席时图标降级自绘(require 有 try/catch 兜底)', () => {
   assert.match(source, /require\('@deepseek-ai\/dsh-client-ui-primitives'\)/)
   assert.match(source, /catch \{\s*return null\s*\}/)
-})
-
-test('扩展字段守卫:login/distro/env 进设置页数据链(wholesale replace 防静默重置)', () => {
-  // toSection(保存)与 toEntries(加载)必须同时携带 login/distro;
-  // env 走 envText(K=V 每行)编辑态往返:保存侧 parseEnvText,加载侧 envText
-  for (const field of ['login', 'distro']) {
-    const writes = (source.match(new RegExp(`^\\s*${field}: .*$`, 'gm')) ?? []).length
-    assert.ok(writes >= 2, `toSection/toEntries 应各携带 ${field}(发现 ${writes} 处)`)
-  }
-  assert.match(source, /env: parseEnvText\(entry\.envText\)/)
-  assert.match(source, /envText: Object\.entries\(entry\.env \?\? \{\}\)/)
-  assert.match(source, /登录壳/)
-  assert.match(source, /发行版/)
-})
-
-test('deny 黑名单进设置页数据链:逐条规则编辑器(deny 绝对,allow 已移除)', () => {
-  // 数据链:state 数组 → 保存直落 deny;加载侧 patternText 按条解析(Trim 去空白)
-  assert.match(source, /denyRules/)
-  assert.match(source, /deny: denyRules/)
-  assert.match(source, /patternText\(section\.deny\)/)
-  // 行级即时校验 LOGIC 段 + 保存侧复用
-  assert.match(source, /denyPatternIssues/)
-  assert.match(source, /LOGIC-BEGIN denyPatternIssues/)
-  // 交互结构:规则行 + 删除 + 添加 + 空态提示
-  assert.match(source, /sls-rule/)
-  assert.match(source, /添加规则/)
-  assert.match(source, /未配置.*命中拦截不生效/)
-  // 术语与僵尸防线
-  assert.match(source, /命令黑名单/)
-  assert.doesNotMatch(source, /denyText/)
-  assert.doesNotMatch(source, /allowText|豁免名单|拒绝名单/)
-})
-
-// LOGIC 段行为测试:行级正则校验(提取形态照 client-card.test.mjs)
-function extractLogic(name) {
-  const pattern = new RegExp('// LOGIC-BEGIN ' + name + '\\n([\\s\\S]*?)\\n\\s*// LOGIC-END ' + name)
-  const match = source.match(pattern)
-  if (!match) throw new Error('client.js 缺少 LOGIC 段: ' + name)
-  return new Function('return (' + match[1].trim() + ')')()
-}
-
-test('denyPatternIssues:合法与空规则无问题', () => {
-  const issues = extractLogic('denyPatternIssues')(['^format\\s', 'rm -rf\\s+(?!\\S*node_modules)', ''])
-  assert.deepEqual(issues, [])
-})
-
-test('denyPatternIssues:非法规则定位到行(行号 = 规则序)', () => {
-  const issues = extractLogic('denyPatternIssues')(['^format\\s', 'rm -rf\\s+(?!', 'shutdown'])
-  assert.equal(issues.length, 1)
-  assert.equal(issues[0].index, 1)
-  assert.match(issues[0].error, /Invalid|regular|正则/)
 })

package/test/client-render.test.mjs

@@ -10,7 +10,7 @@ import { dirname, join } from 'node:path'
 const here = dirname(fileURLToPath(import.meta.url))
 const source = readFileSync(join(here, '..', 'src', 'client.js'), 'utf8')
 
-function reactStub() {
+function reactStub(expanded = false) {
   // 函数组件即时执行(模拟渲染语义):组件体内的未定义引用/坏访问当场抛出
   const createElement = (type, props, ...children) => {
     if (typeof type === 'function') return type(props ?? {})
@@ -18,14 +18,14 @@ function reactStub() {
   }
   return {
     createElement,
-    useState: (init) => [typeof init === 'function' ? init() : init, () => {}],
+    useState: (init) => [expanded || (typeof init === 'function' ? init() : init), () => {}],
     useEffect: () => {},
   }
 }
 
 // 加载 client.js 并执行 apply,返回 slots 注册面
-function loadClient() {
-  const React = reactStub()
+function loadClient(expanded = false) {
+  const React = reactStub(expanded)
   const registrations = []
   const slots = {
     inject: (_name, factory) => factory(),
@@ -70,6 +70,39 @@ function settledBlock(argsRaw, text) {
   }
 }
 
+test('直接 pwsh 接管:折叠与展开都有独立徽章，复制输出剥离事实标记', () => {
+  // Given 已接管 pwsh 结果；When折叠/展开渲染；Then徽章可见且输出不泄露内部标记。
+  const args = JSON.stringify({ command: 'Get-Date', description: 'probe' })
+  for (const expanded of [false, true]) {
+    const component = toolviewOf(loadClient(expanded), 'pwsh')
+    const block = settledBlock(args, 'out\n[exit code: 2]')
+    block.content.push({ type: 'shell-select-takeover', tool: 'pwsh' })
+    const element = component({ block, cwd: 'C:\\repo' })
+    const nodes = []
+    const walk = (node) => { if (!node || typeof node !== 'object') return; if (Array.isArray(node)) return node.forEach(walk); nodes.push(node); node.children?.forEach(walk) }
+    walk(element)
+    assert.ok(nodes.some(node => node.props?.className === 'sls-tv__takeover' && node.children.includes('插件接管')))
+    assert.doesNotMatch(JSON.stringify(element), /\[shell-select: pwsh takeover\]/)
+    if (expanded) assert.ok(nodes.some(node => node.props?.className === 'sls-tv__badge' && node.children.includes('pwsh')))
+  }
+})
+
+test('历史 stdout 恰含标记也不得冒充接管事实或丢失输出', () => {
+  // Given历史pwsh stdout含旧标记；When展开；Then没有接管徽章且原文保留。
+  const element = toolviewOf(loadClient(true), 'pwsh')({ block: settledBlock(JSON.stringify({ command: 'Write-Output marker', description: 'history' }), '[shell-select: pwsh takeover]'), cwd: 'C:\\repo' })
+  assert.doesNotMatch(JSON.stringify(element), /插件接管/)
+  assert.match(JSON.stringify(element), /\[shell-select: pwsh takeover\]/)
+})
+
+test('未标记历史 pwsh 与普通 shell 不显示接管徽章', () => {
+  // Given普通/历史结果；When渲染；Then不由工具名或当前配置臆测接管。
+  const args = JSON.stringify({ command: 'echo x', description: 'probe' })
+  for (const key of ['pwsh', 'shell']) {
+    const element = toolviewOf(loadClient(true), key)({ block: settledBlock(args, 'out'), cwd: 'C:\\repo' })
+    assert.doesNotMatch(JSON.stringify(element), /插件接管/)
+  }
+})
+
 test('渲染守卫:settled terminal 调用组件执行不抛(引用完整)', () => {
   const component = toolviewOf(loadClient(), 'shell')
   const element = component({
@@ -108,18 +141,10 @@ test('渲染守卫:后台 ack 块(默认收起行 + 任务号徽标)组件执行
   assert.notEqual(element, undefined)
 })
 
-test('设置卡注册:settings.section 单卡 id shell-select', () => {
-  const registrations = loadClient()
-  const card = registrations.find((item) => item.meta.name === 'settings.section')
-  assert.notEqual(card, undefined)
-  assert.equal(card.meta.id, 'shell-select')
-})
-
 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'/)
 })
@@ -157,7 +182,7 @@ test('hooks 恒序守卫:组件内 hook 调用必须全部位于第一个提前
     const m = /return h\(/.exec(scope)
     return m === null ? Number.POSITIVE_INFINITY : beginLine + scope.slice(0, m.index).split('\n').length - 1
   }
-  for (const name of ['ShellToolRow', 'GenericShellRow', 'CopyButton', 'RunningDuration', 'ShellSelectApp']) {
+  for (const name of ['ShellToolRow', 'GenericShellRow', 'CopyButton', 'RunningDuration']) {
     const { hookLines } = extract(name)
     const scopeBody = source.slice(source.indexOf(`function ${name}(`))
     const end = scopeBody.indexOf('\n    function ', 1)

package/test/config-entry.test.mjs

@@ -1,4 +1,4 @@
-// 条目级 env 与 wsl distro:schema 默认、argv 形、entryFor 透传。BDD 场景见 docs/feat-shell-select-optim/plan.md S5-S10。
+// 条目级 env 与 wsl distro:schema 默认、argv 形、entryFor 透传。BDD 场景见 docs/feat-shell-select-optim/plan.md S5-S10。
 
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
@@ -69,6 +69,7 @@ function stubCtxFor(config) {
   const registered = { sections: [], tools: [], promptSections: [], routes: [] }
   return {
     reflect: { provide: () => {} },
+    on: () => () => {},
     logger: { warn: () => {} },
     effect: (fn) => { registered.routes.push(fn) },
     get() { return { register: () => {} } },

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/deny-output-schema.test.mjs

@@ -0,0 +1,53 @@
+// FIND-020-3 回归:deny 命中返回对象必须通过工具输出 foreground oneOf 分支校验
+// (additionalProperties:false)——历史缺陷:blocked/blockedBy 声明外字段致宿主判
+// INVALID_TOOL_OUTPUT,拒绝文案在真机不可达。
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+import { DenyError } from '../src/denylist.mjs'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const source = readFileSync(join(here, '..', 'src', 'tool.mjs'), 'utf8')
+
+// 前台输出分支属性表与 additionalProperties 与 src/tool.mjs 同源抽取
+function extractForegroundProperties(src) {
+  const start = src.indexOf('function foregroundOutputProperties()')
+  const body = src.slice(start, src.indexOf('\n}\n', start))
+  return body
+}
+
+function pickStringProps(propsSource) {
+  const names = [...propsSource.matchAll(/^\s{4}(\w+):/gm)].map((m) => m[1])
+  return names
+}
+
+test('deniedForeground 返回对象逐字段落 foreground 分支声明内', () => {
+  const propsSource = extractForegroundProperties(source)
+  const declared = pickStringProps(propsSource)
+  assert.ok(declared.includes('kind') && declared.includes('stderr'), '属性表抽取自净(schema 自身声明)')
+  // deniedForeground 构造器字段全部在声明表内(拒绝实现不再携带声明外字段)
+  const fnStart = source.indexOf('function deniedForeground(')
+  const fnBody = source.slice(fnStart, source.indexOf('\n}\n', fnStart))
+  const used = [...fnBody.matchAll(/^\s{4}(\w+):/gm)].map((m) => m[1])
+  const extra = used.filter((k) => !declared.includes(k))
+  assert.deepEqual(extra, [], `deniedForeground 不得携带声明外字段: ${extra.join(',')}`)
+  assert.doesNotMatch(fnBody, /blocked:/)
+  assert.doesNotMatch(fnBody, /blockedBy:/)
+})
+
+test('两执行分支 catch 均走 deniedForeground(不再内联声明外字段对象)', () => {
+  assert.equal((source.match(/deniedForeground\(error, entry\.id\)/g) ?? []).length, 2)
+  assert.doesNotMatch(source, /kind: 'foreground', shell: entry\.id, blocked: true/)
+})
+
+test('拒绝文案仍含契约锚(模型可见 [blocked by shell-select: matches deny pattern …])', () => {
+  const error = new DenyError('echo\\\\s', 'echo x')
+  const fnStart = source.indexOf('function deniedForeground(')
+  const fnBody = source.slice(fnStart, source.indexOf('\n}\n', fnStart))
+  assert.match(fnBody, /blockedMarker\(error\)/)
+  assert.match(source, /function blockedMarker\(error\)/)
+  assert.ok(error.pattern.length > 0)
+})

package/test/executor-seam.test.mjs

@@ -1,4 +1,4 @@
-// executor 官方 seam 集成(桩 ctx):BDD 场景见本文件与 README「官方工具兼容」。
+// executor 官方 seam 集成(桩 ctx):BDD 场景见本文件与 README「官方工具兼容」。
 // 背景:preset 注入的官方 tool-pwsh 经 cordis 服务代理(ctx.shell)调用执行器,
 // 代理把方法 this 重定向到阴影对象;执行器公开面必须与官方 PwshLocalExecutor
 // 同构地使用公有字段/方法(#私有在阴影 receiver 下触发品牌检查错误)。
@@ -38,6 +38,7 @@ function stubCtx({ sandboxMode = 'danger-full-access', spawn = stubSpawn() } = {
   }
   const ctx = {
     reflect: { provide: () => {} },
+    on: () => () => {},
     logger: { warn: () => {} },
     get(service) {
       if (service === 'webServer') return { register: (item) => registered.routes.push(item.path) }

package/test/executor.test.mjs

@@ -4,7 +4,14 @@
 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'
+
+test('执行器激活后挂模型工具投影', () => {
+  // Given 有模型服务；When构造执行器；Then组装事件由执行器生命周期持有。
+  const { ctx, registered } = stubCtx()
+  new ShellSelectExecutor(ctx, baseConfig())
+  assert.equal(registered.listeners?.filter((row) => row.name === 'system-prompt/assemble').length, 1)
+})
 
 // --- 桩具 ---
 
@@ -59,6 +66,11 @@ function stubCtx({ withSettings = true, sandboxMode = 'danger-full-access', spaw
       }
       fn(child)
     },
+    on(name, handler) {
+      registered.listeners ??= []
+      registered.listeners.push({ name, handler })
+      return () => {}
+    },
     subprocess: spawn,
     sandbox: {
       confine: (argv, policy) => ({
@@ -125,7 +137,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 +420,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()))
+})