@mzzsfy/dsh-shell-select 0.4.0 → 0.4.3

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,11 +14,13 @@
 
 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'
 import { registerShellTool } from './tool.mjs'
+import { mountShellPromptProjection } from './prompt-projection.mjs'
+import { mountPwshTakeover } from './pwsh-takeover.mjs'
 
 export const name = 'shell-select'
 
@@ -137,8 +139,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)))
@@ -150,13 +151,23 @@ export const ShellSelectExecutor = class ShellSelectExecutor extends ShellExecut
     })
     this.#registerTool()
     this.#mountPromptSection()
+    mountShellPromptProjection(ctx)
+    this.markPwshTakeover = mountPwshTakeover(ctx)
+  }
+
+  /** 挂载/换源共用落定:入参经宿主按 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()
   }
 
@@ -219,6 +230,21 @@ export const ShellSelectExecutor = class ShellSelectExecutor extends ShellExecut
     return { id: entry.id, kind: entry.kind, path: resolved, args: entry.args, login: entry.login === true, distro: entry.distro ?? '', env: entry.env ?? {} }
   }
 
+  /**
+   * 官方契约的 pwsh 落点:配置含 pwsh 条目时走 entryFor;条目被删除或不可解析时
+   * 仍按候选探测现场解析一台 pwsh(官方 dsh-pwsh-local 语义——pwsh 调用永远
+   * PowerShell,不落默认客户端,也不得以配置缺失为由改方言)。探测全失时才抛。
+   */
+  contractEntry() {
+    try {
+      return this.entryFor('pwsh')
+    } catch {
+      const [detected] = detectCandidates(['pwsh'], process.env, candidateExists)
+      if (detected === undefined) throw new Error('no pwsh executable on this machine: the official pwsh contract requires PowerShell (pwsh 7 or Windows PowerShell); reinstall PowerShell or add a pwsh entry in the shell-select settings section')
+      return { id: 'pwsh', kind: 'pwsh', path: normalizeWin32Path(detected.path), args: [], login: false, distro: '', env: {} }
+    }
+  }
+
   /** 注册/重注册 shell 工具(描述随客户端清单变化)。 */
   #registerTool() {
     this.#toolRegistration?.()
@@ -229,7 +255,7 @@ export const ShellSelectExecutor = class ShellSelectExecutor extends ShellExecut
     this.ctx.systemPrompt.section({
       name: 'tool:shell',
       order: this.ctx.systemPrompt.getSectionOrder('TOOL_PWSH'),
-      text: 'Non-zero exits are reported as `[exit code: N]` markers; investigate failures before moving on. Commands run in fresh processes: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Pass the `shell` argument only when the default client cannot run the command; the available clients are listed in the tool description.',
+      text: 'Non-zero exits are reported as `[exit code: N]` markers; investigate failures before moving on. On Windows a killed process settles as `[exit code: 1]` without a signal marker; treat a bare exit 1 after an interruption as a termination, not a command failure. Commands run in fresh processes: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Pass the `shell` argument only when the default client cannot run the command; the available clients are listed in the tool description.',
     })
   }
 
@@ -257,14 +283,17 @@ export const ShellSelectExecutor = class ShellSelectExecutor extends ShellExecut
     return buildArgv(entry, spec.command)
   }
 
