dsh-pwsh-plugin 0.2.17 → 0.2.18

package/docs/runtime-notes.md

@@ -6,28 +6,32 @@ Implementation details and historical measurements follow. Behavior depends on t
 
 ## Known limits
 
-- **`read-only` mode is unsupported** (see above); use the built-in `pwsh` tool there.
+- **`read-only` mode is unsupported**; use the built-in `pwsh` tool there.
 - **Refuses to start when the sandbox policy service is absent**, unless `allowUnconfined: true`.
 - **A timeout kills the whole session** (and reaps its child process tree). State is lost; the next call
   rebuilds automatically.
 - **`exit N` exit codes are not observable** (runspace semantics).
-- **stdout / stderr interleaving is not preserved** — everything goes through `*>&1` and is tagged by type.
-- **`[Console]::Error.WriteLine` is swallowed** (the server points `Console.Error` at an in-memory stream so
-  the protocol cannot be polluted). A child process's stderr, `Write-Error` and `throw` all come back fine.
-- **Child std handles are detached from the protocol.** `Console::SetIn/SetOut` only changes the .NET layer, so
-  the server also rewrites the three Win32 slots: stdin goes to `NUL`, stdout and stderr go to a
-  `FILE_FLAG_DELETE_ON_CLOSE` temp file truncated before every call. A grandchild that writes to inherited
-  stdout can no longer inject a fake protocol line (measured: one `Write-Output '<<<BYE>>>'` from a child used
-  to kill the session), and one that reads inherited stdin gets EOF instead of the caller's request.
-  The replacement handles are created **inheritable** (`SECURITY_ATTRIBUTES.bInheritHandle`): a handle made with
-  a `NULL` security descriptor only exists in this process, so a child that trusts `STARTUPINFO.hStdInput`
-  receives a bare handle *number* that means nothing over there — `GetFileType` reports `UNKNOWN`, and once in
-  a few dozen launches that number is recycled by an unrelated object and the read returns its bytes.
-  stdout deliberately does **not** go to `NUL`: that is a character device, PowerShell then believes its output
-  is not redirected and the sandbox denial changes into a useless `StandardOutputEncoding` message.
-  If the temp directory is unwritable it falls back to `NUL` and says so once, in a warning on the first call.
-- **A session is serial**: concurrent calls queue up and run one at a time (no interleaved output, but no
-  parallel speedup either).
+- **stdout / stderr interleaving is not preserved** — streams are collected separately and grouped by type.
+- **Direct Console output is discarded.** `Console.Out` and `Console.Error` use null writers rather than
+  retained memory streams. On Windows, inheritable `NUL` handles replace stdin/stdout/stderr so a child
+  cannot read requests or inject protocol lines. PowerShell-captured native output, `Write-Error` and
+  `throw` still return; launches that directly inherit the detached handles lose their output.
+  Handle-detachment failure refuses startup. `NUL` can change native-launch denial wording, not permissions.
+- **A session is serial**: creation and execution share one queue per DSH ID. The execution timeout
+  excludes queue waiting. Cancelling a queued request affects only itself; active cancellation kills its process.
+- **Reuse rechecks boundaries**: changes to effective policy, workspace or sandbox backend rebuild the
+  process. A missing session ID is rejected instead of sharing a default process.
+- **Pool pressure and idle expiry never evict busy sessions.** A full busy pool refuses new sessions
+  with a retry message. Idle age starts after the last call completes.
+- **UTF-8 payload budgets are enforced on both sides.** Ordinary streams share `maxOutputBytes`; errors
+  retain a separate 64KiB budget, including record separators. Consumed records and undisplayed progress
+  records are drained immediately. Frames are size-limited; display prefixes are outside the payload budget.
+- **Top-level syntax is retained.** Workdir uses a separate API call and objects use
+  `Out-String -Stream -Width 200`. `#requires` checks version, PSEdition, modules and administrator identity
+  before the body; `-ShellId` / `-Assembly` are explicitly refused. Administrator group membership alone
+  does not prove the process is unconfined.
+- **Startup failure cleans up and returns the stderr tail.** Handshake warnings appear once on the first
+  user call. The gzip bootstrap must remain within the encoded Windows command-line budget or startup is refused.
 - **No WSL is required.** `pwsh_run` never touches WSL; only `wsl/custom-bash.mjs` does. Without a usable
   `bashPath`, applying that preset still succeeds (the executable is resolved lazily) and the `bash` tool
   fails per call with `command "<path>" is not an executable file` — a clear failure, not a silent
