@mzzsfy/dsh-shell-select 0.1.0

package/src/guard-config.mjs

@@ -0,0 +1,64 @@
+// guard 官方行配置:从宿主 settings.yaml 读官方 `shell` 节,代挂 pwsh-sandbox
+// 时透传(Config 消费 pwshPath 等),保持官方执行器配置零感知延续。
+// settings.yaml 定位经宿主 dsh-home-paths(官方同构 gateway officialRowConfig,
+// 剥离 pi-ai 专属的 compat 键处理——pwsh 配置无此形态)。
+
+/**
+ * 读官方 shell 节。
+ * @param {() => Promise<object>} readDocument settings.yaml 全文档读取(测试注入)
+ * @returns {Promise<object>} 节缺失/读取失败一律空对象(schema 默认顶上)
+ */
+export async function officialRowConfig(readDocument) {
+  try {
+    const document = await readDocument()
+    const section = document?.shell
+    return typeof section === 'object' && section !== null && !Array.isArray(section) ? section : {}
+  } catch {
+    return {}
+  }
+}
+
+/**
+ * settings.yaml 全文档读取的生产实现:宿主入口依赖树内解析 dsh-home-paths
+ * 与 yaml 包,经 realpath 对齐宿主本体树(官方同构;解析链裸 import 会命中
+ * 与运行宿主脱钩的副本)。
+ */
+export async function readSettingsDocument() {
+  const { createRequire } = await import('node:module')
+  const { pathToFileURL } = await import('node:url')
+  const { realpath } = await import('node:fs/promises')
+  const { dirname, join } = await import('node:path')
+  const entry = process.argv[1]
+  if (!entry) return {}
+  const realEntry = await realpath(entry)
+  const require = createRequire(pathToFileURL(realEntry))
+  const yamlPath = await realpath(require.resolve('yaml'))
+  const { parse } = await import(pathToFileURL(yamlPath).href)
+  let home = null
+  try {
+    const homePaths = await realpath(require.resolve('@deepseek-ai/dsh-home-paths'))
+    const resolved = await import(pathToFileURL(homePaths).href)
+    home = resolved.resolveDshHome
+  } catch {
+    home = null
+  }
+  const filename = typeof home === 'function' ? join(home(), 'settings.yaml') : join(dirname(process.execPath), 'settings.yaml')
+  const { readFile } = await import('node:fs/promises')
+  return parse(await readFile(filename, 'utf8'))
+}
+
+/** 官方包物理路径解析:宿主入口依赖树内定位(官方同构),失败返回 null。 */
+export async function resolveFromHostTree(packageName) {
+  try {
+    const { createRequire } = await import('node:module')
+    const { pathToFileURL } = await import('node:url')
+    const { realpath } = await import('node:fs/promises')
+    const entry = process.argv[1]
+    if (!entry) return null
+    const realEntry = await realpath(entry)
+    const require = createRequire(pathToFileURL(realEntry))
+    return await realpath(require.resolve(packageName))
+  } catch {
+    return null
+  }
+}

package/src/guard-state.mjs

