@mzzsfy/dsh-shell-select 0.4.1 → 0.4.4

package/src/executor.mjs

@@ -19,6 +19,8 @@ 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'
 
@@ -149,6 +151,8 @@ export const ShellSelectExecutor = class ShellSelectExecutor extends ShellExecut
     })
     this.#registerTool()
     this.#mountPromptSection()
+    mountShellPromptProjection(ctx)
+    this.markPwshTakeover = mountPwshTakeover(ctx)
   }
 
   /** 挂载/换源共用落定:入参经宿主按 static Config resolve,volatile 字段是
@@ -226,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?.()
@@ -236,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.',
     })
   }
 
@@ -264,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 事实。
@@ -279,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') {
@@ -420,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/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/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
@@ -124,22 +144,34 @@ function foregroundOutputProperties() {
   }
 }
 
-/** 工具描述:客户端清单与方言随配置动态变化。 */
-function shellDescription({ executor, backgroundEnabled, escalationModes }) {
+/** Bash 命令内路径与宿主工具参数使用不同拼写。 */
+const BASH_PATH_GUIDANCE = 'Use Windows-style paths (C:/...) in workdir and file-tool arguments; MSYS paths (/c/..., /tmp) are valid only inside Bash commands.'
+const SHELL_ENVIRONMENTS = { pwsh: 'PowerShell', bash: 'Bash', cmd: 'Windows cmd.exe', wsl: 'WSL' }
+
+/** 工具描述只展示当前配置与常规调用方式。 */
+export function shellDescription({ executor, backgroundEnabled }) {
   const listing = executor.listShells()
-  const lines = listing.shells
-    .map((entry) => `${entry.id} (${entry.kind}${entry.available ? '' : ', executable not found'})`)
-    .join(', ')
-  const base = 'Execute a command in one of the configured shell clients and return its stdout/stderr. '
-    + `Available clients: ${lines}. The default client is "${listing.default}"; pass \`shell\` only when this command needs a different client (dialects differ: pwsh = PowerShell, bash/wsl = POSIX, cmd = cmd.exe). `
-    + 'Each call runs in a fresh process: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. '
-    + 'Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed environment variables (`DSH_*`); inspect them when needed. '
-    + 'Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. '
-    + (backgroundEnabled
-      ? 'Set `run_in_background: true` for long-running commands: the call returns a job id immediately; read its output with `job_output` and stop it with `job_kill`.'
-      : 'Background execution is not available; long-running commands must finish within the timeout.')
-  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 clients = listing.shells.map((entry) => {
+    const distro = entry.kind === 'wsl' && entry.distro ? ` (${entry.distro})` : ''
+    const availability = entry.available ? '' : ' (unavailable)'
+    return `- ${entry.id} — ${SHELL_ENVIRONMENTS[entry.kind]}${distro}${availability}`
+  }).join('\n')
+  const bashPresent = listing.shells.some((entry) => entry.kind === 'bash' && entry.available)
+  return [
+    `Execute commands using shell=${JSON.stringify(listing.default)} by default and return stdout/stderr.`,
+    'Omit shell to use the default; set it to one of:',
+    clients,
+    '',
+    'Each call starts a fresh process; cwd, variables, and functions do not persist.',
+    'Use workdir to set the working directory.',
+    ...bashPresent ? [BASH_PATH_GUIDANCE] : [],
+    '',
+    ...backgroundEnabled ? [
+      'For long-running commands, set run_in_background=true.',
+      'Use job_output to read background output and job_kill to stop the job.',
+    ] : ['Background execution is not available; long-running commands must finish within the timeout.'],
+    'Long output is truncated; the full-output file path is reported when available.',
+  ].join('\n')
 }
 
 /** pwsh 工具描述:兼容保留工具,只声明不要调用与去向,零执行语义。 */
@@ -182,7 +214,7 @@ export function registerShellTool(ctx, { executor }) {
   const makeDefinition = (toolName, pinned) => (faces) => defineTool({
     name: toolName,
     description: pinned === undefined
-      ? shellDescription({ executor: faces.executor, backgroundEnabled, escalationModes })
+      ? shellDescription({ executor: faces.executor, backgroundEnabled })
       : pwshDescription(),
     parameters: {
       command: {
@@ -199,7 +231,7 @@ export function registerShellTool(ctx, { executor }) {
       },
       ...pinned === undefined ? { shell: {
         type: 'string',
-        description: 'Shell client id from the tool description list (e.g. pwsh, git-bash, cmd). Omit to use the configured default client.',
+        description: 'Override the default shell using an id listed above.',
       } } : {},
       timeoutMs: {
         type: 'number',
@@ -217,7 +249,7 @@ export function registerShellTool(ctx, { executor }) {
         sandbox_permissions: {
           type: 'string',
           enum: [...escalationModes],
-          description: 'The wider sandbox mode this command needs. Only valid as a one-shot retry of a command the sandbox just denied; requires justification and user approval.',
+          description: 'Wider sandbox access mode for this command; requires justification and user approval.',
         },
         justification: {
           type: 'string',
@@ -240,7 +272,7 @@ export function registerShellTool(ctx, { executor }) {
         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)
@@ -250,7 +282,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 } : {},
@@ -263,9 +296,9 @@ 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', 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 } }
+          if (isDenyError(error)) return deniedForeground(error, entry.id)
           throw error
         }
         return {
@@ -274,7 +307,7 @@ export function registerShellTool(ctx, { executor }) {
           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 {
@@ -293,7 +326,7 @@ export function registerShellTool(ctx, { executor }) {
           signal: exec.signal,
         }))
       } catch (error) {
-        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 } }
+        if (isDenyError(error)) return deniedForeground(error, entry.id)
         throw error
       }
       if (result.aborted) throw await abortError('tool call aborted')
@@ -317,7 +350,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,6 +5,7 @@
 // settings.describe,写经 settings.replace;探测/扫描用 resolve 纯函数。
 // HTTP 形态(具名 exact 路由 + 跨源守卫 + 业务异常归一 400)照 dsh-maintain。
 
+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'
@@ -84,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() }),
   }
 }
 

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

@@ -32,10 +32,6 @@ function cardModel(catalog = null) {
   })
 }
 
-function parseEnvText() {
-  return extractLogic('parseEnvText')
-}
-
 test('运行时长格式:秒→m:ss,一小时以上→h:mm:ss,负值钳 0', () => {
   const formatDuration = extractLogic('formatDuration')
   assert.equal(formatDuration(0), '0:00')
@@ -46,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 }
@@ -323,16 +315,3 @@ test('S21j 钉死键集与注册键集同源:PINNED_CLIENT 恒等于 TOOLVIEW_KE
     .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' })
-  assert.deepEqual(parse(''), {})
-  assert.deepEqual(parse(undefined), {})
-})
-
-test('invalidEnvLines:缺 = 行报出,空行不报', () => {
-  const invalid = invalidEnvLines()
-  assert.deepEqual(invalid('A=1\nbroken\n\n  noSep  '), ['broken', 'noSep'])
-  assert.deepEqual(invalid('A=1'), [])
-})

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|正则/)
 })