refactor(pty): follow the naming-contract renames across the persistent pwsh stack

.agents/notes/implemented/architecture/2026-08-11-pwsh-persistent-pty.md

@@ -1,4 +1,4 @@
-# Agent Note: Persistent pwsh over the PTY seam on Windows
+# Agent Note: Persistent pwsh over the terminal seam on Windows
 
 Status: implemented
 
@@ -6,15 +6,15 @@ English | [中文](2026-08-11-pwsh-persistent-pty.zh.md)
 
 ## Problem
 
-The harness had no persistent shell on Windows. The persistent `bash` stack was POSIX-only by construction: `@deepseek-ai/dsh-subprocess-local` threw at terminal allocation (`createProcessInspector()` rejected win32), `@deepseek-ai/dsh-pty-local` was bash-shaped (`/bin/bash` defaults, `PS1`/`PROMPT_COMMAND` environment markers), `@deepseek-ai/dsh-tool-bash-persistent` wrapped commands in bash syntax, and every pty test skipped on win32. The one-shot `pwsh` tool (`@deepseek-ai/dsh-tool-pwsh` over `@deepseek-ai/dsh-pwsh-local`) already ran on Windows, but each call started a fresh `pwsh -Command` process: cwd, `$env:` variables, functions, and interactive children ended with the call, and its README recorded "No persistent shell or PTY" as deferred work.
+The harness had no persistent shell on Windows. The persistent `bash` stack was POSIX-only by construction: `@deepseek-ai/dsh-subprocess-local` threw at terminal allocation (`createProcessInspector()` rejected win32), `@deepseek-ai/dsh-terminal-bash` was bash-shaped (`/bin/bash` defaults, `PS1`/`PROMPT_COMMAND` environment markers), `@deepseek-ai/dsh-tool-bash-persistent` wrapped commands in bash syntax, and every pty test skipped on win32. The one-shot `pwsh` tool (`@deepseek-ai/dsh-tool-pwsh` over `@deepseek-ai/dsh-pwsh-local`) already ran on Windows, but each call started a fresh `pwsh -Command` process: cwd, `$env:` variables, functions, and interactive children ended with the call, and its README recorded "No persistent shell or PTY" as deferred work.
 
 The gap excluded Windows workflows whose state lives in a terminal: stepping a debugger, exploring in a Python or Node REPL, or returning to a shell after interrupting its foreground command — the same class of work the persistent bash pty serves on POSIX.
 
-Two foundations already existed. The PTY service itself (`ctx.pty` registry, owner scoping, send/read/signal/kill contract) is platform-neutral. The Loader's `disabled: !!js` interpolation (PR #2234) gates shell rows per platform and pins the invariant that exactly one shell stack mounts per host; a persistent pwsh stack composes through the same rows.
+Two foundations already existed. the terminal service itself (`ctx.terminals` registry, owner scoping, send/read/signal/kill contract) is platform-neutral. The Loader's `disabled: !!js` interpolation (PR #2234) gates shell rows per platform and pins the invariant that exactly one shell stack mounts per host; a persistent pwsh stack composes through the same rows.
 
 ## Decision
 
-A model-facing persistent `pwsh` tool ships on Windows with the same contract as `tool-bash-persistent`: one owner-scoped persistent shell per Agent, marker-detected command completion, exact native exit codes, bounded output, and timeout/cancel/`exit` semantics that reset the shell and tell the model. Three pieces deliver it: a Windows substrate in `subprocess-local`, a shell-dialect option in `pty-local`, and the new `tool-pwsh-persistent` package with the minimal-preset composition rows.
+A model-facing persistent `pwsh` tool ships on Windows with the same contract as `tool-bash-persistent`: one owner-scoped persistent shell per Agent, marker-detected command completion, exact native exit codes, bounded output, and timeout/cancel/`exit` semantics that reset the shell and tell the model. Three pieces deliver it: a Windows substrate in `subprocess-local`, a shell-dialect option in `terminal-bash`, and the new `tool-pwsh-persistent` package with the minimal-preset composition rows.
 
 ### Windows substrate in `@deepseek-ai/dsh-subprocess-local`
 
@@ -22,7 +22,7 @@ A model-facing persistent `pwsh` tool ships on Windows with the same contract as
 
 `LocalTerminalHandle` branches for win32 because node-pty's `kill(signal)` throws ("Signals not supported on windows") and its bare kill delegates to a console-list agent that fails without a parent console. Teardown escalates through taskkill fenced on the shell's start identity, and — because an externally taskkilled shell may never fire node-pty's exit notification — the handle settles `done` from the inspector-verified absence (`settleExitIfGone`). `signalForeground` maps SIGINT to a `\x03` Ctrl-C input write (the console-wide delivery conhost turns into a CTRL_C event; verified to interrupt a running command), routes SIGTERM/SIGKILL to taskkill, and rejects SIGTSTP/SIGHUP as unavailable on Windows. The public `PtySignal` set and seam types are unchanged; the mapping lives in the backend.
 
-### Shell dialect in `@deepseek-ai/dsh-pty-local`
+### Shell dialect in `@deepseek-ai/dsh-terminal-bash`
 
 One backend, two dialects: `shellDialect: 'bash' | 'pwsh'` (default `'bash'`, existing deployments byte-identical). The effective `shellPath`/`shellArgs` resolve per dialect (bash `/bin/bash --noprofile --norc -i`; pwsh through the shared `dsh-pwsh-local` resolver with `-NoLogo -NoProfile`, keeping the interactive host for child REPLs). The child environment drops the bash-only `PS1`/`PROMPT_COMMAND` markers and adds `NO_COLOR` for pwsh. pwsh cannot install its prompt from the environment, so the backend writes the prompt function through the session at startup and waits until the controlled prompt is actually visible, looping over follow-up sends because the pwsh banner-to-prompt gap can outlast the silence bound; a `session_exit` or `timeout` wait rejects the spawn. Both dialects emit the same BEL-terminated OSC `133;D;` marker, so the sanitizer, `PROMPT_MARKER_PREFIX`, `CONTROLLED_PROMPT`, and the exact-tail readiness logic are reused untouched — the marker stays a readiness signal with an unconsumed payload, exactly as in the bash path, and no model-notification channel was added (aligned with the current implementation; the deferred BEL event channel stays deferred).
 