@@ -0,0 +1,62 @@
+// guard 死态判定(纯函数):主行功能性停摆(禁用停稳 / 旗标 inactive;崩溃
+// pending 保守不判)且官方两行被禁停稳。行 id 解析与 Entry.disabled getter
+// 语义同构 dsh-llm-pi-gateway takeover.mjs(!!js 求值 + 布尔宽化,抛错按未禁)。
+
+// 本包主行 id(cordis.patch.yml insert 声明)
+export const MAIN_ROW_ID = 'shell-select'
+// 官方受控行 id(dsh-base cordis.patch.yml 声明)
+export const OFFICIAL_ROW_IDS = ['tool-pwsh', 'pwsh-sandbox']
+
+// 行 id 解析候选前缀:宿主把 profile 行树经 cordis:include 挂载,受控行实际
+// 解析 id 带前缀;空串覆盖裸树形态(官方同构)
+export const ROW_ID_PREFIXES = ['include:', '']
+
+const ABSENT = Object.freeze({ present: false, disabled: false, running: false })
+
+/** Entry.disabled getter 语义:求值抛错按未禁处理(让位安全向,不占官方资源)。 */
+export function effectiveDisabled(entry) {
+  try {
+    return entry.disabled === true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * 行状态探测;loader 缺失或行不存在按缺席。
+ * @returns {{present: boolean, disabled: boolean, running: boolean}}
+ */
+export function rowState(loader, id) {
+  if (loader?.resolve === undefined) return ABSENT
+  for (const prefix of ROW_ID_PREFIXES) {
+    try {
+      const entry = loader.resolve(prefix + id)
+      if (entry) {
+        return {
+          present: true,
+          disabled: effectiveDisabled(entry),
+          running: entry.fiber?.uid != null,
+        }
+      }
+    } catch {
+      // 该命名空间无此行,试下一候选
+    }
+  }
+  return ABSENT
+}
+
+/**
+ * 死态判定:主行功能性停摆且官方两行全部禁用停稳。
+ * @param {object} loader 宿主 loader 服务
+ * @param {{applyState: () => string}} faces apply 旗标读数
+ * @returns {boolean} PENDING 形态(行不可解析)按 false 处理,下轮再扫
+ */
+export function detectDeadState(loader, { applyState }) {
+  const main = rowState(loader, MAIN_ROW_ID)
+  const mainStalled = (main.present && main.disabled && !main.running) || applyState() === 'inactive'
+  if (!mainStalled) return false
+  return OFFICIAL_ROW_IDS.every((id) => {
+    const state = rowState(loader, id)
+    return !state.present || (state.disabled && !state.running)
+  })
+}

package/src/guard.js

@@ -0,0 +1,256 @@
+// shell-select guard 哨兵行:死态自愈,守服务不抢权(逐项同构 dsh-llm-pi-gateway
+// guard,差异仅代挂对象为官方 tool-pwsh + pwsh-sandbox 两行,且无 compat 键处理)。
+// 死态 = 主行功能性停摆(市场开关即时禁用 / apply 旗标 inactive)且官方两行仍被
+// bundle patch 禁用停稳——无任何 shell 执行器与工具。代挂走 ctx.plugin,随 guard
+// fiber 卸载;主行或官方行任一复活先卸代挂。guard 行 id 含 "/",市场行写入对其
+// 拒绝,窗口内始终存活。
+
+import { MAIN_ROW_ID, OFFICIAL_ROW_IDS, detectDeadState, rowState } from './guard-state.mjs'
+import { officialRowConfig, readSettingsDocument, resolveFromHostTree } from './guard-config.mjs'
+import { shellSelectApplyState } from './apply-state.mjs'
+
+// 官方包 npm 名(与行 id 独立:行 id 是 dsh-base 组合行,包名才是模块解析键)
+const OFFICIAL_PACKAGES = {
+  'tool-pwsh': '@deepseek-ai/dsh-tool-pwsh',
+  'pwsh-sandbox': '@deepseek-ai/dsh-pwsh-sandbox',
+}
+// pwsh-sandbox 行消费官方 settings 文档的 `shell` 节;tool-pwsh 行零配置(schema 默认)
+const OFFICIAL_ROW_CONFIG = {
+  'tool-pwsh': async () => ({}),
+  'pwsh-sandbox': async () => officialRowConfig(readSettingsDocument),
+}
+
+// 事件缺失时的轮询兜底周期与退场等待上界(官方同构)
+const SWEEP_INTERVAL_MS = 3000
+const EXIT_POLL_INTERVAL_MS = 20
+const EXIT_POLL_ROUNDS = 50
+// 护栏:官方包加载/代挂上界,超时按本周期放弃(防 boot 树卡死)
+const MOUNT_TIMEOUT_MS = 10 * 1000
+const LOAD_TIMEOUT_MS = 10 * 1000
+
+const delay = (ms) => new Promise((resolve) => {
+  const timer = setTimeout(resolve, ms)
+  timer.unref?.()
+})
+
+async function withTimeout(promise, timeoutMs, label) {
+  let timer = null
+  try {
+    return await Promise.race([
+      Promise.resolve(promise),
+      new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`${label} 超时(${timeoutMs}ms)`)), timeoutMs)
+      }),
+    ])
+  } finally {
+    if (timer !== null) clearTimeout(timer)
+  }
+}
+
+/**
+ * 官方包模块归一成 ctx.plugin 可挂载形态:apply 型模块(如 tool-pwsh)直挂,
+ * Service 类包(pwsh-sandbox 仅 default 导出类)挂类本身;两形态皆无返回
+ * undefined(按预载失败处理)。
+ */
+function mountableOf(module) {
+  if (typeof module?.apply === 'function') return module
+  if (typeof module?.default === 'function') return module.default
+  return undefined
+}
+
+/** 官方包模块加载:宿主本体树优先,失败回退裸 import;均败抛错(调用方放弃自愈)。 */
+async function importOfficial(packageName) {
+  const hostPath = await resolveFromHostTree(packageName)
+  if (hostPath !== null) {
+    const { pathToFileURL } = await import('node:url')
+    return import(pathToFileURL(hostPath).href)
+  }
+  return import(packageName)
+}
+
+/**
+ * 安装 guard:初始判定后事件跟随 + 轮询兜底双通道跟随死态/复活边沿。
+ * 全部状态挂 guard 自身 fiber,随其卸载自动清理。
+ */
+export async function installGuard(ctx, {
+  importOfficial: importOfficialOverride,
+  delay: delayOverride = delay,
+  sweepIntervalMs = SWEEP_INTERVAL_MS,
+  timeouts = {},
+} = {}) {
+  const loadTimeout = timeouts.load ?? LOAD_TIMEOUT_MS
+  const mountTimeout = timeouts.mount ?? MOUNT_TIMEOUT_MS
+  const importOne = importOfficialOverride ?? importOfficial
+
+  // 官方模块预载并归一挂载形态:瞬时失败退避重试,耗尽才停用自愈
+  // (HMR 重建风暴期 import 竞争易超时,单次放弃会让死态窗口无自愈)
+  const modules = new Map()
+  const LOAD_RETRIES = 2
+  const LOAD_RETRY_DELAY_MS = 3 * 1000
+  for (const id of OFFICIAL_ROW_IDS) {
+    let lastError = null
+    for (let attempt = 0; attempt <= LOAD_RETRIES; attempt++) {
+      try {
+        const loaded = mountableOf(await withTimeout(importOne(OFFICIAL_PACKAGES[id]), loadTimeout, `guard 官方包 ${OFFICIAL_PACKAGES[id]} 加载`))
+        if (loaded === undefined) throw new Error('模块既无 apply 也无 default 导出,无法挂载')
+        modules.set(id, loaded)
+        lastError = null
+        break
+      } catch (error) {
+        lastError = error
+        if (attempt < LOAD_RETRIES) {
+          await delayOverride(LOAD_RETRY_DELAY_MS)
+        }
+      }
+    }
+    if (lastError !== null) {
+      ctx.logger.warn(`shell-select/guard: 官方 ${OFFICIAL_PACKAGES[id]} 不可用,死态自愈停用: ${lastError?.message ?? lastError}`)
+      return undefined
+    }
+  }
+
+  // 代挂状态:id → fiber;mounting 去并发,卸载幂等
+  let mounted = new Map()
+  let mounting = null
+
+  const readRowConfig = async (id) => {
+    try {
+      return await withTimeout(OFFICIAL_ROW_CONFIG[id](), mountTimeout, `guard ${id} 行配置读取`)
+    } catch {
+      return {}
+    }
+  }
+
+  async function mountOfficial() {
+    if (mounted.size > 0 || mounting !== null) return
+    mounting = (async () => {
+      const fibers = new Map()
+      try {
+        // 服务依赖方(tool-pwsh inject shell)与提供者(pwsh-sandbox provide shell)
+        // 都不能串行 await 激活:依赖方挂载会在等待提供者时自锁。全部先发起,
+        // 再统一等待落定;纤维 await 等的是激活完成,窗口由 mountTimeout 兜底。
+        const created = OFFICIAL_ROW_IDS.map(async (id) => {
+          const config = await readRowConfig(id)
+          return [id, Promise.resolve(ctx.plugin(modules.get(id), config))]
+        })
+        for (const pair of await Promise.all(created)) {
+          const [id, fiberPromise] = pair
+          fibers.set(id, await withTimeout(fiberPromise, mountTimeout, `guard 代挂 ${id}`))
+        }
+        mounted = fibers
+        ctx.logger.warn('shell-select/guard: 主行与官方 shell 链同时停用,已代挂官方工具恢复服务;重启后由宿主组合自然归位')
+      } catch (error) {
+        ctx.logger.error(`shell-select/guard: 代挂官方插件失败: ${error?.message ?? error}`)
+        // 半挂态回收:已挂成的部分先卸,不留半套官方链
+        for (const [id, fiber] of fibers) {
+          try {
+            await withTimeout(Promise.resolve(fiber).then((f) => f.dispose()), mountTimeout, `guard 回收半挂 ${id}`)
+          } catch (disposeError) {
+            ctx.logger.warn(`shell-select/guard: 半挂回收失败 ${id}: ${disposeError?.message ?? disposeError}`)
+          }
+        }
+      } finally {
+        mounting = null
+      }
+    })()
+    await mounting
+  }
+
+  async function unmountOfficial() {
+    if (mounting !== null) await mounting
+    const fibers = mounted
+    mounted = new Map()
+    for (const [id, fiber] of fibers) {
+      try {
+        await withTimeout(Promise.resolve(fiber).then((f) => f.dispose()), mountTimeout, `guard 卸代挂 ${id}`)
+      } catch (error) {
+        ctx.logger.warn(`shell-select/guard: 卸代挂失败 ${id}(${error?.message ?? error});放行继续,复活方可能撞残余注册,属有意取舍`)
+      }
+    }
+  }
+
+  // 复活让位:受控行任一即将 init 且本方在场,先卸代挂(waterfall 保证先于其 apply)
+  const patchContextGuard = async (entry, next) => {
+    const id = entry?.options?.id
+    if (id !== MAIN_ROW_ID && !OFFICIAL_ROW_IDS.includes(id)) return next()
+    if (entry.fiber?.uid != null) return next()
+    if (mounted.size === 0 && mounting === null) return next()
+    ctx.logger.warn(`shell-select/guard: ${id} 行复活,卸代挂让位`)
+    try {
+      await unmountOfficial()
+    } catch (error) {
+      ctx.logger.warn(`shell-select/guard: 卸代挂交接异常(${error?.message ?? error}),仍放行复活方`)
+    } finally {
+      return next()
+    }
+  }
+
+  // 禁用边沿:行退场后等注册撤清再判死态,防与退场序列并发
+  const partialDisposeGuard = async (entry) => {
+    const id = entry?.options?.id
+    if (id !== MAIN_ROW_ID && !OFFICIAL_ROW_IDS.includes(id)) return
+    if (entry.fiber?.uid != null) return
+    for (let round = 0; round < EXIT_POLL_ROUNDS; round += 1) {
+      if (entry.fiber?.uid == null) break
+      await delayOverride(EXIT_POLL_INTERVAL_MS)
+    }
+    if (detectDeadState(ctx.loader, { applyState: shellSelectApplyState }) === true) await mountOfficial()
+  }
+
+  // 轮询兜底:边沿时序因宿主版本而异,周期全量扫描保证最终一致;mount/unmount 各自幂等
+  let sweeping = false
+  const sweep = async () => {
+    if (sweeping) return
+    sweeping = true
+    try {
+      const dead = detectDeadState(ctx.loader, { applyState: shellSelectApplyState })
+      if (dead === true && mounted.size === 0 && mounting === null) await mountOfficial()
+      else if (dead === false && (mounted.size > 0 || mounting !== null)) await unmountOfficial()
+    } finally {
+      sweeping = false
+    }
+  }
+
+  // 可观测面:死态判定中间量与代挂状态只读暴露(排障与巡检共用)
+  const webServer = ctx.get?.('webServer')
+  if (webServer !== undefined && typeof webServer.register === 'function') {
+    const status = () => ({
+      dead: detectDeadState(ctx.loader, { applyState: shellSelectApplyState }),
+      applyState: shellSelectApplyState(),
+      mounted: [...mounted.keys()],
+      mounting: mounting !== null,
+      rows: [MAIN_ROW_ID, ...OFFICIAL_ROW_IDS].map((id) => ({ id, ...rowState(ctx.loader, id) })),
+    })
+    ctx.effect(() => webServer.register({
+      kind: 'exact',
+      path: '/api/shell-select/guard-status',
+      handler: (req, res) => {
+        res.writeHead(200, { 'content-type': 'application/json' })
+        res.end(JSON.stringify(status()))
+      },
+    }), 'shell-select/guard status route')
+  }
+
+  ctx.on('loader/patch-context', patchContextGuard, { global: true })
+  ctx.on('loader/partial-dispose', partialDisposeGuard, { global: true })
+
+  const initial = detectDeadState(ctx.loader, { applyState: shellSelectApplyState })
+  ctx.logger.info?.(`shell-select/guard: 初始判定 dead=${initial}`)
+  if (initial === true) await mountOfficial()
+
+  const timer = setInterval(() => {
+    void sweep()
+  }, sweepIntervalMs)
+  timer.unref?.()
+  return undefined
+}
+
+export const name = 'shell-select/guard'
+
+/**
+ * guard 行入口:零配置,无服务依赖(loader 经 ctx 原型链可达)。
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ */
+export async function apply(ctx) {
+  await installGuard(ctx)
+}

package/src/render.mjs

@@ -0,0 +1,59 @@
+// 模型可见渲染:官方 dsh-tool-pwsh 渲染逐字镜像(stdout、[stderr] 段、
+// 截断/超时/信号/退出/沙箱标记),文本形态变更必须与官方同步,否则
+// terminal 卡的 parseExitStatus 退出 pill 复原失效。
+
+import { sandboxDenialMarker, escalationHintMarker } from '@deepseek-ai/dsh-sandbox'
+
+/** 追加单流截断提示(带全量输出 spill 路径)。 */
+function streamText(output) {
+  if (!output.truncated) return output.text
+  return `${output.text}\n[output truncated; full output: ${output.spillPath ?? '(unavailable)'}]`
+}
+
+/**
+ * 前台运行结果 → 模型可见文本。
+ * @param {object} result ShellRunResult(含 sandbox 事实)
+ * @param {string[]} escalationModes 本组合公示的升权目标;非空时拒绝标记后附升权提示
+ */
+export function renderResult(result, escalationModes = []) {
+  const out = streamText(result.stdout)
+  const err = streamText(result.stderr)
+  let body = out
+  if (err.length > 0) {
+    if (body.length > 0 && !body.endsWith('\n')) body += '\n'
+    body += `[stderr]\n${err}`
+  }
+  if (body.length === 0) body = '(no output)'
+  const markers = []
+  if (result.sandbox?.denied) {
+    markers.push(sandboxDenialMarker(result.sandbox.mode))
+    if (escalationModes.length > 0) markers.push(escalationHintMarker('command'))
+  }
+  if (result.timedOut) markers.push(`[timed out after ${result.timeoutMs}ms]`)
+  if (result.signal !== null) markers.push(`[killed by signal: ${result.signal}]`)
+  else if (result.exitCode !== 0) markers.push(`[exit code: ${result.exitCode}]`)
+  if (markers.length === 0) return body
+  if (!body.endsWith('\n')) body += '\n'
+  return body + markers.join('\n')
+}
+
+/**
+ * 后台进程一次增量读 → job_output 增量文本。
+ * @param {object} read ShellProcessRead
+ * @param {object|undefined} sandbox 已定进程的沙箱事实
+ * @param {string[]} escalationModes
+ */
+export function renderProcessRead(read, sandbox, escalationModes = []) {
+  const notices = []
+  if (read.lossy) {
+    const paths = [read.stdoutSpillPath, read.stderrSpillPath].filter((path) => path !== undefined)
+    notices.push(`[some output was dropped from memory; full output: ${paths.length > 0 ? paths.join(', ') : '(unavailable)'}]`)
+  }
+  if (sandbox?.runnerFailed) notices.push('[sandbox: the sandbox runner itself failed under ' + sandbox.mode + ' mode — the command did not run; this is a sandbox problem, not a command failure]')
+  else if (sandbox?.denied) {
+    notices.push(sandboxDenialMarker(sandbox.mode))
+    if (escalationModes.length > 0) notices.push(escalationHintMarker('command'))
+  }
+  if (notices.length === 0) return read.delta
+  return `${read.delta}${read.delta.length > 0 && !read.delta.endsWith('\n') ? '\n' : ''}${notices.join('\n')}`
+}

package/src/resolve.mjs

@@ -0,0 +1,128 @@
+// shell 可执行文件候选探测(纯函数):候选顺序、自动解析与批量探测。
+// 官方 dsh-pwsh-local candidatePwshPaths 语义同构,扩展 bash/cmd/wsl 三类。
+// 存在性判定与官方 lstat 语义一致(isFile || isSymbolicLink),由构造方注入。
+
+import { lstatSync } from 'node:fs'
+
+// PATH 分隔符:仅 Windows 分号(本包 v1 仅 win32 激活)
+const PATH_SEP = ';'
+
+// 各 kind 的探测锚点:主 ProgramFiles;x86 与 LOCALAPPDATA 仅 bash 有常见安装
+const PF_RELATIVE = {
+  pwsh: [['PowerShell', '7', 'pwsh.exe']],
+  bash: [['Git', 'bin', 'bash.exe']],
+}
+
+const PF_X86_RELATIVE = {
+  bash: [['Git', 'bin', 'bash.exe']],
+}
+
+// LOCALAPPDATA 下的附加锚点(仅 bash 的 per-user Git 安装)
+const LAD_RELATIVE = {
+  bash: [['Programs', 'Git', 'bin', 'bash.exe']],
+}
+
+// System32 单文件锚点
+const SYSTEM32_FILES = {
+  pwsh: 'WindowsPowerShell\\v1.0\\powershell.exe',
+  cmd: 'cmd.exe',
+  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 = [
+  'C:\\msys64\\usr\\bin\\bash.exe',
+  'C:\\msys64\\bin\\bash.exe',
+]
+
+/**
+ * 一个 kind 的候选路径,按解析顺序。显式参数化(env)保证纯函数性。
+ * @param {string} kind pwsh|bash|cmd|wsl
+ * @param {object} env 模拟进程环境
+ * @returns {string[]}
+ */
+export function candidatePaths(kind, env) {
+  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)
+    .map((entry) => entry.trim().replace(/^"|"$/g, ''))
+    .filter((entry) => entry.length > 0)
+  // bash 的 PATH 探测排除 SystemRoot 下条目:System32\bash.exe 是 WSL forwarder,
+  // 误命中会让 git-bash 客户端实际跑 WSL bash(方言/路径全变)。
+  // 斜杠形态归一后比较,正斜杠 PATH 条目(手动配置)同样命中;剥尾分隔符防前缀永不匹配
+  const systemRoot = String(env.SystemRoot ?? 'C:\\WINDOWS').toLowerCase().replace(/\//g, '\\').replace(/[\\/]+$/, '')
+  const pathEntriesForKind = (kind) => (kind === 'bash'
+    ? 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 (kind === 'bash') candidates.push(...MSYS2_ANCHORS)
+  for (const entry of pathEntriesForKind(kind)) {
+    const executable = PATH_EXECUTABLES[kind]
+    if (executable !== undefined) candidates.push(`${entry}\\${executable}`)
+  }
+  const system32File = SYSTEM32_FILES[kind]
+  if (system32File !== undefined) candidates.push(`${system32}\\${system32File}`)
+  return candidates
+}
+
+/**
+ * 解析一个 shell 条目的可执行路径:显式 path 原样信任;空 path 走候选探测。
+ * @param {{kind: string, path: string}} entry
+ * @param {(candidate: string) => boolean} exists 存在性判定(lstat 语义)
+ * @param {object} [env] 模拟进程环境,缺省用 process.env
+ * @returns {string|undefined} 无候选命中时 undefined
+ */
+export function resolveEntryPath(entry, exists, env = process.env) {
+  if (entry.path.length > 0) return entry.path
+  for (const candidate of candidatePaths(entry.kind, env)) {
+    if (exists(candidate)) return candidate
+  }
+  return undefined
+}
+
+/**
+ * 批量探测:给定 kind 集合,返回全部命中候选(保持 kind 顺序与候选顺序,
+ * 同路径去重)。
+ * @param {string[]} kinds
+ * @param {object} env
+ * @param {(candidate: string) => boolean} exists
+ * @returns {{kind: string, path: string}[]}
+ */
+export function detectCandidates(kinds, env, exists) {
+  const seen = new Set()
+  const found = []
+  for (const kind of kinds) {
+    for (const candidate of candidatePaths(kind, env)) {
+      if (seen.has(candidate)) continue
+      if (!exists(candidate)) continue
+      seen.add(candidate)
+      found.push({ kind, path: candidate })
+    }
+  }
+  return found
+}
+
+/** 生产存在性判定:官方 lstat 语义(isFile || isSymbolicLink,目录不匹配)。 */
+export function candidateExists(candidate) {
+  try {
+    const stat = lstatSync(candidate)
+    return stat.isFile() || stat.isSymbolicLink()
+  } catch {
+    return false
+  }
+}

package/src/sandbox-classify.mjs

@@ -0,0 +1,82 @@
+// 沙箱结果分类助手:官方 dsh-pwsh-sandbox helpers 逐项镜像(call-for-call),
+// 拒绝/runner 失败判据必须与官方执行器族完全一致,工具层的沙箱渲染才成立。
+
+import { accessSync, constants, statSync } from 'node:fs'
+
+// Node 本地 spawn 码中可证实 runner 可执行文件解析/权限失败的两类
+const EXECUTABLE_SPAWN_CODES = new Set(['EACCES', 'ENOENT'])
+
+/** 调用方 spawn cwd 可进入。 */
+export function isUsableWorkdir(path) {
+  try {
+    if (!statSync(path).isDirectory()) return false
+    accessSync(path, constants.X_OK)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * 仅在排除 cwd 因素后,凭 argv[0] 溯源把 ENOENT/EACCES 归为 runner 自身失败。
+ * @param {unknown} error spawn 拒绝原因
+ * @param {string|undefined} runnerProgram provider argv[0]
+ * @param {string} workdir 调用方 cwd
+ */
+export function isRunnerSpawnFailure(error, runnerProgram, workdir) {
+  if (runnerProgram === undefined || !isUsableWorkdir(workdir)) return false
+  if (typeof error !== 'object' || error === null) return false
+  const { code, path, syscall } = error
+  if (typeof code !== 'string' || !EXECUTABLE_SPAWN_CODES.has(code)) return false
+  if (typeof syscall !== 'string') return false
+  const exactSyscall = `spawn ${runnerProgram}`
+  if (path === undefined) return syscall === exactSyscall
+  if (typeof path !== 'string' || path.length === 0 || path !== runnerProgram) return false
+  return syscall === 'spawn' || syscall === exactSyscall
+}
+
+/**
+ * 按所选 runner 的拒绝方言分类失败运行。
+ * @param {{exitCode: number|null, stderr: {text: string}}} result
+ * @param {string[]} signatures 拒绝签名(大小写不敏感子串)
+ */
+export function classifyDenial(result, signatures) {
+  return matchesSignature(result.exitCode, result.stderr.text, signatures)
+}
+
+/**
+ * 结构化 runner 失败规则匹配:非零退出 + 可选允许码 + 例外信息行后的致命行。
+ * @param {number|null} exitCode
+ * @param {string} stderr
+ * @param {Array<{allowedExitCodes?: number[], informationalLines?: string[], fatalSignatures: string[]}>} rules
+ * @returns {{detail: string}|undefined}
+ */
+export function classifyRunnerFailure(exitCode, stderr, rules) {
+  if (exitCode === null || exitCode === 0) return undefined
+  const lines = stderr.split(/\r?\n/)
+  for (const rule of rules) {
+    if (rule.allowedExitCodes !== undefined && !rule.allowedExitCodes.includes(exitCode)) continue
+    const informationalLines = new Set((rule.informationalLines ?? []).map((line) => line.toLowerCase()))
+    const fatalSignatures = rule.fatalSignatures
+      .filter((signature) => signature.trim().length > 0)
+      .map((signature) => signature.toLowerCase())
+    for (const line of lines) {
+      const lowered = line.toLowerCase()
+      if (informationalLines.has(lowered)) continue
+      if (fatalSignatures.some((signature) => lowered.includes(signature))) return { detail: line }
+    }
+  }
+  return undefined
+}
+
+/**
+ * 非零退出 + stderr 命中任一签名(大小写不敏感)。
+ * @param {number|null} exitCode
+ * @param {string} stderr
+ * @param {string[]} signatures
+ */
+export function matchesSignature(exitCode, stderr, signatures) {
+  if (exitCode === null || exitCode === 0) return false
+  const lowered = stderr.toLowerCase()
+  return signatures.some((signature) => lowered.includes(signature.toLowerCase()))
+}