-  /** 官方 execute seam:已解析 spec 按默认客户端前台执行(dsh-pwsh-local run 同构)。 */
+  /** 官方 execute seam:pwsh 客户端前台执行(dsh-pwsh-local run 同构,契约钉死 pwsh)。 */
   async run(spec) {
-    return this.runFor(this.entryFor(), spec)
+    this.markPwshTakeover()
+    return this.runFor(this.contractEntry(), spec)
   }
 
   /**
    * 官方 ctx.shell 唯一执行契约(ShellExecutor 抽象方法,官方 tool-pwsh 与
-   * 进程内消费方共同依赖):解析 spec 后按默认客户端 spawn,返回 ShellExecution
+   * 进程内消费方共同依赖):解析 spec 后按 pwsh 客户端 spawn(官方 dsh-pwsh-local
+   * 契约即 PowerShell 专用,落默认客户端会随配置漂移炸方言),返回
+   * ShellExecution
    * 句柄(done/readOutput/kill/observed/result)。前台与否是调用方 await 什么的
    * 属性,不是 spawn 的属性。沙箱语义与 runFor 同源:danger 直跑,受限模式
    * confine 包装,定案按 denial/runner-failure 规则附 sandbox 事实。
@@ -272,8 +301,9 @@ export const ShellSelectExecutor = class ShellSelectExecutor extends ShellExecut
    * @returns {Promise<object>} ShellExecution 句柄
    */
   async execute(spec) {
+    this.markPwshTakeover()
     this.assertNotDenied(spec.command)
-    const entry = this.entryFor()
+    const entry = this.contractEntry()
     const policy = spec.sandboxPolicy
     const { mode } = policy
     if (mode === 'danger-full-access') {
@@ -413,9 +443,10 @@ export const ShellSelectExecutor = class ShellSelectExecutor extends ShellExecut
     return Promise.resolve(proc)
   }
 
-  /** 官方 start seam:已解析 spec 按默认客户端后台启动(dsh-pwsh-local start 同构)。 */
+  /** 官方 start seam:pwsh 客户端后台启动(dsh-pwsh-local start 同构,契约钉死 pwsh)。 */
   start(spec) {
-    return this.startFor(this.entryFor(), spec)
+    this.markPwshTakeover()
+    return this.startFor(this.contractEntry(), spec)
   }
 
   /** 组装一次 spawn 的完整规格(官方 spawnSpec 同构,argv/条目参数化)。 */

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/prompt-projection.mjs

@@ -0,0 +1,34 @@
+// 只收敛模型投影，不改工具注册或执行策略；旧调用保持原 PowerShell 契约。
+export function mountShellPromptProjection(ctx) {
+  if (typeof ctx.on !== 'function') return
+  let warned = false
+  return ctx.on('system-prompt/assemble', async (assembly, context, next) => {
+    const result = await next()
+    if (ctx.tools.get('shell', context.scope) === undefined) return result
+    let sections = result.sections
+    const sdk = sections.find((section) => section.name === 'tools:sdk' && section.text.trim() !== '')
+    if (sdk !== undefined) {
+      try {
+        const { renderToolsSdk, renderToolsSdkPy } = await import('@deepseek-ai/dsh-tools')
+        const render = { typescript: renderToolsSdk, python: renderToolsSdkPy }[ctx.get('ptcRuntime')?.language]
+        if (typeof render !== 'function') throw new Error('PTC SDK renderer is unavailable')
+        const schemas = ctx.tools.schemas(context.scope)
+          .filter((schema) => schema.name !== 'pwsh' && schema.name !== 'run_code')
+          .map((schema) => ({ ...schema, output: ctx.tools.get(schema.name, context.scope).output.schema }))
+        const text = render(schemas)
+        sections = sections.map((section) => section === sdk ? { ...section, text, interpolate: false } : section)
+      } catch (error) {
+        if (!warned) {
+          warned = true
+          ctx.logger.warn(`shell-select: 模型工具投影未启用，保留原始工具与SDK：${error.message}`)
+        }
+        return result
+      }
+    }
+    return {
+      ...result,
+      tools: result.tools.filter((tool) => tool.name !== 'pwsh'),
+      sections: sections.filter((section) => section.name !== 'tool:pwsh'),
+    }
+  }, { prepend: true })
+}

package/src/pwsh-takeover.mjs

@@ -0,0 +1,23 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+
+export const PWSH_TAKEOVER_BLOCK = Object.freeze({ type: 'shell-select-takeover', tool: 'pwsh' })
+
+// 调用级事实独立于stdout，持久化扩展块不会进入模型文本。
+export function mountPwshTakeover(ctx) {
+  const calls = new AsyncLocalStorage()
+  const taken = new Set()
+  ctx.effect(() => () => { calls.disable(); taken.clear() })
+  ctx.on('tools/execute', (exec, next) => exec.name === 'pwsh'
+    ? calls.run(exec.token, next)
+    : next())
+  ctx.on('tools/post-execute', async (exec, result, next) => {
+    const intercepted = taken.delete(exec.token)
+    const decision = await next()
+    if (!intercepted || decision.kind !== 'accept' || Object.hasOwn(decision, 'content') || Object.hasOwn(decision, 'value')) return decision
+    return { ...decision, content: [...result.content, PWSH_TAKEOVER_BLOCK] }
+  }, { prepend: true })
+  return () => {
+    const token = calls.getStore()
+    if (token !== undefined) taken.add(token)
+  }
+}

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/resolve.mjs

@@ -4,8 +4,19 @@
 
 import { lstatSync } from 'node:fs'
 
-// PATH 分隔符:仅 Windows 分号(本包 v1 仅 win32 激活)
-const PATH_SEP = ';'
+// POSIX pwsh 探测锚点:发行版包管理器与官方 tarball/Microsoft 源的固定落点
+const POSIX_PWSH_ANCHORS = [
+  '/usr/bin/pwsh',
+  '/usr/local/bin/pwsh',
+  '/opt/microsoft/powershell/7/pwsh',
+  '/opt/homebrew/bin/pwsh',
+]
+
+// PATH 探测的可执行名:win32 带 .exe 后缀,POSIX 裸名
+const executableName = (kind, platform) => {
+  const suffix = platform === 'win32' ? '.exe' : ''
+  return { pwsh: `pwsh${suffix}`, bash: `bash${suffix}` }[kind]
+}
 
 // 各 kind 的探测锚点:主 ProgramFiles;x86 与 LOCALAPPDATA 仅 bash 有常见安装
 const PF_RELATIVE = {
@@ -29,12 +40,6 @@ const SYSTEM32_FILES = {
   wsl: 'wsl.exe',
 }
 
-// PATH 探测的可执行名
-const PATH_EXECUTABLES = {
-  pwsh: 'pwsh.exe',
-  bash: 'bash.exe',
-}
-
 // MSYS2 默认安装锚点:真实 bash.exe 优先。msys2.exe(Cygwin 控制台启动器)
 // 在管道 stdio 下 exit 0 且零输出——命令静默失败,任何情形不得进入候选
 const MSYS2_ANCHORS = [
@@ -43,18 +48,22 @@ const MSYS2_ANCHORS = [
 ]
 
 /**
- * 一个 kind 的候选路径,按解析顺序。显式参数化(env)保证纯函数性。
+ * 一个 kind 的候选路径,按解析顺序。显式参数化(env/platform)保证纯函数性。
  * @param {string} kind pwsh|bash|cmd|wsl
  * @param {object} env 模拟进程环境
+ * @param {string} [platform] 目标平台,缺省 process.platform
  * @returns {string[]}
  */
-export function candidatePaths(kind, env) {
+export function candidatePaths(kind, env, platform = process.platform) {
+  const isWin32 = platform === 'win32'
+  const pathSep = isWin32 ? ';' : ':'
+  const fileSep = isWin32 ? '\\' : '/'
   const programFiles = env.ProgramFiles ?? 'C:\\Program Files'
   const programFilesX86 = env['ProgramFiles(x86)'] ?? 'C:\\Program Files (x86)'
   const localAppData = env.LocalAppData ?? ''
   const system32 = `${env.SystemRoot ?? 'C:\\WINDOWS'}\\System32`
   const pathEntries = (env.PATH ?? '')
-    .split(PATH_SEP)
+    .split(pathSep)
     .map((entry) => entry.trim().replace(/^"|"$/g, ''))
     .filter((entry) => entry.length > 0)
   // bash 的 PATH 探测排除 SystemRoot 下条目:System32\bash.exe 是 WSL forwarder,
@@ -65,18 +74,21 @@ export function candidatePaths(kind, env) {
     ? pathEntries.filter((entry) => !entry.toLowerCase().replace(/\//g, '\\').startsWith(`${systemRoot}\\`))
     : pathEntries)
   const candidates = []
-  for (const relative of PF_RELATIVE[kind] ?? []) candidates.push([programFiles, ...relative].join('\\'))
-  for (const relative of PF_X86_RELATIVE[kind] ?? []) candidates.push([programFilesX86, ...relative].join('\\'))
-  for (const relative of LAD_RELATIVE[kind] ?? []) {
-    if (localAppData.length > 0) candidates.push([localAppData, ...relative].join('\\'))
+  if (isWin32) {
+    for (const relative of PF_RELATIVE[kind] ?? []) candidates.push([programFiles, ...relative].join('\\'))
+    for (const relative of PF_X86_RELATIVE[kind] ?? []) candidates.push([programFilesX86, ...relative].join('\\'))
+    for (const relative of LAD_RELATIVE[kind] ?? []) {
+      if (localAppData.length > 0) candidates.push([localAppData, ...relative].join('\\'))
+    }
   }
-  if (kind === 'bash') candidates.push(...MSYS2_ANCHORS)
+  if (isWin32 && kind === 'bash') candidates.push(...MSYS2_ANCHORS)
+  if (!isWin32 && kind === 'pwsh') candidates.push(...POSIX_PWSH_ANCHORS)
   for (const entry of pathEntriesForKind(kind)) {
-    const executable = PATH_EXECUTABLES[kind]
-    if (executable !== undefined) candidates.push(`${entry}\\${executable}`)
+    const executable = executableName(kind, platform)
+    if (executable !== undefined) candidates.push(`${entry}${fileSep}${executable}`)
   }
   const system32File = SYSTEM32_FILES[kind]
-  if (system32File !== undefined) candidates.push(`${system32}\\${system32File}`)
+  if (isWin32 && system32File !== undefined) candidates.push(`${system32}\\${system32File}`)
   return candidates
 }
 
@@ -87,9 +99,9 @@ export function candidatePaths(kind, env) {
  * @param {object} [env] 模拟进程环境,缺省用 process.env
  * @returns {string|undefined} 无候选命中时 undefined
  */
-export function resolveEntryPath(entry, exists, env = process.env) {
+export function resolveEntryPath(entry, exists, env = process.env, platform = process.platform) {
   if (entry.path.length > 0) return entry.path
-  for (const candidate of candidatePaths(entry.kind, env)) {
+  for (const candidate of candidatePaths(entry.kind, env, platform)) {
     if (exists(candidate)) return candidate
   }
   return undefined
@@ -103,11 +115,11 @@ export function resolveEntryPath(entry, exists, env = process.env) {
  * @param {(candidate: string) => boolean} exists
  * @returns {{kind: string, path: string}[]}
  */
-export function detectCandidates(kinds, env, exists) {
+export function detectCandidates(kinds, env, exists, platform = process.platform) {
   const seen = new Set()
   const found = []
   for (const kind of kinds) {
-    for (const candidate of candidatePaths(kind, env)) {
+    for (const candidate of candidatePaths(kind, env, platform)) {
       if (seen.has(candidate)) continue
       if (!exists(candidate)) continue
       seen.add(candidate)

package/src/tool.mjs

@@ -12,6 +12,7 @@ import { TOOL_ABORTED, defineTool } from '@deepseek-ai/dsh-tools'
 import { ESCALATION_TARGETS, approveEscalation, validateEscalationArgs } from '@deepseek-ai/dsh-sandbox'
 import { isAbsolute, resolve } from 'node:path'
 import { renderResult, renderProcessRead } from './render.mjs'
+import { PWSH_TAKEOVER_BLOCK } from './pwsh-takeover.mjs'
 import { parseExitStatus } from '@deepseek-ai/dsh-shell'
 
 /** 拒升权/Abort 错误构造:dsh-llm HarnessError 缺失时以同码 Error 降级(错误码通道不变)。 */
@@ -40,6 +41,25 @@ function blockedMarker(error) {
   return `[blocked by shell-select: matches deny pattern ${error.pattern}]`
 }
 
+/**
+ * deny 命中 → schema 合法的前台结果:拒绝事实全在 stderr 标记文本,
+ * 禁止携带 blocked/blockedBy 等声明外字段——输出 oneOf 各分支
+ * additionalProperties:false,违者被宿主判 INVALID_TOOL_OUTPUT,拒绝文案不可达。
+ */
+function deniedForeground(error, shellId) {
+  return {
+    kind: 'foreground',
+    exitCode: null,
+    signal: null,
+    timedOut: false,
+    aborted: false,
+    timeoutMs: 0,
+    stdout: { text: '', truncated: false },
+    stderr: { text: blockedMarker(error), truncated: false },
+    shell: shellId,
+  }
+}
+
 /** 显式 workdir 先行,相对者落会话工作区;否则用会话 cwd,执行器默认兜底(官方同构)。 */
 function resolveWorkdir(modelWorkdir, exec) {
   const headerCwd = exec.agent?.session.header.cwd
@@ -56,8 +76,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 +92,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 +102,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 +130,7 @@ function foregroundOutputProperties() {
     timeoutMs: { type: 'number', required: true },
     stdout: streamSchema,
     stderr: streamSchema,
+    shell: { type: 'string' },
     sandbox: {
       type: 'object',
       additionalProperties: false,
@@ -121,8 +144,11 @@ function foregroundOutputProperties() {
   }
 }
 
+/** bash 路径措辞:bash 输出的 MSYS 拼写不得回流进工具参数(宿主文件面只认 Windows 形式)。 */
+const BASH_PATH_GUIDANCE = 'Bash clients accept Windows-style paths (C:/...): use that form for `workdir` and file-tool arguments — MSYS spellings like `/c/Users/...` or `/tmp` only work inside the bash command itself, never in tool arguments.'
+
 /** 工具描述:客户端清单与方言随配置动态变化。 */
-function shellDescription({ executor, backgroundEnabled, escalationModes }) {
+export function shellDescription({ executor, backgroundEnabled, escalationModes }) {
   const listing = executor.listShells()
   const lines = listing.shells
     .map((entry) => `${entry.id} (${entry.kind}${entry.available ? '' : ', executable not found'})`)
@@ -135,22 +161,15 @@ function shellDescription({ executor, backgroundEnabled, escalationModes }) {
     + (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`.'
+  const bashPresent = listing.shells.some((candidate) => candidate.kind === 'bash' && candidate.available)
+  const text = bashPresent ? `${base} ${BASH_PATH_GUIDANCE}` : base
+  if (escalationModes.length === 0) return text
+  return text + ' Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. When a command is denied and a wider mode would let it succeed, escalate immediately in the same turn: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Never escalate speculatively: ground the request in a real denial. If the session states approval prompts are disabled, a denial is final — do not set `sandbox_permissions`.'
 }
 
-/** 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 +208,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,8 +262,10 @@ 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),
+      }, ...(toolName === 'pwsh' ? [PWSH_TAKEOVER_BLOCK] : [])],
     },
     async execute(args, exec) {
       validateArgs(args)
@@ -254,7 +275,8 @@ export function registerShellTool(ctx, { executor }) {
         : undefined
       const policy = approvedMode === undefined ? standingPolicy : { ...standingPolicy, mode: approvedMode }
       const workdir = resolveWorkdir(args.workdir, exec)
-      const entry = faces.executor.entryFor(pinned ?? args.shell)
+      // pwsh 契约:钉死工具永远 PowerShell,配置删条目也现场探测,不落默认客户端
+      const entry = pinned !== undefined ? faces.executor.contractEntry() : faces.executor.entryFor(args.shell)
       const request = {
         command: args.command,
         ...workdir !== undefined ? { workdir } : {},
@@ -267,17 +289,18 @@ export function registerShellTool(ctx, { executor }) {
         if (jobs === undefined) throw new Error('background jobs unavailable: load @deepseek-ai/dsh-jobs and @deepseek-ai/dsh-tool-jobs')
         if (exec.signal.aborted) throw await abortError('tool call aborted')
         try {
-          faces.executor.startFor(entry, faces.executor.resolve(request))
+          faces.executor.assertNotDenied(request.command)
         } 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 deniedForeground(error, entry.id)
           throw error
         }
         return {
           kind: 'background',
+          shell: entry.id,
           jobId: jobs.start({
             kind: 'shell',
             label: args.command,
-            ...exec.agent ? { owner: exec.agent } : {},
+            ...exec.agent ? { owner: exec.agent.id } : {},
             run: () => {
               const proc = faces.executor.startFor(entry, faces.executor.resolve(request))
               return {
@@ -296,11 +319,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 deniedForeground(error, entry.id)
         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) {
@@ -320,7 +343,7 @@ export function registerShellTool(ctx, { executor }) {
       }
     },
     presentResult: (args, result) => {
-      const block = result.content.length === 1 ? result.content[0] : undefined
+      const block = result.content.filter(part => part.type === 'text').length === 1 ? result.content.find(part => part.type === 'text') : undefined
       if (block === undefined || block.type !== 'text') return undefined
       const raw = block.text
       if (typeof args === 'object' && args !== null && args.run_in_background === true || result.isError) {

package/src/web-routes.mjs

@@ -5,7 +5,8 @@
 // settings.describe,写经 settings.replace;探测/扫描用 resolve 纯函数。
 // HTTP 形态(具名 exact 路由 + 跨源守卫 + 业务异常归一 400)照 dsh-maintain。
 
-import { KINDS, resolveConfig, assertServiceableConfig, normalizeConfigPaths, normalizeWin32Path } from './config.mjs'
+import { homedir, tmpdir } from 'node:os'
+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 +49,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)
 }
 
 /**
@@ -82,6 +85,8 @@ export function buildFaces(ctx, settings) {
     },
     detect: (kinds) => detectCandidates(kinds ?? [...KINDS], process.env, candidateExists),
     probe: (candidatePath) => candidateExists(candidatePath),
+    // 宿主路径事实:客户端侧栏路径救援用(翻译 MSYS 拼写回宿主形式的事实来源)
+    pathMap: () => ({ platform: process.platform, home: homedir(), tmpDir: tmpdir() }),
   }
 }