Merge remote-tracking branch 'origin/master' into codex/localized-chinese-doc-links

# Conflicts: # .agents/notes/implemented/architecture/2026-06-11-content-block-vocabulary.i18n.yaml # .agents/notes/implemented/architecture/2026-06-11-content-block-vocabulary.zh.md # .agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.i18n.yaml # .agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml # .agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md # .agents/notes/implemented/bug-fix/2026-07-29-pnpm-setup-runner-isolation.i18n.yaml # .agents/notes/implemented/bug-fix/2026-07-29-pnpm-setup-runner-isolation.zh.md # .agents/notes/implemented/bug-fix/2026-08-18-request-image-payload-bound.i18n.yaml # .agents/notes/implemented/bug-fix/2026-08-18-request-image-payload-bound.zh.md # .agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml # .agents/notes/implemented/feature/2026-07-06-sandbox.zh.md # .agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.i18n.yaml # .agents/notes/implemented/feature/2026-07-21-cross-session-references.i18n.yaml # .agents/notes/implemented/feature/2026-07-21-cross-session-references.zh.md # .agents/notes/implemented/feature/2026-07-22-web-multimodal-image-input-and-durable-attachments.i18n.yaml # .agents/notes/implemented/feature/2026-07-22-web-multimodal-image-input-and-durable-attachments.zh.md # .agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml # .agents/notes/implemented/feature/2026-07-31-permission-default-for-new-sessions.i18n.yaml # .agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.i18n.yaml # .agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.zh.md # .agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.i18n.yaml # .agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.zh.md # .agents/notes/implemented/feature/2026-08-05-agent-teams.i18n.yaml # .agents/notes/implemented/feature/2026-08-05-agent-teams.zh.md # .agents/notes/implemented/feature/2026-08-11-workspace-sidebar-order-and-folding.i18n.yaml # .agents/notes/implemented/feature/2026-08-15-product-subagent-noninteractive-permissions.i18n.yaml # .agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.i18n.yaml # .agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md # .agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.i18n.yaml # .agents/notes/implemented/process/2026-07-22-evidence-based-larger-hosted-runners.zh.md # .agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.i18n.yaml # .agents/notes/implemented/process/2026-07-23-portable-required-pull-request-ci.zh.md # .agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml # .agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md # .agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.i18n.yaml # .agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.zh.md # .agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml # README.i18n.yaml # README.zh.md # docs/architecture.i18n.yaml # docs/architecture.zh.md # docs/development.i18n.yaml # docs/development.zh.md # docs/persistence-catalog.i18n.yaml # docs/persistence-catalog.zh.md # docs/subsystems/README.i18n.yaml # docs/subsystems/README.zh.md # docs/subsystems/agent-team.i18n.yaml # docs/subsystems/agent-team.zh.md # docs/subsystems/client-modules.i18n.yaml # docs/subsystems/client-modules.zh.md # docs/subsystems/commands.i18n.yaml # docs/subsystems/commands.zh.md # docs/subsystems/persistence.i18n.yaml # docs/subsystems/persistence.zh.md # docs/subsystems/session-reference.i18n.yaml # docs/tool-catalog.i18n.yaml # docs/tool-catalog.zh.md # docs/user/guide/providers.i18n.yaml # docs/user/guide/providers.zh.md # packages/README.i18n.yaml # packages/README.zh.md # packages/bundle/web-app/README.i18n.yaml # packages/bundle/web-app/README.zh.md # packages/client/README.i18n.yaml # packages/client/README.zh.md # packages/client/connection/README.i18n.yaml # packages/client/connection/README.zh.md # packages/client/ui-conversation/README.i18n.yaml # packages/client/ui-conversation/README.zh.md # packages/client/ui-primitives/README.i18n.yaml # packages/client/ui-primitives/README.zh.md # packages/client/ui-sidebar/README.i18n.yaml # packages/client/ui-sidebar/README.zh.md # packages/client/ui-workspace/README.i18n.yaml # packages/client/ui-workspace/README.zh.md # packages/context/README.i18n.yaml # packages/context/README.zh.md # packages/core/agent-loop/README.i18n.yaml # packages/credentials/README.i18n.yaml # packages/credentials/README.zh.md # packages/experimental/agent-team/README.i18n.yaml # packages/experimental/agent-team/README.zh.md # packages/experimental/tool-agent-team/README.i18n.yaml # packages/experimental/tool-agent-team/README.zh.md # packages/host/frontend-static/README.i18n.yaml # packages/host/frontend-static/README.zh.md # packages/host/webserver/README.i18n.yaml # packages/host/webserver/README.zh.md # packages/interaction/commands/README.i18n.yaml # packages/interaction/commands/README.zh.md # packages/plan/plan-mode/README.i18n.yaml # packages/plan/plan-mode/README.zh.md # packages/sandbox/sandbox-local/README.i18n.yaml # packages/sandbox/sandbox-local/README.zh.md # packages/session/README.i18n.yaml # packages/session/README.zh.md # packages/session/session-persistence-sqlite/README.i18n.yaml # packages/session/session-persistence-sqlite/README.zh.md # packages/session/session-projection-cache/README.i18n.yaml # packages/session/session-projection-cache/README.zh.md # packages/shell/tool-pwsh/README.i18n.yaml # packages/shell/tool-pwsh/README.zh.md # packages/subagent/subagent-codex/README.i18n.yaml # packages/subagent/subagent-codex/README.zh.md # packages/subagent/subagent/README.i18n.yaml # packages/subagent/subagent/README.zh.md # packages/web/tool-web/README.i18n.yaml # packages/web/tool-web/README.zh.md # scripts/snapshots/translation-prompt-v4/request-response.expected.json
2026-08-29 04:26:38 +00:00 · 2026-08-20 19:15:33 +08:00
parent 00af8d4f77 aef4e1c9b7
commit 84cbec28e9
1351 changed files with 37052 additions and 7350 deletions
@@ -1,7 +1,7 @@
 {
  "name": "@deepseek-ai/dsh-bash-local",
  "description": "Local-subprocess implementation of the DeepSeek Harness bash executor seam",
-  "version": "0.1.0-rc.7",
+  "version": "0.1.0-rc.8",
  "publishConfig": {
    "access": "public"
  },
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/shell/bash-sandbox/README.md
-README.md: fe9a0b1a891bd2b9102357f48141822c70465ddf
-README.zh.md: 1b504346636948cddad6157faf8bb13c0c1b19bc
+README.md: dd0f6dd80394ee8bf0349f706e8fd77cd3c14189
+README.zh.md: 00b146ea88ffb449c7eaca1de6185657592fe774
@@ -19,7 +19,7 @@ Semantics:
 - **Denials are result facts.** A failed run whose stderr carries the selected backend's own denial dialect — the signatures the provider stamps on every wrap (EROFS text under bwrap, EACCES under Landlock, EPERM under Seatbelt) — is reported as `ShellRunResult.sandbox.denied: true` (conservative classification, read from the collected stderr tail); every CONFINED run also carries the mode it executed under (`result.sandbox.mode`) and the provider's enforcement completeness (`result.sandbox.enforcement`: `full`, or `partial` on an older Landlock ABI).
 - **The runner path or syscall must match.** Before a process starts, a rejection is attributed to the runner only when the caller-owned workdir is independently usable and Node reports `ENOENT` or `EACCES` with either an `error.path` equal to provider argv[0] or, when `error.path` is absent, an exact `syscall: 'spawn <runner>'`. A present path also requires `syscall: 'spawn'` or the exact `spawn <runner>`. This covers a missing runner, a non-executable runner, or an executable script whose shebang interpreter is unavailable. A bare `syscall: 'spawn'` without an exact error path, any other code, an invalid or unusable workdir, a resource failure, an unrelated syscall, or an unstructured rejection retains the local executor's command-start failure semantics. Foreground execution throws `SANDBOX_UNAVAILABLE` with the original spawn detail, while asynchronous background settlement stamps `runnerFailed: true` and `denied: false`. If a `SubprocessRuntime` synchronously throws the same runner-identifying `ENOENT`/`EACCES` shape, background start throws `SANDBOX_UNAVAILABLE`; other synchronous errors propagate unchanged. After a process starts, a rule's optional exit-code check and a remaining fatal stderr line must both match after exact informational-line exclusions. A match takes priority over denial; foreground execution throws `SANDBOX_UNAVAILABLE` with the matched fatal line, while a settled background process stamps `process.sandbox.runnerFailed`, which the bash producer renders through generic `job_output`. Confined background handles retain their mode/enforcement facts and release per-process accounting in either path.
 - **Deployment fallback, per-call policy.** [`ctx.sandboxPolicy`](../../sandbox/sandbox-policy/) resolves a complete `SandboxExecutionPolicy` for every tool call: the calling session supplies its mode override and immutable cwd root, while deployment config supplies the fallbacks for agentless calls. An approved escalation changes only that policy's mode; its session root stays attached. `resolve()` carries the policy onto the spec, so overlapping commands from different projects run, classify, and report under their own roots and modes. The capability fact `ctx.shell.sandboxMode` reports the configured default so the tool layer advertises escalation only when this executor is mounted; the static bash tool description separately owns denial and escalation guidance.
- **File effects only.** Network and process visibility are deliberately not restricted — the mode vocabulary does not pretend to cover what the backend does not enforce.
+- **File effects only.** The mode vocabulary claims only file effects. Network stays unrestricted; process visibility is backend-specific and documented by [`dsh-sandbox-local`](../../sandbox/sandbox-local/).
 - Process mechanics (spawn, process-group kills, output collection/spill, background handles, credential scrub) are inherited from [`dsh-bash-local`](../bash-local/); runner selection lives in [`dsh-sandbox-local`](../../sandbox/sandbox-local/).

 Deny-only at the seam: a denial is a reported fact, and this executor never negotiates permissions itself — the approval question lives in the tool layer (`dsh-tool-bash`), which drives the override this package honors.
@@ -82,7 +82,7 @@ Append-only; newly visible content follows the reusable request prefix and does

 ## Known Limitations and Deferred Work

- **Confinement covers file effects only** — network access and process visibility are unchanged, so the modes are not a general-purpose security sandbox.
+- **Confinement covers file effects only** — network restriction and a uniform process-visibility guarantee are absent, so the modes are not a general-purpose security sandbox.
 - **Denials are inferred from failed-command stderr** — backend signatures make the inference portable, but a matching application error can be classified as a denial and a denial omitted from the retained tail can be missed.
 - **An asynchronously observed background runner failure has no immediate error channel** — it is recorded on the settled process and surfaces when the caller reads the generic task with `job_output`; a synchronous `SubprocessRuntime` throw that names the runner path instead fails `start()` immediately.
 - **`danger-full-access` deliberately bypasses `ctx.sandbox`** — it is an explicit unconfined mode, not a wider sandbox profile.
@@ -19,7 +19,7 @@
 - **拒绝是结果事实。** 如果一次失败运行的 stderr 包含所选后端自身的拒绝方言，即提供方在每次包装时加上的特征（bwrap 下的 EROFS 文本、Landlock 下的 EACCES、Seatbelt 下的 EPERM），则结果报告 `ShellRunResult.sandbox.denied: true`（从已收集的 stderr 尾部进行保守分类）。每次受限制运行还会携带执行时模式（`result.sandbox.mode`）与提供方强制执行完整性（`result.sandbox.enforcement`：`full`，或在较旧 Landlock ABI 上为 `partial`）。
 - **Runner 路径或 syscall 必须匹配。** 进程启动前，调用方拥有的 workdir 必须经独立验证可用，Node 必须报告 `ENOENT` 或 `EACCES`，并且错误必须符合以下一种形态：`error.path` 等于提供方返回的 `argv[0]`，同时 `syscall` 为 `'spawn'` 或精确的 `'spawn <runner>'`；或者 `error.path` 不存在，同时 `syscall` 为精确的 `'spawn <runner>'`。这样可以识别缺失的 runner、不可执行的 runner，或 shebang 解释器不可用的可执行脚本。没有精确错误路径的裸 `syscall: 'spawn'`、任何其他错误码、无效或不可用的 workdir、资源失败、无关 syscall 或无结构拒绝仍保留本地执行器的命令启动失败语义。前台执行会抛出 `SANDBOX_UNAVAILABLE` 并附带原始 spawn 错误详情，异步后台结算则会标记 `runnerFailed: true` 和 `denied: false`。如果 `SubprocessRuntime` 同步抛出同样能指明 runner 的 `ENOENT`／`EACCES` 形态，后台启动会抛出 `SANDBOX_UNAVAILABLE`；其他同步错误原样传播。进程启动后，先按整行精确匹配排除信息性行，随后规则的可选退出码检查和余下 stderr 中的一行致命诊断必须同时匹配。匹配结果优先于拒绝；前台执行会抛出 `SANDBOX_UNAVAILABLE` 并附带匹配到的致命行，已结算的后台进程则会标记 `process.sandbox.runnerFailed`，Bash 结果生成方通过通用 `job_output` 渲染它。无论走哪条路径，受限制的后台句柄都会保留自身的模式／强制执行事实，并释放每进程计数。
 - **部署回退，每次调用策略。** [`ctx.sandboxPolicy`](../../sandbox/sandbox-policy/) 为每次工具调用解析完整的 `SandboxExecutionPolicy`：调用会话提供自身的模式覆盖与不可变 cwd 根目录，部署配置则为无 agent（智能体）调用提供回退。已批准的升权只更改该策略的模式，会话根目录仍然附着其上。`resolve()` 把策略带入 spec，因此来自不同项目的重叠命令会在各自的根目录与模式下运行、分类和报告。能力事实 `ctx.shell.sandboxMode` 报告已配置的默认值，因此工具层只在装载该执行器时才公布升权；静态 bash 工具描述则单独负责拒绝与升权引导。
- **只限制文件影响。** 设计上不限制网络与进程可见性：模式词汇不会声称覆盖后端未强制执行的范围。
+- **只限制文件影响。** 模式词汇只声称文件影响。网络仍不受限制；进程可见性因后端而异，具体见 [`dsh-sandbox-local`](../../sandbox/sandbox-local/)。
 - 进程机制（spawn、进程组终止、输出收集／spill、后台句柄、凭证清理）继承自 [`dsh-bash-local`](../bash-local/)；runner 选择位于 [`dsh-sandbox-local`](../../sandbox/sandbox-local/)。

 该 seam 只报告拒绝：拒绝是一项结果事实，本执行器绝不自行协商权限。批准问题位于工具层（`dsh-tool-bash`），由它设置本包所遵守的模式覆盖值。
@@ -82,7 +82,7 @@

 ## 已知限制与暂缓事项

- **限制只覆盖文件影响**：网络访问与进程可见性不变，因此这些模式不是通用安全沙箱。
+- **限制只覆盖文件影响**：不提供网络限制和统一的进程可见性保证，因此这些模式不是通用安全沙箱。
 - **拒绝从失败命令的 stderr 推断**：后端特征使该推断可跨平台使用，但包含相同后端特征的应用错误可能被分类为拒绝，也可能遗漏未出现在保留尾部中的拒绝。
 - **异步观测到的后台 runner 失败没有即时错误通道**：它记录在已结算进程上，并在调用方使用 `job_output` 读取通用任务时呈现；`SubprocessRuntime` 同步抛出的错误包含 runner 路径时，则会使 `start()` 立即失败。
 - **`danger-full-access` 有意绕过 `ctx.sandbox`**：它是显式无约束模式，不是更宽的沙箱 profile。
@@ -1,7 +1,7 @@
 {
  "name": "@deepseek-ai/dsh-bash-sandbox",
  "description": "Sandbox-consuming implementation of the DeepSeek Harness bash executor seam (confines every command via ctx.sandbox, reports denial/enforcement result facts)",
-  "version": "0.1.0-rc.7",
+  "version": "0.1.0-rc.8",
  "publishConfig": {
    "access": "public"
  },
@@ -1,7 +1,7 @@
 {
  "name": "@deepseek-ai/dsh-pwsh-local",
  "description": "Local PowerShell implementation of the DeepSeek Harness bash executor seam",
-  "version": "0.1.0-rc.7",
+  "version": "0.1.0-rc.8",
  "publishConfig": {
    "access": "public"
  },
@@ -1,7 +1,7 @@
 {
  "name": "@deepseek-ai/dsh-pwsh-sandbox",
  "description": "Sandbox-consuming implementation of the DeepSeek Harness PowerShell executor seam (confines every command via ctx.sandbox, reports denial/enforcement result facts)",
-  "version": "0.1.0-rc.7",
+  "version": "0.1.0-rc.8",
  "publishConfig": {
    "access": "public"
  },
@@ -1,7 +1,7 @@
 {
  "name": "@deepseek-ai/dsh-shell-env",
  "description": "Tool-independent managed DSH_* shell environment registry",
-  "version": "0.1.0-rc.7",
+  "version": "0.1.0-rc.8",
  "publishConfig": {
    "access": "public"
  },
@@ -1,7 +1,7 @@
 {
  "name": "@deepseek-ai/dsh-shell",
  "description": "Abstract bash executor seam (ctx.shell) for the DeepSeek Harness",
-  "version": "0.1.0-rc.7",
+  "version": "0.1.0-rc.8",
  "publishConfig": {
    "access": "public"
  },
@@ -1,7 +1,7 @@
 {
  "name": "@deepseek-ai/dsh-tool-bash-persistent",
  "description": "Model-facing owner-scoped persistent Bash tool backed by the Harness PTY service",
-  "version": "0.1.0-rc.7",
+  "version": "0.1.0-rc.8",
  "publishConfig": {
    "access": "public"
  },
@@ -186,6 +186,36 @@ function renderShellExitStatus(
  return appendStatusMarker(content, marker)
 }

+/**
+ * Render the exited-session result, reset the owner's shell, and reset the
+ * message that tells the model the next call starts fresh.
+ * @param shells - the owner-scoped registry to reset.
+ * @param status - the exited session status (exit code and signal).
+ * @returns the complete model-facing result.
+ */
+async function respondToSessionExit(
+  ctx: Context,
+  shells: PersistentShells,
+  owner: Agent,
+  id: TerminalSessionId,
+  status: { exitCode: number | null; signal: NodeJS.Signals | null },
+  marker: CommandMarkers,
+  fallback: string,
+  fallbackTruncated: boolean,
+  config: ResolvedConfig,
+): Promise<string> {
+  const snapshot = retainedScrollback(ctx, owner, id)
+  await shells.reset(owner, 'persistent bash shell exited')
+  return [
+    renderShellExitStatus(
+      renderCaptured(partialOutput(snapshot, marker, fallback, fallbackTruncated), config.maxOutputChars),
+      status.exitCode,
+      status.signal,
+    ),
+    SHELL_RESET_MESSAGE,
+  ].filter(part => part.length > 0).join('\n')
+}
+
 function persistentShells(ctx: Context, config: ResolvedConfig): PersistentShells {
  const pending = new WeakMap<Agent, Promise<TerminalSessionId>>()
  const live = new Map<Agent, TerminalSessionId>()
@@ -277,6 +307,15 @@ async function executeCommand(
  let fallbackTruncated = false

  while (true) {
+    // The shell may flip to exited between iterations (a fast `exit` can
+    // settle the previous send while its exit event is still in flight);
+    // re-observing status before the next send closes that gap.
+    const status = ctx.terminals.list(owner).find(session => session.sessionId === id)?.status
+    if (status?.kind === 'exited') {
+      return await respondToSessionExit(
+        ctx, shells, owner, id, status, marker, fallback, fallbackTruncated, config,
+      )
+    }
    let operation
    let result
    try {
@@ -319,16 +358,9 @@ async function executeCommand(
      if (complete !== undefined) return renderCaptured(complete, config.maxOutputChars)
    }
    if (result.sessionStatus.kind === 'exited') {
-      const snapshot = retainedScrollback(ctx, owner, id, latest)
-      await shells.reset(owner, 'persistent bash shell exited')
-      return [
-        renderShellExitStatus(
-          renderCaptured(partialOutput(snapshot, marker, fallback, fallbackTruncated), config.maxOutputChars),
-          result.sessionStatus.exitCode,
-          result.sessionStatus.signal,
-        ),
-        SHELL_RESET_MESSAGE,
-      ].filter(part => part.length > 0).join('\n')
+      return await respondToSessionExit(
+        ctx, shells, owner, id, result.sessionStatus, marker, fallback, fallbackTruncated, config,
+      )
    }
    // The shell reads stdin again (its prompt, or a foreground child's own
    // read) without having printed the end marker — e.g. `exec`, an interrupt,
@@ -98,6 +98,7 @@ type StubMode =
  | 'incremental-fallback'
  | 'empty-page-after-latest'
  | 'paged-scrollback'
+  | 'exit-after-send'

 class StubPtySession implements TerminalBackendSession {
  readonly motd = 'stub> '
@@ -109,6 +110,7 @@ class StubPtySession implements TerminalBackendSession {
  sends = 0
  pendingText = ''
  historyTruncated = false
+  throwOnSend = false

  constructor(mode: StubMode) {
    this.mode = mode
@@ -127,6 +129,7 @@ class StubPtySession implements TerminalBackendSession {
      return this.operation(Promise.resolve(this.result(this.motd, 'stdin_read')))
    }
    if (this.mode === 'send-error') throw new Error('stub send failed')
+    if (this.throwOnSend) throw new Error('PTY session has exited')
    if (this.mode === 'wait-for-abort' || this.mode === 'end-on-abort') {
      const done = new Promise<ReturnType<StubPtySession['result']>>((resolve) => {
        request.signal?.addEventListener('abort', () => {
@@ -171,6 +174,18 @@ class StubPtySession implements TerminalBackendSession {
      const incremental = `${start ?? ''}\nincrement\n${this.motd}`
      return this.operation(Promise.resolve(this.result(this.motd, 'stdin_read')), incremental)
    }
+    if (this.mode === 'exit-after-send') {
+      // A fast `exit` settles the send while the exit event is still in
+      // flight; the shell flips to exited before the tool's next poll,
+      // exactly like the real backend. The tool must re-observe status
+      // instead of sending.
+      const output = `${start ?? ''}\n`
+      this.scrollback += output
+      const settled = this.result(output, 'inferred_idle')
+      this.statusValue = { kind: 'exited', exitCode: 9, signal: null }
+      this.throwOnSend = true
+      return this.operation(Promise.resolve(settled))
+    }
    if (this.mode === 'torn-status') {
      const output = `${start ?? ''}\nhello from stub\n${end ?? ''}`
      this.scrollback += output
@@ -395,6 +410,21 @@ describe('tool-bash-persistent', () => {
    expect(text(await call(ctx, owner, 'torn status'))).toBe('hello from stub\n[exit code: 7]')
  })

+  it('reports the exit path when the shell exits between send settlement and the next poll', async () => {
+    const { ctx, owner, stub } = await setup({ backendType: 'stub' })
+    await call(ctx, owner, 'warm up')
+    const session = stub.sessions[0]!
+    session.mode = 'exit-after-send'
+
+    const result = text(await call(ctx, owner, 'exit'))
+    expect(result).toContain('[shell exited: code 9]')
+    expect(result).toContain('next bash call starts from the workspace')
+    expect(session.closed).toContain('persistent bash shell exited')
+
+    expect(text(await call(ctx, owner, 'echo "$PWD"'))).toBe('hello from stub')
+    expect(stub.sessions).toHaveLength(2)
+  })
+
  it('reports a shell exit when the backend has no code or signal', async () => {
    const { ctx, owner, stub } = await setup({ backendType: 'stub' })
    await call(ctx, owner, 'warm up')
@@ -1,7 +1,7 @@
 {
  "name": "@deepseek-ai/dsh-tool-bash",
  "description": "Model-facing bash tool with optional generic background-job and sandbox-escalation support",
-  "version": "0.1.0-rc.7",
+  "version": "0.1.0-rc.8",
  "publishConfig": {
    "access": "public"
  },
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/shell/tool-pwsh-persistent/README.md
+README.md: a57c940801606c2eef450f0e54fecb434c62a406
+README.zh.md: 75f6babfaffc79120f96441bdd5e08895b8e452f
@@ -0,0 +1,55 @@
+# @deepseek-ai/dsh-tool-pwsh-persistent
+
+English | [中文](README.zh.md)
+
+Model-facing `pwsh(command)` backed by one owner-scoped `ctx.terminals` shell. The package owns the tool contract and shell reuse; deployments select the terminal backend (a `terminal-bash` instance configured with `shellDialect: pwsh`) and sandbox policy. It is the Windows counterpart of `tool-bash-persistent`: same persistent-state contract, PowerShell dialect.
+
+## Config
+
+| Key | Default | Meaning |
+|---|---:|---|
+| `backendType` | `shell` | Registered terminal backend used for each Agent shell. |
+| `timeoutMs` | `300000` | Wall-clock limit for one command; timeout closes the shell. |
+| `maxOutputChars` | `16000` | Maximum retained command-output characters; fixed diagnostics are added afterward. |
+| `description` | Persistent-shell description | Model-facing environment contract. |
+
+## Model Experience
+
+### Tool schema
+
+#### What the model sees
+
+The generated [`pwsh` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-pwsh-persistent), including the configured `description`. The plugin contributes no standalone system-prompt section; the deployment owns persona and environment guidance.
+
+#### Token effect
+
+Fixed schema cost while `pwsh` is visible.
+
+#### KV Cache effect
+
+Prefix-stable while the configured description and schema remain unchanged.
+
+### Tool results
+
+#### What the model sees
+
+Commands share one shell per Agent, so cwd, `$env:` variables, functions, and background jobs persist across calls. Results exclude private completion markers, the shell prompt, and the echoed input line (PSReadLine renders submitted input back into the stream; the marker-anchored extraction and the wrapper-source strip remove it). A nonzero wrapped command appends `[exit code: N]` — the exact native exit code when the command ran a native program, `1` for a terminating PowerShell error. A shell that exits before reporting that status instead appends `[shell exited: code N]`, `[shell killed by signal: SIG]`, or `[shell exited]` when the backend supplies neither (Windows forced termination reports exit 1 without a signal), then resets and tells the model that the next call starts fresh. Long output keeps the earliest retained prefix plus a clipping notice; if the terminal has already dropped that prefix, the result says so explicitly. Timeout returns bounded partial output, closes the uncertain shell, and reports the reset.
+
+#### Token effect
+
+Data-dependent. `maxOutputChars` bounds retained command output; fixed clipping, lost-prefix, status, timeout, and reset diagnostics can extend the result.
+
+#### KV Cache effect
+
+Append-only tool results follow the reusable request prefix.
+
+## Known Limitations and Deferred Work
+
+- The tool requires an owning Agent and a real terminal backend with a pwsh dialect (Windows ConPTY or a POSIX pwsh).
+- **Input echo is unavoidable**: PowerShell's PSReadLine renders submitted input back into the terminal stream, and there is no `stty -echo` equivalent. The marker-anchored extraction excludes the echo in complete results; the wrapper-source strip covers fallback paths, but a wrapper that wraps across the terminal width may leave a partial echo in partial-output results, bounded by `maxOutputChars`.
+- Raw ESC characters inside model commands are unsupported: PSReadLine consumes them before execution. The wrapper escapes the control bytes it needs (`[char]27`-built OSC markers, backtick escapes for the body).
+- A model redefinition of the `prompt` function removes the readiness marker; the shell then settles on the silence tier instead of the marker fast path.
+- There is no interactive stdin during a command: a foreground command that reads input blocks until the readiness timeout, which resets the shell.
+- SIGTSTP/SIGHUP are unavailable on Windows (backend-rejected); SIGINT is delivered as a console-wide Ctrl-C input write, which at a prompt cancels the pending line instead of signalling a process.
+- Under the Windows ACL sandbox's read-only mode, pwsh starts in ConstrainedLanguage, which may deny the bootstrap's `[Console]::` encoding pin and prompt marker. Commands can still settle through the printable prompt and silence tier, but non-ASCII output may follow the host code page.
+- The BEL-terminated OSC marker remains a readiness signal only; a BEL event channel to the model stays deferred, aligned with the current implementation.
@@ -0,0 +1,55 @@
+# @deepseek-ai/dsh-tool-pwsh-persistent
+
+[English](README.md) | 中文
+
+模型侧 `pwsh(command)`，由一个 owner 作用域的 `ctx.terminals` shell 支撑。本包拥有工具契约与 shell 复用；部署方选择 terminal backend（配置 `shellDialect: pwsh` 的 `terminal-bash` 实例）与沙箱策略。它是 `tool-bash-persistent` 的 Windows 对应物：相同的持久状态契约，PowerShell 方言。
+
+## 配置
+
+| 键 | 默认值 | 含义 |
+|---|---:|---|
+| `backendType` | `shell` | 每个 Agent shell 使用的已注册 terminal backend。 |
+| `timeoutMs` | `300000` | 单条命令的墙钟上限；超时关闭 shell。 |
+| `maxOutputChars` | `16000` | 保留的命令输出字符上限；固定诊断文本在其后追加。 |
+| `description` | 持久 shell 描述 | 模型可见的环境契约。 |
+
+## 模型体验
+
+### 工具 schema
+
+#### 模型看到什么
+
+生成的 [`pwsh` schema](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-pwsh-persistent)，含配置的 `description`。本插件不贡献独立的 system-prompt 段落；persona 与环境指引由部署方负责。
+
+#### Token 影响
+
+`pwsh` 可见期间每个请求有固定的 schema 成本。
+
+#### KV Cache 影响
+
+配置的 description 与 schema 不变时前缀稳定。
+
+### 工具结果
+
+#### 模型看到什么
+
+命令共享每个 Agent 的一个 shell，因此 cwd、`$env:` 变量、函数和后台任务跨调用保留。结果排除私有完成标记、shell 提示符与回显的输入行（PSReadLine 会把提交的输入渲染回输出流；marker 锚定提取与包装器原文剥离将其移除）。非零包装命令追加 `[exit code: N]` —— 命令运行原生程序时是精确的原生退出码，PowerShell 终止性错误为 `1`。shell 在报告状态前退出的，改为追加 `[shell exited: code N]`、`[shell killed by signal: SIG]` 或 `[shell exited]`（backend 两者都没有时；Windows 强杀按无 signal 的 exit 1 报告），然后重置并告知模型下一次调用从全新 shell 开始。长输出保留最早的前缀并附裁剪提示；若 PTY 已丢弃该前缀，结果会明确说明。超时返回有界的部分输出、关闭不确定的 shell 并报告重置。
+
+#### Token 影响
+
+数据相关。`maxOutputChars` 限制保留的命令输出；固定裁剪、前缀丢失、状态、超时与重置诊断可能扩展结果。
+
+#### KV Cache 影响
+
+追加式工具结果跟随可复用的请求前缀。
+
+## 已知限制与延后工作
+
+- 工具需要拥有 Agent 与一个真实支持 pwsh 方言的 terminal backend（Windows ConPTY 或 POSIX 上的 pwsh）。
+- **输入回显不可避免**：PowerShell 的 PSReadLine 会把提交的输入渲染回终端流，且没有 `stty -echo` 的对应物。完整结果中 marker 锚定提取排除回显；包装器原文剥离覆盖回退路径，但跨越终端宽度的包装器折行可能在部分输出结果中残留片段回显，受 `maxOutputChars` 约束。
+- 模型命令中的裸 ESC 字符不受支持：PSReadLine 会在执行前吞掉它们。包装器转义它需要的控制字节（`[char]27` 构造的 OSC 标记、body 的反引号转义）。
+- 模型重定义 `prompt` 函数会移除就绪标记；shell 随后退化为静默档而非 marker 快路径。
+- 命令执行期间没有交互 stdin：读取输入的前台命令会阻塞到就绪超时，随后重置 shell。
+- SIGTSTP/SIGHUP 在 Windows 不可用（backend 拒绝）；SIGINT 以控制台级 Ctrl-C 输入写入投递，在提示符处取消当前行而非向进程发信号。
+- 在 Windows ACL 沙箱的只读模式下，pwsh 以 ConstrainedLanguage 启动，可能拒绝引导代码通过 `[Console]::` 固定编码并写入 prompt marker。命令仍可通过可打印提示符和静默档结算，但非 ASCII 输出可能沿用宿主代码页。
+- BEL 终结的 OSC 标记仍只是就绪信号；面向模型的 BEL 事件通道保持延后，与当前实现对齐。
@@ -0,0 +1,62 @@
+{
+  "name": "@deepseek-ai/dsh-tool-pwsh-persistent",
+  "description": "Model-facing owner-scoped persistent PowerShell tool backed by the Harness PTY service",
+  "version": "0.1.0-rc.8",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/shell/tool-pwsh-persistent"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-terminal": "workspace:^",
+    "@deepseek-ai/dsh-timeout": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
+    "@deepseek-ai/cordis": "workspace:^"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "workspace:^"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis-plugin-include": "workspace:^",
+    "@deepseek-ai/cordis-plugin-loader": "workspace:^",
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-terminal": "workspace:^",
+    "@deepseek-ai/dsh-terminal-bash": "workspace:^",
+    "@deepseek-ai/dsh-pwsh-local": "workspace:^",
+    "@deepseek-ai/dsh-sandbox": "workspace:^",
+    "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-subprocess-local": "workspace:^",
+    "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-timeout": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
+    "@deepseek-ai/cordis": "workspace:^"
+  }
+}
@@ -0,0 +1,514 @@
+/* jscpd:ignore-start -- deliberate mirror of tool-bash-persistent (persistent-pty note 2026-08-11-pwsh-persistent-pty):
+   the PowerShell counterpart shares the session registry, polling loop, and reset contract by design. */
+/**
+ * Model-facing persistent `pwsh` tool over the owner-scoped PTY seam.
+ * @module @deepseek-ai/dsh-tool-pwsh-persistent
+ */
+
+import { randomUUID } from 'node:crypto'
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type { TerminalReadResult, TerminalSendResult, TerminalSessionId } from '@deepseek-ai/dsh-terminal'
+import { deadline, timeoutOf } from '@deepseek-ai/dsh-timeout'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+
+// TODO: Replace the file-search advice; arbitrary command output need not come from a searchable file.
+const TRUNCATED_MESSAGE = '<response clipped><NOTE>To save on context only part of this file has been shown to you. You should retry this tool after you have searched inside the file with Select-String in order to find the line numbers of what you are looking for.</NOTE>'
+const LOST_PREFIX_MESSAGE = '<response clipped><NOTE>The beginning of this command output was dropped by the terminal scrollback limit. The following text is the earliest retained output.</NOTE>\n'
+const SHELL_RESET_MESSAGE = 'The persistent pwsh shell was reset; the next pwsh call starts from the workspace with a fresh current directory and environment.'
+const SHELL_PROMPT = '__DSH_PERSISTENT_PWSH_PROMPT__ '
+const TIMEOUT_CODE = 'PERSISTENT_PWSH_TIMEOUT'
+// One page is enough to find a just-emitted completion marker; the full
+// scrollback is assembled only when a command settles or needs partial output.
+const SCROLLBACK_PAGE_LINES = 1_000
+const POLL_INTERVAL_MS = 25
+
+const DEFAULT_DESCRIPTION = 'Run commands in a persistent PowerShell shell. State, including the current directory and exported environment variables, persists across calls for this agent.'
+
+interface ResolvedConfig {
+  backendType: string
+  timeoutMs: number
+  maxOutputChars: number
+  description: string
+}
+
+interface CommandMarkers {
+  start: string
+  end: string
+}
+
+interface RetainedOutput {
+  text: string
+  truncated: boolean
+}
+
+interface CapturedOutput {
+  text: string
+  incomplete: boolean
+  exitCode?: number
+}
+
+interface PersistentShells {
+  get(owner: Agent, signal: AbortSignal): Promise<TerminalSessionId>
+  reset(owner: Agent, reason: string): Promise<void>
+}
+
+function maybeTruncate(content: string, maxOutputChars: number, incomplete = false): string {
+  if (content.length <= maxOutputChars && !incomplete) return content
+  return content.length <= maxOutputChars
+    ? content + TRUNCATED_MESSAGE
+    : content.slice(0, maxOutputChars) + TRUNCATED_MESSAGE
+}
+
+function markers(): CommandMarkers {
+  const nonce = randomUUID()
+  return {
+    start: `__DSH_PERSISTENT_PWSH_START_${nonce}__`,
+    end: `__DSH_PERSISTENT_PWSH_END_${nonce}:`,
+  }
+}
+
+/**
+ * Escape a command body for embedding in the wrapper's double-quoted string.
+ * Backtick escapes keep every character literal: backtick first so the
+ * escapes this function inserts are never re-escaped, `$` so no expansion
+ * happens at wrapper construction, and `\r\n`/ESC so multi-line commands and
+ * raw control bytes ride one physical input line without PSReadLine mangling.
+ * @param value - the model's PowerShell command text.
+ * @returns the escaped double-quoted-string body.
+ */
+function quoteForPwsh(value: string): string {
+  return value
+    .replaceAll('`', '``')
+    .replaceAll('"', '`"')
+    .replaceAll('$', '`$')
+    .replaceAll('\r', '')
+    .replaceAll('\n', '`n')
+    .replaceAll('\x1b', '`e')
+}
+
+function wrapCommand(command: string, marker: CommandMarkers): string {
+  // Keep the wrapper on one physical line: PSReadLine renders the echoed
+  // input, and a wrapped line would split the echo the extraction strips.
+  // The echoed END nonce can never fabricate completion because the status
+  // regex needs digits immediately after it and the echo continues with
+  // quote characters.
+  const body = quoteForPwsh(command)
+  return `Write-Output '${marker.start}'; $LASTEXITCODE = $null; $__s = 1; try { Invoke-Expression "${body}"; $__ok = $? } catch { $__ok = $false }; if ($null -ne $LASTEXITCODE) { $__s = [int]$LASTEXITCODE } else { $__s = if ($__ok) { 0 } else { 1 } }; Write-Output ('${marker.end}' + $__s)`
+}
+
+function stripPrompt(text: string): string {
+  let result = text.replace(/\r?\n$/, '')
+  while (result.endsWith(SHELL_PROMPT)) {
+    result = result.slice(0, -SHELL_PROMPT.length)
+  }
+  return result.endsWith('\n') ? result.slice(0, -1) : result
+}
+
+function commandOutput(
+  snapshot: RetainedOutput,
+  marker: CommandMarkers,
+  wrapper: string,
+): CapturedOutput | undefined {
+  const text = snapshot.text
+  const end = text.lastIndexOf(marker.end)
+  const status = /^(\d+)\r?\n/.exec(text.slice(end + marker.end.length))?.[1]
+  if (status === undefined) return undefined
+  const startMarker = text.lastIndexOf(marker.start, end)
+  const start = startMarker < 0 ? 0 : startMarker + marker.start.length
+  let captured = text.slice(start, end)
+  // The PSReadLine echo carries the wrapper source (including both marker
+  // nonces) before the real markers; anchor on the real markers excludes it,
+  // and stripping the wrapper covers the rare case where the real START
+  // scrolled out and extraction fell back to the echoed copy.
+  captured = captured.replaceAll(wrapper, '')
+  return {
+    text: captured.replace(/^\r?\n/, '').replace(/\r?\n$/, ''),
+    incomplete: startMarker < 0,
+    exitCode: Number(status),
+  }
+}
+
+function promptCompleted(result: TerminalSendResult): boolean {
+  return result.viewport.endsWith(SHELL_PROMPT)
+    || result.viewport.endsWith(`${SHELL_PROMPT}\r\n`)
+    || result.viewport.endsWith(`${SHELL_PROMPT}\n`)
+}
+
+function partialOutput(
+  snapshot: RetainedOutput,
+  marker: CommandMarkers,
+  wrapper: string,
+  fallback: string,
+  fallbackTruncated = false,
+): CapturedOutput {
+  const startMarker = snapshot.text.lastIndexOf(marker.start)
+  if (startMarker >= 0) {
+    return {
+      text: stripPrompt(snapshot.text.slice(startMarker + marker.start.length).replace(/^\r?\n/, '')),
+      incomplete: false,
+    }
+  }
+  const fallbackStart = fallback.lastIndexOf(marker.start)
+  const afterStart = fallbackStart < 0
+    ? fallback
+    : fallback.slice(fallbackStart + marker.start.length).replace(/^\r?\n/, '')
+  const fallbackEnd = afterStart.lastIndexOf(marker.end)
+  const beforeEnd = fallbackEnd < 0 ? afterStart : afterStart.slice(0, fallbackEnd)
+  return {
+    text: stripPrompt(beforeEnd.replaceAll(SHELL_PROMPT, '').replaceAll(wrapper, '')),
+    incomplete: fallbackTruncated || fallbackStart < 0,
+  }
+}
+
+async function pause(): Promise<void> {
+  await new Promise(resolve => setTimeout(resolve, POLL_INTERVAL_MS))
+}
+
+function nextScrollbackOffset(page: TerminalReadResult, offset: number): number | undefined {
+  if (page.text.length === 0 || page.lineEnd <= offset) return undefined
+  return page.lineEnd
+}
+
+function retainedScrollback(
+  ctx: Context,
+  owner: Agent,
+  id: TerminalSessionId,
+  latest = ctx.terminals.read(owner, id, { offset: 0, count: SCROLLBACK_PAGE_LINES }),
+): RetainedOutput {
+  const pages: string[] = latest.text.length === 0 ? [] : [latest.text]
+  let offset = latest.lineEnd
+  let truncated = latest.truncated
+  while (true) {
+    if (offset >= latest.totalLines) break
+    const page = ctx.terminals.read(owner, id, { offset, count: SCROLLBACK_PAGE_LINES })
+    truncated ||= page.truncated
+    if (page.text.length > 0) pages.unshift(page.text)
+    const next = nextScrollbackOffset(page, offset)
+    if (next === undefined || next >= page.totalLines) break
+    offset = next
+  }
+  return { text: pages.join('\n'), truncated }
+}
+
+function renderCaptured(output: CapturedOutput, maxOutputChars: number): string {
+  const rendered = maybeTruncate(output.text, maxOutputChars, output.incomplete)
+  const withPrefix = output.incomplete && output.text.length > 0
+    ? LOST_PREFIX_MESSAGE + rendered
+    : rendered
+  const marker = output.exitCode !== undefined && output.exitCode !== 0
+    ? `[exit code: ${output.exitCode}]`
+    : undefined
+  return appendStatusMarker(withPrefix, marker)
+}
+
+function appendStatusMarker(content: string, marker: string | undefined): string {
+  if (marker === undefined) return content
+  return content.length === 0 ? marker : `${content}\n${marker}`
+}
+
+function renderShellExitStatus(
+  content: string,
+  exitCode: number | null,
+  signal: NodeJS.Signals | null,
+): string {
+  const marker = signal !== null
+    ? `[shell killed by signal: ${signal}]`
+    : exitCode !== null
+      ? `[shell exited: code ${exitCode}]`
+      : '[shell exited]'
+  return appendStatusMarker(content, marker)
+}
+
+/**
+ * Render the exited-session result, reset the owner's shell, and reset the
+ * message that tells the model the next call starts fresh.
+ * @param shells - the owner-scoped registry to reset.
+ * @param status - the exited session status (exit code and signal).
+ * @returns the complete model-facing result.
+ */
+async function respondToSessionExit(
+  ctx: Context,
+  shells: PersistentShells,
+  owner: Agent,
+  id: TerminalSessionId,
+  status: { exitCode: number | null; signal: NodeJS.Signals | null },
+  marker: CommandMarkers,
+  wrapped: string,
+  fallback: string,
+  fallbackTruncated: boolean,
+  config: ResolvedConfig,
+): Promise<string> {
+  const snapshot = retainedScrollback(ctx, owner, id)
+  await shells.reset(owner, 'persistent pwsh shell exited')
+  return [
+    renderShellExitStatus(
+      renderCaptured(partialOutput(snapshot, marker, wrapped, fallback, fallbackTruncated), config.maxOutputChars),
+      status.exitCode,
+      status.signal,
+    ),
+    SHELL_RESET_MESSAGE,
+  ].filter(part => part.length > 0).join('\n')
+}
+
+/**
+ * The pwsh prompt function that overrides the backend bootstrap value with
+ * this tool's own prompt. `[char]27`/`[char]7` build the OSC bytes at runtime
+ * because raw ESC characters in submitted input are unreliable under
+ * PSReadLine.
+ */
+const PWSH_PROMPT_SETUP =
+  "function prompt { [Console]::Write([char]27 + ']133;D;' + [int]$LASTEXITCODE + [char]7); '" + SHELL_PROMPT + "' }"
+
+function persistentShells(ctx: Context, config: ResolvedConfig): PersistentShells {
+  const pending = new WeakMap<Agent, Promise<TerminalSessionId>>()
+  const live = new Map<Agent, TerminalSessionId>()
+  const creating = new Set<Promise<TerminalSessionId>>()
+  const ownerCleanupInstalled = new WeakSet<Agent>()
+  const lifecycle = new AbortController()
+
+  const close = async (owner: Agent, id: TerminalSessionId, reason: string): Promise<void> => {
+    if (!ctx.terminals.list(owner).some(snapshot => snapshot.sessionId === id)) return
+    await ctx.terminals.kill(owner, id, reason)
+  }
+
+  ctx.effect(() => async () => {
+    lifecycle.abort(new Error('tool-pwsh-persistent disposed during shell creation'))
+    await Promise.allSettled([...creating])
+    const closing = [...live].map(async ([owner, id]) => { await close(owner, id, 'tool-pwsh-persistent disposed') })
+    await Promise.all(closing)
+    live.clear()
+  }, 'tool-pwsh-persistent shell cleanup')
+
+  const reset = async (owner: Agent, reason: string): Promise<void> => {
+    pending.delete(owner)
+    const id = live.get(owner)
+    live.delete(owner)
+    if (id !== undefined) await close(owner, id, reason)
+  }
+
+  const get = (owner: Agent, signal: AbortSignal): Promise<TerminalSessionId> => {
+    const existing = pending.get(owner)
+    if (existing !== undefined) return existing
+    const combinedSignal = AbortSignal.any([signal, lifecycle.signal])
+    const creation = (async () => {
+      try {
+        const cwd = owner.session.header.cwd
+        const spawned = await ctx.terminals.spawn(owner, {
+          type: config.backendType,
+          ...cwd === undefined ? {} : { cwd },
+        }, combinedSignal)
+        live.set(owner, spawned.sessionId)
+        if (!ownerCleanupInstalled.has(owner)) {
+          ownerCleanupInstalled.add(owner)
+          owner.ctx.effect(() => () => {
+            pending.delete(owner)
+            live.delete(owner)
+          }, 'tool-pwsh-persistent owner cache cleanup')
+        }
+        const setup = ctx.terminals.startSend(owner, spawned.sessionId, {
+          text: PWSH_PROMPT_SETUP,
+          submit: true,
+          signal: combinedSignal,
+        })
+        const result = await setup.done
+        if (result.sessionStatus.kind === 'exited' || result.waitReason === 'timeout') {
+          throw new Error('persistent pwsh shell did not accept initialization')
+        }
+        return spawned.sessionId
+      } catch (error: unknown) {
+        await reset(owner, 'persistent pwsh initialization failed')
+        throw error
+      }
+    })()
+    const tracked = creation.finally(() => {
+      creating.delete(tracked)
+    })
+    creating.add(tracked)
+    pending.set(owner, tracked)
+    return tracked
+  }
+
+  return { get, reset }
+}
+
+async function executeCommand(
+  ctx: Context,
+  shells: PersistentShells,
+  owner: Agent,
+  command: string,
+  config: ResolvedConfig,
+  upstream: AbortSignal,
+): Promise<string> {
+  using commandDeadline = deadline(upstream, config.timeoutMs, TIMEOUT_CODE)
+  const id = await shells.get(owner, commandDeadline.signal)
+  const marker = markers()
+  const wrapped = wrapCommand(command, marker)
+  let first = true
+  let fallback = ''
+  let fallbackTruncated = false
+
+  while (true) {
+    // The shell may flip to exited between iterations (a fast `exit` can
+    // settle the previous send while its exit event is still in flight, and
+    // the echoed wrapper can then carry a marker end without status digits);
+    // re-observing status before the next send closes that gap.
+    const status = ctx.terminals.list(owner).find(session => session.sessionId === id)?.status
+    if (status?.kind === 'exited') {
+      return await respondToSessionExit(
+        ctx, shells, owner, id, status, marker, wrapped, fallback, fallbackTruncated, config,
+      )
+    }
+    let operation
+    let result
+    try {
+      operation = ctx.terminals.startSend(owner, id, {
+        text: first ? wrapped : '',
+        submit: first,
+        signal: commandDeadline.signal,
+      })
+      first = false
+      result = await operation.done
+    } catch (error: unknown) {
+      await shells.reset(owner, 'persistent pwsh send failed')
+      throw error
+    }
+    const incremental = operation.readOutput()
+    fallback = incremental.delta.length > 0 ? fallback + incremental.delta : result.viewport
+    fallbackTruncated ||= incremental.truncated || result.truncated
+    const latest = ctx.terminals.read(owner, id, { offset: 0, count: SCROLLBACK_PAGE_LINES })
+    const timedOut = timeoutOf(commandDeadline.signal, TIMEOUT_CODE)
+    if (timedOut !== undefined) {
+      const snapshot = retainedScrollback(ctx, owner, id, latest)
+      const partial = renderCaptured(
+        partialOutput(snapshot, marker, wrapped, fallback, fallbackTruncated),
+        config.maxOutputChars,
+      )
+      await shells.reset(owner, 'persistent pwsh command timed out')
+      return [
+        // TODO: Report a timeout only; this signal does not establish an OOM.
+        `Your command timed out after ${Math.round(timedOut.timeoutMs / 1000)} seconds or experienced an OOM error. Below is partial output:`,
+        partial,
+        SHELL_RESET_MESSAGE,
+      ].join('\n')
+    }
+    if (commandDeadline.signal.aborted) {
+      await shells.reset(owner, 'persistent pwsh command aborted')
+      commandDeadline.signal.throwIfAborted()
+    }
+    if (latest.text.includes(marker.end)) {
+      const complete = commandOutput(retainedScrollback(ctx, owner, id, latest), marker, wrapped)
+      if (complete !== undefined) return renderCaptured(complete, config.maxOutputChars)
+    }
+    if (result.sessionStatus.kind === 'exited') {
+      return await respondToSessionExit(
+        ctx, shells, owner, id, result.sessionStatus, marker, wrapped, fallback, fallbackTruncated, config,
+      )
+    }
+    if (promptCompleted(result)) {
+      const snapshot = retainedScrollback(ctx, owner, id, latest)
+      return renderCaptured(
+        partialOutput(snapshot, marker, wrapped, fallback, fallbackTruncated),
+        config.maxOutputChars,
+      )
+    }
+    await pause()
+  }
+}
+
+/**
+ * Register the model-facing persistent `pwsh` tool.
+ * @param ctx - plugin context carrying tools and the owner-scoped PTY service.
+ * @param config - selected PTY backend and command deadline.
+ */
+function registerPersistentPwsh(ctx: Context, config: ResolvedConfig): void {
+  const shells = persistentShells(ctx, config)
+  const queues = new WeakMap<Agent, Promise<void>>()
+
+  const serialized = async <T>(owner: Agent, operation: () => Promise<T>): Promise<T> => {
+    const prior = queues.get(owner) ?? Promise.resolve()
+    const run = prior.then(operation, operation)
+    const tail = run.then(() => undefined, () => undefined)
+    queues.set(owner, tail)
+    try {
+      return await run
+    } finally {
+      if (queues.get(owner) === tail) queues.delete(owner)
+    }
+  }
+
+  ctx.tools.register(defineTool({
+    name: 'pwsh',
+    description: config.description,
+    parameters: {
+      command: {
+        type: 'string',
+        required: true,
+        description: 'The PowerShell command to run. Relative path is preferred in the command.',
+      },
+    },
+    output: {
+      schema: { type: 'string' },
+      render: (_args, value) => [{ type: 'text', text: value }],
+    },
+    async execute(args, exec) {
+      if (args.command.trim().length === 0) throw new Error('command must be a non-empty string')
+      const owner = exec.agent
+      if (owner === undefined) throw new Error('pwsh requires an owning agent session')
+      return serialized(owner, async () => {
+        exec.signal.throwIfAborted()
+        return executeCommand(ctx, shells, owner, args.command, config, exec.signal)
+      })
+    },
+    presentCall: args => ({ card: 'terminal', title: args.command }),
+  }))
+}
+
+export const name = 'tool-pwsh-persistent'
+export const inject = ['tools', 'terminals']
+
+/** Configuration for the persistent pwsh tool. */
+export interface Config {
+  /** PTY backend used for each owner-isolated persistent shell (default `shell`). */
+  backendType?: string
+  /** Wall-clock limit for one command (default 300000). */
+  timeoutMs?: number
+  /** Maximum returned command-output characters before clipping (default 16000). */
+  maxOutputChars?: number
+  /** Model-facing tool description; deployments may describe their environment. */
+  description?: string
+}
+
+/** Runtime configuration schema for the persistent pwsh tool. */
+export const Config: z<Config> = z.object({
+  backendType: z.string().default('shell'),
+  timeoutMs: z.number().default(300_000),
+  maxOutputChars: z.number().default(16_000),
+  description: z.string().default(DEFAULT_DESCRIPTION),
+})
+
+/** Register one owner-scoped persistent `pwsh` tool. */
+export function apply(ctx: Context, config: Config): void {
+  const resolved: ResolvedConfig = {
+    backendType: config.backendType ?? 'shell',
+    timeoutMs: config.timeoutMs ?? 300_000,
+    maxOutputChars: config.maxOutputChars ?? 16_000,
+    description: config.description ?? DEFAULT_DESCRIPTION,
+  }
+  if (resolved.backendType.trim().length === 0) {
+    throw new Error('tool-pwsh-persistent: backendType must be non-empty')
+  }
+  if (!Number.isSafeInteger(resolved.timeoutMs) || resolved.timeoutMs <= 0) {
+    throw new Error('tool-pwsh-persistent: timeoutMs must be a positive safe integer')
+  }
+  if (!Number.isSafeInteger(resolved.maxOutputChars) || resolved.maxOutputChars <= 0) {
+    throw new Error('tool-pwsh-persistent: maxOutputChars must be a positive safe integer')
+  }
+  if (resolved.description.trim().length === 0) {
+    throw new Error('tool-pwsh-persistent: description must be non-empty')
+  }
+  registerPersistentPwsh(ctx, resolved)
+}
+
+/* jscpd:ignore-end */
@@ -0,0 +1,31 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-tool-pwsh-persistent`.
+ * @module @deepseek-ai/dsh-tool-pwsh-persistent/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from '@deepseek-ai/cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-tool-pwsh-persistent'
+
+/** Cordis companion plugin name. */
+export const name = 'tool-pwsh-persistent-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: the adapter's private owner-to-shell cache has no
+ * observable event or data relation. Lifecycle tests prove its cleanup without
+ * adding a public API solely for an invariant.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
@@ -0,0 +1,167 @@
+import { spawnSync } from 'node:child_process'
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { afterEach, describe, expect, it } from 'vitest'
+import { Context } from '@deepseek-ai/cordis'
+import Loader from '@deepseek-ai/cordis-plugin-loader'
+import Include from '@deepseek-ai/cordis-plugin-include'
+import { CallId } from '@deepseek-ai/dsh-llm'
+import { Session, SessionId } from '@deepseek-ai/dsh-session'
+import AgentRegistry, { Inbox } from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import TerminalSessionService from '@deepseek-ai/dsh-terminal'
+import * as TerminalBash from '@deepseek-ai/dsh-terminal-bash'
+import SandboxProvider from '@deepseek-ai/dsh-sandbox'
+import type { ConfinedArgv, SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
+import SandboxPolicyService from '@deepseek-ai/dsh-sandbox-policy'
+import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
+import { resolvePwshPath } from '@deepseek-ai/dsh-pwsh-local/src/resolve.ts'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import * as ToolPwshPersistent from '@deepseek-ai/dsh-tool-pwsh-persistent'
+
+const hasPwsh = spawnSync(
+  resolvePwshPath(), ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', '$true'],
+  { encoding: 'utf8' },
+).status === 0
+
+let root: string | undefined
+let context: Context | undefined
+
+afterEach(async () => {
+  await context?.fiber.dispose()
+  context = undefined
+  if (root !== undefined) await rm(root, { recursive: true, force: true })
+  root = undefined
+})
+
+class PassthroughSandbox extends SandboxProvider {
+  confine(argv: readonly string[], _policy: SandboxPolicy): ConfinedArgv {
+    return { argv: [...argv], enforcement: 'full', denialSignatures: [], runnerFailureRules: [] }
+  }
+}
+
+function agent(ctx: Context, cwd: string): Agent {
+  const id = SessionId('persistent-pwsh-loader-agent')
+  const scope = ctx.plugin(() => {})
+  const session = Session.create(id, [], { version: 0, id, createdAt: 0, cwd })
+  const value: Agent = {
+    id,
+    options: {},
+    session,
+    inbox: new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }),
+    status: 'idle',
+    ctx: scope.ctx,
+    send: () => {},
+    followup: () => {},
+    steer: () => ({ outcome: Promise.resolve({ status: 'rejected' as const }) }),
+    inject: () => {},
+    cancel() {},
+    runMaintenance: task => task(new AbortController().signal),
+    whenIdle: () => Promise.resolve(),
+  }
+  ctx.agents.register(value)
+  return value
+}
+
+function text(result: { content: { type: string; text?: string }[] }): string {
+  return result.content.filter(block => block.type === 'text').map(block => block.text).join('')
+}
+
+describe.skipIf(!hasPwsh)('persistent pwsh through a real cordis.yml Loader composition', () => {
+  it('preserves cwd and environment across calls', async () => {
+    root = await mkdtemp(join(tmpdir(), 'dsh-persistent-pwsh-loader-'))
+    const configPath = join(root, 'cordis.yml')
+    await writeFile(configPath, [
+      "- name: '@deepseek-ai/dsh-agent'",
+      "- name: '@deepseek-ai/dsh-system-prompt'",
+      "- name: '@deepseek-ai/dsh-tools'",
+      "- name: '@deepseek-ai/dsh-terminal'",
+      "- name: '@deepseek-ai/dsh-test-sandbox'",
+      "- name: '@deepseek-ai/dsh-sandbox-policy'",
+      '  config:',
+      '    mode: danger-full-access',
+      `    workspaceRoot: ${JSON.stringify(root)}`,
+      "- name: '@deepseek-ai/dsh-subprocess-local'",
+      "- name: '@deepseek-ai/dsh-terminal-bash'",
+      '  config:',
+      '    shellDialect: pwsh',
+      '    pollIntervalMs: 10',
+      '    exactProbeAfterMs: 20',
+      '    idleSilenceMs: 300',
+      '    handoffGraceMs: 300',
+      '    scrollbackLines: 20000',
+      '    timeoutMs: 8000',
+      '    disposeGraceMs: 500',
+      "- name: '@deepseek-ai/dsh-tool-pwsh-persistent'",
+      '  config:',
+      '    timeoutMs: 20000',
+      '',
+    ].join('\n'))
+
+    context = new Context()
+    context.baseUrl = pathToFileURL(root).href + '/'
+    await context.plugin(Loader)
+    context.loader.builtins.include = Include
+    const modules = new Map<string, unknown>([
+      ['@deepseek-ai/dsh-agent', AgentRegistry],
+      ['@deepseek-ai/dsh-system-prompt', SystemPrompt],
+      ['@deepseek-ai/dsh-tools', ToolRegistry],
+      ['@deepseek-ai/dsh-terminal', TerminalSessionService],
+      ['@deepseek-ai/dsh-test-sandbox', PassthroughSandbox],
+      ['@deepseek-ai/dsh-sandbox-policy', SandboxPolicyService],
+      ['@deepseek-ai/dsh-subprocess-local', LocalSubprocessService],
+      ['@deepseek-ai/dsh-terminal-bash', TerminalBash],
+      ['@deepseek-ai/dsh-tool-pwsh-persistent', ToolPwshPersistent],
+    ])
+    context.loader.internal = {
+      version: 'v2',
+      async import(specifier: string) {
+        if (!modules.has(specifier)) throw new Error(`unexpected Loader import: ${specifier}`)
+        return modules.get(specifier)
+      },
+    } as unknown as NonNullable<typeof context.loader.internal>
+    await context.loader.create({ name: 'cordis:include', config: { path: pathToFileURL(configPath).href } })
+    await context.loader.await()
+
+    const owner = agent(context, root)
+    const signal = new AbortController().signal
+    const execute = (id: string, command: string) => context!.tools.execute({
+      signal,
+      callId: CallId(id),
+      name: 'pwsh',
+      arguments: { command },
+      agent: owner,
+    })
+
+    expect(context.tools.schemas().map(schema => schema.name)).toEqual(['pwsh'])
+    await execute('state', '$env:KEEP = "loader"; New-Item -ItemType Directory -Force -Path nested | Out-Null; Set-Location nested')
+    const observed = text(await execute('observe', 'Write-Output "cwd=$PWD keep=$env:KEEP"'))
+    expect(observed).toContain(`cwd=${join(root, 'nested')} keep=loader`)
+    expect(observed).not.toContain('DSH_PERSISTENT_PWSH')
+
+    const multiline = text(await execute(
+      'multiline',
+      '$value = "line one"\nWrite-Output "${value}:it\'s fine"',
+    ))
+    expect(multiline).toBe("line one:it's fine")
+    expect(multiline).not.toContain('DSH_PERSISTENT_PWSH')
+
+    const hereString = text(await execute(
+      'here-string',
+      "$h = @'\nalpha\nbeta\n'@\nWrite-Output $h",
+    ))
+    expect(hereString).toBe('alpha\nbeta')
+
+    const large = text(await execute('large-output', '1..12050 | ForEach-Object { $_ }'))
+    expect(large.startsWith('1\n2\n3\n')).toBe(true)
+    expect(large).toContain('<response clipped>')
+    expect(large).not.toContain('beginning of this command output was dropped')
+
+    const exited = text(await execute('exit', 'exit'))
+    expect(exited).toContain('next pwsh call starts from the workspace')
+    expect(text(await execute('after-exit', 'Write-Output "$PWD"'))).toBe(root)
+  }, 60_000)
+})
@@ -0,0 +1,636 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { Context } from '@deepseek-ai/cordis'
+import { CallId } from '@deepseek-ai/dsh-llm'
+import { Session, SessionId } from '@deepseek-ai/dsh-session'
+import AgentRegistry, { Inbox } from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import TerminalSessionService from '@deepseek-ai/dsh-terminal'
+import type {
+  TerminalBackend,
+  TerminalBackendSession,
+  TerminalReadRequest,
+  TerminalSendOperation,
+  TerminalSendRequest,
+  TerminalSessionStatus,
+  TerminalSignal,
+  TerminalWaitReason,
+} from '@deepseek-ai/dsh-terminal'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import * as ToolPwshPersistent from '@deepseek-ai/dsh-tool-pwsh-persistent'
+
+const contexts: Context[] = []
+let callNumber = 0
+
+afterEach(async () => {
+  for (const ctx of contexts.splice(0)) await ctx.fiber.dispose()
+})
+
+function agent(ctx: Context, cwd: string | undefined): Agent {
+  const id = SessionId(`persistent-pwsh-owner-${callNumber}`)
+  const scope = ctx.plugin(() => {})
+  const session = Session.create(id, [], {
+    version: 0,
+    id,
+    createdAt: 0,
+    ...cwd === undefined ? {} : { cwd },
+  })
+  const value: Agent = {
+    id,
+    options: {},
+    session,
+    inbox: new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }),
+    status: 'idle',
+    ctx: scope.ctx,
+    send: () => {},
+    followup: () => {},
+    steer: () => ({ outcome: Promise.resolve({ status: 'rejected' as const }) }),
+    inject: () => {},
+    cancel() {},
+    runMaintenance: task => task(new AbortController().signal),
+    whenIdle: () => Promise.resolve(),
+  }
+  ctx.agents.register(value)
+  return value
+}
+
+function text(result: { content: { type: string; text?: string }[] }): string {
+  return result.content.filter(block => block.type === 'text').map(block => block.text).join('')
+}
+
+function call(
+  ctx: Context,
+  owner: Agent | undefined,
+  command: string,
+  signal = new AbortController().signal,
+) {
+  return ctx.tools.execute({
+    signal,
+    callId: CallId(`persistent-pwsh-${++callNumber}`),
+    name: 'pwsh',
+    arguments: { command },
+    ...owner === undefined ? {} : { agent: owner },
+  })
+}
+
+type StubMode =
+  | 'normal'
+  | 'prompt-only'
+  | 'prompt-crlf'
+  | 'empty-read'
+  | 'stalled-read'
+  | 'exit'
+  | 'signal-exit'
+  | 'unknown-exit'
+  | 'wait-for-abort'
+  | 'end-on-abort'
+  | 'idle-then-normal'
+  | 'large'
+  | 'nonzero'
+  | 'torn-status'
+  | 'finish-torn-status'
+  | 'end-only'
+  | 'init-exit'
+  | 'init-timeout'
+  | 'spawn-error'
+  | 'send-error'
+  | 'prompt-after-idle'
+  | 'incremental-fallback'
+  | 'empty-page-after-latest'
+  | 'paged-scrollback'
+  | 'with-echo'
+  | 'exit-after-send'
+  | 'prompt-collision'
+
+const START_PATTERN = /__DSH_PERSISTENT_PWSH_START_[^_]+(?:-[^_]+)*__/
+const END_PATTERN = /__DSH_PERSISTENT_PWSH_END_[^:]+:/
+
+class StubTerminalSession implements TerminalBackendSession {
+  readonly motd = '__DSH_PERSISTENT_PWSH_PROMPT__ '
+  readonly pid = 123
+  statusValue: TerminalSessionStatus = { kind: 'running' }
+  scrollback = this.motd
+  closed: string[] = []
+  mode: StubMode
+  sends = 0
+  pendingText = ''
+  historyTruncated = false
+  throwOnSend = false
+
+  constructor(mode: StubMode) {
+    this.mode = mode
+  }
+
+  startSend(request: TerminalSendRequest): TerminalSendOperation {
+    this.sends += 1
+    if (request.text.startsWith('function prompt')) {
+      if (this.mode === 'init-exit') {
+        this.statusValue = { kind: 'exited', exitCode: 1, signal: null }
+        return this.operation(Promise.resolve(this.result('', 'session_exit')))
+      }
+      if (this.mode === 'init-timeout') {
+        return this.operation(Promise.resolve(this.result('', 'timeout')))
+      }
+      return this.operation(Promise.resolve(this.result(this.motd, 'stdin_read')))
+    }
+    if (this.mode === 'send-error') throw new Error('stub send failed')
+    if (this.throwOnSend) throw new Error('PTY session has exited')
+    if (this.mode === 'wait-for-abort' || this.mode === 'end-on-abort') {
+      const done = new Promise<ReturnType<StubTerminalSession['result']>>((resolve) => {
+        request.signal?.addEventListener('abort', () => {
+          const start = START_PATTERN.exec(request.text)?.[0]
+          const end = END_PATTERN.exec(request.text)?.[0]
+          const output = this.mode === 'end-on-abort'
+            ? `${start ?? ''}\ninterrupted\n${end ?? ''}130\n${this.motd}`
+            : 'partial output'
+          this.scrollback += output
+          resolve(this.result(output, 'stdin_read'))
+        }, { once: true })
+      })
+      return this.operation(done)
+    }
+    if (this.mode === 'idle-then-normal') {
+      this.mode = 'normal'
+      this.pendingText = request.text
+      return this.operation(Promise.resolve(this.result('', 'inferred_idle')))
+    }
+    if (this.mode === 'prompt-after-idle') {
+      if (request.text.length > 0) {
+        const start = START_PATTERN.exec(request.text)?.[0]
+        const output = `${start ?? ''}\npartial syntax output\n`
+        this.scrollback += output
+        return this.operation(Promise.resolve(this.result(output, 'inferred_idle')))
+      }
+      const output = `pwsh: syntax error\n${this.motd}`
+      this.scrollback += output
+      return this.operation(Promise.resolve(this.result(output, 'stdin_read')))
+    }
+    if (this.mode === 'prompt-only' || this.mode === 'prompt-crlf') {
+      const newline = this.mode === 'prompt-crlf' ? '\r\n' : '\n'
+      const output = `pwsh: syntax error${newline}${this.motd}${newline}`
+      this.scrollback += output
+      return this.operation(Promise.resolve(this.result(output, 'stdin_read')))
+    }
+    const sent = request.text.length > 0 ? request.text : this.pendingText
+    this.pendingText = ''
+    const start = START_PATTERN.exec(sent)?.[0]
+    const end = END_PATTERN.exec(sent)?.[0]
+    if (this.mode === 'with-echo') {
+      // The PSReadLine echo renders the submitted wrapper before the real
+      // markers; the tool must strip it from the captured result.
+      const output = `${sent}\n${start ?? ''}\nhello from stub\n${end ?? ''}0\n${this.motd}`
+      this.scrollback += output
+      return this.operation(Promise.resolve(this.result(output, 'stdin_read')))
+    }
+    if (this.mode === 'exit-after-send') {
+      // A fast `exit` settles the send with an echoed wrapper (marker end,
+      // no status digits) while the exit event is still in flight; the shell
+      // flips to exited before the tool's next poll, exactly like the real
+      // ConPTY backend. The tool must re-observe status instead of sending.
+      const output = `${sent}\n${start ?? ''}\n`
+      this.scrollback += output
+      const settled = this.result(output, 'inferred_idle')
+      this.statusValue = { kind: 'exited', exitCode: 9, signal: null }
+      this.throwOnSend = true
+      return this.operation(Promise.resolve(settled))
+    }
+    if (this.mode === 'incremental-fallback') {
+      const incremental = `${start ?? ''}\nincrement\n${this.motd}`
+      return this.operation(Promise.resolve(this.result(this.motd, 'stdin_read')), incremental)
+    }
+    if (this.mode === 'torn-status') {
+      const output = `${start ?? ''}\nhello from stub\n${end ?? ''}`
+      this.scrollback += output
+      this.mode = 'finish-torn-status'
+      return this.operation(Promise.resolve(this.result(output, 'inferred_idle')))
+    }
+    if (this.mode === 'finish-torn-status') {
+      const output = `7\n${this.motd}`
+      this.scrollback += output
+      return this.operation(Promise.resolve(this.result(output, 'stdin_read')))
+    }
+    if (this.mode === 'end-only') {
+      const output = `recovered output\n${end ?? ''}0\n${this.motd}`
+      this.scrollback += output
+      return this.operation(Promise.resolve(this.result(output, 'stdin_read')))
+    }
+    const commandOutput = this.mode === 'large'
+      ? 'x'.repeat(100)
+      : this.mode === 'nonzero' ? ''
+        : this.mode === 'prompt-collision' ? this.motd
+          : 'hello from stub'
+    const exitCode = this.mode === 'nonzero' ? 7 : 0
+    const output = `${start ?? ''}\n${commandOutput}\n${end ?? ''}${exitCode}\n${this.motd}`
+    this.scrollback += output
+    if (this.mode === 'exit' || this.mode === 'signal-exit' || this.mode === 'unknown-exit') {
+      const exitedOutput = `${start ?? ''}\nhello from stub\n`
+      this.scrollback = this.scrollback.slice(0, -output.length) + exitedOutput
+      this.statusValue = this.mode === 'signal-exit'
+        ? { kind: 'exited', exitCode: null, signal: 'SIGTERM' }
+        : this.mode === 'exit'
+          ? { kind: 'exited', exitCode: 9, signal: null }
+          : { kind: 'exited', exitCode: null, signal: null }
+      return this.operation(Promise.resolve(this.result(exitedOutput, 'session_exit')))
+    }
+    return this.operation(Promise.resolve(this.result(output, 'stdin_read')))
+  }
+
+  read(request: TerminalReadRequest) {
+    if (this.mode === 'empty-read') {
+      return { text: '', totalLines: 0, lineBegin: 0, lineEnd: 0, truncated: false }
+    }
+    if (this.mode === 'stalled-read') {
+      return { text: 'stalled', totalLines: 1, lineBegin: 0, lineEnd: 0, truncated: false }
+    }
+    if (this.mode === 'empty-page-after-latest' && (request.offset ?? 0) > 0) {
+      return { text: '', totalLines: 2, lineBegin: 1, lineEnd: 1, truncated: false }
+    }
+    const lines = this.scrollback.split('\n')
+    if (this.mode === 'paged-scrollback') {
+      const offset = request.offset ?? 0
+      const end = lines.length - offset
+      const start = Math.max(0, end - 3)
+      const returnedLines = end - start
+      return {
+        text: lines.slice(start, end).join('\n'),
+        totalLines: lines.length,
+        lineBegin: offset,
+        lineEnd: offset + returnedLines,
+        truncated: this.historyTruncated,
+      }
+    }
+    return {
+      text: this.scrollback,
+      totalLines: this.mode === 'empty-page-after-latest' ? lines.length + 1 : lines.length,
+      lineBegin: 0,
+      lineEnd: this.mode === 'empty-page-after-latest' ? 1 : lines.length,
+      truncated: this.historyTruncated,
+    }
+  }
+
+  signal(_signal: TerminalSignal) {
+    return Promise.resolve({ delivered: true as const, targetPgid: 123 })
+  }
+
+  status() {
+    return this.statusValue
+  }
+
+  async close(reason: string) {
+    this.closed.push(reason)
+    this.statusValue = { kind: 'exited', exitCode: 0, signal: null }
+  }
+
+  private result(viewport: string, waitReason: TerminalWaitReason) {
+    return { viewport, waitReason, sessionStatus: this.statusValue, truncated: false }
+  }
+
+  private operation(done: Promise<ReturnType<StubTerminalSession['result']>>, delta = ''): TerminalSendOperation {
+    return {
+      done,
+      readOutput: () => ({ delta, truncated: false }),
+      cancel: () => false,
+    }
+  }
+}
+
+function stubBackend(initialMode: StubMode = 'normal') {
+  const sessions: StubTerminalSession[] = []
+  const backend: TerminalBackend = {
+    type: 'stub',
+    async spawn() {
+      if (initialMode === 'spawn-error') throw new Error('stub spawn failed')
+      const session = new StubTerminalSession(initialMode)
+      sessions.push(session)
+      return session
+    },
+  }
+  return { backend, sessions }
+}
+
+async function setup(
+  config: ToolPwshPersistent.Config = { backendType: 'stub' },
+  initialMode: StubMode = 'normal',
+) {
+  const ctx = new Context()
+  contexts.push(ctx)
+  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRegistry)
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(TerminalSessionService)
+  const stub = stubBackend(initialMode)
+  ctx.terminals.registerBackend(stub.backend)
+  const fiber = await ctx.plugin(ToolPwshPersistent, config)
+  return { ctx, stub, fiber, owner: agent(ctx, '/workspace') }
+}
+
+describe('tool-pwsh-persistent', () => {
+  it('registers a configurable schema and reuses one owner shell', async () => {
+    const { ctx, owner, stub, fiber } = await setup({
+      backendType: 'stub',
+      description: 'deployment-specific persistent shell',
+    })
+    const schema = ctx.tools.schemas()[0]
+    expect(ctx.tools.schemas().map(item => item.name)).toEqual(['pwsh'])
+    expect(schema?.description).toBe('deployment-specific persistent shell')
+    expect(schema?.parameters).toMatchObject({
+      required: ['command'],
+      properties: { command: { type: 'string' } },
+    })
+    expect(ctx.tools.get('pwsh')?.presentCall?.({ command: 'pwd' }))
+      .toEqual({ card: 'terminal', title: 'pwd' })
+
+    expect(text(await call(ctx, owner, 'Write-Output one'))).toBe('hello from stub')
+    expect(text(await call(ctx, owner, 'Write-Output two'))).toBe('hello from stub')
+    expect(stub.sessions).toHaveLength(1)
+    expect(stub.sessions[0]?.sends).toBe(3)
+
+    const ownerWithoutCwd = agent(ctx, undefined)
+    expect(text(await call(ctx, ownerWithoutCwd, 'pwd'))).toBe('hello from stub')
+    expect(stub.sessions).toHaveLength(2)
+
+    await fiber.dispose()
+    expect(ctx.tools.schemas()).toEqual([])
+    expect(ctx.tools.get('pwsh')).toBeUndefined()
+  })
+
+  it('strips the echoed wrapper from captured output', async () => {
+    const { ctx, owner, stub } = await setup({ backendType: 'stub' })
+    await call(ctx, owner, 'warm up')
+    stub.sessions[0]!.mode = 'with-echo'
+    const result = text(await call(ctx, owner, 'Write-Output hi'))
+    expect(result).toBe('hello from stub')
+    expect(result).not.toContain('__DSH_PERSISTENT_PWSH_START_')
+    expect(result).not.toContain('__DSH_PERSISTENT_PWSH_END_')
+    expect(result).not.toContain('Invoke-Expression')
+  })
+
+  it('preserves command output that equals the private shell prompt', async () => {
+    const { ctx, owner, stub } = await setup({ backendType: 'stub' })
+    await call(ctx, owner, 'warm up')
+    const session = stub.sessions[0]!
+
+    session.mode = 'prompt-collision'
+    expect(text(await call(ctx, owner, 'complete prompt collision'))).toBe(session.motd)
+  })
+
+  it('reports the exit path when the shell exits between send settlement and the next poll', async () => {
+    const { ctx, owner, stub } = await setup({ backendType: 'stub' })
+    await call(ctx, owner, 'warm up')
+    const session = stub.sessions[0]!
+    session.mode = 'exit-after-send'
+
+    const result = text(await call(ctx, owner, 'exit'))
+    expect(result).toContain('[shell exited: code 9]')
+    expect(result).toContain('next pwsh call starts from the workspace')
+    expect(session.closed).toContain('persistent pwsh shell exited')
+
+    expect(text(await call(ctx, owner, 'Write-Output "$PWD"'))).toBe('hello from stub')
+    expect(stub.sessions).toHaveLength(2)
+  })
+
+  it('handles inferred idle, prompt fallback, shell exit, clipping, and cleanup', async () => {
+    const { ctx, owner, stub, fiber } = await setup({
+      backendType: 'stub',
+      maxOutputChars: 10,
+    })
+    await call(ctx, owner, 'warm up')
+    const session = stub.sessions[0]!
+
+    session.mode = 'idle-then-normal'
+    expect(text(await call(ctx, owner, 'silent then complete'))).toContain('hello from')
+
+    session.mode = 'incremental-fallback'
+    session.scrollback = ''
+    expect(text(await call(ctx, owner, 'incremental fallback'))).toBe('increment')
+
+    session.mode = 'prompt-only'
+    const promptFallback = text(await call(ctx, owner, 'bad {'))
+    expect(promptFallback).toContain('pwsh: synt')
+    expect(promptFallback).not.toContain('DSH_PERSISTENT_PWSH_PROMPT')
+
+    session.mode = 'prompt-crlf'
+    session.scrollback = ''
+    const crlfPromptFallback = text(await call(ctx, owner, 'bad {'))
+    expect(crlfPromptFallback).toContain('pwsh: synt')
+    expect(crlfPromptFallback).not.toContain('DSH_PERSISTENT_PWSH_PROMPT')
+
+    session.mode = 'end-only'
+    session.scrollback = ''
+    const missingStart = text(await call(ctx, owner, 'recover marker'))
+    expect(missingStart).toContain('recovered')
+    expect(missingStart).toContain('beginning of this command output was dropped')
+    expect(missingStart).toContain('<response clipped>')
+
+    session.mode = 'large'
+    expect(text(await call(ctx, owner, 'large'))).toContain('<response clipped>')
+
+    session.mode = 'nonzero'
+    expect(text(await call(ctx, owner, 'false'))).toBe('[exit code: 7]')
+
+    session.mode = 'exit'
+    const exited = text(await call(ctx, owner, 'exit'))
+    expect(exited).toContain('hello from')
+    expect(exited).toContain('[shell exited: code 9]')
+    expect(exited).not.toContain('[exit code: 9]')
+    expect(exited).toContain('next pwsh call starts from the workspace')
+    expect(session.closed).toContain('persistent pwsh shell exited')
+
+    await call(ctx, owner, 'new shell')
+    expect(stub.sessions).toHaveLength(2)
+    const replacement = stub.sessions[1]!
+    replacement.mode = 'signal-exit'
+    expect(text(await call(ctx, owner, 'kill shell')))
+      .toContain('[shell killed by signal: SIGTERM]')
+
+    await call(ctx, owner, 'another shell')
+    expect(stub.sessions).toHaveLength(3)
+    const externallyClosed = ctx.terminals.list(owner)[0]?.sessionId
+    expect(externallyClosed).toBeDefined()
+    await ctx.terminals.kill(owner, externallyClosed!, 'external cleanup')
+    await fiber.dispose()
+    expect(stub.sessions[2]?.closed).toEqual(['external cleanup'])
+  })
+
+  it('waits for status digits after a torn completion marker', async () => {
+    const { ctx, owner, stub } = await setup({ backendType: 'stub', maxOutputChars: 1_000 })
+    await call(ctx, owner, 'warm up')
+    stub.sessions[0]!.mode = 'torn-status'
+    stub.sessions[0]!.scrollback = ''
+
+    expect(text(await call(ctx, owner, 'torn status'))).toBe('hello from stub\n[exit code: 7]')
+  })
+
+  it('reports a shell exit when the backend has no code or signal', async () => {
+    const { ctx, owner, stub } = await setup({ backendType: 'stub' })
+    await call(ctx, owner, 'warm up')
+    stub.sessions[0]!.mode = 'unknown-exit'
+
+    expect(text(await call(ctx, owner, 'exit without status'))).toContain('[shell exited]')
+  })
+
+  it('marks a short missing-prefix result and tolerates exhausted scrollback pages', async () => {
+    const { ctx, owner, stub } = await setup({ backendType: 'stub', maxOutputChars: 1_000 })
+    await call(ctx, owner, 'warm up')
+    const session = stub.sessions[0]!
+
+    session.mode = 'end-only'
+    session.scrollback = ''
+    expect(text(await call(ctx, owner, 'missing start')))
+      .toContain('beginning of this command output was dropped')
+
+    session.mode = 'empty-read'
+    expect(text(await call(ctx, owner, 'empty page'))).toContain('hello from stub')
+
+    session.mode = 'stalled-read'
+    expect(text(await call(ctx, owner, 'stalled page'))).toContain('hello from stub')
+
+    session.mode = 'empty-page-after-latest'
+    expect(text(await call(ctx, owner, 'empty continuation page'))).toContain('hello from stub')
+  })
+
+  it('assembles retained output across backward scrollback pages', async () => {
+    const { ctx, owner, stub } = await setup({ backendType: 'stub', maxOutputChars: 1_000 })
+    await call(ctx, owner, 'warm up')
+    const session = stub.sessions[0]!
+    session.mode = 'paged-scrollback'
+    session.scrollback = 'older one\nolder two\nolder three\nolder four\n'
+
+    expect(text(await call(ctx, owner, 'paged output'))).toBe('hello from stub')
+  })
+
+  it('sanitizes a prompt fallback reached after multiple polling rounds', async () => {
+    const { ctx, owner, stub } = await setup({ backendType: 'stub', maxOutputChars: 1_000 })
+    await call(ctx, owner, 'warm up')
+    const session = stub.sessions[0]!
+    session.mode = 'prompt-after-idle'
+    session.scrollback = ''
+    const result = text(await call(ctx, owner, 'bad {'))
+    expect(result).toContain('partial syntax output')
+    expect(result).toContain('pwsh: syntax error')
+    expect(result).not.toContain('DSH_PERSISTENT_PWSH_PROMPT')
+    expect(result).not.toContain('DSH_PERSISTENT_PWSH_START')
+  })
+
+  it('does not attribute old scrollback truncation to a complete current command', async () => {
+    const { ctx, owner, stub } = await setup({ backendType: 'stub', maxOutputChars: 1_000 })
+    await call(ctx, owner, 'warm up')
+    stub.sessions[0]!.historyTruncated = true
+    const result = text(await call(ctx, owner, 'short command'))
+    expect(result).toBe('hello from stub')
+    expect(result).not.toContain('<response clipped>')
+    expect(result).not.toContain('beginning of this command output was dropped')
+  })
+
+  it('closes a timed-out shell and reports bounded partial output', async () => {
+    const { ctx, owner, stub } = await setup({ backendType: 'stub', timeoutMs: 10 })
+    await call(ctx, owner, 'warm up')
+    stub.sessions[0]!.mode = 'wait-for-abort'
+    const result = await call(ctx, owner, 'hang')
+    expect(text(result)).toContain('timed out after 0 seconds or experienced an OOM error')
+    expect(text(result)).toContain('partial output')
+    expect(text(result)).toContain('next pwsh call starts from the workspace')
+    expect(stub.sessions[0]?.closed).toContain('persistent pwsh command timed out')
+  })
+
+  it.each(['wait-for-abort', 'end-on-abort'] as const)(
+    'cancels %s work, resets the shell, and releases a queued call',
+    async (mode) => {
+      const { ctx, owner, stub } = await setup({ backendType: 'stub', timeoutMs: 5_000 })
+      await call(ctx, owner, 'warm up')
+      stub.sessions[0]!.mode = mode
+      const controller = new AbortController()
+      const cancelled = call(ctx, owner, 'hang', controller.signal)
+      const queued = call(ctx, owner, 'after cancellation')
+      setTimeout(() => {
+        controller.abort(new Error('caller stopped'))
+      }, 5)
+
+      expect((await cancelled).isError).toBe(true)
+      expect(text(await queued)).toBe('hello from stub')
+      expect(stub.sessions[0]?.closed).toContain('persistent pwsh command aborted')
+      expect(stub.sessions).toHaveLength(2)
+    },
+  )
+
+  it.each(['init-exit', 'init-timeout'] as const)(
+    'fails initialization and closes the unusable shell for %s',
+    async (mode) => {
+      const { ctx, owner, stub } = await setup({ backendType: 'stub' }, mode)
+      expect((await call(ctx, owner, 'pwd')).isError).toBe(true)
+      expect(stub.sessions[0]?.closed).toContain('persistent pwsh initialization failed')
+    },
+  )
+
+  it('clears a failed spawn without trying to close an unpublished shell', async () => {
+    const { ctx, owner, stub } = await setup({ backendType: 'stub' }, 'spawn-error')
+    expect((await call(ctx, owner, 'pwd')).isError).toBe(true)
+    expect(stub.sessions).toHaveLength(0)
+  })
+
+  it('resets a cached shell after startSend fails', async () => {
+    const { ctx, owner, stub } = await setup()
+    await call(ctx, owner, 'warm up')
+    stub.sessions[0]!.mode = 'send-error'
+    expect((await call(ctx, owner, 'fails')).isError).toBe(true)
+    expect(stub.sessions[0]?.closed).toContain('persistent pwsh send failed')
+    expect(text(await call(ctx, owner, 'recovers'))).toBe('hello from stub')
+    expect(stub.sessions).toHaveLength(2)
+  })
+
+  it('cancels and awaits a pending shell spawn when the plugin is disposed', async () => {
+    const ctx = new Context()
+    contexts.push(ctx)
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(TerminalSessionService)
+    const spawnStarted = Promise.withResolvers<undefined>()
+    const spawnAborted = Promise.withResolvers<undefined>()
+    ctx.terminals.registerBackend({
+      type: 'slow',
+      spawn: spec => new Promise((_resolve, reject) => {
+        spawnStarted.resolve(undefined)
+        spec.signal?.addEventListener('abort', () => {
+          spawnAborted.resolve(undefined)
+          const reason: unknown = spec.signal?.reason
+          reject(reason instanceof Error
+            ? reason
+            : new Error('slow PTY spawn aborted', { cause: reason }))
+        }, { once: true })
+      }),
+    })
+    const fiber = await ctx.plugin(ToolPwshPersistent, { backendType: 'slow' })
+    const owner = agent(ctx, '/workspace')
+    const running = call(ctx, owner, 'pwd')
+    await spawnStarted.promise
+    await fiber.dispose()
+    await spawnAborted.promise
+    expect((await running).isError).toBe(true)
+    expect(ctx.terminals.list(owner)).toEqual([])
+  })
+
+  it('rejects invalid config and invalid calls', async () => {
+    const { ctx, owner, stub } = await setup()
+    expect((await call(ctx, undefined, 'pwd')).isError).toBe(true)
+    expect(text(await call(ctx, owner, ' '))).toContain('command must be a non-empty string')
+
+    const controller = new AbortController()
+    controller.abort(new Error('caller stopped'))
+    expect((await call(ctx, owner, 'pwd', controller.signal)).isError).toBe(true)
+    expect(stub.sessions).toHaveLength(0)
+
+    expect(() => {
+      ToolPwshPersistent.apply(new Context(), { backendType: '' })
+    }).toThrow('backendType must be non-empty')
+    expect(() => {
+      ToolPwshPersistent.apply(new Context(), { timeoutMs: 0 })
+    }).toThrow('timeoutMs must be a positive safe integer')
+    expect(() => {
+      ToolPwshPersistent.apply(new Context(), { maxOutputChars: 0 })
+    }).toThrow('maxOutputChars must be a positive safe integer')
+    expect(() => {
+      ToolPwshPersistent.apply(new Context(), { description: ' ' })
+    }).toThrow('description must be non-empty')
+  })
+})
@@ -0,0 +1,17 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": ["src"],
+  "references": [
+    { "path": "../../../vendor/cordis" },
+    { "path": "../../../vendor/schemastery" },
+    { "path": "../../core/agent" },
+    { "path": "../../core/tools" },
+    { "path": "../../terminal/terminal" },
+    { "path": "../../runtime-diagnostics/invariants" },
+    { "path": "../../util/timeout" }
+  ]
+}
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/shell/tool-pwsh/README.md
-README.md: af1de3d84c8815f9875faaa8e2fd6a79dff018c2
-README.zh.md: 67c1e20a1e993f242fa660c71de36a4f4b38bf5d
+README.md: e862fcf0ca85d0ecb0a5fe6cff3ee3c7a8153716
+README.zh.md: 0a66b119ac2bf0386c0686e9e22ddfe1c3bb87b1
@@ -121,6 +121,6 @@ Append-only; newly visible content follows the reusable request prefix and does
 ## Known Limitations and Deferred Work

 - **Language mode and named-pipe capture under the Windows sandbox** — under the [Windows ACL sandbox](../../sandbox/sandbox-windows-acl/README.md), read-only pwsh starts in ConstrainedLanguage because its temp write denial makes PowerShell's AppLocker probe fail closed: `Add-Type`, non-core .NET statics (`[System.IO.*]::`, `[math]::`), COM objects, and reflection fail with "only core types" errors, and the mode cannot be lifted from inside. Workspace-write's private temp lets the probe complete, so it stays in FullLanguage unless host policy says otherwise. Both confined modes deny named-pipe opens, so a piped-stdio spawn inside a confined command fails with EPERM. The tool description teaches both contracts to the model; the backend README owns the full limitations.
- **No persistent shell or PTY** — every call starts a fresh `pwsh -Command`; the PTY backends are Linux/macOS-only today, and a Windows ConPTY persistent shell is roadmap work.
+- **No persistent shell** — every call starts a fresh `pwsh -Command`; the persistent-shell counterpart is [`@deepseek-ai/dsh-tool-pwsh-persistent`](../tool-pwsh-persistent/README.md), which keeps one owner-scoped pwsh alive across calls on Windows (ConPTY) and POSIX hosts with pwsh.
 - **PowerShell-dialect contract** — the model must write PowerShell (native paths, `$env:` variables), not bash; there is no dialect translation.
 - **Session-cwd identity is not canonicalized** — the workdir base is the session header cwd as-is, unlike the bash tool's sandbox-root-canonicalized identity. Under a confining executor the policy's workspace root IS canonicalized (by the shared policy service), so the workdir and the confinement root can diverge when the raw session cwd differs from its canonical form — a parity gap deferred to the shared shell-tool base extraction.
@@ -121,6 +121,6 @@ ack 是固定短行；任务输出按读取有界。
 ## 已知限制与暂缓事项

 - **Windows 沙箱下的语言模式与 named-pipe 捕获** — 在 [Windows ACL 沙箱](../../sandbox/sandbox-windows-acl/README.zh.md) 下，read-only pwsh 会以 ConstrainedLanguage 启动，因为临时目录写入被拒绝，导致 PowerShell 的 AppLocker 探针失败并按 fail-closed 处理：`Add-Type`、非核心 .NET 静态调用（`[System.IO.*]::`、`[math]::`）、COM 对象与反射都会以“only core types”错误失败，且该模式无法从内部解除。workspace-write 的私有临时目录使探针得以完成，因此除非主机策略另有规定，否则它保持 FullLanguage。两种受限模式都拒绝 named-pipe 打开，因此受限命令内的管道 stdio spawn 以 EPERM 失败。工具描述把这两个约定教给模型；后端 README 负责完整的限制说明。
- **无持久 shell 或 PTY** — 每次调用都启动全新的 `pwsh -Command`；PTY 后端目前仅限 Linux/macOS，Windows ConPTY 持久 shell 属于路线图工作。
+- **无持久 shell** — 每次调用都启动全新的 `pwsh -Command`；持久 shell 对应物是 [`@deepseek-ai/dsh-tool-pwsh-persistent`](../tool-pwsh-persistent/README.zh.md)，它在 Windows（ConPTY）以及装有 pwsh 的 POSIX 主机上跨调用保持一个 owner 作用域的 pwsh 存活。
 - **PowerShell 方言约定** — 模型必须写 PowerShell（原生路径、`$env:` 变量），而不是 bash；没有方言翻译。
 - **会话 cwd 身份不做规范化** — workdir 基座直接取会话头 cwd 原值，不同于 bash 工具经 sandbox-root 规范化的身份。在隔离执行器下，策略的工作区根**会**被规范化（由共享的策略服务完成），因此当原始会话 cwd 与其规范化形态不同时，workdir 与隔离根可能不一致——这一 parity 差距留待共享 shell 工具基座提取时解决。
@@ -1,7 +1,7 @@
 {
  "name": "@deepseek-ai/dsh-tool-pwsh",
  "description": "Model-facing pwsh tool over the bash executor seam",
-  "version": "0.1.0-rc.7",
+  "version": "0.1.0-rc.8",
  "publishConfig": {
    "access": "public"
  },