@@ -54,4 +58,4 @@ Implementation details and historical measurements follow. Behavior depends on t
 
   Nothing asks whether a call is in flight. The host performs the update; this plugin does not get a say and
   does not gate it. The version is worth more than the session state, but it is not "nothing happened" — do
-  not hold unrecoverable state in a session across an upgrade.
+  not hold unrecoverable state in a session across an upgrade.

package/docs/runtime-notes.zh-CN.md

@@ -6,23 +6,25 @@
 
 ## 已知边界
 
-- **不支持 `read-only` 模式**（见上），用内置 `pwsh`。
+- **不支持 `read-only` 模式**，用内置 `pwsh`。
 - **沙箱策略服务缺席时拒绝启动**，除非 `allowUnconfined: true`。
 - **超时会杀掉整个会话**（连带回收子进程树）。状态丢失，下次调用自动重建。
 - **`exit N` 的退出码不可观测**（runspace 语义）。
-- **stdout / stderr 的逐行时序不保留** —— 全部流经 `*>&1` 合并后按类型打标。
-- **`[Console]::Error.WriteLine` 会被吞掉**（服务端为防协议污染把 `Console.Error` 指向内存流）。
-  子进程的 stderr、`Write-Error`、`throw` 都正常回来。
-- **子进程的 std handle 已与协议流断开。** `Console::SetIn/SetOut` 只改 .NET 层，服务端还改写了三个 Win32 槽位：
-  stdin 接 `NUL`，stdout / stderr 接一个带 `FILE_FLAG_DELETE_ON_CLOSE` 的临时文件、每次调用前截回零。
-  于是子进程往继承来的 stdout 写东西不会再伪造出协议行（实测：子进程一句 `Write-Output '<<<BYE>>>'`
-  曾让会话当场死亡），读继承来的 stdin 也只会读到 EOF，而不是调用方的请求。
-  替上去的句柄必须是**可继承**的（`SECURITY_ATTRIBUTES.bInheritHandle`）：用 `NULL` 安全描述符建的句柄
-  只存在于本进程，子进程按 `STARTUPINFO.hStdInput` 拿到的只是一个在那边没有意义的句柄**编号** ——
-  `GetFileType` 报 `UNKNOWN`，几十次里还有一次那个编号被别的对象复用，读出来是别人的字节。
-  stdout **故意不接 `NUL`**：那是字符设备，PowerShell 会认为输出没被重定向，沙箱拒绝的报错会变成一句
-  没用的 `StandardOutputEncoding` 提示。临时目录不可写时退回 `NUL`，并在第一次调用的警告里说明一次。
-- **会话是串行的**：并发调用排成队列逐个执行（不会串输出，但也没有并行加速）。
+- **stdout / stderr 的逐行时序不保留** —— 流分别收集，最终按类型分组。
+- **直接 Console 输出会被丢弃**：`Console.Out` / `Console.Error` 使用空输出流，不再积存在内存里。
+  Windows 的继承 stdin/stdout/stderr 接可继承的 `NUL` 句柄；子进程不能读请求或向协议注入假行。
+  PowerShell 正常捕获的原生输出、`Write-Error`、`throw` 仍返回；主动绕过 PowerShell 捕获而继承句柄的输出会丢失。
+  句柄隔离失败时拒绝启动，不允许降级继续。`NUL` 可能改变原生启动被拒时的文案，不改变权限边界。
+- **会话是串行的**：同一 DSH ID 的创建与执行共用队列。超时从实际发送开始计；排队取消只取消自身，执行中取消才终止进程。
+- **复用前重新核对边界**：有效策略、工作区或沙箱后端变化后重建。缺少 session ID 会拒绝，不能共享默认状态。
+- **忙会话不会因池满或空闲计时被淘汰**：满池全忙时新调用收到重试说明；完成调用后才计算闲置。
+- **输出正文按 UTF-8 字节限制**：普通流共用 `maxOutputBytes`，错误另留 64KiB，记录换行也计数。
+  服务端立即移除消费过的记录；进度记录不显示且及时清空。单帧有长度限制，显示前缀不计入正文预算。
+- **脚本顶层语义保留**：正文单独执行，工作目录通过 API 设置；对象走 `Out-String -Stream -Width 200`。
+  `#requires` 的版本、PSEdition、模块和管理员身份会在正文前核验；`-ShellId` / `-Assembly` 明确拒绝。
+  管理员身份检查依据当前令牌的有效组身份，不能据此判断沙箱是否存在。
+- **启动失败会清理子进程并带回 stderr 尾部**；握手警告在第一条用户调用显示一次。启动器采用 gzip 压缩，
+  编码后仍须在 Windows 命令行预算以内，否则启动前明确拒绝。
 - **不依赖 WSL。** `pwsh_run` 全程不碰 WSL，只有 `wsl/custom-bash.mjs` 才碰。没有可用的 `bashPath` 时，
   该预设照样加载成功（可执行文件是惰性解析的），`bash` 工具每次调用报
   `command "<路径>" is not an executable file` —— 清晰失败，不会静默降级。默认值是裸名 `bash`；
@@ -42,4 +44,4 @@
   v0.2.3 → v0.2.4 的一次安装：`$PID` 由 24820 变成 15632，安装前设的 `$global:` 变量读回来是空的。
 
   这里没有人问「现在有没有调用在跑」。更新是宿主执行的，本插件既不参与也不设闸门。版本比会话状态值钱，
-  但这并不等于「什么都没发生」—— 别把不可重建的状态放在里面跨过升级。
+  但这并不等于「什么都没发生」—— 别把不可重建的状态放在里面跨过升级。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-pwsh-plugin",
-  "version": "0.2.17",
+  "version": "0.2.18",
   "type": "module",
   "description": "Persistent pwsh session tool (pwsh_run) for DeepSeek Harness: run PowerShell scripts with zero escaping, no 32K command-line cap, and state that survives across calls.",
   "icon": "./icon.svg",
@@ -51,7 +51,7 @@
     "@deepseek-ai/dsh": ">=0.2.0-rc.2 <0.3.0"
   },
   "scripts": {
-    "test": "node test/itest.mjs && node test/plugintest.mjs && node test/denialtest.mjs && node test/metatest.mjs",
-    "test:all": "node test/itest.mjs && node test/plugintest.mjs && node test/e2e-real-subprocess.mjs && node test/sandboxtest.mjs && node test/bashtest.mjs && node test/bash-e2e.mjs && node test/denialtest.mjs && node test/metatest.mjs"
+    "test": "node test/protocoltest.mjs && node test/lifecycletest.mjs && node test/itest.mjs && node test/plugintest.mjs && node test/denialtest.mjs && node test/metatest.mjs",
+    "test:all": "node test/protocoltest.mjs && node test/lifecycletest.mjs && node test/itest.mjs && node test/plugintest.mjs && node test/e2e-real-subprocess.mjs && node test/sandboxtest.mjs && node test/bashtest.mjs && node test/bash-e2e.mjs && node test/denialtest.mjs && node test/metatest.mjs"
   }
 }

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,7 @@
  */
 
 import { readFileSync } from 'node:fs'
-import { DEFAULT_MAX_OUTPUT_BYTES, bootArgv, startSession } from './session.mjs'
+import { DEFAULT_MAX_OUTPUT_BYTES, MAX_TIMEOUT_MS, bootArgv, startSession, validateTimeout, abortable } from './session.mjs'
 
 /** 加载器诊断里显示的插件名。 */
 export const name = 'pwsh-run'
@@ -41,9 +40,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 +55,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 +67,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 +121,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 +145,171 @@ export function apply(ctx, config) {
     return sandboxPolicy.resolve(session === undefined ? {} : { session })
   }
 
-  /** sessionId -> Promise<PwshSession>。用 Promise 占位，避免并发首调用各起一个进程。 */
+  // 槽位在第一次 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 sessionKey = (exec) => {
-    const id = exec?.agent?.session?.id
-    return typeof id === 'string' && id.length > 0 ? id : 'default'
-  }
-
-  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 +320,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 +338,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')
-}
+}