dsh-pwsh-plugin 0.2.17 → 0.2.19

package/plugin/index.mjs

@@ -2,9 +2,8 @@
  * pwsh-run —— 常驻 PowerShell 会话工具（插件行）
  *
  * 为什么需要它
- *   DSH 的 bash 工具把命令包成 /bin/bash -c "<cmd>" 再交给 shell，
- *   所以任何经过 bash 的 PowerShell 命令，$变量 会先被外层双引号展开、
- *   heredoc 也会在那一层失效（实测：pwsh -Command "Write-Output \"var=$abc\"" 输出 var=）。
+ *   把 PowerShell 再包进其它 shell 会增加一层变量与引号解析，
+ *   复杂脚本因此容易在送到 PowerShell 之前改变含义。
  *   原生 pwsh 工具本身不吃 $，但受 Windows 命令行长度限制（实测 32700 字符即 ENAMETOOLONG），
  *   且每次都是全新进程，变量 / 当前目录 / 已导入模块不跨调用保留。
  *
@@ -19,7 +18,7 @@
  *
  * 沙箱：常驻进程在**启动时**整体包进 ctx.sandbox.confine 返回的受限 argv，
  *   之后它的每一次读/写都受同一个 workspace 边界约束（ACL 受限令牌是进程级，
- *   不是逐命令级——这一点与原生工具等价，实测 workspace 外写入全部被拒）。
+ *   不是逐命令级；因此每次复用前核对策略、工作区与后端，变化就重建）。
  *   read-only 模式下 pwsh 以 ConstrainedLanguage 运行，无法构造 runspace，
  *   因此常驻会话在该模式下不启动，直接报错让模型改用原生 pwsh 工具。
  *   ctx.sandboxPolicy 缺席时同样拒绝启动（fail-closed），除非显式 config.allowUnconfined: true。
@@ -30,7 +29,9 @@
  */
 
 import { readFileSync } from 'node:fs'
-import { DEFAULT_MAX_OUTPUT_BYTES, bootArgv, startSession } from './session.mjs'
+export { Config } from './config.mjs'
+import { installNativePwshGuard } from './native-pwsh-guard.mjs'
+import { DEFAULT_MAX_OUTPUT_BYTES, MAX_TIMEOUT_MS, bootArgv, startSession, validateTimeout, abortable } from './session.mjs'
 
 /** 加载器诊断里显示的插件名。 */
 export const name = 'pwsh-run'
@@ -41,9 +42,6 @@ export const inject = ['subprocess', 'tools']
 const DEFAULT_TIMEOUT_MS = 120000
 const DEFAULT_IDLE_MS = 30 * 60 * 1000
 const DEFAULT_MAX_SESSIONS = 4
-/** 调用方超时之外多给的余量：服务端被打断后还要把尾部输出吐完、写结束标记。 */
-const RESPONSE_GRACE_MS = 5000
-
 /** 服务端脚本：随插件分发，启动时经 -EncodedCommand 送入，不落地临时文件。 */
 const SERVER_SOURCE = readFileSync(new URL('./session-server.ps1', import.meta.url), 'utf8')
 
@@ -59,7 +57,9 @@ const parameters = {
       description: 'Optional Windows working directory to Set-Location into before running (e.g. D:\\proj). It persists for later calls in the same session; an invalid path fails the call before the script runs.',
     },
     timeoutMs: {
-      type: 'number',
+      type: 'integer',
+      minimum: 1,
+      maximum: MAX_TIMEOUT_MS,
       description: 'Timeout for this call in milliseconds; defaults to 120000. On timeout the session process is terminated and rebuilt.',
     },
   },
@@ -69,32 +69,17 @@ const parameters = {
 
 /**
  * 解析子进程的启动目录。
- * 与 presets/shared/custom-bash.mjs 同款：workingDirectory 服务优先（会话中途切目录后
+ * 与 wsl/custom-bash.mjs 同款：workingDirectory 服务优先（会话中途切目录后
  * header.cwd 不会更新），服务缺失时退回 header.cwd，再退回进程 cwd。
  */
 async function resolveCwd(ctx, agent, signal) {
-  try {
-    const service = ctx.get('workingDirectory')
-    if (service !== undefined && agent !== undefined) return await service.ensure(agent, signal)
-  } catch {
-    // 服务异常时退回旧路径，不让一次目录查询拖垮工具调用。
-  }
+  const service = ctx.get('workingDirectory')
+  if (service !== undefined && agent !== undefined) return await service.ensure(agent, signal)
   const header = agent?.session?.header
   if (typeof header?.cwd === 'string' && header.cwd.length > 0) return header.cwd
   return process.cwd()
 }
 
-/**
- * 把一个字符串安全地拼进 PowerShell 源码。
- * 必须用单引号字面量：JSON 的双引号写法会被 PowerShell 当成可展开字符串，
- * 路径里一旦出现 $ 或反引号（如 D:\$Recycle.Bin）就会被解析掉，
- * 而且 JSON 会把反斜杠加倍成 \\，与 PowerShell 的转义规则并不一致。
- * PowerShell 单引号里唯一需要转义的字符是单引号本身（写成两个）。
- */
-function psLiteral(value) {
-  return "'" + String(value).replaceAll("'", "''") + "'"
-}
-
 /**
  * confine 失败时把原始 Win32 错误翻译成能照着做的说明。
  * 最常见的一种：工作区根的 DACL 没给 WRITE_DAC / WRITE_OWNER。沙箱要在目录上写 DACL 与
@@ -138,22 +123,19 @@ export function describeExecDenial(text) {
     + ' detaches the child std handles, so session corruption is prevented — the lost output is not.]'
 }
 
-/** 合并调用方取消信号与本地超时信号。 */
-function withTimeout(signal, timeoutMs) {
-  const timeout = AbortSignal.timeout(timeoutMs)
-  return signal === undefined ? timeout : AbortSignal.any([signal, timeout])
-}
-
 export function apply(ctx, config) {
   const pwshPath = typeof config?.pwshPath === 'string' && config.pwshPath.length > 0 ? config.pwshPath : 'pwsh'
-  const defaultTimeoutMs = Number.isSafeInteger(config?.timeoutMs) && config.timeoutMs > 0 ? config.timeoutMs : DEFAULT_TIMEOUT_MS
+  const defaultTimeoutMs = config?.timeoutMs === undefined ? DEFAULT_TIMEOUT_MS : validateTimeout(config.timeoutMs)
   const idleMs = Number.isSafeInteger(config?.idleMs) && config.idleMs > 0 ? config.idleMs : DEFAULT_IDLE_MS
   const maxSessions = Number.isSafeInteger(config?.maxSessions) && config.maxSessions > 0 ? config.maxSessions : DEFAULT_MAX_SESSIONS
-  const maxOutputBytes = Number.isSafeInteger(config?.maxOutputBytes) && config.maxOutputBytes > 0 ? config.maxOutputBytes : DEFAULT_MAX_OUTPUT_BYTES
+  const maxOutputBytes = config?.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES
+  if (!Number.isSafeInteger(maxOutputBytes) || maxOutputBytes < 1 || maxOutputBytes > 2147483647) {
+    throw new Error('pwsh_run maxOutputBytes must be an integer between 1 and 2147483647')
+  }
   // 明确放弃边界的唯一开关：策略服务缺席时默认拒绝启动，只有这里能改主意。
   const allowUnconfined = config?.allowUnconfined === true
 
-  // 沙箱服务每次启动会话时再取：插件 apply 可能早于沙箱服务挂载，
+  // 每次调用都重新取沙箱服务；apply 可能早于服务挂载，后端也可能热替换。
   // 而沙箱缺席时插件仍需能加载（启动会话时给出明确错误即可）。
   // 入参是 Agent（不是 ToolExecution）：sandboxPolicy.resolve 需要 session 才能读到
   // 会话的 sandbox/mode 覆盖与 header.cwd。传错形状会静默退回部署默认值
@@ -165,189 +147,177 @@ export function apply(ctx, config) {
     return sandboxPolicy.resolve(session === undefined ? {} : { session })
   }
 
-  /** sessionId -> Promise<PwshSession>。用 Promise 占位，避免并发首调用各起一个进程。 */
-  const sessions = new Map()
+  installNativePwshGuard(ctx, config?.enforcePwshRun, resolvePolicy)
+  // 页面复用 settings 服务的持久化与 revision 校验，不创建额外的配置文件。
+  ctx.inject?.(['settings'], (child) => {
+    child.effect(() => child.settings.configure({ auto: false }, ctx.fiber), 'pwsh-run.settings-page')
+  })
 
-  const sessionKey = (exec) => {
-    const id = exec?.agent?.session?.id
-    return typeof id === 'string' && id.length > 0 ? id : 'default'
-  }
+  // 槽位在第一次 await 前登记；同 ID 的创建、边界切换与执行共用队列。
+  const sessions = new Map()
+  let stopped = false
+  const fingerprint = (value) => JSON.stringify(value, (_key, item) => {
+    if (item && typeof item === 'object' && !Array.isArray(item)) {
+      return Object.fromEntries(Object.keys(item).sort().map((key) => [key, item[key]]))
+    }
+    return item
+  })
 
-  const evict = async (key, session) => {
-    sessions.delete(key)
-    if (session !== undefined && session !== null) await session.dispose()
+  const evict = async (slot, session, reason) => {
+    if (slot.session === session) slot.session = null
+    if (session) await session.dispose(reason)
   }
 
-  /** 取一个活着的会话，必要时新建；超出上限淘汰最久未用的。 */
-  const acquire = async (key, workdir, agent, signal) => {
-    const existing = sessions.get(key)
-    if (existing !== undefined) {
-      let session = null
-      try {
-        session = await existing
-      } catch {
-        sessions.delete(key)
-      }
-      if (session !== null && !session.dead) {
-        session.lastUsed = Date.now()
-        return session
-      }
-      if (session !== null) await session.dispose()
-      sessions.delete(key)
+  const acquire = async (slot, workdir, agent, signal) => {
+    if (signal?.aborted) throw new Error('pwsh_run cancelled before execution')
+    const cwd = await resolveCwd(ctx, agent, signal)
+    const policy = resolvePolicy(agent) ?? null
+    if (signal?.aborted) throw new Error('pwsh_run cancelled before execution')
+    if (stopped) throw new Error('pwsh_run plugin was stopped')
+    const sandbox = ctx.get('sandbox')
+    const identity = fingerprint({ policy, cwd })
+    if (slot.session && (slot.identity !== identity || slot.sandbox !== sandbox || slot.session.dead)) {
+      await evict(slot, slot.session, 'pwsh session boundary changed')
     }
+    if (policy === null && !allowUnconfined) {
+      throw new Error('pwsh_run: ctx.sandboxPolicy is absent, so the workspace boundary cannot be resolved. '
+        + 'Mount @deepseek-ai/dsh-sandbox-policy, or set config.allowUnconfined: true to accept an unconfined session.')
+    }
+    if (policy?.mode === 'read-only') {
+      throw new Error('pwsh_run does not support read-only mode: a persistent pwsh session needs FullLanguage. Use the native pwsh tool instead.')
+    }
+    if (policy !== null && !['workspace-write', 'danger-full-access'].includes(policy.mode)) {
+      throw new Error('pwsh_run: unsupported sandbox mode ' + policy.mode)
+    }
+    if (slot.session) return slot.session
 
-    const cwd = workdir ?? await resolveCwd(ctx, agent, signal)
-    const pending = (async () => {
-      const executable = await ctx.subprocess.resolveExecutable(pwshPath, undefined, signal)
-      // 常驻进程只在启动时能 confine 一次——但 ACL 受限令牌是**进程级**的，
-      // 之后该进程所有读写都受同一 workspace 边界约束，与原生 pwsh 工具等价（实测）。
-      const policy = resolvePolicy(agent)
-      const boot = bootArgv(SERVER_SOURCE)
-      const plain = [executable].concat(boot)
-      // fail-closed：解析不出边界就拒绝启动，而不是悄悄跑一个不受约束的会话。
-      if (policy === null && allowUnconfined !== true) {
-        throw new Error('pwsh_run: ctx.sandboxPolicy is absent, so the workspace boundary cannot be resolved. ' +
-          'Mount @deepseek-ai/dsh-sandbox-policy, or set config.allowUnconfined: true to accept an unconfined session ' +
-          '(file writes would then NOT be restricted to the workspace).')
-      }
-      if (policy === null || policy.mode === 'danger-full-access') {
-        return await startSession(ctx.subprocess, { executable, cwd, serverSource: SERVER_SOURCE, label: key, maxOutputBytes })
-      }
-      // read-only 下 pwsh 是 ConstrainedLanguage，连 runspace 都建不起来（实测
-      // [Text.UTF8Encoding]::new 即报 "Cannot create type"），常驻会话没法启动。
-      if (policy.mode === 'read-only') {
-        throw new Error('pwsh_run does not support read-only mode: a persistent pwsh session needs FullLanguage ' +
-          '(a read-only sandbox runs pwsh in ConstrainedLanguage, where creating a runspace fails). Use the native pwsh tool instead.')
-      }
-      const sandbox = ctx.get('sandbox')
-      if (sandbox === undefined) throw new Error('pwsh_run: ctx.sandbox is absent, so a persistent session cannot be confined. Mount @deepseek-ai/dsh-sandbox-local, or use the native pwsh tool.')
-      let confined
-      try {
-        confined = await sandbox.confine(plain, policy, signal)
-      } catch (error) {
-        throw new Error(describeConfineFailure(error, policy.workspaceRoot))
-      }
-      return await startSession(ctx.subprocess, { executable, argv: confined.argv, cwd, serverSource: SERVER_SOURCE, label: key, maxOutputBytes })
-    })()
-    pending.catch(() => sessions.delete(key))
-    sessions.set(key, pending)
-
-    if (sessions.size > maxSessions) {
-      const others = [...sessions.entries()].filter(([victim]) => victim !== key)
-      const ages = []
-      for (const entry of others) {
-        let lastUsed = 0
+    const live = [...sessions.values()].filter((item) => item.session || item.starting)
+    let retiring
+    if (live.length >= maxSessions) {
+      const victim = live.filter((item) => item !== slot && item.users === 0 && !item.starting)
+        .sort((a, b) => a.session.lastUsed - b.session.lastUsed)[0]
+      if (!victim) throw new Error('pwsh_run: all ' + maxSessions + ' sessions are busy; retry when a call finishes')
+      retiring = evict(victim, victim.session, 'pwsh session evicted while idle')
+      if (sessions.get(victim.key) === victim) sessions.delete(victim.key)
+    }
+    // 在等待旧进程退出前占住容量，另一 ID 不能同时认领最后一个位置。
+    slot.starting = true
+    slot.startup = new AbortController()
+    const startupSignal = signal ? AbortSignal.any([signal, slot.startup.signal]) : slot.startup.signal
+    try {
+      await retiring
+      if (stopped || startupSignal.aborted) throw new Error('pwsh_run session startup cancelled')
+      const executable = await ctx.subprocess.resolveExecutable(pwshPath, undefined, startupSignal)
+      let argv
+      if (policy !== null && policy.mode !== 'danger-full-access') {
+        if (!sandbox) throw new Error('pwsh_run: ctx.sandbox is absent, so a persistent session cannot be confined. Mount @deepseek-ai/dsh-sandbox-local, or use the native pwsh tool.')
         try {
-          lastUsed = (await entry[1]).lastUsed
-        } catch {
-          lastUsed = 0
+          const confined = await sandbox.confine([executable, ...bootArgv(SERVER_SOURCE)], policy, startupSignal)
+          argv = confined?.argv
+          if (!Array.isArray(argv) || argv.length === 0 || argv.some((item) => typeof item !== 'string')) {
+            throw new Error('sandbox.confine returned no valid confined argv')
+          }
         }
-        ages.push([entry[0], entry[1], lastUsed])
+        catch (error) { throw new Error(describeConfineFailure(error, policy.workspaceRoot)) }
       }
-      ages.sort((a, b) => a[2] - b[2])
-      for (const [victimKey, victim] of ages.slice(0, Math.max(0, sessions.size - maxSessions))) {
-        sessions.delete(victimKey)
-        Promise.resolve(victim).then((session) => session.dispose(), () => undefined)
+      const session = await startSession(ctx.subprocess, { executable, argv, cwd: workdir ?? cwd,
+        serverSource: SERVER_SOURCE, label: slot.key, maxOutputBytes, signal: startupSignal })
+      if (stopped || startupSignal.aborted) {
+        await session.dispose('pwsh session startup cancelled')
+        throw new Error('pwsh_run session startup cancelled')
       }
-    }
-    return await pending
+      slot.session = session
+      slot.identity = identity
+      slot.sandbox = sandbox
+      return session
+    } finally { slot.starting = false; slot.startup = null }
   }
 
-  // 空闲会话回收，避免常驻进程无限累积。
   const reaper = setInterval(() => {
     const now = Date.now()
-    for (const [key, pending] of [...sessions.entries()]) {
-      Promise.resolve(pending).then(async (session) => {
-        if (now - session.lastUsed > idleMs) await evict(key, session)
-      }, () => sessions.delete(key))
+    for (const [key, slot] of sessions) {
+      if (slot.users === 0 && !slot.starting && slot.session && now - slot.session.lastUsed > idleMs) {
+        const retiring = evict(slot, slot.session, 'pwsh session expired while idle')
+        if (sessions.get(key) === slot) sessions.delete(key)
+        void retiring
+      }
     }
   }, Math.min(idleMs, 60000))
-  if (typeof reaper.unref === 'function') reaper.unref()
+  reaper.unref?.()
 
-  /** 插件卸载 / 热重载时清干净：停回收器 + 杀掉所有会话。 */
   ctx.effect(() => () => {
+    stopped = true
     clearInterval(reaper)
-    for (const pending of sessions.values()) Promise.resolve(pending).then((session) => session.dispose(), () => undefined)
+    for (const slot of sessions.values()) {
+      slot.startup?.abort()
+      if (slot.session) void slot.session.dispose('pwsh_run plugin stopped')
+    }
     sessions.clear()
   }, 'pwsh-run.sessions')
 
-
-  /** 一条调用的实体。 */
-  const runScript = async (args, exec) => {
-    const requested = Number.isFinite(args?.timeoutMs) && args.timeoutMs > 0 ? Math.trunc(args.timeoutMs) : defaultTimeoutMs
-    const key = sessionKey(exec)
-    const workdir = typeof args?.workdir === 'string' && args.workdir.length > 0 ? args.workdir : undefined
-
-    // workdir 通过 Set-Location 生效（会话有状态，所以下一次调用会继承）。
-    const script = workdir === undefined
-      ? args.script
-      : 'Set-Location -LiteralPath ' + psLiteral(workdir) + " -ErrorAction Stop\n" + args.script
-
+  const runScript = async (args, exec, slot) => {
+    const requested = args.timeoutMs ?? defaultTimeoutMs
+    const workdir = typeof args.workdir === 'string' && args.workdir.length > 0 ? args.workdir : undefined
+    // 工作目录用 API 设置，避免在正文前拼语句破坏 using / param / #requires。
     let session
-    try {
-      session = await acquire(key, workdir, exec?.agent, exec?.signal)
-    } catch (error) {
-      // acquire 里已经写好人话的错误（沙箱缺席、read-only、confine 失败）不再套第二层前缀。
-      // 用 \b 而不是 'pwsh_run '：几条自带文案是 'pwsh_run: ...' 冒号收尾，带空格的匹配会漏掉它们。
+    try { session = await acquire(slot, workdir, exec?.agent, exec?.signal) }
+    catch (error) {
       const message = String(error?.message ?? error)
       throw new Error(/^pwsh_run\b/.test(message) ? message : 'pwsh_run could not start a session: ' + message)
     }
-
-    const local = withTimeout(exec?.signal, requested + RESPONSE_GRACE_MS)
-    let expired = false
-    const onAbort = () => { expired = true }
-    local.addEventListener('abort', onAbort, { once: true })
-
-    let response = null
-    try {
-      response = await Promise.race([
-        session.run(script, requested),
-        new Promise((resolve) => {
-          local.addEventListener('abort', () => resolve(null), { once: true })
-        }),
-      ])
-    } catch (error) {
-      // 会话中途死亡：清掉，下一次调用自动重建。
-      await evict(key, session)
-      const message = String(error)
-      const note = session.dead ? '[' + message + '; a new session starts on the next call]' : '[' + message + ']'
-      return { text: note }
-    } finally {
-      local.removeEventListener('abort', onAbort)
+    let response
+    try { response = await session.run(args.script, requested, { signal: exec?.signal, workdir }) }
+    catch (error) {
+      await evict(slot, session, 'pwsh session execution failed')
+      return { text: exec?.signal?.aborted
+        ? '[cancelled; the session was terminated and is rebuilt on the next call]'
+        : '[' + String(error) + '; a new session starts on the next call]' }
     }
-
     const notes = []
-    if (response?.truncated === true) notes.push('[output truncated at ' + String(maxOutputBytes) + ' bytes; redirect to a file if you need it all]')
-    if (response === null || expired) {
-      // 服务端没能在预算内回话：整个进程杀掉重建，不让一条调用拖垮后续。
-      await evict(key, session)
-      notes.push(exec?.signal?.aborted === true
-        ? '[cancelled; the session was terminated and is rebuilt on the next call]'
-        : '[no response from the pwsh session within ' + String(Math.round(requested / 1000)) + 's; the session was terminated and is rebuilt on the next call]')
-    } else if (session.dead) {
-      await evict(key, session)
-      notes.push('[' + String(session.deathReason) + '; a new session starts on the next call]')
-    } else if (response.timedOut) {
-      // 服务端 Stop() 能打断脚本，但脚本内 Start-Process 起的子进程不会随之回收
-      // （实测子进程仍存活）。杀掉整个会话才能靠 Job Object 连带清干净。
-      await evict(key, session)
-      notes.push('[timed out after ' + String(Math.round(requested / 1000)) + 's; partial output above; the session was terminated and is rebuilt on the next call]')
+    if (response.truncated) notes.push('[output truncated at ' + maxOutputBytes + ' output bytes plus a separate 65536-byte error budget; redirect to a file if you need it all]')
+    if (response.cancelled || response.noResponse || response.timedOut || session.dead) {
+      await evict(slot, session)
+      if (response.cancelled) notes.push('[cancelled; the session was terminated and is rebuilt on the next call]')
+      else if (response.timedOut) notes.push('[timed out after ' + requested + 'ms; partial output above; the session was terminated and is rebuilt on the next call]')
+      else notes.push('[no response from the pwsh session within ' + requested + 'ms; the session was terminated and is rebuilt on the next call]')
     }
-
-    const body = []
-    for (const line of response?.out ?? []) body.push(line)
-    for (const line of response?.warn ?? []) body.push('WARNING: ' + line)
-    for (const line of response?.verbose ?? []) body.push('VERBOSE: ' + line)
-    if (response?.sentinel === 'threw') body.push('[script threw]')
-    const text = [body.join('\n')]
-      .concat(response?.err ?? [])
-      .concat(response?.exceptions ?? [])
-      .concat(response?.fatal ?? [])
-      .join('\n')
+    const body = [...response.out,
+      ...response.warn.map((line) => 'WARNING: ' + line),
+      ...response.verbose.map((line) => 'VERBOSE: ' + line),
+      ...response.information.map((line) => 'INFORMATION: ' + line),
+      ...response.debug.map((line) => 'DEBUG: ' + line)]
+    if (response.sentinel === 'threw') body.push('[script threw]')
+    const text = [...body, ...response.err, ...response.exceptions, ...response.fatal].join('\n')
     const denial = describeExecDenial(text)
     if (denial !== null) notes.push(denial)
-    const all = [text].concat(notes).filter((part) => part.length > 0).join('\n')
-    return { text: all.length > 0 ? all : '(no output)' }
+    return { text: [text, ...notes].filter(Boolean).join('\n') || '(no output)' }
+  }
+
+  const enqueue = (args, exec) => {
+    validateTimeout(args?.timeoutMs ?? defaultTimeoutMs)
+    if (typeof args?.script !== 'string') throw new Error('pwsh_run script must be a string')
+    if (exec?.signal?.aborted) throw new Error('pwsh_run cancelled before execution')
+    const key = exec?.agent?.session?.id
+    if (typeof key !== 'string' || !key) throw new Error('pwsh_run requires a session ID to isolate persistent state')
+    let slot = sessions.get(key)
+    if (!slot) {
+      slot = { key, tail: Promise.resolve(), session: null, users: 0, starting: false }
+      sessions.set(key, slot)
+    }
+    slot.users++
+    let executing = false
+    const operation = slot.tail.then(() => {
+      executing = true
+      if (exec?.signal?.aborted) throw new Error('pwsh_run cancelled before execution')
+      if (stopped) throw new Error('pwsh_run plugin was stopped')
+      return runScript(args, exec, slot)
+    }).finally(() => {
+      slot.users--
+      if (slot.session) slot.session.lastUsed = Date.now()
+      if (!slot.session && slot.users === 0 && sessions.get(key) === slot) sessions.delete(key)
+    })
+    slot.tail = operation.then(() => undefined, () => undefined)
+    return abortable(operation, exec?.signal, () => !executing)
   }
 
   // 工具注册也要挂到 effect 上：live patchReload 会重新 apply 本模块，
@@ -358,9 +328,9 @@ export function apply(ctx, config) {
       'Run a PowerShell script in a **persistent** pwsh 7 session.',
       '* Send the script body verbatim: do NOT escape $, do NOT wrap it in pwsh -c, do NOT add shell quotes. There is no shell in between — the script goes straight to pwsh over stdin.',
       '* Prefer this over the pwsh tool when the script contains $variables, here-strings (@\'...\'@ / @"..."@), backticks, quotes, non-ASCII text, or is longer than a few thousand characters. The pwsh tool is capped by the Windows command line (~32K) and every call is a fresh process.',
-      '* State persists across calls in the same session: variables, current directory, $env: entries and imported modules. Do not assume a clean slate; reset explicitly when you need to.',
-      '* Output ordering is preserved and streams are labelled (stdout / error / warning / verbose).',
-      '* Each call times out after ' + String(Math.round(defaultTimeoutMs / 1000)) + 's by default (override with timeoutMs). On timeout the whole session process is terminated and rebuilt — persisted state is lost.',
+      '* State persists while the session ID, sandbox policy and workspace stay the same: variables, current directory, $env: entries and imported modules. Do not assume a clean slate; reset explicitly when you need to.',
+      '* Output uses PowerShell formatting; streams are labelled and grouped by type, so inter-stream ordering is not preserved.',
+      '* Execution time excludes queue waiting. Each call times out after ' + String(Math.round(defaultTimeoutMs / 1000)) + 's by default (override with timeoutMs). On timeout the whole session process is terminated and rebuilt — persisted state is lost.',
       '* exit N inside the script only ends that call; its exit code is NOT observable. Use $LASTEXITCODE or Write-Output instead.',
       '* Sandbox: the persistent process is confined once at launch, and because the Windows ACL restricted token applies to the whole process, every later read/write in this session obeys the same workspace boundary as the native pwsh tool. In read-only mode this tool refuses to start (a persistent session needs FullLanguage) — use the native pwsh tool there.',
       '* Not for interactive programs or anything that needs a TTY.',
@@ -376,7 +346,7 @@ export function apply(ctx, config) {
       render: (_args, value) => [{ type: 'text', text: value.text }],
     },
     async execute(args, exec) {
-      return await runScript(args, exec)
+      return await enqueue(args, exec)
     },
   }), 'pwsh-run.tool')
-}
+}

package/plugin/native-pwsh-guard.mjs

@@ -0,0 +1,43 @@
+const MODE_RANK = new Map([
+  ['read-only', 0], ['workspace-write', 1], ['danger-full-access', 2],
+])
+
+const DENIAL = 'Ordinary native pwsh calls are disabled by config.enforcePwshRun. '
+  + 'Use pwsh_run instead: pass the PowerShell command as script, and keep workdir and timeoutMs when supplied. '
+  + 'The native command was not executed.'
+
+/** 守卫在宿主执行前策略之后检查；不用可被后续监听器改回 allow 的瀑布钩子。 */
+export function installNativePwshGuard(ctx, enabled, resolvePolicy) {
+  const live = enabled !== null && typeof enabled === 'object' && typeof enabled.get === 'function'
+  const readEnabled = () => {
+    const value = live ? enabled.get() : enabled
+    if (value !== undefined && typeof value !== 'boolean') {
+      throw new Error('pwsh_run enforcePwshRun must be a boolean')
+    }
+    return value === true
+  }
+  const initial = readEnabled()
+  if (!live && !initial) return
+  if (typeof ctx.tools.guard !== 'function') {
+    throw new Error('pwsh_run enforcePwshRun requires a DSH host with tools.guard(); '
+      + 'upgrade DSH to use this routing configuration. No routing guard was installed.')
+  }
+
+  ctx.effect(() => ctx.tools.guard((exec) => {
+    // Loader 原地更新 volatile 引用；读取它不会销毁正在使用的常驻进程。
+    if (exec.name !== 'pwsh' || !readEnabled()) return undefined
+    // 后台 job 的句柄与逐次审批由原生工具持有，常驻会话不能代接。
+    const args = exec.arguments
+    if (args?.run_in_background === true) return undefined
+    const mode = resolvePolicy(exec.agent)?.mode
+    if (mode === 'read-only') return undefined
+    const requestedRank = MODE_RANK.get(args?.sandbox_permissions)
+    const currentRank = MODE_RANK.get(mode)
+    if (requestedRank !== undefined && currentRank !== undefined && requestedRank > currentRank
+      && typeof args?.justification === 'string' && args.justification.trim().length > 0) {
+      // 只放行真实的提权请求；是否批准仍由原生工具的审批机制决定。
+      return undefined
+    }
+    return DENIAL
+  }), 'pwsh-run.native-guard')
+}