Merge branch 'stack/agent-profiles-5-web-ui' of github.com:deepseek-harness/deepseek-harness into stack/agent-profiles-8-authoring

packages/README.i18n.yaml

@@ -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/README.md
-README.md: fcbe4859954efa20f41a5a7e26bc0f1406cbe7f8
-README.zh.md: 304b95c4fa47ced455411b03529b77956cfb2953
+README.md: d1e579633ea597c46003af97ab9a47e5e616ca73
+README.zh.md: aa6577413899627a947b446ef8f6545492c880cb

packages/README.md

@@ -6,7 +6,7 @@ Packages use the `@deepseek-ai/dsh-*` scope. Cordis `Service` subclasses and fun
 
 ## Hierarchy
 
-Packages live at `packages/<group>/<pkg>/`; groups are containers, while names remain `@deepseek-ai/dsh-<pkg>`. **Each group README is the canonical package/ctx-key map.**
+Groups hold `packages/<group>/<pkg>/`; names stay `@deepseek-ai/dsh-<pkg>`. **Group READMEs own package/ctx-key maps.**
 
 | Group | Role | Release expectation |
 |---|---|---|
@@ -16,6 +16,7 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
 | [`goal/`](goal/README.md) | Same-session goal persistence and lifecycle | Product — stable surface |
 | [`feedback/`](feedback/README.md) | Human feedback | Product — stable surface |
 | [`llm/`](llm/README.md) | LLM capability family: the abstract service + provider adapters | Product — stable surface |
+| [`e2b/`](e2b/README.md) | E2B providers | POC |
 | [`subprocess/`](subprocess/README.md) | Subprocess capability family: spawn seam + local process-tree implementation | Product — stable surface |
 | [`bash/`](bash/README.md) | Bash capability family: executor seam, local impl, model-facing tool | Product — stable surface |
 | [`pty/`](pty/README.md) | Persistent PTY capability family: owner-scoped sessions, local implementation, and model-facing tools | Product — stable surface |

packages/README.zh.md

@@ -6,7 +6,7 @@
 
 ## 层级结构
 
-包位于 `packages/<group>/<pkg>/`；组是容器，包名仍为 `@deepseek-ai/dsh-<pkg>`。**每个组 README 是规范的包／ctx 键映射。**
+包按组置于 `packages/<group>/<pkg>/`；包名仍为 `@deepseek-ai/dsh-<pkg>`。**组 README 负责包／ctx 键映射。**
 
 | 组 | 职责 | 发布预期 |
 |---|---|---|
@@ -16,6 +16,7 @@
 | [`goal/`](goal/README.md) | 同会话 goal 的持久化与生命周期 | 产品：稳定表面 |
 | [`feedback/`](feedback/README.md) | 人类反馈 | 产品：稳定表面 |
 | [`llm/`](llm/README.md) | LLM（大语言模型）能力系列：抽象服务 + 提供方适配器 | 产品：稳定表面 |
+| [`e2b/`](e2b/README.md) | E2B 提供方 | POC |
 | [`subprocess/`](subprocess/README.md) | 进程管理能力系列：spawn seam + 本地进程树实现 | 产品：稳定表面 |
 | [`bash/`](bash/README.md) | Bash 能力系列：执行器 seam、本地实现、面向模型的工具 | 产品：稳定表面 |
 | [`pty/`](pty/README.md) | 持久 PTY 能力系列：按所有者隔离的会话、本地实现和面向模型的工具 | 产品：稳定表面 |

packages/bash/pwsh-local/tests/executor.spec.ts

@@ -119,6 +119,8 @@ describe('spawn construction (pure, every platform)', () => {
   /** A subprocess service that records spawn specs and settles instantly. */
   class CapturingSubprocessService extends SubprocessService {
     specs: SubprocessSpawnSpec[] = []
+    override async resolveExecutable(command: string): Promise<string> { return command }
+    override spawnTerminal(): Promise<never> { throw new Error('pwsh spawns pipes, never terminals') }
     private readonly reader: SubprocessOutputReader = {
       readFrom: () => ({ text: '', lossy: false, nextOffset: 0 }),
     }

packages/context/workspace-context/tests/workspace-context.spec.ts

@@ -75,6 +75,14 @@ class RecordingFileSystem extends FileSystem {
     return { targetKey: FsTargetKey(absolute), displayPath: absolute }
   }
 
+  override processPath(target: FsTarget): string { return String(target.targetKey) }
+
+  override fileUrl(target: FsTarget): string { return `file://${target.targetKey}` }
+
+  override contains(parent: FsTarget, child: FsTarget): boolean {
+    return child.targetKey === parent.targetKey || String(child.targetKey).startsWith(`${parent.targetKey}/`)
+  }
+
   override async stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined> {
     if (signal !== undefined) this.signals.push(signal)
     signal?.throwIfAborted()

packages/cordis/tool-cordis/src/api-catalog.ts

@@ -346,6 +346,16 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
     ],
   },
+  {
+    key: 'e2b',
+    summary: 'Creates one lazily consumable E2B SDK handle and deletes the sandbox at timeout or disposal.',
+    methods: [
+      {
+        signature: 'async getSandbox(): Promise<Sandbox>',
+        jsDoc: '/**\n * Return the shared live SDK handle.\n * @returns the created sandbox after the configured cwd exists.\n * @throws when E2B rejects creation or the service is disposing.\n */',
+      },
+    ],
+  },
   {
     key: 'fs',
     summary: 'Abstract filesystem provider.',
@@ -354,6 +364,18 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         signature: 'abstract resolve(path: string, opts?: { cwd?: string; signal?: AbortSignal }): Promise<FsTarget>',
         jsDoc: '/**\n * Resolve a model/plugin-supplied path into a stable {@link FsTarget}. May perform I/O (a\n * remote/sandboxed backend may need a round-trip to map a path to a stable identity), hence\n * async even though the local backend only normalizes + realpaths.\n *\n * @param path - the path to resolve; relative paths resolve against `opts.cwd`.\n * @param opts - optional cwd override and cancellation signal.\n * @returns the stable target; the same file yields the same `targetKey`.\n */',
       },
+      {
+        signature: 'abstract processPath(target: FsTarget): string',
+        jsDoc: '/**\n * Return the canonical absolute path a subprocess in this filesystem\'s\n * execution world can open. The path is deliberately separate from\n * {@link FsTarget.targetKey}: consumers may pass this value to another OS\n * capability, but must continue treating the target key as opaque.\n * @param target - the resolved target whose process path is required.\n * @returns an absolute path in the backend\'s execution world.\n */',
+      },
+      {
+        signature: 'abstract fileUrl(target: FsTarget): string',
+        jsDoc: '/**\n * Return the canonical `file:` URI for a target in this filesystem\'s\n * execution world. Backends own URI encoding because the host platform may\n * differ from the execution platform.\n * @param target - the resolved target to encode.\n * @returns the target\'s canonical file URI.\n */',
+      },
+      {
+        signature: 'abstract contains(parent: FsTarget, child: FsTarget): boolean',
+        jsDoc: '/**\n * Test canonical containment without exposing or parsing backend target\n * keys. Both targets must come from this provider.\n * @param parent - canonical directory target.\n * @param child - canonical candidate target.\n * @returns true when `child` is `parent` or a descendant of it.\n */',
+      },
       {
         signature: 'abstract stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined>',
         jsDoc: '/**\n * Return target metadata, or `undefined` when the target does not exist.\n * @param target - the resolved target to stat.\n * @param signal - aborts the metadata round-trip.\n * @returns metadata only, never content; undefined for an absent target.\n */',
@@ -1016,10 +1038,18 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
     key: 'subprocess',
     summary: 'Abstract subprocess service.',
     methods: [
+      {
+        signature: 'abstract resolveExecutable( command: string, env?: Readonly<Record<string, string>>, signal?: AbortSignal, ): Promise<string>',
+        jsDoc: '/**\n * Resolve one configured executable in this provider\'s execution world.\n * Absolute paths are verified; bare names use the provider\'s scrubbed PATH\n * plus explicit environment overrides. Relative paths containing separators\n * are rejected: no current consumer defines which directory they would\n * resolve against, so providers fail loud instead of guessing.\n * @param command - absolute executable path or bare PATH name.\n * @param env - explicit environment entries used for lookup.\n * @param signal - aborts remote or local lookup.\n * @returns a canonical executable path.\n */',
+      },
       {
         signature: 'abstract spawn(spec: SubprocessSpawnSpec): SubprocessHandle',
         jsDoc: '/**\n * Start one managed child process from a fully-specified spec; this seam\n * applies no defaults.\n * @param spec - argv, directory, stdio dispositions, grace, cancellation, and environment.\n * @returns the live process handle (streams/readers, signalling, outcome promise).\n */',
       },
+      {
+        signature: 'abstract spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle>',
+        jsDoc: '/**\n * Allocate a real terminal and start one owned process session. This is the\n * only non-pipe process primitive: implementations own terminal byte I/O,\n * foreground groups, signals, and complete session-tree cleanup.\n * @param spec - fully specified argv, cwd, environment, dimensions, grace, and allocation cancellation.\n * @returns the live terminal handle after allocation succeeds.\n */',
+      },
     ],
   },
   {
@@ -2933,6 +2963,22 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'SubprocessStdio',
     declaration: 'export interface SubprocessStdio {\n    stdin: SubprocessStdinMode;\n    stdout: SubprocessOutputMode;\n    stderr: SubprocessOutputMode;\n}',
   },
+  {
+    name: 'SubprocessTerminalForeground',
+    declaration: 'export interface SubprocessTerminalForeground {\n    processGroupId: number;\n    inputWaiting: boolean;\n}',
+  },
+  {
+    name: 'SubprocessTerminalHandle',
+    declaration: 'export interface SubprocessTerminalHandle {\n    readonly pid: number;\n    readonly output: Readable;\n    readonly done: Promise<SubprocessOutcome>;\n    write(data: string): Promise<void>;\n    inspectForeground(): Promise<SubprocessTerminalForeground | undefined>;\n    signalForeground(signal: SubprocessTerminalSignal): Promise<number>;\n    terminate(): Promise<void>;\n}',
+  },
+  {
+    name: 'SubprocessTerminalSignal',
+    declaration: 'export type SubprocessTerminalSignal = \'SIGINT\' | \'SIGTERM\' | \'SIGKILL\' | \'SIGTSTP\' | \'SIGHUP\';',
+  },
+  {
+    name: 'SubprocessTerminalSpawnSpec',
+    declaration: 'export interface SubprocessTerminalSpawnSpec {\n    argv: readonly string[];\n    cwd: string;\n    env?: Record<string, string> | undefined;\n    rows: number;\n    cols: number;\n    graceMs: number;\n    signal?: AbortSignal | undefined;\n}',
+  },
   {
     name: 'SurfaceEvent',
     declaration: 'export type SurfaceEvent = SessionEvent<SurfaceEventType> & {\n    surfaceOp: SurfaceOp;\n};',

packages/e2b/README.i18n.yaml

@@ -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/e2b/README.md
+README.md: f9758e2748aaa2acffb0e928752b2b0fb70cd0a4
+README.zh.md: de068c16d4309499f5dcaa2d08cd9b6cc3023d94

packages/e2b/README.md

@@ -0,0 +1,15 @@
+# e2b/ — E2B remote runtime family
+
+English | [中文](README.zh.md)
+
+An experimental provider-composition POC that places one filesystem/process execution world in an E2B Linux sandbox. E2B supplies only sandbox lifecycle and the two fundamental OS adapters; provider-neutral consumers build higher capabilities above them.
+
+| Package | ctx key | Role |
+|---|---|---|
+| [`e2b`](e2b/README.md) (`@deepseek-ai/dsh-e2b`) | `ctx.e2b` | Create one sandbox, prepare its working/runtime directories, expose the shared SDK handle, and delete it on timeout or disposal |
+| [`fs-e2b`](fs-e2b/README.md) (`@deepseek-ai/dsh-fs-e2b`) | `ctx.fs` | Implement the filesystem seam over E2B Filesystem APIs |
+| [`subprocess-e2b`](subprocess-e2b/README.md) (`@deepseek-ai/dsh-subprocess-e2b`) | `ctx.subprocess` | Implement executable lookup, managed process groups and stdio, remote spill files, and terminal sessions over E2B Commands and PTY APIs |
+
+The existing [`dsh-bash-local`](../bash/bash-local/README.md), [`dsh-pty-local`](../pty/pty-local/README.md), and [`dsh-lsp-local`](../lsp/lsp-local/README.md) need no E2B-specific forks. They delegate every execution-world operation to `ctx.fs` and `ctx.subprocess`, so mounting the two E2B adapters places their mutable work in the same sandbox.
+
+This boundary does not move the harness process, Cordis objects, model calls, agent/session state, session persistence, skills, higher-level protocol state, or E2B SDK buffers. The [portable execution-world decision](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md) owns both the generic composition and this POC boundary.

packages/e2b/README.zh.md

@@ -0,0 +1,15 @@
+# e2b/ — E2B 远程运行时家族
+
+[English](README.md) | 中文
+
+这是一个实验性提供方组合 POC，把一个文件系统／进程执行环境放进 E2B Linux 沙箱。E2B 只提供沙箱生命周期与两个基础 OS 适配器；提供方无关的消费方在其上构建更高层能力。
+
+| 包（package） | ctx 键 | 职责 |
+|---|---|---|
+| [`e2b`](e2b/README.md)（`@deepseek-ai/dsh-e2b`） | `ctx.e2b` | 创建一个沙箱，准备其工作目录与运行时目录，公开共享 SDK 句柄，并在超时或资源释放时将其删除 |
+| [`fs-e2b`](fs-e2b/README.md)（`@deepseek-ai/dsh-fs-e2b`） | `ctx.fs` | 通过 E2B Filesystem API 实现文件系统 seam |
+| [`subprocess-e2b`](subprocess-e2b/README.md)（`@deepseek-ai/dsh-subprocess-e2b`） | `ctx.subprocess` | 通过 E2B Commands 与 PTY API 实现可执行文件查找、受管进程组与 stdio、远程 spill 文件及终端会话 |
+
+现有的 [`dsh-bash-local`](../bash/bash-local/README.md)、[`dsh-pty-local`](../pty/pty-local/README.md) 和 [`dsh-lsp-local`](../lsp/lsp-local/README.md) 无需 E2B 专用 fork。它们把执行环境中的所有操作委托给 `ctx.fs` 和 `ctx.subprocess`，因此挂载这两个 E2B 适配器后，它们执行的可变操作都发生在同一个沙箱内。
+
+该边界不会迁移 harness 进程、Cordis 对象、模型调用、agent（智能体）／会话状态、会话持久化、skill（技能）、更高层协议状态或 E2B SDK 缓冲。[可移植执行世界决策](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md)同时界定通用组合和此 POC 边界。

packages/e2b/e2b/README.i18n.yaml

@@ -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/e2b/e2b/README.md
+README.md: 7ade7c3d6522d8fa6d54d7011766238451b17c9a
+README.zh.md: b683f33d2211106cf422e780b2b37904b0c640ad

packages/e2b/e2b/README.md

@@ -0,0 +1,44 @@
+# @deepseek-ai/dsh-e2b
+
+English | [中文](README.zh.md)
+
+Shared lifecycle owner for one E2B sandbox. The filesystem and subprocess adapters inject `ctx.e2b`, await its single SDK handle, and therefore inhabit the same remote Linux working tree and process world. The package pins `e2b@2.29.1`; the [family map](../README.md) lists the opt-in composition.
+
+## Configuration
+
+```yaml
+- id: e2b
+  name: '@deepseek-ai/dsh-e2b'
+  config:
+    cwd: /home/user/workspace
+    timeoutMs: 300000
+
+- id: subprocess-e2b
+  name: '@deepseek-ai/dsh-subprocess-e2b'
+
+- id: fs-e2b
+  name: '@deepseek-ai/dsh-fs-e2b'
+```
+
+`apiKey` is optional and otherwise reads `E2B_API_KEY`; the key configures the host SDK connection and is never installed in the sandbox. `cwd` defaults to `/home/user/workspace` and must be an absolute POSIX path. `timeoutMs` defaults to five minutes and controls the sandbox lifetime; expiry deletes the sandbox.
+
+## Lifecycle and ownership
+
+Construction starts one sandbox creation. Before resolving `getSandbox()`, the service creates `cwd` and the private `cwd/.dsh-e2b` adapter-state directory, verifies that the reserved path is a real directory rather than a symlink or another file type, then sets it to mode `0700`. Each adapter-internal E2B command shell receives a fresh randomized root-level `HOME`, so the SDK's fixed login shell does not resolve profile files from the mutable user home before the control command.
+
+Disposal first prevents new handle acquisition, then awaits setup and deletes the sandbox. A `SandboxNotFoundError` means expiry or another owner already deleted it and is accepted as quiescence. Initial directory setup failure makes one deletion attempt; the configured E2B timeout bounds a second failure. Provider plugins must load after this owner and dispose before it.
+
+## Model Experience
+
+None, as this shared runtime owner registers no model-visible context; provider adapters and their consumers own any rendered effects.
+
+#### KV Cache effect
+
+No direct invalidation; this package does not contribute request tokens.
+
+## Known Limitations and Deferred Work
+
+- **This is not a whole-harness runtime** — Cordis services, agent/session state, session logs, LLM requests, skills, and SDK-side buffers stay in the host process.
+- **Sandbox state is ephemeral** — disposal and timeout delete the sandbox; reconnect, pause/leave retention, templates, volumes, and snapshots are outside this POC.
+- **No deployment platform is configured** — network policy, host-workspace synchronization, and sandbox discovery are outside this POC.
+- **`cwd` is a resolution convention, not containment** — adapters and commands can address other sandbox paths; E2B network access retains the base image's policy.

packages/e2b/e2b/README.zh.md

@@ -0,0 +1,44 @@
+# @deepseek-ai/dsh-e2b
+
+[English](README.md) | 中文
+
+一个 E2B 沙箱的共享生命周期所有者。文件系统与进程管理适配器注入 `ctx.e2b`，等待其唯一的 SDK 句柄，因此处于同一个远程 Linux 工作树与进程环境中。本包固定使用 `e2b@2.29.1`；可选组合见[包族索引](../README.md)。
+
+## 配置
+
+```yaml
+- id: e2b
+  name: '@deepseek-ai/dsh-e2b'
+  config:
+    cwd: /home/user/workspace
+    timeoutMs: 300000
+
+- id: subprocess-e2b
+  name: '@deepseek-ai/dsh-subprocess-e2b'
+
+- id: fs-e2b
+  name: '@deepseek-ai/dsh-fs-e2b'
+```
+
+`apiKey` 可省略；省略时读取 `E2B_API_KEY`。该密钥只配置宿主 SDK 连接，绝不会安装进沙箱。`cwd` 默认为 `/home/user/workspace`，并且必须是绝对 POSIX 路径。`timeoutMs` 默认为 5 分钟并控制沙箱生命周期；超时会删除沙箱。
+
+## 生命周期与所有权
+
+构造阶段会启动一次沙箱创建。服务在 `getSandbox()` 结算前创建 `cwd` 和私有的 `cwd/.dsh-e2b` 适配器状态目录，验证该预留路径是真实目录而非符号链接或其他文件类型，再把该目录的 mode 设为 `0700`。每个适配器内部的 E2B 命令 shell 都会获得一个位于根目录下、全新随机生成的 `HOME`，因此 SDK 固定使用的登录 shell 不会在控制命令之前解析可变用户主目录中的配置文件。
+
+资源释放会先阻止继续获取新句柄，再等待初始化完成，然后删除沙箱。`SandboxNotFoundError` 表示沙箱已因超时或被另一个所有者删除，因此可视为完全停稳。初始目录设置失败时会尝试删除一次；若该尝试也失败，则由已配置的 E2B 超时约束沙箱的存活时间。提供方插件必须在该所有者之后加载，并在其之前 dispose（资源释放）。
+
+## 模型体验
+
+无。本共享运行时所有者不注册模型可见上下文；提供方适配器及其消费方拥有所有渲染效果。
+
+#### KV Cache 影响
+
+不会直接失效；本包不会贡献请求 token。
+
+## 已知限制与延后工作
+
+- **这不是完整的 harness 运行时**：Cordis 服务、agent（智能体）／会话状态、会话日志、LLM（大语言模型）请求、skill（技能）和 SDK 侧缓冲仍留在宿主进程中。
+- **沙箱状态是短暂的**：资源释放和超时都会删除沙箱；重新连接、pause/leave 保留、模板、卷和快照均不在本 POC 范围内。
+- **没有配置部署平台**：网络策略、宿主工作区同步和沙箱发现均不在本 POC 范围内。
+- **`cwd` 是解析约定，而不是包含边界**：适配器和命令可以访问沙箱中的其他路径；E2B 网络访问也继续采用基础镜像的策略。

packages/e2b/e2b/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@deepseek-ai/dsh-e2b",
+  "description": "Shared E2B sandbox lifecycle for DeepSeek Harness provider adapters",
+  "version": "0.0.1",
+  "private": true,
+  "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"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "dependencies": {
+    "e2b": "2.29.1",
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-loader-smoke": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}

packages/e2b/e2b/src/index.ts

@@ -0,0 +1,182 @@
+/**
+ * Shared ownership of one E2B sandbox. Capability adapters await the same SDK
+ * handle, so filesystem and process operations inhabit one remote Linux world.
+ * @module @deepseek-ai/dsh-e2b
+ */
+
+import { randomUUID } from 'node:crypto'
+import { posix } from 'node:path'
+import { Context, Service } from 'cordis'
+import z from 'schemastery'
+import { FileType, Sandbox, SandboxNotFoundError } from 'e2b'
+
+export {
+  CommandExitError,
+  FileNotFoundError,
+  FileType,
+  Sandbox,
+  SandboxNotFoundError,
+} from 'e2b'
+export type { CommandHandle, CommandResult, EntryInfo } from 'e2b'
+
+/**
+ * Quote one opaque argument for the SDK's unavoidable `/bin/bash -l -c` layer.
+ * @param value - Exact argument value to preserve.
+ * @returns A single shell word with no interpolation.
+ */
+export function quoteE2BShellArg(value: string): string {
+  return `'${value.replaceAll('\'', "'\"'\"'")}'`
+}
+
+/**
+ * Isolate E2B's hard-coded login shell behind a fresh randomized home path.
+ * @param overrides - Additional environment entries for the internal command.
+ * @returns A fresh mutable map that the E2B SDK may extend.
+ */
+export function e2bControlEnvs(
+  overrides: Readonly<Record<string, string>> = {},
+): Record<string, string> {
+  return { ...overrides, HOME: `/.dsh-e2b-control-${randomUUID()}` }
+}
+
+/** Configuration for the shared E2B sandbox owner. */
+export interface Config {
+  /** API key; omission reads `E2B_API_KEY`. It is never forwarded into the sandbox. */
+  apiKey?: string
+  /** Shared remote working directory, created before adapters receive the sandbox. */
+  cwd?: string
+  /** E2B sandbox lifetime in milliseconds; expiry always deletes the sandbox. */
+  timeoutMs?: number
+}
+
+interface ResolvedConfig {
+  apiKey: string
+  cwd: string
+  timeoutMs: number
+}
+
+interface SchemaResolvedConfig extends Config {
+  cwd: string
+  timeoutMs: number
+}
+
+declare module 'cordis' {
+  interface Context {
+    e2b: E2BSandboxService
+  }
+}
+
+/**
+ * Creates one lazily consumable E2B SDK handle and deletes the sandbox at
+ * timeout or disposal. Creation begins at plugin construction; adapters await
+ * {@link getSandbox} before their first operation.
+ */
+export class E2BSandboxService extends Service {
+  static Config: z<Config> = z.object({
+    apiKey: z.string(),
+    cwd: z.string().default('/home/user/workspace'),
+    timeoutMs: z.number().default(300_000),
+  })
+
+  /** Validated remote working directory shared by provider adapters. */
+  readonly cwd: string
+  /** Remote directory reserved for adapter-owned process and terminal state. */
+  readonly runtimeRoot: string
+
+  private readonly config: ResolvedConfig
+  private readonly ready: Promise<Sandbox>
+  private disposed = false
+
+  constructor(ctx: Context, config: Config) {
+    super(ctx, 'e2b')
+    // Schemastery fills these fields before construction; the type does not encode that step.
+    const resolved = config as SchemaResolvedConfig
+    const apiKey = config.apiKey ?? process.env.E2B_API_KEY
+    this.config = {
+      apiKey: apiKey ?? '',
+      cwd: resolved.cwd,
+      timeoutMs: resolved.timeoutMs,
+    }
+    this.validate()
+    this.cwd = this.config.cwd
+    this.runtimeRoot = posix.join(this.cwd, '.dsh-e2b')
+    this.ready = this.open()
+    // A deployment may load the owner before any adapter uses it. Keep a
+    // failed eager connection observed; getSandbox() still returns the error.
+    void this.ready.catch(() => {})
+
+    ctx.effect(() => async () => {
+      this.disposed = true
+      let sandbox: Sandbox
+      try {
+        sandbox = await this.ready
+      } catch (_sandboxSetupFailure) {
+        // open() either acquired no sandbox or already made the POC's one rollback attempt.
+        return
+      }
+      try {
+        await sandbox.kill()
+      } catch (error: unknown) {
+        if (!(error instanceof SandboxNotFoundError)) throw error
+      }
+    }, 'e2b sandbox teardown')
+  }
+
+  /**
+   * Return the shared live SDK handle.
+   * @returns the created sandbox after the configured cwd exists.
+   * @throws when E2B rejects creation or the service is disposing.
+   */
+  async getSandbox(): Promise<Sandbox> {
+    if (this.disposed) throw new Error('E2B sandbox service is disposing')
+    const sandbox = await this.ready
+    // Disposal can race the awaited sandbox readiness despite the synchronous precheck.
+    // oxlint-disable-next-line typescript/no-unnecessary-condition -- Awaiting readiness yields to disposal.
+    if (this.disposed) throw new Error('E2B sandbox service is disposing')
+    return sandbox
+  }
+
+  private validate(): void {
+    if (this.config.apiKey.length === 0) {
+      throw new Error('dsh-e2b: configure apiKey or set E2B_API_KEY')
+    }
+    if (!posix.isAbsolute(this.config.cwd)) {
+      throw new Error(`dsh-e2b: cwd must be an absolute Linux path: ${this.config.cwd}`)
+    }
+    if (!Number.isFinite(this.config.timeoutMs) || this.config.timeoutMs <= 0) {
+      throw new Error('dsh-e2b: timeoutMs must be a positive finite number')
+    }
+  }
+
+  private async open(): Promise<Sandbox> {
+    const sandbox = await Sandbox.create({
+      apiKey: this.config.apiKey,
+      timeoutMs: this.config.timeoutMs,
+      secure: true,
+      lifecycle: { onTimeout: 'kill' },
+    })
+    try {
+      await sandbox.files.makeDir(this.cwd)
+      await sandbox.files.makeDir(this.runtimeRoot)
+      const runtimeRoot = await sandbox.files.getInfo(this.runtimeRoot)
+      if (runtimeRoot.type !== FileType.DIR || runtimeRoot.symlinkTarget !== undefined) {
+        throw new Error(`dsh-e2b: runtime root must be a real directory: ${this.runtimeRoot}`)
+      }
+      await sandbox.commands.run(
+        `chmod 700 -- ${quoteE2BShellArg(this.runtimeRoot)}`,
+        { envs: e2bControlEnvs() },
+      )
+      return sandbox
+    } catch (error: unknown) {
+      try {
+        await sandbox.kill()
+      } catch (_sandboxSetupRollbackFailure) {
+        // TODO(e2b-setup-rollback): Add retry state only if a real double failure
+        // outlives E2B's configured sandbox timeout.
+      }
+      throw error
+    }
+  }
+}
+
+export default E2BSandboxService

packages/e2b/e2b/src/invariant.ts

@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-e2b`.
+ * @module @deepseek-ai/dsh-e2b/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-e2b'
+
+/** Cordis companion plugin name. */
+export const name = 'e2b-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: sandbox creation and teardown have one SDK promise and
+ * no independent event or mutable-data relationship to cross-check.
+ */
+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 */

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

@@ -0,0 +1,182 @@
+import { access } from 'node:fs/promises'
+import { join, posix } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { Context } from 'cordis'
+import { describe, expect, it } from 'vitest'
+import { Inbox } from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
+import {
+  FileNotFoundError,
+  Sandbox,
+  SandboxNotFoundError,
+} from '@deepseek-ai/dsh-e2b'
+import PtyService, { PtySessionId } from '@deepseek-ai/dsh-pty'
+import { LocalPtyBackend } from '@deepseek-ai/dsh-pty-local'
+import { Session, SessionId } from '@deepseek-ai/dsh-session'
+import E2BSubprocessService from '@deepseek-ai/dsh-subprocess-e2b'
+
+const fixtureRoot = fileURLToPath(new URL('../../../../examples/headless-agent/tests/fixtures/e2b/e2b/', import.meta.url))
+const binScript = join(fixtureRoot, 'bin.ts')
+const configPath = join(fixtureRoot, 'cordis.yml')
+const tsconfigPath = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url))
+
+describe.skipIf(!process.env.E2B_API_KEY)('E2B live Loader composition', () => {
+  it('scrubs credentials before actual E2B command and PTY login shells', async () => {
+    const apiKey = process.env.E2B_API_KEY
+    if (apiKey === undefined) throw new Error('E2B_API_KEY disappeared before the PTY environment test')
+    const sandbox = await Sandbox.create({
+      apiKey,
+      envs: { NPM_TOKEN: 'sentinel-secret', DSH_STALE: 'sentinel-stale', KEEP: 'visible' },
+      timeoutMs: 60_000,
+      secure: true,
+      lifecycle: { onTimeout: 'kill' },
+    })
+    try {
+      const profileLeakPath = '/home/user/dsh-e2b-bootstrap-profile-leak'
+      const hostileProfile = [
+        'if [[ "${NPM_TOKEN-}" == "sentinel-secret" ]]; then',
+        `  printf leaked > ${profileLeakPath}`,
+        'fi',
+        '',
+      ].join('\n')
+      await sandbox.files.write([
+        { path: '/home/user/.bash_profile', data: hostileProfile },
+        { path: '/home/user/.profile', data: hostileProfile },
+        { path: '/home/user/.bashrc', data: hostileProfile },
+      ])
+      const ctx = new Context()
+      ctx.provide('e2b', {
+        cwd: '/home/user',
+        runtimeRoot: '/home/user/.dsh-e2b',
+        getSandbox: async () => sandbox,
+      } as never)
+      ctx.provide('sandboxPolicy', {
+        defaultMode: 'danger-full-access',
+        workspaceRoot: '/home/user',
+      } as never)
+      const ptyFiber = await ctx.plugin(PtyService)
+      const subprocessFiber = await ctx.plugin(E2BSubprocessService)
+      const node = await ctx.subprocess.resolveExecutable('node')
+      const relativeNodePath = posix.relative(ctx.e2b.cwd, posix.dirname(node)) || '.'
+      await expect(ctx.subprocess.resolveExecutable('node', { PATH: relativeNodePath })).resolves.toBe(node)
+      await expect(sandbox.files.read(profileLeakPath)).rejects.toBeInstanceOf(FileNotFoundError)
+      const environmentProbe = ctx.subprocess.spawn({
+        argv: ['/bin/bash', '-c', [
+          'dsh_leak=0',
+          'for dsh_pid in "$PPID" $(ps -o pid= --ppid "$PPID"); do',
+          '  [[ "$dsh_pid" == "$$" ]] && continue',
+          '  if tr "\\0" "\\n" < "/proc/$dsh_pid/environ" 2>/dev/null | grep -Fqx "NPM_TOKEN=sentinel-secret"; then dsh_leak=1; fi',
+          'done',
+          'printf "DIRECT=<%s> LEAK=<%s>\\n" "${NPM_TOKEN-}" "$dsh_leak"',
+        ].join('\n')],
+        cwd: '/home/user',
+        stdio: { stdin: 'ignore', stdout: { maxBytes: 1_024 }, stderr: { maxBytes: 1_024 } },
+        graceMs: 500,
+        env: {},
+      })
+      await expect(environmentProbe.done).resolves.toEqual({ exitCode: 0, signal: null })
+      expect(environmentProbe.collected.stdout?.readFrom(0).text).toBe('DIRECT=<> LEAK=<0>\n')
+      await expect(sandbox.files.read(profileLeakPath)).rejects.toBeInstanceOf(FileNotFoundError)
+      const ownerId = SessionId('e2b-pty-env-owner')
+      const ownerSession = Session.create(ownerId)
+      const owner: Agent = {
+        id: ownerId,
+        options: {},
+        session: ownerSession,
+        inbox: new Inbox(ownerSession, { inserted: () => {}, discarded: () => {}, claimed: () => {} }),
+        status: 'idle',
+        ctx,
+        send() {},
+        followup() {},
+        steer() {},
+        inject() {},
+        cancel() {},
+        runMaintenance: task => task(new AbortController().signal),
+        whenIdle: () => Promise.resolve(),
+      }
+      const backend = new LocalPtyBackend(ctx, {
+        backendType: 'shell', 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,
+        handoffGraceMs: 500, timeoutMs: 5_000, disposeGraceMs: 1_000,
+      })
+      const session = await backend.spawn({ sessionId: PtySessionId('env'), owner, type: 'shell' })
+      const result = await session.startSend({
+        text: "printf 'NPM=<%s> DSH=<%s> KEEP=<%s>\\n' \"$NPM_TOKEN\" \"$DSH_STALE\" \"$KEEP\"",
+        submit: true,
+      }).done
+      expect(result.viewport).toContain('NPM=<> DSH=<> KEEP=<visible>')
+      expect(result.viewport).not.toContain('sentinel-secret')
+      expect(result.viewport).not.toContain('sentinel-stale')
+      await expect(sandbox.files.read(profileLeakPath)).rejects.toBeInstanceOf(FileNotFoundError)
+      await session.close('environment test complete')
+      await subprocessFiber.dispose()
+      await ptyFiber.dispose()
+
+    } finally {
+      await sandbox.kill().catch(() => false)
+    }
+  }, 70_000)
+
+  it('runs FS, Bash, PTY, and LSP in one sandbox and deletes it', async () => {
+    const { stdout, stderr } = await runLoaderSmoke({
+      label: 'E2B composition',
+      tempDirPrefix: 'dsh-e2b-composition-',
+      binScript,
+      libBinScript: binScript,
+      configPath,
+      tsconfigPath,
+      env: {
+        NODE_OPTIONS: [process.env.NODE_OPTIONS, '--disable-warning=ExperimentalWarning'].filter(Boolean).join(' '),
+      },
+      processTimeoutMs: 180_000,
+      inspect: async (cwd) => {
+        for (const name of ['from-fs.txt', 'from-bash.txt', 'multibyte # file.ts', 'fixture-lsp.mjs']) {
+          await expect(access(join(cwd, name))).rejects.toMatchObject({ code: 'ENOENT' })
+        }
+      },
+    })
+
+    expect(stderr).toBe('')
+    const output = JSON.parse(stdout) as Record<string, unknown>
+    expect(output).toMatchObject({
+      bashRead: 'versioned-by-fs\n',
+      fsRead: 'written-by-bash\n',
+      explicitEnvironment: true,
+      splitUtf8Output: '你好',
+      hover: {
+        kind: 'hover',
+        hover: { contents: '**remote hover** 你好 café' },
+      },
+      definition: {
+        kind: 'locations',
+        locations: [{ range: { start: { line: 0, character: 6 }, end: { line: 0, character: 10 } } }],
+      },
+      terminal: {
+        echo: { waitReason: 'stdin_read', sessionStatus: { kind: 'running' } },
+        signal: { delivered: true },
+        interrupted: { sessionStatus: { kind: 'running' } },
+        treeCleanup: true,
+      },
+    })
+    const terminalMotd = (output.terminal as { motd: string }).motd
+    expect(terminalMotd.length).toBeGreaterThan(0)
+    expect(terminalMotd).not.toContain('exec /bin/bash')
+    expect(terminalMotd).not.toContain('.dsh-e2b/terminals/')
+    expect((output.terminal as { echo: { viewport: string } }).echo.viewport).toContain('PTY-你好')
+    expect((output.terminal as { scrollback: string }).scrollback).toContain('PTY-你好')
+    expect((output.terminal as { signal: { targetPgid: number } }).signal.targetPgid).toBeGreaterThan(0)
+    expect(['stdin_read', 'inferred_idle']).toContain(
+      (output.terminal as { interrupted: { waitReason: string } }).interrupted.waitReason,
+    )
+    const apiKey = process.env.E2B_API_KEY
+    if (apiKey === undefined) throw new Error('E2B_API_KEY disappeared during the live composition test')
+    await expect(Sandbox.getInfo(String(output.sandboxId), { apiKey })).rejects.toBeInstanceOf(SandboxNotFoundError)
+    await expect.poll(async () => {
+      const sandboxes = await Sandbox.list({ apiKey }).nextItems()
+      return sandboxes.some(sandbox => sandbox.sandboxId === output.sandboxId)
+    }, { interval: 250, timeout: 5_000 }).toBe(false)
+  }, 195_000)
+})

packages/e2b/e2b/tests/e2b.spec.ts

@@ -0,0 +1,247 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type { Mock } from 'vitest'
+import { Context } from 'cordis'
+import type { Sandbox as SandboxType } from 'e2b'
+import E2BSandboxService, {
+  e2bControlEnvs,
+  FileType,
+  SandboxNotFoundError,
+  quoteE2BShellArg,
+} from '@deepseek-ai/dsh-e2b'
+import * as E2BInvariant from '../src/invariant.ts'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+
+const sdk = vi.hoisted(() => ({
+  create: vi.fn(),
+}))
+
+vi.mock('e2b', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('e2b')>()
+  // The mock replaces only the SDK's static factory surface and is never constructed.
+  // oxlint-disable-next-line typescript/no-extraneous-class -- The SDK contract is a class with a static factory.
+  class FakeSandbox {
+    static create(...args: unknown[]): unknown {
+      return sdk.create(...args)
+    }
+  }
+  return { ...actual, Sandbox: FakeSandbox }
+})
+
+interface SandboxFixture {
+  sandbox: SandboxType
+  makeDir: ReturnType<typeof vi.fn>
+  getInfo: ReturnType<typeof vi.fn>
+  run: Mock<RunCommand>
+  kill: ReturnType<typeof vi.fn>
+}
+
+type RunCommand = (
+  command: string,
+  options?: { envs?: Record<string, string> },
+) => Promise<{ exitCode: number; stdout: string; stderr: string }>
+
+function fakeSandbox(id = 'sandbox-1'): SandboxFixture {
+  const makeDir = vi.fn().mockResolvedValue(true)
+  const getInfo = vi.fn().mockResolvedValue({ type: FileType.DIR })
+  const run = vi.fn<RunCommand>().mockResolvedValue({ exitCode: 0, stdout: '', stderr: '' })
+  const kill = vi.fn().mockResolvedValue(undefined)
+  const sandbox = {
+    sandboxId: id,
+    files: { makeDir, getInfo },
+    commands: { run },
+    kill,
+  } as unknown as SandboxType
+  return { sandbox, makeDir, getInfo, run, kill }
+}
+
+beforeEach(() => {
+  sdk.create.mockReset()
+  vi.unstubAllEnvs()
+})
+
+describe('E2BSandboxService', () => {
+  it('gives each SDK login shell a fresh non-overridable control home', () => {
+    const first = e2bControlEnvs({ HOME: '/hostile', NPM_TOKEN: '' })
+    const second = e2bControlEnvs()
+
+    expect(first.HOME).toMatch(/^\/\.dsh-e2b-control-/)
+    expect(first).toEqual({ HOME: first.HOME, NPM_TOKEN: '' })
+    expect(first.HOME).not.toBe(second.HOME)
+  })
+
+  it('creates one protected shared sandbox and kills it on default disposal', async () => {
+    const fixture = fakeSandbox()
+    sdk.create.mockResolvedValue(fixture.sandbox)
+    const ctx = new Context()
+    const fiber = await ctx.plugin(E2BSandboxService, { apiKey: 'test-key' })
+
+    const service = ctx.e2b
+    await expect(service.getSandbox()).resolves.toBe(fixture.sandbox)
+    expect(service.cwd).toBe('/home/user/workspace')
+    expect(service.runtimeRoot).toBe('/home/user/workspace/.dsh-e2b')
+    expect(sdk.create).toHaveBeenCalledWith({
+      apiKey: 'test-key',
+      timeoutMs: 300_000,
+      secure: true,
+      lifecycle: { onTimeout: 'kill' },
+    })
+    expect(fixture.makeDir).toHaveBeenNthCalledWith(1, '/home/user/workspace')
+    expect(fixture.makeDir).toHaveBeenNthCalledWith(2, '/home/user/workspace/.dsh-e2b')
+    expect(fixture.getInfo).toHaveBeenCalledWith('/home/user/workspace/.dsh-e2b')
+    const runOptions = fixture.run.mock.calls[0]?.[1]
+    expect(runOptions?.envs?.HOME).toMatch(/^\/\.dsh-e2b-control-/)
+    expect(fixture.run).toHaveBeenCalledWith(
+      "chmod 700 -- '/home/user/workspace/.dsh-e2b'",
+      { envs: { HOME: runOptions?.envs?.HOME } },
+    )
+
+    await fiber.dispose()
+    expect(fixture.kill).toHaveBeenCalledOnce()
+    await expect(service.getSandbox()).rejects.toThrow(/disposing/)
+  })
+
+  it('rejects handle acquisition when disposal starts during setup', async () => {
+    const fixture = fakeSandbox()
+    const opening = Promise.withResolvers<SandboxType>()
+    sdk.create.mockReturnValue(opening.promise)
+    const ctx = new Context()
+    const fiber = await ctx.plugin(E2BSandboxService, { apiKey: 'test-key' })
+
+    const acquisition = ctx.e2b.getSandbox()
+    const disposing = fiber.dispose()
+    opening.resolve(fixture.sandbox)
+
+    await expect(acquisition).rejects.toThrow(/disposing/)
+    await expect(disposing).resolves.toBeUndefined()
+    expect(fixture.kill).toHaveBeenCalledOnce()
+  })
+
+  it('reads the key from the environment and honors the configured cwd and lifetime', async () => {
+    vi.stubEnv('E2B_API_KEY', 'environment-key')
+    const fixture = fakeSandbox('configured-sandbox')
+    sdk.create.mockResolvedValue(fixture.sandbox)
+    const ctx = new Context()
+    const fiber = await ctx.plugin(E2BSandboxService, {
+      cwd: '/workspace/project',
+      timeoutMs: 60_000,
+    })
+    await ctx.e2b.getSandbox()
+
+    expect(sdk.create).toHaveBeenCalledWith({
+      apiKey: 'environment-key',
+      timeoutMs: 60_000,
+      secure: true,
+      lifecycle: { onTimeout: 'kill' },
+    })
+    expect(ctx.e2b.cwd).toBe('/workspace/project')
+    await fiber.dispose()
+    expect(fixture.kill).toHaveBeenCalledOnce()
+  })
+
+  it('accepts a missing sandbox when disposal itself requests deletion', async () => {
+    const fixture = fakeSandbox()
+    fixture.kill.mockRejectedValue(new SandboxNotFoundError('already deleted'))
+    sdk.create.mockResolvedValue(fixture.sandbox)
+    const ctx = new Context()
+    const errors: unknown[] = []
+    ctx.logger.error = ((error: unknown) => { errors.push(error) }) as typeof ctx.logger.error
+    const fiber = await ctx.plugin(E2BSandboxService, { apiKey: 'test-key' })
+    await ctx.e2b.getSandbox()
+
+    await fiber.dispose()
+    expect(fixture.kill).toHaveBeenCalledOnce()
+    expect(errors).toEqual([])
+  })
+
+  it('does not classify other disposal failures as an already-gone sandbox', async () => {
+    const fixture = fakeSandbox()
+    const failure = new Error('disposition unknown')
+    fixture.kill.mockRejectedValue(failure)
+    sdk.create.mockResolvedValue(fixture.sandbox)
+    const ctx = new Context()
+    const errors: unknown[] = []
+    ctx.logger.error = ((error: unknown) => { errors.push(error) }) as typeof ctx.logger.error
+    const fiber = await ctx.plugin(E2BSandboxService, { apiKey: 'test-key' })
+    await ctx.e2b.getSandbox()
+    await expect(fiber.dispose()).resolves.toBeUndefined()
+    expect(fixture.kill).toHaveBeenCalledOnce()
+    expect(errors).toContain(failure)
+  })
+
+  it('kills a newly created sandbox when remote directory setup fails', async () => {
+    const fixture = fakeSandbox()
+    fixture.makeDir.mockRejectedValueOnce(new Error('setup failed'))
+    sdk.create.mockResolvedValue(fixture.sandbox)
+    const ctx = new Context()
+    const fiber = await ctx.plugin(E2BSandboxService, { apiKey: 'test-key' })
+
+    await expect(ctx.e2b.getSandbox()).rejects.toThrow('setup failed')
+    expect(fixture.kill).toHaveBeenCalledOnce()
+    await fiber.dispose()
+  })
+
+  it('preserves the setup failure after its one rollback attempt fails', async () => {
+    const fixture = fakeSandbox()
+    fixture.run.mockRejectedValueOnce(new Error('chmod failed'))
+    fixture.kill.mockRejectedValueOnce(new Error('cleanup failed'))
+    sdk.create.mockResolvedValue(fixture.sandbox)
+    const ctx = new Context()
+    const fiber = await ctx.plugin(E2BSandboxService, { apiKey: 'test-key' })
+    await expect(ctx.e2b.getSandbox()).rejects.toThrow('chmod failed')
+    expect(fixture.kill).toHaveBeenCalledOnce()
+
+    await fiber.dispose()
+    expect(fixture.kill).toHaveBeenCalledOnce()
+  })
+
+  it.each([
+    ['symbolic link', { type: FileType.DIR, symlinkTarget: '/tmp/redirected' }],
+    ['regular file', { type: FileType.FILE }],
+  ])('rejects a reserved runtime root that is a %s', async (_label, info) => {
+    const fixture = fakeSandbox()
+    fixture.getInfo.mockResolvedValueOnce(info)
+    sdk.create.mockResolvedValue(fixture.sandbox)
+    const ctx = new Context()
+    await ctx.plugin(E2BSandboxService, { apiKey: 'test-key' })
+
+    await expect(ctx.e2b.getSandbox()).rejects.toThrow('runtime root must be a real directory')
+    expect(fixture.run).not.toHaveBeenCalled()
+    expect(fixture.kill).toHaveBeenCalledOnce()
+  })
+
+  it.each([
+    [{ apiKey: '' }, /configure apiKey/],
+    [{ apiKey: 'x', cwd: 'relative' }, /absolute Linux path/],
+    [{ apiKey: 'x', timeoutMs: 0 }, /positive finite/],
+  ] as const)('fails self-contained configuration before opening E2B: %j', async (config, message) => {
+    vi.stubEnv('E2B_API_KEY', '')
+    const ctx = new Context()
+    await expect(ctx.plugin(E2BSandboxService, config)).rejects.toThrow(message)
+    expect(sdk.create).not.toHaveBeenCalled()
+  })
+
+  it('requires a key when both config and the environment omit it', async () => {
+    const original = process.env.E2B_API_KEY
+    delete process.env.E2B_API_KEY
+    try {
+      const ctx = new Context()
+      await expect(ctx.plugin(E2BSandboxService, {})).rejects.toThrow(/configure apiKey/)
+    } finally {
+      if (original === undefined) delete process.env.E2B_API_KEY
+      else process.env.E2B_API_KEY = original
+    }
+  })
+})
+
+describe('E2B helpers and invariant companion', () => {
+  it('quotes opaque shell arguments without interpolation', () => {
+    expect(quoteE2BShellArg("a'b $HOME")).toBe("'a'\"'\"'b $HOME'")
+  })
+
+  it('registers the package-owned empty invariant installer', async () => {
+    const ctx = new Context()
+    await ctx.plugin(InvariantService, { enabled: true })
+    const fiber = await ctx.plugin(E2BInvariant).await()
+    await fiber.dispose()
+  })
+})

packages/e2b/e2b/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": ["src"],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../util/brand"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}

packages/e2b/fs-e2b/README.i18n.yaml

@@ -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/e2b/fs-e2b/README.md
+README.md: cd170bcbe2831b0856b51791a2045382d93c1148
+README.zh.md: f97790cf1d4ef90f042df8ed564723e186327f00

packages/e2b/fs-e2b/README.md

@@ -0,0 +1,31 @@
+# @deepseek-ai/dsh-fs-e2b
+
+English | [中文](README.zh.md)
+
+E2B implementation of the [`@deepseek-ai/dsh-fs`](../../fs/fs/README.md) provider seam. It has no config: load [`@deepseek-ai/dsh-e2b`](../e2b/README.md) first, then this service in place of `dsh-fs-local`. The provider uses the owner's remote cwd and SDK handle, so file tools observe the same world as E2B-backed Bash processes.
+
+## Behavior
+
+- **Remote identity and metadata** — relative paths resolve as POSIX paths against the caller cwd or `ctx.e2b.cwd`; GNU `realpath -mz` supplies canonical target identity without requiring the final file to exist, and ASCII/base64 plus strict NUL framing preserves newline and multibyte paths across the decoded SDK transport. `stat`, no-follow `lstat`, and stable one-level directory listings project E2B metadata into the filesystem seam; listings reuse returned metadata and resolve symbolic-link entries sequentially. Versions are opaque hashes of E2B metadata plus a per-write extended attribute.
+- **Execution-world paths** — canonical targets expose absolute POSIX process paths, percent-encoded `file:` URIs, and provider-owned containment checks, so generic subprocess consumers never parse E2B target ids or apply host path rules.
+- **UTF-8 reads** — whole reads and streamed reads preserve cross-chunk decoding, reject invalid UTF-8, and use the seam's 8192-byte NUL sample for binary detection. The model-facing tool still owns size selection and line windowing.
+- **Atomic mutations** — writes create a random sibling staging directory, change it to mode `0700` before uploading content, preserve an existing file's POSIX mode, and publish the staged file through E2B's same-filesystem atomic rename. The rename response supplies the committed version, so no fallible metadata request follows the commit point. E2B creates missing parent directories. Literal edits LF-normalize for matching, restore dominant CRLF storage, and serialize mutations per canonical target within the host process. Optional create/version guards keep the base seam's observed-state semantics.
+- **Failures and cancellation** — E2B not-found, permission, abort, and other controller failures map to the existing `FsError` vocabulary. Cancellation is best-effort at earlier SDK request boundaries and checked immediately before rename. The signal is not forwarded into the rename RPC, so cancellation cannot interrupt the atomic commit; a successful rename is the commit point.
+
+The provider does not copy, mount, or reconcile the host workspace. Giving it a host path as `cwd` creates a remote directory with the same spelling only.
+
+## Model Experience
+
+Indirectly, through [`dsh-tool-fs`](../../fs/tool-fs/README.md), which renders remote UTF-8 content, directory results, mutation acknowledgements, and provider errors while E2B identity and transport remain internal.
+
+#### KV Cache effect
+
+No direct invalidation; the named consumer owns any request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+- **No host synchronization** — an empty E2B cwd stays empty until a tool, command, or external process populates it; local files are neither uploaded nor reflected back.
+- **Mutation coordination is host-process-local** — another harness connection or remote command can race the adapter; version guards detect only metadata changes represented by E2B.
+- **Reads reopen canonical targets by path** — a concurrent remote path replacement between resolution and stream opening is not fenced by a stable file handle; no observed product defect justifies a provider-specific bounded-read protocol in this POC.
+- **Whole-file mutation costs remain** — overwrite diffs and literal edits read complete files into host memory, and every operation incurs E2B controller latency.
+- **The POC targets E2B's default Linux image** — it relies on GNU `realpath`/`base64`/`chmod`, same-filesystem rename, streaming reads, and metadata extended attributes; custom templates are outside this POC.

packages/e2b/fs-e2b/README.zh.md

@@ -0,0 +1,31 @@
+# @deepseek-ai/dsh-fs-e2b
+
+[English](README.md) | 中文
+
+[`@deepseek-ai/dsh-fs`](../../fs/fs/README.md) 提供方 seam 的 E2B 实现。它没有配置：先加载 [`@deepseek-ai/dsh-e2b`](../e2b/README.md)，再用本服务取代 `dsh-fs-local`。该提供方使用所有者的远程 cwd 和 SDK 句柄，因此文件工具观察到的环境与 E2B 后端 Bash 进程相同。
+
+## 行为
+
+- **远程身份与元数据**：相对路径以调用方 cwd 或 `ctx.e2b.cwd` 为基准，按照 POSIX 路径解析；GNU `realpath -mz` 提供规范化目标身份，且不要求最终文件存在；ASCII/base64 加严格 NUL 分帧会在已解码的 SDK 传输中保留含换行符和多字节字符的路径。`stat`、不跟随链接的 `lstat` 和稳定的单层目录列表会把 E2B 元数据投影到文件系统 seam；目录列表会复用已返回的元数据，并依次解析符号链接条目。版本是 E2B 元数据与每次写入设置的扩展属性所组成的不透明哈希。
+- **执行世界路径**：规范化目标公开绝对 POSIX 进程路径、百分号编码的 `file:` URI，以及由提供方负责的包含关系检查，因此通用进程管理消费方无需解析 E2B 目标 ID，也不会套用宿主路径规则。
+- **UTF-8 读取**：完整读取和流式读取会保留跨分片解码、拒绝无效 UTF-8，并使用 seam 的 8192 字节 NUL 样本检测二进制内容。面向模型的工具仍负责选择大小和行窗口。
+- **原子变更**：写入会创建随机的同级暂存目录，在上传内容前将其 mode 改为 `0700`，保留现有文件的 POSIX mode，并通过 E2B 的同一文件系统原子重命名发布暂存文件。重命名响应会提供已提交的版本，因此提交点之后不会再进行可能失败的元数据请求。E2B 会创建缺失的父目录。字面量编辑匹配时会规范化为 LF，存储时恢复占主导的 CRLF，并在宿主进程内按规范化目标串行执行变更。可选的创建／版本防护会保留基础 seam 的已观察状态语义。
+- **失败与取消**：E2B 的未找到、权限、中止及其他控制器故障会映射到现有 `FsError` 词汇。取消在更早的 SDK 请求边界上采用尽力而为语义，并在 rename 前立即检查。信号不会传入 rename RPC，因此取消无法中断原子提交；成功 rename 是提交点。
+
+该提供方不会复制、挂载或协调宿主工作区。把宿主路径用作 `cwd`，只会在远程创建一个拼写相同的目录。
+
+## 模型体验
+
+通过 [`dsh-tool-fs`](../../fs/tool-fs/README.md) 间接影响模型；该工具会渲染远程 UTF-8 内容、目录结果、变更确认和提供方错误，而 E2B 身份及传输保持内部实现。
+
+#### KV Cache 影响
+
+不会直接失效；请求前缀变更由具名消费方负责。
+
+## 已知限制与延后工作
+
+- **不提供宿主同步**：空的 E2B cwd 会一直为空，直到工具、命令或外部进程填充它；本地文件既不会上传，也不会同步回本地。
+- **变更协调仅限宿主进程内**：另一个 harness 连接或远程命令可能与适配器发生竞态；版本防护只能检测 E2B 元数据所体现的变更。
+- **读取会按路径重新打开规范化目标**：在解析与打开流之间若并发替换远程路径，该操作没有稳定文件句柄提供围栏；在该 POC 中，没有已观察到的产品缺陷能够证明提供方专用的有界读取协议值得引入。
+- **仍需承担完整文件变更成本**：覆盖差异和字面量编辑会把完整文件读入宿主内存，每项操作也都会产生 E2B 控制器延迟。
+- **该 POC 面向 E2B 默认 Linux 镜像**：它依赖 GNU `realpath`／`base64`／`chmod`、同一文件系统内的 rename、流式读取和元数据扩展属性；自定义模板不在该 POC 范围内。

packages/e2b/fs-e2b/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@deepseek-ai/dsh-fs-e2b",
+  "description": "E2B filesystem implementation for DeepSeek Harness",
+  "version": "0.0.1",
+  "private": true,
+  "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"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-e2b": "^0.0.1",
+    "@deepseek-ai/dsh-fs": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-e2b": "workspace:^",
+    "@deepseek-ai/dsh-fs": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}

packages/e2b/fs-e2b/src/index.ts

@@ -0,0 +1,499 @@
+/**
+ * E2B implementation of the filesystem provider seam. Paths, contents, and
+ * atomic staging files remain inside the shared remote sandbox.
+ * @module @deepseek-ai/dsh-fs-e2b
+ */
+
+import { createHash, randomUUID } from 'node:crypto'
+import { Buffer } from 'node:buffer'
+import { posix } from 'node:path'
+import { FileSystem, FsError, FsTargetKey, FsVersion } from '@deepseek-ai/dsh-fs'
+import type {
+  FsDirEntry,
+  FsEditOutcome,
+  FsEditRequest,
+  FsInfo,
+  FsPathInfo,
+  FsTarget,
+  FsWriteIntent,
+  FsWriteOutcome,
+} from '@deepseek-ai/dsh-fs'
+import {
+  CommandExitError,
+  e2bControlEnvs,
+  FileNotFoundError,
+  FileType,
+  quoteE2BShellArg,
+} from '@deepseek-ai/dsh-e2b'
+import type { EntryInfo, Sandbox } from '@deepseek-ai/dsh-e2b'
+
+const VERSION_METADATA_KEY = 'dsh-version'
+const BINARY_SAMPLE_BYTES = 8192
+const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/
+
+function assertNotAborted(signal: AbortSignal | undefined, operation: string): void {
+  if (signal?.aborted === true) throw new FsError(`${operation} aborted`, 'FS_ABORTED')
+}
+
+function normalizeLineEndings(value: string): string {
+  return value.replaceAll('\r\n', '\n')
+}
+
+function detectsCrlf(value: string): boolean {
+  const sample = value.slice(0, 4096)
+  const crlf = sample.split('\r\n').length - 1
+  const lf = sample.split('\n').length - 1 - crlf
+  return crlf > lf
+}
+
+function restoreLineEndings(value: string, crlf: boolean): string {
+  return crlf ? normalizeLineEndings(value).replaceAll('\n', '\r\n') : value
+}
+
+function decodeText(bytes: Uint8Array, displayPath: string, binarySampleBytes: number): string {
+  if (bytes.subarray(0, binarySampleBytes).includes(0)) {
+    throw new FsError(`cannot read "${displayPath}": binary file`, 'FS_NOT_TEXT')
+  }
+  try {
+    return new TextDecoder('utf-8', { fatal: true }).decode(bytes)
+  } catch (error: unknown) {
+    throw new FsError(`cannot read "${displayPath}": invalid UTF-8 text`, 'FS_NOT_TEXT', { cause: error })
+  }
+}
+
+function decodeCanonicalPath(encoded: string): string {
+  if (encoded.length === 0 || !BASE64.test(encoded)) {
+    throw new Error('fs-e2b: canonical path transport returned invalid base64')
+  }
+  const framed = Buffer.from(encoded, 'base64')
+  if (framed.toString('base64') !== encoded
+    || framed.length < 2
+    || framed.at(-1) !== 0
+    || framed.subarray(0, -1).includes(0)) {
+    throw new Error('fs-e2b: canonical path transport returned invalid NUL framing')
+  }
+  let path: string
+  try {
+    path = new TextDecoder('utf-8', { fatal: true }).decode(framed.subarray(0, -1))
+  } catch (error: unknown) {
+    throw new Error('fs-e2b: canonical path is not valid UTF-8', { cause: error })
+  }
+  if (!posix.isAbsolute(path)) throw new Error('fs-e2b: canonical path is not absolute')
+  return path
+}
+
+function signalOpts(signal: AbortSignal | undefined): { signal?: AbortSignal } {
+  return signal === undefined ? {} : { signal }
+}
+
+function commandOpts(signal: AbortSignal | undefined): { envs: Record<string, string>; signal?: AbortSignal } {
+  return { envs: e2bControlEnvs(), ...signalOpts(signal) }
+}
+
+function entryType(entry: EntryInfo): FsInfo['type'] {
+  switch (entry.type) {
+    case FileType.FILE:
+      return 'file'
+    case FileType.DIR:
+      return 'directory'
+    default:
+      return 'other'
+  }
+}
+
+function entryVersion(entry: EntryInfo): ReturnType<typeof FsVersion> {
+  const facts = JSON.stringify([
+    entry.metadata?.[VERSION_METADATA_KEY],
+    entry.path,
+    entry.type,
+    entry.size,
+    entry.mode,
+    entry.modifiedTime?.toISOString(),
+    entry.symlinkTarget,
+  ])
+  return FsVersion(`e2b:${createHash('sha256').update(facts).digest('hex')}`)
+}
+
+function mapError(error: unknown, operation: string, displayPath: string, signal?: AbortSignal): FsError {
+  if (error instanceof FsError) return error
+  if (signal?.aborted === true || (error instanceof DOMException && error.name === 'AbortError')) {
+    return new FsError(`${operation} aborted`, 'FS_ABORTED', { cause: error })
+  }
+  if (error instanceof FileNotFoundError) {
+    return new FsError(`cannot ${operation} "${displayPath}": not found`, 'FS_NOT_FOUND', { cause: error })
+  }
+  if (/permission denied|operation not permitted/i.test(String(error))) {
+    return new FsError(`cannot ${operation} "${displayPath}": permission denied`, 'FS_PERMISSION_DENIED', { cause: error })
+  }
+  return new FsError(`cannot ${operation} "${displayPath}": ${String(error)}`, 'FS_IO_ERROR', { cause: error })
+}
+
+function literalEdit(content: string, request: FsEditRequest, displayPath: string): string {
+  const oldString = normalizeLineEndings(request.oldString)
+  const newString = normalizeLineEndings(request.newString)
+  if (oldString.length === 0) {
+    throw new FsError(`cannot edit "${displayPath}": old_string must be non-empty`, 'FS_EDIT_NOT_FOUND')
+  }
+  let matches = 0
+  let offset = 0
+  while (true) {
+    const found = content.indexOf(oldString, offset)
+    if (found < 0) break
+    matches += 1
+    offset = found + oldString.length
+  }
+  if (matches === 0) throw new FsError(`cannot edit "${displayPath}": old_string was not found`, 'FS_EDIT_NOT_FOUND')
+  if (!request.replaceAll && matches !== 1) {
+    throw new FsError(`cannot edit "${displayPath}": old_string matched ${matches} times`, 'FS_AMBIGUOUS_EDIT')
+  }
+  return request.replaceAll ? content.split(oldString).join(newString) : content.replace(oldString, newString)
+}
+
+/** Remote filesystem backend sharing the sandbox owned by `ctx.e2b`. */
+export class E2BFileSystem extends FileSystem {
+  static inject = ['e2b']
+
+  private readonly locks = new Map<string, Promise<unknown>>()
+
+  override async resolve(path: string, opts?: { cwd?: string; signal?: AbortSignal }): Promise<FsTarget> {
+    assertNotAborted(opts?.signal, 'resolve')
+    if (path.trim().length === 0) throw new FsError('file_path must be a non-empty string', 'FS_NOT_FOUND')
+    const displayPath = posix.resolve(opts?.cwd ?? this.ctx.e2b.cwd, path)
+    try {
+      const sandbox = await this.ctx.e2b.getSandbox()
+      const targetKey = await this.canonicalPath(sandbox, displayPath, opts?.signal)
+      assertNotAborted(opts?.signal, 'resolve')
+      return { targetKey: FsTargetKey(targetKey), displayPath }
+    } catch (error: unknown) {
+      throw mapError(error, 'resolve', displayPath, opts?.signal)
+    }
+  }
+
+  override processPath(target: FsTarget): string {
+    return String(target.targetKey)
+  }
+
+  override fileUrl(target: FsTarget): string {
+    const path = this.processPath(target)
+    if (!posix.isAbsolute(path)) throw new Error(`fs-e2b: expected an absolute process path: ${JSON.stringify(path)}`)
+    return `file://${path.split('/').map(segment => encodeURIComponent(segment)).join('/')}`
+  }
+
+  override contains(parent: FsTarget, child: FsTarget): boolean {
+    const relative = posix.relative(this.processPath(parent), this.processPath(child))
+    return relative === '' || (relative !== '..' && !relative.startsWith('../') && !posix.isAbsolute(relative))
+  }
+
+  override async stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined> {
+    assertNotAborted(signal, 'stat')
+    const entry = await this.probe(String(target.targetKey), target.displayPath, signal)
+    if (entry === undefined) return undefined
+    return {
+      version: entryVersion(entry),
+      type: entryType(entry),
+      ...(entry.type === FileType.FILE ? { size: entry.size } : {}),
+    }
+  }
+
+  override async lstat(path: string, opts?: { cwd?: string }, signal?: AbortSignal): Promise<FsPathInfo | undefined> {
+    assertNotAborted(signal, 'lstat')
+    if (path.trim().length === 0) throw new FsError('file_path must be a non-empty string', 'FS_NOT_FOUND')
+    const displayPath = posix.resolve(opts?.cwd ?? this.ctx.e2b.cwd, path)
+    const entry = await this.probe(displayPath, displayPath, signal)
+    if (entry === undefined) return undefined
+    const type = entry.symlinkTarget !== undefined
+      ? 'symlink' as const
+      : entry.type === FileType.FILE
+        ? 'file' as const
+        : entry.type === FileType.DIR
+          ? 'directory' as const
+          : 'other' as const
+    return {
+      version: entryVersion(entry),
+      type,
+      ...(entry.type === FileType.FILE ? { size: entry.size } : {}),
+    }
+  }
+
+  override async readText(target: FsTarget, signal?: AbortSignal): Promise<string> {
+    const sandbox = await this.ctx.e2b.getSandbox()
+    await this.requireRegular(target, signal)
+    try {
+      const bytes = await sandbox.files.read(String(target.targetKey), { format: 'bytes', ...signalOpts(signal) })
+      assertNotAborted(signal, 'read')
+      return decodeText(bytes, target.displayPath, BINARY_SAMPLE_BYTES)
+    } catch (error: unknown) {
+      throw mapError(error, 'read', target.displayPath, signal)
+    }
+  }
+
+  override async streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>> {
+    const sandbox = await this.ctx.e2b.getSandbox()
+    await this.requireRegular(target, signal)
+    let stream: ReadableStream<Uint8Array>
+    try {
+      // The pinned SDK's stream overload lies for empty files: content-length 0
+      // returns '' instead of a ReadableStream.
+      const read = await sandbox.files.read(String(target.targetKey), { format: 'stream', ...signalOpts(signal) }) as
+        ReadableStream<Uint8Array> | string
+      stream = typeof read === 'string'
+        ? new ReadableStream<Uint8Array>({ start(controller) { controller.close() } })
+        : read
+    } catch (error: unknown) {
+      throw mapError(error, 'read', target.displayPath, signal)
+    }
+    const displayPath = target.displayPath
+    return {
+      async *[Symbol.asyncIterator](): AsyncGenerator<string> {
+        const reader = stream.getReader()
+        const decoder = new TextDecoder('utf-8', { fatal: true })
+        let sampledBytes = 0
+        let completed = false
+        try {
+          while (true) {
+            assertNotAborted(signal, 'read')
+            const next = await reader.read()
+            if (next.done) break
+            if (sampledBytes < BINARY_SAMPLE_BYTES) {
+              const sample = next.value.subarray(0, BINARY_SAMPLE_BYTES - sampledBytes)
+              if (sample.includes(0)) throw new FsError(`cannot read "${displayPath}": binary file`, 'FS_NOT_TEXT')
+              sampledBytes += sample.length
+            }
+            let text: string
+            try {
+              text = decoder.decode(next.value, { stream: true })
+            } catch (error: unknown) {
+              throw new FsError(`cannot read "${displayPath}": invalid UTF-8 text`, 'FS_NOT_TEXT', { cause: error })
+            }
+            if (text.length > 0) yield text
+          }
+          try {
+            decoder.decode()
+          } catch (error: unknown) {
+            throw new FsError(`cannot read "${displayPath}": invalid UTF-8 text`, 'FS_NOT_TEXT', { cause: error })
+          }
+          completed = true
+        } catch (error: unknown) {
+          throw mapError(error, 'read', displayPath, signal)
+        } finally {
+          if (!completed) {
+            try {
+              await reader.cancel()
+            } catch (_streamCancellationFailure) {
+              // The primary read outcome owns the result; cancellation is best-effort after early stop.
+            }
+          }
+          reader.releaseLock()
+        }
+      },
+    }
+  }
+
+  override async listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]> {
+    const info = await this.stat(target, signal)
+    if (info === undefined) throw new FsError(`cannot list "${target.displayPath}": not found`, 'FS_NOT_FOUND')
+    if (info.type !== 'directory') throw new FsError(`cannot list "${target.displayPath}": not a directory`, 'FS_NOT_DIRECTORY')
+    try {
+      const sandbox = await this.ctx.e2b.getSandbox()
+      const listed = await sandbox.files.list(String(target.targetKey), { depth: 1, ...signalOpts(signal) })
+      const entries: FsDirEntry[] = []
+      for (const entry of listed) {
+        const displayPath = posix.join(target.displayPath, entry.name)
+        const canonical = entry.symlinkTarget === undefined
+          ? entry.path
+          : await this.canonicalPath(sandbox, entry.path, signal)
+        const resolved = entry.symlinkTarget === undefined
+          ? entry
+          : await this.probe(canonical, displayPath, signal)
+        entries.push({
+          name: entry.name,
+          type: resolved === undefined ? 'other' : entryType(resolved),
+          target: { targetKey: FsTargetKey(canonical), displayPath },
+          ...(resolved !== undefined ? { version: entryVersion(resolved) } : {}),
+          ...(resolved?.type === FileType.FILE ? { size: resolved.size } : {}),
+        })
+      }
+      return entries.sort((left, right) => left.name.localeCompare(right.name))
+    } catch (error: unknown) {
+      throw mapError(error, 'list', target.displayPath, signal)
+    }
+  }
+
+  override async writeText(
+    target: FsTarget,
+    content: string,
+    expected?: FsWriteIntent,
+    signal?: AbortSignal,
+  ): Promise<FsWriteOutcome> {
+    return this.withLock(String(target.targetKey), async () => {
+      const existing = await this.probe(String(target.targetKey), target.displayPath, signal)
+      if (existing !== undefined && entryType(existing) !== 'file') {
+        throw new FsError(`cannot write "${target.displayPath}": not a regular file`, 'FS_NOT_REGULAR_FILE')
+      }
+      this.checkWriteIntent(existing, expected, target)
+      const before = existing === undefined ? null : await this.readForDiff(target, signal)
+      const version = await this.writeAtomic(target, content, existing, signal)
+      return {
+        operation: existing === undefined ? 'create' : 'update',
+        version,
+        before,
+        after: normalizeLineEndings(content),
+      }
+    })
+  }
+
+  override async editText(
+    target: FsTarget,
+    edit: FsEditRequest,
+    expected?: { version: ReturnType<typeof FsVersion> },
+    signal?: AbortSignal,
+  ): Promise<FsEditOutcome> {
+    return this.withLock(String(target.targetKey), async () => {
+      const existing = await this.probe(String(target.targetKey), target.displayPath, signal)
+      if (existing === undefined) {
+        throw new FsError(`cannot edit "${target.displayPath}": file changed since it was read`, 'FS_STALE_VERSION')
+      }
+      if (entryType(existing) !== 'file') {
+        throw new FsError(`cannot edit "${target.displayPath}": not a regular file`, 'FS_NOT_REGULAR_FILE')
+      }
+      if (expected !== undefined && entryVersion(existing) !== expected.version) {
+        throw new FsError(`cannot edit "${target.displayPath}": file changed since it was read`, 'FS_STALE_VERSION')
+      }
+      const raw = await this.readForEdit(target, signal)
+      const before = normalizeLineEndings(raw)
+      const after = literalEdit(before, edit, target.displayPath)
+      const storage = restoreLineEndings(after, detectsCrlf(raw))
+      const version = await this.writeAtomic(target, storage, existing, signal)
+      return { version, before, after }
+    })
+  }
+
+  private async withLock<T>(targetKey: string, operation: () => Promise<T>): Promise<T> {
+    const prior = this.locks.get(targetKey) ?? Promise.resolve()
+    const run = prior.then(operation, operation)
+    const tail = run.then(() => undefined, () => undefined)
+    this.locks.set(targetKey, tail)
+    try {
+      return await run
+    } finally {
+      if (this.locks.get(targetKey) === tail) this.locks.delete(targetKey)
+    }
+  }
+
+  private async canonicalPath(sandbox: Sandbox, path: string, signal?: AbortSignal): Promise<string> {
+    try {
+      const result = await sandbox.commands.run(
+        `set -o pipefail; realpath -mz -- ${quoteE2BShellArg(path)} | base64 -w0`,
+        commandOpts(signal),
+      )
+      return decodeCanonicalPath(result.stdout)
+    } catch (error: unknown) {
+      if (error instanceof CommandExitError) throw new Error(error.stderr || error.message, { cause: error })
+      throw error
+    }
+  }
+
+  private async probe(path: string, displayPath: string, signal?: AbortSignal): Promise<EntryInfo | undefined> {
+    assertNotAborted(signal, 'stat')
+    try {
+      const sandbox = await this.ctx.e2b.getSandbox()
+      const entry = await sandbox.files.getInfo(path, signalOpts(signal))
+      assertNotAborted(signal, 'stat')
+      return entry
+    } catch (error: unknown) {
+      if (error instanceof FileNotFoundError) return undefined
+      throw mapError(error, 'stat', displayPath, signal)
+    }
+  }
+
+  private async requireRegular(target: FsTarget, signal?: AbortSignal): Promise<void> {
+    const info = await this.stat(target, signal)
+    if (info === undefined) throw new FsError(`cannot read "${target.displayPath}": not found`, 'FS_NOT_FOUND')
+    if (info.type !== 'file') throw new FsError(`cannot read "${target.displayPath}": not a regular file`, 'FS_NOT_REGULAR_FILE')
+  }
+
+  private checkWriteIntent(existing: EntryInfo | undefined, expected: FsWriteIntent | undefined, target: FsTarget): void {
+    if (expected?.kind === 'createIfAbsent' && existing !== undefined) {
+      throw new FsError(`cannot overwrite existing "${target.displayPath}" without reading it first`, 'FS_NOT_OBSERVED')
+    }
+    if (expected?.kind === 'replaceIfVersion') {
+      if (existing === undefined || entryVersion(existing) !== expected.version) {
+        throw new FsError(`cannot write "${target.displayPath}": file changed since it was read`, 'FS_STALE_VERSION')
+      }
+    }
+  }
+
+  private async readForDiff(target: FsTarget, signal?: AbortSignal): Promise<string | null> {
+    try {
+      const sandbox = await this.ctx.e2b.getSandbox()
+      const bytes = await sandbox.files.read(String(target.targetKey), { format: 'bytes', ...signalOpts(signal) })
+      assertNotAborted(signal, 'read')
+      return normalizeLineEndings(decodeText(bytes, target.displayPath, bytes.length))
+    } catch (error: unknown) {
+      if (error instanceof FsError && error.code === 'FS_NOT_TEXT') return null
+      throw mapError(error, 'read', target.displayPath, signal)
+    }
+  }
+
+  private async readForEdit(target: FsTarget, signal?: AbortSignal): Promise<string> {
+    try {
+      const sandbox = await this.ctx.e2b.getSandbox()
+      const bytes = await sandbox.files.read(String(target.targetKey), { format: 'bytes', ...signalOpts(signal) })
+      assertNotAborted(signal, 'edit')
+      return decodeText(bytes, target.displayPath, bytes.length)
+    } catch (error: unknown) {
+      throw mapError(error, 'edit', target.displayPath, signal)
+    }
+  }
+
+  private async writeAtomic(
+    target: FsTarget,
+    content: string,
+    existing: EntryInfo | undefined,
+    signal?: AbortSignal,
+  ): Promise<ReturnType<typeof FsVersion>> {
+    assertNotAborted(signal, 'write')
+    const sandbox = await this.ctx.e2b.getSandbox()
+    const targetPath = String(target.targetKey)
+    const versionId = randomUUID()
+    const stagingDirectory = posix.join(posix.dirname(targetPath), `.dsh-${randomUUID()}.tmp`)
+    const temporary = posix.join(stagingDirectory, 'content')
+    let stagingDirectoryCreated = false
+    try {
+      const created = await sandbox.files.makeDir(stagingDirectory, signalOpts(signal))
+      if (!created) throw new Error('private staging directory already exists')
+      stagingDirectoryCreated = true
+      await sandbox.commands.run(`chmod 700 -- ${quoteE2BShellArg(stagingDirectory)}`, commandOpts(signal))
+      assertNotAborted(signal, 'write')
+      await sandbox.files.write(temporary, content, {
+        metadata: { [VERSION_METADATA_KEY]: versionId },
+        ...signalOpts(signal),
+      })
+      assertNotAborted(signal, 'write')
+      const mode = existing === undefined ? 0o600 : existing.mode & 0o777
+      await sandbox.commands.run(
+        `chmod ${mode.toString(8)} -- ${quoteE2BShellArg(temporary)}`,
+        commandOpts(signal),
+      )
+      assertNotAborted(signal, 'write')
+      const committed = await sandbox.files.rename(temporary, targetPath)
+      try {
+        await sandbox.files.remove(stagingDirectory)
+      } catch (_committedStagingCleanupFailure) {
+        // The target is already committed; an empty private directory cannot turn that write into a failure.
+      }
+      return entryVersion(committed)
+    } catch (error: unknown) {
+      if (stagingDirectoryCreated) {
+        try {
+          await sandbox.files.remove(stagingDirectory)
+        } catch (_stagingDirectoryAlreadyAbsentOrCleanupFailed) {
+          // Only the private staging directory is swallowed; the original failure owns the operation.
+        }
+      }
+      throw mapError(error, 'write', target.displayPath, signal)
+    }
+  }
+}
+
+export default E2BFileSystem

packages/e2b/fs-e2b/src/invariant.ts

@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-fs-e2b`.
+ * @module @deepseek-ai/dsh-fs-e2b/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-fs-e2b'
+
+/** Cordis companion plugin name. */
+export const name = 'fs-e2b-invariant'
+/** Service required before reserving package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: each operation returns the E2B controller's committed
+ * result directly, with no independent event or cache to cross-check.
+ */
+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 */

packages/e2b/fs-e2b/tests/filesystem.spec.ts

@@ -0,0 +1,682 @@
+import { Buffer } from 'node:buffer'
+import { dirname, posix } from 'node:path'
+import { Context } from 'cordis'
+import {
+  CommandExitError,
+  FileNotFoundError,
+  FileType,
+  type EntryInfo,
+  type Sandbox,
+} from '@deepseek-ai/dsh-e2b'
+import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
+import { FsTargetKey, FsVersion } from '@deepseek-ai/dsh-fs'
+import E2BFileSystem from '@deepseek-ai/dsh-fs-e2b'
+import * as E2BFsInvariant from '../src/invariant.ts'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+import { describe, expect, it, vi } from 'vitest'
+
+interface RemoteNode {
+  type: FileType
+  data: Uint8Array
+  mode: number
+  modified: number
+  metadata?: Record<string, string>
+  symlinkTarget?: string
+}
+
+function bytes(value: string | readonly number[]): Uint8Array {
+  return typeof value === 'string' ? new TextEncoder().encode(value) : Uint8Array.from(value)
+}
+
+function commandError(exitCode: number, stderr = ''): CommandExitError {
+  return new CommandExitError({ exitCode, stdout: '', stderr, error: stderr })
+}
+
+class FakeRemote {
+  readonly nodes = new Map<string, RemoteNode>()
+  readonly writes: Array<{ path: string; data: string; metadata?: Record<string, string> }> = []
+  readonly writeParentModes: number[] = []
+  readonly renames: Array<{ from: string; to: string }> = []
+  readonly removals: string[] = []
+  readonly commands: string[] = []
+  streamChunks: Uint8Array[] | undefined
+  streamKeepOpen = false
+  readonly streamCancel = vi.fn()
+  nextCommandError: unknown
+  nextMakeDirResult: boolean | undefined
+  nextInfoError: unknown
+  nextListError: unknown
+  nextReadError: unknown
+  nextRenameError: unknown
+  nextRemoveError: unknown
+  canonicalOutput: string | undefined
+  abortAfterRename: AbortController | undefined
+  disappearOnInfo = new Set<string>()
+  private clock = 1
+
+  constructor() {
+    this.dir('/')
+    this.dir('/workspace')
+  }
+
+  dir(path: string): void {
+    this.nodes.set(path, { type: FileType.DIR, data: bytes(''), mode: 0o755, modified: this.clock++ })
+  }
+
+  file(path: string, data: string | readonly number[], mode = 0o644): void {
+    this.nodes.set(path, { type: FileType.FILE, data: bytes(data), mode, modified: this.clock++ })
+  }
+
+  other(path: string): void {
+    this.nodes.set(path, { type: 'other' as FileType, data: bytes(''), mode: 0o600, modified: this.clock++ })
+  }
+
+  symlink(path: string, target: string): void {
+    this.nodes.set(path, {
+      type: FileType.FILE,
+      data: bytes(''),
+      mode: 0o777,
+      modified: this.clock++,
+      symlinkTarget: target,
+    })
+  }
+
+  mutate(path: string, data: string): void {
+    const node = this.required(path)
+    node.data = bytes(data)
+    node.modified = this.clock++
+  }
+
+  private required(path: string): RemoteNode {
+    const node = this.nodes.get(path)
+    if (node === undefined) throw new FileNotFoundError(`missing: ${path}`)
+    return node
+  }
+
+  private followed(path: string): { path: string; node: RemoteNode; link?: RemoteNode } {
+    const node = this.required(path)
+    if (node.symlinkTarget === undefined) return { path, node }
+    return { path: node.symlinkTarget, node: this.required(node.symlinkTarget), link: node }
+  }
+
+  private info(path: string): EntryInfo {
+    if (this.disappearOnInfo.delete(path)) throw new FileNotFoundError(`missing: ${path}`)
+    return this.rawInfo(path)
+  }
+
+  private rawInfo(path: string): EntryInfo {
+    const followed = this.followed(path)
+    const node = followed.node
+    return {
+      name: posix.basename(path),
+      path,
+      type: node.type,
+      size: node.data.byteLength,
+      mode: node.mode,
+      permissions: 'rw-------',
+      owner: 'user',
+      group: 'user',
+      modifiedTime: new Date(node.modified),
+      ...(node.metadata !== undefined ? { metadata: { ...node.metadata } } : {}),
+      ...(followed.link?.symlinkTarget !== undefined ? { symlinkTarget: followed.link.symlinkTarget } : {}),
+    }
+  }
+
+  private checkAbort(options: { signal?: AbortSignal } | undefined): void {
+    if (options?.signal?.aborted === true) throw new DOMException('aborted', 'AbortError')
+  }
+
+  readonly sandbox = {
+    sandboxId: 'fake',
+    files: {
+      makeDir: async (path: string, options?: { signal?: AbortSignal }): Promise<boolean> => {
+        this.checkAbort(options)
+        if (this.nextMakeDirResult !== undefined) {
+          const result = this.nextMakeDirResult
+          this.nextMakeDirResult = undefined
+          return result
+        }
+        if (this.nodes.has(path)) return false
+        this.dir(path)
+        return true
+      },
+      getInfo: async (path: string, options?: { signal?: AbortSignal }): Promise<EntryInfo> => {
+        this.checkAbort(options)
+        if (this.nextInfoError !== undefined) {
+          const error = this.nextInfoError
+          this.nextInfoError = undefined
+          throw error
+        }
+        return this.info(path)
+      },
+      read: async (path: string, options: { format: 'bytes' | 'stream'; signal?: AbortSignal }): Promise<Uint8Array | ReadableStream<Uint8Array> | string> => {
+        this.checkAbort(options)
+        if (this.nextReadError !== undefined) {
+          const error = this.nextReadError
+          this.nextReadError = undefined
+          throw error
+        }
+        const data = this.followed(path).node.data
+        if (options.format === 'bytes') return data.slice()
+        // Pinned-SDK fidelity: a content-length-0 response returns '' even in stream format.
+        if (data.length === 0 && this.streamChunks === undefined) return ''
+        const chunks = this.streamChunks ?? [data.slice()]
+        return new ReadableStream<Uint8Array>({
+          start: (controller) => {
+            for (const chunk of chunks) controller.enqueue(chunk)
+            if (!this.streamKeepOpen) controller.close()
+          },
+          cancel: () => { this.streamCancel() },
+        })
+      },
+      list: async (path: string, options?: { depth?: number; signal?: AbortSignal }): Promise<EntryInfo[]> => {
+        this.checkAbort(options)
+        if (this.nextListError !== undefined) {
+          const error = this.nextListError
+          this.nextListError = undefined
+          throw error
+        }
+        this.required(path)
+        return [...this.nodes.keys()]
+          .filter(candidate => candidate !== path && dirname(candidate) === path)
+          .map(candidate => this.rawInfo(candidate))
+      },
+      write: async (path: string, data: string, options?: { metadata?: Record<string, string>; signal?: AbortSignal }): Promise<object> => {
+        this.checkAbort(options)
+        const parent = dirname(path)
+        if (!this.nodes.has(parent)) this.dir(parent)
+        this.writeParentModes.push(this.required(parent).mode)
+        this.nodes.set(path, {
+          type: FileType.FILE,
+          data: bytes(data),
+          mode: 0o644,
+          modified: this.clock++,
+          ...(options?.metadata !== undefined ? { metadata: { ...options.metadata } } : {}),
+        })
+        this.writes.push({ path, data, ...(options?.metadata !== undefined ? { metadata: options.metadata } : {}) })
+        return {}
+      },
+      rename: async (from: string, to: string, options?: { signal?: AbortSignal }): Promise<EntryInfo> => {
+        this.checkAbort(options)
+        if (this.nextRenameError !== undefined) {
+          const error = this.nextRenameError
+          this.nextRenameError = undefined
+          throw error
+        }
+        const node = this.required(from)
+        this.nodes.delete(from)
+        this.nodes.set(to, node)
+        this.renames.push({ from, to })
+        this.abortAfterRename?.abort('after commit')
+        this.checkAbort(options)
+        return this.info(to)
+      },
+      remove: async (path: string): Promise<void> => {
+        this.removals.push(path)
+        if (this.nextRemoveError !== undefined) {
+          const error = this.nextRemoveError
+          this.nextRemoveError = undefined
+          throw error
+        }
+        for (const candidate of this.nodes.keys()) {
+          if (candidate === path || candidate.startsWith(`${path}/`)) this.nodes.delete(candidate)
+        }
+      },
+    },
+    commands: {
+      run: async (
+        command: string,
+        options?: { envs?: Record<string, string>; signal?: AbortSignal },
+      ): Promise<{ exitCode: number; stdout: string; stderr: string }> => {
+        this.checkAbort(options)
+        const home = options?.envs?.HOME
+        expect(home).toMatch(/^\/\.dsh-e2b-control-/)
+        expect(options?.envs).toEqual({ HOME: home })
+        this.commands.push(command)
+        if (this.nextCommandError !== undefined) {
+          const error = this.nextCommandError
+          this.nextCommandError = undefined
+          throw error
+        }
+        const realpathPrefix = 'set -o pipefail; realpath -mz -- '
+        const realpathSuffix = ' | base64 -w0'
+        if (command.startsWith(realpathPrefix) && command.endsWith(realpathSuffix)) {
+          const quoted = command.slice(realpathPrefix.length, -realpathSuffix.length)
+          const input = quoted.slice(1, -1).replaceAll(String.raw`'"'"'`, '\'')
+          const node = this.nodes.get(input)
+          const canonical = `${node?.symlinkTarget ?? input}\0`
+          return {
+            exitCode: 0,
+            stdout: this.canonicalOutput ?? Buffer.from(canonical).toString('base64'),
+            stderr: '',
+          }
+        }
+        const chmod = /^chmod ([0-7]+) -- '([^']+)'$/.exec(command)
+        if (chmod !== null) this.required(chmod[2]!).mode = Number.parseInt(chmod[1]!, 8)
+        const move = /^mv -f -- '([^']+)' '([^']+)'$/.exec(command)
+        if (move !== null) {
+          if (this.nextRenameError !== undefined) {
+            const error = this.nextRenameError
+            this.nextRenameError = undefined
+            throw error
+          }
+          const node = this.required(move[1]!)
+          this.nodes.delete(move[1]!)
+          this.nodes.set(move[2]!, node)
+          this.renames.push({ from: move[1]!, to: move[2]! })
+          this.abortAfterRename?.abort('after commit')
+        }
+        return { exitCode: 0, stdout: '', stderr: '' }
+      },
+    },
+  } as unknown as Sandbox
+}
+
+async function setup(remote = new FakeRemote()): Promise<{ ctx: Context; fs: E2BFileSystem; remote: FakeRemote }> {
+  const ctx = new Context()
+  const runtime = {
+    cwd: '/workspace',
+    runtimeRoot: '/workspace/.dsh-e2b',
+    getSandbox: async () => remote.sandbox,
+  } as unknown as E2BSandboxService
+  ctx.provide('e2b', runtime)
+  await ctx.plugin(E2BFileSystem)
+  return { ctx, fs: ctx.fs as E2BFileSystem, remote }
+}
+
+async function expectCode(promise: Promise<unknown>, code: string): Promise<void> {
+  await expect(promise).rejects.toMatchObject({ code })
+}
+
+describe('E2BFileSystem identity, metadata, and reads', () => {
+  it('resolves remote paths, reports symlinks, and lists direct children in stable order', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/z.txt', 'z')
+    remote.file('/workspace/a.txt', 'a')
+    remote.dir('/workspace/dir')
+    remote.other('/workspace/special')
+    remote.file('/workspace/dir/nested.txt', 'nested')
+    remote.symlink('/workspace/link.txt', '/workspace/a.txt')
+    const { fs } = await setup(remote)
+
+    const link = await fs.resolve('link.txt')
+    expect(link).toEqual({ targetKey: '/workspace/a.txt', displayPath: '/workspace/link.txt' })
+    await expect(fs.lstat('link.txt')).resolves.toMatchObject({ type: 'symlink', size: 1 })
+    await expect(fs.lstat('a.txt')).resolves.toMatchObject({ type: 'file', size: 1 })
+    await expect(fs.lstat('dir')).resolves.toEqual(expect.objectContaining({ type: 'directory' }))
+    await expect(fs.lstat('special')).resolves.toEqual(expect.objectContaining({ type: 'other' }))
+    await expect(fs.lstat('missing')).resolves.toBeUndefined()
+    await expect(fs.stat(link)).resolves.toMatchObject({ type: 'file', size: 1 })
+    const directory = await fs.resolve('.')
+    const listed = await fs.listDir(directory)
+    expect(listed.map(entry => entry.name)).toEqual(['a.txt', 'dir', 'link.txt', 'special', 'z.txt'])
+    expect(listed.find(entry => entry.name === 'dir')).toMatchObject({ type: 'directory' })
+    expect(listed.find(entry => entry.name === 'link.txt')).toMatchObject({
+      type: 'file',
+      target: { targetKey: '/workspace/a.txt', displayPath: '/workspace/link.txt' },
+    })
+    expect(listed.some(entry => entry.name === 'nested.txt')).toBe(false)
+  })
+
+  it('projects canonical process paths, file URLs, and containment', async () => {
+    const remote = new FakeRemote()
+    remote.dir('/workspace/nested')
+    remote.file('/workspace/nested/multibyte # file.ts', 'text')
+    remote.file('/outside.ts', 'outside')
+    const { fs } = await setup(remote)
+    const workspace = await fs.resolve('/workspace')
+    const nested = await fs.resolve('/workspace/nested/multibyte # file.ts')
+    const outside = await fs.resolve('/outside.ts')
+
+    expect(fs.processPath(nested)).toBe('/workspace/nested/multibyte # file.ts')
+    expect(fs.fileUrl(nested)).toBe('file:///workspace/nested/multibyte%20%23%20file.ts')
+    expect(fs.contains(workspace, workspace)).toBe(true)
+    expect(fs.contains(workspace, nested)).toBe(true)
+    expect(fs.contains(nested, workspace)).toBe(false)
+    expect(fs.contains(workspace, outside)).toBe(false)
+    expect(() => fs.fileUrl({ targetKey: FsTargetKey('relative'), displayPath: 'relative' }))
+      .toThrow('expected an absolute process path')
+  })
+
+  it('preserves newline and multibyte canonical paths through strict ASCII framing', async () => {
+    const remote = new FakeRemote()
+    const path = '/workspace/你好\nfile.ts'
+    remote.file(path, 'text')
+    const { fs } = await setup(remote)
+
+    await expect(fs.resolve(path)).resolves.toEqual({ targetKey: path, displayPath: path })
+  })
+
+  it.each([
+    ['invalid base64', '!!!!'],
+    ['missing terminator', Buffer.from('/workspace/file').toString('base64')],
+    ['multiple records', Buffer.from('/workspace/file\0/other\0').toString('base64')],
+    ['invalid UTF-8', Buffer.from([47, 0xff, 0]).toString('base64')],
+    ['relative path', Buffer.from('workspace/file\0').toString('base64')],
+  ])('rejects %s from canonical path transport', async (_label, output) => {
+    const remote = new FakeRemote()
+    remote.canonicalOutput = output
+    const { fs } = await setup(remote)
+    await expectCode(fs.resolve('file'), 'FS_IO_ERROR')
+  })
+
+  it('reads whole and streamed UTF-8 across chunk boundaries', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/text.txt', 'A€B')
+    remote.streamChunks = [bytes([65, 0xe2]), bytes([0x82, 0xac, 66])]
+    const { fs } = await setup(remote)
+    const target = await fs.resolve('text.txt')
+    await expect(fs.readText(target)).resolves.toBe('A€B')
+    let streamed = ''
+    for await (const chunk of await fs.streamText(target)) streamed += chunk
+    expect(streamed).toBe('A€B')
+
+    remote.streamChunks = [bytes([0xe2]), bytes([0x82, 0xac])]
+    let initiallyBuffered = ''
+    for await (const chunk of await fs.streamText(target)) initiallyBuffered += chunk
+    expect(initiallyBuffered).toBe('€')
+  })
+
+  it('streams an empty file even though the pinned SDK returns a non-stream value', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/empty.txt', '')
+    const { fs } = await setup(remote)
+    let streamed = ''
+    for await (const chunk of await fs.streamText(await fs.resolve('empty.txt'))) streamed += chunk
+    expect(streamed).toBe('')
+  })
+
+  it('cancels a remote stream when its consumer stops early', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/text.txt', 'ab')
+    remote.streamChunks = [bytes('a'), bytes('b')]
+    remote.streamKeepOpen = true
+    const { fs } = await setup(remote)
+    const stream = await fs.streamText(await fs.resolve('text.txt'))
+
+    for await (const chunk of stream) {
+      expect(chunk).toBe('a')
+      break
+    }
+
+    expect(remote.streamCancel).toHaveBeenCalledOnce()
+  })
+
+  it('matches local binary sampling while edits still reject any NUL byte', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/late-nul.txt', `${'a'.repeat(8192)}\0tail`)
+    const { fs } = await setup(remote)
+    const target = await fs.resolve('late-nul.txt')
+    await expect(fs.readText(target)).resolves.toContain('\0tail')
+    remote.streamChunks = [bytes('a'.repeat(8192)), bytes([0, 116])]
+    let streamed = ''
+    for await (const chunk of await fs.streamText(target)) streamed += chunk
+    expect(streamed).toBe(`${'a'.repeat(8192)}\0t`)
+    await expectCode(fs.editText(target, { oldString: 'tail', newString: 'end', replaceAll: false }), 'FS_NOT_TEXT')
+  })
+
+  it('maps binary, invalid UTF-8, missing, and non-regular read failures', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/binary', [0, 1])
+    remote.file('/workspace/invalid', [0xff])
+    remote.dir('/workspace/directory')
+    const { fs } = await setup(remote)
+    await expectCode(fs.readText(await fs.resolve('binary')), 'FS_NOT_TEXT')
+    await expectCode(fs.readText(await fs.resolve('invalid')), 'FS_NOT_TEXT')
+    await expectCode(fs.readText(await fs.resolve('missing')), 'FS_NOT_FOUND')
+    await expectCode(fs.readText(await fs.resolve('directory')), 'FS_NOT_REGULAR_FILE')
+
+    remote.streamChunks = [bytes([0xff])]
+    const invalid = await fs.streamText(await fs.resolve('invalid'))
+    await expect((async () => { for await (const _chunk of invalid) void _chunk })()).rejects.toMatchObject({ code: 'FS_NOT_TEXT' })
+    remote.streamChunks = [bytes([0])]
+    const binary = await fs.streamText(await fs.resolve('binary'))
+    await expect((async () => { for await (const _chunk of binary) void _chunk })()).rejects.toMatchObject({ code: 'FS_NOT_TEXT' })
+
+    remote.streamChunks = [bytes([0xe2])]
+    const incomplete = await fs.streamText(await fs.resolve('invalid'))
+    await expect((async () => { for await (const _chunk of incomplete) void _chunk })()).rejects.toMatchObject({ code: 'FS_NOT_TEXT' })
+
+    const raced = await fs.resolve('invalid')
+    remote.nextReadError = new FileNotFoundError('gone after stat')
+    await expectCode(fs.streamText(raced), 'FS_NOT_FOUND')
+  })
+
+  it('honors aborts before and during remote reads', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/a', 'a')
+    const { fs } = await setup(remote)
+    await expectCode(fs.resolve('a', { signal: AbortSignal.abort() }), 'FS_ABORTED')
+    await expectCode(fs.lstat('a', undefined, AbortSignal.abort()), 'FS_ABORTED')
+    await expectCode(fs.stat(await fs.resolve('a'), AbortSignal.abort()), 'FS_ABORTED')
+    remote.nextReadError = new DOMException('aborted', 'AbortError')
+    await expectCode(fs.readText(await fs.resolve('a')), 'FS_ABORTED')
+  })
+
+  it('rejects empty paths and directory-listing type errors', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/file', 'x')
+    const { fs } = await setup(remote)
+    await expectCode(fs.resolve('   '), 'FS_NOT_FOUND')
+    await expectCode(fs.lstat(''), 'FS_NOT_FOUND')
+    await expectCode(fs.listDir(await fs.resolve('missing')), 'FS_NOT_FOUND')
+    await expectCode(fs.listDir(await fs.resolve('/workspace/file')), 'FS_NOT_DIRECTORY')
+    remote.nextListError = new Error('listing transport failed')
+    await expectCode(fs.listDir(await fs.resolve('/workspace')), 'FS_IO_ERROR')
+  })
+})
+
+describe('E2BFileSystem atomic writes and edits', () => {
+  it('creates owner-only files and returns metadata after the committed move', async () => {
+    const { fs, remote } = await setup()
+    const target = await fs.resolve('new.txt')
+    const outcome = await fs.writeText(target, 'one\r\ntwo\rthree', { kind: 'createIfAbsent' })
+    expect(outcome).toMatchObject({ operation: 'create', before: null, after: 'one\ntwo\rthree' })
+    expect(remote.nodes.get('/workspace/new.txt')?.mode).toBe(0o600)
+    expect(remote.nodes.get('/workspace/new.txt')?.metadata?.['dsh-version']).toBeDefined()
+    expect(remote.writeParentModes).toEqual([0o700])
+    const stagingDirectory = posix.dirname(remote.writes[0]!.path)
+    expect(posix.dirname(stagingDirectory)).toBe('/workspace')
+    expect(remote.removals).toContain(stagingDirectory)
+    await expect(fs.stat(target)).resolves.toMatchObject({ version: outcome.version, size: 14 })
+  })
+
+  it('preserves replacement mode, normalizes only CRLF for diffs, and changes version on external writes', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/file.txt', 'old\r\nline\rlone', 0o640)
+    const { fs } = await setup(remote)
+    const target = await fs.resolve('file.txt')
+    const before = (await fs.stat(target))!.version
+    const outcome = await fs.writeText(target, 'new', { kind: 'replaceIfVersion', version: before })
+    expect(outcome).toMatchObject({ operation: 'update', before: 'old\nline\rlone', after: 'new' })
+    expect(remote.nodes.get('/workspace/file.txt')?.mode).toBe(0o640)
+    const committed = outcome.version
+    remote.mutate('/workspace/file.txt', 'external')
+    expect((await fs.stat(target))!.version).not.toBe(committed)
+  })
+
+  it('returns null as the overwrite diff basis for binary or invalid prior content', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/file.txt', [0xff])
+    const { fs } = await setup(remote)
+    const target = await fs.resolve('file.txt')
+    await expect(fs.writeText(target, 'valid')).resolves.toMatchObject({ before: null, after: 'valid' })
+  })
+
+  it('fails an overwrite when reading its text diff basis fails for another reason', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/file.txt', 'prior')
+    const { fs } = await setup(remote)
+    const target = await fs.resolve('file.txt')
+    remote.nextReadError = new Error('read transport failed')
+    await expectCode(fs.writeText(target, 'replacement'), 'FS_IO_ERROR')
+    expect(new TextDecoder().decode(remote.nodes.get('/workspace/file.txt')?.data)).toBe('prior')
+  })
+
+  it('enforces create and version intents before publication', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/file.txt', 'v1')
+    const { fs } = await setup(remote)
+    const target = await fs.resolve('file.txt')
+    const version = (await fs.stat(target))!.version
+    await expectCode(fs.writeText(target, 'blind', { kind: 'createIfAbsent' }), 'FS_NOT_OBSERVED')
+    remote.mutate('/workspace/file.txt', 'v2')
+    await expectCode(fs.writeText(target, 'stale', { kind: 'replaceIfVersion', version }), 'FS_STALE_VERSION')
+    await expectCode(fs.writeText(await fs.resolve('missing'), 'stale', { kind: 'replaceIfVersion', version }), 'FS_STALE_VERSION')
+    remote.dir('/workspace/dir')
+    await expectCode(fs.writeText(await fs.resolve('dir'), 'x'), 'FS_NOT_REGULAR_FILE')
+  })
+
+  it('does not turn an abort observed after a successful move into a failed write', async () => {
+    const remote = new FakeRemote()
+    const controller = new AbortController()
+    remote.abortAfterRename = controller
+    const { fs } = await setup(remote)
+    await expect(fs.writeText(await fs.resolve('committed'), 'yes', undefined, controller.signal))
+      .resolves.toMatchObject({ operation: 'create' })
+    expect(controller.signal.aborted).toBe(true)
+  })
+
+  it('does not turn post-commit staging cleanup failure into a failed write', async () => {
+    const remote = new FakeRemote()
+    remote.nextRemoveError = new Error('empty staging cleanup failed')
+    const { fs } = await setup(remote)
+    await expect(fs.writeText(await fs.resolve('committed'), 'yes'))
+      .resolves.toMatchObject({ operation: 'create' })
+    expect(new TextDecoder().decode(remote.nodes.get('/workspace/committed')?.data)).toBe('yes')
+  })
+
+  it('returns committed rename metadata without a fallible post-commit lookup', async () => {
+    const remote = new FakeRemote()
+    const getInfo = vi.spyOn(remote.sandbox.files, 'getInfo')
+    const { fs } = await setup(remote)
+
+    await expect(fs.writeText(await fs.resolve('committed'), 'yes'))
+      .resolves.toMatchObject({ operation: 'create' })
+    expect(getInfo).toHaveBeenCalledTimes(1)
+    expect(remote.renames).toHaveLength(1)
+  })
+
+  it('cleans staging files and maps command, permission, and abort failures', async () => {
+    const remote = new FakeRemote()
+    const { fs } = await setup(remote)
+    const commandTarget = await fs.resolve('command')
+    remote.nextCommandError = commandError(1, 'chmod failed')
+    await expectCode(fs.writeText(commandTarget, 'x'), 'FS_IO_ERROR')
+    expect(remote.removals).toHaveLength(1)
+
+    remote.nextRenameError = new Error('permission denied')
+    await expectCode(fs.writeText(await fs.resolve('permission'), 'x'), 'FS_PERMISSION_DENIED')
+    remote.nextRemoveError = new Error('cleanup also failed')
+    remote.nextRenameError = new DOMException('aborted', 'AbortError')
+    await expectCode(fs.writeText(await fs.resolve('abort'), 'x'), 'FS_ABORTED')
+
+    const removalsBeforeCollision = remote.removals.length
+    remote.nextMakeDirResult = false
+    await expectCode(fs.writeText(await fs.resolve('collision'), 'x'), 'FS_IO_ERROR')
+    expect(remote.removals).toHaveLength(removalsBeforeCollision)
+  })
+
+  it('applies literal edits atomically and restores the detected CRLF style', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/file.txt', 'one\r\ntwo\r\nthree\n')
+    const { fs } = await setup(remote)
+    const target = await fs.resolve('file.txt')
+    const version = (await fs.stat(target))!.version
+    const outcome = await fs.editText(
+      target,
+      { oldString: 'two\r\n', newString: 'TWO\r\n', replaceAll: false },
+      { version },
+    )
+    expect(outcome).toMatchObject({ before: 'one\ntwo\nthree\n', after: 'one\nTWO\nthree\n' })
+    expect(new TextDecoder().decode(remote.nodes.get('/workspace/file.txt')?.data)).toBe('one\r\nTWO\r\nthree\r\n')
+  })
+
+  it('reports stale and literal-match failures with stable codes', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/file.txt', 'a a')
+    remote.dir('/workspace/dir')
+    const { fs } = await setup(remote)
+    const target = await fs.resolve('file.txt')
+    await expectCode(fs.editText(target, { oldString: '', newString: 'x', replaceAll: false }), 'FS_EDIT_NOT_FOUND')
+    await expectCode(fs.editText(target, { oldString: 'z', newString: 'x', replaceAll: false }), 'FS_EDIT_NOT_FOUND')
+    await expectCode(fs.editText(target, { oldString: 'a', newString: 'x', replaceAll: false }), 'FS_AMBIGUOUS_EDIT')
+    await expect(fs.editText(target, { oldString: 'a', newString: 'x', replaceAll: true }))
+      .resolves.toMatchObject({ after: 'x x' })
+    await expectCode(fs.editText(target, { oldString: 'x', newString: 'y', replaceAll: false }, { version: FsVersion('stale') }), 'FS_STALE_VERSION')
+    await expectCode(fs.editText(await fs.resolve('missing'), { oldString: 'x', newString: 'y', replaceAll: false }), 'FS_STALE_VERSION')
+    await expectCode(fs.editText(await fs.resolve('dir'), { oldString: 'x', newString: 'y', replaceAll: false }), 'FS_NOT_REGULAR_FILE')
+  })
+
+  it('serializes guarded mutations so only one stale version can win', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/file.txt', 'base')
+    const { fs } = await setup(remote)
+    const target = await fs.resolve('file.txt')
+    const version = (await fs.stat(target))!.version
+    const results = await Promise.allSettled([
+      fs.writeText(target, 'one', { kind: 'replaceIfVersion', version }),
+      fs.editText(target, { oldString: 'base', newString: 'two', replaceAll: false }, { version }),
+    ])
+    expect(results.filter(result => result.status === 'fulfilled')).toHaveLength(1)
+    expect(results.filter(result => result.status === 'rejected')).toHaveLength(1)
+  })
+})
+
+describe('E2B filesystem adapter integration edges', () => {
+  it('maps canonicalization, permission, and generic provider failures', async () => {
+    const remote = new FakeRemote()
+    const { fs } = await setup(remote)
+    remote.nextCommandError = commandError(1, 'not a directory')
+    await expectCode(fs.resolve('bad'), 'FS_IO_ERROR')
+    remote.nextCommandError = commandError(1)
+    await expectCode(fs.resolve('bad-again'), 'FS_IO_ERROR')
+    remote.nextCommandError = new Error('canonical transport failed')
+    await expectCode(fs.resolve('bad-transport'), 'FS_IO_ERROR')
+    remote.file('/workspace/a', 'a')
+    const target = await fs.resolve('a')
+    remote.nextInfoError = new Error('metadata transport failed')
+    await expectCode(fs.stat(target), 'FS_IO_ERROR')
+    remote.nextReadError = new Error('operation not permitted')
+    await expectCode(fs.readText(target), 'FS_PERMISSION_DENIED')
+    remote.nextReadError = 'transport vanished'
+    await expectCode(fs.readText(target), 'FS_IO_ERROR')
+  })
+
+  it('uses listing metadata directly and canonicalizes only symbolic links', async () => {
+    const remote = new FakeRemote()
+    remote.file('/workspace/a', 'a')
+    remote.file('/workspace/target', 'target')
+    remote.file('/workspace/gone', 'gone')
+    remote.symlink('/workspace/link', '/workspace/target')
+    remote.symlink('/workspace/vanished-link', '/workspace/gone')
+    remote.disappearOnInfo.add('/workspace/gone')
+    const { fs } = await setup(remote)
+    const directory = await fs.resolve('/workspace')
+    const commandsBefore = remote.commands.length
+    const getInfo = vi.spyOn(remote.sandbox.files, 'getInfo')
+
+    const listed = await fs.listDir(directory)
+
+    expect(listed.find(entry => entry.name === 'a')).toMatchObject({
+      type: 'file', target: { targetKey: '/workspace/a' }, size: 1,
+    })
+    expect(listed.find(entry => entry.name === 'link')).toMatchObject({
+      type: 'file', target: { targetKey: '/workspace/target' }, size: 6,
+    })
+    expect(listed.find(entry => entry.name === 'vanished-link')).toEqual({
+      name: 'vanished-link',
+      type: 'other',
+      target: { targetKey: '/workspace/gone', displayPath: '/workspace/vanished-link' },
+    })
+    expect(remote.commands.slice(commandsBefore)).toHaveLength(2)
+    expect(getInfo).toHaveBeenCalledTimes(3)
+  })
+
+  it('registers the package-owned empty invariant installer', async () => {
+    const ctx = new Context()
+    await ctx.plugin(InvariantService, { enabled: true })
+    const fiber = await ctx.plugin(E2BFsInvariant).await()
+    await fiber.dispose()
+  })
+})

packages/e2b/fs-e2b/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": ["src"],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../e2b"
+    },
+    {
+      "path": "../../fs/fs"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}

packages/e2b/subprocess-e2b/README.i18n.yaml

@@ -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/e2b/subprocess-e2b/README.md
+README.md: 926d4f22f8e96daa103c236121d35e461290221a
+README.zh.md: d1634b6d1a701f7f4815135b4ec6bb86ad1a8c87

packages/e2b/subprocess-e2b/README.md

@@ -0,0 +1,43 @@
+# @deepseek-ai/dsh-subprocess-e2b
+
+English | [中文](README.zh.md)
+
+E2B implementation of the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) seam. Load [`@deepseek-ai/dsh-e2b`](../e2b/README.md) first, then this service in place of `dsh-subprocess-local`. Existing Bash, PTY, and LSP consumers then execute in the shared remote sandbox without E2B-specific capability packages.
+
+## Configuration
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `pollMs` | `20` | Remote status/liveness poll cadence in milliseconds; each tick is one control-plane request, so a larger value trades exit-observation latency for fewer requests. |
+
+## Behavior
+
+- **Asynchronous remote start** — the synchronous seam returns a handle immediately while `Sandbox.commands.run(..., { background: true })` starts remotely. `pid` is `-1` until the wrapper publishes and the adapter validates its process-group id; stdin and ordinary observation wait for that publication. An owned startup signal aborts environment and private-state preparation before allocation; once allocation begins, cancellation waits for a provisional SDK handle it can clean.
+- **Execution-world coordinates** — `cwd` and private `runtimeRoot` come from the shared owner; executable lookup verifies absolute paths or resolves a bare name against the sandbox PATH plus explicit overrides, and rejects relative paths containing separators like every subprocess provider.
+- **Linux process groups** — a quoted wrapper starts each argv under `exec setsid --wait` and records its actual process-group id plus private status files beneath `ctx.e2b.runtimeRoot/processes`. The handle waits for that file instead of treating the SDK command PID as its published identity. Termination signals the negative recorded id with `SIGTERM`, waits the caller's `graceMs`, then escalates to `SIGKILL` and the SDK kill fallback; TERM delivery or probe failures also force that escalation. Process-table probes treat groups containing only zombie or dead entries as quiescent. Force cleanup succeeds only after a bounded probe finds the group empty; otherwise `waitForExit()` exposes a retryable failure, while proven quiescence makes later termination a no-op. Publication and monitoring failures apply the same cleanup transaction before rejecting. Service disposal rejects new starts, terminates and joins every retained process group, then awaits SDK settlement and private cleanup before the sandbox owner disposes.
+- **Environment boundary** — one trusted control-shell probe resolves the sandbox user's login home from its passwd entry and transports the sandbox environment as base64 ASCII for one strict UTF-8 decode; the wrapper then removes ambient `DSH_*` and credential-shaped (`*KEY*`, `*SECRET*`, `*TOKEN*`) names and restores every valid `spec.env` entry as an explicit caller opt-in. Empty names, `=`, and NUL framing violations reject before launch. Subsequent E2B command and PTY login shells receive a fresh randomized root-level `HOME` plus empty overrides for every scrubbed ambient name before user profiles can run; the requested argv receives the serialized environment afterward without changing the sandbox user's umask. Host ambient variables never enter the sandbox implicitly. Private environment files are removed after consumption, and failed command or terminal setup removes its private state before rejecting.
+- **Stdio projection** — the remote wrapper branches raw bytes into optional bounded spill files, frames each live chunk as newline-delimited base64 ASCII, and the host incrementally restores bytes across arbitrary SDK callback boundaries. Pipe mode writes those bytes to host Node streams; inherit mode writes them to the harness process streams; collect mode retains a bounded host tail with offset reads. The wrapper publishes the direct command status before waiting for inherited writers. For collect or inherit output, the adapter disconnects an incomplete SDK stream after `graceMs`, withholds its partial spill, and returns that status while retaining the remote group for `waitForExit()` and termination. Natural raw-pipe completion instead awaits lossless transport and preserves backpressure; explicit termination destroys the host pipes and releases blocked output before remote cleanup. Batch and streaming stdin use the SDK handle.
+- **Terminal sessions** — `spawnTerminal()` uses E2B's byte PTY API, installs the exact argv and scrubbed environment through private mode-`0600` files, reports the foreground process group, sends real signals, and tears down every live group in the remote terminal session through one retryable awaited `terminate()`; termination rejects new handle operations, aborts and joins in-flight writes, inspections, and signals, and treats zombie-only groups as quiescent. A private random output boundary discards the E2B bootstrap shell's prompt and echoed runner command while preserving every requested-process byte, including its first prompt. Terminal output is pushed to the handle's stream without awaiting host backpressure: a flowing consumer (the PTY backend attaches one at construction) folds bytes into its own bounded state, while a paused consumer buffers in host memory. PTY allocation is awaited through handle publication before cancellation is observed, so owned rollback can clean the published handle. Setup and teardown own the private state transaction, abort pending setup during service disposal, and fence publication; sandbox disposal or timeout bounds a setup rollback that also fails. Prompt detection, scrollback, readiness, and owner policy remain in `dsh-pty-local`.
+- **Sandbox disappearance** — `SandboxNotFoundError` during process or terminal liveness, termination, rollback, or disconnect proves the remote execution world cannot retain work, so cleanup treats it as quiescent; unrelated failures remain observable.
+
+The default E2B base image supplies the runtime and Bash/GNU utilities this adapter invokes: `node`, `bash`, `setsid`, `ps`, `awk`, `tr`, `env`, `base64`, `chmod`, `tee`, `head`, `rm`, `kill`, `id`, and `getent`.
+
+## Model Experience
+
+Indirectly, through consumer seams such as the Bash executor behind `dsh-tool-bash`, which render remote output, exit facts, background deltas, and spill paths.
+
+#### KV Cache effect
+
+No direct invalidation; the named consumers own any request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+- **The SDK still retains complete command output in host memory** — E2B `CommandHandle.stdout` and `.stderr` accumulate the base64 transport even when this adapter exposes bounded raw-byte tails, so the subprocess seam's normal host-memory bound is not achieved and transport retention is larger than the source stream.
+- **Synchronous-PID consumers are unsupported** — `pid` remains `-1` during remote startup; consumers that require a positive PID immediately, including the ACP child backend, cannot use this provider unchanged.
+- **Private state lives for the sandbox lifetime** — process directories and valid spill files remain under `.dsh-e2b` until the owner deletes the sandbox; this POC supplies no in-sandbox sweep.
+- **Control state shares the sandbox user's UID** — E2B runs every command as the same default user, so `0700`/`0600` modes cannot isolate `.dsh-e2b` control files from concurrently running sandbox processes. A background process could rewrite `pid`/`exit-code` or read a not-yet-consumed `environment` file. The adapter validates published values and refuses group ids whose negative form is unsafe to signal (`<= 1`), but real isolation needs an E2B per-command user or an out-of-band control channel.
+- **Numeric process identities are not reuse-fenced** — E2B exposes numeric PID/PGID PTY input, signalling, and cleanup operations but no atomic identity-bound alternative. The adapter minimizes host round trips and live coverage exercises the reproducible stale-interrupt overlap; replacement is deferred until E2B adds an identity primitive or a failure demonstrates a narrower protocol.
+- **The initial environment probe inherits sandbox defaults** — E2B merges command overrides with default environment entries, so the probe cannot blank unknown credential-shaped names before enumerating them. A same-UID untrusted process already in the sandbox could inspect that short-lived control shell; this POC therefore does not support secrets in sandbox-default environment variables and requires an E2B replacement-environment primitive to close the gap.
+- **E2B exposes no signal fact** — an adapter-requested `SIGTERM` or `SIGKILL` is reported only when no wrapper-published direct exit code wins; every unrequested SDK exit remains an exit code, including values shaped like `128 + signal`.
+- **Exact terminal stdin-wait inspection is unavailable** — E2B exposes the foreground process group but not the syscall evidence needed to prove it is waiting on fd 0, so the generic PTY backend falls back to controlled prompt markers and bounded silence.
+- **Linux utility and E2B transport semantics are assumed** — there is no Windows, escaped-session recovery, or network-partition fidelity layer.

packages/e2b/subprocess-e2b/README.zh.md

@@ -0,0 +1,43 @@
+# @deepseek-ai/dsh-subprocess-e2b
+
+[English](README.md) | 中文
+
+[`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) seam 的 E2B 实现。先加载 [`@deepseek-ai/dsh-e2b`](../e2b/README.md)，再用本服务取代 `dsh-subprocess-local`。现有的 Bash、PTY 和 LSP 消费方随后会在共享远程沙箱中执行，无需 E2B 专用的功能包（package）。
+
+## 配置
+
+| 键 | 默认值 | 含义 |
+| --- | --- | --- |
+| `pollMs` | `20` | 远程状态／存活轮询节奏（毫秒）；每个 tick 是一次控制面请求，调大该值以牺牲退出观察延迟换取更少的请求。 |
+
+## 行为
+
+- **异步远程启动**：同步 seam 会立即返回一个句柄，同时由 `Sandbox.commands.run(..., { background: true })` 在远程启动进程。包装层发布进程组 ID 并由适配器完成验证之前，`pid` 为 `-1`；stdin 和常规观察会等待该发布。自有启动信号会在分配前中止环境和私有状态准备；分配开始后，取消会等待可清理的临时 SDK 句柄。
+- **执行世界坐标**：`cwd` 和私有 `runtimeRoot` 来自共享所有者；可执行文件查找会验证绝对路径，或根据沙箱 PATH 加显式覆盖来解析裸名称，并与所有 subprocess 提供方一致地拒绝含分隔符的相对路径。
+- **Linux 进程组**：带引号保护的包装层会在 `exec setsid --wait` 下启动每组 argv，并在 `ctx.e2b.runtimeRoot/processes` 下记录实际进程组 ID 和私有状态文件。句柄会等待该文件，而不会把 SDK 命令 PID 当作已发布的身份。终止操作以记录的负数 ID 发送 `SIGTERM`，等待调用方的 `graceMs`，再升级到 `SIGKILL` 和 SDK kill 回退；TERM 信号发送或探测失败也会强制触发该升级。进程表探测会把仅含僵尸或已死亡条目的进程组视为完全停稳。强制清理只有在有界探测发现进程组为空后才算成功；否则 `waitForExit()` 会公开可重试的失败，而已证明的完全停稳会让后续终止操作不再执行任何动作。发布失败与监控失败都会在拒绝前执行同一清理事务。服务 dispose（资源释放）会拒绝新的启动请求、终止并等待每个保留进程组退出，再等待 SDK 结算和私有清理完成，之后沙箱所有者才会释放。
+- **环境边界**：一次受信任的控制 shell 探测会从 passwd 条目解析沙箱用户的登录主目录，以 base64 ASCII 传输沙箱环境，再进行一次严格 UTF-8 解码；随后包装层移除环境中的 `DSH_*` 和形似凭据的名称（`*KEY*`、`*SECRET*`、`*TOKEN*`），并把每个有效的 `spec.env` 条目恢复为调用方显式选择。空名称、`=` 和违反 NUL 分帧规则的条目会在启动前被拒绝。在用户 profile 脚本运行前，此后的 E2B 命令 shell 与 PTY 登录 shell 会获得位于根目录下、全新随机生成的 `HOME`，并为每个被清理的环境变量名设置空值覆盖；之后，请求的 argv 会在不改变沙箱用户 umask 的前提下接收序列化环境。宿主环境变量绝不会隐式进入沙箱。私有环境文件在使用后会被删除；命令或终端设置失败时，会先删除其私有状态再拒绝。
+- **stdio 投影**：远程包装层先把原始字节分流到可选的有界 spill 文件，再把每个实时分片编码为换行分隔的 base64 ASCII 帧；宿主会跨任意 SDK 回调边界增量恢复字节。pipe 模式把这些字节写入宿主 Node 流；inherit 模式把字节写入 harness 进程流；collect 模式保留有界的宿主尾部，并支持基于偏移量读取。包装层会在等待继承管道的写入方之前发布直接命令状态。对于 collect 或 inherit 输出，超过 `graceMs` 后，适配器会断开未完成的 SDK 流，不公开其中不完整的 spill，并返回该状态，同时保留远程进程组供 `waitForExit()` 和终止操作使用。原始 pipe 自然完成时，会等待无损传输完成并保留背压；显式终止则会销毁宿主 pipe，并在远程清理前释放受阻的输出写入。批量 stdin 和流式 stdin 都使用 SDK 句柄。
+- **终端会话**：`spawnTerminal()` 使用 E2B 的字节 PTY API，以 mode 为 `0600` 的私有文件传入原样 argv 与清理后的环境，报告前台进程组，发送真实信号，并通过一项可重试且须等待的 `terminate()` 清理远程终端会话中仍存活的每个进程组；终止会拒绝新的句柄操作，中止并等待在途写入、检查和信号操作结算，并把仅含僵尸进程的进程组视为已经完全停稳。私有随机输出边界会丢弃 E2B 引导 shell 的提示符和回显的 runner 命令，同时保留请求进程的每个字节，包括其第一个提示符。终端输出推入句柄流时不等待宿主背压：流动的消费方（PTY 后端在构造时就挂上一个）把字节折叠进自身的有界状态，而暂停的消费方会在宿主内存中缓冲。PTY 分配会一直等待到句柄发布后才观察取消，以便由承担清理责任的回滚清理已发布句柄。setup 与 teardown 负责私有状态事务，在服务 dispose 期间中止待处理的 setup 并阻止发布；若 setup 回滚也失败，则由沙箱 dispose 或超时约束其存活时间。提示符检测、scrollback、就绪状态与所有者策略仍归 `dsh-pty-local` 所有。
+- **沙箱消失**：在进程或终端的存活探测、终止、回滚或断开连接期间出现 `SandboxNotFoundError`，证明远程执行环境无法保留工作，因此清理会将其视为完全停稳；其他故障仍可观察。
+
+E2B 默认基础镜像提供该适配器调用的运行时和 Bash/GNU 工具：`node`、`bash`、`setsid`、`ps`、`awk`、`tr`、`env`、`base64`、`chmod`、`tee`、`head`、`rm`、`kill`、`id` 和 `getent`。
+
+## 模型体验
+
+通过消费方 seam 间接影响模型，例如 `dsh-tool-bash` 背后的 Bash 执行器；这些消费方会渲染远程输出、退出事实、后台增量和 spill 路径。
+
+#### KV Cache 影响
+
+不会直接失效；请求前缀变更由具名消费方负责。
+
+## 已知限制与延后工作
+
+- **SDK 仍会在宿主内存中保留完整命令输出**：即使本适配器公开的是有界原始字节尾部，E2B `CommandHandle.stdout` 和 `.stderr` 仍会累积 base64 传输内容，因此无法达到进程管理 seam 通常提供的宿主内存边界，而且传输保留量大于源数据流。
+- **不支持需要同步 PID 的消费方**：远程启动期间，`pid` 保持为 `-1`；包括 ACP 子进程后端在内，要求立即获得正 PID 的消费方无法原样使用本提供方。
+- **私有状态随沙箱生命周期存在**：进程目录和有效的 spill 文件会留在 `.dsh-e2b` 下，直到所有者删除沙箱；本 POC 不提供沙箱内清理。
+- **控制状态与沙箱用户同 UID**：E2B 以同一默认用户运行每条命令，因此 `0700`/`0600` 权限无法把 `.dsh-e2b` 控制文件与并发运行的沙箱进程隔离开。后台进程可以改写 `pid`/`exit-code`，或读取尚未被消费的 `environment` 文件。适配器会验证已发布的值，并拒绝取负后不安全的进程组 ID（`<= 1`），但真正的隔离需要 E2B 提供按命令用户或带外控制通道。
+- **数值进程身份没有复用围栏**：E2B 公开基于数值 PID/PGID 的 PTY 输入、信号发送和清理操作，却没有与身份原子绑定的替代方案。适配器会尽量减少宿主往返，真实环境测试会覆盖可复现的陈旧中断重叠；在 E2B 新增身份原语，或实际故障证明需要更窄的协议之前，替代方案会继续延后。
+- **初始环境探测会继承沙箱默认值**：E2B 会把命令覆盖与默认环境条目合并，因此探测无法在枚举未知且形似凭据的名称之前将它们置空。一个已在沙箱内运行的同 UID 不可信进程可以检查该短时存在的控制 shell；因此，该 POC 不支持把 secret 放入沙箱默认环境变量，需要 E2B 的替换环境原语才能弥合该缺口。
+- **E2B 不公开信号事实**：适配器请求的 `SIGTERM` 或 `SIGKILL` 只有在包装层发布的直接退出码没有胜出时才报告为信号；其他未请求的 SDK 退出始终保留为退出码，包括形似 `128 + signal` 的值。
+- **无法精确检查终端 stdin 等待状态**：E2B 会公开前台进程组，但不提供证明其正在等待 fd 0 所需的 syscall 证据，因此通用 PTY 后端会回退到受控提示符标记与有界静默机制。
+- **依赖 Linux 工具与 E2B 传输语义**：没有 Windows、逃逸会话恢复或网络分区的保真层。

packages/e2b/subprocess-e2b/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@deepseek-ai/dsh-subprocess-e2b",
+  "description": "E2B subprocess implementation for DeepSeek Harness",
+  "version": "0.0.1",
+  "private": true,
+  "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"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-e2b": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-subprocess": "^0.0.1",
+    "@deepseek-ai/dsh-timeout": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-e2b": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-subprocess": "workspace:^",
+    "@deepseek-ai/dsh-timeout": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}

packages/e2b/subprocess-e2b/src/environment.ts

@@ -0,0 +1,104 @@
+/** Shared remote-environment scrubbing for E2B process and terminal launchers. */
+
+import { Buffer } from 'node:buffer'
+import { posix } from 'node:path'
+import { e2bControlEnvs } from '@deepseek-ai/dsh-e2b'
+import type { Sandbox } from '@deepseek-ai/dsh-e2b'
+import { SENSITIVE_ENV_PATTERN } from '@deepseek-ai/dsh-subprocess'
+
+const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/
+
+function remoteEnvironmentEntries(raw: string): Array<readonly [string, string]> {
+  const entries: Array<readonly [string, string]> = []
+  for (const entry of raw.split('\0')) {
+    if (entry.length === 0) continue
+    const separator = entry.indexOf('=')
+    if (separator <= 0) continue
+    entries.push([entry.slice(0, separator), entry.slice(separator + 1)])
+  }
+  return entries
+}
+
+/**
+ * Read the remote environment through ASCII base64 so SDK callback chunking cannot corrupt UTF-8.
+ * @param sandbox - shared E2B execution world.
+ * @param signal - optional cancellation for the control-plane request.
+ * @returns the complete NUL-delimited UTF-8 environment.
+ */
+export async function readRemoteEnvironment(sandbox: Sandbox, signal?: AbortSignal): Promise<string> {
+  // TODO(e2b-replace-environment): Remove this ambient probe when E2B can start
+  // a command with a replacement environment instead of merged overrides.
+  const result = await sandbox.commands.run(
+    'set -o pipefail; dsh_e2b_passwd="$(getent passwd "$(id -u)")"; IFS=: read -r _ _ _ _ _ dsh_e2b_home _ <<<"$dsh_e2b_passwd"; test -n "$dsh_e2b_home" -a -d "$dsh_e2b_home"; printf \'%s\' "$dsh_e2b_home" | base64 -w 0; printf \'\\n\'; env -0 | base64 -w 0',
+    { envs: e2bControlEnvs(), ...(signal === undefined ? {} : { signal }) },
+  )
+  const lines = result.stdout.trim().split('\n')
+  if (lines.length !== 2 || !lines.every(line => BASE64.test(line))) {
+    throw new Error('subprocess-e2b: remote environment transport returned invalid base64')
+  }
+  const [encodedHome, encodedEnvironment] = lines as [string, string]
+  let home: string
+  let raw: string
+  try {
+    const decoder = new TextDecoder('utf-8', { fatal: true })
+    home = decoder.decode(Buffer.from(encodedHome, 'base64'))
+    raw = decoder.decode(Buffer.from(encodedEnvironment, 'base64'))
+  } catch (error: unknown) {
+    throw new Error('subprocess-e2b: remote environment is not valid UTF-8', { cause: error })
+  }
+  if (!posix.isAbsolute(home) || home.includes('\0')) {
+    throw new Error(`subprocess-e2b: remote login home is invalid: ${JSON.stringify(home)}`)
+  }
+  const environment = new Map(remoteEnvironmentEntries(raw))
+  environment.set('HOME', home)
+  return [...environment].map(([name, value]) => `${name}=${value}\0`).join('')
+}
+
+/**
+ * Parse an E2B NUL-delimited environment while removing harness-private and credential-shaped names.
+ * @param raw - The complete NUL-delimited remote environment.
+ * @returns Mutable retained entries for the caller to overlay and serialize.
+ */
+export function scrubRemoteEnvironment(raw: string): Map<string, string> {
+  const environment = new Map<string, string>()
+  for (const [name, value] of remoteEnvironmentEntries(raw)) {
+    if (name.startsWith('DSH_') || SENSITIVE_ENV_PATTERN.test(name)) continue
+    environment.set(name, value)
+  }
+  return environment
+}
+
+/**
+ * Isolate E2B's fixed login-shell bootstrap from user profiles and ambient credentials.
+ * @param raw - The complete NUL-delimited remote environment.
+ * @returns Explicit E2B command or PTY overrides for bootstrap-shell startup.
+ */
+export function bootstrapEnvironment(raw: string): Record<string, string> {
+  const environment: Record<string, string> = { TERM: 'dumb' }
+  for (const [name] of remoteEnvironmentEntries(raw)) {
+    if (name.startsWith('DSH_') || SENSITIVE_ENV_PATTERN.test(name)) environment[name] = ''
+  }
+  return environment
+}
+
+/**
+ * Overlay explicit entries and serialize one validated E2B environment.
+ * @param raw - The complete NUL-delimited remote environment.
+ * @param explicit - Deliberate caller overrides applied after ambient scrubbing; an `undefined` tombstone removes an ambient entry.
+ * @returns NUL-delimited `name=value` entries accepted by `env -i`.
+ */
+export function serializeRemoteEnvironment(
+  raw: string,
+  explicit: Readonly<NodeJS.ProcessEnv> | undefined,
+): string {
+  const environment = scrubRemoteEnvironment(raw)
+  for (const [name, value] of Object.entries(explicit ?? {})) {
+    if (name.length === 0 || name.includes('=') || name.includes('\0') || value?.includes('\0') === true) {
+      throw new Error('subprocess-e2b: environment entries require non-empty NUL-free names without = and NUL-free values')
+    }
+    // An explicit undefined is the seam's tombstone: remove the ambient entry.
+    if (value === undefined) environment.delete(name)
+    else environment.set(name, value)
+  }
+  return [...environment].map(([name, value]) => `${name}=${value}\0`).join('')
+}

packages/e2b/subprocess-e2b/src/index.ts

@@ -0,0 +1,208 @@
+/**
+ * E2B implementation of the subprocess seam. Each handle starts through the
+ * shared sandbox and retains command output/status paths in that remote world.
+ * @module @deepseek-ai/dsh-subprocess-e2b
+ */
+
+import { randomUUID } from 'node:crypto'
+import { posix } from 'node:path'
+import { Context } from 'cordis'
+import z from 'schemastery'
+import { SubprocessService } from '@deepseek-ai/dsh-subprocess'
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
+import type {
+  SubprocessHandle,
+  SubprocessSpawnSpec,
+  SubprocessTerminalHandle,
+  SubprocessTerminalSpawnSpec,
+} from '@deepseek-ai/dsh-subprocess'
+import { e2bControlEnvs, quoteE2BShellArg } from '@deepseek-ai/dsh-e2b'
+import { E2BSubprocessHandle } from './process.ts'
+import { asError, signalOpts } from './remote.ts'
+import { spawnE2BTerminal } from './terminal.ts'
+
+/** Configuration for the E2B subprocess adapter. */
+export interface Config {
+  /** Remote status/liveness poll cadence in milliseconds; each tick is one control-plane request. */
+  pollMs?: number
+}
+
+interface SchemaResolvedConfig extends Config {
+  pollMs: number
+}
+
+interface TerminalSetup {
+  done: Promise<void>
+  controller: AbortController
+}
+
+/**
+ * Enforce the seam's documented grace bound (positive, finite, one Node timer),
+ * matching subprocess-local's spawn-time check; an unbounded grace would make
+ * the remote force-escalation deadline unreachable.
+ * @param graceMs - The spec's cleanup grace in milliseconds.
+ */
+function requireRepresentableGrace(graceMs: number): void {
+  if (!Number.isFinite(graceMs) || graceMs <= 0 || graceMs > MAX_TIMER_DELAY_MS) {
+    throw new Error(`subprocess graceMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`)
+  }
+}
+
+/** E2B command manager registered as `ctx.subprocess`. */
+export class E2BSubprocessService extends SubprocessService {
+  static inject = ['e2b']
+
+  static Config: z<Config> = z.object({
+    pollMs: z.number().default(20),
+  })
+
+  private readonly live = new Set<E2BSubprocessHandle>()
+  private readonly terminals = new Set<SubprocessTerminalHandle>()
+  private readonly terminalSetups = new Set<TerminalSetup>()
+  private readonly pollMs: number
+  private disposing = false
+
+  /** Create the E2B subprocess service and bind its disposal policy. */
+  constructor(ctx: Context, config: Config) {
+    super(ctx)
+    // Schemastery fills pollMs before construction; the type does not encode that step.
+    const { pollMs } = config as SchemaResolvedConfig
+    if (!Number.isSafeInteger(pollMs) || pollMs <= 0) {
+      throw new Error('subprocess-e2b: pollMs must be a positive safe integer')
+    }
+    this.pollMs = pollMs
+    ctx.effect(() => async () => {
+      this.disposing = true
+      for (const setup of this.terminalSetups) {
+        setup.controller.abort(new Error('subprocess-e2b: service disposed during terminal setup'))
+      }
+      await Promise.all([...this.terminalSetups].map(setup => setup.done))
+      const handles = [...this.live]
+      const terminals = [...this.terminals]
+      const pending: Promise<unknown>[] = []
+      for (const handle of handles) {
+        handle.terminate()
+        pending.push(handle.waitForExit().then(async () => {
+          await handle.done.catch(() => undefined)
+          this.live.delete(handle)
+        }))
+      }
+      for (const terminal of terminals) {
+        pending.push(terminal.terminate().then(() => { this.terminals.delete(terminal) }))
+      }
+      const outcomes = await Promise.allSettled(pending)
+      const failures = outcomes.flatMap<unknown>(outcome => outcome.status === 'rejected'
+        ? [outcome.reason as unknown]
+        : [])
+      if (failures.length === 1) throw asError(failures[0])
+      if (failures.length > 1) throw new AggregateError(failures, 'subprocess-e2b: teardown failed')
+    }, 'e2b subprocess teardown')
+  }
+
+  /** @inheritdoc */
+  async resolveExecutable(
+    command: string,
+    env?: Readonly<Record<string, string>>,
+    signal?: AbortSignal,
+  ): Promise<string> {
+    if (command.length === 0) throw new Error('subprocess-e2b: executable name must be non-empty')
+    signal?.throwIfAborted()
+    const sandbox = await this.ctx.e2b.getSandbox()
+    if (posix.isAbsolute(command)) {
+      await sandbox.commands.run(
+        `test -f ${quoteE2BShellArg(command)} -a -x ${quoteE2BShellArg(command)}`,
+        { envs: e2bControlEnvs(), ...signalOpts(signal) },
+      )
+      signal?.throwIfAborted()
+      return command
+    }
+    if (command.includes('/')) {
+      throw new Error(
+        `subprocess-e2b: command ${JSON.stringify(command)} is a relative path; use an absolute path or a bare PATH name`,
+      )
+    }
+    const path = env?.PATH
+    const prefix = path === undefined ? '' : `PATH=${quoteE2BShellArg(path)} `
+    const result = await sandbox.commands.run(
+      `${prefix}command -v -- ${quoteE2BShellArg(command)}`,
+      { cwd: this.ctx.e2b.cwd, envs: e2bControlEnvs(), ...signalOpts(signal) },
+    )
+    signal?.throwIfAborted()
+    const executable = result.stdout.trim()
+    if (executable.includes('\n') || (!posix.isAbsolute(executable) && !executable.includes('/'))) {
+      throw new Error(`subprocess-e2b: executable ${JSON.stringify(command)} did not resolve to one absolute path`)
+    }
+    // A relative result comes from a relative PATH entry; the lookup ran with the shared cwd.
+    return posix.resolve(this.ctx.e2b.cwd, executable)
+  }
+
+  /** @inheritdoc */
+  spawn(spec: SubprocessSpawnSpec): SubprocessHandle {
+    if (this.disposing) throw new Error('subprocess-e2b: service is disposing')
+    const program = spec.argv[0]
+    if (program === undefined || program.length === 0) {
+      throw new Error('invalid argv: expected a non-empty program name at argv[0]')
+    }
+    requireRepresentableGrace(spec.graceMs)
+    if (spec.signal?.aborted === true) {
+      throw new Error(`aborted before spawn: ${String(spec.signal.reason)}`)
+    }
+    const stateDir = posix.join(this.ctx.e2b.runtimeRoot, 'processes', randomUUID())
+    const handle = new E2BSubprocessHandle(this.ctx.e2b, spec, stateDir, this.pollMs)
+    this.live.add(handle)
+    const release = async (): Promise<void> => {
+      await handle.waitForExit()
+      this.live.delete(handle)
+    }
+    void handle.done.then(release, release).catch((_automaticReleaseFailure: unknown) => {
+      // Retain the handle so service disposal can retry its cleanup transaction.
+    })
+    return handle
+  }
+
+  /** @inheritdoc */
+  async spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle> {
+    if (this.disposing) throw new Error('subprocess-e2b: service is disposing')
+    const program = spec.argv[0]
+    if (program === undefined || program.length === 0) {
+      throw new Error('subprocess-e2b: terminal argv must contain a program')
+    }
+    requireRepresentableGrace(spec.graceMs)
+    spec.signal?.throwIfAborted()
+    const stateDir = posix.join(this.ctx.e2b.runtimeRoot, 'terminals', randomUUID())
+    const done = Promise.withResolvers<void>()
+    const setup: TerminalSetup = { done: done.promise, controller: new AbortController() }
+    const setupSignal = spec.signal === undefined
+      ? setup.controller.signal
+      : AbortSignal.any([spec.signal, setup.controller.signal])
+    this.terminalSetups.add(setup)
+    try {
+      const terminal = await spawnE2BTerminal(
+        this.ctx.e2b,
+        { ...spec, signal: setupSignal },
+        stateDir,
+        this.pollMs,
+      )
+      this.terminals.add(terminal)
+      // oxlint-disable-next-line typescript/no-unnecessary-condition -- Remote allocation yields to disposal.
+      if (this.disposing) {
+        await terminal.terminate()
+        this.terminals.delete(terminal)
+        throw new Error('subprocess-e2b: service disposed during terminal setup')
+      }
+      const release = async (): Promise<void> => {
+        await terminal.terminate()
+        this.terminals.delete(terminal)
+      }
+      void terminal.done.then(release, release).catch((_automaticReleaseFailure: unknown) => {
+        // Retain the terminal so service disposal can retry its cleanup transaction.
+      })
+      return terminal
+    } finally {
+      this.terminalSetups.delete(setup)
+      done.resolve()
+    }
+  }
+}
+
+export default E2BSubprocessService

packages/e2b/subprocess-e2b/src/invariant.ts

@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-subprocess-e2b`.
+ * @module @deepseek-ai/dsh-subprocess-e2b/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-subprocess-e2b'
+
+/** Cordis companion plugin name. */
+export const name = 'subprocess-e2b-invariant'
+/** Service required before reserving package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: live remote handles are private teardown ownership,
+ * and the E2B command event stream is the sole outcome authority.
+ */
+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 */

packages/e2b/subprocess-e2b/src/output.ts

@@ -0,0 +1,131 @@
+/** Bounded host-side projection of a complete output file retained in E2B. */
+
+import { Buffer } from 'node:buffer'
+import type { SubprocessOutputRead, SubprocessOutputReader } from '@deepseek-ai/dsh-subprocess'
+
+const BASE64_TEXT = /^[A-Za-z0-9+/]+={0,2}$/u
+
+/** Reserved non-base64 frame proving that one remote encoder reached clean EOF. */
+export const E2B_OUTPUT_COMPLETE_FRAME = '!dsh-e2b-output-complete!'
+
+/** Incrementally decode newline-delimited base64 frames emitted by one remote encoder. */
+export class E2BBase64Decoder {
+  private pending = ''
+  private complete = false
+
+  /**
+   * Decode every complete newline-delimited frame in one arbitrarily split SDK callback.
+   * @param text - ASCII base64 frames from E2B's decoded callback.
+   * @returns the complete raw bytes made available by this callback.
+   */
+  push(text: string): Buffer {
+    if (text.length === 0) return Buffer.alloc(0)
+    this.pending += text
+    const decoded: Buffer[] = []
+    for (;;) {
+      const boundary = this.pending.indexOf('\n')
+      if (boundary < 0) break
+      const frame = this.pending.slice(0, boundary)
+      this.pending = this.pending.slice(boundary + 1)
+      if (frame === E2B_OUTPUT_COMPLETE_FRAME) {
+        if (this.complete) throw new Error('subprocess-e2b: duplicate output transport completion')
+        this.complete = true
+        continue
+      }
+      if (this.complete) throw new Error('subprocess-e2b: output transport continued after completion')
+      if (!BASE64_TEXT.test(frame)) {
+        throw new Error('subprocess-e2b: invalid base64 output transport')
+      }
+      const bytes = Buffer.from(frame, 'base64')
+      if (bytes.toString('base64') !== frame) {
+        throw new Error('subprocess-e2b: invalid base64 output transport')
+      }
+      decoded.push(bytes)
+    }
+    return Buffer.concat(decoded)
+  }
+
+  /**
+   * Validate clean encoder completion, or discard an interrupted trailing frame after requested termination.
+   * @param requireComplete - Whether natural completion requires the reserved EOF frame.
+   */
+  finish(requireComplete = true): void {
+    if (!requireComplete) {
+      this.pending = ''
+      return
+    }
+    if (this.pending.length > 0) {
+      throw new Error('subprocess-e2b: truncated base64 output transport')
+    }
+    if (!this.complete) throw new Error('subprocess-e2b: incomplete output transport')
+  }
+}
+
+/** Offset reader used for one collect-mode E2B stream. */
+export class E2BOutputReader implements SubprocessOutputReader {
+  private chunks: Buffer[] = []
+  private retainedBytes = 0
+  private totalBytes = 0
+  private spillValid = true
+
+  /**
+   * Create a bounded reader over one remote spill path.
+   * @param maxBytes - In-memory tail cap.
+   * @param maxSpillBytes - Maximum complete remote file size the caller accepts.
+   * @param spillPath - Remote full-output path.
+   */
+  constructor(
+    private readonly maxBytes: number,
+    private readonly maxSpillBytes: number | undefined,
+    private readonly spillPath: string,
+  ) {}
+
+  /** Total bytes observed from the SDK stream. */
+  get size(): number {
+    return this.totalBytes
+  }
+
+  /** Stop advertising a remote spill whose writer did not reach clean EOF. */
+  invalidateSpill(): void {
+    this.spillValid = false
+  }
+
+  /**
+   * Append one byte-faithful decoded transport event.
+   * @param bytes - Raw command bytes recovered from the ASCII SDK transport.
+   */
+  push(bytes: Uint8Array): void {
+    if (bytes.length === 0) return
+    const chunk = Buffer.from(bytes)
+    this.totalBytes += chunk.length
+    this.chunks.push(chunk)
+    this.retainedBytes += chunk.length
+    while (this.retainedBytes > this.maxBytes) {
+      const head = this.chunks[0] as Buffer
+      const excess = this.retainedBytes - this.maxBytes
+      if (head.length <= excess) {
+        this.chunks.shift()
+        this.retainedBytes -= head.length
+      } else {
+        this.chunks[0] = head.subarray(excess)
+        this.retainedBytes -= excess
+      }
+    }
+  }
+
+  /** @inheritdoc */
+  readFrom(fromByte: number): SubprocessOutputRead {
+    const retained = Buffer.concat(this.chunks, this.retainedBytes)
+    const firstRetained = this.totalBytes - this.retainedBytes
+    const lossy = fromByte < firstRetained
+    const start = lossy ? 0 : Math.min(retained.length, Math.max(0, fromByte - firstRetained))
+    return {
+      text: retained.subarray(start).toString('utf8'),
+      nextOffset: this.totalBytes,
+      lossy,
+      ...(lossy && this.spillValid && this.maxSpillBytes !== undefined && this.totalBytes <= this.maxSpillBytes
+        ? { spillPath: this.spillPath }
+        : {}),
+    }
+  }
+}

packages/e2b/subprocess-e2b/src/process.ts

@@ -0,0 +1,698 @@
+/** One asynchronously-started E2B command projected onto the subprocess seam. */
+
+import { Buffer } from 'node:buffer'
+import { PassThrough, Writable } from 'node:stream'
+import { posix } from 'node:path'
+import {
+  CommandExitError,
+  e2bControlEnvs,
+  FileNotFoundError,
+  SandboxNotFoundError,
+  quoteE2BShellArg,
+} from '@deepseek-ai/dsh-e2b'
+import type { CommandHandle, CommandResult, Sandbox } from '@deepseek-ai/dsh-e2b'
+import type {
+  SubprocessCollect,
+  SubprocessHandle,
+  SubprocessOutcome,
+  SubprocessOutputMode,
+  SubprocessSpawnSpec,
+} from '@deepseek-ai/dsh-subprocess'
+import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
+import { bootstrapEnvironment, readRemoteEnvironment, serializeRemoteEnvironment } from './environment.ts'
+import { E2BBase64Decoder, E2B_OUTPUT_COMPLETE_FRAME, E2BOutputReader } from './output.ts'
+import { asError, commandOpts, signalRemoteGroups, waitTick } from './remote.ts'
+
+const OUTPUT_ENCODER_SOURCE = [
+  '(async () => {',
+  '  for await (const chunk of process.stdin) {',
+  "    if (!process.stdout.write(chunk.toString('base64') + '\\n')) {",
+  "      await new Promise(resolve => process.stdout.once('drain', resolve))",
+  '    }',
+  '  }',
+  `  if (!process.stdout.write(${JSON.stringify(E2B_OUTPUT_COMPLETE_FRAME)} + '\\n')) {`,
+  "    await new Promise(resolve => process.stdout.once('drain', resolve))",
+  '  }',
+  '})().catch(() => { process.exitCode = 1 })',
+].join('\n')
+
+function isCollect(mode: SubprocessOutputMode): mode is SubprocessCollect {
+  return mode !== 'pipe' && mode !== 'inherit'
+}
+
+function hasSpill(mode: SubprocessOutputMode): mode is SubprocessCollect & { spill: { maxBytes: number } } {
+  return isCollect(mode) && mode.spill !== undefined
+}
+
+function isValidProcessId(value: number): boolean {
+  return Number.isSafeInteger(value) && value > 0
+}
+
+class DeferredStdin extends Writable {
+  constructor(private readonly ready: Promise<CommandHandle>) {
+    super({ decodeStrings: false })
+  }
+
+  override _write(chunk: string | Buffer, _encoding: BufferEncoding, callback: (error?: Error | null) => void): void {
+    void this.ready.then(handle => handle.sendStdin(chunk)).then(
+      () => { callback() },
+      (error: unknown) => { callback(asError(error)) },
+    )
+  }
+
+  override _final(callback: (error?: Error | null) => void): void {
+    void this.ready.then(handle => handle.closeStdin()).then(
+      () => { callback() },
+      (error: unknown) => { callback(asError(error)) },
+    )
+  }
+}
+
+interface RemotePaths {
+  pid: string
+  status: string
+  environment: string
+  stdout: string
+  stderr: string
+}
+
+type CommandSettlement =
+  | { kind: 'result'; result: CommandResult }
+  | { kind: 'error'; error: unknown }
+
+function withinMs(settlement: Promise<CommandSettlement>, timeoutMs: number): Promise<CommandSettlement | undefined> {
+  return new Promise<CommandSettlement | undefined>((resolve) => {
+    const timer = setTimeout(() => { resolve(undefined) }, timeoutMs)
+    void settlement.then((value) => {
+      clearTimeout(timer)
+      resolve(value)
+    })
+  })
+}
+
+function commandText(spec: SubprocessSpawnSpec, paths: RemotePaths): string {
+  const encoder = `"$dsh_e2b_env_bin" -i "$dsh_e2b_node" -e ${quoteE2BShellArg(OUTPUT_ENCODER_SOURCE)}`
+  const stdoutRedirect = hasSpill(spec.stdio.stdout)
+    ? `> >("$dsh_e2b_tee" --output-error=warn-nopipe >("$dsh_e2b_head" -c ${spec.stdio.stdout.spill.maxBytes} > ${quoteE2BShellArg(paths.stdout)}) | ${encoder} 2>/dev/null)`
+    : `> >(${encoder} 2>/dev/null)`
+  const stderrRedirect = hasSpill(spec.stdio.stderr)
+    ? `2> >("$dsh_e2b_tee" --output-error=warn-nopipe >("$dsh_e2b_head" -c ${spec.stdio.stderr.spill.maxBytes} > ${quoteE2BShellArg(paths.stderr)}) | ${encoder} >&2 2>/dev/null)`
+    : `2> >(${encoder} >&2 2>/dev/null)`
+  const inner = [
+    'set +e',
+    'dsh_e2b_env_bin=$1',
+    'dsh_e2b_node=$2',
+    'dsh_e2b_ps=$3',
+    'dsh_e2b_tr=$4',
+    'dsh_e2b_tee=$5',
+    'dsh_e2b_head=$6',
+    'dsh_e2b_rm=$7',
+    'shift 7',
+    'dsh_e2b_pgid="$("$dsh_e2b_ps" -o pgid= -p "$$" | "$dsh_e2b_tr" -d " ")"',
+    `printf '%s\\n' "$dsh_e2b_pgid" > ${quoteE2BShellArg(paths.pid)}`,
+    `mapfile -d '' -t dsh_e2b_env < ${quoteE2BShellArg(paths.environment)}`,
+    `"$dsh_e2b_rm" -f -- ${quoteE2BShellArg(paths.environment)}`,
+    `"$dsh_e2b_env_bin" -i -- "\${dsh_e2b_env[@]}" "$@" ${stdoutRedirect} ${stderrRedirect}`.trimEnd(),
+    'dsh_e2b_status=$?',
+    `printf '%s\\n' "$dsh_e2b_status" > ${quoteE2BShellArg(paths.status)}`,
+    'wait',
+    'exit "$dsh_e2b_status"',
+  ].join('\n')
+  const argv = spec.argv.map(quoteE2BShellArg).join(' ')
+  const bootstrap = [
+    `mapfile -d '' -t dsh_e2b_env < ${quoteE2BShellArg(paths.environment)}`,
+    'dsh_e2b_env_bin="$(command -v env)"',
+    'dsh_e2b_setsid="$(command -v setsid)"',
+    'dsh_e2b_bash="$(command -v bash)"',
+    'dsh_e2b_node="$(command -v node)"',
+    'dsh_e2b_ps="$(command -v ps)"',
+    'dsh_e2b_tr="$(command -v tr)"',
+    'dsh_e2b_tee="$(command -v tee)"',
+    'dsh_e2b_head="$(command -v head)"',
+    'dsh_e2b_rm="$(command -v rm)"',
+    'for dsh_e2b_tool in "$dsh_e2b_env_bin" "$dsh_e2b_setsid" "$dsh_e2b_bash" "$dsh_e2b_node" "$dsh_e2b_ps" "$dsh_e2b_tr" "$dsh_e2b_tee" "$dsh_e2b_head" "$dsh_e2b_rm"; do',
+    '  [[ "$dsh_e2b_tool" == /* && -x "$dsh_e2b_tool" ]] || exit 125',
+    'done',
+    `exec "$dsh_e2b_env_bin" -i -- "\${dsh_e2b_env[@]}" "$dsh_e2b_setsid" --wait -- "$dsh_e2b_bash" -c ${quoteE2BShellArg(inner)} dsh-e2b "$dsh_e2b_env_bin" "$dsh_e2b_node" "$dsh_e2b_ps" "$dsh_e2b_tr" "$dsh_e2b_tee" "$dsh_e2b_head" "$dsh_e2b_rm" ${argv}`,
+  ].join('\n')
+  return bootstrap
+}
+
+const WAIT_ABORTED = Symbol('wait aborted')
+
+function waitWithSignal<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T | typeof WAIT_ABORTED> {
+  if (signal === undefined) return promise
+  if (signal.aborted) return Promise.resolve(WAIT_ABORTED)
+  return new Promise<T | typeof WAIT_ABORTED>((resolve) => {
+    const onAbort = (): void => { cleanup(); resolve(WAIT_ABORTED) }
+    const cleanup = (): void => { signal.removeEventListener('abort', onAbort) }
+    signal.addEventListener('abort', onAbort, { once: true })
+    if (signal.aborted) {
+      onAbort()
+      return
+    }
+    void promise.then((value) => { cleanup(); resolve(value) })
+  })
+}
+
+/** E2B-backed subprocess handle with deferred remote PID acquisition. */
+export class E2BSubprocessHandle implements SubprocessHandle {
+  readonly stdin: Writable | undefined
+  readonly stdout: PassThrough | undefined
+  readonly stderr: PassThrough | undefined
+  readonly collected: SubprocessHandle['collected']
+  readonly done: Promise<SubprocessOutcome>
+
+  private readonly commandState = Promise.withResolvers<CommandHandle | undefined>()
+  private readonly readyState = Promise.withResolvers<CommandHandle>()
+  private readonly stdoutDecoder = new E2BBase64Decoder()
+  private readonly stderrDecoder = new E2BBase64Decoder()
+  private readonly terminationController = new AbortController()
+  /** Releases output waits that survive the command outcome, so blocked SDK callbacks settle. */
+  private readonly outputReleased = new AbortController()
+  private readonly stdoutReader: E2BOutputReader | undefined
+  private readonly stderrReader: E2BOutputReader | undefined
+  private readonly paths: RemotePaths
+  private controlEnvs: Record<string, string> = {}
+  private remotePid = -1
+  private outputTransportError: Error | undefined
+  private outputDrainExpired = false
+  private stateDirectoryCreated = false
+  private quiescenceProven = false
+  private terminationAttempt: Promise<void> | undefined
+  private terminationFailure: Error | undefined
+  private terminationSignal: NodeJS.Signals | null = null
+
+  /**
+   * Begin an E2B command without blocking the synchronous subprocess spawn seam.
+   * @param runtime - Shared E2B sandbox owner.
+   * @param spec - Fully resolved subprocess request.
+   * @param stateDir - Remote directory retaining process identity, status, and valid spills.
+   * @param pollMs - Remote status/liveness poll cadence.
+   */
+  constructor(
+    private readonly runtime: E2BSandboxService,
+    private readonly spec: SubprocessSpawnSpec,
+    readonly stateDir: string,
+    private readonly pollMs: number,
+  ) {
+    this.paths = {
+      pid: posix.join(stateDir, 'pid'),
+      status: posix.join(stateDir, 'exit-code'),
+      environment: posix.join(stateDir, 'environment'),
+      stdout: posix.join(stateDir, 'stdout.log'),
+      stderr: posix.join(stateDir, 'stderr.log'),
+    }
+    const outMode = spec.stdio.stdout
+    const errMode = spec.stdio.stderr
+    this.stdout = outMode === 'pipe' ? new PassThrough() : undefined
+    this.stderr = errMode === 'pipe' ? new PassThrough() : undefined
+    this.stdoutReader = isCollect(outMode)
+      ? new E2BOutputReader(outMode.maxBytes, outMode.spill?.maxBytes, this.paths.stdout)
+      : undefined
+    this.stderrReader = isCollect(errMode)
+      ? new E2BOutputReader(errMode.maxBytes, errMode.spill?.maxBytes, this.paths.stderr)
+      : undefined
+    this.collected = {
+      ...(this.stdoutReader !== undefined ? { stdout: this.stdoutReader } : {}),
+      ...(this.stderrReader !== undefined ? { stderr: this.stderrReader } : {}),
+    }
+    this.stdin = spec.stdio.stdin === 'pipe' ? new DeferredStdin(this.readyState.promise) : undefined
+    void this.readyState.promise.catch(() => {})
+    spec.signal?.addEventListener('abort', this.onAbort, { once: true })
+    this.done = this.run()
+    void this.done.catch(() => {})
+    if (spec.signal?.aborted === true) this.terminate()
+  }
+
+  /** Remote process id after start; `-1` while E2B startup is pending or after it fails. */
+  get pid(): number {
+    return this.remotePid
+  }
+
+  /** @inheritdoc */
+  terminate(): void {
+    if (this.quiescenceProven || this.terminationAttempt !== undefined) return
+    this.terminationController.abort(new Error('subprocess-e2b: command terminated'))
+    this.stdout?.destroy()
+    this.stderr?.destroy()
+    this.terminationFailure = undefined
+    const attempt = this.terminateRemote()
+    this.terminationAttempt = attempt
+    void attempt.then(
+      () => { this.terminationAttempt = undefined },
+      (error: unknown) => {
+        if (!this.quiescenceProven) this.terminationFailure = asError(error)
+        this.terminationAttempt = undefined
+      },
+    )
+  }
+
+  /** @inheritdoc */
+  async waitForExit(signal?: AbortSignal): Promise<boolean> {
+    if (this.quiescenceProven) return true
+    let handle: CommandHandle | undefined
+    if (this.terminationController.signal.aborted) {
+      const observed = await waitWithSignal(this.commandState.promise, signal)
+      if (observed === WAIT_ABORTED) return false
+      handle = observed
+      if (handle === undefined) {
+        this.markQuiescent()
+        return true
+      }
+      if (this.remotePid <= 0) {
+        const attempt = this.terminationAttempt
+        if (attempt !== undefined && await waitWithSignal(attempt.catch(() => undefined), signal) === WAIT_ABORTED) {
+          return false
+        }
+        this.throwTerminationFailure()
+        // Successful pre-publication termination records quiescence; its only other outcome is the failure above.
+        return true
+      }
+    } else {
+      const observed = await waitWithSignal(
+        this.readyState.promise.catch(() => this.commandState.promise),
+        signal,
+      )
+      if (observed === WAIT_ABORTED) return false
+      handle = observed
+      if (handle === undefined) {
+        this.markQuiescent()
+        return true
+      }
+    }
+    this.throwTerminationFailure()
+    let sandbox: Sandbox
+    try {
+      sandbox = await this.runtime.getSandbox()
+    } catch (error: unknown) {
+      if (signal?.aborted === true) return false
+      if (error instanceof SandboxNotFoundError) {
+        this.markQuiescent()
+        return true
+      }
+      throw error
+    }
+    const processGroupId = this.remotePid > 0 ? this.remotePid : handle.pid
+    while (await this.groupAlive(sandbox, processGroupId, signal)) {
+      this.throwTerminationFailure()
+      if (!await waitTick(this.pollMs, signal)) return false
+    }
+    this.throwTerminationFailure()
+    if (signal?.aborted === true) return false
+    this.markQuiescent()
+    return true
+  }
+
+  private readonly onAbort = (): void => { this.terminate() }
+
+  private markQuiescent(): void {
+    this.quiescenceProven = true
+    this.terminationFailure = undefined
+  }
+
+  private async run(): Promise<SubprocessOutcome> {
+    let sandbox: Sandbox | undefined
+    let preparing = true
+    try {
+      sandbox = await this.runtime.getSandbox()
+      await this.prepareState(sandbox)
+      preparing = false
+      const handle = await sandbox.commands.run(
+        commandText(this.spec, this.paths),
+        {
+          background: true,
+          cwd: this.spec.cwd,
+          envs: e2bControlEnvs(this.controlEnvs),
+          stdin: this.spec.stdio.stdin !== 'ignore',
+          timeoutMs: 0,
+          onStdout: async (data) => { await this.dispatchOutput('stdout', data) },
+          onStderr: async (data) => { await this.dispatchOutput('stderr', data) },
+        },
+      )
+      const completion = handle.wait()
+      void completion.catch(() => {})
+      if (!isValidProcessId(handle.pid)) {
+        const invalidPid = new Error(`subprocess-e2b: E2B returned invalid command pid ${handle.pid}`)
+        try {
+          await handle.kill()
+          this.markQuiescent()
+        } catch (cleanupError: unknown) {
+          this.terminationFailure = asError(cleanupError)
+          this.commandState.resolve(handle)
+          throw new AggregateError(
+            [invalidPid, cleanupError],
+            'subprocess-e2b: invalid command pid rollback did not reach quiescence',
+          )
+        }
+        throw invalidPid
+      }
+      this.commandState.resolve(handle)
+      try {
+        this.remotePid = await this.waitForProcessGroupId(sandbox, completion)
+      } catch (error: unknown) {
+        try {
+          await this.rollbackUnpublishedGroup(sandbox, handle)
+        } catch (cleanupError: unknown) {
+          throw new AggregateError(
+            [error, cleanupError],
+            'subprocess-e2b: process-group publication failed and rollback did not reach quiescence',
+          )
+        }
+        throw error
+      }
+      this.readyState.resolve(handle)
+      await this.writeBatchStdin(handle)
+      const outcome = await this.waitForCommand(sandbox, handle, completion)
+      if (this.outputTransportError !== undefined) throw this.outputTransportError
+      const requireCompleteOutput = this.terminationSignal === null && !this.outputDrainExpired
+      this.stdoutDecoder.finish(requireCompleteOutput)
+      this.stderrDecoder.finish(requireCompleteOutput)
+      await this.finalizeSpills(sandbox)
+      return outcome
+    } catch (error: unknown) {
+      const canceledPreparation = preparing && this.terminationController.signal.aborted
+      let failure = await this.rollbackPublishedFailure(error)
+      if (sandbox !== undefined && this.stateDirectoryCreated) {
+        try {
+          await this.removeFailedState(sandbox)
+        } catch (cleanupError: unknown) {
+          failure = new AggregateError(
+            [failure, cleanupError],
+            'subprocess-e2b: command failed and private state cleanup failed',
+          )
+        }
+      }
+      this.commandState.resolve(undefined)
+      this.readyState.reject(failure)
+      if (canceledPreparation && failure === error) return { exitCode: null, signal: 'SIGTERM' }
+      throw failure
+    } finally {
+      this.spec.signal?.removeEventListener('abort', this.onAbort)
+      this.stdout?.end()
+      this.stderr?.end()
+    }
+  }
+
+  private async prepareState(sandbox: Sandbox): Promise<void> {
+    const signal = this.terminationController.signal
+    const ambient = await readRemoteEnvironment(sandbox, signal)
+    this.controlEnvs = bootstrapEnvironment(ambient)
+    // Own the directory before the request: a cancellation racing a committed
+    // creation must still enter cleanup (removal tolerates an absent path).
+    this.stateDirectoryCreated = true
+    await sandbox.files.makeDir(this.stateDir, { signal })
+    await sandbox.commands.run(
+      `chmod 700 -- ${quoteE2BShellArg(this.stateDir)}`,
+      commandOpts(this.controlEnvs, signal),
+    )
+    const files = [
+      { path: this.paths.pid, data: '' },
+      { path: this.paths.status, data: '' },
+      { path: this.paths.environment, data: serializeRemoteEnvironment(ambient, this.spec.env) },
+      ...(hasSpill(this.spec.stdio.stdout) ? [{ path: this.paths.stdout, data: '' }] : []),
+      ...(hasSpill(this.spec.stdio.stderr) ? [{ path: this.paths.stderr, data: '' }] : []),
+    ]
+    await sandbox.files.write(files, { signal })
+    await sandbox.commands.run(
+      `chmod 600 -- ${files.map(file => quoteE2BShellArg(file.path)).join(' ')}`,
+      commandOpts(this.controlEnvs, signal),
+    )
+    signal.throwIfAborted()
+  }
+
+  private async writeBatchStdin(handle: CommandHandle): Promise<void> {
+    if (typeof this.spec.stdio.stdin !== 'object') return
+    try {
+      await handle.sendStdin(this.spec.stdio.stdin.data)
+      await handle.closeStdin()
+    } catch (_processClosedItsInput) {
+      // Like the local adapter, batch stdin is best-effort; exit and output remain authoritative.
+    }
+  }
+
+  private async dispatchOutput(stream: 'stdout' | 'stderr', data: string): Promise<void> {
+    let bytes: Buffer
+    try {
+      bytes = stream === 'stdout' ? this.stdoutDecoder.push(data) : this.stderrDecoder.push(data)
+    } catch (error: unknown) {
+      this.outputTransportError ??= asError(error)
+      const target = stream === 'stdout' ? this.stdout : this.stderr
+      target?.destroy(this.outputTransportError)
+      return
+    }
+    try {
+      if (stream === 'stdout') {
+        this.stdoutReader?.push(bytes)
+        await this.writeOutput(this.stdout, this.spec.stdio.stdout === 'inherit' ? process.stdout : undefined, bytes)
+        return
+      }
+      this.stderrReader?.push(bytes)
+      await this.writeOutput(this.stderr, this.spec.stdio.stderr === 'inherit' ? process.stderr : undefined, bytes)
+    } catch (error: unknown) {
+      const target = stream === 'stdout' ? this.stdout : this.stderr
+      target?.destroy(asError(error))
+    }
+  }
+
+  private async writeOutput(pipe: PassThrough | undefined, inherited: NodeJS.WriteStream | undefined, data: Uint8Array): Promise<void> {
+    const target = pipe ?? inherited
+    if (target === undefined || data.length === 0 || this.terminationController.signal.aborted) return
+    if (target.destroyed) throw new Error('subprocess output stream is closed')
+    if (target.write(data)) return
+    await new Promise<void>((resolve, reject) => {
+      const onDrain = (): void => { cleanup(); resolve() }
+      const onClose = (): void => { cleanup(); resolve() }
+      const onRelease = (): void => { cleanup(); resolve() }
+      const onError = (error: Error): void => { cleanup(); reject(error) }
+      const cleanup = (): void => {
+        target.removeListener('drain', onDrain)
+        target.removeListener('close', onClose)
+        target.removeListener('error', onError)
+        this.terminationController.signal.removeEventListener('abort', onRelease)
+        this.outputReleased.signal.removeEventListener('abort', onRelease)
+      }
+      target.once('drain', onDrain)
+      target.once('close', onClose)
+      target.once('error', onError)
+      this.terminationController.signal.addEventListener('abort', onRelease, { once: true })
+      this.outputReleased.signal.addEventListener('abort', onRelease, { once: true })
+      if (this.terminationController.signal.aborted || this.outputReleased.signal.aborted) onRelease()
+    })
+  }
+
+  private async waitForProcessGroupId(sandbox: Sandbox, completion: Promise<CommandResult>): Promise<number> {
+    const commandSettled = completion.then(
+      () => true,
+      () => true,
+    )
+    while (true) {
+      // TODO(e2b-publication-cancel): Join cancellation to the existing
+      // termination transaction before aborting an in-flight SDK file read.
+      const raw = await sandbox.files.read(this.paths.pid)
+      const value = raw.trim()
+      if (value.length > 0) {
+        const pid = Number(value)
+        if (!/^[1-9][0-9]*$/.test(value) || !Number.isSafeInteger(pid)) {
+          throw new Error(`subprocess-e2b: remote wrapper published invalid process-group id ${JSON.stringify(value)}`)
+        }
+        // A same-UID sandbox process can rewrite this file; refuse ids whose
+        // negative form addresses every process (`kill -- -1`) or init's group.
+        if (pid <= 1) {
+          throw new Error(`subprocess-e2b: unsafe published process-group id ${pid}`)
+        }
+        return pid
+      }
+      const settled = await Promise.race([commandSettled, waitTick(this.pollMs).then(() => false)])
+      if (settled) throw new Error('subprocess-e2b: remote command exited before publishing its process-group id')
+    }
+  }
+
+  private async waitForCommand(
+    sandbox: Sandbox,
+    handle: CommandHandle,
+    completion: Promise<CommandResult>,
+  ): Promise<SubprocessOutcome> {
+    const settlement = completion.then<CommandSettlement, CommandSettlement>(
+      result => ({ kind: 'result', result }),
+      (error: unknown) => ({ kind: 'error', error }),
+    )
+    const hasPipeOutput = this.spec.stdio.stdout === 'pipe' || this.spec.stdio.stderr === 'pipe'
+    let completed = hasPipeOutput ? await settlement : undefined
+    while (true) {
+      const rawStatus = (await sandbox.files.read(this.paths.status)).trim()
+      if (rawStatus.length > 0) {
+        const exitCode = Number(rawStatus)
+        if (!/^(?:0|[1-9][0-9]*)$/.test(rawStatus) || !Number.isSafeInteger(exitCode) || exitCode > 255) {
+          throw new Error(`subprocess-e2b: remote wrapper published invalid exit code ${JSON.stringify(rawStatus)}`)
+        }
+        if (completed !== undefined) return this.commandOutcome(completed, exitCode)
+        const drained = await withinMs(settlement, this.spec.graceMs)
+        if (drained !== undefined) return this.commandOutcome(drained, exitCode)
+        this.outputDrainExpired = true
+        this.stdoutReader?.invalidateSpill()
+        this.stderrReader?.invalidateSpill()
+        // Release inherited-output waits so a callback blocked on host
+        // backpressure cannot keep the disconnected SDK settlement pending.
+        this.outputReleased.abort(new Error('subprocess-e2b: output drain grace expired'))
+        await handle.disconnect()
+        return { exitCode, signal: null }
+      }
+      if (completed !== undefined) return this.commandOutcome(completed)
+      // TODO(e2b-status-watch): Replace collect/inherit control-plane polling
+      // when E2B can observe direct-command exit independently of descendant-held output.
+      completed = await Promise.race([settlement, waitTick(this.pollMs).then(() => undefined)])
+    }
+  }
+
+  private commandOutcome(settlement: CommandSettlement, publishedExitCode?: number): SubprocessOutcome {
+    if (settlement.kind === 'result') {
+      return { exitCode: publishedExitCode ?? settlement.result.exitCode, signal: null }
+    }
+    if (settlement.error instanceof CommandExitError) {
+      if (publishedExitCode !== undefined) return { exitCode: publishedExitCode, signal: null }
+      return this.terminationSignal === null
+        ? { exitCode: settlement.error.exitCode, signal: null }
+        : { exitCode: null, signal: this.terminationSignal }
+    }
+    throw settlement.error
+  }
+
+  private async rollbackPublishedFailure(error: unknown): Promise<unknown> {
+    if (this.remotePid <= 0 || this.quiescenceProven) return error
+    this.terminate()
+    try {
+      await this.waitForExit()
+      return error
+    } catch (cleanupError: unknown) {
+      return new AggregateError(
+        [asError(error), asError(cleanupError)],
+        'subprocess-e2b: command monitoring failed and process-group rollback did not reach quiescence',
+      )
+    }
+  }
+
+  private async rollbackUnpublishedGroup(sandbox: Sandbox, handle: CommandHandle): Promise<void> {
+    // The bootstrap ends in an exec chain through the scrubbed environment and
+    // `setsid`, so E2B's command PID is the provisional group id even before the
+    // private publication file can be trusted. Kill that group before the SDK-PID
+    // fallback, then prove no group member survived before rejecting startup.
+    await this.forceKillGroup(sandbox, handle, handle.pid)
+    this.markQuiescent()
+  }
+
+  private async terminateRemote(): Promise<void> {
+    try {
+      await this.terminateRemoteInSandbox()
+    } catch (error: unknown) {
+      if (error instanceof SandboxNotFoundError) {
+        this.markQuiescent()
+        return
+      }
+      throw error
+    }
+  }
+
+  private async terminateRemoteInSandbox(): Promise<void> {
+    const handle = await this.commandState.promise
+    if (handle === undefined) {
+      this.markQuiescent()
+      return
+    }
+    if (!isValidProcessId(handle.pid) && this.remotePid <= 0) {
+      await handle.kill()
+      this.markQuiescent()
+      return
+    }
+    const sandbox = await this.runtime.getSandbox()
+    const processGroupId = this.remotePid > 0 ? this.remotePid : handle.pid
+    await this.terminateGroup(sandbox, handle, processGroupId)
+  }
+
+  private async terminateGroup(sandbox: Sandbox, handle: CommandHandle, processGroupId: number): Promise<void> {
+    this.terminationSignal = 'SIGTERM'
+    try {
+      await signalRemoteGroups(sandbox, this.controlEnvs, [processGroupId], 'TERM')
+      if (await this.waitForGroupExit(sandbox, processGroupId)) {
+        this.markQuiescent()
+        return
+      }
+    } catch (_gracefulTerminationFailure) {
+      // Failed TERM delivery or observation cannot prove exit; force cleanup still owns the group.
+    }
+    this.terminationSignal = 'SIGKILL'
+    await this.forceKillGroup(sandbox, handle, processGroupId)
+    this.markQuiescent()
+  }
+
+  private async forceKillGroup(sandbox: Sandbox, handle: CommandHandle, processGroupId: number): Promise<void> {
+    try {
+      await signalRemoteGroups(sandbox, this.controlEnvs, [processGroupId], 'KILL')
+    } catch (_processGroupKillFailure) {
+      // SDK kill and the final liveness probe remain independent cleanup paths.
+    }
+    try {
+      await handle.kill()
+    } catch (_sdkKillFailure) {
+      // The final liveness probe, not either transport's self-report, proves cleanup.
+    }
+    if (await this.waitForGroupExit(sandbox, processGroupId)) return
+    throw new Error(`subprocess-e2b: remote process group ${processGroupId} remained live after force termination`)
+  }
+
+  private async waitForGroupExit(sandbox: Sandbox, processGroupId: number): Promise<boolean> {
+    const deadline = Date.now() + this.spec.graceMs
+    while (await this.groupAlive(sandbox, processGroupId)) {
+      if (Date.now() >= deadline) return false
+      await waitTick(this.pollMs)
+    }
+    return true
+  }
+
+  private throwTerminationFailure(): void {
+    if (this.terminationFailure !== undefined) throw this.terminationFailure
+  }
+
+  private async groupAlive(sandbox: Sandbox, pid: number, signal?: AbortSignal): Promise<boolean> {
+    const result = await sandbox.commands.run(
+      `set -o pipefail; ps -eo pgid=,stat= | awk '$1 == ${pid} && $2 !~ /^[ZXx]/ { live=1 } END { if (live) print "live" }'`,
+      commandOpts(this.controlEnvs, signal),
+    ).catch((error: unknown) => {
+      if (signal?.aborted === true) return undefined
+      if (error instanceof SandboxNotFoundError) return { exitCode: 0, stdout: '', stderr: '' }
+      throw error
+    })
+    return result?.stdout.trim() === 'live'
+  }
+
+  private async finalizeSpills(sandbox: Sandbox): Promise<void> {
+    const removals: Promise<void>[] = []
+    const collect = (mode: SubprocessOutputMode, reader: E2BOutputReader | undefined, path: string): void => {
+      if (!hasSpill(mode)) return
+      // A spill mode is a collect mode, so construction always created its reader.
+      const size = (reader as E2BOutputReader).size
+      if (this.outputDrainExpired || size <= mode.maxBytes || size > mode.spill.maxBytes) {
+        removals.push(sandbox.files.remove(path).catch((_adapterPrivateSpillRemovalFailure: unknown) => {
+          // The command outcome is authoritative; owner teardown bounds private residue.
+        }))
+      }
+    }
+    collect(this.spec.stdio.stdout, this.stdoutReader, this.paths.stdout)
+    collect(this.spec.stdio.stderr, this.stderrReader, this.paths.stderr)
+    await Promise.all(removals)
+  }
+
+  private async removeFailedState(sandbox: Sandbox): Promise<void> {
+    const failures: Error[] = []
+    for (const path of [this.paths.environment, this.stateDir]) {
+      try {
+        await sandbox.files.remove(path)
+      } catch (error: unknown) {
+        if (!(error instanceof FileNotFoundError)) failures.push(asError(error))
+      }
+    }
+    if (failures.length > 0) {
+      throw new AggregateError(failures, 'subprocess-e2b: failed to remove private command state')
+    }
+  }
+}

packages/e2b/subprocess-e2b/src/remote.ts

@@ -0,0 +1,97 @@
+/**
+ * Shared remote-control helpers for the E2B subprocess adapter: SDK option
+ * shaping, poll ticks, and the one tolerant process-group signal used by both
+ * the ordinary-process and terminal teardown ladders.
+ */
+
+import { CommandExitError, e2bControlEnvs, SandboxNotFoundError } from '@deepseek-ai/dsh-e2b'
+import type { Sandbox } from '@deepseek-ai/dsh-e2b'
+
+/**
+ * Normalize an unknown rejection into an Error.
+ * @param error - Any thrown or rejected value.
+ * @returns The value itself when already an Error, else a stringified wrapper.
+ */
+export function asError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error))
+}
+
+/**
+ * Shape the optional-signal SDK options object.
+ * @param signal - Optional cancellation for one SDK request.
+ * @returns An options fragment that omits an undefined signal.
+ */
+export function signalOpts(signal: AbortSignal | undefined): { signal?: AbortSignal } {
+  return signal === undefined ? {} : { signal }
+}
+
+/**
+ * Shape control-shell command options with the isolated HOME override.
+ * @param envs - Explicit environment entries for the control command.
+ * @param signal - Optional cancellation for the SDK request.
+ * @returns Options for `sandbox.commands.run` control invocations.
+ */
+export function commandOpts(
+  envs: Record<string, string>,
+  signal?: AbortSignal,
+): { envs: Record<string, string>; signal?: AbortSignal } {
+  return { envs: e2bControlEnvs(envs), ...signalOpts(signal) }
+}
+
+/**
+ * Resolve after one duration.
+ * @param ms - Milliseconds to wait.
+ * @returns Settles after the timeout.
+ */
+export function delay(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+/**
+ * Wait one poll interval or until the signal aborts.
+ * @param pollMs - Poll cadence in milliseconds.
+ * @param signal - Optional abort that ends the wait early.
+ * @returns `true` after a full tick, `false` when aborted first.
+ */
+export function waitTick(pollMs: number, signal?: AbortSignal): Promise<boolean> {
+  if (signal?.aborted === true) return Promise.resolve(false)
+  return new Promise<boolean>((resolve) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort)
+      resolve(true)
+    }, pollMs)
+    const onAbort = (): void => {
+      clearTimeout(timer)
+      resolve(false)
+    }
+    signal?.addEventListener('abort', onAbort, { once: true })
+  })
+}
+
+/**
+ * Signal remote process groups, tolerating the shared teardown outcomes: a
+ * nonzero `kill` (groups already gone) and a disappeared sandbox. Both the
+ * pgid-keyed process ladder and the sid-keyed terminal ladder deliver signals
+ * through this single tolerance so they cannot drift apart.
+ * @param sandbox - Live SDK handle.
+ * @param envs - Control-shell environment entries.
+ * @param groups - Positive process-group ids to signal.
+ * @param signal - `TERM` or `KILL`.
+ */
+export async function signalRemoteGroups(
+  sandbox: Sandbox,
+  envs: Record<string, string>,
+  groups: readonly number[],
+  signal: 'TERM' | 'KILL',
+): Promise<void> {
+  // TODO(e2b-pgid-identity): Prefer an atomic identity-bound group signal if E2B adds one;
+  // a userspace identity precheck cannot close the numeric-PGID reuse race.
+  try {
+    await sandbox.commands.run(
+      `kill -${signal} -- ${groups.map(group => `-${group}`).join(' ')}`,
+      commandOpts(envs),
+    )
+  } catch (error: unknown) {
+    if (!(error instanceof CommandExitError) && !(error instanceof SandboxNotFoundError)) throw error
+  }
+}

packages/e2b/subprocess-e2b/src/terminal.ts

@@ -0,0 +1,567 @@
+/** E2B PTY allocation and process-session ownership for the subprocess seam. */
+
+import { Buffer } from 'node:buffer'
+import { randomUUID } from 'node:crypto'
+import { PassThrough } from 'node:stream'
+import { posix } from 'node:path'
+import {
+  CommandExitError,
+  e2bControlEnvs,
+  FileNotFoundError,
+  SandboxNotFoundError,
+  quoteE2BShellArg,
+} from '@deepseek-ai/dsh-e2b'
+import type { CommandHandle, CommandResult, Sandbox } from '@deepseek-ai/dsh-e2b'
+import type {
+  SubprocessOutcome,
+  SubprocessTerminalForeground,
+  SubprocessTerminalHandle,
+  SubprocessTerminalSignal,
+  SubprocessTerminalSpawnSpec,
+} from '@deepseek-ai/dsh-subprocess'
+import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
+import {
+  bootstrapEnvironment,
+  readRemoteEnvironment,
+  serializeRemoteEnvironment,
+} from './environment.ts'
+import { asError, commandOpts, delay, signalOpts, signalRemoteGroups } from './remote.ts'
+
+const TERMINAL_RUNNER_SOURCE = [
+  '#!/bin/bash',
+  'set -euo pipefail',
+  'dsh_state=$1',
+  'mapfile -d \'\' -t dsh_env < "$dsh_state/environment"',
+  'mapfile -d \'\' -t dsh_argv < "$dsh_state/argv"',
+  'dsh_output_marker=$(<"$dsh_state/output-marker")',
+  'rm -f -- "$dsh_state/environment" "$dsh_state/argv" "$dsh_state/output-marker" "$dsh_state/runner.bash"',
+  'if (( ${#dsh_argv[@]} == 0 )); then',
+  "  printf 'terminal runner received empty argv\\n' >&2",
+  '  exit 125',
+  'fi',
+  'printf \'%s\' "$dsh_output_marker"',
+  'exec env -i -- "${dsh_env[@]}" "${dsh_argv[@]}"',
+  '',
+].join('\n')
+
+interface TerminalPaths {
+  runner: string
+  environment: string
+  argv: string
+  outputMarker: string
+}
+
+class BootstrapOutputFilter {
+  readonly ready: Promise<void>
+
+  private readonly readyState = Promise.withResolvers<void>()
+  private pending = Buffer.alloc(0)
+  private published = false
+
+  constructor(
+    private readonly marker: Buffer,
+    private readonly output: PassThrough,
+  ) {
+    this.ready = this.readyState.promise
+  }
+
+  push(data: Uint8Array): void {
+    if (this.published) {
+      this.write(data)
+      return
+    }
+    const combined = Buffer.concat([this.pending, Buffer.from(data)])
+    const markerOffset = combined.indexOf(this.marker)
+    if (markerOffset < 0) {
+      const retained = Math.min(combined.length, this.marker.length - 1)
+      this.pending = Buffer.from(combined.subarray(combined.length - retained))
+      return
+    }
+    this.published = true
+    this.pending = Buffer.alloc(0)
+    this.readyState.resolve()
+    this.write(combined.subarray(markerOffset + this.marker.length))
+  }
+
+  private write(data: Uint8Array): void {
+    if (data.length > 0 && !this.output.destroyed) this.output.write(data)
+  }
+}
+
+async function waitForBootstrapOutput(
+  ready: Promise<void>,
+  completion: Promise<CommandResult>,
+  signal?: AbortSignal,
+): Promise<void> {
+  signal?.throwIfAborted()
+  await new Promise<void>((resolve, reject) => {
+    let settled = false
+    let removeAbort: (() => void) | undefined
+    const finish = (complete: () => void): void => {
+      if (settled) return
+      settled = true
+      removeAbort?.()
+      complete()
+    }
+    const onExit = (): void => {
+      finish(() => { reject(new Error('subprocess-e2b: terminal exited before publishing its output boundary')) })
+    }
+    if (signal !== undefined) {
+      const onAbort = (): void => {
+        finish(() => { reject(asError(signal.reason)) })
+      }
+      signal.addEventListener('abort', onAbort, { once: true })
+      removeAbort = () => { signal.removeEventListener('abort', onAbort) }
+    }
+    void ready.then(() => { finish(resolve) })
+    void completion.then(onExit, onExit)
+  })
+}
+
+function parsePositiveId(value: string, message: string): number {
+  const raw = value.trim()
+  const id = Number(raw)
+  if (!/^[1-9][0-9]*$/.test(raw) || !Number.isSafeInteger(id)) throw new Error(message)
+  return id
+}
+
+function serializeValues(values: readonly string[], kind: string): string {
+  for (const value of values) {
+    if (value.includes('\0')) throw new Error(`subprocess-e2b: terminal ${kind} must not contain NUL bytes`)
+  }
+  return values.map(value => `${value}\0`).join('')
+}
+
+async function terminalSessionId(
+  sandbox: Sandbox,
+  pid: number,
+  envs: Record<string, string>,
+  signal?: AbortSignal,
+): Promise<number> {
+  const result = await sandbox.commands.run(`ps -o sid= -p ${pid}`, commandOpts(envs, signal))
+  signal?.throwIfAborted()
+  return parsePositiveId(result.stdout, `subprocess-e2b: cannot resolve process session for terminal ${pid}`)
+}
+
+async function sessionProcessGroups(
+  sandbox: Sandbox,
+  sessionId: number,
+  envs: Record<string, string>,
+): Promise<number[]> {
+  let result: CommandResult
+  try {
+    result = await sandbox.commands.run(
+      `set -o pipefail; ps -eo sid=,pgid=,stat= | awk '$1 == ${sessionId} && $3 !~ /^[ZXx]/ { print $2 }'`,
+      commandOpts(envs),
+    )
+  } catch (error: unknown) {
+    if (error instanceof SandboxNotFoundError) return []
+    throw error
+  }
+  const groups = new Set<number>()
+  for (const raw of result.stdout.trim().split(/\s+/)) {
+    if (raw.length === 0) continue
+    const group = parsePositiveId(
+      raw,
+      `subprocess-e2b: invalid process group ${JSON.stringify(raw)} in terminal session ${sessionId}`,
+    )
+    if (group <= 1) {
+      throw new Error(`subprocess-e2b: unsafe process group ${group} in terminal session ${sessionId}`)
+    }
+    groups.add(group)
+  }
+  return [...groups]
+}
+
+async function awaitSessionEmpty(
+  sandbox: Sandbox,
+  sessionId: number,
+  envs: Record<string, string>,
+  graceMs: number,
+  pollMs: number,
+  kill = false,
+): Promise<number[]> {
+  const deadline = Date.now() + graceMs
+  for (;;) {
+    const groups = await sessionProcessGroups(sandbox, sessionId, envs)
+    if (groups.length === 0) return groups
+    if (kill) {
+      await signalRemoteGroups(sandbox, envs, groups, 'KILL')
+      if (Date.now() >= deadline) return await sessionProcessGroups(sandbox, sessionId, envs)
+    } else if (Date.now() >= deadline) {
+      return groups
+    }
+    await delay(Math.min(pollMs, Math.max(1, deadline - Date.now())))
+  }
+}
+
+async function rollbackUnpublishedTerminal(
+  sandbox: Sandbox,
+  handle: CommandHandle,
+  completion: Promise<CommandResult>,
+  envs: Record<string, string>,
+  graceMs: number,
+  pollMs: number,
+): Promise<void> {
+  let topLevelExited = false
+  void completion.then(
+    () => { topLevelExited = true },
+    () => { topLevelExited = true },
+  )
+  const validPid = Number.isSafeInteger(handle.pid) && handle.pid > 1
+  const attemptFailures: Error[] = []
+  let sessionId: number | undefined
+  if (validPid) {
+    sessionId = handle.pid
+    try {
+      sessionId = await terminalSessionId(sandbox, handle.pid, envs)
+    } catch (_sessionLookupFailure) {
+      // E2B's PTY leader is also the provisional POSIX session leader, so its
+      // PID remains usable after the setup lookup itself fails or is canceled.
+    }
+    try {
+      let groups = await sessionProcessGroups(sandbox, sessionId, envs)
+      if (groups.length > 0) {
+        await signalRemoteGroups(sandbox, envs, groups, 'TERM')
+        groups = await awaitSessionEmpty(sandbox, sessionId, envs, graceMs, pollMs)
+      }
+      if (groups.length > 0) {
+        await awaitSessionEmpty(sandbox, sessionId, envs, graceMs, pollMs, true)
+      }
+    } catch (error: unknown) {
+      attemptFailures.push(asError(error))
+    }
+  }
+  // Completion can settle while any awaited provider cleanup above is running.
+  // oxlint-disable-next-line typescript/no-unnecessary-condition -- Provider cleanup yields to completion.
+  if (!topLevelExited) {
+    try {
+      await handle.kill()
+    } catch (error: unknown) {
+      if (error instanceof SandboxNotFoundError) return
+      attemptFailures.push(asError(error))
+    }
+    await Promise.race([completion.catch(() => undefined), delay(graceMs)])
+  }
+  const proofFailures: Error[] = []
+  if (sessionId !== undefined) {
+    try {
+      const groups = await awaitSessionEmpty(sandbox, sessionId, envs, graceMs, pollMs, true)
+      if (groups.length > 0) {
+        proofFailures.push(new Error(
+          `subprocess-e2b: terminal setup rollback failed; surviving process groups: ${groups.join(', ')}`,
+        ))
+      }
+    } catch (error: unknown) {
+      proofFailures.push(asError(error))
+    }
+  }
+  // The bounded completion race above updates this callback-owned state.
+  // oxlint-disable-next-line typescript/no-unnecessary-condition -- The callback mutates this after a race.
+  if (!topLevelExited) {
+    proofFailures.push(new Error(`subprocess-e2b: terminal setup rollback failed; surviving pid: ${handle.pid}`))
+  }
+  if (proofFailures.length > 0) {
+    throw new AggregateError(
+      [...attemptFailures, ...proofFailures],
+      'subprocess-e2b: terminal setup rollback did not reach quiescence',
+    )
+  }
+  try {
+    await handle.disconnect()
+  } catch (error: unknown) {
+    if (!(error instanceof SandboxNotFoundError)) throw error
+  }
+}
+
+/** One E2B PTY and all process groups in its remote process session. */
+export class E2BTerminalHandle implements SubprocessTerminalHandle {
+  readonly pid: number
+  readonly done: Promise<SubprocessOutcome>
+
+  private topLevelExited = false
+  private cleanup: Promise<void> | undefined
+  private readonly operationController = new AbortController()
+  private readonly operations = new Set<Promise<unknown>>()
+  private terminationSignal: NodeJS.Signals | null = null
+
+  constructor(
+    private readonly sandbox: Sandbox,
+    private readonly handle: CommandHandle,
+    readonly output: PassThrough,
+    private readonly completion: Promise<CommandResult>,
+    private readonly sessionId: number,
+    private readonly controlEnvs: Record<string, string>,
+    private readonly stateDir: string,
+    private readonly graceMs: number,
+    private readonly pollMs: number,
+  ) {
+    this.pid = handle.pid
+    this.done = this.waitForCommand()
+  }
+
+  // TODO(e2b-pgid-identity): Replace retained numeric PTY/session ids when E2B
+  // exposes identity-bound input, foreground-signal, and cleanup operations.
+  /** @inheritdoc */
+  write(data: string): Promise<void> {
+    return this.trackOperation(async (signal) => {
+      if (this.topLevelExited) throw new Error('terminal process has exited')
+      await this.sandbox.pty.sendInput(this.pid, Buffer.from(data, 'utf8'), { signal })
+    })
+  }
+
+  /** @inheritdoc */
+  inspectForeground(): Promise<SubprocessTerminalForeground | undefined> {
+    return this.trackOperation(signal => this.inspectForegroundOnce(signal))
+  }
+
+  /** @inheritdoc */
+  signalForeground(signal: SubprocessTerminalSignal): Promise<number> {
+    return this.trackOperation(async (operationSignal) => {
+      const foreground = await this.inspectForegroundOnce(operationSignal)
+      if (foreground === undefined) {
+        throw new Error(`subprocess-e2b: cannot resolve foreground process group for terminal ${this.pid}`)
+      }
+      if (signal === 'SIGKILL' && foreground.processGroupId === this.pid) {
+        throw new Error('refusing to SIGKILL the terminal shell; terminate the terminal session instead')
+      }
+      await this.sandbox.commands.run(
+        `kill -${signal.slice(3)} -- -${foreground.processGroupId}`,
+        commandOpts(this.controlEnvs, operationSignal),
+      )
+      return foreground.processGroupId
+    })
+  }
+
+  /** @inheritdoc */
+  terminate(): Promise<void> {
+    if (this.cleanup !== undefined) return this.cleanup
+    this.operationController.abort(new Error('subprocess-e2b: terminal is terminating'))
+    const cleanup = this.closeAfterOperations()
+    this.cleanup = cleanup
+    void cleanup.catch((_cleanupFailure: unknown) => {
+      this.cleanup = undefined
+    })
+    return cleanup
+  }
+
+  private async inspectForegroundOnce(
+    signal: AbortSignal,
+  ): Promise<SubprocessTerminalForeground | undefined> {
+    try {
+      const result = await this.sandbox.commands.run(
+        `ps -o tpgid= -p ${this.pid}`,
+        commandOpts(this.controlEnvs, signal),
+      )
+      return {
+        processGroupId: parsePositiveId(
+          result.stdout,
+          `subprocess-e2b: cannot resolve foreground process group for terminal ${this.pid}`,
+        ),
+        // E2B exposes process-table commands but not the /proc memory access
+        // needed to prove a specific syscall is waiting on fd 0.
+        inputWaiting: false,
+      }
+    } catch (error: unknown) {
+      if (error instanceof CommandExitError && (error.exitCode === 1 || this.topLevelExited)) return undefined
+      throw error
+    }
+  }
+
+  private trackOperation<T>(operation: (signal: AbortSignal) => Promise<T>): Promise<T> {
+    if (this.operationController.signal.aborted) {
+      return Promise.reject(new Error('subprocess-e2b: terminal is terminating'))
+    }
+    const pending = operation(this.operationController.signal)
+    this.operations.add(pending)
+    void pending.then(
+      () => { this.operations.delete(pending) },
+      () => { this.operations.delete(pending) },
+    )
+    return pending
+  }
+
+  private async closeAfterOperations(): Promise<void> {
+    await Promise.allSettled(this.operations)
+    await this.closeOnce()
+  }
+
+  private async waitForCommand(): Promise<SubprocessOutcome> {
+    try {
+      const result = await this.completion
+      return { exitCode: result.exitCode, signal: null }
+    } catch (error: unknown) {
+      if (error instanceof CommandExitError) {
+        return this.terminationSignal === null
+          ? { exitCode: error.exitCode, signal: null }
+          : { exitCode: null, signal: this.terminationSignal }
+      }
+      this.output.destroy(error instanceof Error ? error : new Error(String(error)))
+      throw error
+    } finally {
+      this.topLevelExited = true
+      if (!this.output.destroyed) this.output.end()
+    }
+  }
+
+  private async closeOnce(): Promise<void> {
+    let groups = await sessionProcessGroups(this.sandbox, this.sessionId, this.controlEnvs)
+    if (groups.length > 0) {
+      this.terminationSignal = 'SIGTERM'
+      await signalRemoteGroups(this.sandbox, this.controlEnvs, groups, 'TERM')
+      groups = await awaitSessionEmpty(this.sandbox, this.sessionId, this.controlEnvs, this.graceMs, this.pollMs)
+    }
+    if (groups.length === 0 && !this.topLevelExited) {
+      await Promise.race([this.done.catch(() => undefined), delay(this.graceMs)])
+    }
+    if (groups.length > 0 || !this.topLevelExited) {
+      this.terminationSignal = 'SIGKILL'
+      if (!this.topLevelExited) {
+        try {
+          await this.handle.kill()
+        } catch (error: unknown) {
+          if (error instanceof SandboxNotFoundError) return
+          throw error
+        }
+      }
+      groups = await awaitSessionEmpty(this.sandbox, this.sessionId, this.controlEnvs, this.graceMs, this.pollMs, true)
+      if (!this.topLevelExited) await Promise.race([this.done.catch(() => undefined), delay(this.graceMs)])
+    }
+    if (groups.length > 0) {
+      throw new Error(`subprocess-e2b: terminal cleanup failed; surviving process groups: ${groups.join(', ')}`)
+    }
+    if (!this.topLevelExited) {
+      throw new Error(`subprocess-e2b: terminal cleanup failed; surviving pid: ${this.pid}`)
+    }
+    try {
+      await this.handle.disconnect()
+    } catch (error: unknown) {
+      if (!(error instanceof SandboxNotFoundError)) throw error
+    }
+    try {
+      await this.sandbox.files.remove(this.stateDir)
+    } catch (_adapterPrivateStateRemovalFailure) {
+      // The terminal is quiescent; owner teardown bounds private residue.
+    }
+  }
+}
+
+/**
+ * Allocate an E2B PTY, replace its bootstrap shell with the requested argv,
+ * and return only after the private runner has published readiness.
+ * @param runtime - Shared E2B sandbox owner.
+ * @param spec - Fully specified terminal-process request.
+ * @param stateDir - Private remote directory for one startup transaction.
+ * @param pollMs - Remote session liveness poll cadence.
+ * @returns The live subprocess terminal handle.
+ */
+export async function spawnE2BTerminal(
+  runtime: E2BSandboxService,
+  spec: SubprocessTerminalSpawnSpec,
+  stateDir: string,
+  pollMs: number,
+): Promise<E2BTerminalHandle> {
+  const sandbox = await runtime.getSandbox()
+  spec.signal?.throwIfAborted()
+  const paths: TerminalPaths = {
+    runner: posix.join(stateDir, 'runner.bash'),
+    environment: posix.join(stateDir, 'environment'),
+    argv: posix.join(stateDir, 'argv'),
+    outputMarker: posix.join(stateDir, 'output-marker'),
+  }
+  const outputMarker = Buffer.from(`dsh-e2b-bootstrap:${randomUUID()}`)
+  const output = new PassThrough()
+  const outputFilter = new BootstrapOutputFilter(outputMarker, output)
+  let handle: CommandHandle | undefined
+  let completion: Promise<CommandResult> | undefined
+  let stateDirectoryCreated = false
+  let controlEnvs: Record<string, string> = {}
+  try {
+    const ambient = await readRemoteEnvironment(sandbox, spec.signal)
+    controlEnvs = bootstrapEnvironment(ambient)
+    const environment = serializeRemoteEnvironment(ambient, spec.env)
+    const argv = serializeValues(spec.argv, 'argv')
+    stateDirectoryCreated = true
+    await sandbox.files.makeDir(stateDir, signalOpts(spec.signal))
+    await sandbox.commands.run(
+      `chmod 700 -- ${quoteE2BShellArg(stateDir)}`,
+      commandOpts(controlEnvs, spec.signal),
+    )
+    await sandbox.files.write([
+      { path: paths.runner, data: TERMINAL_RUNNER_SOURCE },
+      { path: paths.environment, data: environment },
+      { path: paths.argv, data: argv },
+      { path: paths.outputMarker, data: outputMarker.toString('utf8') },
+    ], signalOpts(spec.signal))
+    await sandbox.commands.run(
+      `chmod 600 -- ${quoteE2BShellArg(paths.runner)} ${quoteE2BShellArg(paths.environment)} ${quoteE2BShellArg(paths.argv)} ${quoteE2BShellArg(paths.outputMarker)}`,
+      commandOpts(controlEnvs, spec.signal),
+    )
+    handle = await sandbox.pty.create({
+      rows: spec.rows,
+      cols: spec.cols,
+      cwd: spec.cwd,
+      envs: e2bControlEnvs(controlEnvs),
+      timeoutMs: 0,
+      onData: (data) => { outputFilter.push(data) },
+    })
+    completion = handle.wait()
+    void completion.catch(() => {})
+    spec.signal?.throwIfAborted()
+    if (!Number.isSafeInteger(handle.pid) || handle.pid <= 0) {
+      throw new Error(`subprocess-e2b: E2B returned invalid terminal pid ${handle.pid}`)
+    }
+    const command = `exec /bin/bash ${quoteE2BShellArg(paths.runner)} ${quoteE2BShellArg(stateDir)}\r`
+    await sandbox.pty.sendInput(handle.pid, Buffer.from(command), signalOpts(spec.signal))
+    await waitForBootstrapOutput(outputFilter.ready, completion, spec.signal)
+    const sessionId = await terminalSessionId(sandbox, handle.pid, controlEnvs, spec.signal)
+    return new E2BTerminalHandle(
+      sandbox,
+      handle,
+      output,
+      completion,
+      sessionId,
+      controlEnvs,
+      stateDir,
+      spec.graceMs,
+      pollMs,
+    )
+  } catch (error: unknown) {
+    output.destroy()
+    let terminalQuiescent = handle === undefined
+    let stateRemoved = !stateDirectoryCreated
+    const cleanup = async (): Promise<void> => {
+      const failures: Error[] = []
+      if (!terminalQuiescent && handle !== undefined) {
+        try {
+          if (completion === undefined) await handle.kill()
+          else await rollbackUnpublishedTerminal(sandbox, handle, completion, controlEnvs, spec.graceMs, pollMs)
+          terminalQuiescent = true
+        } catch (cleanupError: unknown) {
+          if (cleanupError instanceof SandboxNotFoundError) terminalQuiescent = true
+          else failures.push(asError(cleanupError))
+        }
+      }
+      if (!stateRemoved) {
+        try {
+          await sandbox.files.remove(stateDir)
+          stateRemoved = true
+        } catch (stateError: unknown) {
+          if (stateError instanceof FileNotFoundError || stateError instanceof SandboxNotFoundError) stateRemoved = true
+          else failures.push(asError(stateError))
+        }
+      }
+      if (failures.length > 0) {
+        throw new AggregateError(failures, 'subprocess-e2b: terminal setup cleanup did not complete')
+      }
+    }
+    try {
+      await cleanup()
+    } catch (cleanupError: unknown) {
+      // TODO(e2b-terminal-setup-rollback): Retain retry state only if a real
+      // double failure must be recovered before sandbox disposal or timeout.
+      throw new AggregateError([asError(error), asError(cleanupError)], asError(error).message)
+    }
+    throw error
+  }
+}

packages/e2b/subprocess-e2b/tests/terminal.spec.ts

@@ -0,0 +1,926 @@
+import { Buffer } from 'node:buffer'
+import { once } from 'node:events'
+import { Context } from 'cordis'
+import { describe, expect, it, vi } from 'vitest'
+import {
+  CommandExitError,
+  FileNotFoundError,
+  SandboxNotFoundError,
+  type CommandHandle,
+  type CommandResult,
+  type Sandbox,
+} from '@deepseek-ai/dsh-e2b'
+import type E2BSandboxService from '@deepseek-ai/dsh-e2b'
+import type { SubprocessTerminalSpawnSpec } from '@deepseek-ai/dsh-subprocess'
+import E2BSubprocessService from '@deepseek-ai/dsh-subprocess-e2b'
+import { spawnE2BTerminal } from '../src/terminal.ts'
+
+function commandError(exitCode: number): CommandExitError {
+  return new CommandExitError({ exitCode, stdout: '', stderr: '', error: `exit ${exitCode}` })
+}
+
+interface CommandOptions {
+  signal?: AbortSignal
+  cwd?: string
+  envs?: Record<string, string>
+}
+
+class FakeTerminalCommandHandle {
+  pid = 123
+  disconnects = 0
+  sdkKills = 0
+  disconnectError: unknown
+  sdkKillError: unknown
+  waitError: unknown
+  settleOnSdkKill = true
+  private readonly result = Promise.withResolvers<CommandResult>()
+  private settled = false
+
+  wait(): Promise<CommandResult> {
+    if (this.waitError !== undefined) throw this.waitError
+    return this.result.promise
+  }
+
+  async disconnect(): Promise<void> {
+    this.disconnects += 1
+    if (this.disconnectError !== undefined) throw this.disconnectError
+  }
+
+  async kill(): Promise<boolean> {
+    this.sdkKills += 1
+    if (this.sdkKillError !== undefined) {
+      const error = this.sdkKillError
+      if (this.settleOnSdkKill) this.fail(137)
+      throw error
+    }
+    if (this.settleOnSdkKill) this.fail(137)
+    return true
+  }
+
+  succeed(exitCode = 0): void {
+    if (this.settled) return
+    this.settled = true
+    this.result.resolve({ exitCode, stdout: '', stderr: '' })
+  }
+
+  fail(exitCode: number): void {
+    if (this.settled) return
+    this.settled = true
+    this.result.reject(commandError(exitCode))
+  }
+
+  crash(error: unknown): void {
+    if (this.settled) return
+    this.settled = true
+    this.result.reject(error)
+  }
+
+  asHandle(): CommandHandle {
+    return this as unknown as CommandHandle
+  }
+}
+
+class FakeTerminalSandbox {
+  readonly handle = new FakeTerminalCommandHandle()
+  readonly commands: string[] = []
+  readonly commandOptions: CommandOptions[] = []
+  readonly inputs: Array<{ pid: number; data: Buffer }> = []
+  readonly removed: string[] = []
+  readonly directories: string[] = []
+  readonly writes = new Map<string, string>()
+  createOptions: Parameters<Sandbox['pty']['create']>[0] | undefined
+  ambient = 'KEEP=visible\0UNICODE=你好\0NPM_TOKEN=secret\0DSH_STALE=old\0BROKEN\0=bad\0'
+  sessionId = '123\n'
+  foreground = '456\n'
+  groups = [123]
+  zombieGroups: number[] = []
+  createError: unknown
+  writeError: unknown
+  sendError: unknown
+  commandFailure: unknown
+  makeDirRequest: ((signal: AbortSignal | undefined) => Promise<void>) | undefined
+  sendInputRequest: ((signal: AbortSignal | undefined) => Promise<void>) | undefined
+  foregroundRequest: ((signal: AbortSignal | undefined) => Promise<void>) | undefined
+  signalRequest: ((signal: AbortSignal | undefined) => Promise<void>) | undefined
+  sessionGroupsFailure: unknown
+  foregroundFailure: unknown
+  termFailure: unknown
+  removeError: unknown
+  clearOnTerm = true
+  clearOnKill = true
+  resolvedExecutable = '/usr/bin/node\n'
+  requestedOutput = 'requested-shell$ '
+  emitOutputMarker = true
+  afterSessionLookup: (() => void) | undefined
+  private createGate: Promise<undefined> | undefined
+  private releaseCreateGate: (() => void) | undefined
+
+  deferCreate(): void {
+    const gate = Promise.withResolvers<undefined>()
+    this.createGate = gate.promise
+    this.releaseCreateGate = () => { gate.resolve(undefined) }
+  }
+
+  releaseCreate(): void {
+    this.releaseCreateGate?.()
+  }
+
+  readonly sandbox = {
+    files: {
+      makeDir: async (path: string, options?: CommandOptions): Promise<boolean> => {
+        this.directories.push(path)
+        await this.makeDirRequest?.(options?.signal)
+        options?.signal?.throwIfAborted()
+        return true
+      },
+      write: async (files: Array<{ path: string; data: string }>): Promise<object[]> => {
+        for (const file of files) this.writes.set(file.path, file.data)
+        if (this.writeError !== undefined) throw this.writeError
+        return files.map(() => ({}))
+      },
+      remove: async (path: string): Promise<void> => {
+        this.removed.push(path)
+        if (this.removeError !== undefined) throw this.removeError
+      },
+    },
+    commands: {
+      run: async (command: string, options?: CommandOptions): Promise<CommandResult> => {
+        this.commands.push(command)
+        if (options !== undefined) this.commandOptions.push(options)
+        options?.signal?.throwIfAborted()
+        if (this.commandFailure !== undefined) {
+          const error = this.commandFailure
+          this.commandFailure = undefined
+          throw error
+        }
+        if (command.includes('env -0 | base64')) {
+          return {
+            exitCode: 0,
+            stdout: ['/home/user', this.ambient].map(value => Buffer.from(value).toString('base64')).join('\n'),
+            stderr: '',
+          }
+        }
+        if (command.includes('command -v -- ')) {
+          return { exitCode: 0, stdout: this.resolvedExecutable, stderr: '' }
+        }
+        if (command.startsWith('ps -o sid=')) {
+          this.afterSessionLookup?.()
+          return { exitCode: 0, stdout: this.sessionId, stderr: '' }
+        }
+        if (command.startsWith('ps -o tpgid=')) {
+          await this.foregroundRequest?.(options?.signal)
+          options?.signal?.throwIfAborted()
+          if (this.foregroundFailure !== undefined) throw this.foregroundFailure
+          return { exitCode: 0, stdout: this.foreground, stderr: '' }
+        }
+        if (command.startsWith('set -o pipefail; ps -eo sid=')) {
+          if (this.sessionGroupsFailure !== undefined) throw this.sessionGroupsFailure
+          const groups = command.includes('stat=') && command.includes('$3 !~ /^[ZXx]/')
+            ? this.groups
+            : [...this.groups, ...this.zombieGroups]
+          return { exitCode: 0, stdout: groups.map(group => `${group}\n`).join(''), stderr: '' }
+        }
+        if (command.startsWith('kill -TERM -- ')) {
+          if (this.termFailure !== undefined) throw this.termFailure
+          if (this.clearOnTerm) {
+            this.groups = []
+            this.handle.fail(143)
+          }
+        }
+        if (command.startsWith('kill -INT -- ')) {
+          await this.signalRequest?.(options?.signal)
+          options?.signal?.throwIfAborted()
+        }
+        if (command.startsWith('kill -KILL -- ') && this.clearOnKill) this.groups = []
+        return { exitCode: 0, stdout: '', stderr: '' }
+      },
+    },
+    pty: {
+      create: async (options: Parameters<Sandbox['pty']['create']>[0]): Promise<CommandHandle> => {
+        this.createOptions = options
+        if (this.createError !== undefined) throw this.createError
+        await this.createGate
+        options.signal?.throwIfAborted()
+        await options.onData(Buffer.from('buffered banner\n'))
+        return this.handle.asHandle()
+      },
+      sendInput: async (pid: number, data: Uint8Array, options?: { signal?: AbortSignal }): Promise<void> => {
+        options?.signal?.throwIfAborted()
+        await this.sendInputRequest?.(options?.signal)
+        options?.signal?.throwIfAborted()
+        this.inputs.push({ pid, data: Buffer.from(data) })
+        if (this.sendError !== undefined) throw this.sendError
+        if (this.emitOutputMarker && Buffer.from(data).includes(Buffer.from('runner.bash'))) {
+          const marker = [...this.writes].find(([path]) => path.endsWith('/output-marker'))?.[1]
+          const onData = this.createOptions?.onData
+          if (marker !== undefined && onData !== undefined) {
+            await onData(Buffer.from(Buffer.from(data).toString().replace(/\r$/, '\r\n')))
+            const split = Math.floor(marker.length / 2)
+            await onData(Buffer.from(marker.slice(0, split)))
+            await onData(Buffer.from(marker.slice(split)))
+            await onData(Buffer.from(this.requestedOutput))
+          }
+        }
+      },
+    },
+  } as unknown as Sandbox
+}
+
+function runtime(fake: FakeTerminalSandbox): E2BSandboxService {
+  return {
+    cwd: '/workspace',
+    runtimeRoot: '/workspace/.dsh-e2b',
+    getSandbox: async () => fake.sandbox,
+  } as unknown as E2BSandboxService
+}
+
+function spec(overrides: Partial<SubprocessTerminalSpawnSpec> = {}): SubprocessTerminalSpawnSpec {
+  return {
+    argv: ['/bin/bash', '--noprofile', '--norc'],
+    cwd: '/workspace',
+    rows: 24,
+    cols: 80,
+    graceMs: 5,
+    env: { TERM: 'dumb', DSH_SESSION_ID: 'owner', TOKEN_EXPLICIT: 'kept' },
+    ...overrides,
+  }
+}
+
+function holdRequestUntilAbort(started: PromiseWithResolvers<AbortSignal>) {
+  return async (signal: AbortSignal | undefined): Promise<void> => {
+    if (signal === undefined) throw new Error('expected an operation signal')
+    signal.throwIfAborted()
+    started.resolve(signal)
+    await new Promise<void>((_resolve, reject) => {
+      signal.addEventListener('abort', () => {
+        reject(signal.reason instanceof Error ? signal.reason : new Error(String(signal.reason)))
+      }, { once: true })
+    })
+  }
+}
+
+/** Spawn the terminal under test with the config default the service would pass. */
+function testSpawn(
+  runtime: Parameters<typeof spawnE2BTerminal>[0],
+  spec: Parameters<typeof spawnE2BTerminal>[1],
+  stateDir: string,
+  pollMs = 20,
+): ReturnType<typeof spawnE2BTerminal> {
+  return spawnE2BTerminal(runtime, spec, stateDir, pollMs)
+}
+
+describe('E2B terminal allocation', () => {
+  it('hides bootstrap-shell bytes and preserves requested-shell bytes across the output boundary', async () => {
+    const fake = new FakeTerminalSandbox()
+    const terminal = await testSpawn(runtime(fake), spec(), '/runtime/terminal-one')
+    let output = ''
+    terminal.output.on('data', (chunk) => { output += String(chunk) })
+    await new Promise(resolve => setTimeout(resolve, 0))
+
+    expect(output).toBe('requested-shell$ ')
+    expect(output).not.toContain('buffered banner')
+    expect(output).not.toContain('runner.bash')
+    expect(fake.createOptions).toMatchObject({ rows: 24, cols: 80, cwd: '/workspace', timeoutMs: 0 })
+    const controlEnvs = fake.createOptions?.envs
+    expect(controlEnvs?.HOME).toMatch(/^\/\.dsh-e2b-control-/)
+    expect(controlEnvs).toEqual({
+      TERM: 'dumb',
+      NPM_TOKEN: '',
+      DSH_STALE: '',
+      HOME: controlEnvs?.HOME,
+    })
+    expect(fake.inputs[0]?.data.toString()).toContain("exec /bin/bash '/runtime/terminal-one/runner.bash'")
+    expect(fake.writes.get('/runtime/terminal-one/environment')).toContain('KEEP=visible\0')
+    expect(fake.writes.get('/runtime/terminal-one/environment')).toContain('UNICODE=你好\0')
+    expect(fake.writes.get('/runtime/terminal-one/environment')).toContain('TOKEN_EXPLICIT=kept\0')
+    expect(fake.writes.get('/runtime/terminal-one/environment')).not.toContain('secret')
+    expect(fake.writes.get('/runtime/terminal-one/environment')).not.toContain('DSH_STALE')
+    expect(fake.writes.get('/runtime/terminal-one/argv')).toBe('/bin/bash\0--noprofile\0--norc\0')
+    const marker = fake.writes.get('/runtime/terminal-one/output-marker') ?? ''
+    expect(marker).toMatch(/^dsh-e2b-bootstrap:/)
+    expect(fake.inputs[0]?.data.toString()).not.toContain(marker)
+    const runner = fake.writes.get('/runtime/terminal-one/runner.bash') ?? ''
+    expect(runner).toContain('if (( ${#dsh_argv[@]} == 0 )); then')
+    expect(runner).toContain('printf \'%s\' "$dsh_output_marker"')
+    expect(runner).toContain('exec env -i -- "${dsh_env[@]}" "${dsh_argv[@]}"')
+    expect(runner).not.toContain('\u007f')
+    terminal.output.destroy()
+    await fake.createOptions?.onData(Buffer.from('late bootstrap callback'))
+    expect(output).toBe('requested-shell$ ')
+
+    await terminal.write('echo ok\r')
+    expect(fake.inputs.at(-1)?.data.toString()).toBe('echo ok\r')
+    await expect(terminal.inspectForeground()).resolves.toEqual({ processGroupId: 456, inputWaiting: false })
+    await expect(terminal.signalForeground('SIGINT')).resolves.toBe(456)
+    expect(fake.commands).toContain('kill -INT -- -456')
+
+    const terminated = terminal.terminate()
+    await expect(terminal.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
+    await terminated
+    expect(fake.handle.disconnects).toBe(1)
+    expect(fake.removed).toContain('/runtime/terminal-one')
+  })
+
+  it('inherits only safe ambient values and limits the allocation signal to setup', async () => {
+    const fake = new FakeTerminalSandbox()
+    const controller = new AbortController()
+    const terminal = await testSpawn(
+      runtime(fake),
+      spec({ env: undefined, signal: controller.signal }),
+      '/runtime/abort-live',
+    )
+    const environment = fake.writes.get('/runtime/abort-live/environment') ?? ''
+    expect(environment).toContain('KEEP=visible\0')
+    expect(environment).not.toContain('secret')
+    expect(environment).not.toContain('DSH_STALE')
+
+    controller.abort(new Error('stop'))
+    await terminal.write('still live\r')
+    expect(fake.inputs.at(-1)?.data.toString()).toBe('still live\r')
+    await terminal.terminate()
+    await expect(terminal.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
+  })
+
+  it('publishes the PTY handle before honoring allocation cancellation', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.deferCreate()
+    const controller = new AbortController()
+    const spawning = testSpawn(
+      runtime(fake),
+      spec({ signal: controller.signal }),
+      '/runtime/allocation-cancel',
+    )
+    await vi.waitFor(() => { expect(fake.createOptions).toBeDefined() })
+
+    controller.abort(new Error('allocation cancelled'))
+    fake.releaseCreate()
+    await expect(spawning).rejects.toThrow('allocation cancelled')
+    expect(fake.createOptions?.signal).toBeUndefined()
+    expect(fake.groups).toEqual([])
+    expect(fake.handle.disconnects).toBe(1)
+  })
+
+  it('rejects malformed environment and argv values before PTY allocation', async () => {
+    const invalidName = new FakeTerminalSandbox()
+    await expect(testSpawn(runtime(invalidName), spec({ env: { 'BAD=NAME': 'x' } }), '/runtime/name'))
+      .rejects.toThrow('environment entries')
+    expect(invalidName.createOptions).toBeUndefined()
+
+    const invalidValue = new FakeTerminalSandbox()
+    await expect(testSpawn(runtime(invalidValue), spec({ env: { BAD: 'x\0y' } }), '/runtime/value'))
+      .rejects.toThrow('environment entries')
+
+    const invalidArg = new FakeTerminalSandbox()
+    await expect(testSpawn(runtime(invalidArg), spec({ argv: ['/bin/bash', 'x\0y'] }), '/runtime/argv'))
+      .rejects.toThrow('argv must not contain NUL')
+  })
+
+  it('cleans malformed handles, bootstrap failures, and readiness failures', async () => {
+    const failedState = new FakeTerminalSandbox()
+    failedState.writeError = new Error('state write failed')
+    await expect(testSpawn(runtime(failedState), spec(), '/runtime/state-write'))
+      .rejects.toThrow('state write failed')
+    expect(failedState.writes.get('/runtime/state-write/environment')).toContain('KEEP=visible\0')
+    expect(failedState.removed).toContain('/runtime/state-write')
+    expect(failedState.createOptions).toBeUndefined()
+
+    const stateAlreadyGone = new FakeTerminalSandbox()
+    stateAlreadyGone.writeError = new Error('state write failed after external cleanup')
+    stateAlreadyGone.removeError = new FileNotFoundError('state already gone')
+    await expect(testSpawn(runtime(stateAlreadyGone), spec(), '/runtime/state-gone'))
+      .rejects.toThrow('state write failed after external cleanup')
+
+    const invalidPid = new FakeTerminalSandbox()
+    invalidPid.handle.pid = 0
+    await expect(testSpawn(runtime(invalidPid), spec(), '/runtime/invalid-pid'))
+      .rejects.toThrow('invalid terminal pid 0')
+    expect(invalidPid.handle.sdkKills).toBe(1)
+    expect(invalidPid.removed).toContain('/runtime/invalid-pid')
+
+    const failedInput = new FakeTerminalSandbox()
+    failedInput.sendError = new Error('bootstrap failed')
+    await expect(testSpawn(runtime(failedInput), spec(), '/runtime/input'))
+      .rejects.toThrow('bootstrap failed')
+    expect(failedInput.commands).toContain('kill -TERM -- -123')
+    expect(failedInput.groups).toEqual([])
+
+    const invalidSession = new FakeTerminalSandbox()
+    invalidSession.sessionId = 'not-a-session\n'
+    invalidSession.clearOnTerm = false
+    await expect(testSpawn(runtime(invalidSession), spec(), '/runtime/session'))
+      .rejects.toThrow('cannot resolve process session')
+    expect(invalidSession.commands).toContain('kill -TERM -- -123')
+    expect(invalidSession.commands).toContain('kill -KILL -- -123')
+    expect(invalidSession.groups).toEqual([])
+    expect(invalidSession.handle.sdkKills).toBe(1)
+    const lateData = invalidSession.createOptions?.onData
+    if (lateData === undefined) throw new Error('missing captured terminal callback')
+    expect(lateData(Buffer.from('late bytes'))).toBeUndefined()
+
+    const termFailed = new FakeTerminalSandbox()
+    termFailed.sendError = new Error('bootstrap failed')
+    termFailed.termFailure = new Error('TERM transport failed')
+    await expect(testSpawn(runtime(termFailed), spec(), '/runtime/term-failed'))
+      .rejects.toThrow('bootstrap failed')
+    expect(termFailed.commands).toContain('kill -KILL -- -123')
+    expect(termFailed.handle.sdkKills).toBe(1)
+
+    const uninspectable = new FakeTerminalSandbox()
+    uninspectable.sendError = new Error('bootstrap failed')
+    uninspectable.sessionGroupsFailure = 'session enumeration failed'
+    uninspectable.handle.sdkKillError = new Error('PTY kill failed')
+    let uninspectableFailure: unknown
+    try {
+      await testSpawn(runtime(uninspectable), spec(), '/runtime/uninspectable')
+    } catch (error: unknown) {
+      uninspectableFailure = error
+    }
+    expect(uninspectableFailure).toBeInstanceOf(AggregateError)
+    expect(uninspectable.handle.sdkKills).toBe(1)
+
+    const survivingGroups = new FakeTerminalSandbox()
+    survivingGroups.sendError = new Error('bootstrap failed')
+    survivingGroups.clearOnTerm = false
+    survivingGroups.clearOnKill = false
+    await expect(testSpawn(runtime(survivingGroups), spec({ graceMs: 1 }), '/runtime/surviving-groups'))
+      .rejects.toThrow('bootstrap failed')
+
+    const survivingPid = new FakeTerminalSandbox()
+    survivingPid.sendError = new Error('bootstrap failed')
+    survivingPid.groups = []
+    survivingPid.handle.settleOnSdkKill = false
+    await expect(testSpawn(runtime(survivingPid), spec({ graceMs: 1 }), '/runtime/surviving-pid'))
+      .rejects.toThrow('bootstrap failed')
+
+    const waitFailed = new FakeTerminalSandbox()
+    waitFailed.handle.waitError = new Error('wait failed')
+    waitFailed.handle.settleOnSdkKill = false
+    waitFailed.handle.sdkKillError = new Error('kill failed')
+    await expect(testSpawn(runtime(waitFailed), spec(), '/runtime/wait-failed'))
+      .rejects.toThrow('wait failed')
+    expect(waitFailed.handle.sdkKills).toBe(1)
+
+    const cleanupFailed = new FakeTerminalSandbox()
+    cleanupFailed.handle.pid = 0
+    cleanupFailed.handle.sdkKillError = new Error('kill transport failed')
+    cleanupFailed.removeError = new Error('remove transport failed')
+    await expect(testSpawn(runtime(cleanupFailed), spec(), '/runtime/cleanup-failed'))
+      .rejects.toThrow('invalid terminal pid 0')
+
+    const expiredDuringRollback = new FakeTerminalSandbox()
+    expiredDuringRollback.sendError = new Error('bootstrap failed before timeout')
+    expiredDuringRollback.groups = []
+    expiredDuringRollback.handle.settleOnSdkKill = false
+    expiredDuringRollback.handle.sdkKillError = new SandboxNotFoundError('sandbox expired')
+    expiredDuringRollback.removeError = new SandboxNotFoundError('sandbox expired')
+    await expect(testSpawn(runtime(expiredDuringRollback), spec(), '/runtime/expired-rollback'))
+      .rejects.toThrow('bootstrap failed before timeout')
+    expect(expiredDuringRollback.handle.sdkKills).toBe(1)
+
+    const expiredBeforeSdkRollback = new FakeTerminalSandbox()
+    expiredBeforeSdkRollback.handle.waitError = new Error('wait failed after timeout')
+    expiredBeforeSdkRollback.handle.sdkKillError = new SandboxNotFoundError('sandbox expired')
+    expiredBeforeSdkRollback.handle.settleOnSdkKill = false
+    await expect(testSpawn(runtime(expiredBeforeSdkRollback), spec(), '/runtime/expired-sdk-rollback'))
+      .rejects.toThrow('wait failed after timeout')
+
+    const missingDuringDisconnect = new FakeTerminalSandbox()
+    missingDuringDisconnect.sendError = new Error('bootstrap failed before disconnect')
+    missingDuringDisconnect.handle.disconnectError = new SandboxNotFoundError('sandbox expired')
+    await expect(testSpawn(runtime(missingDuringDisconnect), spec(), '/runtime/missing-disconnect'))
+      .rejects.toThrow('bootstrap failed before disconnect')
+
+    const failedDisconnect = new FakeTerminalSandbox()
+    failedDisconnect.sendError = new Error('bootstrap failed with disconnect failure')
+    failedDisconnect.handle.disconnectError = new Error('disconnect transport failed')
+    await expect(testSpawn(runtime(failedDisconnect), spec(), '/runtime/failed-disconnect'))
+      .rejects.toThrow('bootstrap failed with disconnect failure')
+  })
+
+  it('propagates setup cancellation and provider failures', async () => {
+    const aborted = new FakeTerminalSandbox()
+    await expect(testSpawn(runtime(aborted), spec({ signal: AbortSignal.abort(new Error('stop')) }), '/runtime/abort'))
+      .rejects.toThrow('stop')
+
+    const createFailed = new FakeTerminalSandbox()
+    createFailed.createError = new Error('create failed')
+    await expect(testSpawn(runtime(createFailed), spec(), '/runtime/create'))
+      .rejects.toThrow('create failed')
+
+  })
+
+  it('bounds a missing bootstrap-output boundary by process exit or cancellation', async () => {
+    const exited = new FakeTerminalSandbox()
+    exited.emitOutputMarker = false
+    const exiting = testSpawn(runtime(exited), spec(), '/runtime/missing-output-boundary')
+    await vi.waitFor(() => { expect(exited.inputs).toHaveLength(1) })
+    exited.handle.succeed(0)
+    await expect(exiting).rejects.toThrow('terminal exited before publishing its output boundary')
+
+    const cancelled = new FakeTerminalSandbox()
+    cancelled.emitOutputMarker = false
+    const controller = new AbortController()
+    const cancelling = testSpawn(
+      runtime(cancelled),
+      spec({ signal: controller.signal }),
+      '/runtime/cancel-output-boundary',
+    )
+    await vi.waitFor(() => { expect(cancelled.inputs).toHaveLength(1) })
+    await new Promise(resolve => setTimeout(resolve, 0))
+    controller.abort(new Error('cancel output boundary'))
+    await expect(cancelling).rejects.toThrow('cancel output boundary')
+  })
+})
+
+describe('E2B terminal lifecycle', () => {
+  it('aborts and joins in-flight terminal operations before cleanup', async () => {
+    const fake = new FakeTerminalSandbox()
+    const terminal = await testSpawn(runtime(fake), spec(), '/runtime/in-flight-operations')
+    const writeStarted = Promise.withResolvers<AbortSignal>()
+    const inspectStarted = Promise.withResolvers<AbortSignal>()
+    const signalStarted = Promise.withResolvers<AbortSignal>()
+    fake.sendInputRequest = holdRequestUntilAbort(writeStarted)
+    let foregroundRequests = 0
+    fake.foregroundRequest = async (signal) => {
+      foregroundRequests += 1
+      if (foregroundRequests === 1) await holdRequestUntilAbort(inspectStarted)(signal)
+    }
+    let signalCompleted = false
+    fake.signalRequest = async (operationSignal) => {
+      await holdRequestUntilAbort(signalStarted)(operationSignal)
+      signalCompleted = true
+    }
+    const write = terminal.write('late input')
+    const inspect = terminal.inspectForeground()
+    await Promise.all([writeStarted.promise, inspectStarted.promise])
+    const signal = terminal.signalForeground('SIGINT')
+    await signalStarted.promise
+
+    const terminating = terminal.terminate()
+    await expect(write).rejects.toThrow('terminal is terminating')
+    await expect(inspect).rejects.toThrow('terminal is terminating')
+    await expect(signal).rejects.toThrow('terminal is terminating')
+    await terminating
+    expect(signalCompleted).toBe(false)
+    expect(fake.inputs).toHaveLength(1)
+    const commandCount = fake.commands.length
+    await expect(terminal.write('after termination')).rejects.toThrow('terminal is terminating')
+    await expect(terminal.inspectForeground()).rejects.toThrow('terminal is terminating')
+    await expect(terminal.signalForeground('SIGINT')).rejects.toThrow('terminal is terminating')
+    expect(fake.commands).toHaveLength(commandCount)
+  })
+
+  it('maps ordinary exits, closes output, and reports an absent foreground after exit', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.groups = []
+    const terminal = await testSpawn(runtime(fake), spec(), '/runtime/natural')
+    terminal.output.resume()
+    const ended = once(terminal.output, 'end')
+    fake.handle.succeed(7)
+    await expect(terminal.done).resolves.toEqual({ exitCode: 7, signal: null })
+    await ended
+    await expect(terminal.write('late')).rejects.toThrow('exited')
+    fake.foregroundFailure = commandError(1)
+    await expect(terminal.inspectForeground()).resolves.toBeUndefined()
+    await expect(terminal.signalForeground('SIGINT')).rejects.toThrow('cannot resolve foreground process group')
+    await terminal.terminate()
+  })
+
+  it.each([
+    [7, { exitCode: 7, signal: null }],
+    [143, { exitCode: 143, signal: null }],
+    [255, { exitCode: 255, signal: null }],
+  ] as const)('classifies an unrequested command exit %i', async (exitCode, expected) => {
+    const fake = new FakeTerminalSandbox()
+    fake.groups = []
+    const terminal = await testSpawn(runtime(fake), spec(), `/runtime/exit-${exitCode}`)
+    fake.handle.fail(exitCode)
+    await expect(terminal.done).resolves.toEqual(expected)
+    await terminal.terminate()
+  })
+
+  it('treats a terminal session containing only zombies as quiescent', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.groups = []
+    fake.zombieGroups = [123]
+    const terminal = await testSpawn(runtime(fake), spec(), '/runtime/zombie-session')
+
+    fake.handle.succeed(0)
+    await expect(terminal.done).resolves.toEqual({ exitCode: 0, signal: null })
+    await terminal.terminate()
+    expect(fake.commands).toContain(
+      "set -o pipefail; ps -eo sid=,pgid=,stat= | awk '$1 == 123 && $3 !~ /^[ZXx]/ { print $2 }'",
+    )
+  })
+
+  it('treats a timeout-killed sandbox as quiescent during terminal cleanup', async () => {
+    const fake = new FakeTerminalSandbox()
+    const terminal = await testSpawn(runtime(fake), spec(), '/runtime/expired-sandbox')
+    fake.sessionGroupsFailure = new SandboxNotFoundError('sandbox expired')
+    fake.handle.succeed(0)
+
+    await expect(terminal.done).resolves.toEqual({ exitCode: 0, signal: null })
+    await terminal.terminate()
+  })
+
+  it('treats sandbox disappearance during PTY kill as quiescent', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.groups = []
+    fake.handle.settleOnSdkKill = false
+    fake.handle.sdkKillError = new SandboxNotFoundError('sandbox expired')
+    const terminal = await testSpawn(runtime(fake), spec({ graceMs: 1 }), '/runtime/expired-pty-kill')
+
+    await terminal.terminate()
+    expect(fake.handle.sdkKills).toBe(1)
+  })
+
+  it('propagates a non-missing PTY kill failure', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.groups = []
+    fake.handle.settleOnSdkKill = false
+    fake.handle.sdkKillError = new Error('PTY kill transport failed')
+    const terminal = await testSpawn(runtime(fake), spec({ graceMs: 1 }), '/runtime/failed-pty-kill')
+
+    await expect(terminal.terminate()).rejects.toThrow('PTY kill transport failed')
+    fake.handle.sdkKillError = undefined
+    fake.handle.succeed(0)
+    await terminal.done
+    await terminal.terminate()
+  })
+
+  it.each([
+    ['accepts sandbox loss', new SandboxNotFoundError('sandbox expired'), true],
+    ['propagates another failure', new Error('disconnect failed'), false],
+  ] as const)('%s while disconnecting a settled terminal', async (_label, failure, accepted) => {
+    const fake = new FakeTerminalSandbox()
+    const terminal = await testSpawn(runtime(fake), spec(), `/runtime/disconnect-${accepted}`)
+    fake.handle.disconnectError = failure
+    fake.groups = []
+    fake.handle.succeed(0)
+
+    if (accepted) await expect(terminal.terminate()).resolves.toBeUndefined()
+    else await expect(terminal.terminate()).rejects.toThrow('disconnect failed')
+  })
+
+  it('rejects killing the terminal shell and propagates live foreground failures', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.foreground = '123\n'
+    const terminal = await testSpawn(runtime(fake), spec(), '/runtime/signal')
+    await expect(terminal.signalForeground('SIGKILL')).rejects.toThrow('refusing to SIGKILL')
+    fake.foreground = 'invalid\n'
+    await expect(terminal.inspectForeground()).rejects.toThrow('cannot resolve foreground')
+    fake.foregroundFailure = commandError(1)
+    await expect(terminal.inspectForeground()).resolves.toBeUndefined()
+    fake.foregroundFailure = commandError(2)
+    await expect(terminal.inspectForeground()).rejects.toBeInstanceOf(CommandExitError)
+    fake.clearOnTerm = true
+    await terminal.terminate()
+  })
+
+  it('sends KILL before checking an expired force-cleanup deadline', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.groups = [123, 456]
+    fake.clearOnTerm = false
+    const terminal = await testSpawn(runtime(fake), spec({ graceMs: 0 }), '/runtime/escalate')
+    const terminating = terminal.terminate()
+    await expect(terminal.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
+    await terminating
+    expect(fake.commands).toContain('kill -TERM -- -123 -456')
+    expect(fake.commands).toContain('kill -KILL -- -123 -456')
+  })
+
+  it('surfaces cleanup failures and allows a later retry', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.groups = [1]
+    const terminal = await testSpawn(runtime(fake), spec({ graceMs: 1 }), '/runtime/retry')
+    await expect(terminal.terminate()).rejects.toThrow('unsafe process group 1')
+
+    fake.groups = []
+    fake.handle.succeed(0)
+    await terminal.done
+    await terminal.terminate()
+  })
+
+  it('propagates a process-group signalling transport failure before retry', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.termFailure = new Error('signal transport failed')
+    const terminal = await testSpawn(runtime(fake), spec({ graceMs: 1 }), '/runtime/signal-failure')
+    await expect(terminal.terminate()).rejects.toThrow('signal transport failed')
+
+    fake.groups = []
+    fake.handle.succeed(0)
+    await terminal.done
+    await terminal.terminate()
+
+    const alreadyExited = new FakeTerminalSandbox()
+    alreadyExited.termFailure = commandError(1)
+    const tolerant = await testSpawn(runtime(alreadyExited), spec({ graceMs: 1 }), '/runtime/group-exited')
+    const tolerantTermination = tolerant.terminate()
+    await expect(tolerant.done).resolves.toEqual({ exitCode: null, signal: 'SIGKILL' })
+    await tolerantTermination
+  })
+
+  it('keeps command rejection authoritative while cleanup is already waiting', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.groups = []
+    fake.removeError = new Error('private state already gone')
+    const terminal = await testSpawn(runtime(fake), spec(), '/runtime/reject-during-cleanup')
+    terminal.output.on('error', () => {})
+    const cleanup = terminal.terminate()
+    await Promise.resolve()
+    fake.handle.crash(new Error('command transport failed'))
+    await expect(terminal.done).rejects.toThrow('command transport failed')
+    await cleanup
+  })
+
+  it('keeps a late command rejection authoritative after PTY kill', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.groups = []
+    fake.handle.settleOnSdkKill = false
+    const terminal = await testSpawn(runtime(fake), spec({ graceMs: 1 }), '/runtime/reject-after-kill')
+    terminal.output.on('error', () => {})
+    const cleanup = terminal.terminate()
+    while (fake.handle.sdkKills === 0) await new Promise(resolve => setTimeout(resolve, 0))
+    await Promise.resolve()
+    fake.handle.crash(new Error('late command transport failed'))
+    await expect(terminal.done).rejects.toThrow('late command transport failed')
+    await cleanup
+  })
+
+  it('reports surviving groups, a surviving top-level pid, and transport failure', async () => {
+    const survivor = new FakeTerminalSandbox()
+    survivor.clearOnTerm = false
+    survivor.clearOnKill = false
+    const terminal = await testSpawn(runtime(survivor), spec({ graceMs: 1 }), '/runtime/survivor')
+    await expect(terminal.terminate()).rejects.toThrow('surviving process groups: 123')
+
+    const livePid = new FakeTerminalSandbox()
+    livePid.groups = []
+    livePid.handle.settleOnSdkKill = false
+    const live = await testSpawn(runtime(livePid), spec({ graceMs: 1 }), '/runtime/live-pid')
+    await expect(live.terminate()).rejects.toThrow('surviving pid: 123')
+    livePid.handle.succeed(0)
+    await live.done
+
+    const crashed = new FakeTerminalSandbox()
+    crashed.groups = []
+    const failed = await testSpawn(runtime(crashed), spec(), '/runtime/crashed')
+    const outputError = once(failed.output, 'error')
+    crashed.handle.crash('transport gone')
+    await expect(failed.done).rejects.toEqual('transport gone')
+    await expect(outputError).resolves.toMatchObject([{ message: 'transport gone' }])
+    await failed.terminate()
+  })
+})
+
+describe('E2B subprocess terminal service', () => {
+  async function service(fake = new FakeTerminalSandbox()): Promise<{
+    ctx: Context
+    fiber: Awaited<ReturnType<Context['plugin']>>
+    fake: FakeTerminalSandbox
+  }> {
+    const ctx = new Context()
+    ctx.provide('e2b', runtime(fake))
+    const fiber = await ctx.plugin(E2BSubprocessService)
+    return { ctx, fiber, fake }
+  }
+
+  it('resolves remote executables', async () => {
+    const { ctx, fake } = await service()
+    await expect(ctx.subprocess.resolveExecutable('/bin/bash')).resolves.toBe('/bin/bash')
+    await expect(ctx.subprocess.resolveExecutable('node', { PATH: '/custom/bin' }, new AbortController().signal))
+      .resolves.toBe('/usr/bin/node')
+    fake.resolvedExecutable = 'tools/bin/node\n'
+    await expect(ctx.subprocess.resolveExecutable('node', { PATH: 'tools/bin' }))
+      .resolves.toBe('/workspace/tools/bin/node')
+    const commandOptions = fake.commandOptions.at(-1)
+    expect(commandOptions).toMatchObject({ cwd: '/workspace' })
+    expect(commandOptions?.envs?.HOME).toMatch(/^\/\.dsh-e2b-control-/)
+    expect(commandOptions?.envs).toEqual({ HOME: commandOptions?.envs?.HOME })
+    expect((ctx.e2b)).toBeDefined()
+  })
+
+  it('rejects invalid executable lookup inputs and results', async () => {
+    const { ctx, fake } = await service()
+    await expect(ctx.subprocess.resolveExecutable('')).rejects.toThrow('non-empty')
+    await expect(ctx.subprocess.resolveExecutable('./bin/server')).rejects.toThrow('is a relative path')
+    await expect(ctx.subprocess.resolveExecutable('node_modules/.bin/server')).rejects.toThrow('is a relative path')
+    await expect(ctx.subprocess.resolveExecutable('node', undefined, AbortSignal.abort(new Error('stop'))))
+      .rejects.toThrow('stop')
+    fake.resolvedExecutable = 'node\n'
+    await expect(ctx.subprocess.resolveExecutable('node')).rejects.toThrow('did not resolve')
+    fake.resolvedExecutable = '/one\n/two\n'
+    await expect(ctx.subprocess.resolveExecutable('node')).rejects.toThrow('did not resolve')
+  })
+
+  it('rejects a non-positive poll cadence at load', async () => {
+    const ctx = new Context()
+    ctx.provide('e2b', runtime(new FakeTerminalSandbox()))
+    await expect(ctx.plugin(E2BSubprocessService, { pollMs: 0 }))
+      .rejects.toThrow('pollMs must be a positive safe integer')
+    const explicit = await ctx.plugin(E2BSubprocessService, { pollMs: 5 })
+    await explicit.dispose()
+  })
+
+  it('owns live terminals through service disposal', async () => {
+    const { ctx, fiber, fake } = await service()
+    const terminal = await ctx.subprocess.spawnTerminal(spec({ signal: new AbortController().signal }))
+    await fiber.dispose()
+    await expect(terminal.done).resolves.toEqual({ exitCode: null, signal: 'SIGTERM' })
+    expect(fake.handle.disconnects).toBe(1)
+  })
+
+  it('joins and rejects terminal setup that completes during service disposal', async () => {
+    const fake = new FakeTerminalSandbox()
+    const { ctx, fiber } = await service(fake)
+    let disposing: Promise<void> | undefined
+    fake.afterSessionLookup = () => {
+      fake.afterSessionLookup = undefined
+      queueMicrotask(() => {
+        queueMicrotask(() => { disposing = fiber.dispose() })
+      })
+    }
+    const subprocess = ctx.subprocess
+    const spawning = ctx.subprocess.spawnTerminal(spec())
+    const rejected = expect(spawning).rejects.toThrow('service disposed during terminal setup')
+    await vi.waitFor(() => { expect(disposing).toBeDefined() })
+    await expect(subprocess.spawnTerminal(spec())).rejects.toThrow('service is disposing')
+
+    await rejected
+    await disposing
+    expect(fake.groups).toEqual([])
+    expect(fake.handle.disconnects).toBe(1)
+    expect(fake.removed.some(path => path.includes('/terminals/'))).toBe(true)
+  })
+
+  it('aborts and rolls back terminal setup that cannot publish its output boundary during disposal', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.emitOutputMarker = false
+    const { ctx, fiber } = await service(fake)
+    const spawning = ctx.subprocess.spawnTerminal(spec())
+    const rejected = expect(spawning).rejects.toThrow('service disposed during terminal setup')
+    await vi.waitFor(() => { expect(fake.inputs).toHaveLength(1) })
+
+    await fiber.dispose()
+    await rejected
+    expect(fake.groups).toEqual([])
+    expect(fake.handle.disconnects).toBe(1)
+  })
+
+  it('owns and cancels terminal state-directory creation during disposal', async () => {
+    const fake = new FakeTerminalSandbox()
+    fake.makeDirRequest = async (signal) => {
+      await new Promise<never>((_resolve, reject) => {
+        const onAbort = (): void => {
+          const reason: unknown = signal?.reason
+          reject(reason instanceof Error ? reason : new Error(String(reason)))
+        }
+        signal?.addEventListener('abort', onAbort, { once: true })
+        if (signal?.aborted === true) onAbort()
+      })
+    }
+    const { ctx, fiber } = await service(fake)
+    const spawning = ctx.subprocess.spawnTerminal(spec())
+    const rejected = expect(spawning).rejects.toThrow('service disposed during terminal setup')
+    await vi.waitFor(() => { expect(fake.directories.some(path => path.includes('/terminals/'))).toBe(true) })
+
+    await fiber.dispose()
+    await rejected
+    expect(fake.removed.some(path => path.includes('/terminals/'))).toBe(true)
+    expect(fake.createOptions).toBeUndefined()
+  })
+
+  it('releases naturally settled terminals and validates terminal requests', async () => {
+    const { ctx, fiber, fake } = await service()
+    for (const request of [
+      spec({ argv: [] }),
+      spec({ signal: AbortSignal.abort(new Error('cancelled')) }),
+    ]) {
+      await expect(ctx.subprocess.spawnTerminal(request)).rejects.toThrow()
+    }
+
+    fake.groups = []
+    const terminal = await ctx.subprocess.spawnTerminal(spec())
+    fake.handle.succeed(0)
+    await terminal.done
+    await terminal.terminate()
+    const signals = fake.commands.filter(command => command.startsWith('kill -')).length
+    await fiber.dispose()
+    expect(fake.commands.filter(command => command.startsWith('kill -'))).toHaveLength(signals)
+  })
+
+  it('contains a failed automatic terminal release until service disposal retries it', async () => {
+    const { fiber, fake } = await service()
+    fake.clearOnTerm = false
+    fake.clearOnKill = false
+    const terminal = await (fiber.ctx).subprocess.spawnTerminal(spec({ graceMs: 1 }))
+    fake.handle.succeed(0)
+    await terminal.done
+    await new Promise(resolve => setTimeout(resolve, 10))
+    expect(fake.commands).toContain('kill -KILL -- -123')
+
+    fake.groups = []
+    await fiber.dispose()
+    await expect(terminal.terminate()).resolves.toBeUndefined()
+  })
+})

packages/e2b/subprocess-e2b/tsconfig.json

@@ -0,0 +1,30 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../subprocess/subprocess"
+    },
+    {
+      "path": "../../support/invariants"
+    },
+    {
+      "path": "../../util/timeout"
+    },
+    {
+      "path": "../e2b"
+    }
+  ]
+}

packages/fs/README.i18n.yaml

@@ -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/fs/README.md
-README.md: 108d7d862a1dc6307268e2a93fa00789c952e440
-README.zh.md: 8b037cc3192bf6ceb0f0671d62911a8e035db24c
+README.md: b15012e882b60847e1ad22edf08d1202ba64fe5b
+README.zh.md: 628f6c74894bc67559d49f7cf5d1378d0ece2382

packages/fs/README.md

@@ -2,16 +2,20 @@
 
 English | [中文](README.zh.md)
 
-The filesystem capability family: provider seam, interchangeable backends, policy, and model-facing tools. All **product** packages.
+The filesystem stack: a provider seam (execution-world paths, bounded text IO, and atomic mutation with an optional version guard), a local implementation, a policy gate plugin (observed-state + read-before-edit + version-guarded write/edit), the model-facing file tools + executor, and the bash-backed discovery tools. All **product** packages.
 
 | Package | Role | ctx key |
 |---|---|---|
-| [`fs/`](fs/README.md) | Filesystem provider seam and policy-event vocabulary | `ctx.fs` |
-| [`fs-local/`](fs-local/README.md) | Local-filesystem backend | registers `ctx.fs` |
-| [`fs-sandbox/`](fs-sandbox/README.md) | Sandbox-enforcing backend | registers `ctx.fs` |
-| [`fs-policy/`](fs-policy/README.md) | Observed-state and mutation policy | `fs/*` listeners |
-| [`tool-fs/`](tool-fs/README.md) | Model-facing file tools | registers on `ctx.tools` |
-| [`tool-fs-search/`](tool-fs-search/README.md) | Process-backed discovery tools | registers on `ctx.tools` |
-| [`tool-str-replace-editor/`](tool-str-replace-editor/README.md) | Model-facing string-replacement editor | registers on `ctx.tools` |
+| `fs/` | Provider seam: canonical process paths/file URIs/containment, text IO, and atomic mutation primitives; owns the `fs/*` policy events | `ctx.fs` |
+| `fs-local/` | Local-filesystem `FileSystem` implementation | (registers `ctx.fs`) |
+| [`e2b/fs-e2b`](../e2b/fs-e2b/README.md) | E2B-backed `FileSystem` implementation sharing the remote runtime owned by `ctx.e2b` | (registers `ctx.fs`) |
+| `fs-sandbox/` | Sandbox-enforcing `FileSystem`: extends `fs-local` and fences write/edit by the per-call mode + workspace root policy (read-only denies, workspace-write contains to the session workspace + temp roots), reads pass through | (registers `ctx.fs`) |
+| `fs-policy/` | Policy gate plugin: observed-state + read-before-edit + version-guarded write/edit, via the `fs/*` event gate | (no service — `fs/*` listeners) |
+| `tool-fs/` | Model-facing `read`/`write`/`edit` tools AND the executor (reads via `ctx.fs`, owns read windowing, dispatches `fs/*`); preserves filesystem semantics for session-cwd-relative paths and advertises sandbox escalation fields when the mounted `ctx.fs` confines | (registers on `ctx.tools`) |
+| `tool-fs-search/` | Model-facing `glob`/`grep` discovery tools when `rg` is available on the bash executor `PATH`, backed by fixed ripgrep commands through `ctx.bash`, NOT by `ctx.fs` provider methods | (registers on `ctx.tools`) |
 
-Backends replace one another behind `ctx.fs`; policy and tools consume the seam independently. Discovery remains process-backed instead of expanding the provider contract. Child READMEs own containment, mutation, schema, and timeout details.
+The interface lives at `fs/fs/`. A sandboxed, remote, or project-scoped filesystem backend can replace `fs-local` without touching the seam, the policy gate, or the model-facing tool schemas: `fs-sandbox` provides an in-process path fence over the shared sandbox mode ([decision](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)), while `fs-e2b` places file state in the remote execution world shared with the E2B subprocess provider ([decision](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md)). The policy (`fs-policy/`) is a plugin that participates only through the `fs/*` event gate, not a service the tool injects — so dropping it gracefully loses the policy and leaves the unconstrained bare provider rather than breaking the tool. A deployment that loads `tool-fs/` is expected to also load it. The mode fence and the read-before-edit gate are orthogonal and compose. Discovery (`tool-fs-search/`) deliberately does NOT extend the provider seam: search is a process-backed `rg` workflow on the bash executor, so filesystem backends stay free of a universal search contract; its tools register only when that executor can find `rg`, and its results are follow-up-readable when the bash workdir and the `read` root are the same workspace (the co-located deployment its README documents).
+
+## No timeouts on file IO
+
+`read`/`write`/`edit` take **no** `timeoutMs`, and the provider seam arms no deadline — unlike bash and web (which consume [`@deepseek-ai/dsh-timeout`](../util/timeout/README.md)) and the bash-backed `glob`/`grep` (whose declared `timeoutMs` is enforced by `@deepseek-ai/dsh-timeout-policy`): those are process-backed, where a deadline can really kill the work. A local syscall is best-effort-abortable at most: a timeout could not force an in-progress `fsync`/`rename` to stop, so a deadline here would be a knob that cannot deliver on its promise. Adding one would also be an implicit default in the exact place explicit-over-implicit forbids. Both reference agents (Claude Code, Codex) leave file IO untimed for the same reason; cancellation still propagates through the tool-execution signal for best-effort abort at syscall boundaries.

packages/fs/README.zh.md

@@ -1,17 +1,21 @@
-# fs/ - 文件系统能力家族
+# fs/：文件系统能力族
 
 [English](README.md) | 中文
 
-文件系统能力家族：提供方 seam、可互换后端、策略和面向模型工具。这些全是**产品**包。
+文件系统栈包括：提供方 seam（执行世界路径、有界文本 I/O 与带可选版本防护的原子变更）、本地实现、政策门禁插件（已观察状态、编辑前读取、版本防护的写入/编辑）、面向模型的文件工具与执行器，以及基于 bash 的发现工具。全部都是**产品** 包。
 
-| 包 | 职责 | ctx key |
+| 包 | 角色 | ctx 键 |
 |---|---|---|
-| [`fs/`](fs/README.md) | 文件系统提供方 seam 和策略事件词汇 | `ctx.fs` |
-| [`fs-local/`](fs-local/README.md) | 本地文件系统后端 | 注册 `ctx.fs` |
-| [`fs-sandbox/`](fs-sandbox/README.md) | 强制执行沙箱的后端 | 注册 `ctx.fs` |
-| [`fs-policy/`](fs-policy/README.md) | 已观察状态和修改策略 | `fs/*` 监听器 |
-| [`tool-fs/`](tool-fs/README.md) | 面向模型的文件工具 | 注册到 `ctx.tools` |
-| [`tool-fs-search/`](tool-fs-search/README.md) | 基于进程的发现工具 | 注册到 `ctx.tools` |
-| [`tool-str-replace-editor/`](tool-str-replace-editor/README.md) | 面向模型的字符串替换编辑器 | 注册到 `ctx.tools` |
+| `fs/` | 提供方 seam：规范化进程路径、文件 URI 与包含关系、文本 I/O 和原子变更原语；拥有 `fs/*` 政策事件 | `ctx.fs` |
+| `fs-local/` | 本地文件系统 `FileSystem` 实现 | （注册 `ctx.fs`） |
+| [`e2b/fs-e2b`](../e2b/fs-e2b/README.md) | 以 E2B 为后端的 `FileSystem` 实现，共享由 `ctx.e2b` 拥有的远程运行时 | （注册 `ctx.fs`） |
+| `fs-sandbox/` | 强制沙箱的 `FileSystem`：扩展 `fs-local`，并按每次调用的模式与工作区根政策约束写入/编辑（只读模式拒绝，工作区写入模式限制在会话工作区与临时根目录内）；读取直接通过 | （注册 `ctx.fs`） |
+| `fs-policy/` | 政策门禁插件：通过 `fs/*` 事件门禁提供已观察状态、编辑前读取和版本防护的写入/编辑 | （无服务，仅有 `fs/*` 监听器） |
+| `tool-fs/` | 面向模型的 `read`/`write`/`edit` 工具以及执行器（通过 `ctx.fs` 读取，拥有读取窗口逻辑，分派 `fs/*`）；为会话 cwd 相对路径保留文件系统语义，并在已挂载的 `ctx.fs` 实施约束时声明沙箱升级字段 | （注册到 `ctx.tools`） |
+| `tool-fs-search/` | 面向模型的 `glob`/`grep` 发现工具；当 `rg` 位于 bash 执行器 `PATH` 上时注册，通过 `ctx.bash` 运行固定 ripgrep 命令，而不是使用 `ctx.fs` 提供方方法 | （注册到 `ctx.tools`） |
 
-后端可在 `ctx.fs` 后互相替换；策略和工具独立消费该 seam。发现功能仍由进程提供，不扩展提供方契约。子 README 负责围堵、修改、schema 和超时细节。
+接口位于 `fs/fs/`。沙箱化、远程或限定项目作用域的文件系统后端可以替换 `fs-local`，而无需更改 seam、政策门禁或面向模型的工具 schema：`fs-sandbox` 基于共享沙箱模式提供进程内路径围栏（[决策](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)），而 `fs-e2b` 则把文件状态置于与 E2B 进程管理提供方共享的远程执行世界中（[决策](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md)）。政策（`fs-policy/`）是一个只通过 `fs/*` 事件门禁参与的插件，不是工具注入的服务；因此移除它会平稳失去政策，留下不受约束的裸提供方，而不会破坏工具。加载 `tool-fs/` 的部署也应加载该插件。模式围栏与编辑前读取门禁彼此正交，可以组合。发现（`tool-fs-search/`）有意不扩展提供方 seam：搜索是在 bash 执行器上运行 `rg`、由进程支持的工作流，因此文件系统后端无需承担通用搜索契约；只有当执行器能找到 `rg` 时，其工具才会注册。如果 bash 工作目录与 `read` 根目录是同一工作区，结果就能继续读取，这也是其 README 所述的共置部署。
+
+## 文件 I/O 不设超时
+
+`read`/`write`/`edit` **不** 接受 `timeoutMs`，提供方 seam 也不启动 deadline。这与 bash 和 web（两者使用 [`@deepseek-ai/dsh-timeout`](../util/timeout/README.md)）及基于 bash 的 `glob`/`grep` 不同（它们声明的 `timeoutMs` 由 `@deepseek-ai/dsh-timeout-policy` 强制执行）：这些工作由进程支持，deadline 可以实际终止工作。本地系统调用至多只能尽力中止：超时无法强制正在进行的 `fsync`/`rename` 停止，因此这里的 deadline 会成为无法兑现承诺的配置项。在此添加 deadline 还会在「显式优于隐式」明确禁止的地方引入隐式默认值。两个参考 agent（Claude Code、Codex）出于同一原因都不为文件 I/O 计时；取消仍通过工具执行信号传播，在系统调用边界尽力中止。

packages/fs/fs-local/README.i18n.yaml

@@ -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/fs/fs-local/README.md
-README.md: 6d344fa3fef7f6bda6c0daa50184661156a925a7
-README.zh.md: 4c94de64561d805684f91f02d5b0dfc375f0d04f
+README.md: 2e934298ceff75440357b0742770010c8b1c3904
+README.zh.md: 14f4867ce0f9eaae2a1dea98dbd7d401c98d4535

packages/fs/fs-local/README.md

@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The **local-filesystem implementation** of the `ctx.fs` provider seam ([`@deepseek-ai/dsh-fs`](../fs)). Backs the eight `FileSystem` primitives with the host filesystem; loading it as a plugin populates `ctx.fs`.
+The **local-filesystem implementation** of the `ctx.fs` provider seam ([`@deepseek-ai/dsh-fs`](../fs)). Backs the eleven `FileSystem` primitives with the host filesystem; loading it as a plugin populates `ctx.fs`.
 
 ```ts ignore-check
 import { LocalFileSystem } from '@deepseek-ai/dsh-fs-local'
@@ -15,8 +15,9 @@ await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
 ## Behavior
 
 - **`resolve(path, opts?)`** — a relative `path` resolves against `opts.cwd` when the caller supplies one (the model-facing tools pass the calling agent's session cwd — see [the per-session cwd Agent Note](../../../.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.md)), else `config.cwd` (default `process.cwd()`); an absolute `path` ignores both. `opts.signal` is checked before and after local resolution, while a remote sibling backend may use it to abort its round-trip. The `targetKey` is the file's `realpath`, so two input paths reaching the same file through symlinks share one identity, and writes/edits land on the link target (preserving the link). A not-yet-existing path uses the realpathed parent directory plus basename when the parent exists; only an unresolvable parent falls back to the absolute path. `displayPath` is the absolute (un-resolved) path.
+- **Execution-world coordinates** — `processPath` exposes the target's canonical host path, `fileUrl` encodes that path through Node's platform-aware URL conversion, and `contains` uses platform path semantics to test identity or descendant containment without consumers parsing `targetKey`.
 - **`stat` / `lstat`** — return target metadata or `undefined` when absent. `stat` reports `FsInfo` for an already resolved target (`version` = an opaque token derived from bigint `dev:ino:size:mtimeNs:ctimeNs`, `type` of `file`/`directory`/`other`, byte `size`); path-shaped `lstat` reports `FsPathInfo` without following the final symlink and can therefore return `symlink`. Both check cancellation before and after their asynchronous metadata probe, so an abort that lands in flight reports `FS_ABORTED` rather than stale absence.
-- **`readText` / `streamText`** — UTF-8 only. `readText` reads the whole file; `streamText` streams it in chunks (cross-chunk decoding) so a huge file never has to be held whole in memory. Both reject invalid UTF-8 and NUL-byte binary samples (`FS_NOT_TEXT`) and non-regular targets. The `read` tool (`@deepseek-ai/dsh-tool-fs`) decides which to call by size and owns the line windowing.
+- **`readText` / `streamText`** — UTF-8 only. `readText` reads the whole file; `streamText` decodes chunks so a huge file need not be held whole in memory and consumers can enforce their own retention bounds. Both reject invalid UTF-8 and NUL-byte binary samples (`FS_NOT_TEXT`) and non-regular targets. The `read` tool (`@deepseek-ai/dsh-tool-fs`) owns line windowing.
 - **`listDir`** — lists one directory level in stable `name.localeCompare()` order. Each entry carries the child basename, type, resolved child target (`displayPath` under the listed directory, `targetKey` as the realpath identity), and cheap stat metadata (`version`, plus `size` for regular files). It never opens or decodes file contents. Missing targets report `FS_NOT_FOUND`, file/special-file targets report `FS_NOT_DIRECTORY`, aborted calls report `FS_ABORTED`, permission failures report `FS_PERMISSION_DENIED`, and other listing or child metadata I/O failures report `FS_IO_ERROR`. Broken/disappeared children are returned as `other` without metadata, but permission/IO failures while resolving a child fail the whole listing with a structured `FsError`.
 - **`writeText`** — atomic: writes to a temp file opened exclusively (`wx`, `0o600`) inside a randomly-named private staging dir (`0o700`) next to the target, fsyncs, then renames over the target. An existing file's mode is preserved, while new files default to `0o600`; on Windows a new file inherits the destination directory's DACL, while replacement copies the target DACL onto the empty temp before writing and publishes through `ReplaceFileW` so the original access policy survives ([Windows DACL preservation Agent Note](../../../.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)). The `expected` guard is OPTIONAL: omitting it unconditionally creates-or-overwrites; `createIfAbsent` creates a missing target and rejects an existing one (`FS_NOT_OBSERVED`); `replaceIfVersion` replaces only at the observed version (a missing target or mismatch is `FS_STALE_VERSION`).
 - **`editText`** — atomic literal read-modify-write over the same primitive, serialized per target by a mutation lock. The `expected` guard is OPTIONAL: when supplied it verifies the version BEFORE literal matching (a stale edit reports `FS_STALE_VERSION`, never `FS_EDIT_NOT_FOUND`/`FS_AMBIGUOUS_EDIT` against newer content); omitting it edits the current content unconditionally. A missing target reports `FS_STALE_VERSION` either way. LF-normalizes for matching, restores the file's dominant CRLF/LF style, and rejects empty `oldString` / zero matches (`FS_EDIT_NOT_FOUND`) or ambiguous multi-matches without `replace_all` (`FS_AMBIGUOUS_EDIT`).
@@ -35,7 +36,7 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 
 - **`config.cwd` is not a sandbox** — it is a resolution default, not containment: absolute paths and `..` escape it. Enforce containment with a stricter `ctx.fs` backend or a permission plugin on the `tools/execute` waterfall ([capability-seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md#consequences)).
 - **An overwrite reads the whole prior file into memory** — solely as the UI diff basis; bounding that pre-read above a size threshold is deferred (`TODO(overwrite-diff-bound)`).
-- **Version tokens are `mtimeMs:size`** — an external change that preserves both within the filesystem's timestamp granularity defeats the stale guard.
+- **Version tokens depend on filesystem metadata** — they combine device, inode, size, nanosecond mtime, and nanosecond ctime; a storage layer that cannot update any of those facts for a rewrite can still defeat the stale guard.
 - **`editText` holds the whole file (plus the edited copy) in memory** — streaming exists only on the read path.
 - **Binary detection is asymmetric** — reads NUL-sample only the first 8192 bytes while edits scan the whole buffer, so a file with a late NUL reads fine but rejects edits.
 - **The per-target mutation lock is in-process only** — a writer in another process is caught only by the optional version guard, never serialized.

packages/fs/fs-local/README.zh.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-`ctx.fs` 提供方 seam（[`@deepseek-ai/dsh-fs`](../fs)）的**本地文件系统实现**。它使用宿主文件系统支持八个 `FileSystem` 原语；将其作为插件加载会填充 `ctx.fs`。
+`ctx.fs` 提供方 seam（[`@deepseek-ai/dsh-fs`](../fs)）的**本地文件系统实现**。它使用宿主文件系统支持十一个 `FileSystem` 原语；将其作为插件加载会填充 `ctx.fs`。
 
 ```ts ignore-check
 import { LocalFileSystem } from '@deepseek-ai/dsh-fs-local'
@@ -15,27 +15,28 @@ await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
 ## 行为
 
 - **`resolve(path, opts?)`**：相对 `path` 在调用方提供 `opts.cwd` 时以该值为基准解析（面向模型的工具会传入调用 agent（智能体）的会话 cwd；见[每会话 cwd Agent Note](../../../.agents/notes/implemented/architecture/2026-07-02-fs-per-session-cwd.md)），否则以 `config.cwd` 为基准（默认 `process.cwd()`）；绝对 `path` 会忽略两者。`opts.signal` 会在本地解析前后检查，远程同级后端则可以用它中止往返。`targetKey` 是文件的 `realpath`，因此经符号链接到达同一文件的两个输入路径会共享一个身份，写入/编辑落在链接目标上，同时保留链接。尚不存在的路径在父目录存在时使用 realpath 后的父目录加 basename；只有父目录无法解析时才回退到绝对路径。`displayPath` 是绝对但未经解析的路径。
-- **`stat` / `lstat`**：返回目标元数据；目标不存在时返回 `undefined`。`stat` 为已解析目标报告 `FsInfo`（`version` 是由 bigint `dev:ino:size:mtimeNs:ctimeNs` 派生的不透明 token，`type` 为 `file`/`directory`/`other`，`size` 以字节计）；路径形态的 `lstat` 不跟随最后一个符号链接，报告 `FsPathInfo`，因此可以返回 `symlink`。两者都会在异步元数据探测前后检查取消，因此异步探测进行期间发生的中止会报告 `FS_ABORTED`，而非已失效的「不存在」结果。
-- **`readText` / `streamText`**：只支持 UTF-8。`readText` 读取整个文件；`streamText` 按分片流式读取（跨分片解码），因此超大文件无需整体保存在内存中。两者都会拒绝无效 UTF-8、包含 NUL 字节的二进制样本（`FS_NOT_TEXT`）以及非普通文件目标。`read` 工具（`@deepseek-ai/dsh-tool-fs`）按大小决定调用哪个方法，并负责行窗口逻辑。
+- **执行世界坐标**：`processPath` 公开目标的规范化宿主路径，`fileUrl` 通过 Node 的平台感知 URL 转换对该路径编码，`contains` 则使用平台路径语义检查身份相等或后代包含关系，消费方无需解析 `targetKey`。
+- **`stat` / `lstat`**：返回目标元数据；目标不存在时返回 `undefined`。`stat` 为已解析目标报告 `FsInfo`（`version` 是由 bigint `dev:ino:size:mtimeNs:ctimeNs` 派生的不透明 token，`type` 为 `file`/`directory`/`other`，`size` 以字节计）；路径形态的 `lstat` 不跟随最后一个符号链接，报告 `FsPathInfo`，因此可以返回 `symlink`。两者都会在异步元数据探测前后检查取消，因此飞行中的中止会报告 `FS_ABORTED`，而非陈旧的不存在结果。
+- **`readText` / `streamText`**：只支持 UTF-8。`readText` 读取整个文件；`streamText` 按分片解码，因此超大文件无需整体保存在内存中，消费方也可以执行各自的保留上限。两者都会拒绝无效 UTF-8、包含 NUL 字节的二进制样本（`FS_NOT_TEXT`）以及非普通文件目标。`read` 工具（`@deepseek-ai/dsh-tool-fs`）拥有行窗口逻辑。
 - **`listDir`**：按稳定的 `name.localeCompare()` 顺序列出一层目录。每个条目携带子项 basename、类型、解析后的子目标（`displayPath` 位于所列目录下，`targetKey` 是 realpath 身份）和低成本 stat 元数据（`version`，普通文件另有 `size`）。它绝不会打开或解码文件内容。缺失目标报告 `FS_NOT_FOUND`，文件/特殊文件目标报告 `FS_NOT_DIRECTORY`，已中止调用报告 `FS_ABORTED`，权限失败报告 `FS_PERMISSION_DENIED`，其他列出或子项元数据 I/O 失败报告 `FS_IO_ERROR`。损坏/消失的子项以无元数据的 `other` 返回，但解析子项时出现权限/I/O 失败会让整个列表以结构化 `FsError` 失败。
-- **`writeText`**：原子写入。它会向排他打开的临时文件（`wx`、`0o600`）写入；该文件位于目标旁随机命名的私有暂存目录（`0o700`）内。完成写入和 fsync 后，以 rename 覆盖目标。现有文件的 mode 会保留，新文件默认为 `0o600`；Windows 上的新文件继承目标目录的 DACL，而替换会在写入前把目标 DACL 复制到空临时文件，并通过 `ReplaceFileW` 发布，使原访问策略得以保留（见 [Windows DACL 保留 Agent Note](../../../.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)）。`expected` 防护是可选（OPTIONAL）的：省略时无条件创建或覆盖；`createIfAbsent` 创建缺失目标并拒绝现有目标（`FS_NOT_OBSERVED`）；`replaceIfVersion` 只在观察到的版本上替换（目标缺失或版本不匹配均为 `FS_STALE_VERSION`）。
-- **`editText`**：在同一原语之上执行原子式的字面量读取-修改-写入，并通过变更锁按目标串行化。`expected` 防护是可选（OPTIONAL）的：提供时，会在字面量匹配之前校验版本（陈旧编辑报告 `FS_STALE_VERSION`，绝不会针对较新内容报告 `FS_EDIT_NOT_FOUND`/`FS_AMBIGUOUS_EDIT`）；省略时，无条件编辑当前内容。无论哪种情况，目标缺失都报告 `FS_STALE_VERSION`。匹配时规范化为 LF，随后恢复文件主要的 CRLF/LF 风格；空 `oldString` / 零匹配报告 `FS_EDIT_NOT_FOUND`，未设置 `replace_all` 的多个匹配则报告 `FS_AMBIGUOUS_EDIT`。
+- **`writeText`**：原子写入。它会向排他打开的临时文件（`wx`、`0o600`）写入；该文件位于目标旁随机命名的私有暂存目录（`0o700`）内。完成写入和 fsync 后，以 rename 覆盖目标。现有文件的 mode 会保留，新文件默认为 `0o600`；Windows 上的新文件继承目标目录的 DACL，而替换会在写入前把目标 DACL 复制到空临时文件，并通过 `ReplaceFileW` 发布，使原访问政策得以保留（见 [Windows DACL 保留 Agent Note](../../../.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md)）。`expected` 防护是可选的：省略时无条件创建或覆盖；`createIfAbsent` 创建缺失目标并拒绝现有目标（`FS_NOT_OBSERVED`）；`replaceIfVersion` 只在观察到的版本上替换（目标缺失或版本不匹配均为 `FS_STALE_VERSION`）。
+- **`editText`**：在同一原语之上依次执行原子的字面量读取、修改和写入，并通过变更锁按目标串行化。`expected` 防护是可选的：提供时，会在字面量匹配之前校验版本（陈旧编辑报告 `FS_STALE_VERSION`，绝不会针对较新内容报告 `FS_EDIT_NOT_FOUND`/`FS_AMBIGUOUS_EDIT`）；省略时，无条件编辑当前内容。无论哪种情况，目标缺失都报告 `FS_STALE_VERSION`。匹配时规范化为 LF，随后恢复文件主要的 CRLF/LF 风格；空 `oldString` / 零匹配报告 `FS_EDIT_NOT_FOUND`，未设置 `replace_all` 的多个匹配则报告 `FS_AMBIGUOUS_EDIT`。
 
-包根目录的 SDK 接口包含默认/具名 `LocalFileSystem` 类和 `Config`。原始 I/O 位于 `src/fsio.ts`（不依赖 Cordis，单独进行单元测试）；`src/index.ts` 是轻量服务接线。
+包根 SDK 接口包含默认/具名 `LocalFileSystem` 类和 `Config`。原始 I/O 位于 `src/fsio.ts`（不依赖 Cordis，单独进行单元测试）；`src/index.ts` 是轻量服务接线。
 
 ## 模型体验
 
-通过 [`dsh-tool-fs`](../tool-fs/README.md) 间接产生影响；该消费方在有上限的保留结果中渲染本提供方带行窗口的 UTF-8 内容、变更确认和精确提供方消息，而版本、原子写入机制和目录元数据仍属内部实现。
+通过 [`dsh-tool-fs`](../tool-fs/README.md) 间接产生影响；该消费方把本提供方带行窗口的 UTF-8 内容、变更确认和精确提供方消息渲染为有上限且保留的结果，而版本、原子写入机制和目录元数据保持内部可见。
 
 #### KV Cache 影响
 
 不会直接使缓存失效；具名消费方负责请求前缀的任何变化。
 
-## 已知限制与暂缓事项
+## 已知限制与延期工作
 
 - **`config.cwd` 不是沙箱**：它是解析默认值，而非约束；绝对路径和 `..` 可以逃逸。请使用更严格的 `ctx.fs` 后端或 `tools/execute` waterfall（瀑布式事件）上的权限插件实施约束（见[能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md#consequences)）。
 - **覆盖会把整个旧文件读入内存**：只用于 UI diff；在大小阈值之上限制这次预读取的工作延期处理（`TODO(overwrite-diff-bound)`）。
-- **版本 token 是 `mtimeMs:size`**：如果外部变更在文件系统时间戳粒度内保持两者不变，就能绕过陈旧防护。
+- **版本 token 依赖文件系统元数据**：它们组合设备、inode、大小、纳秒级 mtime 和纳秒级 ctime；如果存储层在重写时无法更新其中任何一项事实，仍可能绕过陈旧防护。
 - **`editText` 会把整个文件及编辑后的副本保存在内存中**：只有读取路径支持流式处理。
 - **二进制检测不对称**：读取只对前 8192 字节执行 NUL 采样，编辑则扫描整个 buffer，因此 NUL 出现在后部的文件可以读取，但编辑会被拒绝。
 - **每目标变更锁仅限进程内**：其他进程中的写入方只会被可选版本防护发现，绝不会被串行化。

packages/fs/fs-local/src/index.ts

@@ -5,7 +5,8 @@
  */
 
 import { Context } from 'cordis'
-import { resolve } from 'node:path'
+import { isAbsolute, relative, resolve, sep } from 'node:path'
+import { pathToFileURL } from 'node:url'
 import z from 'schemastery'
 import { FileSystem, FsError, FsVersion } from '@deepseek-ai/dsh-fs'
 import type {
@@ -90,6 +91,19 @@ export class LocalFileSystem extends FileSystem {
     return { targetKey: local.targetKey, displayPath: local.displayPath }
   }
 
+  override processPath(target: FsTarget): string {
+    return String(target.targetKey)
+  }
+
+  override fileUrl(target: FsTarget): string {
+    return pathToFileURL(this.processPath(target)).href
+  }
+
+  override contains(parent: FsTarget, child: FsTarget): boolean {
+    const path = relative(this.processPath(parent), this.processPath(child))
+    return path === '' || (path !== '..' && !path.startsWith(`..${sep}`) && !isAbsolute(path))
+  }
+
   override async stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined> {
     if (signal?.aborted) throw new FsError('stat aborted', 'FS_ABORTED')
     const info = await probe(target.targetKey)

packages/fs/fs-local/tests/filesystem.spec.ts

@@ -10,6 +10,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { mkdir, mkdtemp, readFile, realpath, rm, stat, symlink, unlink, utimes, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
 import { Context } from 'cordis'
 import { LocalFileSystem } from '@deepseek-ai/dsh-fs-local'
 import { FsVersion } from '@deepseek-ai/dsh-fs'
@@ -85,6 +86,20 @@ describe('resolve', () => {
 
     await expect(pending).rejects.toMatchObject({ code: 'FS_ABORTED' })
   })
+
+  it('projects process paths, file URLs, and canonical containment', async () => {
+    await mkdir(join(dir, 'nested'))
+    await writeFile(join(dir, 'nested', 'file.txt'), 'text')
+    const root = await fs.resolve('.')
+    const child = await fs.resolve('nested/file.txt')
+    const outside = await fs.resolve('..')
+
+    expect(fs.processPath(child)).toBe(await realpath(join(dir, 'nested', 'file.txt')))
+    expect(fs.fileUrl(child)).toBe(pathToFileURL(await realpath(join(dir, 'nested', 'file.txt'))).href)
+    expect(fs.contains(root, root)).toBe(true)
+    expect(fs.contains(root, child)).toBe(true)
+    expect(fs.contains(root, outside)).toBe(false)
+  })
 })
 
 describe('stat', () => {

packages/fs/fs/README.i18n.yaml

@@ -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/fs/fs/README.md
-README.md: 6c80cc22f6f28e792c3458df3390b241b51d8202
-README.zh.md: 4772d799221efbfff9667cbc8b9e1df6af07dcff
+README.md: bf1dd1c1eb65146258cd64e450749845522e7057
+README.zh.md: f3fcc0c3794b972233dc418e93bdd80b1cc8570a

packages/fs/fs/README.md

@@ -2,21 +2,33 @@
 
 English | [中文](README.zh.md)
 
-The **filesystem provider seam**: an abstract `FileSystem` service (`ctx.fs`) defining the storage primitives a backend provides — resolve a path, stat metadata, no-follow path metadata, read/stream text, list directories, write atomically, and apply a literal edit — without saying HOW. Both mutations take their version guard **optionally**, so `ctx.fs` on its own is a complete, unconstrained text-storage seam. This package also owns the `fs/*` policy event vocabulary the tool dispatches and the policy plugin listens for.
+The **filesystem provider seam**: an abstract `FileSystem` service (`ctx.fs`) defining the storage primitives in one execution world — resolve paths, expose canonical process paths and file URIs, test containment, read whole or streaming text, inspect/list metadata, write atomically, and apply a literal edit — without saying HOW. Both mutations take their version guard **optionally**, so `ctx.fs` on its own is a complete, unconstrained text-storage seam. This package also owns the `fs/*` policy event vocabulary the tool dispatches and the policy plugin listens for.
 
-This package is the provider-seam layer of the [filesystem family](../README.md). The [tool](../tool-fs/README.md), [policy](../fs-policy/README.md), and [local](../fs-local/README.md) and [sandboxed](../fs-sandbox/README.md) backends remain separate consumers and implementations; the capability-seam decisions own the split ([foundation](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md), [filesystem seam](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md), [provider split](../../../.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md), [event gate](../../../.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md)).
+This package is the provider-seam layer of the four-layer filesystem stack, split so each concern can evolve (and be swapped) independently (see [the capability-seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md), [the filesystem capability-seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md), [the split-the-filesystem-seam Agent Note](../../../.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md), and [the file-context event-gate Agent Note](../../../.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md)):
+
+| Layer | Package | Role |
+|---|---|---|
+| tool / executor | `@deepseek-ai/dsh-tool-fs` | model-facing `read`/`write`/`edit` schemas + read windowing + text rendering; reads/writes/edits via `ctx.fs`, dispatches the `fs/*` events |
+| policy | `@deepseek-ai/dsh-fs-policy` | observed-state + read-before-edit + version-guarded write/edit, contributed through the `fs/*` event gate (no service) |
+| provider seam | `@deepseek-ai/dsh-fs` (this) | `ctx.fs`: execution-world paths, text IO, and atomic mutation primitives (optional version guard); owns the `fs/*` event vocabulary |
+| provider | `@deepseek-ai/dsh-fs-local` | the host-filesystem implementation |
+
+A future sandboxed, virtual, or remote backend implements this interface and the policy/tool layers don't change.
 
 ## Service API (`ctx.fs`)
 
-A backend subclasses `FileSystem` and implements eight primitives.
+A backend subclasses `FileSystem` and implements eleven primitives.
 
 | Member | Semantics |
 |---|---|
 | `resolve(path, opts?)` | Resolve a path into a stable `FsTarget` (opaque `targetKey`, `displayPath`). `opts.cwd` is the base a relative `path` resolves against (a caller supplies its session workspace; absolute paths ignore it; omitted ⇒ the backend default), while `opts.signal` aborts a backend round-trip. Async — a remote backend may need I/O. The same file via different paths must yield the same `targetKey`. |
+| `processPath(target)` | Return the canonical absolute path that a subprocess in this provider's execution world can open. This is intentionally distinct from opaque `targetKey`. |
+| `fileUrl(target)` | Return the canonical `file:` URI in the execution world's platform syntax. The backend, not the host process, owns encoding. |
+| `contains(parent, child)` | Test canonical identity/descendant containment without exposing or parsing target keys. Both targets come from this provider. |
 | `stat(target, signal?)` | Return `FsInfo` metadata (`version`, `type`, optional `size`), or `undefined` when the target is absent. Never content. |
 | `lstat(path, opts?, signal?)` | Return `FsPathInfo` metadata without following the final path component when it is a symlink. This is path-shaped so consumers can reject repository-owned symlinks before `resolve` follows them into a target. |
 | `readText(target, signal?)` | Read the whole regular text file as one decoded string. Owns regular-file checks, UTF-8 decoding, binary/NUL rejection (`FS_NOT_TEXT`). |
-| `streamText(target, signal?)` | Stream the same text as decoded chunks for large files (cross-chunk UTF-8 decoding stays here). |
+| `streamText(target, signal?)` | Stream the same text as decoded chunks for large files (cross-chunk UTF-8 decoding stays here); consumers that need a byte ceiling enforce it while consuming the stream. |
 | `listDir(target, signal?)` | List direct directory children in stable name order. Returns entry names, entry types, resolved child targets, and cheap metadata (`version`/file `size` when available); never reads file contents. Missing targets throw `FS_NOT_FOUND`, non-directories throw `FS_NOT_DIRECTORY`, permission failures throw `FS_PERMISSION_DENIED`, and other backend I/O failures throw `FS_IO_ERROR`. Broken/disappeared children may be returned as `other` without metadata; child permission/IO failures fail the whole listing with the same structured codes. |
 | `writeText(target, content, expected?, signal?)` | Atomic create/replace. `expected` is OPTIONAL: omit ⇒ unconditional create-or-overwrite; supply an `FsWriteIntent` (`createIfAbsent`/`replaceIfVersion`) to guard. |
 | `editText(target, edit, expected?, signal?)` | Literal edit. `expected` is OPTIONAL: omit ⇒ unconditional edit of the current content; supply `{ version }` to guard (verified BEFORE matching). A missing target reports `FS_STALE_VERSION` either way. Applies and writes atomically — one mutation critical section. |
@@ -37,10 +49,6 @@ This package declares three events (see the generated [events catalog](../../../
 
 `FsTargetKey` / `FsVersion` are branded opaque ids ([the branded-ids Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-branded-ids.md)) — consumers must not parse `targetKey` or interpret `version`; only `displayPath` is for model/UI output. `FsWriteIntent` is the explicit GUARDED write intent (`createIfAbsent` creates a missing target and rejects an existing one with `FS_NOT_OBSERVED`; `replaceIfVersion` replaces only at the observed version, else `FS_STALE_VERSION`); omitting it from `writeText` is the third, unconditional state. `FsPathInfo` is the no-follow metadata shape that can report `symlink`, unlike target-level `FsInfo`. Failures throw `FsError` (extends `HarnessError`, [the structured error taxonomy Agent Note](../../../.agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.md)) carrying a stable `FsErrorCode` (`FS_NOT_FOUND`, `FS_NOT_DIRECTORY`, `FS_NOT_TEXT`, `FS_NOT_REGULAR_FILE`, `FS_PERMISSION_DENIED`, `FS_IO_ERROR`, `FS_STALE_VERSION`, `FS_NOT_OBSERVED`, `FS_AMBIGUOUS_EDIT`, `FS_EDIT_NOT_FOUND`, `FS_ABORTED`); the tool registry surfaces `{ name, code }` on `isError` results. See `src/types.ts` for the full contracts.
 
-## No IO deadline
-
-Filesystem primitives accept an optional `AbortSignal` but arm no deadline. Local IO is only best-effort abortable: a timeout cannot force an in-progress `fsync` or `rename` to stop, so a fixed deadline would promise control the backend cannot provide. Process-backed discovery owns its separate timeout contract.
-
 ## Model Experience
 
 Indirectly, through `dsh-tool-fs`, which renders provider text and errors as bounded, retained filesystem tool results.
@@ -52,6 +60,6 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 ## Known Limitations and Deferred Work
 
 - **Text-only by contract** — backends reject binary/non-UTF-8 content with `FS_NOT_TEXT`; binary-safe operations are a deliberate deferral of [the tool-schemas Agent Note](../../../.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md).
-- **Eight primitives only** — no delete, rename/move, copy, or watch; `listDir` is single-level, with recursion, globbing, pagination, and search out of scope per [the directory-listing Agent Note](../../../.agents/notes/archived/architecture/2026-07-03-filesystem-directory-listing-seam.md).
-- **No IO deadline** — cancellation is best-effort at primitive boundaries.
+- **Eleven primitives only** — no delete, rename/move, copy, or watch; `listDir` is single-level, with recursion, globbing, pagination, and search out of scope per [the directory-listing Agent Note](../../../.agents/notes/archived/architecture/2026-07-03-filesystem-directory-listing-seam.md).
+- **No IO deadline** — the seam arms no timeout; cancellation is a best-effort optional `AbortSignal` per primitive (the deliberate [fs-family stance](../README.md)).
 - **Resolve-then-operate costs a remote backend two round-trips per tool call** — folding or caching resolution is left to such a backend.

packages/fs/fs/README.zh.md

@@ -2,56 +2,64 @@
 
 [English](README.md) | 中文
 
-**文件系统提供方 seam**：抽象 `FileSystem` 服务（`ctx.fs`），定义后端提供的存储原语，包括路径解析、stat 元数据、不跟随链接的路径元数据、读取/流式读取文本、列出目录、原子写入和应用字面量编辑，但不规定实现方式。两个变更操作都**可选**接收版本防护，因此 `ctx.fs` 本身就是完整且不受约束的文本存储 seam。本包还拥有由工具分派、策略插件监听的 `fs/*` 策略事件词汇。
+**文件系统提供方 seam**：抽象 `FileSystem` 服务（`ctx.fs`），定义同一个执行世界中的存储原语，包括解析路径、公开规范化进程路径与文件 URI、检查包含关系、完整或流式读取文本、检查／列出元数据、原子写入和应用字面量编辑，但不规定实现方式。两个变更操作都**可选** 接收版本防护，因此 `ctx.fs` 本身就是完整且不受约束的文本存储 seam。本包还拥有由工具分派、政策插件监听的 `fs/*` 政策事件词汇。
 
-本包是[文件系统家族](../README.md)中的提供方 seam 层。[工具](../tool-fs/README.md)、[策略](../fs-policy/README.md)、[本地](../fs-local/README.md)与[沙箱化](../fs-sandbox/README.md)后端分别作为消费方与实现保持独立；能力 seam 决策负责该拆分（[基础](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)、[文件系统 seam](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md)、[提供方拆分](../../../.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md)、[事件门禁](../../../.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md)）。
+本包是四层文件系统栈中的提供方 seam 层；该拆分使每个关注点可以独立演进和替换（见[能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)、[文件系统能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md)、[拆分文件系统 seam Agent Note](../../../.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md)和[文件上下文事件门禁 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md)）：
+
+| 层 | 包 | 角色 |
+|---|---|---|
+| 工具/执行器 | `@deepseek-ai/dsh-tool-fs` | 面向模型的 `read`/`write`/`edit` schema、读取窗口和文本渲染；通过 `ctx.fs` 读取/写入/编辑，并分派 `fs/*` 事件 |
+| 政策 | `@deepseek-ai/dsh-fs-policy` | 已观察状态、编辑前读取和版本防护的写入/编辑，通过 `fs/*` 事件门禁贡献（无服务） |
+| 提供方 seam | `@deepseek-ai/dsh-fs`（本包） | `ctx.fs`：执行世界路径、文本 I/O 与原子变更原语（可选版本防护）；拥有 `fs/*` 事件词汇 |
+| 提供方 | `@deepseek-ai/dsh-fs-local` | 宿主文件系统实现 |
+
+未来的沙箱化、虚拟或远程后端只需实现该接口，政策层和工具层无需改变。
 
 ## 服务 API（`ctx.fs`）
 
-后端继承 `FileSystem` 并实现八个原语。
+后端继承 `FileSystem` 并实现十一个原语。
 
 | 成员 | 语义 |
 |---|---|
 | `resolve(path, opts?)` | 把路径解析为稳定的 `FsTarget`（不透明 `targetKey`、`displayPath`）。`opts.cwd` 是相对 `path` 解析所依据的基准（调用方提供其会话工作区；绝对路径忽略该值；省略时使用后端默认值），`opts.signal` 则中止后端往返。该方法是异步的，因为远程后端可能需要 I/O。经不同路径到达的同一文件必须产生相同 `targetKey`。 |
+| `processPath(target)` | 返回该提供方执行世界中的子进程可以打开的规范化绝对路径。该路径有意与不透明的 `targetKey` 分离。 |
+| `fileUrl(target)` | 返回采用执行世界平台语法的规范化 `file:` URI。编码由后端而非宿主进程负责。 |
+| `contains(parent, child)` | 在不公开或解析目标 key 的情况下，检查规范化身份相等或后代包含关系。两个目标都来自该提供方。 |
 | `stat(target, signal?)` | 返回 `FsInfo` 元数据（`version`、`type`、可选 `size`）；目标不存在时返回 `undefined`。绝不返回内容。 |
-| `lstat(path, opts?, signal?)` | 当最后一个路径组件是符号链接时，不跟随该组件，返回 `FsPathInfo` 元数据。该方法采用路径形态，使消费方能在 `resolve` 跟随仓库自有的符号链接进入目标前拒绝它。 |
+| `lstat(path, opts?, signal?)` | 当最后一个路径组件是符号链接时，不跟随该组件，返回 `FsPathInfo` 元数据。该方法采用路径形态，使消费方能在 `resolve` 跟随仓库所有的符号链接进入目标前拒绝它。 |
 | `readText(target, signal?)` | 把整个普通文本文件读取为一个解码后的字符串。负责普通文件检查、UTF-8 解码和二进制/NUL 拒绝（`FS_NOT_TEXT`）。 |
-| `streamText(target, signal?)` | 为大文件按解码后的分片流式读取相同文本（跨分片 UTF-8 解码仍由此处负责）。 |
-| `listDir(target, signal?)` | 按稳定名称顺序列出直接子项。返回条目名称、条目类型、解析后的子目标和低成本元数据（若可用则包括 `version`/文件 `size`）；绝不读取文件内容。缺失目标抛出 `FS_NOT_FOUND`，非目录抛出 `FS_NOT_DIRECTORY`，权限失败抛出 `FS_PERMISSION_DENIED`，其他后端 I/O 失败抛出 `FS_IO_ERROR`。损坏/消失的子项可以作为无元数据的 `other` 返回；子项权限/I/O 失败会使用相同结构化代码使整个列出操作失败。 |
+| `streamText(target, signal?)` | 为大文件按解码后的分片流式读取相同文本（跨分片 UTF-8 解码仍由此处负责）；需要字节上限的消费方在消费流时执行该上限。 |
+| `listDir(target, signal?)` | 按稳定名称顺序列出直接子项。返回条目名称、条目类型、解析后的子目标和低成本元数据（若可用则包括 `version`/文件 `size`）；绝不读取文件内容。缺失目标抛出 `FS_NOT_FOUND`，非目录抛出 `FS_NOT_DIRECTORY`，权限失败抛出 `FS_PERMISSION_DENIED`，其他后端 I/O 失败抛出 `FS_IO_ERROR`。损坏/消失的子项可以作为无元数据的 `other` 返回；子项权限/I/O 失败会使用相同结构化代码使整个列表失败。 |
 | `writeText(target, content, expected?, signal?)` | 原子创建/替换。`expected` 是可选的：省略 ⇒ 无条件创建或覆盖；提供 `FsWriteIntent`（`createIfAbsent`/`replaceIfVersion`）⇒ 添加防护。 |
 | `editText(target, edit, expected?, signal?)` | 字面量编辑。`expected` 是可选的：省略 ⇒ 无条件编辑当前内容；提供 `{ version }` ⇒ 添加防护，并在匹配之前校验。无论哪种情况，目标缺失都报告 `FS_STALE_VERSION`。应用和写入以原子方式完成，使用同一个变更临界区。 |
 
 无论是否有版本防护，变更都在后端的每目标锁内运行，因此无条件写入/编辑仍是原子的；「无条件」只移除*版本*前置条件，不移除原子性。
 
-## `fs/*` 策略事件
+## `fs/*` 政策事件
 
-本包声明三个事件（见已生成的[事件目录](../../../docs/cordis-catalog/events.md)），使发出方（`@deepseek-ai/dsh-tool-fs`）和策略监听器（`@deepseek-ai/dsh-fs-policy`）共享词汇，而无需让发出方依赖策略插件。`fs/write-intent` 和 `fs/edit-intent` 是单槽决策 waterfall（瀑布式事件）（监听器完整决策，绝不调用 `next()`）；`fs/observed` 是发后即忘的记录事件。它们只携带 `dsh-fs` 词汇和一个不透明 `object` 参与者，不含面向模型的概念或 agent（智能体）/会话所有者结构。
+本包声明三个事件（见已生成的[事件目录](../../../docs/cordis-catalog/events.md)），使发出方（`@deepseek-ai/dsh-tool-fs`）和政策监听器（`@deepseek-ai/dsh-fs-policy`）共享词汇，而无需让发出方依赖政策插件。`fs/write-intent` 和 `fs/edit-intent` 是单槽决策 waterfall（监听器完整决策，绝不调用 `next()`）；`fs/observed` 是发后即忘的记录事件。它们只携带 `dsh-fs` 词汇和一个不透明 `object` 参与者，不含面向模型的概念或 agent（智能体）/会话所有者结构。
 
-## 提供方 seam，不是策略层
+## 提供方 seam，不是政策层
 
-`ctx.fs` 有意接近 fsspec 风格的存储原语，比字节级 `cat`/`open` 高半层，因为它会解码文本并拒绝二进制，使策略层绝不接触原始字节。它负责 UTF-8 解码、二进制拒绝、原子写入和字面量编辑临界区。它**不**负责行窗口、编号行、渲染 footer 或已观察状态。已观察状态、编辑前读取和版本防护的写入/编辑属于插件（`@deepseek-ai/dsh-fs-policy`）通过提供可选防护而添加的策略，并非提供方行为，因此沙箱化/远程后端不会继承任何面向模型的观察策略。
+`ctx.fs` 有意接近 fsspec 风格的存储原语，比字节级 `cat`/`open` 高半层，因为它会解码文本并拒绝二进制，使政策层绝不接触原始字节。它负责 UTF-8 解码、二进制拒绝、原子写入和字面量编辑临界区。它**不** 负责行窗口、编号行、渲染 footer 或已观察状态。已观察状态、编辑前读取和版本防护的写入/编辑属于插件（`@deepseek-ai/dsh-fs-policy`）通过提供可选防护而添加的政策，并非提供方行为，因此沙箱化/远程后端不会继承任何面向模型的观察政策。
 
-`editText` 留在该 seam 上，不由策略层通过读取加写入组合，因为版本防护、字面量匹配和原子重写必须处于同一临界区内，才能正确归因错误并实现一方胜出/一方陈旧的并发；远程后端也可以将其实现为原生比较并编辑操作。
+`editText` 留在该 seam 上，不由政策层通过读取加写入组合，因为版本防护、字面量匹配和原子重写必须处于同一临界区内，才能正确归因错误并实现一方胜出/一方陈旧的并发；远程后端也可以将其实现为原生比较并编辑操作。
 
 ## 词汇
 
 `FsTargetKey` / `FsVersion` 是带品牌的不透明 id（见[品牌 id Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-branded-ids.md)）；消费方不得解析 `targetKey` 或解释 `version`，只有 `displayPath` 用于模型/UI 输出。`FsWriteIntent` 是显式的防护写入意图（`createIfAbsent` 创建缺失目标，并以 `FS_NOT_OBSERVED` 拒绝现有目标；`replaceIfVersion` 只在观察版本上替换，否则为 `FS_STALE_VERSION`）；从 `writeText` 中省略该值就是第三种无条件状态。`FsPathInfo` 是可报告 `symlink` 的不跟随链接元数据形态，区别于目标级 `FsInfo`。失败会抛出 `FsError`（继承 `HarnessError`；见[结构化错误分类 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.md)），并携带稳定的 `FsErrorCode`（`FS_NOT_FOUND`、`FS_NOT_DIRECTORY`、`FS_NOT_TEXT`、`FS_NOT_REGULAR_FILE`、`FS_PERMISSION_DENIED`、`FS_IO_ERROR`、`FS_STALE_VERSION`、`FS_NOT_OBSERVED`、`FS_AMBIGUOUS_EDIT`、`FS_EDIT_NOT_FOUND`、`FS_ABORTED`）；工具注册表公开 `{ name, code }`，并将其附在 `isError` 结果上。完整契约见 `src/types.ts`。
 
-## 无 I/O deadline
-
-文件系统原语接受可选 `AbortSignal`，但不会启动 deadline。本地 I/O 只能尽力取消：超时无法强制进行中的 `fsync` 或 `rename` 停止，因此固定 deadline 会承诺后端无法提供的控制能力。基于进程的发现功能拥有独立的超时契约。
-
 ## 模型体验
 
 通过 `dsh-tool-fs` 间接产生影响；该消费方把提供方文本和错误渲染为有界且保留的文件系统工具结果。
 
 #### KV Cache 影响
 
-不会直接使缓存失效；上述消费方负责请求前缀的任何变化。
+不会直接使缓存失效；具名消费方负责请求前缀的任何变化。
 
-## 已知限制与暂缓事项
+## 已知限制与延期工作
 
 - **契约只支持文本**：后端以 `FS_NOT_TEXT` 拒绝二进制/非 UTF-8 内容；二进制安全操作是[工具 schema Agent Note](../../../.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md)有意延期的工作。
-- **只有八个原语**：没有删除、重命名/移动、复制或监视；`listDir` 只支持一层，递归、glob、分页和搜索不在范围内，见[目录列出 Agent Note](../../../.agents/notes/archived/architecture/2026-07-03-filesystem-directory-listing-seam.md)。
-- **没有 I/O deadline**：取消只能在原语边界尽力执行。
+- **只有十一个原语**：没有删除、重命名/移动、复制或监视；`listDir` 只支持一层，递归、glob、分页和搜索不在范围内，见[目录列出 Agent Note](../../../.agents/notes/archived/architecture/2026-07-03-filesystem-directory-listing-seam.md)。
+- **没有 I/O deadline**：该 seam 不启动超时；取消只是每个原语上尽力而为的可选 `AbortSignal`（见有意采用的 [fs 能力族立场](../README.md)）。
 - **先解析后操作使远程后端每次工具调用需要两次往返**：折叠或缓存解析由这种后端自行决定。

packages/fs/fs/src/index.ts

@@ -1,8 +1,10 @@
 /**
- * Filesystem text-storage provider seam. Backends own stable target identity,
- * text decoding, binary rejection, and atomic mutations. Read windows and
- * observed-state policy stay in consumer and policy plugins; `editText` remains
- * here so version check, literal match, and rewrite share one critical section.
+ * Filesystem provider seam for one execution world. Backends own stable target
+ * identity, process paths and file URIs, containment, text reads, decoding,
+ * binary rejection, and atomic mutations. Read windows and
+ * observed-state policy stay in consumer and policy plugins; `editText`
+ * remains here so version check, literal match, and rewrite share one critical
+ * section.
  * @module @deepseek-ai/dsh-fs
  */
 
@@ -83,7 +85,6 @@ export abstract class FileSystem extends Service {
     super(ctx, 'fs')
   }
 
-  /**
   /**
    * The sandbox mode this backend enforces on mutations BY DEFAULT, or
    * `undefined` when it does not confine at all — the capability fact the tool
@@ -111,6 +112,34 @@ export abstract class FileSystem extends Service {
    */
   abstract resolve(path: string, opts?: { cwd?: string; signal?: AbortSignal }): Promise<FsTarget>
 
+  /**
+   * Return the canonical absolute path a subprocess in this filesystem's
+   * execution world can open. The path is deliberately separate from
+   * {@link FsTarget.targetKey}: consumers may pass this value to another OS
+   * capability, but must continue treating the target key as opaque.
+   * @param target - the resolved target whose process path is required.
+   * @returns an absolute path in the backend's execution world.
+   */
+  abstract processPath(target: FsTarget): string
+
+  /**
+   * Return the canonical `file:` URI for a target in this filesystem's
+   * execution world. Backends own URI encoding because the host platform may
+   * differ from the execution platform.
+   * @param target - the resolved target to encode.
+   * @returns the target's canonical file URI.
+   */
+  abstract fileUrl(target: FsTarget): string
+
+  /**
+   * Test canonical containment without exposing or parsing backend target
+   * keys. Both targets must come from this provider.
+   * @param parent - canonical directory target.
+   * @param child - canonical candidate target.
+   * @returns true when `child` is `parent` or a descendant of it.
+   */
+  abstract contains(parent: FsTarget, child: FsTarget): boolean
+
   /**
    * Return target metadata, or `undefined` when the target does not exist.
    * @param target - the resolved target to stat.

packages/fs/fs/tests/service.spec.ts

@@ -19,13 +19,18 @@ import type {
   FsWriteOutcome,
 } from '@deepseek-ai/dsh-fs'
 
-/** A minimal in-memory fake implementing the eight provider primitives. */
+/** A minimal in-memory fake implementing the provider primitives. */
 class FakeFileSystem extends FileSystem {
   files = new Map<string, string>()
 
   override async resolve(path: string): Promise<FsTarget> {
     return { targetKey: FsTargetKey(path), displayPath: path }
   }
+  override processPath(target: FsTarget): string { return String(target.targetKey) }
+  override fileUrl(target: FsTarget): string { return `file:///${encodeURIComponent(String(target.targetKey))}` }
+  override contains(parent: FsTarget, child: FsTarget): boolean {
+    return child.targetKey === parent.targetKey || String(child.targetKey).startsWith(`${parent.targetKey}/`)
+  }
   override async stat(target: FsTarget): Promise<FsInfo | undefined> {
     const content = this.files.get(target.targetKey)
     if (content === undefined) return undefined
@@ -75,6 +80,7 @@ describe('FileSystem provider seam', () => {
     const ctx = new Context()
     await ctx.plugin(FakeFileSystem)
     const fs = ctx.fs as FakeFileSystem
+    expect(fs.sandboxMode).toBeUndefined()
     fs.files.set('a.txt', 'hi')
     const target = await fs.resolve('a.txt')
     expect((await fs.stat(target))?.type).toBe('file')

packages/fs/tool-fs-search/tests/tools.spec.ts

@@ -148,6 +148,8 @@ class FakeHandle implements SubprocessHandle {
  */
 class FakeSubprocess extends SubprocessService {
   spawns: SubprocessSpawnSpec[] = []
+  override async resolveExecutable(command: string): Promise<string> { return command }
+  override spawnTerminal(): Promise<never> { throw new Error('search tools spawn pipes, never terminals') }
   handles: FakeHandle[] = []
   /** Arms the per-spawn script; a `{ reject }` return scripts a spawn-level failure. */
   handler: (spec: SubprocessSpawnSpec) => ScriptedRun | { reject: Error } = () => runResult('')

packages/fs/tool-fs/tests/tools.spec.ts

@@ -48,6 +48,11 @@ class FakeFs extends FileSystem {
   override async resolve(path: string): Promise<FsTarget> {
     return { targetKey: FsTargetKey(`key:${path}`), displayPath: `/abs/${path}` }
   }
+  override processPath(target: FsTarget): string { return String(target.targetKey) }
+  override fileUrl(target: FsTarget): string { return `file://${target.targetKey}` }
+  override contains(parent: FsTarget, child: FsTarget): boolean {
+    return child.targetKey === parent.targetKey || String(child.targetKey).startsWith(`${parent.targetKey}/`)
+  }
   override async stat(target: FsTarget): Promise<FsInfo | undefined> {
     this.throwIfArmed()
     const content = this.files.get(target.targetKey)

packages/lsp/README.i18n.yaml

@@ -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/lsp/README.md
-README.md: 4964d78f1096d1a4bc78fa80c6b5febaf24a5661
-README.zh.md: 93b872002cf1f53cdbb96ff42402bfeb9557575f
+README.md: 7fbdf071735673fb0158f6fa66148be1c644a433
+README.zh.md: e059dbd80b7e38c0e447e54178162316dfd127c7

packages/lsp/README.md

@@ -6,8 +6,10 @@ The language-server capability seam: an abstract LSP interface, a generic stdio
 
 | Package | Role | ctx key |
 |---|---|---|
-| [`lsp/`](lsp/README.md) | LSP provider seam and shared vocabulary | `ctx.lsp` |
-| [`lsp-local/`](lsp-local/README.md) | Local stdio language-server backend | registers providers on `ctx.lsp` |
-| [`tool-lsp/`](tool-lsp/README.md) | Model-facing semantic-navigation tool | registers on `ctx.tools` |
+| `lsp/` | Abstract LSP seam (provider registry by branded id + extension mapping, per-query selection, vocabulary, `LspError`) | `ctx.lsp` |
+| `lsp-local/` | Generic multi-server stdio backend over `ctx.fs` and `ctx.subprocess` (JSON-RPC, transient-open queries) | (registers providers on `ctx.lsp`) |
+| `tool-lsp/` | Model-facing `lsp` tool (four operations, one-based UTF-16 cursor coordinates) | (registers on `ctx.tools`) |
 
-Providers register semantic capabilities; the tool owns the model-facing contract. The child READMEs document operation, protocol, and presentation details, while the [LSP capability-seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md) owns the rationale.
+The interface lives at `lsp/lsp/`. The seam exposes exactly four semantic operations — `goToDefinition`, `findReferences`, `goToImplementation`, `hover` — and no generic JSON-RPC escape hatch, so a provider swap does not change how the model asks for navigation and no protocol payload or unreviewed mutation reaches the model contract. Providers register **capabilities**, not tools; `tool-lsp` is the only owner of the model-facing name, schema, prompt guidance, and presentation.
+
+See the [LSP capability seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md) for the design rationale, including why documents open transiently per query, why the stdio host consumes the shared filesystem/subprocess execution world, and why extension ownership is exclusive within one runtime.

packages/lsp/README.zh.md

@@ -2,12 +2,14 @@
 
 [English](README.md) | 中文
 
-语言服务器能力 seam：抽象 LSP 接口、通用 stdio 提供方和面向模型的 `lsp` 工具。这些全是**产品**包。
+语言服务器能力 seam：抽象 LSP 接口、通用 stdio 提供方，以及面向模型的 `lsp` 工具。这些全是**产品** 包。
 
 | 包 | 职责 | ctx key |
 |---|---|---|
-| [`lsp/`](lsp/README.md) | LSP 提供方 seam 和共享词汇 | `ctx.lsp` |
-| [`lsp-local/`](lsp-local/README.md) | 本地 stdio 语言服务器后端 | 在 `ctx.lsp` 上注册提供方 |
-| [`tool-lsp/`](tool-lsp/README.md) | 面向模型的语义导航工具 | 注册到 `ctx.tools` |
+| `lsp/` | 抽象 LSP seam（按品牌化 id + 扩展名映射组织的提供方注册表、逐查询选择、词汇、`LspError`） | `ctx.lsp` |
+| `lsp-local/` | 基于 `ctx.fs` 与 `ctx.subprocess` 的通用多服务器 stdio 后端（JSON-RPC、临时打开查询） | （在 `ctx.lsp` 上注册提供方） |
+| `tool-lsp/` | 面向模型的 `lsp` 工具（四种操作、从 1 开始的 UTF-16 光标坐标） | （注册到 `ctx.tools`） |
 
-提供方注册语义能力；工具负责面向模型的契约。子 README 记录操作、协议和呈现细节，[LSP 能力 seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)负责设计原理。
+接口位于 `lsp/lsp/`。该 seam 恰好公开四种语义操作：`goToDefinition`、`findReferences`、`goToImplementation`、`hover`，且不提供通用 JSON-RPC 逃生口；因此，替换提供方不会改变模型请求导航的方式，也不会让协议载荷或未经评审的修改进入模型契约。提供方注册的是**能力** 而非工具；`tool-lsp` 是面向模型名称、schema、提示词指引和呈现的唯一 owner。
+
+设计原理见 [LSP 能力 seam Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)，其中也解释了文档为何在每次查询时临时打开、stdio 主机为何使用共享的文件系统／子进程执行环境，以及扩展名归属为何在同一运行时内互斥。

packages/lsp/lsp-local/README.i18n.yaml

@@ -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/lsp/lsp-local/README.md
-README.md: 37676a82fb5d45b40ca86507259aca9509d25a43
-README.zh.md: 9e8b7f4f4395985bdbc29c1d911520b3559d7e0c
+README.md: 661c27d3326adfc3408b33550a63fe3ebe183a39
+README.zh.md: 83f0eaa1fb4caccc381a1623b791355b2f5c5b65

packages/lsp/lsp-local/README.md

@@ -2,18 +2,19 @@
 
 English | [中文](README.zh.md)
 
-A **generic local stdio language-server backend** for `ctx.lsp`. One plugin instance accepts a named server table and registers one isolated provider per entry. This is a generic host, not a language-server catalog or installer — deployments configure commands and mappings explicitly; presets belong in `cordis.yml` overlays.
+A **generic stdio language-server backend** for `ctx.lsp`. One plugin instance accepts a named server table and registers one isolated provider per entry. It reads through `ctx.fs` and launches through `ctx.subprocess`, so the server and source always inhabit the mounted execution world. This is a generic host, not a language-server catalog or installer — deployments configure commands and mappings explicitly; presets belong in `cordis.yml` overlays.
 
 Namespace plugin (`name` / `inject` / `Config` / `apply`, no default export).
 
 ## What it does
 
 - Resolves every server-local setting before registration; an invalid mapping or registration conflict rolls back earlier entries, so a failed load leaves no provider routes.
-- Lazily single-flights one server process per `(server id, canonical workspace realpath)`. A live server error is not replayed; if the selected pooled transport fails before or during a read-only query, the provider awaits its disposal and retries that query once on a fresh process.
-- Uses a compatibility-first **transient-open** sequence per query: canonicalize and read the source with Node APIs, `textDocument/didOpen` (version 1, full text), the requested request, then `textDocument/didClose` in `finally`. A failed or canceled `didOpen` write terminates the instance before the pool can reuse it. Documents close after each call, so the first version needs no `didChange`, content cache, or document LRU.
-- Serializes each source-read/open/query/close lifecycle through one abortable per-workspace queue so queued calls read current source only when their turn starts; distinct workspaces run in parallel.
+- Lazily single-flights one server process per `(server id, canonical workspace target)`. A live server error is not replayed; if the selected pooled transport fails before or during a read-only query, the provider awaits its disposal and retries that query once on a fresh process.
+- Uses a compatibility-first **transient-open** sequence per query: resolve and byte-bound the source while streaming it through `ctx.fs`, `textDocument/didOpen` (version 1, full text), the requested request, then `textDocument/didClose` in `finally`. A failed or canceled `didOpen` write terminates the instance before the pool can reuse it. Documents close after each call, so the first version needs no `didChange`, content cache, or document LRU.
+- Serializes each source-read/open/query/close lifecycle through one abortable per-workspace queue so queued calls read current source only when their turn starts; distinct workspaces run in parallel. Provider disposal aborts filesystem and protocol work, awaits workspace lookups that have not entered a queue, then drains every queue and server.
 - After protocol shutdown fails, terminates the server's descendant tree through the subprocess seam (POSIX process-group signaling; Windows `taskkill /T /F`). Tree-kill delivery is contained like every group signal — it races server exit — and quiescence is confirmed by the handle's tree-liveness wait rather than by the kill's own outcome.
-- Reads sources through Node filesystem APIs in the subprocess's host namespace — NOT `ctx.fs`, and emits no `fs/observed`: only the LSP result is model-visible, so a query does not satisfy read-before-write policy.
+- Resolves the server executable, cwd, process, and protocol streams through `ctx.subprocess`; `initialize.processId` is `null` because another machine or PID namespace must not monitor the harness process.
+- Uses `ctx.fs` canonical containment, file URIs, and streamed text validation, but emits no `fs/observed`: only the LSP result is model-visible, so a query does not satisfy read-before-write policy.
 
 ## Configuration
 
@@ -41,7 +42,7 @@ Initialization advertises `general.positionEncodings: ['utf-16']`, `workspace: {
 
 ## Security boundary
 
-The provider trusts its configured server and claims no sandbox confinement. It canonicalizes and reads source through Node APIs, rejecting a source that is missing, non-regular, non-UTF-8, oversized, or whose canonical path resolves outside the canonical workspace (symlink aliases share one instance). Result locations may be external, but an external path cannot become a query source. The first implementation therefore requires trusted host-local deployment; restricted, remote, or virtual workspaces require another provider.
+The provider trusts its configured server and claims no sandbox confinement. It delegates canonical identity, containment, regular-file streaming, UTF-8 validation, and file-URI encoding to `ctx.fs`; it rejects missing, non-regular, non-UTF-8, oversized, or canonically out-of-workspace query sources before server startup. Containment is evaluated before the stream opens and does not promise stable-handle identity across concurrent path replacement. Result locations may be external, but an external path cannot become a query source. A deployment must mount filesystem and subprocess providers for the same execution world; split-world composition is invalid.
 
 ## Model Experience
 
@@ -53,6 +54,7 @@ No direct invalidation; `dsh-tool-lsp` owns request-prefix changes.
 
 ## Known Limitations and Deferred Work
 
-- **Trusted host-local only** — no sandbox confinement, no private cache/temp write contract; supporting untrusted binaries or restricted/remote/virtual workspaces requires a later process/filesystem contract and a different provider ([seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)). Containment resolves `realpath`, then opens the source through one handle with `O_NOFOLLOW | O_NONBLOCK` (final-component symlink guard plus nonblocking rejection of FIFOs) and a bounded read; a concurrent mutator that swaps an *ancestor* directory for a symlink between the resolve and the open is an accepted residual TOCTOU under this trusted-deployment model, not closed with non-portable `openat` segment walks.
-- **Transient-open compatibility floor** — servers whose synchronization omits open/close (or advertise `None`) are unsupported even if closed-document queries would work; compatibility with one TypeScript server does not imply cross-language support.
+- **No confinement policy** — this package trusts the configured server and does not sandbox its process; a restricted deployment must supply appropriate process/filesystem providers or a same-world sandbox wrapper.
+- **Transient-open compatibility floor** — servers whose synchronization omits open/close (or advertise `None`) are unsupported even if closed-document queries would work; the pinned TypeScript e2e establishes one compatibility floor, not a cross-language claim.
 - **Per-server/workspace serialization latency** — parallel agents sharing one server and workspace queue behind one process; long-lived workspace processes consume memory until disposal.
+- **A hard-killed harness orphans language servers** — `initialize.processId: null` removes server-side client-PID monitoring, so servers are cleaned only by graceful service disposal; a SIGKILL'd harness leaves them running until they exit on their own.

packages/lsp/lsp-local/README.zh.md

@@ -2,18 +2,19 @@
 
 [English](README.md) | 中文
 
-`ctx.lsp` 的**通用本地 stdio 语言服务器后端**。一个插件实例接受一张命名服务器表，并逐配置项注册一个隔离的提供方。这是通用主机，而不是语言服务器目录或安装器：部署需要显式配置命令与映射，预设应放在 `cordis.yml` overlay 中。
+`ctx.lsp` 的**通用 stdio 语言服务器后端**。一个插件实例接受一张命名服务器表，并逐配置项注册一个隔离的提供方。它通过 `ctx.fs` 读取，并通过 `ctx.subprocess` 启动，因此服务器与源文件始终位于已挂载的执行世界中。这是通用主机，而不是语言服务器目录或安装器：部署需要显式配置命令与映射，预设应放在 `cordis.yml` overlay 中。
 
 Namespace 插件（`name`／`inject`／`Config`／`apply`，无默认导出）。
 
 ## 功能
 
 - 在注册前解析每项服务器局部设置；无效映射或注册冲突会回滚较早配置项，因此加载失败不会留下提供方路由。
-- 每个 `(server id, canonical workspace realpath)` 惰性 single-flight 一个服务器进程。存活服务器错误不会回放；如果选中的池化传输在只读查询之前或期间失败，提供方会等待其 dispose（资源释放）完成，并在新进程上重试该查询一次。
-- 每次查询都使用兼容性优先的**临时打开**序列：通过 Node API 规范化并读取源文件、`textDocument/didOpen`（版本 1、完整文本）、所请求操作，然后执行 `textDocument/didClose`，该操作位于 `finally` 中。写入 `didOpen` 失败或取消时，会在池复用该实例前将其终止。文档在每次调用后关闭，因此第一版不需要 `didChange`、内容 cache 或文档 LRU。
-- 通过一条逐 Workspace、可中止的队列，串行执行每个源读取／打开／查询／关闭生命周期，因此排队调用只会在轮到自身时读取当前源；不同 Workspace 并行运行。
+- 每个 `(server id, canonical workspace target)` 惰性 single-flight 一个服务器进程。存活服务器错误不会回放；如果选中的池化传输在只读查询之前或期间失败，提供方会等待其 dispose（资源释放）完成，并在新进程上重试该查询一次。
+- 每次查询都使用兼容性优先的**临时打开**序列：通过 `ctx.fs` 流式读取源文件，同时解析并限制其字节数；随后执行 `textDocument/didOpen`（版本 1、完整文本）、所请求操作，再执行位于 `finally` 中的 `textDocument/didClose`。写入 `didOpen` 失败或取消时，会在池复用该实例前将其终止。文档在每次调用后关闭，因此第一版不需要 `didChange`、内容 cache 或文档 LRU。
+- 通过一条逐 Workspace、可中止的队列，串行执行每个源读取／打开／查询／关闭生命周期，因此排队调用只会在轮到自身时读取当前源；不同 Workspace 并行运行。提供方 dispose 会中止文件系统与协议工作，等待尚未进入队列的 Workspace 查找完成，随后排空每条队列与每个服务器。
 - 协议 shutdown 失败后，经由子进程 seam 终止服务器后代树（POSIX 进程组信号；Windows `taskkill /T /F`）。树终止的投递结果与所有进程组信号一样被就地吸收，不向外抛出（投递与服务器退出存在竞态）；服务器是否完全停稳，由句柄的进程树存活等待确认，而非由这次终止自身的结果确认。
-- 通过子进程 host namespace 中的 Node 文件系统 API 读取源文件，绝不使用 `ctx.fs`，也不发出 `fs/observed`：只有 LSP 结果对模型可见，因此查询不满足先读后写策略。
+- 通过 `ctx.subprocess` 解析服务器可执行文件、cwd、进程和协议流；`initialize.processId` 为 `null`，因为另一台机器或 PID namespace 不得监视 harness 进程。
+- 使用 `ctx.fs` 提供的规范化包含关系、文件 URI 与流式文本验证，但不发出 `fs/observed`：只有 LSP 结果对模型可见，因此查询不满足先读后写策略。
 
 ## 配置
 
@@ -41,7 +42,7 @@ Namespace 插件（`name`／`inject`／`Config`／`apply`，无默认导出）
 
 ## 安全边界
 
-提供方信任其配置的服务器，不提供任何沙箱隔离。它通过 Node API 规范化并读取源文件，拒绝缺失、非普通文件、非 UTF-8、过大，或规范路径位于规范 Workspace 外部的源文件（符号链接别名共享一个实例）。结果位置可以在外部，但外部路径不能成为查询源。因此，第一版要求可信的主机本地部署；受限、远程或虚拟 Workspace 需要另一个提供方。
+提供方信任其配置的服务器，不提供任何沙箱隔离。它把规范化身份、包含关系、普通文件流式读取、UTF-8 验证和文件 URI 编码委托给 `ctx.fs`；并在服务器启动前拒绝缺失、非普通文件、非 UTF-8、过大，或规范化后位于 Workspace 外部的查询源。包含关系在打开流之前评估，不承诺在并发路径替换期间保持稳定句柄身份。结果位置可以在外部，但外部路径不能成为查询源。部署必须挂载描述同一执行世界的文件系统与进程管理提供方；分裂世界组合无效。
 
 ## 模型体验
 
@@ -53,6 +54,7 @@ Namespace 插件（`name`／`inject`／`Config`／`apply`，无默认导出）
 
 ## 已知限制与暂缓事项
 
-- **仅限可信主机本地环境**：没有沙箱隔离，也没有私有 cache／temp 写入契约；支持不受信任 binary 或受限／远程／虚拟 Workspace，需要后续的进程／文件系统契约及不同提供方（见 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)）。限制逻辑先解析 `realpath`，再通过一个带 `O_NOFOLLOW | O_NONBLOCK` 的 handle 打开源文件（最终组件符号链接防护，并以非阻塞方式拒绝 FIFO），同时进行有界读取；并发修改方如果在解析与打开之间把*祖先*目录替换为符号链接，会造成残余 TOCTOU。在该可信部署模型下接受此风险，不使用不可移植的 `openat` 逐 segment 遍历来封闭。
-- **临时打开兼容性下限**：同步能力省略打开／关闭（或声明 `None`）的服务器不受支持，即使关闭文档查询能够工作；与一个 TypeScript 服务器兼容，并不表示支持其他语言。
+- **不提供隔离策略**：本包（package）信任所配置的服务器，不对其进程实施沙箱；受限部署必须提供适当的进程／文件系统提供方，或使用同一执行世界的沙箱包装层。
+- **临时打开兼容性下限**：同步能力省略打开／关闭（或声明 `None`）的服务器不受支持，即使关闭文档查询能够工作；固定的 TypeScript e2e 只建立一项兼容性下限，不代表跨语言承诺。
 - **逐服务器／Workspace 串行化延迟**：共享同一个服务器与 Workspace 的并行 agent（智能体）会在一个进程后排队；长生命周期 Workspace 进程会占用内存直到 dispose。
+- **被强制杀死的 harness 会遗留语言服务器**：`initialize.processId: null` 取消了服务器侧的客户端 PID 监视，因此服务器只能由服务的优雅 dispose 清理；被 SIGKILL 的 harness 会让它们继续运行，直到自行退出。

packages/lsp/lsp-local/package.json

@@ -26,6 +26,7 @@
   "license": "BSD-3-Clause",
   "peerDependencies": {
     "@deepseek-ai/dsh-brand": "^0.0.1",
+    "@deepseek-ai/dsh-fs": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-lsp": "^0.0.1",
@@ -38,6 +39,8 @@
   },
   "devDependencies": {
     "@deepseek-ai/dsh-brand": "workspace:^",
+    "@deepseek-ai/dsh-fs": "workspace:^",
+    "@deepseek-ai/dsh-fs-local": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-lsp": "workspace:^",

packages/lsp/lsp-local/src/connection.ts

@@ -22,7 +22,7 @@ export interface ConnectionSpec {
   readonly args: readonly string[]
   /** The child's working directory (the canonical workspace). */
   readonly cwd: string
-  /** The child's environment (credential-scrubbed, with overrides applied). */
+  /** Explicit child environment overrides; the subprocess provider owns its ambient scrub. */
   readonly env: Record<string, string>
   /** Largest single framed message accepted from the server. */
   readonly maxMessageBytes: number
@@ -98,9 +98,8 @@ export class LspConnection {
         stderr: { maxBytes: spec.maxStderrBytes },
       },
       graceMs: spec.killGraceMs,
-      // spec.env mixes the scrubbed base with explicit config entries; the
-      // seam merges the whole map after its own ambient scrub, so a
-      // configured DSH_* fact reaches the child.
+      // The seam merges explicit config entries after its ambient scrub, so a
+      // configured credential or DSH_* fact reaches the child deliberately.
       env: spec.env,
     })
     /* v8 ignore start -- 'pipe' dispositions expose both streams by the seam contract; defensive. */

packages/lsp/lsp-local/src/host.ts

@@ -1,154 +1,124 @@
-/**
- * Host-filesystem source access for the local provider, using Node APIs directly in the
- * subprocess's namespace (never `ctx.fs`): only the LSP result is model-visible, so a query does not
- * satisfy read-before-write policy and emits no `fs/observed`. Canonicalization derives target
- * identity from `realpath`, so symlink aliases share a workspace; a source is rejected before server
- * startup when it is missing, non-regular, non-UTF-8, oversized, or canonically outside the
- * workspace. External result locations are allowed, but an external path can never become a query
- * source.
- * @module @deepseek-ai/dsh-lsp-local/host
- */
+/** Filesystem-seam source access for the generic stdio LSP provider. */
 
-import { constants } from 'node:fs'
-import { open, realpath, stat } from 'node:fs/promises'
-import type { FileHandle } from 'node:fs/promises'
-import { isAbsolute, resolve as resolvePath, sep } from 'node:path'
+import { Buffer } from 'node:buffer'
+import type { FileSystem, FsTarget } from '@deepseek-ai/dsh-fs'
 import { throwIfAborted } from './abort.ts'
 
-/** A validated source: its canonical absolute path and current UTF-8 text. */
-export interface HostSource {
-  /** The canonical (realpath-resolved) absolute path, inside the canonical workspace. */
+/** A canonical workspace in the filesystem/subprocess execution world. */
+export interface HostWorkspace {
+  /** Stable filesystem identity used for provider pooling. */
+  readonly target: FsTarget
+  /** Canonical absolute path accepted as a subprocess cwd. */
   readonly canonicalPath: string
-  /** The file's current text, read as UTF-8. */
+  /** Canonical file URI sent during LSP initialization. */
+  readonly fileUrl: string
+}
+
+/** A validated source and the exact URI sent to the language server. */
+export interface HostSource {
+  /** Canonical file URI in the execution world's platform syntax. */
+  readonly fileUrl: string
+  /** Current complete UTF-8 text. */
   readonly text: string
 }
 
 /**
- * Canonicalize a workspace root: it must exist and be a directory. The returned realpath supplies
- * process cwd, `rootUri`, the sole `workspaceFolders` entry, and pool identity, so symlinked roots
- * collapse to one instance.
- * @param workspaceRoot - the caller's workspace root (absolute).
- * @param signal - optional cancellation observed around each filesystem operation.
- * @returns the canonical directory path.
- * @throws Error when the path is missing or not a directory.
+ * Resolve and validate one workspace through `ctx.fs`.
+ * @param fs - filesystem provider sharing the language server's execution world.
+ * @param workspaceRoot - caller-supplied workspace path.
+ * @param signal - optional cancellation around provider operations.
+ * @returns stable identity plus process path and file URI.
  */
-export async function canonicalizeWorkspace(workspaceRoot: string, signal?: AbortSignal): Promise<string> {
+export async function canonicalizeWorkspace(
+  fs: FileSystem,
+  workspaceRoot: string,
+  signal?: AbortSignal,
+): Promise<HostWorkspace> {
   throwIfAborted(signal)
-  let canonical: string
+  let target: FsTarget
   try {
-    canonical = await realpath(workspaceRoot)
-  } catch (error) {
-    throw new Error(`workspace root "${workspaceRoot}" cannot be resolved: ${messageOf(error)}`)
+    target = await fs.resolve(workspaceRoot, signal === undefined ? {} : { signal })
+  } catch (error: unknown) {
+    throwIfAborted(signal)
+    throw new Error(`workspace root "${workspaceRoot}" cannot be resolved: ${messageOf(error)}`, { cause: error })
   }
   throwIfAborted(signal)
-  const info = await stat(canonical)
+  const info = await fs.stat(target, signal).catch((error: unknown) => {
+    throwIfAborted(signal)
+    throw error
+  })
   throwIfAborted(signal)
-  if (!info.isDirectory()) {
+  if (info?.type !== 'directory') {
     throw new Error(`workspace root "${workspaceRoot}" is not a directory`)
   }
-  return canonical
+  return {
+    target,
+    canonicalPath: fs.processPath(target),
+    fileUrl: fs.fileUrl(target),
+  }
 }
 
 /**
- * Resolve, canonicalize, validate, and read a query source in one pass. A relative `filePath`
- * resolves against `canonicalWorkspace`; an absolute one is taken directly. The canonical target
- * must be a regular UTF-8 file no larger than `maxDocumentBytes`, and must lie inside the canonical
- * workspace.
- * @param filePath - the model-supplied source path (relative or absolute).
- * @param canonicalWorkspace - the already-canonicalized workspace root.
- * @param maxDocumentBytes - the largest source this host will open.
- * @param signal - optional cancellation observed throughout resolution, validation, and reading.
- * @returns the canonical path and current UTF-8 text.
- * @throws Error when the source is missing, non-regular, oversized, non-UTF-8, or out of workspace.
+ * Resolve, contain, and read one byte-bounded query source through `ctx.fs`.
+ * This layer owns the LSP-specific complete-document cap while the filesystem
+ * provider owns streaming, regular-file checks, and UTF-8 validation.
+ * @param fs - filesystem provider sharing the server's execution world.
+ * @param filePath - absolute source path or path relative to `workspace`.
+ * @param workspace - already-canonical workspace.
+ * @param maxDocumentBytes - largest complete source accepted by this host.
+ * @param signal - optional cancellation.
+ * @returns canonical file URI and current text.
  */
 export async function readHostSource(
+  fs: FileSystem,
   filePath: string,
-  canonicalWorkspace: string,
+  workspace: HostWorkspace,
   maxDocumentBytes: number,
   signal?: AbortSignal,
 ): Promise<HostSource> {
   throwIfAborted(signal)
-  const requested = isAbsolute(filePath) ? filePath : resolvePath(canonicalWorkspace, filePath)
-  let canonicalPath: string
+  let target: FsTarget
   try {
-    canonicalPath = await realpath(requested)
-  } catch (error) {
-    throw new Error(`source "${filePath}" cannot be resolved: ${messageOf(error)}`)
+    target = await fs.resolve(filePath, {
+      cwd: workspace.canonicalPath,
+      ...signal === undefined ? {} : { signal },
+    })
+  } catch (error: unknown) {
+    throwIfAborted(signal)
+    throw new Error(`source "${filePath}" cannot be resolved: ${messageOf(error)}`, { cause: error })
   }
   throwIfAborted(signal)
-  if (!isInside(canonicalWorkspace, canonicalPath)) {
+  if (!fs.contains(workspace.target, target)) {
     throw new Error(`source "${filePath}" resolves outside the workspace`)
   }
-  // Open ONE handle after containment, then stat and read through it: a concurrent replace between
-  // realpath and read cannot swap the target, so the regular-file and size checks bind the bytes we
-  // actually read (no path-based TOCTOU). O_NOFOLLOW rejects the final component being swapped for a
-  // symlink between realpath and open (which would otherwise escape the workspace).
-  // O_NONBLOCK prevents a FIFO with no writer from hanging before fstat can reject it as nonregular.
-  const handle = await open(canonicalPath, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK)
+  const chunks: string[] = []
+  let bytes = 0
   try {
-    throwIfAborted(signal)
-    const info = await handle.stat()
-    throwIfAborted(signal)
-    if (!info.isFile()) {
-      throw new Error(`source "${filePath}" is not a regular file`)
+    // XXX(lsp-source-replacement): Revisit stable-handle identity only if a real query observes
+    // replacement between canonical containment and the provider opening this stream.
+    const stream = await fs.streamText(target, signal)
+    for await (const chunk of stream) {
+      throwIfAborted(signal)
+      bytes += Buffer.byteLength(chunk)
+      if (bytes > maxDocumentBytes) break
+      chunks.push(chunk)
     }
-    if (info.size > maxDocumentBytes) {
-      throw new Error(`source "${filePath}" is ${info.size} bytes, over the ${maxDocumentBytes}-byte limit`)
-    }
-    // Bound the read to the cap even if the file grew after stat: read one extra byte and reject on
-    // overflow, so a concurrent grow cannot defeat the memory bound.
-    const buffer = await readCapped(handle, maxDocumentBytes, filePath, signal)
-    const text = decodeUtf8Strict(buffer, filePath)
+  } catch (error: unknown) {
     throwIfAborted(signal)
-    return { canonicalPath, text }
-  } finally {
-    await handle.close()
+    throw new Error(`source "${filePath}" could not be read: ${messageOf(error)}`, { cause: error })
+  }
+  if (bytes > maxDocumentBytes) {
+    throw new Error(
+      `source "${filePath}" exceeds the ${maxDocumentBytes}-byte limit; reading stopped after ${bytes} bytes`,
+    )
+  }
+  throwIfAborted(signal)
+  return {
+    fileUrl: fs.fileUrl(target),
+    text: chunks.join(''),
   }
 }
 
-/** Read at most `maxBytes` from the handle, rejecting when the source overflows the cap. */
-async function readCapped(
-  handle: FileHandle,
-  maxBytes: number,
-  filePath: string,
-  signal?: AbortSignal,
-): Promise<Buffer> {
-  const limit = maxBytes + 1
-  const chunk = Buffer.allocUnsafe(limit)
-  let total = 0
-  for (;;) {
-    throwIfAborted(signal)
-    const { bytesRead } = await handle.read(chunk, total, limit - total, total)
-    throwIfAborted(signal)
-    if (bytesRead === 0) break
-    total += bytesRead
-    /* v8 ignore next 3 -- overflow requires the file to grow past the cap between stat and read (a concurrent mutation); defensive. */
-    if (total > maxBytes) {
-      throw new Error(`source "${filePath}" grew past the ${maxBytes}-byte limit while reading`)
-    }
-  }
-  return chunk.subarray(0, total)
-}
-
-/** Whether `child` is the workspace itself or a descendant of it (both already canonical). */
-function isInside(workspace: string, child: string): boolean {
-  if (child === workspace) return true
-  /* v8 ignore next -- a canonical non-root workspace never ends with a separator; the guard covers the filesystem root. */
-  const base = workspace.endsWith(sep) ? workspace : workspace + sep
-  return child.startsWith(base)
-}
-
-/** Decode strictly as UTF-8: a fatal decoder rejects only malformed bytes, keeping a legitimate U+FFFD. */
-function decodeUtf8Strict(buffer: Buffer, filePath: string): string {
-  try {
-    return new TextDecoder('utf-8', { fatal: true }).decode(buffer)
-  } catch {
-    throw new Error(`source "${filePath}" is not valid UTF-8 text`)
-  }
-}
-
-/** Extract a message from an unknown thrown value without leaking `any`. */
 function messageOf(error: unknown): string {
-  /* v8 ignore next -- Node fs rejections are always Error instances; the String() fallback is defensive. */
   return error instanceof Error ? error.message : String(error)
 }

packages/lsp/lsp-local/src/index.ts

@@ -1,18 +1,16 @@
 /**
  * Generic stdio language-server backend for `ctx.lsp`. One plugin instance configures a named table
  * of server commands and registers one isolated provider for each entry. Every provider lazily
- * single-flights one server process per canonical workspace realpath, serves transient-open queries
+ * single-flights one server process per canonical workspace target, serves transient-open queries
  * through it, and replaces a selected transport that fails before or during the next read-only
- * query. Providers read sources through Node APIs in the host namespace (not `ctx.fs`)
- * and trust their configured servers — no sandbox confinement.
+ * query. Providers read sources through `ctx.fs` and launch servers through
+ * `ctx.subprocess`, so both local and remote implementations share one host.
  *
  * Namespace plugin (named exports, no default export). Lifecycle is effect-scoped: disposal
  * unregisters from `ctx.lsp` and tears down every live server.
  * @module @deepseek-ai/dsh-lsp-local
  */
 
-import { accessSync, constants, statSync } from 'node:fs'
-import { delimiter, isAbsolute, join } from 'node:path'
 import type { Context } from 'cordis'
 import z from 'schemastery'
 import { LspError, LspProviderId } from '@deepseek-ai/dsh-lsp'
@@ -24,9 +22,9 @@ import type {
 import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import { abortable, abortError } from './abort.ts'
 import { canonicalizeWorkspace, readHostSource } from './host.ts'
+import type { HostWorkspace } from './host.ts'
 import { LspInstance } from './instance.ts'
 import type { ConnectionSpawner } from './connection.ts'
-import { scrubbedParentEnv } from '@deepseek-ai/dsh-subprocess'
 import type { InstanceSpec } from './instance.ts'
 
 export { canonicalizeWorkspace, readHostSource } from './host.ts'
@@ -46,10 +44,7 @@ export { LspConnection } from './connection.ts'
 export const name = 'lsp-local'
 
 /** Services required by this plugin. */
-export const inject = ['lsp', 'subprocess']
-
-/** Credential-shaped ambient env vars are NOT forwarded to the child by default. */
-
+export const inject = ['fs', 'lsp', 'subprocess']
 
 const DEFAULT_MAX_MESSAGE_BYTES = 16_000_000
 const DEFAULT_MAX_STDERR_BYTES = 1_000_000
@@ -91,6 +86,7 @@ export interface Config {
 
 /** One server config after schemastery fills every default. */
 type ResolvedServerConfig = Required<LspLocalServerConfig>
+type WorkspaceKey = HostWorkspace['target']['targetKey']
 
 const LspLocalServerConfig: z<LspLocalServerConfig> = z.object({
   command: z.string().required(),
@@ -110,27 +106,67 @@ export const Config: z<Config> = z.object({
   servers: z.dict(LspLocalServerConfig).required(),
 })
 
+/** Propagate teardown failures only after every sibling has settled. */
+function throwTeardownFailures(results: readonly PromiseSettledResult<void>[], message: string): void {
+  const failures: unknown[] = []
+  for (const result of results) {
+    if (result.status === 'rejected') failures.push(result.reason)
+  }
+  if (failures.length === 1) throw failures[0]
+  if (failures.length > 1) throw new AggregateError(failures, message)
+}
+
 /**
  * Register the configured stdio LSP providers. Resolves every executable at load (after credential
  * scrubbing) before publishing any provider; each process launches lazily on its first matching
  * query.
- * @param ctx - the plugin context (must inject `lsp`).
+ * @param ctx - the plugin context carrying `fs`, `lsp`, and `subprocess`.
  * @param config - the resolved plugin configuration (schemastery has filled every default).
  */
-export function apply(ctx: Context, config: Config): void {
+export async function apply(ctx: Context, config: Config): Promise<void> {
   const entries = Object.entries(config.servers)
   if (entries.length === 0) throw new Error('lsp-local: servers must contain at least one server')
 
+  const setupAbort = new AbortController()
+  const stopSetupCancellation = ctx.on('internal/plugin', (fiber) => {
+    // An async plugin callback must observe its own disposal before Cordis can
+    // run effect cleanup, because unload otherwise waits for this callback.
+    if (fiber === ctx.fiber && fiber.uid === null) {
+      setupAbort.abort(new Error('lsp-local setup disposed'))
+    }
+  })
+
   // Resolve every server-local setting before registration so a bad later command or bound cannot
   // publish an earlier provider. Registry-level mapping conflicts are rolled back below.
-  const providers = entries.map(([providerId, rawConfig]) => {
-    if (providerId.trim() === '') throw new Error('lsp-local: server ids must be non-empty strings')
-    const resolved = rawConfig as ResolvedServerConfig
-    validateServerConfig(providerId, resolved)
-    const childEnv = buildChildEnv(resolved.env)
-    const executable = resolveExecutable(resolved.command, childEnv)
-    return new LocalLspProvider(providerId, resolved, childEnv, executable, spec => ctx.subprocess.spawn(spec))
-  })
+  const providers = await (async () => {
+    const lookups = entries.map(async ([providerId, rawConfig]) => {
+      if (providerId.trim() === '') throw new Error('lsp-local: server ids must be non-empty strings')
+      const resolved = rawConfig as ResolvedServerConfig
+      validateServerConfig(providerId, resolved)
+      const executable = await ctx.subprocess.resolveExecutable(
+        resolved.command,
+        resolved.env,
+        setupAbort.signal,
+      )
+      setupAbort.signal.throwIfAborted()
+      return new LocalLspProvider(
+        providerId,
+        ctx.fs,
+        resolved,
+        executable,
+        spec => ctx.subprocess.spawn(spec),
+      )
+    })
+    try {
+      return await Promise.all(lookups)
+    } catch (error: unknown) {
+      setupAbort.abort(error)
+      await Promise.allSettled(lookups)
+      throw error
+    } finally {
+      stopSetupCancellation()
+    }
+  })()
 
   ctx.effect(() => {
     const disposers: Array<() => void> = []
@@ -143,7 +179,8 @@ export function apply(ctx: Context, config: Config): void {
     return async () => {
       // Remove every route before process teardown so no new query can enter a draining provider.
       for (const dispose of disposers.reverse()) dispose()
-      await Promise.all(providers.map(provider => provider.disposeAll()))
+      const results = await Promise.allSettled(providers.map(provider => provider.disposeAll()))
+      throwTeardownFailures(results, 'lsp-local provider teardown failed')
     }
   }, 'lsp-local.registerProviders')
 }
@@ -180,16 +217,19 @@ function assertPositiveInteger(providerId: string, name: string, value: number):
 class LocalLspProvider implements LspProvider {
   readonly id: LspProviderId
   readonly extensionToLanguage: Readonly<Record<string, string>>
-  /** One live instance per canonical workspace realpath. */
-  private readonly instances = new Map<string, LspInstance>()
+  /** One live instance per stable canonical workspace identity. */
+  private readonly instances = new Map<WorkspaceKey, LspInstance>()
   /** One complete source-read→open→query→close serialization tail per canonical workspace. */
-  private readonly queues = new Map<string, Promise<void>>()
+  private readonly queues = new Map<WorkspaceKey, Promise<void>>()
+  /** Workspace canonicalizations that have not entered a provider-owned queue yet. */
+  private readonly workspaceLookups = new Set<Promise<void>>()
+  private readonly lifetime = new AbortController()
   private disposed = false
 
   constructor(
     providerId: string,
+    private readonly fs: Context['fs'],
     private readonly config: ResolvedServerConfig,
-    private readonly childEnv: Record<string, string>,
     private readonly executable: string,
     private readonly spawner: ConnectionSpawner,
   ) {
@@ -210,43 +250,60 @@ class LocalLspProvider implements LspProvider {
     if (signal?.aborted) throw abortError(signal)
   }
 
+  /** Fuse caller cancellation with provider disposal for every filesystem and protocol await. */
+  private querySignal(signal?: AbortSignal): AbortSignal {
+    return signal === undefined
+      ? this.lifetime.signal
+      : AbortSignal.any([signal, this.lifetime.signal])
+  }
+
   async query(request: LspProviderQuery, signal?: AbortSignal): Promise<LspQueryResult> {
-    // Honor an already-aborted signal before host I/O so a canceled request never starts a server.
+    // Honor an already-aborted signal before provider I/O so a canceled request never starts a server.
     this.assertActive(signal)
-    const workspace = await canonicalizeWorkspace(request.workspaceRoot, signal)
-    this.assertActive(signal)
-    return this.enqueue(workspace, signal, async () => {
-      this.assertActive(signal)
+    const querySignal = this.querySignal(signal)
+    const workspaceResult = canonicalizeWorkspace(this.fs, request.workspaceRoot, querySignal)
+    const workspaceLookup = workspaceResult.then(() => undefined, () => undefined)
+    this.workspaceLookups.add(workspaceLookup)
+    let workspace: HostWorkspace
+    try {
+      workspace = await workspaceResult
+    } finally {
+      this.workspaceLookups.delete(workspaceLookup)
+    }
+    this.assertActive(querySignal)
+    const workspaceKey = workspace.target.targetKey
+    return this.enqueue(workspaceKey, querySignal, async () => {
+      this.assertActive(querySignal)
       // Read inside the workspace queue but before spawning: a queued query sees current bytes when
       // its turn starts, while an invalid source still cannot leave an idle process pooled.
-      const source = await readHostSource(request.filePath, workspace, this.config.maxDocumentBytes, signal)
+      const source = await readHostSource(this.fs, request.filePath, workspace, this.config.maxDocumentBytes, querySignal)
       // Disposal may have snapshotted the instance map while host I/O was pending. Re-check before a
       // synchronous get-or-create so every spawned process remains owned by teardown.
-      this.assertActive(signal)
-      let instance = this.instanceFor(workspace)
+      this.assertActive(querySignal)
+      let instance = this.instanceFor(workspaceKey, workspace)
       try {
-        return await instance.query(request, source, signal)
+        return await instance.query(request, source, querySignal)
       } catch (error) {
         // A selected child can have died while idle or fail during the next write. Queries are
         // read-only, so replace that transport once and retry transparently.
         if (!instance.isTransportFailure(error)) throw error
         await instance.dispose()
-        this.evictIfCurrent(workspace, instance)
-        this.assertActive(signal)
-        instance = this.instanceFor(workspace)
-        return await instance.query(request, source, signal)
+        this.evictIfCurrent(workspaceKey, instance)
+        this.assertActive(querySignal)
+        instance = this.instanceFor(workspaceKey, workspace)
+        return await instance.query(request, source, querySignal)
       } finally {
         // Reach quiescence before dropping a dead slot; a replacement must survive this ownership check.
         if (instance.dead) {
           await instance.dispose()
-          this.evictIfCurrent(workspace, instance)
+          this.evictIfCurrent(workspaceKey, instance)
         }
       }
     })
   }
 
   /** Serialize one complete query lifecycle for a canonical workspace. */
-  private enqueue<T>(workspace: string, signal: AbortSignal | undefined, run: () => Promise<T>): Promise<T> {
+  private enqueue<T>(workspace: WorkspaceKey, signal: AbortSignal | undefined, run: () => Promise<T>): Promise<T> {
     const previous = this.queues.get(workspace) ?? Promise.resolve()
     const result = abortable(previous, signal).then(run)
     // The tail follows the actual prior work even when this caller aborts its wait. It never rejects,
@@ -260,27 +317,28 @@ class LocalLspProvider implements LspProvider {
   }
 
   /** Return or synchronously publish the one instance for a canonical workspace. */
-  private instanceFor(workspace: string): LspInstance {
+  private instanceFor(workspaceKey: WorkspaceKey, workspace: HostWorkspace): LspInstance {
     this.assertActive()
-    const existing = this.instances.get(workspace)
+    const existing = this.instances.get(workspaceKey)
     if (existing !== undefined) return existing
     const created = this.createInstance(workspace)
-    this.instances.set(workspace, created)
+    this.instances.set(workspaceKey, created)
     return created
   }
 
   /** Drop the slot iff it still contains this instance. */
-  private evictIfCurrent(workspace: string, instance: LspInstance): void {
+  private evictIfCurrent(workspace: WorkspaceKey, instance: LspInstance): void {
     /* v8 ignore next -- mismatch requires another query to replace the slot before this finally runs. */
     if (this.instances.get(workspace) === instance) this.instances.delete(workspace)
   }
 
-  private createInstance(workspace: string): LspInstance {
+  private createInstance(workspace: HostWorkspace): LspInstance {
     const spec: InstanceSpec = {
       command: this.executable,
       args: this.config.args,
-      cwd: workspace,
-      env: this.childEnv,
+      cwd: workspace.canonicalPath,
+      workspaceUri: workspace.fileUrl,
+      env: this.config.env,
       configuration: this.config.configuration,
       initializationOptions: this.config.initializationOptions,
       maxMessageBytes: this.config.maxMessageBytes,
@@ -294,51 +352,18 @@ class LocalLspProvider implements LspProvider {
   /** Dispose every live instance and block further queries. */
   async disposeAll(): Promise<void> {
     this.disposed = true
+    this.lifetime.abort(new LspError('lsp-local provider is disposed', 'LSP_DISPOSED'))
     const live = [...this.instances.values()]
     const draining = [...this.queues.values()]
+    const resolving = [...this.workspaceLookups]
     this.instances.clear()
-    await Promise.all([
+    const results = await Promise.allSettled([
       ...live.map(instance => instance.dispose()),
       ...draining,
+      ...resolving,
     ])
     this.queues.clear()
-  }
-}
-
-/** The seam's scrubbed parent env (credential-shaped and DSH_* names dropped), plus the config's explicit env. */
-function buildChildEnv(extra: Record<string, string>): Record<string, string> {
-  return { ...scrubbedParentEnv(), ...extra }
-}
-
-/**
- * Resolve the server executable to an absolute path: an absolute command is verified directly; a
- * bare command is looked up on the child's PATH. Fails loudly when nothing is executable.
- */
-function resolveExecutable(command: string, childEnv: Record<string, string>): string {
-  if (isAbsolute(command)) {
-    // Verify an absolute command too, so an unavailable one fails at load, not on the first query.
-    if (!isExecutableFileSync(command)) {
-      throw new Error(`lsp-local: command "${command}" is not an executable file`)
-    }
-    return command
-  }
-  /* v8 ignore next -- buildChildEnv always sets PATH from the ambient env; the further fallbacks are defensive. */
-  const pathValue = childEnv.PATH ?? process.env.PATH ?? ''
-  for (const dir of pathValue.split(delimiter)) {
-    if (dir === '') continue
-    const candidate = join(dir, command)
-    if (isExecutableFileSync(candidate)) return candidate
-  }
-  throw new Error(`lsp-local: command "${command}" was not found on PATH`)
-}
-
-/** Synchronous regular-file and executable check used only at load-time resolution. */
-function isExecutableFileSync(path: string): boolean {
-  try {
-    if (!statSync(path).isFile()) return false
-    accessSync(path, constants.X_OK)
-    return true
-  } catch {
-    return false
+    this.workspaceLookups.clear()
+    throwTeardownFailures(results, 'lsp-local instance teardown failed')
   }
 }

packages/lsp/lsp-local/src/instance.ts

@@ -7,7 +7,6 @@
  * @module @deepseek-ai/dsh-lsp-local/instance
  */
 
-import { pathToFileURL } from 'node:url'
 import { LspError } from '@deepseek-ai/dsh-lsp'
 import type {
   LspOperation,
@@ -31,6 +30,8 @@ import {
 
 /** Everything an instance needs beyond the connection spec. */
 export interface InstanceSpec extends ConnectionSpec {
+  /** Canonical workspace file URI supplied by the filesystem provider. */
+  readonly workspaceUri: string
   /** Static `initialize` options forwarded to the server. */
   readonly initializationOptions: unknown
   /** Graceful `shutdown`/`exit` budget before escalation (ms). */
@@ -108,9 +109,11 @@ export class LspInstance {
 
   private async initialize(): Promise<void> {
     const initializeResult = await this.connection.request('initialize', {
-      processId: process.pid,
-      rootUri: pathToFileURL(this.spec.cwd).href,
-      workspaceFolders: [{ uri: pathToFileURL(this.spec.cwd).href, name: 'workspace' }],
+      // A subprocess provider may run in another PID namespace or machine;
+      // the host PID would let the server monitor an unrelated process.
+      processId: null,
+      rootUri: this.spec.workspaceUri,
+      workspaceFolders: [{ uri: this.spec.workspaceUri, name: 'workspace' }],
       capabilities: CLIENT_CAPABILITIES,
       initializationOptions: this.spec.initializationOptions,
     }) as WireInitializeResult
@@ -147,7 +150,7 @@ export class LspInstance {
       throw new LspError('server does not support the transient textDocument/didOpen this host requires', 'LSP_UNSUPPORTED_OPERATION')
     }
 
-    const uri = pathToFileURL(source.canonicalPath).href
+    const uri = source.fileUrl
     let opened = false
     try {
       /* v8 ignore next -- guards an abort landing between the ready wait and didOpen; not deterministically reproducible. */
@@ -241,10 +244,9 @@ export class LspInstance {
     if (operation === 'hover') {
       return { kind: 'hover', hover: normalizeHover(payload) }
     }
-    // `spec.cwd` is the canonical workspace realpath (the provider canonicalizes before spawning),
-    // and every `file:` location URI is relative to it — so it is the root a caller must relativize
-    // display paths against, not the request's possibly-symlinked workspaceRoot.
-    return { kind: 'locations', locations: normalizeLocations(payload), resolvedWorkspaceRoot: this.spec.cwd }
+    // The filesystem provider owns URI syntax for the execution platform, which may differ from the
+    // harness host. Preserve that coordinate through rendering instead of reparsing `spec.cwd` there.
+    return { kind: 'locations', locations: normalizeLocations(payload), resolvedWorkspaceUri: this.spec.workspaceUri }
   }
 
   private answerServerRequest(method: string, params: unknown): Promise<unknown> {

packages/lsp/lsp-local/tests/built-lib.e2e.ts

@@ -16,8 +16,9 @@ import { afterAll, beforeAll, describe, expect, it } from 'vitest'
 
 const pkgDir = fileURLToPath(new URL('..', import.meta.url))
 const seamLib = join(pkgDir, '../lsp/lib/index.js')
+const fsLib = join(pkgDir, '../../fs/fs-local/lib/index.js')
 const subprocessLib = join(pkgDir, '../../subprocess/subprocess-local/lib/index.js')
-const built = existsSync(join(pkgDir, 'lib/index.js')) && existsSync(seamLib) && existsSync(subprocessLib)
+const built = existsSync(join(pkgDir, 'lib/index.js')) && existsSync(seamLib) && existsSync(fsLib) && existsSync(subprocessLib)
 
 const fixtureServer = fileURLToPath(new URL('./fixture-server.ts', import.meta.url))
 
@@ -42,10 +43,12 @@ describe.skipIf(!built)('built lib real load path (plain node)', () => {
       const { Context } = await import('cordis')
       const { default: Lsp } = await import('@deepseek-ai/dsh-lsp')
       const LspLocal = await import('@deepseek-ai/dsh-lsp-local')
+      const { default: LocalFileSystem } = await import('@deepseek-ai/dsh-fs-local')
       const { default: LocalSubprocessService } = await import('@deepseek-ai/dsh-subprocess-local')
       const ctx = new Context()
       await ctx.plugin(Lsp)
       await ctx.plugin(LocalSubprocessService)
+      await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
       await ctx.plugin(LspLocal, {
         servers: {
           fake: {

packages/lsp/lsp-local/tests/host.spec.ts

@@ -4,7 +4,10 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { realpath } from 'node:fs/promises'
 import { execFile } from 'node:child_process'
+import { pathToFileURL } from 'node:url'
 import { promisify } from 'node:util'
+import { Context } from 'cordis'
+import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
 import { deadline } from '@deepseek-ai/dsh-timeout'
 import { canonicalizeWorkspace, readHostSource } from '@deepseek-ai/dsh-lsp-local'
 
@@ -12,84 +15,125 @@ const execFileAsync = promisify(execFile)
 
 let root: string
 let ws: string
+let ctx: Context
+let fs: LocalFileSystem
 
 beforeEach(async () => {
   root = await realpath(await mkdtemp(join(tmpdir(), 'lsp-host-')))
   ws = join(root, 'ws')
   await mkdir(ws)
+  ctx = new Context()
+  await ctx.plugin(LocalFileSystem, { cwd: root })
+  fs = ctx.fs as LocalFileSystem
 })
 
 afterEach(async () => {
+  await ctx.fiber.dispose()
   await rm(root, { recursive: true, force: true })
 })
 
 const BIG = 1_000_000
 
+async function workspace() {
+  return await canonicalizeWorkspace(fs, ws)
+}
+
+async function readSource(filePath: string, maxBytes = BIG, signal?: AbortSignal) {
+  return await readHostSource(fs, filePath, await workspace(), maxBytes, signal)
+}
+
 describe('canonicalizeWorkspace', () => {
   it('returns the realpath of a directory', async () => {
-    expect(await canonicalizeWorkspace(ws)).toBe(ws)
+    expect((await workspace()).canonicalPath).toBe(ws)
   })
 
   it('resolves a symlinked workspace to its target so aliases share identity', async () => {
     const link = join(root, 'ws-link')
     await symlink(ws, link)
-    expect(await canonicalizeWorkspace(link)).toBe(ws)
+    expect((await canonicalizeWorkspace(fs, link)).canonicalPath).toBe(ws)
   })
 
   it('rejects a missing workspace', async () => {
-    await expect(canonicalizeWorkspace(join(root, 'nope'))).rejects.toThrow(/cannot be resolved/)
+    await expect(canonicalizeWorkspace(fs, join(root, 'nope'))).rejects.toThrow(/not a directory/)
+  })
+
+  it('wraps a provider failure while resolving the workspace', async () => {
+    fs.resolve = async () => { throw 'raw workspace resolve failure' }
+    await expect(canonicalizeWorkspace(fs, ws))
+      .rejects.toThrow(`workspace root "${ws}" cannot be resolved: raw workspace resolve failure`)
   })
 
   it('rejects a non-directory workspace', async () => {
     const file = join(root, 'file.txt')
     await writeFile(file, 'x')
-    await expect(canonicalizeWorkspace(file)).rejects.toThrow(/not a directory/)
+    await expect(canonicalizeWorkspace(fs, file)).rejects.toThrow(/not a directory/)
+  })
+
+  it('normalizes workspace metadata cancellation and preserves other provider failures', async () => {
+    const providerFailure = new Error('workspace metadata failed')
+    fs.stat = async () => { throw providerFailure }
+    await expect(canonicalizeWorkspace(fs, ws)).rejects.toBe(providerFailure)
+
+    const controller = new AbortController()
+    fs.stat = async () => {
+      controller.abort(new Error('workspace metadata cancelled'))
+      throw providerFailure
+    }
+    await expect(canonicalizeWorkspace(fs, ws, controller.signal))
+      .rejects.toThrow('workspace metadata cancelled')
   })
 })
 
 describe('readHostSource', () => {
   it('reads a relative path against the workspace', async () => {
     await writeFile(join(ws, 'a.ts'), 'const x = 1\n')
-    const source = await readHostSource('a.ts', ws, BIG)
-    expect(source.canonicalPath).toBe(join(ws, 'a.ts'))
+    const source = await readSource('a.ts')
+    expect(source.fileUrl).toBe(pathToFileURL(join(ws, 'a.ts')).href)
     expect(source.text).toBe('const x = 1\n')
   })
 
   it('reads an absolute path inside the workspace', async () => {
     const abs = join(ws, 'b.ts')
     await writeFile(abs, 'b')
-    const source = await readHostSource(abs, ws, BIG)
-    expect(source.canonicalPath).toBe(abs)
+    const source = await readSource(abs)
+    expect(source.fileUrl).toBe(pathToFileURL(abs).href)
   })
 
   it('accepts a source reached through a symlink that stays inside the workspace', async () => {
     await mkdir(join(ws, 'real'))
     await writeFile(join(ws, 'real', 'c.ts'), 'c')
     await symlink(join(ws, 'real'), join(ws, 'linked'))
-    const source = await readHostSource('linked/c.ts', ws, BIG)
-    expect(source.canonicalPath).toBe(join(ws, 'real', 'c.ts'))
+    const source = await readSource('linked/c.ts')
+    expect(source.fileUrl).toBe(pathToFileURL(join(ws, 'real', 'c.ts')).href)
   })
 
   it('rejects a source whose canonical path escapes the workspace via symlink', async () => {
     const outside = join(root, 'outside.ts')
     await writeFile(outside, 'secret')
     await symlink(outside, join(ws, 'escape.ts'))
-    await expect(readHostSource('escape.ts', ws, BIG)).rejects.toThrow(/outside the workspace/)
+    await expect(readSource('escape.ts')).rejects.toThrow(/outside the workspace/)
   })
 
   it('rejects an absolute source outside the workspace', async () => {
     const outside = join(root, 'out.ts')
     await writeFile(outside, 'x')
-    await expect(readHostSource(outside, ws, BIG)).rejects.toThrow(/outside the workspace/)
+    await expect(readSource(outside)).rejects.toThrow(/outside the workspace/)
   })
 
   it('rejects a missing source', async () => {
-    await expect(readHostSource('nope.ts', ws, BIG)).rejects.toThrow(/cannot be resolved/)
+    await expect(readSource('nope.ts')).rejects.toThrow(/not found/)
+  })
+
+  it('wraps a provider failure while resolving the source', async () => {
+    const canonical = await workspace()
+    fs.resolve = async () => { throw 'raw resolve failure' }
+    await expect(readHostSource(fs, 'broken.ts', canonical, BIG))
+      .rejects.toThrow('source "broken.ts" cannot be resolved: raw resolve failure')
   })
 
   it('rejects a non-regular source (directory)', async () => {
     await mkdir(join(ws, 'dir'))
-    await expect(readHostSource('dir', ws, BIG)).rejects.toThrow(/not a regular file/)
+    await expect(readSource('dir')).rejects.toThrow(/not a regular file/)
   })
 
   // Windows has no filesystem FIFO; the directory case above pins non-regular rejection there.
@@ -97,36 +141,44 @@ describe('readHostSource', () => {
     const fifo = join(ws, 'pipe.ts')
     await execFileAsync('mkfifo', [fifo])
     using d = deadline(undefined, 1000, 'FIFO_READ_TIMEOUT')
-    await expect(readHostSource('pipe.ts', ws, BIG, d.signal)).rejects.toThrow(/not a regular file/)
+    await expect(readSource('pipe.ts', BIG, d.signal)).rejects.toThrow(/not a regular file/)
   })
 
   it('honors a pre-aborted source read before filesystem work', async () => {
     const controller = new AbortController()
     controller.abort(new Error('source read cancelled'))
-    await expect(readHostSource('missing.ts', ws, BIG, controller.signal)).rejects.toThrow(/source read cancelled/)
+    await expect(readSource('missing.ts', BIG, controller.signal)).rejects.toThrow(/source read cancelled/)
   })
 
   it('treats the workspace root itself as inside, then rejects it as non-regular', async () => {
-    // filePath '.' canonicalizes to the workspace dir: isInside's identity branch is taken, and the
-    // directory then fails the regular-file check.
-    await expect(readHostSource('.', ws, BIG)).rejects.toThrow(/not a regular file/)
+    // The filesystem containment primitive accepts the workspace itself; the
+    // bounded read then rejects the directory as non-regular.
+    await expect(readSource('.')).rejects.toThrow(/not a regular file/)
   })
 
-  it('rejects an oversized source', async () => {
+  it('rejects an oversized source and reports the observed lower bound', async () => {
     await writeFile(join(ws, 'big.ts'), 'x'.repeat(100))
-    await expect(readHostSource('big.ts', ws, 10)).rejects.toThrow(/over the 10-byte limit/)
+    await expect(readSource('big.ts', 10)).rejects.toMatchObject({
+      message: 'source "big.ts" exceeds the 10-byte limit; reading stopped after 100 bytes',
+    })
+  })
+
+  it('counts the complete UTF-8 byte length at the configured boundary', async () => {
+    await writeFile(join(ws, 'multibyte.ts'), '€abc')
+    await expect(readSource('multibyte.ts', 6)).resolves.toMatchObject({ text: '€abc' })
+    await expect(readSource('multibyte.ts', 5)).rejects.toThrow(/5-byte limit/)
   })
 
   it('rejects a non-UTF-8 source', async () => {
     await writeFile(join(ws, 'bin.ts'), Buffer.from([0xff, 0xfe, 0x00]))
-    await expect(readHostSource('bin.ts', ws, BIG)).rejects.toThrow(/not valid UTF-8/)
+    await expect(readSource('bin.ts')).rejects.toThrow(/invalid UTF-8|binary file/)
   })
 
   it('keeps a valid U+FFFD replacement character in otherwise-valid UTF-8', async () => {
     // The literal replacement char is valid UTF-8; a fatal decoder must accept it (only malformed
     // byte sequences are rejected).
     await writeFile(join(ws, 'repl.ts'), 'const s = "<22>"\n')
-    const source = await readHostSource('repl.ts', ws, BIG)
+    const source = await readSource('repl.ts')
     expect(source.text).toBe('const s = "<22>"\n')
   })
 })

packages/lsp/lsp-local/tests/instance.spec.ts

@@ -1,8 +1,11 @@
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { readFileSync } from 'node:fs'
 import { mkdtemp, mkdir, readFile, rm, writeFile, realpath } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { pathToFileURL, fileURLToPath } from 'node:url'
+import { Context } from 'cordis'
+import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
 import { LspInstance, readHostSource } from '@deepseek-ai/dsh-lsp-local'
 import { encodeMessage } from '@deepseek-ai/dsh-lsp-local'
 import type { ConnectionWriter } from '@deepseek-ai/dsh-lsp-local/src/connection.ts'
@@ -15,6 +18,8 @@ const fixtureServer = fileURLToPath(new URL('./fixture-server.ts', import.meta.u
 
 let root: string
 let ws: string
+let ctx: Context
+let fs: LocalFileSystem
 let live: LspInstance[] = []
 
 beforeEach(async () => {
@@ -22,11 +27,15 @@ beforeEach(async () => {
   ws = join(root, 'ws')
   await mkdir(ws)
   await writeFile(join(ws, 'a.ts'), 'const x = 1\n')
+  ctx = new Context()
+  await ctx.plugin(LocalFileSystem, { cwd: root })
+  fs = ctx.fs as LocalFileSystem
 })
 
 afterEach(async () => {
   for (const instance of live) await instance.dispose()
   live = []
+  await ctx.fiber.dispose()
   await rm(root, { recursive: true, force: true })
 })
 
@@ -39,6 +48,7 @@ function makeInstance(
     command: process.execPath,
     args: [fixtureServer],
     cwd: ws,
+    workspaceUri: pathToFileURL(ws).href,
     env: { ...scrubbedParentEnv(), ...env },
     configuration: { setting: 42 },
     initializationOptions: { init: true },
@@ -58,7 +68,12 @@ function query(operation: LspProviderQuery['operation'] = 'goToDefinition'): Lsp
 
 /** Run a query against an instance, reading the source first the way the provider does. */
 async function run(instance: LspInstance, operation: LspProviderQuery['operation'] = 'goToDefinition', signal?: AbortSignal): Promise<LspQueryResult> {
-  const source = await readHostSource('a.ts', ws, 4_000_000)
+  const workspace = {
+    target: await fs.resolve(ws),
+    canonicalPath: ws,
+    fileUrl: pathToFileURL(ws).href,
+  }
+  const source = await readHostSource(fs, 'a.ts', workspace, 4_000_000)
   return instance.query(query(operation), source, signal)
 }
 
@@ -68,6 +83,7 @@ function scriptInstance(script: string, overrides: Partial<InstanceSpec> = {}):
     command: process.execPath,
     args: ['-e', script],
     cwd: ws,
+    workspaceUri: pathToFileURL(ws).href,
     env: scrubbedParentEnv(),
     configuration: null,
     initializationOptions: null,
@@ -102,17 +118,17 @@ describe('LspInstance server-request handling', () => {
 
   it('accepts a lifecycle client/registerCapability request', async () => {
     const instance = makeInstance({ LSP_FAKE_ON_OPEN: 'lifecycle', LSP_FAKE_DEF: 'null' })
-    await expect(run(instance, 'goToDefinition')).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: ws })
+    await expect(run(instance, 'goToDefinition')).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceUri: pathToFileURL(ws).href })
   })
 
   it('rejects a workspace/applyEdit request but keeps serving', async () => {
     const instance = makeInstance({ LSP_FAKE_ON_OPEN: 'applyEdit', LSP_FAKE_DEF: 'null' })
-    await expect(run(instance, 'goToDefinition')).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: ws })
+    await expect(run(instance, 'goToDefinition')).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceUri: pathToFileURL(ws).href })
   })
 
   it('rejects an unknown server request but keeps serving', async () => {
     const instance = makeInstance({ LSP_FAKE_ON_OPEN: 'unknown', LSP_FAKE_DEF: 'null' })
-    await expect(run(instance, 'goToDefinition')).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: ws })
+    await expect(run(instance, 'goToDefinition')).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceUri: pathToFileURL(ws).href })
   })
 })
 
@@ -248,7 +264,7 @@ describe('LspInstance query and abort', () => {
     await expect(run(instance, 'goToDefinition')).resolves.toEqual({
       kind: 'locations',
       locations: [],
-      resolvedWorkspaceRoot: ws,
+      resolvedWorkspaceUri: pathToFileURL(ws).href,
     })
     expect(instance.dead).toBe(true)
   })
@@ -331,14 +347,22 @@ describe('LspInstance disposal', () => {
 function processAlive(pid: number): boolean {
   try {
     process.kill(pid, 0)
-    return true
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === 'ESRCH') return false
     throw error
   }
+  if (process.platform !== 'linux') return true
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, 'utf8')
+    const state = stat.slice(stat.lastIndexOf(')') + 2).split(/\s+/, 1)[0]
+    return !/^[ZXx]$/.test(state ?? '')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false
+    throw error
+  }
 }
 
-/** Wait until a process id disappears so temporary-workspace cleanup cannot race handle release. */
+/** Wait until a process can no longer execute so temporary-workspace cleanup cannot race handle release. */
 async function waitForProcessExit(pid: number, timeoutMs = 3_000): Promise<void> {
   const started = Date.now()
   while (processAlive(pid)) {

packages/lsp/lsp-local/tests/lifecycle.spec.ts

@@ -8,6 +8,7 @@ import { Context } from 'cordis'
 import Lsp, { type LspProvider, type LspQueryRequest, type LspQueryResult } from '@deepseek-ai/dsh-lsp'
 import { deadline } from '@deepseek-ai/dsh-timeout'
 import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
+import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
 import * as LspLocal from '@deepseek-ai/dsh-lsp-local'
 import type { LspLocalServerConfig } from '@deepseek-ai/dsh-lsp-local'
 
@@ -47,6 +48,7 @@ async function mount(
   const ctx = new Context()
   await ctx.plugin(Lsp)
   await ctx.plugin(LocalSubprocessService)
+  await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
   const register = ctx.lsp.registerProvider.bind(ctx.lsp)
   const registrationSpy = captureProvider === undefined
     ? undefined
@@ -79,6 +81,7 @@ describe('lsp-local end to end over a fake server', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     await ctx.plugin(LspLocal, {
       servers: {
         typescript: fakeServer({ LSP_FAKE_HOVER: JSON.stringify({ contents: 'ts' }) }),
@@ -99,7 +102,7 @@ describe('lsp-local end to end over a fake server', () => {
     expect(result).toEqual<LspQueryResult>({
       kind: 'locations',
       locations: [{ uri: pathToFileURL(join(ws, 'a.ts')).href, range: { start: { line: 0, character: 0 }, end: { line: 0, character: 3 } } }],
-      resolvedWorkspaceRoot: ws,
+      resolvedWorkspaceUri: pathToFileURL(ws).href,
     })
     await ctx.fiber.dispose()
   })
@@ -130,7 +133,7 @@ describe('lsp-local end to end over a fake server', () => {
 
   it('returns an empty locations result for a null definition', async () => {
     const ctx = await mount({ LSP_FAKE_DEF: 'null' })
-    expect(await ctx.lsp.query(query('goToDefinition'))).toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: ws })
+    expect(await ctx.lsp.query(query('goToDefinition'))).toEqual({ kind: 'locations', locations: [], resolvedWorkspaceUri: pathToFileURL(ws).href })
     await ctx.fiber.dispose()
   })
 
@@ -170,7 +173,7 @@ describe('lsp-local end to end over a fake server', () => {
 
   it('accepts openClose options sync', async () => {
     const ctx = await mount({ LSP_FAKE_SYNC: JSON.stringify({ openClose: true, change: 2 }), LSP_FAKE_DEF: 'null' })
-    expect(await ctx.lsp.query(query('goToDefinition'))).toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: ws })
+    expect(await ctx.lsp.query(query('goToDefinition'))).toEqual({ kind: 'locations', locations: [], resolvedWorkspaceUri: pathToFileURL(ws).href })
     await ctx.fiber.dispose()
   })
 
@@ -279,8 +282,9 @@ describe('lsp-local end to end over a fake server', () => {
       readonly instances: ReadonlyMap<string, { readonly dead: boolean }>
     }).instances
     const instance = [...instances.values()][0]
-    if (instance === undefined) throw new Error('expected one pooled LSP instance')
-    await waitFor(async () => instance.dead)
+    // The query's finally may already have observed the exit and evicted the dead slot. When the
+    // slot remains, synchronize with its close before proving the next query replaces it.
+    if (instance !== undefined) await waitFor(async () => instance.dead)
     expect(await ctx.lsp.query(query('goToDefinition'))).toMatchObject({ kind: 'locations' })
     await ctx.fiber.dispose()
   })
@@ -294,7 +298,128 @@ describe('lsp-local end to end over a fake server', () => {
     controller.abort(new Error('mid-read cancel'))
     await expect(pending).rejects.toThrow(/mid-read cancel/)
     // A subsequent live query still works, proving no half-created instance poisoned the pool.
-    expect(await ctx.lsp.query(query('goToDefinition'))).toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: ws })
+    expect(await ctx.lsp.query(query('goToDefinition'))).toEqual({ kind: 'locations', locations: [], resolvedWorkspaceUri: pathToFileURL(ws).href })
+    await ctx.fiber.dispose()
+  })
+
+  it('aborts and awaits a workspace lookup when the provider is disposed', async () => {
+    const ctx = await mount({ LSP_FAKE_DEF: 'null' })
+    const fs = ctx.fs
+    const resolve = fs.resolve.bind(fs)
+    const started = Promise.withResolvers<AbortSignal>()
+    const release = Promise.withResolvers<undefined>()
+    vi.spyOn(fs, 'resolve').mockImplementation(async (path, options) => {
+      if (path !== ws) return await resolve(path, options)
+      const signal = options?.signal
+      if (signal === undefined) throw new Error('workspace lookup missing provider lifetime signal')
+      started.resolve(signal)
+      return await rejectWhenAborted(signal, release.promise)
+    })
+
+    const pending = ctx.lsp.query(query('goToDefinition'))
+    const signal = await started.promise
+    let disposed = false
+    const disposing = ctx.fiber.dispose().then(() => { disposed = true })
+    await new Promise<void>(resolve => setImmediate(resolve))
+
+    expect(signal.aborted).toBe(true)
+    expect(disposed).toBe(false)
+    release.resolve(undefined)
+    await expect(pending).rejects.toThrow('provider is disposed')
+    await expect(disposing).resolves.toBeUndefined()
+  })
+
+  it('aborts a queued source stream when the provider is disposed', async () => {
+    const ctx = await mount({ LSP_FAKE_DEF: 'null' })
+    const fs = ctx.fs
+    const started = Promise.withResolvers<AbortSignal>()
+    vi.spyOn(fs, 'streamText').mockImplementation(async (_target, signal) => {
+      if (signal === undefined) throw new Error('source read missing provider lifetime signal')
+      started.resolve(signal)
+      return (async function* () {
+        await rejectWhenAborted(signal)
+        yield ''
+      })()
+    })
+
+    const pending = ctx.lsp.query(query('goToDefinition'))
+    const signal = await started.promise
+    const disposing = ctx.fiber.dispose()
+
+    await expect(pending).rejects.toThrow('provider is disposed')
+    await expect(disposing).resolves.toBeUndefined()
+    expect(signal.aborted).toBe(true)
+  })
+
+  it('waits for every owned teardown before aggregating instance failures', async () => {
+    let provider: LspProvider | undefined
+    const ctx = await mount({ LSP_FAKE_DEF: 'null' }, {}, (registered) => { provider = registered })
+    if (provider === undefined) throw new Error('expected lsp-local to register a provider')
+    const internals = provider as unknown as {
+      readonly instances: Map<string, { dispose(): Promise<void> }>
+      readonly queues: Map<string, Promise<void>>
+      readonly workspaceLookups: Set<Promise<void>>
+      disposeAll(): Promise<void>
+    }
+    const firstFailure = new Error('first instance cleanup failed')
+    const secondFailure = new Error('second instance cleanup failed')
+    const release = Promise.withResolvers<undefined>()
+    internals.instances.set('first', { dispose: async () => { throw firstFailure } })
+    internals.instances.set('second', { dispose: async () => { throw secondFailure } })
+    internals.queues.set('pending', release.promise)
+    internals.workspaceLookups.add(Promise.resolve())
+
+    let settled = false
+    const disposing = internals.disposeAll().finally(() => { settled = true })
+    await new Promise<void>(resolve => setImmediate(resolve))
+    expect(settled).toBe(false)
+    release.resolve(undefined)
+    await expect(disposing).rejects.toMatchObject({
+      errors: [firstFailure, secondFailure],
+      message: 'lsp-local instance teardown failed',
+    })
+    expect(internals.instances.size).toBe(0)
+    expect(internals.queues.size).toBe(0)
+    expect(internals.workspaceLookups.size).toBe(0)
+    await ctx.fiber.dispose()
+  })
+
+  it('waits for every provider before reporting plugin teardown failure', async () => {
+    const ctx = new Context()
+    const disposalErrors: unknown[] = []
+    ctx.logger.error = ((error: unknown) => { disposalErrors.push(error) }) as typeof ctx.logger.error
+    await ctx.plugin(Lsp)
+    await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
+    const providers: LspProvider[] = []
+    const register = ctx.lsp.registerProvider.bind(ctx.lsp)
+    const registrationSpy = vi.spyOn(ctx.lsp, 'registerProvider').mockImplementation((provider) => {
+      providers.push(provider)
+      return register(provider)
+    })
+    const fiber = await ctx.plugin(LspLocal, {
+      servers: {
+        first: fakeServer(),
+        second: fakeServer({}, { extensionToLanguage: { '.js': 'javascript' } }),
+      },
+    })
+    registrationSpy.mockRestore()
+    expect(providers).toHaveLength(2)
+    const failure = new Error('provider cleanup failed')
+    const release = Promise.withResolvers<undefined>()
+    const first = providers[0] as LspProvider & { disposeAll(): Promise<void> }
+    const second = providers[1] as LspProvider & { disposeAll(): Promise<void> }
+    first.disposeAll = async () => { throw failure }
+    second.disposeAll = async () => { await release.promise }
+
+    let disposed = false
+    const disposing = fiber.dispose().then(() => { disposed = true })
+    await new Promise<void>(resolve => setImmediate(resolve))
+    expect(disposed).toBe(false)
+    expect(disposalErrors).toEqual([])
+    release.resolve(undefined)
+    await disposing
+    expect(disposalErrors).toEqual([failure])
     await ctx.fiber.dispose()
   })
 
@@ -322,6 +447,7 @@ describe('lsp-local end to end over a fake server', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     await expect(ctx.plugin(LspLocal, {
       servers: {
         missing: {
@@ -354,3 +480,16 @@ async function waitFor(condition: () => Promise<boolean>, timeoutMs = 3000): Pro
     await new Promise<void>(resolve => setTimeout(resolve, 10))
   }
 }
+
+/** Hold one fake provider operation until cancellation, optionally behind a cleanup gate. */
+function rejectWhenAborted<T>(signal: AbortSignal, release: Promise<unknown> = Promise.resolve()): Promise<T> {
+  return new Promise((_resolve, reject) => {
+    const onAbort = (): void => {
+      void release.then(() => {
+        reject(signal.reason instanceof Error ? signal.reason : new Error(String(signal.reason)))
+      })
+    }
+    signal.addEventListener('abort', onAbort, { once: true })
+    if (signal.aborted) onAbort()
+  })
+}

packages/lsp/lsp-local/tests/provider.spec.ts

@@ -1,9 +1,10 @@
-import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { chmod, mkdtemp, mkdir, rm, writeFile, realpath } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { delimiter, join } from 'node:path'
 import { Context } from 'cordis'
 import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
+import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
 import Lsp, { type LspQueryRequest } from '@deepseek-ai/dsh-lsp'
 import * as LspLocal from '@deepseek-ai/dsh-lsp-local'
 import type { Config, LspLocalServerConfig } from '@deepseek-ai/dsh-lsp-local'
@@ -44,6 +45,7 @@ describe('lsp-local provider resolution', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     await expect(ctx.plugin(LspLocal, config('onpath', {
       command: 'fake-lsp',
       args: [],
@@ -57,6 +59,7 @@ describe('lsp-local provider resolution', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     await expect(ctx.plugin(LspLocal, config('nope', {
       command: 'fake-lsp',
       args: [],
@@ -71,6 +74,7 @@ describe('lsp-local provider resolution', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     // Grab the provider instance by registering, then dispose the whole plugin fiber.
     const lsp = ctx.lsp
     const fiber = await ctx.plugin(LspLocal, config('disp', {
@@ -88,6 +92,7 @@ describe('lsp-local provider resolution', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     await expect(ctx.plugin(LspLocal, config('bad-budget', {
       command: process.execPath,
       args: ['-e', ''],
@@ -101,6 +106,7 @@ describe('lsp-local provider resolution', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     await expect(ctx.plugin(LspLocal, config('bad-cap', {
       command: process.execPath,
       args: ['-e', ''],
@@ -114,6 +120,7 @@ describe('lsp-local provider resolution', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     await expect(ctx.plugin(LspLocal, config('bad-timer', {
       command: process.execPath,
       args: ['-e', ''],
@@ -130,6 +137,7 @@ describe('lsp-local provider resolution', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     await expect(ctx.plugin(LspLocal, config('abs-bad', {
       command: notExe,
       args: [],
@@ -142,6 +150,7 @@ describe('lsp-local provider resolution', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     await expect(ctx.plugin(LspLocal, config('abs-directory', {
       command: ws,
       args: [],
@@ -154,6 +163,7 @@ describe('lsp-local provider resolution', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     await expect(ctx.plugin(LspLocal, { servers: {} })).rejects.toThrow(/servers must contain at least one server/)
     await ctx.fiber.dispose()
   })
@@ -162,6 +172,7 @@ describe('lsp-local provider resolution', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     await expect(ctx.plugin(LspLocal, config('', {
       command: process.execPath,
       extensionToLanguage: { '.ts': 'typescript' },
@@ -173,6 +184,7 @@ describe('lsp-local provider resolution', () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     await expect(ctx.plugin(LspLocal, {
       servers: {
         valid: { command: process.execPath, extensionToLanguage: { '.ts': 'typescript' } },
@@ -183,10 +195,90 @@ describe('lsp-local provider resolution', () => {
     await ctx.fiber.dispose()
   })
 
+  it('waits for aborted sibling executable lookups before setup rejects', async () => {
+    const ctx = new Context()
+    await ctx.plugin(Lsp)
+    await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
+    const slowStarted = Promise.withResolvers<undefined>()
+    const slowAborted = Promise.withResolvers<undefined>()
+    const releaseCleanup = Promise.withResolvers<undefined>()
+    vi.spyOn(ctx.subprocess, 'resolveExecutable').mockImplementation(async (command, _env, signal) => {
+      if (signal === undefined) throw new Error('missing setup signal')
+      if (command === 'slow-lsp') {
+        return await new Promise<string>((_resolve, reject) => {
+          const onAbort = (): void => {
+            slowAborted.resolve(undefined)
+            void releaseCleanup.promise.then(() => {
+              reject(signal.reason instanceof Error ? signal.reason : new Error(String(signal.reason)))
+            })
+          }
+          signal.addEventListener('abort', onAbort, { once: true })
+          slowStarted.resolve(undefined)
+          if (signal.aborted) onAbort()
+        })
+      }
+      await slowStarted.promise
+      throw new Error('lookup failed')
+    })
+
+    const loading = ctx.plugin(LspLocal, {
+      servers: {
+        slow: { command: 'slow-lsp', extensionToLanguage: { '.ts': 'typescript' } },
+        failing: { command: 'failing-lsp', extensionToLanguage: { '.js': 'javascript' } },
+      },
+    })
+    await slowAborted.promise
+    let settled = false
+    void loading.then(() => { settled = true }, () => { settled = true })
+    await new Promise<void>((resolve) => { setImmediate(resolve) })
+    expect(settled).toBe(false)
+
+    releaseCleanup.resolve(undefined)
+    await expect(loading).rejects.toThrow('lookup failed')
+    await ctx.fiber.dispose()
+  })
+
+  it('aborts executable resolution when disposed during setup', async () => {
+    const ctx = new Context()
+    await ctx.plugin(Lsp)
+    await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
+    const subprocess = ctx.subprocess
+    const lookupStarted = Promise.withResolvers<AbortSignal>()
+    vi.spyOn(subprocess, 'resolveExecutable').mockImplementation(async (_command, _env, signal) => {
+      if (signal === undefined) throw new Error('missing setup signal')
+      lookupStarted.resolve(signal)
+      return await new Promise<string>((_resolve, reject) => {
+        const onAbort = (): void => {
+          reject(signal.reason instanceof Error ? signal.reason : new Error(String(signal.reason)))
+        }
+        signal.addEventListener('abort', onAbort, { once: true })
+        if (signal.aborted) onAbort()
+      })
+    })
+
+    const loading = ctx.plugin(LspLocal, config('pending', {
+      command: 'pending-lsp',
+      extensionToLanguage: { '.ts': 'typescript' },
+    }))
+    const signal = await lookupStarted.promise
+    const unrelated = await ctx.plugin(() => {})
+    await unrelated.dispose()
+    expect(signal.aborted).toBe(false)
+    const disposing = loading.dispose()
+
+    await expect(loading).rejects.toThrow('lsp-local setup disposed')
+    await expect(disposing).resolves.toBeUndefined()
+    expect(signal.aborted).toBe(true)
+    await ctx.fiber.dispose()
+  })
+
   it('rolls back earlier registrations when a later server conflicts', async () => {
     const ctx = new Context()
     await ctx.plugin(Lsp)
     await ctx.plugin(LocalSubprocessService)
+    await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
     await expect(ctx.plugin(LspLocal, {
       servers: {
         first: { command: process.execPath, extensionToLanguage: { '.ts': 'typescript' } },

packages/lsp/lsp-local/tests/typescript-server.e2e.ts

@@ -11,6 +11,7 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { Context } from 'cordis'
 import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
+import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
 import Lsp, { type LspQueryRequest, type LspQueryResult } from '@deepseek-ai/dsh-lsp'
 import * as LspLocal from '@deepseek-ai/dsh-lsp-local'
 
@@ -54,6 +55,7 @@ beforeAll(async () => {
   ctx = new Context()
   await ctx.plugin(Lsp)
   await ctx.plugin(LocalSubprocessService)
+  await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
   await ctx.plugin(LspLocal, {
     servers: {
       typescript: {

packages/lsp/lsp-local/tsconfig.json

@@ -26,6 +26,9 @@
     {
       "path": "../../llm/llm"
     },
+    {
+      "path": "../../fs/fs"
+    },
     {
       "path": "../lsp"
     },

packages/lsp/lsp/README.i18n.yaml

@@ -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/lsp/lsp/README.md
-README.md: f96fc67ec8cb95f423eff9b312b7b591ec9d3008
-README.zh.md: 9757147de692684747d9965efda6329b3bbe2638
+README.md: 5c1044be50368acf13d8c36a15d5b2bd99d02701
+README.zh.md: cc412333e63b9469319240d67269bf0192ad3858

packages/lsp/lsp/README.md

@@ -27,7 +27,7 @@ Providers register **capabilities**, not tools. `dsh-tool-lsp` is the only owner
 
 ## Vocabulary
 
-`LspQueryRequest` (`operation`, `filePath`, `position`, `workspaceRoot`) — every field required, so no field needs implementation defaulting and there is no `resolve()` step. Positions and ranges are zero-based UTF-16, matching the protocol; the tool owns the one-based cursor convention. `findReferences` always includes declarations — providers enforce this internally, so callers get no flag. `LspQueryResult` is a CLOSED discriminated union: `{ kind: 'locations'; locations; resolvedWorkspaceRoot }` for navigation, `{ kind: 'hover'; hover }` for hover (content or `null`) — consumers `switch` to exhaustiveness so a new arm breaks compilation until handled. `resolvedWorkspaceRoot` is the provider's canonical form of the request's `workspaceRoot` and the root its `file:` URIs are relative to; a caller relativizing display paths uses it, not the (possibly symlinked) request root. See `src/types.ts` for the full contracts and `src/index.ts` for the `LspError` codes, including `LSP_DISPOSED` and `LSP_MALFORMED_RESPONSE`.
+`LspQueryRequest` (`operation`, `filePath`, `position`, `workspaceRoot`) — every field required, so no field needs implementation defaulting and there is no `resolve()` step. Positions and ranges are zero-based UTF-16, matching the protocol; the tool owns the one-based cursor convention. `findReferences` always includes declarations — providers enforce this internally, so callers get no flag. `LspQueryResult` is a CLOSED discriminated union: `{ kind: 'locations'; locations; resolvedWorkspaceUri }` for navigation, `{ kind: 'hover'; hover }` for hover (content or `null`) — consumers `switch` to exhaustiveness so a new arm breaks compilation until handled. `resolvedWorkspaceUri` is the provider's canonical workspace `file:` URI; callers relativize location URIs against it instead of applying host-platform path rules to the possibly symlinked request root. See `src/types.ts` for the full contracts and `src/index.ts` for the `LspError` codes, including `LSP_DISPOSED` and `LSP_MALFORMED_RESPONSE`.
 
 ## Model Experience
 

packages/lsp/lsp/README.zh.md

@@ -8,7 +8,7 @@
 
 | 包 | 职责 |
 |---|---|
-| `@deepseek-ai/dsh-lsp`（本包） | 接口：服务、以带品牌类型的 id 和扩展名映射为键的提供方注册表、逐查询选择、请求／结果词汇、`LspError` 分类体系 |
+| `@deepseek-ai/dsh-lsp`（本包） | 接口：服务、以品牌化 id + 扩展名映射为 key 的提供方注册表、逐查询选择、请求／结果词汇、`LspError` 分类体系 |
 | `@deepseek-ai/dsh-lsp-local` | 通用本地后端，注册已配置的 stdio 语言服务器提供方 |
 | `@deepseek-ai/dsh-tool-lsp` | 面向模型的 `lsp` 工具，基于 `ctx.lsp` |
 
@@ -18,16 +18,16 @@
 
 | 成员 | 语义 |
 |---|---|
-| `registerProvider(provider)` | 注册后端，以原子方式保留其带品牌类型的 `id` 与每个规范化文件扩展名。任何无效输入或冲突都不会发布内容，并抛出 `LspError`（`LSP_INVALID_PROVIDER`／`LSP_CONFLICT`）。返回释放所有保留项的 disposer。随调用 fiber 一同 dispose（资源释放）。 |
+| `registerProvider(provider)` | 注册后端，以原子方式保留其品牌化 `id` 与每个规范化文件扩展名。任何无效输入或冲突都不会发布内容，并抛出 `LspError`（`LSP_INVALID_PROVIDER`／`LSP_CONFLICT`）。返回释放所有保留项的 disposer。随调用 fiber 释放。 |
 | `query(request, signal?)` | 按文件最终扩展名选择提供方，从该提供方的映射派生 `languageId`，并运行一次查询。没有匹配项时抛出 `LspError` `LSP_UNAVAILABLE`。 |
 
-选择逐查询进行且与顺序无关：一个提供方独占一组扩展名，因此注册和 HMR（热模块替换）顺序绝不会改变路由。扩展名 key 规范化为小写且以点开头；`languageId` 只用于同步临时文档，绝不参与选择。第一版没有 glob、language-id 或显式路由 selector。
+选择逐查询进行且与顺序无关：一个提供方独占一组扩展名，因此注册和 HMR 顺序绝不会改变路由。扩展名 key 规范化为小写且以点开头；`languageId` 只用于同步临时文档，绝不参与选择。第一版没有 glob、language-id 或显式路由 selector。
 
-提供方注册的是**能力**，而非工具。`dsh-tool-lsp` 是面向模型名称、描述、提示词指引、schema 和呈现的唯一 owner。
+提供方注册的是**能力** 而非工具。`dsh-tool-lsp` 是面向模型名称、描述、提示词指引、schema 和呈现的唯一 owner。
 
 ## 词汇
 
-`LspQueryRequest`（`operation`、`filePath`、`position`、`workspaceRoot`）：每个字段都必填，因此没有字段需要实现默认值，也不存在 `resolve()` 步骤。位置与范围使用从零开始的 UTF-16，与协议一致；工具负责从 1 开始的光标约定。`findReferences` 始终包含声明，提供方在内部强制执行，因此调用方没有 flag。`LspQueryResult` 是封闭的判别联合：导航使用 `{ kind: 'locations'; locations; resolvedWorkspaceRoot }`，悬停使用 `{ kind: 'hover'; hover }`（内容或 `null`）；消费方通过 `switch` 实现穷尽检查，因此新增分支会使编译失败，直到完成处理。`resolvedWorkspaceRoot` 是提供方对请求 `workspaceRoot` 的规范形式，也是其 `file:` URI 所相对的根；调用方把显示路径相对化时使用该值，而非可能含符号链接的请求根。完整契约见 `src/types.ts`；`src/index.ts` 给出 `LspError` 代码，包括 `LSP_DISPOSED` 和 `LSP_MALFORMED_RESPONSE`。
+`LspQueryRequest`（`operation`、`filePath`、`position`、`workspaceRoot`）：每个字段都必填，因此没有字段需要实现默认值，也不存在 `resolve()` 步骤。位置与范围使用从零开始的 UTF-16，与协议一致；工具拥有从 1 开始的光标约定。`findReferences` 始终包含声明，提供方在内部强制执行，因此调用方没有 flag。`LspQueryResult` 是封闭的判别联合：导航使用 `{ kind: 'locations'; locations; resolvedWorkspaceUri }`，悬停使用 `{ kind: 'hover'; hover }`（内容或 `null`）；消费方通过 `switch` 实现穷尽检查，因此新增分支会使编译失败，直到完成处理。`resolvedWorkspaceUri` 是提供方的规范工作区 `file:` URI；调用方相对化位置 URI 时以它为基准，而不是对可能含符号链接的请求根应用宿主平台路径规则。完整契约见 `src/types.ts`；`src/index.ts` 给出 `LspError` code，包括 `LSP_DISPOSED` 和 `LSP_MALFORMED_RESPONSE`。
 
 ## 模型体验
 
@@ -39,6 +39,6 @@
 
 ## 已知限制与暂缓事项
 
-- **同一运行时内扩展名归属互斥**：两个提供方不能同时声明 `.ts`，即使语言 ID 不同；重叠会使注册失败。预期扩展是在注册之上增加部署配置的 selector；它可以放宽互斥保留，而无需把提供方选择加入模型输入（见 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)）。
+- **同一运行时内扩展名归属互斥**：两个提供方不能同时声明 `.ts`，即使 language id 不同；重叠会使注册失败。预期扩展是在注册之上增加部署配置的 selector；它可以放宽互斥保留，而无需把提供方选择加入模型输入（见 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)）。
 - **仅四种操作**：symbol 与 call hierarchy 暂缓（它们需要不同 schema）；diagnostics 需要独立的新鲜度／累积规则；修改操作（rename、code action、formatting）需要独立工具，并集成预览、权限和写入策略。
-- **没有观测接口**：可用性只能通过运行 `query()` 并按抛出的 `LspError` 代码进行路由来观测；没有提供方变更事件或能力状态查询。
+- **没有观测表层**：可用性只能通过运行 `query()` 并按抛出的 `LspError` code 路由来观测；没有提供方变更事件或能力状态查询。

packages/lsp/lsp/src/types.ts

@@ -77,13 +77,13 @@ export interface LspHover {
  * `goToImplementation`) normalize to `locations`; `hover` normalizes to content or `null`.
  * Consumers `switch` on `kind` to exhaustiveness so a new arm breaks compilation until handled.
  *
- * The `locations` variant carries `resolvedWorkspaceRoot`: the provider's canonical form of the
- * request's `workspaceRoot`, and the root its `file:` location URIs are relative to. A caller that
- * relativizes display paths MUST use this, not the request's (possibly symlinked) `workspaceRoot`;
- * otherwise a symlinked workspace misclassifies in-workspace results as external.
+ * The `locations` variant carries `resolvedWorkspaceUri`: the provider's canonical `file:` URI for
+ * the request's workspace root. A caller that relativizes location URIs MUST use this, not parse the
+ * request's possibly symlinked process path with host-platform rules; the execution platform may
+ * differ from the caller's.
  */
 export type LspQueryResult =
-  | { readonly kind: 'locations'; readonly locations: readonly LspLocation[]; readonly resolvedWorkspaceRoot: string }
+  | { readonly kind: 'locations'; readonly locations: readonly LspLocation[]; readonly resolvedWorkspaceUri: string }
   | { readonly kind: 'hover'; readonly hover: LspHover | null }
 
 /**

packages/lsp/lsp/tests/lsp.spec.ts

@@ -13,7 +13,7 @@ import Lsp, {
 function makeProvider(
   id: string,
   extensionToLanguage: Record<string, string>,
-  result: LspQueryResult = { kind: 'locations', locations: [], resolvedWorkspaceRoot: '/ws' },
+  result: LspQueryResult = { kind: 'locations', locations: [], resolvedWorkspaceUri: 'file:///ws' },
 ): LspProvider & { seen: LspProviderQuery[]; seenSignals: (AbortSignal | undefined)[] } {
   const seen: LspProviderQuery[] = []
   const seenSignals: (AbortSignal | undefined)[] = []
@@ -63,7 +63,7 @@ describe('Lsp registration', () => {
     const provider = makeProvider('ts', { '.ts': 'typescript' })
     const dispose = lsp.registerProvider(provider)
 
-    await expect(lsp.query(query('a.ts'))).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: '/ws' })
+    await expect(lsp.query(query('a.ts'))).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceUri: 'file:///ws' })
     expect(provider.seen[0]).toMatchObject({ filePath: 'a.ts', languageId: 'typescript' })
 
     dispose()
@@ -148,7 +148,7 @@ describe('Lsp registration', () => {
     const py = makeProvider('py', { '.py': 'python' })
     lsp.registerProvider(ts)
     lsp.registerProvider(py)
-    await expect(lsp.query(query('a.py'))).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: '/ws' })
+    await expect(lsp.query(query('a.py'))).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceUri: 'file:///ws' })
     await expect(lsp.query(query('a.ts', 'hover'))).resolves.toEqual(hover)
   })
 
@@ -172,7 +172,7 @@ describe('Lsp registration', () => {
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
       inner.lsp.registerProvider(makeProvider('ts', { '.ts': 'typescript' }))
     }, { inject: ['lsp'] }))
-    await expect(lsp.query(query('a.ts'))).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: '/ws' })
+    await expect(lsp.query(query('a.ts'))).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceUri: 'file:///ws' })
     await fiber.dispose()
     await expect(lsp.query(query('a.ts'))).rejects.toThrow(expect.objectContaining({ code: 'LSP_UNAVAILABLE' }))
   })

packages/lsp/tool-lsp/README.i18n.yaml

@@ -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/lsp/tool-lsp/README.md
-README.md: 9b4130015ddf7e1cad6fa9a0e131be86f3bd4bcc
-README.zh.md: a3f59fb6e39bb6c19cc2ef06d0bc256633e75386
+README.md: 1e89abf22e853735c094d17047b2c946af210905
+README.zh.md: 396b4d22ada8761b17c01d0c40e4bb4cfe80ca67

packages/lsp/tool-lsp/README.md

@@ -10,7 +10,7 @@ Namespace plugin (`name` / `inject` / `Config` / `apply`, no default export). In
 
 `lsp` accepts `operation` (`goToDefinition` | `findReferences` | `goToImplementation` | `hover`), `file_path`, `line`, and `character`. `line` and `character` are positive, one-based UTF-16 cursor coordinates; the tool converts them to the seam's zero-based positions and converts rendered locations back. `findReferences` includes declarations so impact analysis does not omit the defining site. Provider, language id, workspace root, limits, timeout, initialization, and executable stay outside model input.
 
-The tool requires the workspace root from the session `header.cwd`, with no fallback: absence fails as `LSP_WORKSPACE_REQUIRED` before querying. Its canonical result is the complete normalized seam union: `{ kind: "locations", locations, resolvedWorkspaceRoot }` or `{ kind: "hover", hover }`; Code Mode can inspect every acquired location and zero-based range directly. Native rendering then projects stable, file-grouped `path:line:character` entries relativized against the result's `resolvedWorkspaceRoot` (the provider's canonical root), not the session cwd — so a symlinked cwd still renders in-workspace results as workspace-relative paths; a `file:` URI becomes a workspace-relative path (inside) or absolute path (outside), and any other URI stays verbatim. Empty locations and `null` hover are successful no-result responses; malformed provider payloads remain structured errors.
+The tool requires the workspace root from the session `header.cwd`, with no fallback: absence fails as `LSP_WORKSPACE_REQUIRED` before querying. Its canonical result is the complete normalized seam union: `{ kind: "locations", locations, resolvedWorkspaceUri }` or `{ kind: "hover", hover }`; Code Mode can inspect every acquired location and zero-based range directly. Native rendering projects stable, file-grouped `path:line:character` entries against the provider's canonical workspace URI rather than applying host-platform path rules to the session cwd. A `file:` URI becomes a workspace-relative path inside that URI or a URI-derived absolute path outside it; malformed and non-`file:` URIs stay verbatim. Empty locations and `null` hover are successful no-result responses; malformed provider payloads remain structured errors.
 
 ## Configuration
 

packages/lsp/tool-lsp/README.zh.md

@@ -8,13 +8,13 @@ Namespace 插件（`name`／`inject`／`Config`／`apply`，无默认导出）
 
 ## 工具
 
-`lsp` 接受 `operation`（`goToDefinition` | `findReferences` | `goToImplementation` | `hover`）、`file_path`、`line` 和 `character`。`line` 与 `character` 是正的、从 1 开始的 UTF-16 光标坐标；工具将其转换为 seam 从零开始的位置，并把渲染位置转换回来。`findReferences` 包含声明，因此影响分析不会遗漏定义位置。提供方、语言 ID、工作区根目录、限制、超时、初始化和可执行文件均不进入模型输入。
+`lsp` 接受 `operation`（`goToDefinition` | `findReferences` | `goToImplementation` | `hover`）、`file_path`、`line` 和 `character`。`line` 与 `character` 是正的、从 1 开始的 UTF-16 光标坐标；工具将其转换为 seam 从零开始的位置，并把渲染位置转换回来。`findReferences` 包含声明，因此影响分析不会遗漏定义位置。提供方、language id、Workspace 根、限制、超时、初始化和可执行文件均不进入模型输入。
 
-该工具要求从会话 `header.cwd` 取得工作区根目录，没有回退值：缺失时会在查询前以 `LSP_WORKSPACE_REQUIRED` 失败。其规范结果是完整的已规范化 seam 联合：`{ kind: "locations", locations, resolvedWorkspaceRoot }` 或 `{ kind: "hover", hover }`；Code Mode 可以直接检查每个已取得的位置和从零开始的范围。Native 渲染随后投影出稳定的、按文件分组的 `path:line:character` 条目，并相对于结果的 `resolvedWorkspaceRoot`（提供方的规范根目录）而非会话 cwd；因此，即使 cwd 包含符号链接，工作区内的结果仍渲染为相对路径。`file:` URI 位于工作区内时成为工作区相对路径，位于工作区外时成为绝对路径，其他 URI 保持原样。空位置和 `null` hover 都是成功的无结果响应；格式错误的提供方载荷仍是结构化错误。
+该工具要求从会话 `header.cwd` 取得 Workspace 根，没有回退值：缺失时会在查询前以 `LSP_WORKSPACE_REQUIRED` 失败。其规范结果是完整的已规范化 seam 联合：`{ kind: "locations", locations, resolvedWorkspaceUri }` 或 `{ kind: "hover", hover }`；Code Mode 可以直接检查每个已取得的位置和从零开始的范围。原生渲染以提供方的规范工作区 URI 为基准，投影按文件稳定分组的 `path:line:character` 条目，而不对会话 cwd 应用宿主平台路径规则。`file:` URI 落在该工作区 URI 内时成为工作区相对路径，位于其外时成为从 URI 派生的绝对路径；格式错误的 URI 与非 `file:` URI 保持原样。空位置和 `null` hover 都是成功的无结果响应；格式错误的提供方载荷仍是结构化错误。
 
 ## 配置
 
-| 配置键 | 默认值 | 含义 |
+| Key | 默认值 | 含义 |
 |---|---|---|
 | `maxLocations` | `100` | 出现省略标记前可渲染位置的最大数量。 |
 | `maxResultChars` | `16000` | 完整渲染结果的最大长度，包括截断元数据。 |
@@ -40,7 +40,7 @@ Use search/read for ordinary navigation. Use lsp when textual matches are ambigu
 
 #### KV Cache 影响
 
-只要插件作用域与指引文本不变，前缀就保持稳定；激活或 dispose（资源释放）可能使从该区段起的复用失效。
+只要插件 scope 与指引文本不变，前缀就保持稳定；激活或释放可能使从该区段起的复用失效。
 
 ### 工具 schema
 
@@ -54,13 +54,13 @@ Use search/read for ordinary navigation. Use lsp when textual matches are ambigu
 
 #### KV Cache 影响
 
-只要可见工具定义与顺序不变，前缀就保持稳定；注册生命周期或作用域限制可能使从第一个变化的 schema token 起的复用失效。
+只要可见工具定义与顺序不变，前缀就保持稳定；注册生命周期或 scope 限制可能使从第一个变化的 schema token 起的复用失效。
 
 ### 结果
 
 #### 模型看到的内容
 
-按文件分组的 `path:line:character` 位置行或规范化 hover 文本，先由 `maxLocations` 限制，再由 `maxResultChars` 限制；省略与截断标记计入完整字符上限。这些上限只影响 Native／模型呈现，不影响规范值。空结果使用不同的 `No results.`／`No hover information.` 行。
+按文件分组的 `path:line:character` 位置行或规范化 hover 文本，先由 `maxLocations` 限制，再由 `maxResultChars` 限制；省略与截断标记计入完整字符上限。这些上限只影响原生／模型呈现，不影响规范值。空结果使用不同的 `No results.`／`No hover information.` 行。
 
 #### Token 影响
 
@@ -74,7 +74,7 @@ Use search/read for ordinary navigation. Use lsp when textual matches are ambigu
 
 #### 模型看到的内容
 
-无。客户端渲染通用搜索卡片：`{ card: 'generic', kind: 'search', title, locations: [{ path, line }] }`；从 args 派生的标题携带操作与从 1 开始的光标，编辑器跟随定位会聚焦所查询的行，标题则保留列号。
+无。客户端渲染通用搜索卡片：`{ card: 'generic', kind: 'search', title, locations: [{ path, line }] }`；从 args 派生的标题携带操作与从 1 开始的光标，跟随焦点对准查询行，标题则保留列号。
 
 #### Token 影响
 
@@ -86,5 +86,5 @@ Use search/read for ordinary navigation. Use lsp when textual matches are ambigu
 
 ## 已知限制与暂缓事项
 
-- **UTF-16 光标坐标**：列坐标与协议精确一致，但模型难以在非 BMP 字符周围计数；不在符号上的位置可能返回空结果，因此提示词解释了该约定，但不会鼓励宽泛使用 LSP（见 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)）。
+- **UTF-16 光标坐标**：列坐标与协议精确一致，但模型难以在非 BMP 字符周围计数；非 symbol 位置可能返回空结果，因此提示词解释了该约定，但不会鼓励宽泛使用 LSP（见 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-15-lsp-capability-seam.md)）。
 - **不承诺跨服务器完整性**：受支持的服务器仍可能根据索引就绪情况返回空或部分结果；该工具不承诺跨语言或服务器的完整性。

packages/lsp/tool-lsp/package.json

@@ -38,11 +38,13 @@
   },
   "devDependencies": {
     "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-fs-local": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-lsp": "workspace:^",
     "@deepseek-ai/dsh-lsp-local": "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-timeout-policy": "workspace:^",

packages/lsp/tool-lsp/src/index.ts

@@ -138,7 +138,7 @@ export function apply(ctx: Context, config: Config): void {
                   },
                 },
               },
-              resolvedWorkspaceRoot: { type: 'string', required: true },
+              resolvedWorkspaceUri: { type: 'string', required: true },
             },
           },
           {
@@ -167,7 +167,7 @@ export function apply(ctx: Context, config: Config): void {
       render: (_args, value) => {
         switch (value.kind) {
           case 'locations':
-            return [{ type: 'text', text: formatLocations(value.locations, value.resolvedWorkspaceRoot, resolved.maxLocations, resolved.maxResultChars) }]
+            return [{ type: 'text', text: formatLocations(value.locations, value.resolvedWorkspaceUri, resolved.maxLocations, resolved.maxResultChars) }]
           case 'hover':
             return [{ type: 'text', text: formatHover(value.hover, resolved.maxResultChars) }]
           /* v8 ignore next -- exhaustive over the output schema's closed union; unreachable. */
@@ -200,7 +200,7 @@ export function apply(ctx: Context, config: Config): void {
                 end: { line: location.range.end.line, character: location.range.end.character },
               },
             })),
-            resolvedWorkspaceRoot: result.resolvedWorkspaceRoot,
+            resolvedWorkspaceUri: result.resolvedWorkspaceUri,
           }
         case 'hover':
           return {

packages/lsp/tool-lsp/src/render.ts

@@ -6,10 +6,10 @@
  * @module @deepseek-ai/dsh-tool-lsp/render
  */
 
-import { fileURLToPath } from 'node:url'
-import { isAbsolute, relative, sep } from 'node:path'
 import type { GenericCallView } from '@deepseek-ai/dsh-tools'
 import type { LspHover, LspLocation, LspOperation, LspPosition } from '@deepseek-ai/dsh-lsp'
+import { posix, win32 } from 'node:path'
+import { fileURLToPath } from 'node:url'
 
 /** The four operations the tool exposes, as a runtime tuple for schema enum + validation. */
 export const LSP_OPERATIONS: readonly LspOperation[] = ['goToDefinition', 'findReferences', 'goToImplementation', 'hover']
@@ -74,17 +74,17 @@ function oneBased(value: number, name: string): number {
 /**
  * Render a locations result grouped by file, converting each zero-based location back to a one-based
  * `path:line:character` entry. A `file:` URI inside the workspace becomes a workspace-relative path;
- * outside it, an absolute path; a non-`file:` URI is kept verbatim. Applies `maxLocations` and
+ * outside it, a URI-derived absolute path; a non-`file:` URI is kept verbatim. Applies `maxLocations` and
  * appends an omission marker when it truncates by count, then applies the complete result cap.
  * @param locations - the seam's locations (possibly empty).
- * @param workspaceRoot - the canonical workspace root for relativizing `file:` paths.
+ * @param workspaceUri - the provider's canonical workspace `file:` URI.
  * @param maxLocations - the cap before truncation.
  * @param maxResultChars - the complete rendered-text cap, including truncation metadata.
  * @returns the rendered text; a distinct no-result line when there are none.
  */
 export function formatLocations(
   locations: readonly LspLocation[],
-  workspaceRoot: string,
+  workspaceUri: string,
   maxLocations: number,
   maxResultChars: number,
 ): string {
@@ -93,7 +93,7 @@ export function formatLocations(
   const omitted = locations.length - shown.length
   const grouped = new Map<string, string[]>()
   for (const location of shown) {
-    const path = renderUri(location.uri, workspaceRoot)
+    const path = renderUri(location.uri, workspaceUri)
     const line = location.range.start.line + 1
     const character = location.range.start.character + 1
     const entries = grouped.get(path) ?? []
@@ -128,27 +128,50 @@ function boundResult(text: string, maxChars: number, label: string): string {
 }
 
 /**
- * Resolve a location URI to a display path. A `file:` URI accepted by Node becomes workspace-relative
- * (inside) or absolute (outside); any other URI is returned verbatim.
+ * Resolve a location URI without applying the harness host's path rules. A valid `file:` URI becomes
+ * workspace-relative when it is under the provider's canonical workspace URI, or a URI-derived
+ * absolute path otherwise; malformed and non-`file:` URIs remain verbatim.
  * @param uri - the target URI from the seam.
- * @param workspaceRoot - the canonical workspace root.
+ * @param workspaceUri - the provider's canonical workspace `file:` URI.
  * @returns the display path or the verbatim URI.
  */
-export function renderUri(uri: string, workspaceRoot: string): string {
+export function renderUri(uri: string, workspaceUri: string): string {
   if (!uri.startsWith('file:')) return uri
-  let absolute: string
+  let target: URL
+  let workspace: URL
   try {
-    absolute = fileURLToPath(uri)
+    target = new URL(uri)
+    workspace = new URL(workspaceUri)
   } catch {
-    // A malformed file: URI is not a path we can resolve; show it verbatim.
     return uri
   }
-  const rel = relative(workspaceRoot, absolute)
-  if (rel === '') return '.'
-  // A leading `..` SEGMENT (or an absolute rel) means outside the workspace; guard against a false
-  // positive on an in-workspace path whose first component merely starts with dots (e.g. `..gen/x`).
-  const outside = rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)
-  return outside ? absolute : rel.split(sep).join('/')
+  if (workspace.protocol !== 'file:') return uri
+  // A `file:` URI does not carry its world's OS, so a leading `/X:` segment is
+  // read as a Windows drive. A POSIX workspace literally rooted at `/c:/...`
+  // would mis-render (display only; edits and reads use the exact URI).
+  const drivePath = /^\/[a-z](?::|%3A)/iu
+  const windowsWorld = workspace.hostname.length > 0 || drivePath.test(workspace.pathname)
+  const targetWindowsWorld = windowsWorld && (target.hostname.length > 0 || drivePath.test(target.pathname))
+  const workspacePath = filePath(workspace, windowsWorld)
+  const targetPath = filePath(target, targetWindowsWorld)
+  if (workspacePath === undefined || targetPath === undefined) return uri
+  if (windowsWorld !== targetWindowsWorld) return targetPath
+  const path = windowsWorld ? win32 : posix
+  const relative = path.relative(workspacePath, targetPath)
+  const outside = relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)
+  const rendered = relative === '' ? '.' : outside ? targetPath : relative
+  return windowsWorld ? rendered.replaceAll('\\', '/') : rendered
+}
+
+/** Decode a file URL for its execution world while containing malformed URL failures. */
+function filePath(url: URL, windows: boolean): string | undefined {
+  try {
+    const path = fileURLToPath(url, { windows })
+    return path.includes('\0') ? undefined : path
+  } catch {
+    // `fileURLToPath` rejects malformed escapes, authorities, and encoded path separators.
+    return undefined
+  }
 }
 
 /**

packages/lsp/tool-lsp/tests/integration.spec.ts

@@ -6,6 +6,7 @@ import { pathToFileURL } from 'node:url'
 import { Context } from 'cordis'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
+import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
 import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
 import Lsp from '@deepseek-ai/dsh-lsp'
 import * as LspLocal from '@deepseek-ai/dsh-lsp-local'
@@ -50,6 +51,7 @@ async function mount(hang: boolean, timeoutMs?: number): Promise<Context> {
   await ctx.plugin(SystemPrompt)
   await ctx.plugin(ToolRegistry)
   await ctx.plugin(Lsp)
+  await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
   await ctx.plugin(LocalSubprocessService)
   await ctx.plugin(LspLocal, {
     servers: {

packages/lsp/tool-lsp/tests/render.spec.ts

@@ -14,6 +14,7 @@ import {
 import type { LspLocation } from '@deepseek-ai/dsh-lsp'
 
 const WS = resolve('/home/u/proj')
+const WS_URI = pathToFileURL(WS).href
 
 function loc(uri: string, line: number, character = 0): LspLocation {
   return { uri, range: { start: { line, character }, end: { line, character: character + 1 } } }
@@ -48,64 +49,92 @@ describe('parseLspArgs', () => {
 describe('renderUri', () => {
   it('relativizes a file: URI inside the workspace with forward slashes', () => {
     const uri = pathToFileURL(join(WS, 'src', 'a.ts')).href
-    expect(renderUri(uri, WS)).toBe('src/a.ts')
+    expect(renderUri(uri, WS_URI)).toBe('src/a.ts')
   })
 
   it('returns an absolute path for a file: URI outside the workspace', () => {
     const outside = resolve(WS, '..', 'other', 'lib', 'b.ts')
     const uri = pathToFileURL(outside).href
-    expect(renderUri(uri, WS)).toBe(outside)
+    expect(renderUri(uri, WS_URI)).toBe(outside)
   })
 
   it('renders the workspace root itself as "."', () => {
-    expect(renderUri(pathToFileURL(WS).href, WS)).toBe('.')
+    expect(renderUri(WS_URI, WS_URI)).toBe('.')
   })
 
   it('keeps an in-workspace path whose first segment starts with dots relative', () => {
     // `..generated` is a real in-workspace dir, not a parent escape; only a `..` segment is external.
     const uri = pathToFileURL(join(WS, '..generated', 'a.ts')).href
-    expect(renderUri(uri, WS)).toBe('..generated/a.ts')
+    expect(renderUri(uri, WS_URI)).toBe('..generated/a.ts')
+  })
+
+  it('relativizes Windows execution-world URIs on a non-Windows host', () => {
+    expect(renderUri('file:///C:/WORKSPACE/src/a.ts', 'file:///c:/workspace')).toBe('src/a.ts')
+    expect(renderUri('file:///D:/lib/b.ts', 'file:///C:/workspace')).toBe('D:/lib/b.ts')
+  })
+
+  it('renders remote file authorities without host path conversion', () => {
+    expect(renderUri('file://server/share/workspace/a.ts', 'file://server/share/workspace')).toBe('a.ts')
+    expect(renderUri('file://SERVER/share/workspace/src/A.ts', 'file://server/Share/Workspace')).toBe('src/A.ts')
+    expect(renderUri('file://other/share/b.ts', 'file://server/share/workspace')).toBe('//other/share/b.ts')
+    expect(renderUri('file:///D:/lib/a.ts', 'file://server/share/workspace')).toBe('D:/lib/a.ts')
+    expect(renderUri('file:///a.ts', 'file://server/')).toBe('/a.ts')
+    expect(renderUri('file:///a.ts', 'file:///')).toBe('a.ts')
+  })
+
+  it('preserves backslashes as ordinary POSIX filename characters', () => {
+    expect(renderUri('file:///home/u/proj/dir%5Cname/a.ts', WS_URI)).toBe('dir\\name/a.ts')
+  })
+
+  it('keeps malformed or mismatched URI coordinates verbatim', () => {
+    expect(renderUri('file://[', WS_URI)).toBe('file://[')
+    expect(renderUri('file:///a.ts', 'https://example.com/workspace')).toBe('file:///a.ts')
+    expect(renderUri('file:///a.ts', 'file:///bad%ZZ')).toBe('file:///a.ts')
+    expect(renderUri('file:///C:/workspace/bad%5Cpath', 'file:///C:/workspace')).toBe('file:///C:/workspace/bad%5Cpath')
+    expect(renderUri('file:///short', 'file:///short/deeper')).toBe('/short')
+    expect(renderUri('file:///', 'file:///C:/workspace')).toBe('/')
   })
 
   it('keeps a non-file URI verbatim', () => {
-    expect(renderUri('untitled:Untitled-1', WS)).toBe('untitled:Untitled-1')
-    expect(renderUri('jdt://contents/Foo.class', WS)).toBe('jdt://contents/Foo.class')
+    expect(renderUri('untitled:Untitled-1', WS_URI)).toBe('untitled:Untitled-1')
+    expect(renderUri('jdt://contents/Foo.class', WS_URI)).toBe('jdt://contents/Foo.class')
   })
 
   it('keeps a malformed file: URI verbatim when it cannot be parsed to a path', () => {
     // An encoded path separator is invalid on every platform and must remain verbatim.
-    expect(renderUri('file:///bad%2Fpath', WS)).toBe('file:///bad%2Fpath')
+    expect(renderUri('file:///bad%2Fpath', WS_URI)).toBe('file:///bad%2Fpath')
+    expect(renderUri('file:///bad%00path', WS_URI)).toBe('file:///bad%00path')
   })
 })
 
 describe('formatLocations', () => {
   it('renders a no-result line for an empty list', () => {
-    expect(formatLocations([], WS, DEFAULT_MAX_LOCATIONS, DEFAULT_MAX_RESULT_CHARS)).toBe('No results.')
+    expect(formatLocations([], WS_URI, DEFAULT_MAX_LOCATIONS, DEFAULT_MAX_RESULT_CHARS)).toBe('No results.')
   })
 
   it('renders one-based path:line:character grouped by file', () => {
     const a = pathToFileURL(join(WS, 'a.ts')).href
-    const text = formatLocations([loc(a, 0, 0), loc(a, 4, 2)], WS, DEFAULT_MAX_LOCATIONS, DEFAULT_MAX_RESULT_CHARS)
+    const text = formatLocations([loc(a, 0, 0), loc(a, 4, 2)], WS_URI, DEFAULT_MAX_LOCATIONS, DEFAULT_MAX_RESULT_CHARS)
     expect(text).toBe('a.ts:1:1\na.ts:5:3')
   })
 
   it('caps at maxLocations and marks the omission', () => {
     const a = pathToFileURL(join(WS, 'a.ts')).href
     const many = Array.from({ length: 5 }, (_, i) => loc(a, i))
-    const text = formatLocations(many, WS, 2, DEFAULT_MAX_RESULT_CHARS)
+    const text = formatLocations(many, WS_URI, 2, DEFAULT_MAX_RESULT_CHARS)
     expect(text).toContain('a.ts:1:1')
     expect(text).toContain('3 more locations omitted (limit 2).')
   })
 
   it('uses the singular omission marker for exactly one extra', () => {
     const a = pathToFileURL(join(WS, 'a.ts')).href
-    const text = formatLocations([loc(a, 0), loc(a, 1)], WS, 1, DEFAULT_MAX_RESULT_CHARS)
+    const text = formatLocations([loc(a, 0), loc(a, 1)], WS_URI, 1, DEFAULT_MAX_RESULT_CHARS)
     expect(text).toContain('1 more location omitted (limit 1).')
   })
 
   it('caps the complete location text even when one URI is enormous', () => {
     const maxResultChars = 80
-    const text = formatLocations([loc(`custom:${'x'.repeat(1_000_000)}`, 0)], WS, 1, maxResultChars)
+    const text = formatLocations([loc(`custom:${'x'.repeat(1_000_000)}`, 0)], WS_URI, 1, maxResultChars)
     expect(text).toHaveLength(maxResultChars)
     expect(text).toContain('locations truncated')
   })

packages/lsp/tool-lsp/tests/tool-lsp.spec.ts

@@ -44,6 +44,7 @@ let seq = 0
 const testToolSignal = new AbortController().signal
 const workspaceRoot = resolve('/virtual/workspace')
 const resolvedWorkspaceRoot = resolve('/virtual/real-workspace')
+const resolvedWorkspaceUri = pathToFileURL(resolvedWorkspaceRoot).href
 const workspaceAlias = resolve('/virtual/workspace-alias')
 /** `cwd: null` means "no agent" (tests LSP_WORKSPACE_REQUIRED); a string is the session cwd. */
 function call(ctx: Context, args: unknown, cwd: string | null = workspaceRoot) {
@@ -59,7 +60,7 @@ function call(ctx: Context, args: unknown, cwd: string | null = workspaceRoot) {
 const okLocations: LspQueryResult = {
   kind: 'locations',
   locations: [{ uri: pathToFileURL(join(workspaceRoot, 'a.ts')).href, range: { start: { line: 0, character: 0 }, end: { line: 0, character: 1 } } }],
-  resolvedWorkspaceRoot: workspaceRoot,
+  resolvedWorkspaceUri: pathToFileURL(workspaceRoot).href,
 }
 
 describe('tool-lsp registration', () => {
@@ -138,7 +139,7 @@ describe('tool-lsp execution', () => {
     const { ctx } = await mount(stubProvider(() => ({
       kind: 'locations',
       locations,
-      resolvedWorkspaceRoot: cappedWorkspaceRoot,
+      resolvedWorkspaceUri: pathToFileURL(cappedWorkspaceRoot).href,
     })), { maxLocations: 1 })
     const result = await call(ctx, { operation: 'findReferences', file_path: 'a.ts', line: 1, character: 1 }, cappedWorkspaceRoot)
     expect(result.content[0]).toEqual({
@@ -147,17 +148,17 @@ describe('tool-lsp execution', () => {
     })
     expect(result).toMatchObject({
       isError: false,
-      value: { kind: 'locations', locations, resolvedWorkspaceRoot: cappedWorkspaceRoot },
+      value: { kind: 'locations', locations, resolvedWorkspaceUri: pathToFileURL(cappedWorkspaceRoot).href },
     })
   })
 
-  it('relativizes against the provider resolvedWorkspaceRoot, not the session cwd', async () => {
+  it('relativizes against the provider resolvedWorkspaceUri, not the session cwd', async () => {
     // A symlinked session cwd resolves to the real path that contains the provider's location URIs.
     // Relativizing against the alias would misclassify the location as external.
     const provider = stubProvider(() => ({
       kind: 'locations',
       locations: [{ uri: pathToFileURL(join(resolvedWorkspaceRoot, 'a.ts')).href, range: { start: { line: 0, character: 0 }, end: { line: 0, character: 1 } } }],
-      resolvedWorkspaceRoot,
+      resolvedWorkspaceUri,
     }))
     const { ctx } = await mount(provider)
     const result = await call(ctx, { operation: 'goToDefinition', file_path: 'a.ts', line: 1, character: 1 }, workspaceAlias)

packages/pty/README.i18n.yaml

@@ -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/pty/README.md
-README.md: 9c8206464d45b1be1d6ee3861c57c128e77686c5
-README.zh.md: 70d081e60a7db61443ed616b64586a93c119a640
+README.md: a4f743056b4a524be9623b0f700f37e0534b463f
+README.zh.md: c84ad3f1b59afcdbbd111f1b82c57c56aa24fdcf

packages/pty/README.md

@@ -2,13 +2,12 @@
 
 English | [中文](README.zh.md)
 
-This family provides persistent, owner-scoped pseudo-terminal sessions for interactive or stateful terminal work. It complements one-shot bash execution.
+`PTY` stands for **Pseudo-Terminal**（伪终端）. This capability provides persistent, owner-scoped terminal sessions for workflows that require state across tool calls or interactive stdin. PTY complements the one-shot bash and filesystem tools; it does not replace their stronger per-operation contracts.
 
 | Package | Role | ctx key |
 |---|---|---|
-| [`pty/`](pty/README.md) | Defines the PTY service and session lifecycle | `ctx.pty` |
-| [`pty-local/`](pty-local/README.md) | Provides local persistent terminal sessions | registers on `ctx.pty` |
-| [`tool-pty/`](tool-pty/README.md) | Exposes PTY session operations to the model | registers on `ctx.tools` |
-| [`tool-bash-persistent/`](tool-bash-persistent/README.md) | Exposes a reusable PTY-backed bash tool | registers on `ctx.tools` |
+| [`pty`](pty/README.md) (`@deepseek-ai/dsh-pty`) | Backend registry, branded ids, exact-Agent ownership, session operations, and awaited cleanup | `ctx.pty` |
+| `pty-local` (`@deepseek-ai/dsh-pty-local`) | Shell backend over `ctx.subprocess.spawnTerminal`: readiness detection, bounded terminal state, sandbox policy, and session operations | registers on `ctx.pty` |
+| `tool-pty` (`@deepseek-ai/dsh-tool-pty`) | Six model-facing tools and generic task integration for background sends | registers on `ctx.tools` |
 
-The [persistent PTY decision](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md) records the family boundary.
+The design and deferred boundaries live in the [persistent PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md).

packages/pty/README.zh.md

@@ -2,13 +2,12 @@
 
 [English](README.md) | 中文
 
-本家族为交互式或有状态的终端工作提供持久且限定所有者范围的伪终端会话，是单次 bash 执行的补充。
+`PTY` 的全称是 **Pseudo-Terminal（伪终端）**。这项能力提供持久且限定所有者范围的终端会话，适用于需要跨工具调用保留状态或使用交互式 stdin 的工作流。PTY 是单次 bash 与文件系统工具的补充，不会取代后两者更严格的逐操作契约。
 
 | 包 | 职责 | ctx 键 |
 |---|---|---|
-| [`pty/`](pty/README.md) | 定义 PTY 服务和会话生命周期 | `ctx.pty` |
-| [`pty-local/`](pty-local/README.md) | 提供本地持久终端会话 | 注册到 `ctx.pty` |
-| [`tool-pty/`](tool-pty/README.md) | 向模型公开 PTY 会话操作 | 注册到 `ctx.tools` |
-| [`tool-bash-persistent/`](tool-bash-persistent/README.md) | 公开可复用的 PTY 后端 bash 工具 | 注册到 `ctx.tools` |
+| [`pty`](pty/README.md)（`@deepseek-ai/dsh-pty`） | 后端注册表、品牌化 id、精确的 Agent 所有权、会话操作与等待完成的清理 | `ctx.pty` |
+| `pty-local`（`@deepseek-ai/dsh-pty-local`） | `ctx.subprocess.spawnTerminal` 之上的 shell 后端：就绪检测、有界终端状态、沙箱策略与会话操作 | 注册到 `ctx.pty` |
+| `tool-pty`（`@deepseek-ai/dsh-tool-pty`） | 6 个面向模型的工具，并为后台发送集成通用任务 | 注册到 `ctx.tools` |
 
-[持久 PTY 决策](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md)记录了该家族的边界。
+设计与暂缓边界记录在[持久 PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md) 中。

packages/pty/pty-local/README.i18n.yaml

@@ -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/pty/pty-local/README.md
-README.md: ba05495318127b63b3d2a6a60ec743e1ff1c5821
-README.zh.md: 81987ea0685d761507b535b7ed6eefa0888fbd54
+README.md: 5acc92853e6e8fcb8938c48e391559bf4a28fb75
+README.zh.md: 353c2a4bdac7e8402fc63071dfb6fb85dcff66d5

packages/pty/pty-local/README.md

@@ -2,15 +2,15 @@
 
 English | [中文](README.zh.md)
 
-Local Linux/macOS `node-pty` backend for `ctx.pty`; loading it on another platform fails as unsupported. It starts an interactive shell under the shared `ctx.sandboxPolicy`, strips credential-shaped ambient environment variables, retains bounded line-oriented output, detects readiness, and tears down the captured process tree rooted at the `node-pty` child.
+Persistent shell backend for `ctx.pty` over `ctx.subprocess.spawnTerminal`. It starts an interactive shell under the shared `ctx.sandboxPolicy`, retains bounded line-oriented output, and detects readiness while the subprocess provider owns PTY allocation, environment scrubbing, foreground process groups, signalling, and complete terminal-session cleanup. The same PTY backend therefore composes with local or remote execution-world providers.
 
 ## Plugin (`pty-local`)
 
-The plugin injects `pty`, `sandbox`, and `sandboxPolicy`, then registers the configured backend type (`shell`). `danger-full-access` starts the shell directly; confined modes wrap the exact shell argv through `ctx.sandbox`. At spawn, one `ctx.sandboxPolicy.resolve({ session })` call supplies both the effective mode and the session workspace root; the same root is the default shell cwd when the caller omits one. A change to a different effective mode is rejected before its `sandbox/mode` event commits while that owner has an open PTY or a spawn in progress; the fence is attached to the exact owner and therefore outlives a local-provider reload that retains existing sessions. Wait for creation to settle and close the sessions before changing modes, so a terminal opened with wider access cannot survive a downgrade.
+The plugin injects `pty`, `sandboxPolicy`, and `subprocess`, then registers the configured backend type (`shell`). `danger-full-access` starts the shell directly without requiring a sandbox provider; confined modes require a same-world `ctx.sandbox` and wrap the exact shell argv through it, failing before spawn when none is mounted. At spawn, one `ctx.sandboxPolicy.resolve({ session })` call supplies both the effective mode and the session workspace root; the same root is the default shell cwd when the caller omits one. A change to a different effective mode is rejected before its `sandbox/mode` event commits while that owner has an open PTY or a spawn in progress; the fence is attached to the exact owner and therefore outlives a provider reload that retains existing sessions. Wait for creation to settle and close the sessions before changing modes, so a terminal opened with wider access cannot survive a downgrade.
 
-Linux readiness combines a foreground-verified private bash prompt marker, foreground-process-group syscall inspection, silence fallback, and absolute timeout. macOS uses the verified prompt marker plus silence/timeout because it has no `/proc` syscall surface. A marker is not ready until printable prompt text arrives, including when the OSC marker and `PS1` are split across data callbacks; when bash prints the marker before the kernel publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win; that grace must cover at least one `pollIntervalMs` and is rejected at load otherwise. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unrecognized or unreadable process state is never a positive exact-idle signal. A foreground group's stdin wait that already existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason even when its foreground process group is not observable yet; if that close fails, `PtyBackendCleanupError` separately preserves the cleanup failure for registry disposal. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
+Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until the printable tail after the latest owned marker exactly equals the controlled `PS1`, including when the OSC marker and prompt are split across data callbacks; echoed input or output following an earlier prompt therefore cannot settle the current send. Prompt and silence evidence collected before the provider write, including while pre-write foreground inspection is pending, is discarded at the write boundary. When bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `PtyBackendCleanupError` separately preserves a cleanup failure. The caller's signal is forwarded for terminal allocation and readiness initialization; after publication the handle owns its lifetime. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; malformed UTF-8 terminal output uses replacement characters, and a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
 
-Send cancellation resolves the current foreground process group and delivers a real `SIGINT`; it never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. Close sends `SIGTERM` to descendants, waits, then sends `SIGKILL` to the union of captured survivors and newly scanned descendants so reparenting cannot hide a process from teardown. It verifies that every retained identity is gone or, on Linux, a non-executing zombie before stopping the shell; zombie entries are quiescent and are reaped as the shell exits. A survivor failure does not cache a permanently rejected close; a later close retries the teardown.
+Send cancellation marks queued input as canceled before asking the terminal handle to signal the current foreground process group with a real `SIGINT`; if asynchronous pre-write inspection later settles, it cannot execute that input. If a provider write is already in flight, signalling waits for it to settle; a rejected write sends no signal. The canceled send retains its slot until the write and foreground signalling settle, so a successor cannot receive either late bytes or that signal. A provider write or signal that never settles therefore retains the slot indefinitely; closing the session (`terminal_close`) is the recovery. The absolute deadline remains armed while cancellation waits. A signal failure is a terminal transport failure and rejects the active send. Cancellation never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. Close rejects new public signals, stops readiness polling, and awaits the handle's provider-owned complete-session termination before settling the active send as `session_exit`.
 
 ## Model Experience
 
@@ -31,6 +31,6 @@ A standing-policy change appends an owner-rendered superseding runtime-context s
 ## Known Limitations and Deferred Work
 
 - Line-oriented output is normalized; full-screen alternate-buffer interaction is unsupported.
-- Linux exact probes support x64 and arm64 UAPI tables; other architectures use prompt-marker and silence/timeout readiness.
-- A descendant that daemonizes and reparents before teardown leaves the captured tree; cleanup never broadens to the launcher PID's POSIX session because that can include unrelated processes.
+- Exact stdin-wait detection depends on the mounted subprocess provider; providers that cannot prove it use prompt-marker and silence/timeout readiness.
+- Cleanup guarantees are those of `SubprocessTerminalHandle`; provider-specific gaps belong to that implementation's contract rather than this PTY consumer.
 - Sessions do not survive harness process exit.

packages/pty/pty-local/README.zh.md

@@ -2,15 +2,15 @@
 
 [English](README.md) | 中文
 
-这个本地 Linux／macOS `node-pty` 后端实现 `ctx.pty`；在其他平台加载时会以不支持为由失败。它在共享 `ctx.sandboxPolicy` 下启动交互式 shell，移除形似凭据的环境变量，保留有界的逐行输出，检测就绪状态，并清理以 `node-pty` 子进程为根的已捕获进程树。
+这是一个基于 `ctx.subprocess.spawnTerminal`、为 `ctx.pty` 提供的持久 shell 后端。它在共享 `ctx.sandboxPolicy` 下启动交互式 shell，保留有界的逐行输出并检测就绪状态；进程管理提供方则负责 PTY 分配、环境清理、前台进程组、信号发送和完整终端会话清理。因此，同一个 PTY 后端可以与本地或远程执行世界提供方组合。
 
 ## 插件（`pty-local`）
 
-该插件注入 `pty`、`sandbox` 和 `sandboxPolicy`，然后注册所配置的后端类型（`shell`）。`danger-full-access` 会直接启动 shell；受限模式则通过 `ctx.sandbox` 包装确切的 shell argv。Spawn 时，一次 `ctx.sandboxPolicy.resolve({ session })` 调用会同时给出实际模式与会话工作区根目录；调用方省略 cwd 时，同一根目录也是 shell 的默认 cwd。当某个所有者存在开放的 PTY 或正在进行 spawn 时，如果配置变更会得到不同的实际模式，系统会在对应 `sandbox/mode` 事件提交前拒绝该变更。该限制绑定到确切所有者，因此即使本地提供方重新加载并保留现有会话，它仍然有效。更改模式前，请等待创建完成并关闭会话，避免以更宽权限打开的终端在权限降级后继续存在。
+该插件注入 `pty`、`sandboxPolicy` 和 `subprocess`，然后注册所配置的后端类型（`shell`）。`danger-full-access` 无需沙箱提供方即可直接启动 shell；受限模式要求同一执行世界中存在 `ctx.sandbox`，并通过它包装确切的 shell argv，未挂载时会在 spawn 前失败。Spawn 时，一次 `ctx.sandboxPolicy.resolve({ session })` 调用会同时给出实际模式与会话工作区根目录；调用方省略 cwd 时，同一根目录也是 shell 的默认 cwd。当某个所有者存在开放的 PTY 或正在进行 spawn 时，如果配置变更会得到不同的实际模式，系统会在对应 `sandbox/mode` 事件提交前拒绝该变更。该限制绑定到确切所有者，因此即使提供方重新加载并保留现有会话，它仍然有效。更改模式前，请等待创建完成并关闭会话，避免以更宽权限打开的终端在权限降级后继续存在。
 
-Linux 的就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、前台进程组 syscall 检查、静默回退和绝对超时。macOS 没有 `/proc` syscall 接口，因此使用经过验证的提示符标记以及静默／超时。当可打印的提示符文本尚未到达时，即使 OSC 标记和 `PS1` 被拆到多个数据回调中，系统也不会把标记视为就绪。如果 bash 在内核发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出；该宽限至少要覆盖一个 `pollIntervalMs`，否则加载时即被拒绝。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法一直抑制推断空闲就绪直至绝对超时。无法识别或读取的进程状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝，即使当时还无法观察其前台进程组。如果关闭失败，`PtyBackendCleanupError` 会单独保留清理失败，供注册表 dispose（资源释放）时处理。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
+就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最新自有标记之后的可打印尾部与受控 `PS1` 完全相等，标记才算就绪；即使 OSC 标记和提示符被拆到多个数据回调中也一样。因此，较早提示符之后的回显输入或输出无法使当前 send 完成。提供方写入前收集的提示符与静默证据，包括写入前前台检查仍在等待时收集的证据，都会在写入边界丢弃。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法一直抑制推断空闲就绪直至绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。调用方的 signal 会转发给终端分配与就绪初始化；发布后，句柄负责其生命周期。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。格式错误的 UTF-8 终端输出使用替换字符；末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
 
-取消发送时，系统会解析当前前台进程组并发送真正的 `SIGINT`；它绝不会通过写入 `\x03` 模拟中断，因此，即使程序运行在 raw 模式下，也仍可取消。关闭操作先向后代发送 `SIGTERM` 并等待，再向已捕获的存活进程与新扫描到的后代之并集发送 `SIGKILL`，防止进程通过重新设定父进程而逃避清理。在停止 shell 前，系统会确认每个保留的进程身份都已消失，或者在 Linux 上已成为不再执行的僵尸进程；僵尸进程条目视为完全停稳，并会随 shell 退出而回收。如果仍有进程存活，失败结果不会缓存成永久拒绝的关闭操作；后续关闭仍会重试清理。
+取消发送时，系统会先把排队输入标记为已取消，再要求终端句柄向当前前台进程组发送真正的 `SIGINT`；异步写入前检查即使随后结算，也无法执行该输入。如果提供方写入已在途，信号发送会等待其结算；写入被拒绝时不会发送信号。已取消的 send 会保留其位置，直到写入与前台信号发送都结算，因此后继 send 不会收到延迟字节或该信号。因此，永不结算的提供方写入或信号会无限期保留该位置；恢复手段是关闭会话（`terminal_close`）。取消等待期间，绝对 deadline 仍保持启用。信号发送失败是终端传输失败，会拒绝活跃 send。取消绝不会通过写入 `\x03` 模拟中断，因此，即使程序运行在 raw 模式下，也仍可取消。关闭操作会拒绝新的公开信号、停止就绪轮询，并等待由句柄提供方负责的完整会话终止，然后才把活跃 send 结算为 `session_exit`。
 
 ## 模型体验
 
@@ -31,6 +31,6 @@ Linux 的就绪检测结合以下机制：由前台状态验证的私有 bash
 ## 已知限制与暂缓事项
 
 - 输出按行规范化；不支持全屏备用缓冲区交互。
-- Linux 精确探针支持 x64 与 arm64 UAPI 表；其他架构使用提示符标记和静默／超时就绪机制。
-- 如果后代进程在清理前守护化并重新设定父进程，它会脱离已捕获的进程树；清理绝不会扩大到启动器 PID 所属的整个 POSIX 会话，因为其中可能包含无关进程。
+- 精确 stdin 等待检测取决于已挂载的进程管理提供方；无法证明该状态的提供方使用提示符标记和静默／超时就绪机制。
+- 清理保证以 `SubprocessTerminalHandle` 的保证为准；提供方特定的缺口属于该实现的契约，而非这个 PTY 消费方。
 - harness 进程退出后，会话无法继续存在。

packages/pty/pty-local/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-pty-local",
-  "description": "Local node-pty backend for persistent DeepSeek Harness PTY sessions",
+  "description": "Persistent shell PTY backend over the DeepSeek Harness subprocess terminal primitive",
   "version": "0.0.1",
   "private": true,
   "type": "module",
@@ -21,12 +21,8 @@
   "files": [
     "lib/index.js",
     "lib/invariant.js",
-    "scripts/ensure-spawn-helper.mjs",
     "lib/types/**/*.d.ts"
   ],
-  "scripts": {
-    "postinstall": "node scripts/ensure-spawn-helper.mjs"
-  },
   "license": "BSD-3-Clause",
   "peerDependencies": {
     "@deepseek-ai/dsh-agent": "^0.0.1",
@@ -39,7 +35,6 @@
     "cordis": "^4.0.0-rc.7"
   },
   "dependencies": {
-    "node-pty": "^1.1.0",
     "schemastery": "^3.18.0"
   },
   "devDependencies": {
@@ -50,6 +45,7 @@
     "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-subprocess": "workspace:^",
+    "@deepseek-ai/dsh-subprocess-local": "workspace:^",
     "cordis": "^4.0.0-rc.7"
   }
 }

packages/pty/pty-local/src/index.ts

@@ -1,31 +1,28 @@
 /**
- * Local persistent PTY backend using public `node-pty` APIs, shared sandbox
- * policy, bounded output, platform readiness probes, and process-session cleanup.
+ * Persistent shell PTY backend over the subprocess terminal primitive, shared
+ * sandbox policy, bounded output, and provider-owned session cleanup.
  * @module @deepseek-ai/dsh-pty-local
  */
 
 import { Context } from 'cordis'
-import * as nodePty from 'node-pty'
-import type { IPtyForkOptions } from 'node-pty'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
 import { PtyBackendCleanupError } from '@deepseek-ai/dsh-pty'
-import { scrubbedParentEnv } from '@deepseek-ai/dsh-subprocess'
 import type { PtyBackend, PtyBackendSpawnSpec } from '@deepseek-ai/dsh-pty'
+import type { SubprocessTerminalHandle, SubprocessTerminalSpawnSpec } from '@deepseek-ai/dsh-subprocess'
 import type { SandboxExecutionPolicy } from '@deepseek-ai/dsh-sandbox'
 import { effectiveSandboxMode } from '@deepseek-ai/dsh-sandbox-policy'
 import { type Config, type ResolvedConfig, validateConfig } from './config.ts'
-import { createProcessInspector } from './process-inspector.ts'
-import type { ProcessInspector } from './process-inspector.ts'
 import { LocalPtySession } from './session.ts'
+import { CONTROLLED_PROMPT } from './sanitize.ts'
 
 export { Config } from './config.ts'
 export type { Config as PtyLocalConfig } from './config.ts'
 
 /** Cordis plugin name. */
 export const name = 'pty-local'
-/** Required services: PTY registry plus the one shared confinement policy. */
-export const inject = ['pty', 'sandbox', 'sandboxPolicy']
+/** Required services: PTY registry, shared confinement policy, and process substrate. */
+export const inject = ['pty', 'sandboxPolicy', 'subprocess']
 
 interface SandboxModeFenceState {
   pty: Context['pty']
@@ -55,14 +52,14 @@ function ensureSandboxModeFence(ctx: Context, owner: Agent): void {
   }, { global: true })
 }
 
-function childEnvironment(spec: PtyBackendSpawnSpec): NodeJS.ProcessEnv {
-  // node-pty owns the spawn; the base env shares the subprocess seam's scrub.
+function childEnvironment(spec: PtyBackendSpawnSpec): Record<string, string> {
+  // The subprocess provider supplies its own scrubbed ambient base; these are
+  // deliberate terminal-specific overrides layered after it.
   return {
-    ...scrubbedParentEnv(),
     TERM: 'dumb',
     PAGER: 'cat',
     GIT_PAGER: 'cat',
-    PS1: 'dsh> ',
+    PS1: CONTROLLED_PROMPT,
     PROMPT_COMMAND: 'printf "\\033]133;D;%s\\007" "$?"',
     BASH_SILENCE_DEPRECATION_WARNING: '1',
     DSH_SHELL: '1',
@@ -74,8 +71,31 @@ function childEnvironment(spec: PtyBackendSpawnSpec): NodeJS.ProcessEnv {
 function spawnArgv(ctx: Context, config: ResolvedConfig, policy: SandboxExecutionPolicy): string[] {
   const argv = [config.shellPath, ...config.shellArgs]
   if (policy.mode === 'danger-full-access') return argv
+  const sandbox = ctx.get('sandbox')
+  if (sandbox === undefined) {
+    throw new Error(`pty-local: sandbox mode "${policy.mode}" requires a ctx.sandbox provider in the execution world`)
+  }
   // Re-state the discriminant because object spread does not preserve its narrowed type.
-  return ctx.sandbox.confine(argv, { ...policy, mode: policy.mode }).argv
+  return sandbox.confine(argv, { ...policy, mode: policy.mode }).argv
+}
+
+// TODO(pty-initialize-race-home): Fold this outer abort race into
+// LocalPtySession.initialize when the send-state consolidation lands; the
+// session already owns the send lifecycle the race protects.
+async function initializeSession(session: LocalPtySession, signal?: AbortSignal): Promise<void> {
+  if (signal === undefined) {
+    await session.initialize(signal)
+    return
+  }
+  const aborted = Promise.withResolvers<never>()
+  const onAbort = (): void => { aborted.reject(signal.reason) }
+  signal.addEventListener('abort', onAbort, { once: true })
+  try {
+    signal.throwIfAborted()
+    await Promise.race([session.initialize(signal), aborted.promise])
+  } finally {
+    signal.removeEventListener('abort', onAbort)
+  }
 }
 
 /** Local shell backend registered under the configured type. */
@@ -85,13 +105,13 @@ export class LocalPtyBackend implements PtyBackend {
   constructor(
     private readonly ctx: Context,
     private readonly config: ResolvedConfig,
-    private readonly inspector: ProcessInspector,
-    private readonly spawnTerminal: typeof nodePty.spawn = nodePty.spawn,
+    private readonly spawnTerminal: (
+      spec: SubprocessTerminalSpawnSpec,
+    ) => Promise<SubprocessTerminalHandle> = spec => ctx.subprocess.spawnTerminal(spec),
     private readonly createSession: (
-      terminal: ReturnType<typeof nodePty.spawn>,
-      inspector: ProcessInspector,
+      terminal: SubprocessTerminalHandle,
       config: ResolvedConfig,
-    ) => LocalPtySession = (terminal, inspector, config) => new LocalPtySession(terminal, inspector, config),
+    ) => LocalPtySession = (terminal, config) => new LocalPtySession(terminal, config),
   ) {
     this.type = config.backendType
   }
@@ -101,19 +121,19 @@ export class LocalPtyBackend implements PtyBackend {
     ensureSandboxModeFence(this.ctx, spec.owner)
     const policy = this.ctx.sandboxPolicy.resolve({ session: spec.owner.session })
     const argv = spawnArgv(this.ctx, this.config, policy)
-    const file = argv[0]
-    if (file === undefined) throw new Error('pty-local: sandbox returned empty argv')
-    const options: IPtyForkOptions = {
-      name: 'dumb',
-      cols: this.config.cols,
-      rows: this.config.rows,
+    if (argv[0] === undefined) throw new Error('pty-local: sandbox returned empty argv')
+    const terminal = await this.spawnTerminal({
+      argv,
       cwd: spec.cwd ?? policy.workspaceRoot,
       env: childEnvironment(spec),
-    }
-    const terminal = this.spawnTerminal(file, argv.slice(1), options)
-    const session = this.createSession(terminal, this.inspector, this.config)
+      rows: this.config.rows,
+      cols: this.config.cols,
+      graceMs: this.config.disposeGraceMs,
+      signal: spec.signal,
+    })
+    const session = this.createSession(terminal, this.config)
     try {
-      await session.initialize(spec.signal)
+      await initializeSession(session, spec.signal)
       return session
     } catch (error) {
       try {
@@ -129,6 +149,5 @@ export class LocalPtyBackend implements PtyBackend {
 /** Register the local PTY backend. */
 export function apply(ctx: Context, config: Config): void {
   validateConfig(config)
-  const inspector = createProcessInspector()
-  ctx.pty.registerBackend(new LocalPtyBackend(ctx, config, inspector))
+  ctx.pty.registerBackend(new LocalPtyBackend(ctx, config))
 }

packages/pty/pty-local/src/sanitize.ts

@@ -5,12 +5,15 @@ import { Buffer } from 'node:buffer'
 /** OSC marker emitted by the controlled bash before each prompt. */
 export const PROMPT_MARKER_PREFIX = '133;D;'
 
+/** Exact printable prompt emitted after the private marker. */
+export const CONTROLLED_PROMPT = 'dsh> '
+
 /** One sanitized chunk plus whether it contained the owned prompt marker. */
 export interface SanitizedChunk {
   text: string
   prompt: boolean
-  /** Present when printable text followed the latest owned prompt marker. */
-  promptText?: true
+  /** Printable text after the latest owned marker in this chunk. */
+  promptTail?: string
 }
 
 /**
@@ -23,7 +26,7 @@ export class TerminalSanitizer {
   private discardMode: 'osc' | 'csi' | undefined
   private discardOscEscape = false
   private trailingCarriageReturn = false
-  private awaitingPromptText = false
+  private trackingPromptTail = false
 
   constructor(private readonly maxPendingBytes: number) {}
 
@@ -36,24 +39,21 @@ export class TerminalSanitizer {
     this.pending += this.discardPrefix(chunk)
     let text = ''
     let prompt = false
-    let promptText = false
+    let includePromptTail = this.trackingPromptTail
+    let promptTail = ''
     let index = 0
-    const appendText = (value: string): boolean => {
+    const appendText = (value: string): void => {
       text += value
-      if (this.awaitingPromptText && value.replace(/[\r\n\x07]/g, '').length > 0) {
-        this.awaitingPromptText = false
-        return true
-      }
-      return false
+      if (this.trackingPromptTail) promptTail += value
     }
     while (index < this.pending.length) {
       const escape = this.pending.indexOf('\x1b', index)
       if (escape < 0) {
-        promptText = appendText(this.pending.slice(index)) || promptText
+        appendText(this.pending.slice(index))
         index = this.pending.length
         break
       }
-      promptText = appendText(this.pending.slice(index, escape)) || promptText
+      appendText(this.pending.slice(index, escape))
       if (escape + 1 >= this.pending.length) {
         index = escape
         break
@@ -74,8 +74,9 @@ export class TerminalSanitizer {
         const content = this.pending.slice(escape + 2, end - terminatorBytes)
         if (content.startsWith(PROMPT_MARKER_PREFIX)) {
           prompt = true
-          promptText = false
-          this.awaitingPromptText = true
+          this.trackingPromptTail = true
+          includePromptTail = true
+          promptTail = ''
         }
         index = end
         continue
@@ -99,7 +100,11 @@ export class TerminalSanitizer {
     }
     this.pending = this.pending.slice(index)
     this.enforcePendingBound()
-    return { text: this.normalizeText(text), prompt, ...promptText ? { promptText: true } : {} }
+    return {
+      text: this.normalizeText(text),
+      prompt,
+      ...includePromptTail ? { promptTail } : {},
+    }
   }
 
   /**
@@ -111,7 +116,7 @@ export class TerminalSanitizer {
     this.pending = ''
     this.discardMode = undefined
     this.discardOscEscape = false
-    this.awaitingPromptText = false
+    this.trackingPromptTail = false
     const normalized = this.normalizeText(text)
     if (!this.trailingCarriageReturn) return normalized
     this.trailingCarriageReturn = false

packages/pty/pty-local/src/session.ts

@@ -1,8 +1,12 @@
-/** Local `node-pty` session: bounded output, readiness, signals, and teardown. */
+/** Persistent PTY session over the subprocess seam's terminal primitive. */
 
-import { constants } from 'node:os'
 import { Buffer } from 'node:buffer'
-import type { IDisposable, IPty } from 'node-pty'
+import type {
+  SubprocessOutcome,
+  SubprocessTerminalForeground,
+  SubprocessTerminalHandle,
+} from '@deepseek-ai/dsh-subprocess'
+import { PtyError } from '@deepseek-ai/dsh-pty'
 import type {
   PtyBackendSession,
   PtyReadRequest,
@@ -17,12 +21,7 @@ import type {
   PtyWaitReason,
 } from '@deepseek-ai/dsh-pty'
 import type { ResolvedConfig } from './config.ts'
-import type { ProcessIdentity, ProcessInspector } from './process-inspector.ts'
-import { TerminalSanitizer } from './sanitize.ts'
-
-function delay(ms: number): Promise<void> {
-  return new Promise(resolve => setTimeout(resolve, ms))
-}
+import { CONTROLLED_PROMPT, TerminalSanitizer } from './sanitize.ts'
 
 function utf8Tail(text: string, maxBytes: number): { text: string; truncated: boolean } {
   if (Buffer.byteLength(text) <= maxBytes) return { text, truncated: false }
@@ -79,24 +78,32 @@ class LocalSendOperation implements PtySendOperation {
   private readonly output: BoundedTextBuffer
   private readonly promise: PromiseWithResolvers<PtySendResult>
   private finished = false
+  private cancellationRequested = false
   private initialForegroundLeftWait: boolean
+  private initialForegroundPgid: number | undefined
 
   constructor(
     maxBytes: number,
     readonly startedAt: number,
-    private readonly initialForegroundPgid: number | undefined,
-    initialForegroundWasWaiting: boolean,
     private readonly onCancel: () => void,
   ) {
     this.output = new BoundedTextBuffer(maxBytes)
     this.promise = Promise.withResolvers<PtySendResult>()
-    this.initialForegroundLeftWait = !initialForegroundWasWaiting
+    this.initialForegroundLeftWait = true
   }
 
   get done(): Promise<PtySendResult> {
     return this.promise.promise
   }
 
+  get settled(): boolean {
+    return this.finished
+  }
+
+  get cancelRequested(): boolean {
+    return this.cancellationRequested
+  }
+
   append(text: string): void {
     if (!this.finished) this.output.append(text)
   }
@@ -123,6 +130,11 @@ class LocalSendOperation implements PtySendOperation {
     return this.output.consume()
   }
 
+  setInitialForeground(foreground: SubprocessTerminalForeground | undefined): void {
+    this.initialForegroundPgid = foreground?.processGroupId
+    this.initialForegroundLeftWait = foreground?.inputWaiting !== true
+  }
+
   acceptsStdinWait(pgid: number, waiting: boolean): boolean {
     // The same group may still expose the wait that existed before terminal.write.
     // Observe every poll so a departure before the exact-settlement threshold
@@ -134,56 +146,59 @@ class LocalSendOperation implements PtySendOperation {
 
   cancel(): boolean {
     if (this.finished) return false
+    this.cancellationRequested = true
     this.onCancel()
     return true
   }
 }
 
-function signalName(number: number | undefined): NodeJS.Signals | null {
-  if (number === undefined || number === 0) return null
-  for (const [name, value] of Object.entries(constants.signals)) {
-    if (value === number) return name as NodeJS.Signals
-  }
-  return null
-}
-
-/** Backend session wrapping one `node-pty` process and its captured process tree. */
+/** Backend session wrapping one provider-owned terminal process. */
 export class LocalPtySession implements PtyBackendSession {
   motd = ''
   readonly pid: number
+  private readonly decoder = new TextDecoder()
   private readonly sanitizer: TerminalSanitizer
   private readonly scrollback: BoundedTextBuffer
-  private readonly exitPromise: PromiseWithResolvers<void> = Promise.withResolvers<void>()
-  private readonly dataDisposable: IDisposable
-  private readonly exitDisposable: IDisposable
+  private readonly outputEnded = Promise.withResolvers<void>()
+  private readonly completion: Promise<void>
   private statusValue: PtySessionStatus = { kind: 'running' }
+  // TODO(pty-send-state-consolidation): Fold the per-send fields below
+  // (active/activeTimer/activeDeadlineTimer/activeAbort/interrupting/
+  // activeWrite/pollingReady/polling) into one send-lifecycle owner; the
+  // cancellation/readiness interplay now has enough pinned tests to carry
+  // that refactor safely.
   private active: LocalSendOperation | undefined
   private activeTimer: NodeJS.Timeout | undefined
+  private activeDeadlineTimer: NodeJS.Timeout | undefined
   private activeAbort: (() => void) | undefined
+  private interrupting: LocalSendOperation | undefined
+  private activeWrite: Promise<boolean> | undefined
+  private pollingReady: LocalSendOperation | undefined
+  private polling = false
   private promptSeen = false
   private promptTextSeen = false
+  private promptTail = ''
   private shellPgid: number | undefined
   private initializing = false
   private lastOutputAt = Date.now()
   private closing = false
   private closePromise: Promise<void> | undefined
+  private transportFailure: Error | undefined
 
   constructor(
-    private readonly terminal: IPty,
-    private readonly inspector: ProcessInspector,
+    private readonly terminal: SubprocessTerminalHandle,
     private readonly config: ResolvedConfig,
   ) {
     this.pid = terminal.pid
     this.sanitizer = new TerminalSanitizer(config.maxReadBytes)
     this.scrollback = new BoundedTextBuffer(config.scrollbackMaxBytes, config.scrollbackLines)
-    this.dataDisposable = terminal.onData((data) => { this.onData(data) })
-    this.exitDisposable = terminal.onExit(({ exitCode, signal }) => {
-      const tail = this.sanitizer.flush()
-      this.appendOutput(tail)
-      this.statusValue = { kind: 'exited', exitCode, signal: signalName(signal) }
-      this.settleActive('session_exit')
-      this.exitPromise.resolve()
-    })
+    terminal.output.on('data', this.onTerminalData)
+    terminal.output.once('end', this.onTerminalEnd)
+    terminal.output.once('error', this.onTerminalError)
+    this.completion = terminal.done.then(
+      outcome => this.onExit(outcome),
+      (error: unknown) => { this.onTransportFailure(error) },
+    )
   }
 
   /**
@@ -210,43 +225,95 @@ export class LocalPtySession implements PtyBackendSession {
   startSend(request: PtySendRequest): PtySendOperation {
     if (this.closing) throw new Error('PTY session is closing')
     if (this.statusValue.kind === 'exited') throw new Error('PTY session has exited')
-    if (this.active !== undefined) throw new Error('PTY session already has an active send')
+    if (this.active !== undefined) {
+      const draining = this.activeWrite !== undefined
+        ? ' or draining provider write'
+        : this.interrupting !== undefined
+          ? ' or draining foreground interrupt'
+          : ''
+      throw new PtyError(`PTY session already has an active send${draining}`, 'SEND_ACTIVE')
+    }
     if (request.signal?.aborted === true) throw new Error('PTY send aborted before write')
 
-    const initialForegroundPgid = this.inspector.foregroundPgid(this.pid)
-    const initialForegroundWasWaiting = initialForegroundPgid !== undefined
-      && this.inspector.isStdinWaiting(initialForegroundPgid)
     const operation = new LocalSendOperation(
       this.config.maxReadBytes,
       Date.now(),
-      initialForegroundPgid,
-      initialForegroundWasWaiting,
       () => { this.interrupt(operation) },
     )
     this.active = operation
-    this.lastOutputAt = Date.now()
-    this.promptSeen = false
-    this.promptTextSeen = false
+    this.resetReadinessEvidence()
 
     if (request.signal !== undefined) {
       const onAbort = (): void => { operation.cancel() }
       request.signal.addEventListener('abort', onAbort, { once: true })
       this.activeAbort = () => request.signal?.removeEventListener('abort', onAbort)
     }
-
-    try {
-      if (request.text.length > 0) this.terminal.write(request.text)
-      if (request.submit) this.terminal.write('\r')
-    } catch (error: unknown) {
-      this.clearActive()
-      operation.fail(error)
-      return operation
-    }
-
-    this.activeTimer = setInterval(() => { this.pollReadiness(operation) }, this.config.pollIntervalMs)
+    this.activeDeadlineTimer = setTimeout(() => {
+      if (this.active === operation) {
+        this.settleActive('timeout', this.activeWrite !== undefined || this.interrupting === operation)
+      }
+    }, this.config.timeoutMs)
+    void this.beginSend(operation, request)
     return operation
   }
 
+  private async beginSend(operation: LocalSendOperation, request: PtySendRequest): Promise<void> {
+    let foreground: SubprocessTerminalForeground | undefined
+    try {
+      foreground = await this.terminal.inspectForeground()
+    } catch (error: unknown) {
+      // A pre-write inspection failure while cancellation owns the slot must not
+      // release it: interruptOnce's in-flight foreground signal could land on a
+      // successor's foreground group. The interrupt path's post-signal tail
+      // resumes polling, whose guarded catch propagates a persistent failure.
+      // A retained settled operation implies that same in-flight interrupt, so
+      // this guard admits only an unsettled active send.
+      if (this.active === operation && !this.closing && this.interrupting !== operation) {
+        this.failActive(error)
+      }
+      return
+    }
+    try {
+      if (this.active !== operation || this.closing || this.interrupting === operation) return
+      operation.setInitialForeground(foreground)
+      const input = `${request.text}${request.submit ? '\r' : ''}`
+      if (input.length > 0 && !operation.cancelRequested) {
+        this.resetReadinessEvidence()
+        const write = this.terminal.write(input)
+        this.activeWrite = write.then(() => true, () => false)
+        try {
+          await write
+        } finally {
+          this.activeWrite = undefined
+        }
+      }
+      // Cancellation owns post-write signalling and reservation release.
+      if (operation.cancelRequested) return
+      if (this.active === operation && operation.settled) {
+        this.clearActive()
+        return
+      }
+      // Closing can race the awaited provider write even though static analysis sees only local assignments.
+      // oxlint-disable-next-line typescript/no-unnecessary-condition -- awaited provider writes can close the session.
+      if (this.active === operation && !this.closing) {
+        this.pollingReady = operation
+        this.schedulePoll(operation)
+      }
+    } catch (error: unknown) {
+      if (this.active === operation && !this.closing) {
+        if (operation.settled) this.clearActive()
+        else this.failActive(error)
+      }
+    }
+  }
+
+  private resetReadinessEvidence(): void {
+    this.lastOutputAt = Date.now()
+    this.promptSeen = false
+    this.promptTextSeen = false
+    this.promptTail = ''
+  }
+
   read(request: PtyReadRequest): PtyReadResult {
     const snapshot = this.scrollback.snapshot()
     const lines = snapshot.text.split('\n')
@@ -272,16 +339,10 @@ export class LocalPtySession implements PtyBackendSession {
     }
   }
 
-  signal(signal: PtySignal): Promise<PtySignalResult> {
-    return Promise.resolve().then(() => {
-      const pgid = this.inspector.foregroundPgid(this.pid)
-      if (pgid === undefined) throw new Error(`cannot resolve foreground process group for PTY ${this.pid}`)
-      if (signal === 'SIGKILL' && pgid === this.pid) {
-        throw new Error('refusing to SIGKILL the PTY shell; use terminal_close')
-      }
-      this.inspector.signalGroup(pgid, signal)
-      return { delivered: true, targetPgid: pgid }
-    })
+  async signal(signal: PtySignal): Promise<PtySignalResult> {
+    if (this.closing) throw new Error('PTY session is closing')
+    const targetPgid = await this.terminal.signalForeground(signal)
+    return { delivered: true, targetPgid }
   }
 
   status(): PtySessionStatus {
@@ -300,21 +361,56 @@ export class LocalPtySession implements PtyBackendSession {
     return closing
   }
 
+  private readonly onTerminalData = (chunk: Buffer | Uint8Array | string): void => {
+    const bytes = typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk
+    this.onData(this.decoder.decode(bytes, { stream: true }))
+  }
+
+  private readonly onTerminalEnd = (): void => {
+    this.onData(this.decoder.decode())
+    this.appendOutput(this.sanitizer.flush())
+    this.outputEnded.resolve()
+  }
+
+  private readonly onTerminalError = (error: Error): void => {
+    this.onTransportFailure(error)
+    this.outputEnded.resolve()
+  }
+
   private onData(data: string): void {
     const sanitized = this.sanitizer.push(data)
     this.appendOutput(sanitized.text)
     if (sanitized.prompt) {
-      const foregroundPgid = this.inspector.foregroundPgid(this.pid)
-      if (this.shellPgid === undefined) this.shellPgid = foregroundPgid
+      // TODO(pty-delayed-signal-prompt): With a reproducer, define a marker-generation boundary
+      // before attributing a signal-delayed prompt to a later send.
       // Bash can print PROMPT_COMMAND before the kernel publishes its return
       // to the foreground process group. Retain the marker; polling below is
       // the authority that accepts it only after bash owns the foreground.
       this.promptSeen = true
-      this.promptTextSeen = sanitized.promptText === true
+      this.promptTail = ''
       this.lastOutputAt = Date.now()
-    } else if (this.promptSeen && sanitized.promptText === true) {
-      this.promptTextSeen = true
     }
+    if (this.promptSeen && sanitized.promptTail !== undefined) {
+      const remaining = Math.max(0, CONTROLLED_PROMPT.length + 1 - this.promptTail.length)
+      this.promptTail += sanitized.promptTail.slice(0, remaining)
+      if (sanitized.promptTail.length > remaining) this.promptTail = `${CONTROLLED_PROMPT}\0`
+      this.promptTextSeen = this.promptTail === CONTROLLED_PROMPT
+    }
+  }
+
+  private async onExit(outcome: SubprocessOutcome): Promise<void> {
+    await this.outputEnded.promise
+    if (this.transportFailure !== undefined) return
+    this.statusValue = { kind: 'exited', exitCode: outcome.exitCode, signal: outcome.signal }
+    this.settleActive('session_exit')
+  }
+
+  private onTransportFailure(error: unknown): void {
+    const failure = error instanceof Error ? error : new Error(String(error))
+    this.transportFailure ??= failure
+    this.statusValue = { kind: 'exited', exitCode: null, signal: null }
+    this.failActive(failure)
+    void this.terminal.terminate().catch(() => {})
   }
 
   private appendOutput(text: string): void {
@@ -324,63 +420,94 @@ export class LocalPtySession implements PtyBackendSession {
     this.active?.append(text)
   }
 
-  private pollReadiness(operation: LocalSendOperation): void {
-    if (this.active !== operation) return
-    if (this.statusValue.kind === 'exited') {
-      this.settleActive('session_exit')
-      return
-    }
-    if (this.promptSeen && this.promptTextSeen && Date.now() - this.lastOutputAt >= this.config.pollIntervalMs) {
-      const pgid = this.inspector.foregroundPgid(this.pid)
-      if (this.shellPgid !== undefined && pgid === this.shellPgid) {
+  private schedulePoll(operation: LocalSendOperation, delayMs = this.config.pollIntervalMs): void {
+    if (this.active !== operation || this.interrupting === operation || this.polling) return
+    if (this.activeTimer !== undefined) clearTimeout(this.activeTimer)
+    this.activeTimer = setTimeout(() => {
+      this.activeTimer = undefined
+      void this.pollReadiness(operation)
+    }, delayMs)
+  }
+
+  private async pollReadiness(operation: LocalSendOperation): Promise<void> {
+    if (this.active !== operation || this.polling) return
+    this.polling = true
+    try {
+      if (this.statusValue.kind === 'exited') {
+        this.settleActive('session_exit')
+        return
+      }
+      const foreground = await this.terminal.inspectForeground()
+      if (this.active !== operation || this.closing || this.interrupting === operation) return
+      const idleFor = Date.now() - this.lastOutputAt
+      if (this.promptSeen && foreground !== undefined && this.shellPgid === undefined) {
+        this.shellPgid = foreground.processGroupId
+      }
+      if (this.promptSeen && this.promptTextSeen && idleFor >= this.config.pollIntervalMs
+        && foreground?.processGroupId === this.shellPgid) {
         this.settleActive('stdin_read')
         return
       }
+      const elapsed = Date.now() - operation.startedAt
+      const startupHasOutput = !this.initializing || this.scrollback.snapshot().text.length > 0
+      const acceptsStdinWait = startupHasOutput && foreground !== undefined
+        && operation.acceptsStdinWait(foreground.processGroupId, foreground.inputWaiting)
+      if (elapsed >= this.config.exactProbeAfterMs && acceptsStdinWait) {
+        this.settleActive('stdin_read')
+        return
+      }
+      // A prompt candidate can race bash's foreground handoff, but an interactive
+      // child also inherits PROMPT_COMMAND. Silence therefore remains the bound
+      // on waiting for shell ownership instead of letting a child marker suppress
+      // readiness until the absolute timeout.
+      const handoffGrace = this.promptSeen ? this.config.handoffGraceMs : 0
+      if (startupHasOutput && idleFor >= this.config.idleSilenceMs + handoffGrace) {
+        this.settleActive('inferred_idle')
+      }
+    } catch (error: unknown) {
+      if (this.active === operation && !this.closing && this.interrupting !== operation) this.failActive(error)
+    } finally {
+      this.polling = false
+      const active = this.active
+      // Awaited provider inspection can clear or replace the active send despite static analysis.
+      // oxlint-disable-next-line typescript/no-unnecessary-condition -- awaited inspection can replace the active send.
+      if (active !== undefined && this.pollingReady === active) this.schedulePoll(active)
     }
-    const elapsed = Date.now() - operation.startedAt
-    const startupHasOutput = !this.initializing || this.scrollback.snapshot().text.length > 0
-    let acceptsStdinWait = false
-    if (startupHasOutput) {
-      const pgid = this.inspector.foregroundPgid(this.pid)
-      acceptsStdinWait = pgid !== undefined
-        && operation.acceptsStdinWait(pgid, this.inspector.isStdinWaiting(pgid))
-    }
-    if (elapsed >= this.config.exactProbeAfterMs && acceptsStdinWait) {
-      this.settleActive('stdin_read')
-      return
-    }
-    // A prompt candidate can race bash's foreground handoff, but an interactive
-    // child also inherits PROMPT_COMMAND. Silence therefore remains the bound
-    // on waiting for shell ownership instead of letting a child marker suppress
-    // readiness until the absolute timeout. When a prompt marker was seen, the
-    // configured grace holds the fallback past the silence bound so polls in
-    // that window can observe the foreground handoff and settle as stdin_read.
-    const idleFor = Date.now() - this.lastOutputAt
-    const handoffGrace = this.promptSeen ? this.config.handoffGraceMs : 0
-    if (startupHasOutput && idleFor >= this.config.idleSilenceMs + handoffGrace) {
-      this.settleActive('inferred_idle')
-      return
-    }
-    if (elapsed >= this.config.timeoutMs) this.settleActive('timeout')
   }
 
-  private settleActive(waitReason: PtyWaitReason): void {
+  private settleActive(waitReason: PtyWaitReason, retainOwnership = false): void {
     const operation = this.active
     if (operation === undefined) return
     const scrollbackTruncated = this.scrollback.snapshot().truncated
-    this.clearActive()
+    if (retainOwnership) {
+      this.stopPolling()
+      this.activeAbort?.()
+      this.activeAbort = undefined
+    } else {
+      this.clearActive()
+    }
     operation.settle(waitReason, this.statusValue, scrollbackTruncated)
   }
 
   private stopPolling(): void {
-    if (this.activeTimer !== undefined) clearInterval(this.activeTimer)
+    this.stopReadinessPolling()
+    if (this.activeDeadlineTimer !== undefined) clearTimeout(this.activeDeadlineTimer)
+    this.activeDeadlineTimer = undefined
+  }
+
+  private stopReadinessPolling(): void {
+    if (this.activeTimer !== undefined) clearTimeout(this.activeTimer)
     this.activeTimer = undefined
+    this.pollingReady = undefined
   }
 
   private clearActive(): void {
+    const operation = this.active
     this.stopPolling()
     this.activeAbort?.()
     this.activeAbort = undefined
+    if (this.interrupting === operation) this.interrupting = undefined
+    this.pollingReady = undefined
     this.active = undefined
   }
 
@@ -393,104 +520,46 @@ export class LocalPtySession implements PtyBackendSession {
 
   private interrupt(operation: LocalSendOperation): void {
     if (this.active !== operation) return
+    this.interrupting = operation
+    this.stopReadinessPolling()
+    void this.interruptOnce(operation)
+  }
+
+  private async interruptOnce(operation: LocalSendOperation): Promise<void> {
     try {
-      const pgid = this.inspector.foregroundPgid(this.pid)
-      if (pgid === undefined) throw new Error(`cannot resolve foreground process group for PTY ${this.pid}`)
-      this.inspector.signalGroup(pgid, 'SIGINT')
+      const activeWrite = this.activeWrite
+      if (activeWrite !== undefined && !await activeWrite) return
+      await this.terminal.signalForeground('SIGINT')
     } catch (error: unknown) {
-      this.failActive(error)
+      if (this.active === operation && !this.closing) this.onTransportFailure(error)
+      return
+    } finally {
+      if (this.interrupting === operation) this.interrupting = undefined
     }
-  }
-
-  private survivors(members: ProcessIdentity[]): ProcessIdentity[] {
-    return members.filter(member => this.inspector.isAlive(member))
-  }
-
-  private descendants(): ProcessIdentity[] {
-    return this.inspector.processTree(this.pid).filter(member => member.pid !== this.pid)
-  }
-
-  private async waitForExit(members: ProcessIdentity[]): Promise<ProcessIdentity[]> {
-    const deadline = Date.now() + this.config.disposeGraceMs
-    let survivors = this.survivors(members)
-    while (survivors.length > 0 && Date.now() < deadline) {
-      await delay(Math.min(25, Math.max(1, deadline - Date.now())))
-      survivors = this.survivors(members)
-    }
-    return survivors
-  }
-
-  private signalMembers(members: ProcessIdentity[], signal: 'SIGTERM' | 'SIGKILL'): void {
-    for (const member of members) {
-      try {
-        this.inspector.signalProcess(member, signal)
-      } catch (_alreadyExitedDuringSignal) {
-        // Identity is rechecked by the inspector; a same-tick exit is success.
-      }
-    }
-  }
-
-  private unionMembers(...groups: ProcessIdentity[][]): ProcessIdentity[] {
-    const members: ProcessIdentity[] = []
-    const seen = new Set<string>()
-    for (const group of groups) {
-      for (const member of group) {
-        const key = JSON.stringify([member.pid, member.started])
-        if (seen.has(key)) continue
-        seen.add(key)
-        members.push(member)
-      }
-    }
-    return members
-  }
-
-  private async stopDescendants(): Promise<ProcessIdentity[]> {
-    const captured = this.descendants()
-    this.signalMembers(captured, 'SIGTERM')
-    const capturedSurvivors = await this.waitForExit(captured)
-    // A TERM-handling descendant may have forked while winding down. Rescan
-    // while the shell can still reap every member, then kill both the fresh
-    // tree and captured survivors that were reparented out of that tree.
-    const members = this.unionMembers(capturedSurvivors, this.descendants())
-    this.signalMembers(members, 'SIGKILL')
-    const survivors = await this.waitForExit(members)
-    return this.survivors(this.unionMembers(survivors, this.descendants()))
-  }
-
-  private async stopShell(): Promise<void> {
-    try {
-      this.terminal.kill('SIGTERM')
-    } catch (_topLevelAlreadyExitedDuringTerm) {
-      // The exit notification remains authoritative.
-    }
-    if (this.statusValue.kind === 'running') {
-      await Promise.race([this.exitPromise.promise, delay(this.config.disposeGraceMs)])
-    }
-    if (this.statusValue.kind === 'running') {
-      try {
-        this.terminal.kill('SIGKILL')
-      } catch (_topLevelAlreadyExitedDuringKill) {
-        // The exit notification remains authoritative.
-      }
-      await Promise.race([this.exitPromise.promise, delay(this.config.disposeGraceMs)])
-    }
-    if (this.statusValue.kind === 'running') {
-      throw new Error(`PTY cleanup failed; surviving pids: ${this.pid}`)
+    if (this.active === operation && operation.settled) {
+      this.clearActive()
+    } else if (this.active === operation && !this.closing) {
+      this.pollingReady = operation
+      this.schedulePoll(operation, 0)
     }
   }
 
   private async closeOnce(reason: string): Promise<void> {
-    this.dataDisposable.dispose()
     // Stop readiness polling but retain the active operation: teardown settles
     // it as session_exit below, so an in-flight send is never mis-settled as
     // stdin_read/inferred_idle/timeout during the grace period.
     this.stopPolling()
-    const survivors = await this.stopDescendants()
-    if (survivors.length > 0) {
-      throw new Error(`PTY cleanup failed (${reason}); surviving pids: ${survivors.map(member => member.pid).join(', ')}`)
+    try {
+      await this.terminal.terminate()
+    } catch (error: unknown) {
+      throw new Error(`PTY cleanup failed (${reason})`, { cause: error })
     }
-    await this.stopShell()
+    // Quiescence is the active send's terminal outcome.
     this.settleActive('session_exit')
-    this.exitDisposable.dispose()
+    await this.completion
+    this.terminal.output.off('data', this.onTerminalData)
+    this.terminal.output.off('end', this.onTerminalEnd)
+    this.terminal.output.off('error', this.onTerminalError)
+    if (this.transportFailure !== undefined) throw this.transportFailure
   }
 }

packages/pty/pty-local/tests/index.spec.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from 'vitest'
-import type { IPty, IPtyForkOptions } from 'node-pty'
+import { PassThrough } from 'node:stream'
 import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
 import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session'
@@ -11,8 +11,14 @@ import PtyService, { PtyBackendCleanupError, PtySessionId } from '@deepseek-ai/d
 import { LocalPtyBackend } from '@deepseek-ai/dsh-pty-local'
 import * as ptyLocal from '@deepseek-ai/dsh-pty-local'
 import type { ResolvedConfig } from '@deepseek-ai/dsh-pty-local/src/config.ts'
-import type { ProcessInspector } from '@deepseek-ai/dsh-pty-local/src/process-inspector.ts'
 import type { LocalPtySession } from '@deepseek-ai/dsh-pty-local/src/session.ts'
+import { SubprocessService } from '@deepseek-ai/dsh-subprocess'
+import type {
+  SubprocessHandle,
+  SubprocessSpawnSpec,
+  SubprocessTerminalHandle,
+  SubprocessTerminalSpawnSpec,
+} from '@deepseek-ai/dsh-subprocess'
 
 class EmptySandbox extends SandboxProvider {
   confine(_argv: readonly string[], _policy: SandboxPolicy): ConfinedArgv {
@@ -52,14 +58,26 @@ function agent(ctx: Context, cwd?: string): Agent {
   }
 }
 
-const inspector = {
-  foregroundPgid: () => undefined,
-  isStdinWaiting: () => false,
-  processTree: () => [],
-  isAlive: () => false,
-  signalGroup() {},
-  signalProcess() {},
-} satisfies ProcessInspector
+function terminalHandle(): SubprocessTerminalHandle {
+  const output = new PassThrough()
+  return {
+    pid: 123,
+    output,
+    done: Promise.resolve({ exitCode: 0, signal: null }),
+    write: async () => {},
+    inspectForeground: async () => ({ processGroupId: 123, inputWaiting: true }),
+    signalForeground: async () => 123,
+    terminate: async () => { output.end() },
+  }
+}
+
+class StubSubprocessService extends SubprocessService {
+  async resolveExecutable(command: string): Promise<string> { return command }
+  spawn(_spec: SubprocessSpawnSpec): SubprocessHandle { throw new Error('unused') }
+  async spawnTerminal(_spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle> {
+    return terminalHandle()
+  }
+}
 
 function spec(owner: Agent, signal?: AbortSignal) {
   return {
@@ -81,12 +99,11 @@ function stubLocalSession(initialize: () => Promise<void> = () => Promise.resolv
 }
 
 function registerStubLocalBackend(ctx: Context, createSession: () => LocalPtySession) {
-  return ctx.inject(['pty', 'sandbox', 'sandboxPolicy'], (providerCtx) => {
+  return ctx.inject(['pty', 'sandbox', 'sandboxPolicy', 'subprocess'], (providerCtx) => {
     providerCtx.pty.registerBackend(new LocalPtyBackend(
       providerCtx,
       { ...config(), backendType: 'stub' },
-      inspector,
-      (() => ({})) as never,
+      async () => terminalHandle(),
       createSession,
     ))
   })
@@ -97,7 +114,7 @@ describe('LocalPtyBackend startup rollback', () => {
     const ctx = new Context()
     await ctx.plugin(EmptySandbox)
     await ctx.plugin(SandboxPolicyService, { mode: 'read-only', workspaceRoot: '/tmp' })
-    const backend = new LocalPtyBackend(ctx, config(), inspector)
+    const backend = new LocalPtyBackend(ctx, config(), async () => terminalHandle())
     const controller = new AbortController()
     const abortReason = new Error('spawn aborted')
     controller.abort(abortReason)
@@ -107,13 +124,12 @@ describe('LocalPtyBackend startup rollback', () => {
 
   it('closes failed startup and aggregates cleanup failure', async () => {
     const ctx = new Context()
-    await ctx.plugin(EmptySandbox)
     await ctx.plugin(SandboxPolicyService, { mode: 'danger-full-access', workspaceRoot: '/tmp' })
-    const spawnTerminal = (() => ({} as IPty)) as never
+    const spawnTerminal = async (): Promise<SubprocessTerminalHandle> => terminalHandle()
 
     const closed = vi.fn<() => Promise<void>>().mockResolvedValue(undefined)
     const failed = { initialize: () => Promise.reject(new Error('startup failed')), close: closed } as unknown as LocalPtySession
-    const backend = new LocalPtyBackend(ctx, config(), inspector, spawnTerminal, () => failed)
+    const backend = new LocalPtyBackend(ctx, config(), spawnTerminal, () => failed)
     await expect(backend.spawn(spec(agent(ctx)))).rejects.toThrow('startup failed')
     expect(closed).toHaveBeenCalledWith('PTY startup failed')
 
@@ -123,7 +139,7 @@ describe('LocalPtyBackend startup rollback', () => {
       initialize: () => Promise.reject(startupFailure),
       close: () => Promise.reject(cleanupFailure),
     } as unknown as LocalPtySession
-    const aggregate = new LocalPtyBackend(ctx, config(), inspector, spawnTerminal, () => doublyFailed)
+    const aggregate = new LocalPtyBackend(ctx, config(), spawnTerminal, () => doublyFailed)
     await expect(aggregate.spawn(spec(agent(ctx)))).rejects.toEqual(expect.objectContaining({
       name: 'PtyBackendCleanupError',
       spawnError: startupFailure,
@@ -131,79 +147,191 @@ describe('LocalPtyBackend startup rollback', () => {
     } satisfies Partial<PtyBackendCleanupError>))
   })
 
-  it('resolves session mode and root together before wrapping the shell', async () => {
+  it('starts startup rollback when cancellation wins a stalled initialization', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SandboxPolicyService, { mode: 'danger-full-access', workspaceRoot: '/tmp' })
+    const initialization = Promise.withResolvers<undefined>()
+    const initializationStarted = Promise.withResolvers<undefined>()
+    const close = vi.fn<() => Promise<void>>().mockResolvedValue(undefined)
+    const session = {
+      initialize: () => {
+        initializationStarted.resolve(undefined)
+        return initialization.promise
+      },
+      close,
+    } as unknown as LocalPtySession
+    const backend = new LocalPtyBackend(ctx, config(), async () => terminalHandle(), () => session)
+    const controller = new AbortController()
+    const reason = new Error('cancel stalled startup')
+
+    const spawning = backend.spawn(spec(agent(ctx), controller.signal))
+    await initializationStarted.promise
+    controller.abort(reason)
+
+    await expect(spawning).rejects.toBe(reason)
+    expect(close).toHaveBeenCalledWith('PTY startup failed')
+    initialization.resolve(undefined)
+  })
+
+  it('wraps confined argv, scrubs the environment, and returns initialized sessions', async () => {
     const ctx = new Context()
     await ctx.plugin(RecordingSandbox)
-    await ctx.plugin(SandboxPolicyService, { mode: 'read-only', workspaceRoot: '/deployment-fallback' })
-    const terminal = {} as IPty
-    let spawned: { file: string; args: string[]; options: IPtyForkOptions } | undefined
-    const spawnTerminal = ((file: string, args: string[], options: IPtyForkOptions) => {
-      spawned = { file, args, options }
+    await ctx.plugin(SandboxPolicyService, { mode: 'workspace-write', workspaceRoot: '/workspace' })
+    const terminal = terminalHandle()
+    let spawned: SubprocessTerminalSpawnSpec | undefined
+    const spawnTerminal = async (spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle> => {
+      spawned = spec
       return terminal
-    }) as never
+    }
     const initialized = vi.fn<() => Promise<void>>().mockResolvedValue(undefined)
     const session = { initialize: initialized } as unknown as LocalPtySession
     const backend = new LocalPtyBackend(
       ctx,
       { ...config(), shellArgs: ['-i'] },
-      inspector,
       spawnTerminal,
       () => session,
     )
     const previous = process.env.PTY_TEST_SECRET
     process.env.PTY_TEST_SECRET = 'must-not-leak'
-    const owner = agent(ctx, '/session-workspace')
-    setSandboxMode(owner.session, 'workspace-write')
     try {
-      expect(await backend.spawn(spec(owner))).toBe(session)
+      expect(await backend.spawn({ ...spec(agent(ctx)), cwd: '/work' })).toBe(session)
     } finally {
       if (previous === undefined) delete process.env.PTY_TEST_SECRET
       else process.env.PTY_TEST_SECRET = previous
     }
 
     expect(spawned).toMatchObject({
-      file: '/sandbox',
-      args: ['--', '/bin/bash', '-i'],
-      options: {
-        name: 'dumb', cols: 80, rows: 24, cwd: '/session-workspace',
-        env: {
-          TERM: 'dumb', PAGER: 'cat', GIT_PAGER: 'cat', PS1: 'dsh> ', BASH_SILENCE_DEPRECATION_WARNING: '1',
-          DSH_SHELL: '1', DSH_SESSION_ID: 'agent', DSH_PTY_SESSION_ID: 'pty-1',
-        },
+      argv: ['/sandbox', '--', '/bin/bash', '-i'],
+      cols: 80,
+      rows: 24,
+      cwd: '/work',
+      graceMs: 10,
+      env: {
+        TERM: 'dumb', PAGER: 'cat', GIT_PAGER: 'cat', PS1: 'dsh> ', BASH_SILENCE_DEPRECATION_WARNING: '1',
+        DSH_SHELL: '1', DSH_SESSION_ID: 'agent', DSH_PTY_SESSION_ID: 'pty-1',
       },
     })
-    expect(spawned?.options.env?.PTY_TEST_SECRET).toBeUndefined()
+    expect(spawned?.env?.PTY_TEST_SECRET).toBeUndefined()
     expect(initialized).toHaveBeenCalledWith(undefined)
+    expect((ctx.sandbox as RecordingSandbox).calls).toEqual([{
+      argv: ['/bin/bash', '-i'],
+      policy: { mode: 'workspace-write', workspaceRoot: '/workspace' },
+    }])
+  })
+
+  it('resolves session mode and root together before wrapping the shell', async () => {
+    const ctx = new Context()
+    await ctx.plugin(RecordingSandbox)
+    await ctx.plugin(SandboxPolicyService, { mode: 'read-only', workspaceRoot: '/deployment-fallback' })
+    const terminal = terminalHandle()
+    let spawned: SubprocessTerminalSpawnSpec | undefined
+    const spawnTerminal = async (spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle> => {
+      spawned = spec
+      return terminal
+    }
+    const initialized = vi.fn<() => Promise<void>>().mockResolvedValue(undefined)
+    const session = { initialize: initialized } as unknown as LocalPtySession
+    const backend = new LocalPtyBackend(
+      ctx,
+      { ...config(), shellArgs: ['-i'] },
+      spawnTerminal,
+      () => session,
+    )
+    const owner = agent(ctx, '/session-workspace')
+    setSandboxMode(owner.session, 'workspace-write')
+    expect(await backend.spawn(spec(owner))).toBe(session)
+
+    expect(spawned).toMatchObject({
+      argv: ['/sandbox', '--', '/bin/bash', '-i'],
+      cwd: '/session-workspace',
+    })
     expect((ctx.sandbox as RecordingSandbox).calls).toEqual([{
       argv: ['/bin/bash', '-i'],
       policy: { mode: 'workspace-write', workspaceRoot: '/session-workspace' },
     }])
   })
 
+  it('rejects a confined spawn without a sandbox provider', async () => {
+    const confinedCtx = new Context()
+    await confinedCtx.plugin(SandboxPolicyService, { mode: 'workspace-write', workspaceRoot: '/workspace' })
+    const confined = new LocalPtyBackend(
+      confinedCtx,
+      config(),
+      async () => { throw new Error('terminal spawn must not run') },
+      () => stubLocalSession(),
+    )
+    await expect(confined.spawn(spec(agent(confinedCtx)))).rejects.toThrow(
+      'sandbox mode "workspace-write" requires a ctx.sandbox provider in the execution world',
+    )
+  })
+
+  it('forwards terminal allocation cancellation directly', async () => {
+    const ctx = new Context()
+    await ctx.plugin(EmptySandbox)
+    await ctx.plugin(SandboxPolicyService, { mode: 'danger-full-access', workspaceRoot: '/tmp' })
+
+    const publishedController = new AbortController()
+    let publishedSignal: AbortSignal | undefined
+    const published = new LocalPtyBackend(
+      ctx,
+      config(),
+      async (spawnSpec) => {
+        publishedSignal = spawnSpec.signal
+        return terminalHandle()
+      },
+      () => stubLocalSession(),
+    )
+    await published.spawn(spec(agent(ctx), publishedController.signal))
+    expect(publishedSignal).toBe(publishedController.signal)
+    publishedController.abort(new Error('originating turn ended'))
+    expect(publishedSignal?.aborted).toBe(true)
+
+    const pendingController = new AbortController()
+    const seen = Promise.withResolvers<AbortSignal>()
+    const pending = new LocalPtyBackend(
+      ctx,
+      config(),
+      async spawnSpec => await new Promise<SubprocessTerminalHandle>((_resolve, reject) => {
+        const setupSignal = spawnSpec.signal as AbortSignal
+        seen.resolve(setupSignal)
+        const onAbort = (): void => {
+          reject(setupSignal.reason instanceof Error ? setupSignal.reason : new Error(String(setupSignal.reason)))
+        }
+        setupSignal.addEventListener('abort', onAbort, { once: true })
+      }),
+      () => stubLocalSession(),
+    )
+    const spawning = pending.spawn(spec(agent(ctx), pendingController.signal))
+    const pendingSignal = await seen.promise
+    const reason = new Error('cancel pending allocation')
+    pendingController.abort(reason)
+    await expect(spawning).rejects.toBe(reason)
+    expect(pendingSignal.aborted).toBe(true)
+  })
+
   it('composes the default local session around a spawned terminal', async () => {
     const ctx = new Context()
     await ctx.plugin(EmptySandbox)
     await ctx.plugin(SandboxPolicyService, { mode: 'danger-full-access', workspaceRoot: '/workspace' })
-    let exitListener: ((event: { exitCode: number; signal?: number }) => void) | undefined
-    const terminal = {
-      pid: 123, cols: 80, rows: 24, process: 'bash', handleFlowControl: false,
-      onData(listener: (data: string) => void) {
-        queueMicrotask(() => { listener('\x1b]133;D;0\x07dsh> ') })
-        return { dispose() {} }
+    const output = new PassThrough()
+    const outcome = Promise.withResolvers<{ exitCode: number | null; signal: NodeJS.Signals | null }>()
+    const terminal: SubprocessTerminalHandle = {
+      pid: 123,
+      output,
+      done: outcome.promise,
+      write: async () => {},
+      inspectForeground: async () => ({ processGroupId: 123, inputWaiting: true }),
+      signalForeground: async () => 123,
+      async terminate() {
+        output.end()
+        outcome.resolve({ exitCode: null, signal: 'SIGTERM' })
       },
-      onExit(listener: (event: { exitCode: number; signal?: number }) => void) {
-        exitListener = listener
-        return { dispose() {} }
-      },
-      write() {},
-      kill() { exitListener?.({ exitCode: 0, signal: 15 }) },
-      resize() {}, clear() {}, pause() {}, resume() {},
-    } as IPty
+    }
+    queueMicrotask(() => { output.write(Buffer.from('\x1b]133;D;0\x07dsh> ')) })
     const backend = new LocalPtyBackend(
       ctx,
       config(),
-      { ...inspector, foregroundPgid: () => terminal.pid },
-      () => terminal,
+      async () => terminal,
     )
     const session = await backend.spawn(spec(agent(ctx)))
     expect(session.motd).toBe('dsh> ')
@@ -217,7 +345,7 @@ describe('pty-local plugin shape', () => {
     const loader = Object.create(Loader.prototype) as Loader
     const unwrapped = loader.unwrapExports(ptyLocal) as Record<string, unknown>
     expect(unwrapped.name).toBe('pty-local')
-    expect(unwrapped.inject).toEqual(['pty', 'sandbox', 'sandboxPolicy'])
+    expect(unwrapped.inject).toEqual(['pty', 'sandboxPolicy', 'subprocess'])
     expect(unwrapped.Config).toBeDefined()
   })
 
@@ -225,8 +353,8 @@ describe('pty-local plugin shape', () => {
     const ctx = new Context()
     await ctx.plugin(AgentRegistry)
     await ctx.plugin(PtyService)
-    await ctx.plugin(EmptySandbox)
     await ctx.plugin(SandboxPolicyService, { mode: 'danger-full-access', workspaceRoot: '/tmp' })
+    await ctx.plugin(StubSubprocessService)
     const fiber = await ctx.plugin(ptyLocal, config())
     expect(ctx.pty.listBackends()).toEqual(['shell'])
     await fiber.dispose()
@@ -240,6 +368,7 @@ describe('pty-local plugin shape', () => {
     await ctx.plugin(PtyService)
     await ctx.plugin(EmptySandbox)
     await ctx.plugin(SandboxPolicyService, { mode: 'danger-full-access', workspaceRoot: '/tmp' })
+    await ctx.plugin(StubSubprocessService)
     await ctx.plugin(ptyLocal, config())
 
     const session = ctx.sessions.create(SessionId('unowned-mode'))
@@ -256,6 +385,7 @@ describe('pty-local plugin shape', () => {
     await ctx.plugin(PtyService)
     await ctx.plugin(RecordingSandbox)
     await ctx.plugin(SandboxPolicyService, { mode: 'danger-full-access', workspaceRoot: '/tmp' })
+    await ctx.plugin(StubSubprocessService)
 
     const session = ctx.sessions.create(SessionId('mode-owner'))
     const ownerFiber = await ctx.plugin(() => {})
@@ -304,6 +434,7 @@ describe('pty-local plugin shape', () => {
     await ctx.plugin(PtyService)
     await ctx.plugin(RecordingSandbox)
     await ctx.plugin(SandboxPolicyService, { mode: 'danger-full-access', workspaceRoot: '/tmp' })
+    await ctx.plugin(StubSubprocessService)
 
     const session = ctx.sessions.create(SessionId('pending-mode-owner'))
     const ownerFiber = await ctx.plugin(() => {})

packages/pty/pty-local/tests/local.spec.ts

@@ -1,4 +1,4 @@
-import { mkdtempSync, realpathSync, rmSync } from 'node:fs'
+import { existsSync, mkdtempSync, readFileSync, realpathSync, rmSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
@@ -11,6 +11,7 @@ import type { PtySendOperation } from '@deepseek-ai/dsh-pty'
 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 * as ptyLocal from '@deepseek-ai/dsh-pty-local'
 
 const roots: string[] = []
@@ -57,6 +58,7 @@ async function harness(
   await ctx.plugin(PtyService)
   await ctx.plugin(PassthroughSandbox)
   await ctx.plugin(SandboxPolicyService, { mode, workspaceRoot: root })
+  await ctx.plugin(LocalSubprocessService)
   const fiber = await ctx.plugin(ptyLocal, {
     pollIntervalMs: 10,
     exactProbeAfterMs: 20,
@@ -96,6 +98,22 @@ function expectReadyForNextSend(waitReason: string): void {
   expect(['stdin_read', 'inferred_idle']).toContain(waitReason)
 }
 
+function processIsRunning(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+  } catch (_missingProcess) {
+    return false
+  }
+  if (process.platform !== 'linux') return true
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, 'utf8')
+    const state = stat.slice(stat.lastIndexOf(')') + 2).split(/\s+/, 1)[0]
+    return !/^[ZXx]$/.test(state ?? '')
+  } catch (_unreadableProcEntry) {
+    return false
+  }
+}
+
 describe('pty-local real shell', () => {
   it('persists cwd and environment across sends, scrubs secrets, and closes', async () => {
     const previous = process.env.DSH_TEST_SECRET
@@ -154,6 +172,47 @@ describe('pty-local real shell', () => {
     expect(() => process.kill(pid, 0)).toThrow()
   }, 10_000)
 
+  it('quiesces a disowned same-session descendant after the shell exits naturally', async () => {
+    const { ctx, root, agent } = await harness('danger-full-access')
+    const created = await ctx.pty.spawn(agent, { type: 'shell' })
+    const pidFile = join(root, 'disowned.pid')
+    let pid: number | undefined
+    try {
+      const background = ctx.pty.startSend(agent, created.sessionId, {
+        text: `sh -c 'trap "" TERM; printf "%s" "$$" > "$1"; sleep 60' dsh "${pidFile}" & disown`,
+        submit: true,
+      })
+      await background.done
+      const pidDeadline = Date.now() + 2_000
+      let childPid = 0
+      while (childPid === 0 && Date.now() < pidDeadline) {
+        if (existsSync(pidFile)) childPid = Number(readFileSync(pidFile, 'utf8'))
+        if (childPid > 0) break
+        await new Promise(resolve => setTimeout(resolve, 10))
+      }
+      expect(existsSync(pidFile), ctx.pty.read(agent, created.sessionId, { offset: 0, count: 100 }).text).toBe(true)
+      expect(childPid).toBeGreaterThan(0)
+      pid = childPid
+      expect(() => process.kill(childPid, 0)).not.toThrow()
+      await ctx.pty.startSend(agent, created.sessionId, { text: 'exit', submit: true }).done
+      const deadline = Date.now() + 2_000
+      while (ctx.pty.list(agent)[0]?.status.kind !== 'exited' && Date.now() < deadline) {
+        await new Promise(resolve => setTimeout(resolve, 10))
+      }
+      expect(ctx.pty.list(agent)[0]?.status.kind).toBe('exited')
+      await ctx.pty.kill(agent, created.sessionId)
+      expect(processIsRunning(childPid)).toBe(false)
+    } finally {
+      if (pid !== undefined) {
+        try {
+          process.kill(pid, 'SIGKILL')
+        } catch (_alreadyReaped) {
+          // Product cleanup is the expected path; this only contains a failed regression.
+        }
+      }
+    }
+  }, 10_000)
+
   it('cancels a slow-starting raw-mode foreground process with a real SIGINT', async () => {
     const { ctx, agent } = await harness('danger-full-access', {
       idleSilenceMs: 10_000,

packages/pty/pty-local/tests/sanitize.spec.ts

@@ -7,7 +7,7 @@ describe('TerminalSanitizer', () => {
     expect(sanitizer.push('red\x1b[3')).toEqual({ text: 'red', prompt: false })
     expect(sanitizer.push('1m text\x1b[0m\r\n')).toEqual({ text: ' text\n', prompt: false })
     expect(sanitizer.push('\x1b]133;')).toEqual({ text: '', prompt: false })
-    expect(sanitizer.push('D;0\x07dsh> ')).toEqual({ text: 'dsh> ', prompt: true, promptText: true })
+    expect(sanitizer.push('D;0\x07dsh> ')).toEqual({ text: 'dsh> ', prompt: true, promptTail: 'dsh> ' })
   })
 
   it('drops unrelated OSC, short escapes, BEL, and incomplete trailing escape', () => {
@@ -35,8 +35,8 @@ describe('TerminalSanitizer', () => {
 
   it('reports printable prompt text that follows a marker in a later chunk', () => {
     const sanitizer = new TerminalSanitizer(64)
-    expect(sanitizer.push('\x1b]133;D;0\x07')).toEqual({ text: '', prompt: true })
-    expect(sanitizer.push('dsh> ')).toEqual({ text: 'dsh> ', prompt: false, promptText: true })
+    expect(sanitizer.push('\x1b]133;D;0\x07')).toEqual({ text: '', prompt: true, promptTail: '' })
+    expect(sanitizer.push('dsh> ')).toEqual({ text: 'dsh> ', prompt: false, promptTail: 'dsh> ' })
   })
 
   it('bounds and discards unterminated control sequences through their terminators', () => {