@deepseek-ai/dsh-subprocess-local 0.1.1-rc.2 → 0.1.2-alpha.2

package/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/subprocess/subprocess-local/README.md
-README.md: 0935bb309bd10dec7503a74708a28442223bf296
-README.zh.md: 2f37cbce8df0b5f454d2301b78b44961cf66ea31
+README.md: 5e609bf96002c62d18684517bcd815e6f4fc0bb0
+README.zh.md: 9e53c9f9444c0c19ed4ec337357a9151d8f90328

package/README.md

@@ -1,23 +1,115 @@
+---
+description: "The local host provider for the subprocess service: run managed process trees and real terminal sessions on the host machine."
+kind: "package-reference"
+---
+
 # @deepseek-ai/dsh-subprocess-local
 
 English | [中文](README.zh.md)
 
-Local Service Provider for the [`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam. `LocalSubprocessRuntime` resolves local executables, spawns ordinary detached process trees with explicit stdio, and implements terminal processes through `node-pty` plus platform process inspection. It has no config: every disposition, limit, terminal dimension, grace, and directory arrives from the calling capability seams ([`dsh-bash-local`](../../shell/bash-local/README.md), [`dsh-lsp-stdio`](../../lsp/lsp-stdio/README.md), and [`dsh-terminal-bash`](../../terminal/terminal-bash/README.md)).
+## Summary
+
+Mount `dsh-subprocess-local` in any composition that runs child processes on the host: it resolves local executables, spawns detached process trees with explicit stdio, and provides real terminal sessions through `node-pty`. It has no configuration, so every disposition, limit, terminal size, and grace arrives on the spawn request from the calling capability seam. Output collection keeps a bounded in-memory tail with optional spill files for full-stream recovery, children start from a scrubbed environment, and disposal terminates and joins every running tree.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Mount the provider beside its consumers and start processes exactly as the subprocess service specifies; this package decides only how those processes run on the host.
+
+### Mounting the provider
+
+Load the provider in the same composition as its consumers. It has no config fields: every choice arrives on the spawn request, so deployment-varying decisions stay with the caller's configuration.
+
+```yaml
+- name: '@deepseek-ai/dsh-subprocess-local'
+- name: '@deepseek-ai/dsh-bash-local'
+```
+
+### Resolving executables
+
+Absolute executable paths are verified; bare names resolve against the scrubbed PATH with platform-aware executable extensions (`.COM`/`.EXE`/`.BAT`/`.CMD` on Windows). Relative paths containing separators are rejected — provide an absolute path or a bare PATH name — and relative PATH entries resolve from the host process cwd.
+
+### Collecting output
+
+Collect mode keeps the last `maxBytes` of a stream in memory — errors and final results cluster at the end — and, when a `spill` cap is configured, appends the complete stream to a private file under a per-process directory in the OS temp dir (a `0700` directory, `0600` random-named files). A stream larger than the spill cap discards its incomplete spill and returns only the marked truncated tail. Reads are offset-based and non-consuming, so background and batch readers coexist before and after exit.
+
+### Running terminal sessions
+
+`spawnTerminal` allocates a real PTY and bridges UTF-8 text; you can inspect and signal the current foreground process group and await a `terminate()` that settles every session member the provider can still observe. On Linux, an exact input wait requires a foreground thread whose fd 0 identifies the shell's controlling terminal and whose current syscall waits on that fd. If the kernel denies the syscall probe, the provider reports no exact wait and leaves the higher PTY backend to its idle inference; process sleep state is not evidence. On Windows, SIGINT is delivered as a Ctrl-C input write, SIGTSTP and SIGHUP are unsupported, and teardown verifies the shell's termination through the process table because an externally killed shell may never fire the PTY exit notification.
+
+### Shutdown behavior
+
+Normal disposal terminates every running tree and terminal and awaits their exit. During a JavaScript-observable host exit — direct `process.exit()`, default uncaught exceptions, default unhandled rejections — a synchronous finalization force-terminates everything still owned (SIGKILL to the group, `taskkill /T /F` on Windows) without creating promises or timers. Unhandled `SIGTERM`/`SIGINT`/`SIGHUP`, `SIGKILL`, fatal OOM, native crashes, and power loss need an external supervisor.
+
+### What can go wrong
+
+An executable that cannot be resolved fails loud with a stable error; a spawn that never starts rejects `done`. A read past the retained tail is `lossy` and points at the spill file when one exists. A daemonized descendant that leaves the tree or terminal session can outlive cleanup — see the limitations below.
+
+-----
 
-## Behavior
+<a id="understand-the-implementation"></a>
+## Understand the implementation
 
-- **Detached process trees with platform-correct signalling** — POSIX children are spawned `detached` (own process group) and signalled by negative pgid with a direct-child fallback; Windows terminates the tree via `taskkill /PID <pid> /T /F`. `terminate()` — the handle's only termination verb — sends SIGTERM then SIGKILL after the spec's grace (OpenCode's escalation; pipelines and subshells die with the parent) and is a no-op once the tree is gone; `waitForExit()` polls whole-tree liveness so consumer teardown confirms real quiescence. After the leader exits, still-open pipes receive the same bounded drain grace so a surviving descendant cannot hold the outcome open indefinitely. ESRCH is tolerated; daemons that re-parent away from the group can still survive.
-- **Per-stream dispositions** — `'pipe'` hands the raw stream to the caller untouched (protocol framing stays consumer-owned); `'inherit'` passes the parent descriptor through; collect mode keeps the in-memory TAIL beyond its cap (errors and results cluster at the end — pi/OpenCode rationale) while the FULL stream is appended to a private temp file when a spill cap is configured — omitting `spill` keeps only the tail, the diagnostic shape. A stream larger than the spill cap discards its now-incomplete spill and returns only the marked truncated tail; spill fds are sealed at settlement, and a failed final close withholds the path rather than advertising an incomplete file. Spill files are `0600` with random names under a lazily-created `0700` per-process directory.
-- **Credential scrub + explicit merge** — `process.env` minus credential-shaped vars (`*KEY*`/`*PASSWORD*`/`*SECRET*`/`*TOKEN*`) and all ambient `DSH_*` names; the spec's explicit `env` merges after that scrub with no namespace validation, so a deliberately supplied credential or current `DSH_*` fact wins while stale nested-harness identity cannot leak in ambiently. Supplied stdin is written and closed; otherwise fd 0 is `/dev/null`. See the [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-api.md) and [managed environment Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md).
-- **Offset-based reads** — collect-mode readers return deltas in whole-stream byte coordinates; the service never holds a cursor, so consumer-owned cursors (the bash background read path) and full-stream re-reads coexist, before and after settlement.
-- **Executable lookup** — `resolveExecutable` checks absolute files or searches the scrubbed effective PATH with platform-aware executable extensions; relative paths containing separators are rejected at the seam, and relative PATH entries resolve from the host process cwd.
-- **Terminal-process ownership** — `spawnTerminal` allocates `node-pty`, bridges UTF-8 terminal text, inspects and signals the current foreground process group, and exposes one awaited termination operation that sweeps descendants before and after terminating the top-level shell. Each foreground inspection retains exact identities from the rooted tree; Linux also enumerates the POSIX session after its leader exits. A previously observed macOS descendant and any same-session Linux member therefore remain fenced after reparenting, while pid/start identity prevents cleanup from following PID reuse. On Windows the koffi-backed inspector enumerates the process table through Toolhelp32, combines GetProcessTimes start identities with zero-time process-handle waits for liveness, reports the shell pid as the pseudo foreground group (Windows has no POSIX groups), and teardown verifies the shell's termination because externally taskkilled shells may never fire node-pty's exit notification. The higher PTY backend owns prompt readiness, buffers, and model-facing operations.
-- **Terminate-and-join disposal** — the service retains live handles so its own disposal can escalate every running tree and await its exit; quiescent and spawn-failed handles leave the live set after whole-tree or terminal-session cleanup finishes.
-- **Synchronous host-exit finalization** — while the service effect is active, a Node `exit` listener force-terminates every ordinary tree and observable terminal session still in the same live sets. The local-only operations send POSIX SIGKILL to the managed group, run Windows `taskkill /T /F`, and synchronously signal captured/current terminal identities around the PTY root kill; they create no promise or timer, preserve the host's exit code and diagnostic, contain each target's failure, and do not claim quiescence. Normal disposal keeps the awaited graceful path above. See the [host-exit cleanup decision](../../../.agents/notes/implemented/bug-fix/2026-08-11-synchronous-subprocess-exit-cleanup.md).
+<details>
+<summary>Implementation internals — click to expand</summary>
 
+This section explains the design decisions behind the provider and points at the code that realizes them; the observable behavior is covered in [Use this package](#use-this-package).
+
+### Design concept
+
+The provider treats the process tree as the unit of lifetime. POSIX children spawn detached (their own process group) so the whole tree is signalled by negative group id with a direct-child fallback; Windows terminates by root pid through `taskkill /T`. Signalling, escalation, and teardown guard on tree liveness rather than direct-child settlement, so a TERM-trapping helper cannot outlive the handle unnoticed.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Service wiring: live-handle sets, disposal, host-exit finalization, executable lookup |
+| [`src/spawn.ts`](src/spawn.ts) | Process plumbing: detached spawn, tail-keep collection, spill files, escalation, tree-exit observer |
+| [`src/terminal.ts`](src/terminal.ts) | `node-pty` terminal handle: foreground inspection, session cleanup, Windows teardown |
+| [`src/process-inspector.ts`](src/process-inspector.ts) | POSIX process-tree and session inspection |
+| [`src/windows-inspector.ts`](src/windows-inspector.ts) | Windows Toolhelp32 process-table inspection via koffi |
+| [`src/invariant.ts`](src/invariant.ts) | Invariant companion (no runtime invariant; the seam owns the contract) |
+
+### Main flow
+
+A spawn builds the scrubbed child environment, starts the detached process, attaches collectors to the collected streams, and returns a handle. `done` settles at process close after a bounded pipe-drain grace, so a surviving descendant that inherited a pipe cannot hold the outcome open indefinitely; the escalation timer survives direct-child settlement so SIGKILL still reaches tree survivors. Terminal cleanup sweeps descendants by exact identity, stops the shell, re-sweeps, and verifies absence through the process table.
+
+### Safety invariants
+
+Spill files are opened `0600` with `O_EXCL` and random names under a `0700` per-process directory, defeating symlink planting in shared temp dirs; a failed final close withholds the spill path. Process identities carry start times, so cleanup never follows PID reuse. Host-exit finalization creates no promises or timers, preserves the host exit code and diagnostic, contains each target's failure, and does not claim quiescence.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when the provider-level contract is not enough. They move from the exhaustive type reference to the abstract contract and the decisions behind the host mechanics.
+
+- [Subprocess subsystem](../../../docs/subsystems/subprocess.md) — spawn specs, output readers, outcomes, and the `DSH_*` environment in full.
+- [dsh-subprocess](../subprocess/README.md) — the abstract contract this provider implements.
+- [dsh-bash-local](../../shell/bash-local/README.md) — the largest consumer and the concrete stdio shapes it asks for.
+- [Subprocess seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md) — why the process half became its own seam.
+- [Synchronous subprocess exit cleanup](../../../.agents/notes/implemented/bug-fix/2026-08-11-synchronous-subprocess-exit-cleanup.md) — the host-exit finalization decision and its failure modes.
+
+-----
+
+<a id="model-experience"></a>
 ## Model Experience
 
-Indirectly, through Consumers (today the bash executor family behind `dsh-tool-bash`), which own all model-facing rendering of process output and lifecycle.
+Indirectly, through consumer seams such as the bash executor family, which own all model-facing rendering of spawned process output and lifecycle.
 
 #### KV Cache effect
 
@@ -25,11 +117,24 @@ No direct invalidation; the named consumers own any request-prefix changes.
 
 ## Known Limitations and Deferred Work
 
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define when the provider is a poor fit or needs special operational care. They are current package constraints, not a general platform comparison or a task backlog.
+
 - **Windows tree support is best-effort** — termination routes through `taskkill /PID <pid> /T /F` with all outcomes contained (absent tree, races, missing binary), and liveness falls back to the direct-child boundary.
-- **Windows terminal signalling is console-wide** — SIGINT is delivered as a `\x03` Ctrl-C input write that conhost turns into a console-wide CTRL_C event; SIGTSTP and SIGHUP are rejected as unavailable; a `taskkill` without `/F` does not terminate console processes, so the teardown TERM tier is a grace wait before the `/F` escalation. Windows readiness has no exact stdin-wait tier: the prompt-marker fast path compares the shell pid as the pseudo foreground group, and silence/timing tiers cover the rest.
-- **A daemonized terminal descendant can still escape the observable boundary** — on macOS, a child that reparents before any foreground-inspection snapshot is no longer discoverable from the `node-pty` root; on Linux, a child that calls `setsid` leaves both the tree and owned terminal session. The local provider does not add a continuous process-table monitor.
-- **In-process cleanup requires a JavaScript-observable exit** — direct `process.exit()`, default uncaught exceptions, and default unhandled rejections emit Node's synchronous `exit` event. The default OS disposition for an unhandled `SIGTERM`, `SIGINT`, or `SIGHUP` bypasses that event; an application covers those signals only by installing a handler that performs normal disposal or calls `process.exit()`. `SIGKILL`, fatal OOM, `process.abort()`, native crashes, power loss, and any failure that cannot run JavaScript require an external supervisor, container init, or equivalent OS owner.
-- **The credential scrub is a name heuristic** — `*KEY*`/`*PASSWORD*`/`*SECRET*`/`*TOKEN*` only; differently-named secrets (e.g. `*PASSPHRASE*`) pass through, and a whitelist for over-scrubbed vars is noted future work.
-- **Completed spill files are not deleted** — bounded full-output recovery files (and the private per-process spill dir) accumulate under the OS tmpdir until something external cleans them; oversize incomplete spills are discarded and deletion is attempted immediately, but a cleanup failure can leave a bounded file behind.
+- **Windows terminal signalling is console-wide** — SIGINT is delivered as a `\x03` Ctrl-C input write that conhost turns into a console-wide CTRL_C event; SIGTSTP and SIGHUP are rejected as unavailable; a `taskkill` without `/F` does not terminate console processes, so the teardown TERM tier is a grace wait before the `/F` escalation.
+- **A daemonized terminal descendant can still escape the observable boundary** — on macOS, a child that reparents before any foreground-inspection snapshot is no longer discoverable from the PTY root; on Linux, a `setsid` child leaves both the tree and the owned terminal session; the provider adds no continuous process-table monitor.
+- **In-process cleanup requires a JavaScript-observable exit** — direct `process.exit()`, default uncaught exceptions, and default unhandled rejections emit Node's synchronous `exit` event; an unhandled `SIGTERM`, `SIGINT`, or `SIGHUP`, `SIGKILL`, fatal OOM, `process.abort()`, native crashes, and power loss require an external supervisor, container init, or equivalent OS owner.
+- **The credential scrub is a name heuristic** — `*KEY*`/`*PASSWORD*`/`*SECRET*`/`*TOKEN*` only; differently named secrets (for example `*PASSPHRASE*`) pass through, and a whitelist for over-scrubbed variables is noted future work.
+- **Completed spill files are not deleted** — bounded full-output recovery files (and the private per-process spill directory) accumulate under the OS tmpdir until something external cleans them.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
 
-The raw process handling lives in `src/spawn.ts`; `src/index.ts` is the service wiring.
+</details>

package/README.zh.md

@@ -1,35 +1,140 @@
+---
+description: "面向部署方与维护者的子进程服务本地宿主提供方说明：在宿主机器上运行受管进程树与真实终端会话。"
+kind: "package-reference"
+---
+
 # @deepseek-ai/dsh-subprocess-local
 
 [English](README.md) | 中文
 
-[`@deepseek-ai/dsh-subprocess`](../subprocess/README.zh.md) seam 的本地 Service Provider。`LocalSubprocessRuntime` 解析本地可执行文件，以显式 stdio spawn 普通 detached 进程树，并通过 `node-pty` 加平台进程检查实现终端进程。该实现没有任何配置：每项处置方式、限制、终端尺寸、宽限期与目录都来自调用方能力 seam（[`dsh-bash-local`](../../shell/bash-local/README.zh.md)、[`dsh-lsp-stdio`](../../lsp/lsp-stdio/README.zh.md) 和 [`dsh-terminal-bash`](../../terminal/terminal-bash/README.zh.md)）。
+## 概述
+
+在需要于宿主机上运行子进程的组合中挂载 `dsh-subprocess-local`：它解析本地可执行文件、以显式 stdio 运行 detached 进程树，并通过 `node-pty` 提供真实终端会话。它没有任何配置，因此每项处置方式、限制、终端尺寸与宽限期都随 spawn 请求来自调用方能力 seam。输出收集在内存中保留一段有界尾部，并可选地用 spill 文件恢复完整流；子进程从清理后的环境起步；dispose（资源释放）会终止并等待每棵仍在运行的进程树退出。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+把提供方与它的消费方挂载在同一组合中，并完全按子进程服务的规定启动进程；本包只决定这些进程在宿主机上如何运行。
+
+### 挂载提供方
+
+在与消费方相同的组合中加载本提供方。它没有任何配置字段：每项选择都随 spawn 请求到达，因此随部署变化的决策留在调用方的配置里。
+
+```yaml
+- name: '@deepseek-ai/dsh-subprocess-local'
+- name: '@deepseek-ai/dsh-bash-local'
+```
+
+### 解析可执行文件
+
+绝对可执行文件路径会被验证；裸名称根据清理后的 PATH 并以平台感知的可执行文件扩展名（Windows 上为 `.COM`/`.EXE`/`.BAT`/`.CMD`）解析。含分隔符的相对路径会被拒绝——请提供绝对路径或裸 PATH 名称——相对 PATH 条目从宿主进程 cwd 解析。
+
+### 收集输出
+
+收集模式在内存中保留一条流的最后 `maxBytes`——错误与最终结果通常聚集在末尾——并在配置了 `spill` 上限时把完整流追加到 OS 临时目录下每进程目录中的私有文件（`0700` 目录、`0600` 随机命名文件）。某条流大于 spill 上限时，会丢弃不完整的 spill，只返回带截断标记的尾部。读取基于偏移量且从不消费，因此后台读取与批量读取在退出前后都可以共存。
+
+### 运行终端会话
+
+`spawnTerminal` 分配真实 PTY 并桥接 UTF-8 文本；你可以检查当前前台进程组并向其发送信号，还可以等待一次 `terminate()`，让提供方仍可观察到的每个会话成员完全停稳。在 Linux 上，精确输入等待要求前台线程的 fd 0 标识 shell 的控制终端，且线程当前的 syscall 正在等待该 fd。如果内核拒绝 syscall 探测，提供方不会报告精确等待，而由上层 PTY 后端使用空闲推断；进程睡眠状态不能作为证据。在 Windows 上，SIGINT 以 Ctrl-C 输入写入投递，SIGTSTP 与 SIGHUP 不受支持，拆卸会通过进程表验证 shell 已终止，因为被外部终止的 shell 可能永远不会触发 PTY 退出通知。
+
+### 关闭行为
+
+正常 dispose 会终止每棵仍在运行的进程树与终端并等待其退出。在 JavaScript 可观察的宿主退出期间——直接 `process.exit()`、默认未捕获异常、默认未处理 rejection——同步最终清理会强制终止所有仍归本包所有的对象（对进程组发送 SIGKILL，Windows 上运行 `taskkill /T /F`），且不创建任何 Promise 或定时器。未处理的 `SIGTERM`/`SIGINT`/`SIGHUP`、`SIGKILL`、fatal OOM、native crash 与断电则需要外部 supervisor。
+
+### 可能出错的地方
+
+无法解析的可执行文件会以稳定的错误快速失败；从未启动成功的 spawn 会让 `done` reject。越过保留尾部的读取是 `lossy` 的，并在 spill 文件存在时指向它。脱离进程树或终端会话的 daemon 化后代可能比清理更长寿——见下文限制。
+
+-----
 
-## 行为
+<a id="understand-the-implementation"></a>
+## 理解实现
 
-- **以适合平台的方式发送信号的 detached 进程树**：POSIX 子进程使用 `detached` spawn（拥有独立进程组），信号以负 pgid 发送并以直接子进程作为回退；Windows 通过 `taskkill /PID <pid> /T /F` 终止进程树。`terminate()`（句柄唯一的终止操作）先发送 SIGTERM，经过 spec 的宽限期后再发送 SIGKILL（沿用 OpenCode 的升级策略；流水线与子 shell 会随父进程一起结束），进程树消亡后为空操作；`waitForExit()` 轮询整棵进程树的存活状态，使消费方的拆卸能确认真正的完全停稳。组长进程退出后，仍然打开的管道也只获得同样有界的排空宽限期，因此存活的后代进程无法无限期地拖住结果不结算。系统会容忍 ESRCH；重新指定父进程并脱离该组的 daemon 仍可能存活。
-- **按流划分的处置方式**：`'pipe'` 把原始流原样交给调用方（协议分帧仍归消费方所有）；`'inherit'` 直通父进程的描述符；收集模式（collect）在输出超过上限后于内存中保留尾部（错误与结果通常聚集在末尾，沿用 pi/OpenCode 的理由），并在配置了 spill 上限时把完整流追加到一个私有临时文件；省略 `spill` 则只保留用于诊断的尾部。某条流大于 spill 上限时，会丢弃已不完整的 spill，仅返回带截断标记的尾部；spill 文件描述符在结算时封存，最终关闭失败时则不公布路径，以免声称存在不完整的文件。spill 文件权限为 `0600`、名称随机，位于按需创建、权限为 `0700` 的每进程目录之下。
-- **凭据清除 + 显式合并**：以 `process.env` 为基础，移除形似凭据的变量（`*KEY*`／`*PASSWORD*`／`*SECRET*`／`*TOKEN*`）和所有环境中已有的 `DSH_*` 名称；spec 的显式 `env` 在该清除之后合并且不做命名空间校验，因此有意提供的凭据或当前 `DSH_*` 事实会胜出，而陈旧的嵌套 harness 身份无法从环境中隐式漏入。提供的 stdin 会被写入后关闭；否则 fd 0 指向 `/dev/null`。参见 [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-api.zh.md)与[受管环境 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.zh.md)。
-- **基于偏移量的读取**：收集模式的读取器按完整流的字节坐标返回增量；服务自身从不持有游标，因此消费方自有的游标（bash 的后台读取路径）与完整流重读可以共存，结算前后皆然。
-- **可执行文件查找**：`resolveExecutable` 检查绝对文件，或根据平台可执行文件扩展名在清理后的有效 PATH 中搜索；含分隔符的相对路径在该 seam 处被拒绝，相对 PATH 条目从宿主进程 cwd 解析。
-- **终端进程所有权**：`spawnTerminal` 分配 `node-pty`，桥接 UTF-8 终端文本，检查当前前台进程组并向其发送信号，还会公开一项须等待的终止操作，在终止顶层 shell 前后清理后代进程。每次前台检查都会保留根进程树中的精确身份；Linux 还会在 POSIX 会话 leader 退出后枚举该会话。因此，之前观察到的 macOS 后代以及同会话 Linux 成员在重新设定父进程后仍受围栏保护，pid/start 身份则防止清理跟随 PID 复用。在 Windows 上，基于 koffi 的检查器通过 Toolhelp32 枚举进程表，把 GetProcessTimes 启动身份与进程句柄零时等待结合起来判断存活状态，并把 shell pid 作为伪前台进程组（Windows 没有 POSIX 进程组）。拆卸会验证 shell 已终止，因为被外部 taskkill 的 shell 可能永远不会触发 node-pty 的退出通知。上层 PTY 后端负责提示符就绪、缓冲区与面向模型的操作。
-- **先终止再等待退出的 dispose（资源释放）**：服务保留存活句柄，使自身的 dispose 能对每个仍在运行的进程树执行升级并等待其退出；完全停稳与 spawn 失败的句柄会在整棵进程树或 terminal session 清理完成后离开存活集合。
-- **同步宿主退出最终清理**：服务 effect 仍有效时，Node `exit` listener 会强制终止同一组存活集合中仍存在的每棵普通进程树和可观察 terminal session。这些仅供本地实现使用的操作会向受管 POSIX 进程组发送 SIGKILL、在 Windows 运行 `taskkill /T /F`，并在终止 PTY root 前后同步向已捕获及当前可观察的 terminal 身份发送信号；它们不会创建 Promise 或 timer，不改变宿主退出码与诊断，会分别包含每个目标的失败，也不会声称已经完全停稳。正常 dispose 仍使用上面的须等待温和路径。参见[宿主退出清理决策](../../../.agents/notes/implemented/bug-fix/2026-08-11-synchronous-subprocess-exit-cleanup.zh.md)。
+<details>
+<summary>实现细节——点击展开</summary>
 
+本节解释提供方背后的设计决策，并指出实现它们的代码位置；可观察行为已在[使用本包](#use-this-package)中说明。
+
+### 设计理念
+
+本提供方把进程树视为生命周期单元。POSIX 子进程以 detached 方式 spawn（拥有独立进程组），因此整棵进程树以负进程组 id 发送信号，并以直接子进程作为回退；Windows 通过 `taskkill /T` 按根 pid 终止。信号发送、升级与拆卸都以进程树存活状态为守卫，而非以直接子进程结算为准，因此拦截 TERM 的辅助进程无法在无人察觉的情况下比句柄更长寿。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 服务接线：存活句柄集合、dispose、宿主退出最终清理、可执行文件查找 |
+| [`src/spawn.ts`](src/spawn.ts) | 进程管道：detached spawn、保尾收集、spill 文件、升级、进程树退出观察器 |
+| [`src/terminal.ts`](src/terminal.ts) | `node-pty` 终端句柄：前台检查、会话清理、Windows 拆卸 |
+| [`src/process-inspector.ts`](src/process-inspector.ts) | POSIX 进程树与会话检查 |
+| [`src/windows-inspector.ts`](src/windows-inspector.ts) | 经 koffi 的 Windows Toolhelp32 进程表检查 |
+| [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件（无运行时不变式；约定归 seam 所有） |
+
+### 主流程
+
+一次 spawn 会构建清理后的子进程环境、启动 detached 进程、把收集器挂到收集模式的流上，然后返回句柄。`done` 在进程关闭后、经过一段有界管道排空宽限期才结算，因此继承了管道的存活后代无法无限期拖住结果；升级定时器在直接子进程结算后依然存活，使 SIGKILL 仍能到达进程树幸存者。终端清理按精确身份清扫后代、停止 shell、再次清扫，并通过进程表验证其已不存在。
+
+### 安全不变式
+
+spill 文件以 `0600` 权限、`O_EXCL` 与随机名称在 `0700` 每进程目录下创建，可抵御共享临时目录中的符号链接植入；最终关闭失败时不公布 spill 路径。进程身份携带启动时间，因此清理绝不会跟随 PID 复用。宿主退出最终清理不创建 Promise 或定时器，保留宿主退出码与诊断，分别包含每个目标的失败，也不会声称已经完全停稳。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当提供方级约定不够用时阅读以下页面。它们从穷尽式类型参考逐步进入抽象约定，以及宿主机制背后的决策。
+
+- [子进程子系统](../../../docs/subsystems/subprocess.zh.md)——spawn spec、输出读取器、结果与完整的 `DSH_*` 环境。
+- [dsh-subprocess](../subprocess/README.zh.md)——本提供方实现的抽象约定。
+- [dsh-bash-local](../../shell/bash-local/README.zh.md)——最大的消费方及其请求的具体 stdio 形态。
+- [subprocess seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.zh.md)——进程部分为何成为独立的 seam。
+- [同步子进程退出清理](../../../.agents/notes/implemented/bug-fix/2026-08-11-synchronous-subprocess-exit-cleanup.zh.md)——宿主退出最终清理决策及其失败模式。
+
+-----
+
+<a id="model-experience"></a>
 ## 模型体验
 
-通过 Consumer 间接影响（目前是 `dsh-tool-bash` 背后的 bash 执行器家族）；进程输出与生命周期面向模型的全部渲染归 Consumer 所有。
+通过消费方 seam（例如 bash 执行器家族）间接影响，它们负责所 spawn 进程的输出与生命周期的全部面向模型渲染。
 
 #### KV Cache 影响
 
 不会直接导致 KV Cache 失效；请求前缀变更由上述消费方负责。
 
-## 已知限制与暂缓事项
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明本提供方何时不合适，或何时需要特别的运维注意。它们是当前包约束，不是通用平台对比或任务积压。
+
+- **Windows 进程树支持仅为尽力而为**——终止经由 `taskkill /PID <pid> /T /F` 完成，所有结果都被就地吸收（进程树已不存在、竞态、二进制缺失），存活探测则回退到直接子进程边界。
+- **Windows 终端信号是控制台级的**——SIGINT 以 `\x03` Ctrl-C 输入写入投递，由 conhost 转为控制台级 CTRL_C 事件；SIGTSTP 与 SIGHUP 因不可用而被拒绝；不带 `/F` 的 `taskkill` 无法终止控制台进程，因此拆卸的 TERM 档是 `/F` 升级前的宽限等待。
+- **守护化的终端后代仍可能逃出可观察边界**——在 macOS 上，子进程如果在任何前台检查快照之前重新设定父进程，将无法再从 PTY 根进程发现；在 Linux 上，调用 `setsid` 的子进程会同时离开进程树与自有终端会话；本提供方不新增持续进程表监视器。
+- **进程内清理要求退出阶段仍能执行 JavaScript**——直接 `process.exit()`、默认未捕获异常和默认未处理 rejection 会发出 Node 同步 `exit` 事件；未处理的 `SIGTERM`、`SIGINT` 或 `SIGHUP`、`SIGKILL`、fatal OOM、`process.abort()`、native crash 与断电，都需要外部 supervisor、容器 init 或等价的 OS 所有者负责。
+- **凭据清除依赖名称启发式规则**——只匹配 `*KEY*`/`*PASSWORD*`/`*SECRET*`/`*TOKEN*`；名称不同的 secret（例如 `*PASSPHRASE*`）会继续传递，对误删变量引入白名单属于已记录的后续工作。
+- **不会删除已完成的 spill 文件**——有界的完整输出恢复文件（以及每进程私有 spill 目录）会在 OS tmpdir 下累积，直到外部机制进行清理。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
 
-- **Windows 进程树支持仅为尽力而为**：终止经由 `taskkill /PID <pid> /T /F` 完成，所有结果都被就地吸收，不向外抛出（进程树已不存在、竞态、二进制缺失），存活探测则回退到直接子进程边界。
-- **Windows 终端信号是控制台级的**：SIGINT 以 `\x03` Ctrl-C 输入写入投递，由 conhost 转为控制台级 CTRL_C 事件；SIGTSTP 与 SIGHUP 被拒绝（不可用）；不带 `/F` 的 `taskkill` 无法终止控制台进程，因此拆卸的 TERM 档是 `/F` 升级前的宽限等待。Windows 就绪没有精确的 stdin-wait 档：prompt-marker 快路径把 shell pid 作为伪前台进程组比较，其余由静默/计时档覆盖。
-- **守护化的终端后代仍可能逃出可观察边界**：在 macOS 上，子进程如果在任何前台检查快照之前重新设定父进程，将无法再从 `node-pty` 根进程发现；在 Linux 上，调用 `setsid` 的子进程会同时离开进程树与自有终端会话。本地提供方不会新增持续进程表监视器。
-- **进程内清理要求退出阶段仍能执行 JavaScript**：直接 `process.exit()`、默认未捕获异常和默认未处理 rejection 会发出 Node 同步 `exit` 事件。未安装 handler 时，`SIGTERM`、`SIGINT` 或 `SIGHUP` 的默认 OS 处置不会发出该事件；应用只有安装执行正常 dispose 或调用 `process.exit()` 的 handler 才能覆盖这些信号。`SIGKILL`、fatal OOM、`process.abort()`、native crash、断电，以及任何无法运行 JavaScript 的故障，都需要外部 supervisor、容器 init 或等价的 OS 所有者负责。
-- **凭据清除依赖名称启发式规则**：只匹配 `*KEY*`／`*PASSWORD*`／`*SECRET*`／`*TOKEN*`；名称不同的 secret（例如 `*PASSPHRASE*`）会继续传递，对误删变量引入白名单属于已记录的后续工作。
-- **不会删除已完成的 spill 文件**：有界的完整输出恢复文件（以及每个进程的私有 spill 目录）会在 OS tmpdir 下累积，直到外部机制进行清理；超大的不完整 spill 会被丢弃并立即尝试删除，但清理失败可能留下一个有界文件。
+无。
 
-原始进程处理位于 `src/spawn.ts`；`src/index.ts` 负责服务接线。
+</details>

package/lib/index.js

@@ -1,4 +1,4 @@
-import { closeSync, constants, mkdtempSync, openSync, readFileSync, readSync, readdirSync, unlinkSync, writeSync } from "node:fs";
+import { closeSync, constants, mkdtempSync, openSync, readFileSync, readSync, readdirSync, readlinkSync, statSync, unlinkSync, writeSync } from "node:fs";
 import { access, stat } from "node:fs/promises";
 import { delimiter, extname, isAbsolute, join, resolve } from "node:path";
 import * as nodePty from "node-pty";
@@ -70,19 +70,21 @@ var WindowsProcessInspector = class {
 	foregroundPgid(shellPid) {
 		return shellPid;
 	}
-	isStdinWaiting(_pgid) {
+	isStdinWaiting(_pgid, _shellPid) {
 		return false;
 	}
-	processTree(rootPid) {
-		return windowsProcessTree(this.internals.snapshot(), rootPid, (pid) => this.internals.processState(pid)?.started);
-	}
-	processSession(_sessionId) {
-		return [];
-	}
 	isAlive(identity) {
 		const state = this.internals.processState(identity.pid);
 		return state?.active === true && state.started === identity.started;
 	}
+	snapshot() {
+		let entries;
+		return {
+			tree: (rootPid) => windowsProcessTree(entries ??= this.internals.snapshot(), rootPid, (pid) => this.internals.processState(pid)?.started),
+			session: () => [],
+			alive: (identity) => this.isAlive(identity)
+		};
+	}
 	signalGroup(pgid, signal) {
 		this.internals.taskkill(pgid, signal === "SIGKILL");
 	}
@@ -264,6 +266,8 @@ function defaultWindowsProcessInternals() {
 const DEFAULT_INTERNALS = {
 	readFile: (path) => readFileSync(path, "utf8"),
 	readDir: (path) => readdirSync(path),
+	readLink: (path) => readlinkSync(path, "utf8"),
+	stat: (path) => statSync(path),
 	open: (path) => openSync(path, "r"),
 	read: (fd, buffer, length, position) => readSync(fd, buffer, 0, length, position),
 	close: closeSync,
@@ -285,6 +289,7 @@ function parseProcStat(text) {
 	const parentPid = Number(rest[1]);
 	const pgrp = Number(rest[2]);
 	const session = Number(rest[3]);
+	const ttyDevice = Number(rest[4]);
 	const tpgid = Number(rest[5]);
 	const started = rest[19];
 	if (![
@@ -292,6 +297,7 @@ function parseProcStat(text) {
 		parentPid,
 		pgrp,
 		session,
+		ttyDevice,
 		tpgid
 	].every(Number.isSafeInteger) || state.length !== 1 || started === void 0) return void 0;
 	return {
@@ -300,6 +306,7 @@ function parseProcStat(text) {
 		pgrp,
 		session,
 		state,
+		ttyDevice,
 		tpgid,
 		started
 	};
@@ -311,6 +318,21 @@ function readLinuxStat(internals, pid) {
 		return;
 	}
 }
+function linuxDeviceNumber(value) {
+	return value >>> 0;
+}
+function readLinuxTerminalDevice(internals, pid, ttyDevice, tid) {
+	const terminalDevice = linuxDeviceNumber(ttyDevice);
+	if (terminalDevice === 0) return void 0;
+	const path = tid === void 0 ? `/proc/${pid}/fd/0` : `/proc/${pid}/task/${tid}/fd/0`;
+	try {
+		if (internals.readLink(path) === "/dev/tty") return terminalDevice;
+		const status = internals.stat(path);
+		return status.isCharacterDevice() && linuxDeviceNumber(status.rdev) === terminalDevice ? terminalDevice : void 0;
+	} catch (_unreadableStdinDevice) {
+		return;
+	}
+}
 /**
 * Report whether a Linux process group has an executing member. `false`
 * means the group contains only zombie/dead entries; `undefined` means the
@@ -382,9 +404,9 @@ function pollHasStdin(internals, pid, address, count) {
 	for (let offset = 0; offset + 8 <= memory.length; offset += 8) if (memory.readInt32LE(offset) === 0 && (memory.readInt16LE(offset + 4) & 1) !== 0) return true;
 	return false;
 }
-function epollHasStdin(internals, pid, epfd) {
+function epollHasStdin(internals, pid, tid, epfd) {
 	try {
-		return internals.readFile(`/proc/${pid}/fdinfo/${epfd}`).split("\n").some((line) => /^tfd:\s+0\b/.test(line.trim()));
+		return internals.readFile(`/proc/${pid}/task/${tid}/fdinfo/${epfd}`).split("\n").some((line) => /^tfd:\s+0\b/.test(line.trim()));
 	} catch (_unreadableFdInfo) {
 		return false;
 	}
@@ -406,12 +428,20 @@ const SYSCALLS = {
 		epollPwait: 22
 	}
 };
-function syscallWaitsOnStdin(internals, pid, syscall, table) {
+const SUPPORTED_SYSCALL_TABLES = Object.values(SYSCALLS);
+function linuxSyscallTables(arch) {
+	const primary = SYSCALLS[arch];
+	if (primary === void 0) return void 0;
+	return [primary, ...SUPPORTED_SYSCALL_TABLES.filter((table) => table !== primary)];
+}
+function syscallWaitsOnStdin(internals, pid, tid, syscall, tables) {
 	const [a0 = 0, a1 = 0, a2 = 0] = syscall.args;
-	if (syscall.number === table.read) return a0 === 0;
-	if (syscall.number === table.select || syscall.number === table.pselect) return a0 >= 1 && fdSetHasStdin(internals, pid, a1);
-	if (syscall.number === table.poll || syscall.number === table.ppoll) return a1 >= 1 && pollHasStdin(internals, pid, a0, a1);
-	if (syscall.number === table.epollWait || syscall.number === table.epollPwait) return a2 >= 1 && epollHasStdin(internals, pid, a0);
+	for (const table of tables) {
+		if (syscall.number === table.read) return a0 === 0;
+		if (syscall.number === table.select || syscall.number === table.pselect) return a0 >= 1 && fdSetHasStdin(internals, pid, a1);
+		if (syscall.number === table.poll || syscall.number === table.ppoll) return a1 >= 1 && pollHasStdin(internals, pid, a0, a1);
+		if (syscall.number === table.epollWait || syscall.number === table.epollPwait) return a2 >= 1 && epollHasStdin(internals, pid, tid, a0);
+	}
 	return false;
 }
 var PosixProcessInspector = class {
@@ -426,6 +456,30 @@ var PosixProcessInspector = class {
 		if (this.isAlive(identity)) this.internals.kill(identity.pid, signal);
 	}
 };
+function quiescent(state) {
+	return state !== void 0 && /^[ZXx]$/.test(state);
+}
+var PosixProcessSnapshot = class {
+	rows;
+	byPid;
+	constructor(rows) {
+		this.rows = rows;
+		this.byPid = new Map(rows.map((row) => [row.pid, row]));
+	}
+	tree(rootPid) {
+		return processTree(this.rows, rootPid);
+	}
+	session(sessionId) {
+		return this.rows.flatMap((row) => row.session === sessionId ? [{
+			pid: row.pid,
+			started: row.started
+		}] : []);
+	}
+	alive(identity) {
+		const row = this.byPid.get(identity.pid);
+		return row?.started === identity.started && !quiescent(row.state);
+	}
+};
 function processTree(entries, rootPid) {
 	const root = new Map(entries.map((entry) => [entry.pid, entry])).get(rootPid);
 	if (root === void 0) return [];
@@ -459,40 +513,38 @@ var LinuxProcessInspector = class extends PosixProcessInspector {
 		const tpgid = readLinuxStat(this.internals, shellPid)?.tpgid;
 		return tpgid !== void 0 && tpgid > 0 ? tpgid : void 0;
 	}
-	isStdinWaiting(pgid) {
-		const table = SYSCALLS[this.arch];
-		if (table === void 0) return false;
+	isStdinWaiting(pgid, shellPid) {
+		const tables = linuxSyscallTables(this.arch);
+		if (tables === void 0) return false;
+		const shell = readLinuxStat(this.internals, shellPid);
+		if (shell === void 0) return false;
+		const terminalDevice = readLinuxTerminalDevice(this.internals, shellPid, shell.ttyDevice);
+		if (terminalDevice === void 0) return false;
 		for (const pid of numericEntries(this.internals, "/proc")) {
-			if (readLinuxStat(this.internals, pid)?.pgrp !== pgid) continue;
+			const process = readLinuxStat(this.internals, pid);
+			if (process?.pgrp !== pgid) continue;
 			for (const tid of numericEntries(this.internals, `/proc/${pid}/task`)) {
 				const syscall = readSyscall(this.internals, pid, tid);
-				if (syscall !== void 0 && syscallWaitsOnStdin(this.internals, pid, syscall, table)) return true;
+				if (syscall !== void 0 && syscallWaitsOnStdin(this.internals, pid, tid, syscall, tables) && readLinuxTerminalDevice(this.internals, pid, process.ttyDevice, tid) === terminalDevice) return true;
 			}
 		}
 		return false;
 	}
-	processTree(rootPid) {
-		return processTree(numericEntries(this.internals, "/proc").flatMap((pid) => {
+	isAlive(identity) {
+		const stat = readLinuxStat(this.internals, identity.pid);
+		return stat?.started === identity.started && !quiescent(stat.state);
+	}
+	snapshot() {
+		return new PosixProcessSnapshot(numericEntries(this.internals, "/proc").flatMap((pid) => {
 			const stat = readLinuxStat(this.internals, pid);
 			return stat === void 0 ? [] : [{
 				pid,
 				parentPid: stat.parentPid,
-				started: stat.started
+				started: stat.started,
+				session: stat.session,
+				state: stat.state
 			}];
-		}), rootPid);
-	}
-	processSession(sessionId) {
-		return numericEntries(this.internals, "/proc").flatMap((pid) => {
-			const stat = readLinuxStat(this.internals, pid);
-			return stat?.session === sessionId ? [{
-				pid,
-				started: stat.started
-			}] : [];
-		});
-	}
-	isAlive(identity) {
-		const stat = readLinuxStat(this.internals, identity.pid);
-		return stat?.started === identity.started && !/^[ZXx]$/.test(stat.state);
+		}));
 	}
 };
 function macProcessTable(internals) {
@@ -502,7 +554,9 @@ function macProcessTable(internals) {
 		return [{
 			pid: Number(match[1]),
 			parentPid: Number(match[2]),
-			started: match[3]
+			started: match[3],
+			session: void 0,
+			state: void 0
 		}];
 	});
 }
@@ -520,18 +574,15 @@ var MacProcessInspector = class extends PosixProcessInspector {
 			return;
 		}
 	}
-	isStdinWaiting(_pgid) {
+	isStdinWaiting(_pgid, _shellPid) {
 		return false;
 	}
-	processTree(rootPid) {
-		return processTree(macProcessTable(this.internals), rootPid);
-	}
-	processSession(_sessionId) {
-		return [];
-	}
 	isAlive(identity) {
 		return macProcessTable(this.internals).some((entry) => entry.pid === identity.pid && entry.started === identity.started);
 	}
+	snapshot() {
+		return new PosixProcessSnapshot(macProcessTable(this.internals));
+	}
 };
 /**
 * Create the supported platform inspector or fail at plugin load.
@@ -997,7 +1048,7 @@ var LocalTerminalHandle = class {
 		this.graceMs = graceMs;
 		this.platform = platform;
 		this.pid = terminal.pid;
-		this.rootIdentity = inspector.processTree(this.pid).find((member) => member.pid === this.pid);
+		this.rootIdentity = inspector.snapshot().tree(this.pid).find((member) => member.pid === this.pid);
 		this.done = this.outcome.promise;
 		this.dataDisposable = terminal.onData((data) => {
 			this.output.write(Buffer$1.from(data, "utf8"));
@@ -1017,12 +1068,12 @@ var LocalTerminalHandle = class {
 		this.terminal.write(data);
 	}
 	async inspectForeground() {
-		this.descendants();
+		this.descendants(this.inspector.snapshot());
 		const processGroupId = this.inspector.foregroundPgid(this.pid);
 		if (processGroupId === void 0) return void 0;
 		return {
 			processGroupId,
-			inputWaiting: this.inspector.isStdinWaiting(processGroupId)
+			inputWaiting: this.inspector.isStdinWaiting(processGroupId, this.pid)
 		};
 	}
 	async signalForeground(signal) {
@@ -1069,22 +1120,23 @@ var LocalTerminalHandle = class {
 			this.terminal.kill("SIGKILL");
 		} catch (_unidentifiedShellExitedDuringHostExit) {}
 	}
-	survivors(members) {
-		return members.filter((member) => this.inspector.isAlive(member));
+	survivors(members, observed) {
+		return members.filter((member) => observed.alive(member));
 	}
-	descendants() {
-		const tree = this.inspector.processTree(this.pid);
+	descendants(observed) {
+		const tree = observed.tree(this.pid);
 		const root = tree.find((member) => member.pid === this.pid);
 		const rootVerified = this.rootIdentity !== void 0 && root !== void 0 && root.started === this.rootIdentity.started;
-		this.trackedDescendants = this.survivors(this.unionMembers(this.trackedDescendants, ...rootVerified ? [tree, this.inspector.processSession(this.pid)] : []).filter((member) => member.pid !== this.pid));
+		this.trackedDescendants = this.survivors(this.unionMembers(this.trackedDescendants, ...rootVerified ? [tree, observed.session(this.pid)] : []).filter((member) => member.pid !== this.pid), observed);
 		return this.trackedDescendants;
 	}
 	async waitForMembers(members) {
+		if (members.length === 0) return [];
 		const until = Date.now() + this.graceMs;
-		let survivors = this.survivors(members);
+		let survivors = this.survivors(members, this.inspector.snapshot());
 		while (survivors.length > 0 && Date.now() < until) {
 			await delay(Math.min(25, Math.max(1, until - Date.now())));
-			survivors = this.survivors(members);
+			survivors = this.survivors(members, this.inspector.snapshot());
 		}
 		return survivors;
 	}
@@ -1096,7 +1148,7 @@ var LocalTerminalHandle = class {
 	forceStopDescendants() {
 		let members = this.trackedDescendants;
 		try {
-			members = this.descendants();
+			members = this.descendants(this.inspector.snapshot());
 		} catch (_processTableUnavailableDuringHostExit) {}
 		this.signalMembers(members, "SIGKILL");
 	}
@@ -1112,13 +1164,14 @@ var LocalTerminalHandle = class {
 		return members;
 	}
 	async stopDescendants() {
-		const captured = this.descendants();
+		const captured = this.descendants(this.inspector.snapshot());
 		this.signalMembers(captured, "SIGTERM");
 		const capturedSurvivors = await this.waitForMembers(captured);
-		const members = this.unionMembers(capturedSurvivors, this.descendants());
+		const members = this.unionMembers(capturedSurvivors, this.descendants(this.inspector.snapshot()));
 		this.signalMembers(members, "SIGKILL");
 		const survivors = await this.waitForMembers(members);
-		return this.survivors(this.unionMembers(survivors, this.descendants()));
+		const observed = this.inspector.snapshot();
+		return this.survivors(this.unionMembers(survivors, this.descendants(observed)), observed);
 	}
 	async stopShell() {
 		if (this.platform === "win32") {

package/lib/types/process-inspector.d.ts

@@ -5,23 +5,93 @@ export interface ProcessIdentity {
     pid: number;
     started: string;
 }
+interface FileStatus {
+    readonly rdev: number;
+    isCharacterDevice(): boolean;
+}
+/**
+ * One observation of the platform process table, shared by every question a
+ * single readiness poll or teardown pass asks.
+ *
+ * The table is read at most once, on the first question that needs it — a
+ * `/bin/ps` fork on macOS, a `/proc` walk on Linux, a Toolhelp32 enumeration on
+ * Windows. Later questions never re-read it, which is what keeps a poll's cost
+ * independent of how many descendants the running command spawned. Windows
+ * liveness needs no table at all: wait state is a per-handle question there, so
+ * a snapshot asked only for liveness never enumerates.
+ *
+ * A snapshot answers what the process table showed, which is what batch
+ * filtering wants and what signalling must not use: {@link ProcessInspector.isAlive}
+ * is the fence a signal takes, because it reads current state instead.
+ */
+export interface ProcessSnapshot {
+    /**
+     * Return the root and its transitive descendants as observed, children first.
+     * @param rootPid - tree root to descend from.
+     * @returns Observed root and descendants, children before parents.
+     */
+    tree(rootPid: number): ProcessIdentity[];
+    /**
+     * Return observed members of one POSIX process session.
+     * @param sessionId - POSIX session identifier.
+     * @returns Observed session members, empty where the platform's table omits session ids.
+     */
+    session(sessionId: number): ProcessIdentity[];
+    /**
+     * Return whether the exact identity was a non-quiescent process.
+     * @param identity - PID plus start identity to match.
+     * @returns Whether that exact identity — not merely that PID — was running.
+     */
+    alive(identity: ProcessIdentity): boolean;
+}
 /** Injectable OS process operations used by one local PTY session. */
 export interface ProcessInspector {
     foregroundPgid(shellPid: number): number | undefined;
-    isStdinWaiting(pgid: number): boolean;
-    /** Return the root and its current transitive descendants, children first. */
-    processTree(rootPid: number): ProcessIdentity[];
-    /** Return current members of one POSIX process session when the platform exposes them. */
-    processSession(sessionId: number): ProcessIdentity[];
-    /** Return whether the exact identity remains a non-quiescent process. */
+    /**
+     * Report whether the foreground group waits on the terminal shell's stdin.
+     *
+     * @param pgid Foreground process-group identifier.
+     * @param shellPid Persistent terminal shell process identifier.
+     * @returns Whether a group member is blocked reading the shell's terminal input.
+     */
+    isStdinWaiting(pgid: number, shellPid: number): boolean;
+    /**
+     * Read the process table once and answer tree, session, and liveness from it.
+     * @returns A process-table observation whose reads are shared.
+     */
+    snapshot(): ProcessSnapshot;
+    /**
+     * Return whether the exact identity is a non-quiescent process right now.
+     *
+     * Reads the narrowest per-identity source the platform offers rather than a
+     * whole table, so a signalling round can re-check every target without
+     * paying for a scan. Callers filtering many members at once want
+     * {@link ProcessSnapshot.alive} instead.
+     *
+     * @param identity - PID plus start identity to match.
+     * @returns Whether that exact identity — not merely that PID — is running.
+     */
     isAlive(identity: ProcessIdentity): boolean;
     signalGroup(pgid: number, signal: SubprocessTerminalSignal): void;
+    /**
+     * Signal one exact process identity, fenced against PID reuse.
+     *
+     * The fence reads current state immediately before the signal. An observation
+     * taken earlier in the same round cannot stand in for it: the observation
+     * preserves the original PID-to-start-time pairing, so a recycled PID would
+     * still match and take a signal meant for the process that exited.
+     *
+     * @param identity - PID plus start identity to signal.
+     * @param signal - termination signal to deliver.
+     */
     signalProcess(identity: ProcessIdentity, signal: 'SIGTERM' | 'SIGKILL'): void;
 }
 /** Testable boundary around filesystem, process-table, and signal syscalls. */
 export interface ProcessInspectorInternals {
     readFile(path: string): string;
     readDir(path: string): string[];
+    readLink(path: string): string;
+    stat(path: string): FileStatus;
     open(path: string): number;
     read(fd: number, buffer: Buffer, length: number, position: number): number;
     close(fd: number): void;
@@ -34,6 +104,7 @@ interface ProcStat {
     pgrp: number;
     session: number;
     state: string;
+    ttyDevice: number;
     tpgid: number;
     started: string;
 }

package/lib/types/windows-inspector.d.ts

@@ -9,7 +9,7 @@
  * @module dsh-subprocess-local/windows-inspector
  */
 import type { SubprocessTerminalSignal } from '@deepseek-ai/dsh-subprocess';
-import type { ProcessIdentity, ProcessInspector } from './process-inspector.ts';
+import type { ProcessIdentity, ProcessInspector, ProcessSnapshot } from './process-inspector.ts';
 /** One Toolhelp32 process-table row. */
 export interface ProcessEntry {
     pid: number;
@@ -52,10 +52,9 @@ export declare class WindowsProcessInspector implements ProcessInspector {
     private readonly internals;
     constructor(internals?: WindowsProcessInspectorInternals);
     foregroundPgid(shellPid: number): number;
-    isStdinWaiting(_pgid: number): boolean;
-    processTree(rootPid: number): ProcessIdentity[];
-    processSession(_sessionId: number): ProcessIdentity[];
+    isStdinWaiting(_pgid: number, _shellPid: number): boolean;
     isAlive(identity: ProcessIdentity): boolean;
+    snapshot(): ProcessSnapshot;
     signalGroup(pgid: number, signal: SubprocessTerminalSignal): void;
     signalProcess(identity: ProcessIdentity, signal: 'SIGTERM' | 'SIGKILL'): void;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-subprocess-local",
   "description": "Local-subprocess implementation of the DeepSeek Harness subprocess seam",
-  "version": "0.1.1-rc.2",
+  "version": "0.1.2-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -33,21 +33,21 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-subprocess": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-timeout": "^0.1.1-rc.2",
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2"
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-subprocess": "^0.1.2-alpha.2",
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-timeout": "^0.1.2-alpha.2"
   },
   "dependencies": {
     "koffi": "^3.1.0",
     "node-pty": "1.2.0-beta.15"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-loader-smoke": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-subprocess": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-timeout": "^0.1.1-rc.2",
-    "@deepseek-ai/cordis": "^4.0.1"
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-loader-smoke": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-subprocess": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-timeout": "^0.1.2-alpha.2",
+    "@deepseek-ai/cordis": "^4.0.2"
   },
   "scripts": {
     "postinstall": "node scripts/ensure-spawn-helper.mjs"