@@ -34,11 +34,11 @@ Commands run through a wrapper that resets `$LASTEXITCODE` (assignable, verified
 
 ### Composition
 
-The minimal preset gates its persistent shell stack by platform with the #2234 `disabled: !!js` interpolation: the bash rows (`pty-local` + `tool-bash-persistent`) mount on POSIX, and the pwsh rows (`pty-local` with `shellDialect: pwsh` + `tool-pwsh-persistent`) mount on win32 — exactly one persistent shell per host. `windows-shell.spec` pins the per-platform roster; the real Loader composition exercises the whole stack over a real ConPTY pwsh.
+The minimal preset gates its persistent shell stack by platform with the #2234 `disabled: !!js` interpolation: the bash rows (`terminal-bash` + `tool-bash-persistent`) mount on POSIX, and the pwsh rows (`terminal-bash` with `shellDialect: pwsh` + `tool-pwsh-persistent`) mount on win32 — exactly one persistent shell per host. `windows-shell.spec` pins the per-platform roster; the real Loader composition exercises the whole stack over a real ConPTY pwsh.
 
 ### Testing
 
-The Windows test surface follows master's exemption structure: pty-local and subprocess-local tests stay excluded on win32 (`windowsUnsupportedTests`) and their sources stay coverage-exempt there (`windowsUnsupportedCoveragePackages`), so the platform-gated fixtures and node-translated commands remain the win32 dev-lane evidence, while the koffi-backed inspector joins the windows-only coverage exclusions on Linux. `tool-pwsh-persistent` is not exempt: its suite runs and its sources are coverage-required on the windows-native lane, mirroring `tool-bash-persistent`'s stub-mode matrix plus an echo-stripping mode; the real-pwsh suites prove persistent cwd/env, secret scrubbing, multiline and here-string commands, large-output clipping, and exit/reset over real ConPTY sessions.
+The Windows test surface follows master's exemption structure: terminal-bash and subprocess-local tests stay excluded on win32 (`windowsUnsupportedTests`) and their sources stay coverage-exempt there (`windowsUnsupportedCoveragePackages`), so the platform-gated fixtures and node-translated commands remain the win32 dev-lane evidence, while the koffi-backed inspector joins the windows-only coverage exclusions on Linux. `tool-pwsh-persistent` is not exempt: its suite runs and its sources are coverage-required on the windows-native lane, mirroring `tool-bash-persistent`'s stub-mode matrix plus an echo-stripping mode; the real-pwsh suites prove persistent cwd/env, secret scrubbing, multiline and here-string commands, large-output clipping, and exit/reset over real ConPTY sessions.
 
 ## Alternatives considered
 
@@ -54,7 +54,7 @@ The Windows test surface follows master's exemption structure: pty-local and sub
 
 **Windows became a first-class persistent-shell host.** The persistent pwsh stack runs and is coverage-gated on the windows-native lane; the one-shot/persistent shell split mirrors POSIX, and the preset spec pins exactly one shell stack per host on both platforms.
 
-**Windows coverage keeps master's exemption structure.** subprocess-local and pty-local sources stay coverage-exempt and their suites test-excluded on win32 exactly as on master; the Windows code paths are exercised through the win32 dev lane and the real-pwsh tool suites, and the new surface's coverage obligation on the windows-native lane sits on `tool-pwsh-persistent`.
+**Windows coverage keeps master's exemption structure.** subprocess-local and terminal-bash sources stay coverage-exempt and their suites test-excluded on win32 exactly as on master; the Windows code paths are exercised through the win32 dev lane and the real-pwsh tool suites, and the new surface's coverage obligation on the windows-native lane sits on `tool-pwsh-persistent`.
 
 **Windows readiness is weaker than Linux.** The pseudo-pgid marker fast path covers shell prompts, but a child without a prompt settles on the silence tier (~3 s), exactly like macOS; there is no exact stdin-wait tier.
 

.agents/notes/implemented/architecture/2026-08-11-pwsh-persistent-pty.zh.md

@@ -1,4 +1,4 @@
-# Agent Note: Windows 上基于 PTY seam 的持久化 pwsh
+# Agent Note: Windows 上基于 terminal seam 的持久化 pwsh
 
 Status: implemented
 
@@ -6,15 +6,15 @@ Status: implemented
 
 ## 问题
 
-harness 在 Windows 上没有持久 shell。持久 `bash` 栈按构造就是 POSIX-only：`@deepseek-ai/dsh-subprocess-local` 在终端分配时直接抛错（`createProcessInspector()` 拒绝 win32），`@deepseek-ai/dsh-pty-local` 是 bash 形态（`/bin/bash` 默认值、`PS1`/`PROMPT_COMMAND` 环境标记），`@deepseek-ai/dsh-tool-bash-persistent` 用 bash 语法包装命令，pty 测试全部在 win32 上 skip。一次性 `pwsh` 工具（`@deepseek-ai/dsh-tool-pwsh` + `@deepseek-ai/dsh-pwsh-local`）已经能在 Windows 运行，但每次调用都是全新的 `pwsh -Command` 进程：cwd、`$env:` 变量、函数和交互式子进程都随调用结束，其 README 把 "No persistent shell or PTY" 记为 deferred work。
+harness 在 Windows 上没有持久 shell。持久 `bash` 栈按构造就是 POSIX-only：`@deepseek-ai/dsh-subprocess-local` 在终端分配时直接抛错（`createProcessInspector()` 拒绝 win32），`@deepseek-ai/dsh-terminal-bash` 是 bash 形态（`/bin/bash` 默认值、`PS1`/`PROMPT_COMMAND` 环境标记），`@deepseek-ai/dsh-tool-bash-persistent` 用 bash 语法包装命令，pty 测试全部在 win32 上 skip。一次性 `pwsh` 工具（`@deepseek-ai/dsh-tool-pwsh` + `@deepseek-ai/dsh-pwsh-local`）已经能在 Windows 运行，但每次调用都是全新的 `pwsh -Command` 进程：cwd、`$env:` 变量、函数和交互式子进程都随调用结束，其 README 把 "No persistent shell or PTY" 记为 deferred work。
 
 这个缺口排除了状态驻留在终端里的 Windows 工作流：单步调试、在 Python 或 Node REPL 中探索、中断前台命令后回到原 shell —— 正是持久 bash pty 在 POSIX 上服务的同一类工作。
 
-两个基础已经存在。PTY 服务本身（`ctx.pty` 注册表、owner 作用域、send/read/signal/kill 契约）是平台无关的。Loader 的 `disabled: !!js` 插值（PR #2234）按平台门控 shell 行，并钉死了"每宿主恰好挂载一个 shell 栈"的不变量；持久 pwsh 栈通过同一行机制组合。
+两个基础已经存在。PTY 服务本身（`ctx.terminals` 注册表、owner 作用域、send/read/signal/kill 契约）是平台无关的。Loader 的 `disabled: !!js` 插值（PR #2234）按平台门控 shell 行，并钉死了"每宿主恰好挂载一个 shell 栈"的不变量；持久 pwsh 栈通过同一行机制组合。
 
 ## 决定
 
-模型侧持久 `pwsh` 工具在 Windows 上交付，契约与 `tool-bash-persistent` 逐项对齐：每个 Agent 一个 owner 作用域的持久 shell、标记检测的命令完成、精确的原生退出码、有界输出，以及超时/取消/`exit` 时重置 shell 并告知模型的语义。三块交付：`subprocess-local` 的 Windows 基座、`pty-local` 的 shell 方言选项、新的 `tool-pwsh-persistent` 包加 minimal 预设组合行。
+模型侧持久 `pwsh` 工具在 Windows 上交付，契约与 `tool-bash-persistent` 逐项对齐：每个 Agent 一个 owner 作用域的持久 shell、标记检测的命令完成、精确的原生退出码、有界输出，以及超时/取消/`exit` 时重置 shell 并告知模型的语义。三块交付：`subprocess-local` 的 Windows 基座、`terminal-bash` 的 shell 方言选项、新的 `tool-pwsh-persistent` 包加 minimal 预设组合行。
 
 ### `@deepseek-ai/dsh-subprocess-local` 的 Windows 基座
 
@@ -22,7 +22,7 @@ harness 在 Windows 上没有持久 shell。持久 `bash` 栈按构造就是 POS
 
 `LocalTerminalHandle` 为 win32 分支，因为 node-pty 的 `kill(signal)` 会抛错（"Signals not supported on windows"），其无参 kill 委托的 console-list agent 在没有父控制台时失败。拆卸经 taskkill 升级并以 shell 的启动身份作栅栏；由于被外部 taskkill 的 shell 可能永远不会触发 node-pty 的退出通知，句柄从 inspector 验证的消失状态结算 `done`（`settleExitIfGone`）。`signalForeground` 把 SIGINT 映射为 `\x03` Ctrl-C 输入写入（conhost 转为控制台级 CTRL_C 事件的投递方式；实测可中断运行中的命令），SIGTERM/SIGKILL 路由到 taskkill，SIGTSTP/SIGHUP 以 Windows 不可用为由拒绝。公共 `PtySignal` 集合与 seam 类型不变；映射全部留在 backend。
 
-### `@deepseek-ai/dsh-pty-local` 的 shell 方言
+### `@deepseek-ai/dsh-terminal-bash` 的 shell 方言
 
 一个 backend、两种方言：`shellDialect: 'bash' | 'pwsh'`（默认 `'bash'`，存量部署逐字节不变）。有效 `shellPath`/`shellArgs` 按方言解析（bash `/bin/bash --noprofile --norc -i`；pwsh 经共享的 `dsh-pwsh-local` 解析器取 `-NoLogo -NoProfile`，保留交互宿主供子 REPL）。子环境去掉 bash 专属 `PS1`/`PROMPT_COMMAND` 标记并为 pwsh 加 `NO_COLOR`。pwsh 无法从环境安装提示符，因此 backend 在启动时通过会话写入 prompt 函数，并等待受控提示符真正可见——因为 pwsh 从横幅到提示符的间隙可能超过静默上限，所以会在后续 send 上循环等待；`session_exit` 或 `timeout` 结算拒绝 spawn。两种方言发出相同的 BEL 终结 OSC `133;D;` 标记，因此 sanitizer、`PROMPT_MARKER_PREFIX`、`CONTROLLED_PROMPT` 与精确尾部就绪逻辑原样复用——标记仍只是就绪信号、载荷不被消费，与 bash 路径完全一致，且没有新增模型通知通道（与当前实现对齐；延后的 BEL 事件通道保持延后）。
 
@@ -34,11 +34,11 @@ harness 在 Windows 上没有持久 shell。持久 `bash` 栈按构造就是 POS
 
 ### 组合
 
-minimal 预设用 #2234 的 `disabled: !!js` 插值按平台门控持久 shell 栈：bash 行（`pty-local` + `tool-bash-persistent`）在 POSIX 挂载，pwsh 行（`shellDialect: pwsh` 的 `pty-local` + `tool-pwsh-persistent`）在 win32 挂载——每宿主恰好一个持久 shell。`windows-shell.spec` 钉死按平台的花名册；真实 Loader 组合在真实 ConPTY pwsh 上跑通整条栈。
+minimal 预设用 #2234 的 `disabled: !!js` 插值按平台门控持久 shell 栈：bash 行（`terminal-bash` + `tool-bash-persistent`）在 POSIX 挂载，pwsh 行（`shellDialect: pwsh` 的 `terminal-bash` + `tool-pwsh-persistent`）在 win32 挂载——每宿主恰好一个持久 shell。`windows-shell.spec` 钉死按平台的花名册；真实 Loader 组合在真实 ConPTY pwsh 上跑通整条栈。
 
 ### 测试
 
-Windows 测试面沿用 master 的豁免结构：pty-local 与 subprocess-local 的测试在 win32 上继续排除（`windowsUnsupportedTests`），其源码在 win32 上继续覆盖豁免（`windowsUnsupportedCoveragePackages`），平台门控 fixture 与 node 翻译命令因此仍是 win32 开发车道的证据；koffi-backed inspector 在 Linux 侧加入 windows-only 覆盖豁免。`tool-pwsh-persistent` 不在豁免之列：其套件在 windows-native 车道上运行、源码受覆盖约束，镜像 `tool-bash-persistent` 的 stub 模式矩阵并加回显剥离模式；真实 pwsh 套件在真实 ConPTY 会话上证明持久 cwd/env、密钥清洗、多行与 here-string 命令、大输出裁剪与退出/重置。
+Windows 测试面沿用 master 的豁免结构：terminal-bash 与 subprocess-local 的测试在 win32 上继续排除（`windowsUnsupportedTests`），其源码在 win32 上继续覆盖豁免（`windowsUnsupportedCoveragePackages`），平台门控 fixture 与 node 翻译命令因此仍是 win32 开发车道的证据；koffi-backed inspector 在 Linux 侧加入 windows-only 覆盖豁免。`tool-pwsh-persistent` 不在豁免之列：其套件在 windows-native 车道上运行、源码受覆盖约束，镜像 `tool-bash-persistent` 的 stub 模式矩阵并加回显剥离模式；真实 pwsh 套件在真实 ConPTY 会话上证明持久 cwd/env、密钥清洗、多行与 here-string 命令、大输出裁剪与退出/重置。
 
 ## 备选方案
 
@@ -54,7 +54,7 @@ Windows 测试面沿用 master 的豁免结构：pty-local 与 subprocess-local
 
 **Windows 成为一等公民的持久 shell 宿主。** 持久 pwsh 栈在 windows-native 车道上运行并受覆盖门禁约束；一次性/持久 shell 的划分与 POSIX 镜像，预设 spec 在两种平台上都钉死每宿主恰好一个 shell 栈。
 
-**Windows 覆盖沿用 master 的豁免结构。** subprocess-local 与 pty-local 源码在 win32 上保持覆盖豁免、其套件保持测试排除，与 master 完全一致；Windows 代码路径经 win32 开发车道与真实 pwsh 工具套件验证，新表面的覆盖义务在 windows-native 车道上落在 `tool-pwsh-persistent`。
+**Windows 覆盖沿用 master 的豁免结构。** subprocess-local 与 terminal-bash 源码在 win32 上保持覆盖豁免、其套件保持测试排除，与 master 完全一致；Windows 代码路径经 win32 开发车道与真实 pwsh 工具套件验证，新表面的覆盖义务在 windows-native 车道上落在 `tool-pwsh-persistent`。
 
 **Windows 就绪弱于 Linux。** 伪 pgid marker 快路径覆盖 shell 提示符，但没有提示符的子进程按静默档结算（约 3s），与 macOS 完全一致；没有精确的 stdin-wait 档。
 

apps/cli/tests/windows-shell.spec.ts

@@ -142,17 +142,17 @@ describe('shipped agent presets gate both shell tools by platform', () => {
     const byId = new Map(rows
       .filter((entry): entry is Record<string, unknown> => typeof entry === 'object' && entry !== null)
       .map(entry => [entry.id, entry]))
-    // The bash stack (pty-local + persistent-bash) mounts on POSIX only; the
-    // pwsh twin (pty-local with shellDialect pwsh + persistent-pwsh) mounts on
+    // The bash stack (terminal-bash + persistent-bash) mounts on POSIX only; the
+    // pwsh twin (terminal-bash with shellDialect pwsh + persistent-pwsh) mounts on
     // win32 only — exactly one persistent shell per host.
-    for (const id of ['pty-local', 'persistent-bash']) {
+    for (const id of ['terminal-bash', 'persistent-bash']) {
       expect(disabledOn(byId.get(id)!, 'win32'), `${id} on win32`).toBe(true)
       expect(disabledOn(byId.get(id)!, 'linux'), `${id} on linux`).toBe(false)
     }
-    for (const id of ['pty-pwsh', 'persistent-pwsh']) {
+    for (const id of ['terminal-pwsh', 'persistent-pwsh']) {
       expect(disabledOn(byId.get(id)!, 'win32'), `${id} on win32`).toBe(false)
       expect(disabledOn(byId.get(id)!, 'linux'), `${id} on linux`).toBe(true)
     }
-    expect(byId.get('pty-pwsh')?.config).toMatchObject({ shellDialect: 'pwsh' })
+    expect(byId.get('terminal-pwsh')?.config).toMatchObject({ shellDialect: 'pwsh' })
   })
 })

packages/e2b/e2b/tests/composition.e2e.ts

@@ -97,7 +97,7 @@ describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
         whenIdle: () => Promise.resolve(),
       }
       const backend = new BashTerminalBackend(ctx, {
-        backendType: 'shell', shellPath: '/bin/bash', shellArgs: ['--noprofile', '--norc', '-i'],
+        backendType: 'shell', shellDialect: 'bash', shellPath: '/bin/bash', shellArgs: ['--noprofile', '--norc', '-i'],
         rows: 24, cols: 80,
         scrollbackLines: 100, scrollbackMaxBytes: 65_536, maxReadBytes: 16_384,
         pollIntervalMs: 25, exactProbeAfterMs: 150, idleSilenceMs: 1_000,

packages/shell/tool-bash-persistent/src/index.ts

@@ -208,7 +208,7 @@ async function respondToSessionExit(
   ctx: Context,
   shells: PersistentShells,
   owner: Agent,
-  id: PtySessionId,
+  id: TerminalSessionId,
   status: { exitCode: number | null; signal: NodeJS.Signals | null },
   marker: CommandMarkers,
   fallback: string,
@@ -319,7 +319,7 @@ async function executeCommand(
     // 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.pty.list(owner).find(session => session.sessionId === id)?.status
+    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,

packages/pty/tool-pwsh-persistent/README.i18n.yaml → packages/shell/tool-pwsh-persistent/README.i18n.yaml

@@ -1,6 +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/pty/tool-pwsh-persistent/README.md
-README.md: 32fcaf15d38648c347e6423c9b68753ccca91287
-README.zh.md: 8c2201657796d2d6bd39ea5d130ee246a58e17d9
+#   pnpm run verify-translation-pairing --write packages/shell/tool-pwsh-persistent/README.md
+README.md: 7bb66477ab7ffe52039b0c699d48c9ca761ac04c
+README.zh.md: b20041b1d42908d4d1e893455d825eafa2e2f87d

packages/pty/tool-pwsh-persistent/README.md → packages/shell/tool-pwsh-persistent/README.md

@@ -2,13 +2,13 @@
 
 English | [中文](README.zh.md)
 
-Model-facing `pwsh(command)` backed by one owner-scoped `ctx.pty` shell. The package owns the tool contract and shell reuse; deployments select the PTY backend (a `pty-local` instance configured with `shellDialect: pwsh`) and sandbox policy. It is the Windows counterpart of `tool-bash-persistent`: same persistent-state contract, PowerShell dialect.
+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 PTY backend used for each Agent shell. |
+| `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. |
@@ -33,7 +33,7 @@ Prefix-stable while the configured description and schema remain unchanged.
 
 #### 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 PTY has already dropped that prefix, the result says so explicitly. Timeout returns bounded partial output, closes the uncertain shell, and reports the reset.
+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
 
@@ -45,7 +45,7 @@ Append-only tool results follow the reusable request prefix.
 
 ## Known Limitations and Deferred Work
 
-- The tool requires an owning Agent and a real PTY backend with a pwsh dialect (Windows ConPTY or a POSIX pwsh).
+- 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.

packages/pty/tool-pwsh-persistent/README.zh.md → packages/shell/tool-pwsh-persistent/README.zh.md

@@ -2,13 +2,13 @@
 
 [English](README.md) | 中文
 
-模型侧 `pwsh(command)`，由一个 owner 作用域的 `ctx.pty` shell 支撑。本包拥有工具契约与 shell 复用；部署方选择 PTY backend（配置 `shellDialect: pwsh` 的 `pty-local` 实例）与沙箱策略。它是 `tool-bash-persistent` 的 Windows 对应物：相同的持久状态契约，PowerShell 方言。
+模型侧 `pwsh(command)`，由一个 owner 作用域的 `ctx.terminals` shell 支撑。本包拥有工具契约与 shell 复用；部署方选择 terminal backend（配置 `shellDialect: pwsh` 的 `terminal-bash` 实例）与沙箱策略。它是 `tool-bash-persistent` 的 Windows 对应物：相同的持久状态契约，PowerShell 方言。
 
 ## 配置
 
 | 键 | 默认值 | 含义 |
 |---|---:|---|
-| `backendType` | `shell` | 每个 Agent shell 使用的已注册 PTY backend。 |
+| `backendType` | `shell` | 每个 Agent shell 使用的已注册 terminal backend。 |
 | `timeoutMs` | `300000` | 单条命令的墙钟上限；超时关闭 shell。 |
 | `maxOutputChars` | `16000` | 保留的命令输出字符上限；固定诊断文本在其后追加。 |
 | `description` | 持久 shell 描述 | 模型可见的环境契约。 |
@@ -45,7 +45,7 @@
 
 ## 已知限制与延后工作
 
-- 工具需要拥有 Agent 与一个真实支持 pwsh 方言的 PTY backend（Windows ConPTY 或 POSIX 上的 pwsh）。
+- 工具需要拥有 Agent 与一个真实支持 pwsh 方言的 terminal backend（Windows ConPTY 或 POSIX 上的 pwsh）。
 - **输入回显不可避免**：PowerShell 的 PSReadLine 会把提交的输入渲染回终端流，且没有 `stty -echo` 的对应物。完整结果中 marker 锚定提取排除回显；包装器原文剥离覆盖回退路径，但跨越终端宽度的包装器折行可能在部分输出结果中残留片段回显，受 `maxOutputChars` 约束。
 - 模型命令中的裸 ESC 字符不受支持：PSReadLine 会在执行前吞掉它们。包装器转义它需要的控制字节（`[char]27` 构造的 OSC 标记、body 的反引号转义）。
 - 模型重定义 `prompt` 函数会移除就绪标记；shell 随后退化为静默档而非 marker 快路径。

packages/pty/tool-pwsh-persistent/package.json → packages/shell/tool-pwsh-persistent/package.json

@@ -8,7 +8,7 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
-    "directory": "packages/pty/tool-pwsh-persistent"
+    "directory": "packages/shell/tool-pwsh-persistent"
   },
   "type": "module",
   "main": "lib/index.js",
@@ -33,7 +33,7 @@
   "peerDependencies": {
     "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
-    "@deepseek-ai/dsh-pty": "workspace:^",
+    "@deepseek-ai/dsh-terminal": "workspace:^",
     "@deepseek-ai/dsh-timeout": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
     "@deepseek-ai/cordis": "workspace:^"
@@ -47,8 +47,8 @@
     "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
-    "@deepseek-ai/dsh-pty": "workspace:^",
-    "@deepseek-ai/dsh-pty-local": "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:^",

packages/pty/tool-pwsh-persistent/src/index.ts → packages/shell/tool-pwsh-persistent/src/index.ts

@@ -7,7 +7,7 @@ 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 { PtyReadResult, PtySendResult, PtySessionId } from '@deepseek-ai/dsh-pty'
+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'
 
@@ -48,7 +48,7 @@ interface CapturedOutput {
 }
 
 interface PersistentShells {
-  get(owner: Agent, signal: AbortSignal): Promise<PtySessionId>
+  get(owner: Agent, signal: AbortSignal): Promise<TerminalSessionId>
   reset(owner: Agent, reason: string): Promise<void>
 }
 
@@ -128,7 +128,7 @@ function commandOutput(
   }
 }
 
-function promptCompleted(result: PtySendResult): boolean {
+function promptCompleted(result: TerminalSendResult): boolean {
   return result.viewport.endsWith(SHELL_PROMPT)
     || result.viewport.endsWith(`${SHELL_PROMPT}\r\n`)
     || result.viewport.endsWith(`${SHELL_PROMPT}\n`)
@@ -164,7 +164,7 @@ async function pause(): Promise<void> {
   await new Promise(resolve => setTimeout(resolve, POLL_INTERVAL_MS))
 }
 
-function nextScrollbackOffset(page: PtyReadResult, offset: number): number | undefined {
+function nextScrollbackOffset(page: TerminalReadResult, offset: number): number | undefined {
   if (page.text.length === 0 || page.lineEnd <= offset) return undefined
   return page.lineEnd
 }
@@ -172,15 +172,15 @@ function nextScrollbackOffset(page: PtyReadResult, offset: number): number | und
 function retainedScrollback(
   ctx: Context,
   owner: Agent,
-  id: PtySessionId,
-  latest = ctx.pty.read(owner, id, { offset: 0, count: SCROLLBACK_PAGE_LINES }),
+  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.pty.read(owner, id, { offset, count: SCROLLBACK_PAGE_LINES })
+    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)
@@ -230,7 +230,7 @@ async function respondToSessionExit(
   ctx: Context,
   shells: PersistentShells,
   owner: Agent,
-  id: PtySessionId,
+  id: TerminalSessionId,
   status: { exitCode: number | null; signal: NodeJS.Signals | null },
   marker: CommandMarkers,
   wrapped: string,
@@ -260,15 +260,15 @@ 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<PtySessionId>>()
-  const live = new Map<Agent, PtySessionId>()
-  const creating = new Set<Promise<PtySessionId>>()
+  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: PtySessionId, reason: string): Promise<void> => {
-    if (!ctx.pty.list(owner).some(snapshot => snapshot.sessionId === id)) return
-    await ctx.pty.kill(owner, id, reason)
+  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 () => {
@@ -286,14 +286,14 @@ function persistentShells(ctx: Context, config: ResolvedConfig): PersistentShell
     if (id !== undefined) await close(owner, id, reason)
   }
 
-  const get = (owner: Agent, signal: AbortSignal): Promise<PtySessionId> => {
+  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.pty.spawn(owner, {
+        const spawned = await ctx.terminals.spawn(owner, {
           type: config.backendType,
           ...cwd === undefined ? {} : { cwd },
         }, combinedSignal)
@@ -305,7 +305,7 @@ function persistentShells(ctx: Context, config: ResolvedConfig): PersistentShell
             live.delete(owner)
           }, 'tool-pwsh-persistent owner cache cleanup')
         }
-        const setup = ctx.pty.startSend(owner, spawned.sessionId, {
+        const setup = ctx.terminals.startSend(owner, spawned.sessionId, {
           text: PWSH_PROMPT_SETUP,
           submit: true,
           signal: combinedSignal,
@@ -352,7 +352,7 @@ async function executeCommand(
     // 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.pty.list(owner).find(session => session.sessionId === id)?.status
+    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,
@@ -361,7 +361,7 @@ async function executeCommand(
     let operation
     let result
     try {
-      operation = ctx.pty.startSend(owner, id, {
+      operation = ctx.terminals.startSend(owner, id, {
         text: first ? wrapped : '',
         submit: first,
         signal: commandDeadline.signal,
@@ -375,7 +375,7 @@ async function executeCommand(
     const incremental = operation.readOutput()
     fallback = incremental.delta.length > 0 ? fallback + incremental.delta : result.viewport
     fallbackTruncated ||= incremental.truncated || result.truncated
-    const latest = ctx.pty.read(owner, id, { offset: 0, count: SCROLLBACK_PAGE_LINES })
+    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)
@@ -464,7 +464,7 @@ function registerPersistentPwsh(ctx: Context, config: ResolvedConfig): void {
 }
 
 export const name = 'tool-pwsh-persistent'
-export const inject = ['tools', 'pty']
+export const inject = ['tools', 'terminals']
 
 /** Configuration for the persistent pwsh tool. */
 export interface Config {

packages/pty/tool-pwsh-persistent/tests/loader-composition.spec.ts → packages/shell/tool-pwsh-persistent/tests/loader-composition.spec.ts

@@ -11,8 +11,8 @@ 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 PtyService from '@deepseek-ai/dsh-pty'
-import * as PtyLocal from '@deepseek-ai/dsh-pty-local'
+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'
@@ -78,14 +78,14 @@ describe.skipIf(!hasPwsh)('persistent pwsh through a real cordis.yml Loader comp
       "- name: '@deepseek-ai/dsh-agent'",
       "- name: '@deepseek-ai/dsh-system-prompt'",
       "- name: '@deepseek-ai/dsh-tools'",
-      "- name: '@deepseek-ai/dsh-pty'",
+      "- 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-pty-local'",
+      "- name: '@deepseek-ai/dsh-terminal-bash'",
       '  config:',
       '    shellDialect: pwsh',
       '    pollIntervalMs: 10',
@@ -109,11 +109,11 @@ describe.skipIf(!hasPwsh)('persistent pwsh through a real cordis.yml Loader comp
       ['@deepseek-ai/dsh-agent', AgentRegistry],
       ['@deepseek-ai/dsh-system-prompt', SystemPrompt],
       ['@deepseek-ai/dsh-tools', ToolRegistry],
-      ['@deepseek-ai/dsh-pty', PtyService],
+      ['@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-pty-local', PtyLocal],
+      ['@deepseek-ai/dsh-terminal-bash', TerminalBash],
       ['@deepseek-ai/dsh-tool-pwsh-persistent', ToolPwshPersistent],
     ])
     context.loader.internal = {

packages/pty/tool-pwsh-persistent/tests/tools.spec.ts → packages/shell/tool-pwsh-persistent/tests/tools.spec.ts

@@ -4,17 +4,17 @@ 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 PtyService from '@deepseek-ai/dsh-pty'
+import TerminalSessionService from '@deepseek-ai/dsh-terminal'
 import type {
-  PtyBackend,
-  PtyBackendSession,
-  PtyReadRequest,
-  PtySendOperation,
-  PtySendRequest,
-  PtySessionStatus,
-  PtySignal,
-  PtyWaitReason,
-} from '@deepseek-ai/dsh-pty'
+  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'
@@ -104,10 +104,10 @@ type StubMode =
 const START_PATTERN = /__DSH_PERSISTENT_PWSH_START_[^_]+(?:-[^_]+)*__/
 const END_PATTERN = /__DSH_PERSISTENT_PWSH_END_[^:]+:/
 
-class StubPtySession implements PtyBackendSession {
+class StubTerminalSession implements TerminalBackendSession {
   readonly motd = '__DSH_PERSISTENT_PWSH_PROMPT__ '
   readonly pid = 123
-  statusValue: PtySessionStatus = { kind: 'running' }
+  statusValue: TerminalSessionStatus = { kind: 'running' }
   scrollback = this.motd
   closed: string[] = []
   mode: StubMode
@@ -120,7 +120,7 @@ class StubPtySession implements PtyBackendSession {
     this.mode = mode
   }
 
-  startSend(request: PtySendRequest): PtySendOperation {
+  startSend(request: TerminalSendRequest): TerminalSendOperation {
     this.sends += 1
     if (request.text.startsWith('function prompt')) {
       if (this.mode === 'init-exit') {
@@ -135,7 +135,7 @@ class StubPtySession implements PtyBackendSession {
     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) => {
+      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]
@@ -232,7 +232,7 @@ class StubPtySession implements PtyBackendSession {
     return this.operation(Promise.resolve(this.result(output, 'stdin_read')))
   }
 
-  read(request: PtyReadRequest) {
+  read(request: TerminalReadRequest) {
     if (this.mode === 'empty-read') {
       return { text: '', totalLines: 0, lineBegin: 0, lineEnd: 0, truncated: false }
     }
@@ -265,7 +265,7 @@ class StubPtySession implements PtyBackendSession {
     }
   }
 
-  signal(_signal: PtySignal) {
+  signal(_signal: TerminalSignal) {
     return Promise.resolve({ delivered: true as const, targetPgid: 123 })
   }
 
@@ -278,11 +278,11 @@ class StubPtySession implements PtyBackendSession {
     this.statusValue = { kind: 'exited', exitCode: 0, signal: null }
   }
 
-  private result(viewport: string, waitReason: PtyWaitReason) {
+  private result(viewport: string, waitReason: TerminalWaitReason) {
     return { viewport, waitReason, sessionStatus: this.statusValue, truncated: false }
   }
 
-  private operation(done: Promise<ReturnType<StubPtySession['result']>>, delta = ''): PtySendOperation {
+  private operation(done: Promise<ReturnType<StubTerminalSession['result']>>, delta = ''): TerminalSendOperation {
     return {
       done,
       readOutput: () => ({ delta, truncated: false }),
@@ -292,12 +292,12 @@ class StubPtySession implements PtyBackendSession {
 }
 
 function stubBackend(initialMode: StubMode = 'normal') {
-  const sessions: StubPtySession[] = []
-  const backend: PtyBackend = {
+  const sessions: StubTerminalSession[] = []
+  const backend: TerminalBackend = {
     type: 'stub',
     async spawn() {
       if (initialMode === 'spawn-error') throw new Error('stub spawn failed')
-      const session = new StubPtySession(initialMode)
+      const session = new StubTerminalSession(initialMode)
       sessions.push(session)
       return session
     },
@@ -314,9 +314,9 @@ async function setup(
   await ctx.plugin(SystemPrompt)
   await ctx.plugin(ToolRegistry)
   await ctx.plugin(AgentRegistry)
-  await ctx.plugin(PtyService)
+  await ctx.plugin(TerminalSessionService)
   const stub = stubBackend(initialMode)
-  ctx.pty.registerBackend(stub.backend)
+  ctx.terminals.registerBackend(stub.backend)
   const fiber = await ctx.plugin(ToolPwshPersistent, config)
   return { ctx, stub, fiber, owner: agent(ctx, '/workspace') }
 }
@@ -433,9 +433,9 @@ describe('tool-pwsh-persistent', () => {
 
     await call(ctx, owner, 'another shell')
     expect(stub.sessions).toHaveLength(3)
-    const externallyClosed = ctx.pty.list(owner)[0]?.sessionId
+    const externallyClosed = ctx.terminals.list(owner)[0]?.sessionId
     expect(externallyClosed).toBeDefined()
-    await ctx.pty.kill(owner, externallyClosed!, 'external cleanup')
+    await ctx.terminals.kill(owner, externallyClosed!, 'external cleanup')
     await fiber.dispose()
     expect(stub.sessions[2]?.closed).toEqual(['external cleanup'])
   })
@@ -572,10 +572,10 @@ describe('tool-pwsh-persistent', () => {
     await ctx.plugin(SystemPrompt)
     await ctx.plugin(ToolRegistry)
     await ctx.plugin(AgentRegistry)
-    await ctx.plugin(PtyService)
+    await ctx.plugin(TerminalSessionService)
     const spawnStarted = Promise.withResolvers<undefined>()
     const spawnAborted = Promise.withResolvers<undefined>()
-    ctx.pty.registerBackend({
+    ctx.terminals.registerBackend({
       type: 'slow',
       spawn: spec => new Promise((_resolve, reject) => {
         spawnStarted.resolve(undefined)
@@ -595,7 +595,7 @@ describe('tool-pwsh-persistent', () => {
     await fiber.dispose()
     await spawnAborted.promise
     expect((await running).isError).toBe(true)
-    expect(ctx.pty.list(owner)).toEqual([])
+    expect(ctx.terminals.list(owner)).toEqual([])
   })
 
   it('rejects invalid config and invalid calls', async () => {

packages/pty/tool-pwsh-persistent/tsconfig.json → packages/shell/tool-pwsh-persistent/tsconfig.json

@@ -10,8 +10,8 @@
     { "path": "../../../vendor/schemastery" },
     { "path": "../../core/agent" },
     { "path": "../../core/tools" },
-    { "path": "../pty" },
-    { "path": "../../support/invariants" },
+    { "path": "../../terminal/terminal" },
+    { "path": "../../runtime-diagnostics/invariants" },
     { "path": "../../util/timeout" }
   ]
 }

packages/terminal/terminal-bash/tests/local.spec.ts

@@ -259,7 +259,7 @@ const hasPwsh = spawnSync(
   { encoding: 'utf8' },
 ).status === 0
 
-describe.skipIf(!hasPwsh)('pty-local pwsh real shell', () => {
+describe.skipIf(!hasPwsh)('terminal-bash pwsh real shell', () => {
   it('bootstraps a persistent pwsh, persists state, and scrubs secrets', async () => {
     const previous = process.env.DSH_TEST_SECRET
     process.env.DSH_TEST_SECRET = 'must-not-leak'
@@ -269,15 +269,15 @@ describe.skipIf(!hasPwsh)('pty-local pwsh real shell', () => {
         handoffGraceMs: 300,
         timeoutMs: 8_000,
       }, 'pwsh')
-      const created = await ctx.pty.spawn(agent, { type: 'shell', name: 'main', cwd: root })
+      const created = await ctx.terminals.spawn(agent, { type: 'shell', name: 'main', cwd: root })
       expect(created.motd).toContain('dsh> ')
 
-      const first = ctx.pty.startSend(agent, created.sessionId, {
+      const first = ctx.terminals.startSend(agent, created.sessionId, {
         text: '$env:KEEP = "ok"; Set-Location /',
         submit: true,
       })
       expect((await first.done).waitReason).toBe('stdin_read')
-      const second = ctx.pty.startSend(agent, created.sessionId, {
+      const second = ctx.terminals.startSend(agent, created.sessionId, {
         text: 'Write-Output "keep=$env:KEEP secret=$env:DSH_TEST_SECRET"',
         submit: true,
       })
@@ -286,9 +286,9 @@ describe.skipIf(!hasPwsh)('pty-local pwsh real shell', () => {
       expect(result.viewport).toContain('secret=')
       expect(result.viewport).not.toContain('must-not-leak')
 
-      expect(ctx.pty.read(agent, created.sessionId, { offset: 0, count: 40 }).text).toContain('keep=ok')
-      expect(await ctx.pty.kill(agent, created.sessionId)).toBe(true)
-      expect(ctx.pty.list(agent)).toEqual([])
+      expect(ctx.terminals.read(agent, created.sessionId, { offset: 0, count: 40 }).text).toContain('keep=ok')
+      expect(await ctx.terminals.kill(agent, created.sessionId)).toBe(true)
+      expect(ctx.terminals.list(agent)).toEqual([])
     } finally {
       if (previous === undefined) delete process.env.DSH_TEST_SECRET
       else process.env.DSH_TEST_SECRET = previous

packages/terminal/terminal-bash/tsconfig.json

@@ -18,7 +18,7 @@
       "path": "../../../vendor/schemastery"
     },
     {
-      "path": "../../bash/pwsh-local"
+      "path": "../../shell/pwsh-local"
     },
     {
       "path": "../../core/agent"

packages/workflow/workflow-worker-thread/tests/workflow-worker-thread.spec.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it, vi } from 'vitest'
+import { tmpdir } from 'node:os'
 import { fileURLToPath } from 'node:url'
 import type { Worker } from 'node:worker_threads'
 import { Context } from '@deepseek-ai/cordis'
@@ -9,6 +10,7 @@ import type { SubagentCapabilities, SubagentProvider, SubagentResult, SubagentRu
 import type { WorkflowMeta, WorkflowResult, WorkflowResultInfo, WorkflowRun, WorkflowRunInfo } from '@deepseek-ai/dsh-workflow'
 import * as workerEngineModule from '../src/index.ts'
 import WorkerThreadWorkflowEngine, { type Config } from '../src/index.ts'
+import { workerSpawnEnv } from '../src/host.ts'
 import { HostToWorkerType, WorkerToHostType } from '../src/protocol.ts'
 import { SessionId } from '@deepseek-ai/dsh-session'
 
@@ -559,24 +561,44 @@ describe('dsh-workflow-worker-thread', () => {
       expect(result.value).toBe('fine')
     })
 
-    it('the worker spawns with an EMPTY environment: an escaped script finds no ambient credentials', async () => {
+    it('the worker spawns with a scrubbed environment: an escaped script finds no ambient credentials', async () => {
       const { ctx, parent } = await setup()
       // A canary in the HARNESS process's env: with an inherited environment
       // the escape below would read it back (exactly how DEEPSEEK_API_KEY
-      // would leak); env: {} in the spawn options is what keeps it out.
+      // would leak); the worker env keeps every ambient variable out. Windows
+      // additionally receives the host temp path (TMP/TEMP) so `os.tmpdir()`
+      // inside the worker resolves instead of degrading to a cwd-relative
+      // `undefined\temp` (tsx writes its transform cache there).
       process.env.WORKFLOW_ENV_CANARY = 'leak me'
       try {
         const result = await run(ctx, parent, scripted(`
           const proc = ${ESCAPE}
-          return { canary: proc.env.WORKFLOW_ENV_CANARY ?? null, keys: Object.keys(proc.env).length }
+          return { canary: proc.env.WORKFLOW_ENV_CANARY ?? null, keys: Object.keys(proc.env).sort() }
         `))
         expect(result.stopReason).toBe('completed')
-        expect(result.value).toEqual({ canary: null, keys: 0 })
+        const expectedKeys = process.platform === 'win32' ? ['TEMP', 'TMP'] : []
+        expect(result.value).toEqual({ canary: null, keys: expectedKeys })
       } finally {
         delete process.env.WORKFLOW_ENV_CANARY
       }
     })
 
+    it('workerSpawnEnv injects the host temp path on win32 and leaves the POSIX peer empty', () => {
+      const tmp = tmpdir()
+      expect(workerSpawnEnv('win32')).toEqual({ TMP: tmp, TEMP: tmp })
+      expect(workerSpawnEnv('linux')).toEqual({})
+    })
+
+    it('workerSpawnEnv forwards TSX_TSCONFIG_PATH when the snapshot harness pins it', () => {
+      const tsconfig = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url))
+      expect(workerSpawnEnv('linux', tsconfig)).toEqual({ TSX_TSCONFIG_PATH: tsconfig })
+      expect(workerSpawnEnv('win32', tsconfig)).toEqual({
+        TMP: tmpdir(),
+        TEMP: tmpdir(),
+        TSX_TSCONFIG_PATH: tsconfig,
+      })
+    })
+
     it('the unbuilt worker forwards exactly TSX_TSCONFIG_PATH through the scrub: the paths-map pin survives, secrets do not', async () => {
       const { ctx, parent } = await setup()
       // The ACP snapshot harness runs the parent with its cwd OUTSIDE the
@@ -589,10 +611,13 @@ describe('dsh-workflow-worker-thread', () => {
       try {
         const result = await run(ctx, parent, scripted(`
           const proc = ${ESCAPE}
-          return { keys: Object.keys(proc.env), tsconfig: proc.env.TSX_TSCONFIG_PATH }
+          return { keys: Object.keys(proc.env).sort(), tsconfig: proc.env.TSX_TSCONFIG_PATH }
         `))
         expect(result.stopReason).toBe('completed')
-        expect(result.value).toEqual({ keys: ['TSX_TSCONFIG_PATH'], tsconfig })
+        const expectedKeys = process.platform === 'win32'
+          ? ['TEMP', 'TMP', 'TSX_TSCONFIG_PATH']
+          : ['TSX_TSCONFIG_PATH']
+        expect(result.value).toEqual({ keys: expectedKeys, tsconfig })
       } finally {
         delete process.env.TSX_TSCONFIG_PATH
         delete process.env.WORKFLOW_ENV_CANARY

scripts/gen-tool-catalog.ts

@@ -281,11 +281,11 @@ const TOOL_PACKAGES: ToolPackage[] = [
   {
     pkg: '@deepseek-ai/dsh-tool-pwsh-persistent',
     dir: 'tool-pwsh-persistent',
-    source: 'packages/pty/tool-pwsh-persistent/src/index.ts',
-    requires: ['ctx.tools', 'ctx.pty', 'an owning Agent at execution time'],
+    source: 'packages/shell/tool-pwsh-persistent/src/index.ts',
+    requires: ['ctx.tools', 'ctx.terminals', 'an owning Agent at execution time'],
     writes: ['tool/call', 'PTY shell state', 'tool/result'],
     async mount(ctx) {
-      await ctx.plugin(PtyService)
+      await ctx.plugin(TerminalSessionService)
       await ctx.plugin(ToolPwshPersistent)
     },
     note: