From d404609e19e9f548d55bbd427a1b6a4c8d378d96 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 26 Jul 2026 22:54:44 +0800
Subject: [PATCH] docs(subprocess): bring the zh side of the consumer-migration
 pairs along

The parent branch's zh translations were recorded against its pre-reshape
en text; this PR's Node-ward en deltas get minimal zh updates across the
subprocess catalog and the subprocess/lsp-local/subagent READMEs (all
type-equiv blocks byte-identical), with pairing records re-recorded.
---
 .../core-data-structures/subprocess.i18n.yaml |   4 +-
 docs/core-data-structures/subprocess.zh.md    | 225 ++++++++++++++----
 packages/lsp/lsp-local/README.i18n.yaml       |   4 +-
 packages/lsp/lsp-local/README.zh.md           |   2 +-
 packages/subagent/README.i18n.yaml            |   4 +-
 packages/subagent/README.zh.md                |   3 +-
 .../subagent/subagent-acp/README.i18n.yaml    |   4 +-
 packages/subagent/subagent-acp/README.zh.md   |   2 +-
 packages/subprocess/README.i18n.yaml          |   4 +-
 packages/subprocess/README.zh.md              |   6 +-
 .../subprocess-local/README.i18n.yaml         |   4 +-
 .../subprocess/subprocess-local/README.zh.md  |  12 +-
 .../subprocess/subprocess/README.i18n.yaml    |   4 +-
 packages/subprocess/subprocess/README.zh.md   |  17 +-
 14 files changed, 209 insertions(+), 86 deletions(-)

diff --git a/docs/core-data-structures/subprocess.i18n.yaml b/docs/core-data-structures/subprocess.i18n.yaml
index 10be6b6d75..0527cf34a3 100644
--- a/docs/core-data-structures/subprocess.i18n.yaml
+++ b/docs/core-data-structures/subprocess.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
-subprocess.md: 2481afe324b0cbd2404186ae79670da81038f8f5
-subprocess.zh.md: 291233c456f73a1ea80de19290a6fc71a1f22725
+subprocess.md: cdd4507c7d37f47ca243ddf38114f5aa6b6f3ad1
+subprocess.zh.md: 78325c3255c42ed591bbd98fdbdb4fdfcba48202
diff --git a/docs/core-data-structures/subprocess.zh.md b/docs/core-data-structures/subprocess.zh.md
index 291233c456..78325c3255 100644
--- a/docs/core-data-structures/subprocess.zh.md
+++ b/docs/core-data-structures/subprocess.zh.md
@@ -2,13 +2,13 @@
 
 [English](subprocess.md) | 中文
 
-进程管理器 seam 分为接口（[dsh-subprocess](../../packages/subprocess/subprocess)，`ctx.subprocess`）与实现（[dsh-subprocess-local](../../packages/subprocess/subprocess-local)）；它的消费方是其他能力 seam：目前是 [bash 执行器家族](bash.md)，后者传入 `['bash', '-c', command]` argv，并拥有每一项默认值。该 seam 拥有受管的 `DSH_*` 环境命名空间与 `CollectedOutput` 形状；[dsh-bash](../../packages/bash/bash) 将二者重导出，使 bash 消费方保持单一导入入口。
+进程管理器 seam 分为接口（[dsh-subprocess](../../packages/subprocess/subprocess)，`ctx.subprocess`）与实现（[dsh-subprocess-local](../../packages/subprocess/subprocess-local)）；它的消费方是其他能力 seam 与进程外后端：[bash 执行器家族](bash.md)使用收集模式（collect）的批量输出，LSP 主机使用管道化的协议流 + 收集的 stderr 尾部，ACP（Agent Client Protocol）subagent 后端则使用管道化的协议流 + inherit 的 stderr。该 seam 拥有受管的 `DSH_*` 环境命名空间、共享的凭据清除（`scrubbedParentEnv`）与 `CollectedOutput` 形状；[dsh-bash](../../packages/bash/bash) 重导出这套词汇，使 bash 消费方保持单一导入入口。
 
 源码：[`packages/subprocess/subprocess/src/types.ts`](../../packages/subprocess/subprocess/src/types.ts)
 
 ## 受管环境命名空间与捕获的输出
 
-`DSH_*` 变量是归 Harness 所有的子进程事实；实现会在合并调用方快照之前丢弃环境中已有的 `DSH_*` 名称，每条被捕获的流都通过 `CollectedOutput` 报告自身的截断与 spill 恢复状态。
+`DSH_*` 变量是归 Harness 所有的子进程事实；实现会在合并调用方快照之前丢弃环境中已有的 `DSH_*` 名称，每条被收集的流都通过 `CollectedOutput` 报告自身的截断与 spill 恢复状态。
 
 ```ts type-equiv
 /** One environment key inside the managed {@link DSH_ENV_PREFIX} namespace. */
@@ -32,83 +32,170 @@ interface CollectedOutput {
 }
 ```
 
-## 完全显式的 spawn spec
+## Node 形状的 stdio 处置方式（disposition）
 
-该 seam 不应用任何默认值：每项限制与目录都在 spec 上显式给出，因此由调用方自己的配置决定它们，而不是由某个隐藏的进程管理器默认值决定。`argv` 绝不经过 shell 解释。
+每条流的处置方式都显式给出，由各消费方自行选择：原始管道用于协议分帧（LSP JSON-RPC、ACP ndjson），inherit 用于直通的诊断输出，收集模式用于有界的批量输出；其中 spill 文件是可选的，因此诊断尾部（语言服务器的 stderr）可以只在内存中缓冲，不留下任何文件。
 
 ```ts type-equiv
 /**
- * A fully-specified spawn request. This seam applies no defaults: every limit
- * and directory is explicit, so the caller's own config — not a hidden
- * subprocess-service default — decides them (the `dsh-bash` request/spec split
- * is the owning template).
+ * stdin disposition. `'ignore'` leaves fd 0 on `/dev/null`; `'pipe'` exposes
+ * {@link SubprocessHandle.stdin} for the caller's ongoing protocol writes;
+ * `{ data }` writes the bytes and closes (the batch shape).
+ */
+type SubprocessStdinMode = 'ignore' | 'pipe' | { readonly data: string }
+```
+
+```ts type-equiv
+/**
+ * Bounded in-memory collection for one output stream, with an optional
+ * full-stream spill file. Omitting `spill` keeps only the in-memory tail —
+ * the diagnostic-tail shape (a language server's stderr); including it makes
+ * the complete stream recoverable up to its cap (the bash tool shape).
+ */
+interface SubprocessCollect {
+  /** In-memory cap in bytes; overflow keeps the TAIL. */
+  maxBytes: number
+  /** Full-stream spill file; absent disables spilling entirely. */
+  spill?: {
+    /** Whole-stream byte cap; a larger stream discards its now-incomplete spill. */
+    maxBytes: number
+  }
+}
+```
+
+```ts type-equiv
+/**
+ * stdout/stderr disposition. `'pipe'` exposes the raw `Readable` for the
+ * caller's protocol decoding; `'inherit'` passes the parent's descriptor
+ * through (child diagnostics land on the harness's own stream); a
+ * {@link SubprocessCollect} object buffers boundedly with offset-based reads.
+ */
+type SubprocessOutputMode = 'pipe' | 'inherit' | SubprocessCollect
+```
+
+```ts type-equiv
+/** Per-stream stdio dispositions, all explicit — this seam applies no defaults. */
+interface SubprocessStdio {
+  stdin: SubprocessStdinMode
+  stdout: SubprocessOutputMode
+  stderr: SubprocessOutputMode
+}
+```
+
+## 完全显式的 spawn spec
+
+该 seam 不应用任何默认值：每项处置方式、限制与目录都在 spec 上显式给出，因此由调用方自己的配置决定它们，而不是由某个隐藏的进程管理器默认值决定。`argv` 绝不经过 shell 解释。
+
+```ts type-equiv
+/**
+ * A fully-specified spawn request. This seam applies no defaults: every
+ * disposition, limit, and directory is explicit, so the caller's own config —
+ * not a hidden subprocess-service default — decides them (the `dsh-bash`
+ * request/spec split is the owning template).
  */
 interface SubprocessSpawnSpec {
   /** Executable and arguments; `argv[0]` is the program. Never shell-interpreted here. */
   argv: readonly string[]
   /** Working directory for the child. */
   cwd: string
-  /** Stdout in-memory cap; overflow spills to disk (tail kept in memory). */
-  stdoutMaxBytes: number
-  /** Stderr in-memory cap; overflow spills to disk (tail kept in memory). */
-  stderrMaxBytes: number
-  /** Per-stream spill-file cap; larger streams retain only their in-memory tail. */
-  maxSpillBytes: number
-  /** Grace period for kill escalation and for inherited pipes after process exit. */
+  /** Per-stream stdio dispositions. */
+  stdio: SubprocessStdio
+  /**
+   * Grace period in milliseconds for the {@link SubprocessHandle.terminate}
+   * escalation and for draining still-open collected pipes after the process
+   * exits (an inherited descriptor held by a surviving descendant cannot hold
+   * the outcome open indefinitely).
+   */
   graceMs: number
   /**
-   * Abort signal — kills the process group when it fires. The caller owns
-   * deadlines and cause classification; this seam only reacts to the abort.
+   * Abort signal — starts the terminate escalation on the process tree when
+   * it fires. The caller owns deadlines and cause classification; this seam
+   * only reacts to the abort.
    */
   signal?: AbortSignal | undefined
   /**
-   * Bytes to write to the child's stdin, then close it. Absent (or empty)
-   * leaves stdin closed/empty.
-   */
-  stdin?: string | undefined
-  /**
-   * Ordinary environment entries merged after the implementation's credential
-   * scrub. `DSH_*` names are rejected and belong in {@link dshEnv}.
+   * Ordinary environment entries merged onto the implementation's scrubbed
+   * parent base (see `scrubbedParentEnv`). `DSH_*` names are rejected and
+   * belong in {@link dshEnv}; a deliberately forwarded credential-shaped
+   * entry survives because this layer merges after the scrub.
    */
   env?: Record<string, string> | undefined
   /**
-   * Harness-owned `DSH_*` variables for this execution. Implementations
-   * discard ambient `DSH_*` entries before merging this snapshot, so an
-   * unavailable current fact cannot inherit a stale value from the harness
-   * process, and reject non-`DSH_*` names supplied through this channel.
+   * Harness-owned `DSH_*` variables for this execution. The scrubbed base has
+   * already discarded ambient `DSH_*` entries, so an unavailable current fact
+   * cannot inherit a stale value from the harness process; non-`DSH_*` names
+   * on this channel are rejected.
    */
   dshEnv?: DshEnvironment | undefined
 }
 ```
 
-## 句柄与基于偏移量的读取
+## 句柄：流、读取器与以进程树为范围的终止
 
-spawn 会立即返回一个实时句柄。输出读取器接受全流字节偏移量且从不消费，因此独立的读取器不会抢走彼此的增量；bash 工具呈现的消费游标模型，是消费方在这些读取器之上自行持有的状态。
+spawn 会立即返回一个实时句柄。收集模式的读取器接受全流字节偏移量且从不消费，因此独立的读取器不会抢走彼此的增量；管道化的流归调用方所有。终止在每个平台上都以进程树为范围：`kill(signal)` 以 Node 风格只发送一个信号，`terminate()` 执行 SIGTERM→宽限期→SIGKILL 升级，`waitForExit()` 观察整棵进程树，`dispose(graces)` 运行进程外子进程所需的协作式 stdin EOF→SIGTERM→SIGKILL 阶梯。
 
 ```ts type-equiv
 /**
- * A live child process. `kill()` starts the group SIGTERM→grace→SIGKILL
- * escalation; buffered output remains readable after exit.
+ * A live child process rooted in its own process tree. Collected output
+ * remains readable after exit; piped streams belong to the caller.
+ *
+ * Termination is tree-scoped everywhere: POSIX signals the detached process
+ * group (falling back to the direct child when the group is gone), Windows
+ * terminates the tree via `taskkill /T`, so helper processes cannot outlive
+ * the handle unnoticed.
  */
 interface SubprocessHandle {
-  /** Process id (group leader); -1 when the spawn itself failed. */
+  /** Process id (tree root); -1 when the spawn itself failed. */
   readonly pid: number
-  /** Live stdout reader (also readable after exit). */
-  readonly stdout: SubprocessOutputReader
-  /** Live stderr reader (also readable after exit). */
-  readonly stderr: SubprocessOutputReader
-  /** Resolves when the process closes; rejects only for spawn-level failures. */
+  /** The child's stdin, present iff spawned with `stdin: 'pipe'`. */
+  readonly stdin: Writable | undefined
+  /** The child's raw stdout, present iff spawned with `stdout: 'pipe'`. */
+  readonly stdout: Readable | undefined
+  /** The child's raw stderr, present iff spawned with `stderr: 'pipe'`. */
+  readonly stderr: Readable | undefined
+  /** Offset-based readers for collect-mode streams (also readable after exit). */
+  readonly collected: SubprocessCollectedOutputs
+  /** Resolves at process close with exit facts; rejects only for spawn-level failures. */
   readonly done: Promise<SubprocessOutcome>
-  /** Begin SIGTERM→grace→SIGKILL on the process group. Idempotent. */
-  kill(): void
+  /**
+   * Send one signal to the process tree, Node-style — no escalation, no
+   * timers. A no-op after the outcome has settled (the pid may be reused).
+   * @param signal - the signal to deliver (default `SIGTERM`; Windows
+   *   force-terminates the tree for any value).
+   */
+  kill(signal?: NodeJS.Signals): void
+  /**
+   * Begin the SIGTERM → `graceMs` → SIGKILL escalation on the process tree
+   * (Windows force-terminates immediately). Idempotent; also triggered by the
+   * spec's abort signal.
+   */
+  terminate(): void
+  /**
+   * Wait until the process tree has exited — the tree, not just the direct
+   * child, so a still-running helper is observable before teardown returns.
+   * @param signal - optional bound for the wait.
+   * @returns `true` when the tree exited, `false` when the signal aborted first.
+   */
+  waitForExit(signal?: AbortSignal): Promise<boolean>
+  /**
+   * Tear the child down to quiescence, resolving only after exit: close stdin
+   * (when this handle owns a piped one) and allow cooperative flush for
+   * `eofGraceMs`, then SIGTERM with a `graceMs` window (POSIX), then forced
+   * tree termination with a final bounded `graceMs` wait.
+   * @param graces - the ladder's two windows, from the consumer's Config.
+   * @throws when the child still has not exited `graceMs` after the forced tier.
+   */
+  dispose(graces: SubprocessDisposeGraces): Promise<void>
 }
 ```
 
 ```ts type-equiv
 /**
- * Cursor-free incremental access to one live output stream. Offsets are
+ * Cursor-free incremental access to one collected output stream. Offsets are
  * whole-stream byte coordinates owned by the caller, so independent readers
- * cannot consume one another's output.
+ * cannot consume one another's output; `readFrom(0)` after settlement is the
+ * batch result (`lossy` then means the in-memory tail lost its head — the
+ * {@link CollectedOutput.truncated} fact).
  */
 interface SubprocessOutputReader {
   /**
@@ -136,26 +223,62 @@ interface SubprocessOutputRead {
 }
 ```
 
-## 结果不携带原因分类
-
-`done` 报告原始退出事实。服务会在中止时终止进程，但绝不判定原因：调用方读取归自己所有的 deadline 信号，以区分超时与取消（即 bash 执行器的 `timedOut`/`aborted` 拆分）。
+```ts type-equiv
+/** Offset-based readers for the streams spawned in collect mode. */
+interface SubprocessCollectedOutputs {
+  /** Present iff stdout is a {@link SubprocessCollect}. */
+  readonly stdout?: SubprocessOutputReader
+  /** Present iff stderr is a {@link SubprocessCollect}. */
+  readonly stderr?: SubprocessOutputReader
+}
+```
 
 ```ts type-equiv
 /**
- * Raw outcome of one closed process. Deliberately carries NO timeout or
- * cancellation classification: the service kills on abort but does not decide
- * why — the caller reads the signal it owns to classify causes.
+ * The two grace periods of the cooperative dispose ladder
+ * ({@link SubprocessHandle.dispose}). Consumers carry them as defaulted,
+ * validated Config fields, so teardown timing is deployment-tunable and this
+ * seam hardcodes nothing.
+ */
+interface SubprocessDisposeGraces {
+  /**
+   * Tier-1 window (ms): after stdin EOF, how long the child gets to quiesce
+   * ON ITS OWN — flush durable state, tear down its own descendants — before
+   * escalation to platform termination. Usually WIDER than
+   * {@link SubprocessDisposeGraces.graceMs}: a cooperative child's EOF-driven
+   * teardown may itself wait on a signal-trapping grandchild plus a final
+   * flush.
+   */
+  eofGraceMs: number
+  /**
+   * Termination confirmation window (ms): POSIX applies it after `SIGTERM`
+   * and again after `SIGKILL`; Windows applies it after the forced tree
+   * termination.
+   */
+  graceMs: number
+}
+```
+
+## 结果只承载退出事实
+
+`done` 报告 Node close 事件的词汇，不携带原因分类：服务会在中止时终止进程，但绝不判定原因（调用方读取归自己所有的 deadline 信号，例如 bash 执行器的 `timedOut`/`aborted` 拆分）。收集到的输出在结算后仍可经 `handle.collected` 读取，因此批量与流式调用方共用一条访问路径。
+
+```ts type-equiv
+/**
+ * Exit facts of one closed process — Node's `close`-event vocabulary.
+ * Deliberately carries NO timeout or cancellation classification (the caller
+ * reads the signal it owns to classify causes) and NO output: collected
+ * streams stay readable through {@link SubprocessHandle.collected} after
+ * settlement, so batch and streaming callers share one access path.
  */
 interface SubprocessOutcome {
   /** Exit code; null when the process died from a signal. */
   exitCode: number | null
   /** Terminating signal (e.g. 'SIGTERM'); null on normal exit. */
   signal: NodeJS.Signals | null
-  stdout: CollectedOutput
-  stderr: CollectedOutput
 }
 ```
 
 ## 服务行为
 
-抽象的 [`SubprocessService`](../../packages/subprocess/subprocess/src/index.ts) seam 只定义 `spawn`；[`LocalSubprocessService`](../../packages/subprocess/subprocess-local/src/index.ts) 是本地实现（detached 进程组、以 spill 文件兜底的尾部保留收集、凭据清除、先终止再等待退出的 dispose（资源释放））。seam 契约见 [`dsh-subprocess`](../../packages/subprocess/subprocess/README.md)，具体机制见 [`dsh-subprocess-local`](../../packages/subprocess/subprocess-local/README.md)。
+抽象的 [`SubprocessService`](../../packages/subprocess/subprocess/src/index.ts) seam 只定义 `spawn`；[`LocalSubprocessService`](../../packages/subprocess/subprocess-local/src/index.ts) 是本地实现（detached 进程树、按处置方式接线的流、凭据清除、先终止再等待退出的 dispose（资源释放））。seam 契约见 [`dsh-subprocess`](../../packages/subprocess/subprocess/README.md)，具体机制见 [`dsh-subprocess-local`](../../packages/subprocess/subprocess-local/README.md)。
diff --git a/packages/lsp/lsp-local/README.i18n.yaml b/packages/lsp/lsp-local/README.i18n.yaml
index dcef438cf7..9532bc1cb3 100644
--- a/packages/lsp/lsp-local/README.i18n.yaml
+++ b/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
-README.md: 877c131ca4e34fdce59a46f820b889a1b9a73555
-README.zh.md: 58cf5a0558c680abd12b599ac7ef7696ce044877
+README.md: 462cb12ce96dbbb645c9a19126911d32d4ddd722
+README.zh.md: f5537a416c49106b128188efe4adb2d65304320a
diff --git a/packages/lsp/lsp-local/README.zh.md b/packages/lsp/lsp-local/README.zh.md
index 58cf5a0558..f5537a416c 100644
--- a/packages/lsp/lsp-local/README.zh.md
+++ b/packages/lsp/lsp-local/README.zh.md
@@ -12,7 +12,7 @@ Namespace 插件（`name`／`inject`／`Config`／`apply`，无默认导出）
 - 每个 `(server id, canonical workspace realpath)` 惰性 single-flight 一个服务器进程。存活服务器错误不会回放；如果选中的池化传输在只读查询之前或期间失败，提供方会等待其释放，并在新进程上重试该查询一次。
 - 每次查询都使用兼容性优先的**临时打开** 序列：通过 Node API 规范化并读取源文件、`textDocument/didOpen`（版本 1、完整文本）、所请求操作，然后执行 `textDocument/didClose`，该操作位于 `finally` 中。写入 `didOpen` 失败或取消时，会先终止实例再允许池复用。文档在每次调用后关闭，因此第一版不需要 `didChange`、内容 cache 或文档 LRU。
 - 通过一条逐 Workspace、可中止的队列，串行执行每个源读取／打开／查询／关闭生命周期，因此排队调用只会在轮到自身时读取当前源；不同 Workspace 并行运行。
-- 协议 shutdown 失败后，通过 POSIX 进程组信号或同步 Windows `taskkill /T /F` 终止服务器后代树。Windows 只抑制 taskkill 报告的树已不存在结果；命令、权限与其他树终止失败仍保持可见。
+- 协议 shutdown 失败后，经由进程管理器 seam 终止服务器后代树（POSIX 进程组信号；Windows `taskkill /T /F`）。树终止的投递结果与所有进程组信号一样被就地吸收，不向外抛出（投递与服务器退出存在竞态）；服务器是否完全停稳，由句柄的进程树存活等待确认，而非由这次终止自身的结果确认。
 - 通过子进程 host namespace 中的 Node 文件系统 API 读取源文件，绝不使用 `ctx.fs`，也不发出 `fs/observed`：只有 LSP 结果对模型可见，因此查询不满足先读后写策略。
 
 ## 配置
diff --git a/packages/subagent/README.i18n.yaml b/packages/subagent/README.i18n.yaml
index 7be70e0fe5..17e68d1607 100644
--- a/packages/subagent/README.i18n.yaml
+++ b/packages/subagent/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
-README.md: 5e3bddc67d213d74766a75da65cc44a21c8bb149
-README.zh.md: 4391809ee83c822fcada25f0bdc021af44be9354
+README.md: 8414836efd756f60258566ae3e4e00de2d4110d7
+README.zh.md: d32228495cd6c57398c88cea92ce168ecf278188
diff --git a/packages/subagent/README.zh.md b/packages/subagent/README.zh.md
index 4391809ee8..d32228495c 100644
--- a/packages/subagent/README.zh.md
+++ b/packages/subagent/README.zh.md
@@ -10,10 +10,9 @@ subagent seam 允许 agent（智能体）把工作委派给子 agent。与 [bash
 | `subagent-inprocess/` | 共享进程内运行驱动器（不提供提供方；每次运行使用一个清理 effect） | 无 |
 | `subagent-spawn/` | 进程内后端：全新的子 agent | （注册到 `ctx.subagents`） |
 | `subagent-fork/` | 进程内后端：以父 agent 已完成轮次的前缀作为初始内容的子 agent | （注册到 `ctx.subagents`） |
-| `subagent-subprocess/` | 共享进程外机制：环境变量清理、dispose（资源释放）阶梯、隔离配置目录（纯库；不注册任何内容） | 无 |
 | `subagent-acp/` | 进程外后端：在派生子进程中运行并通过 ACP（Agent Client Protocol）驱动的子 agent | （注册到 `ctx.subagents`） |
 | `tool-subagent/` | 面向模型的 `subagent` 委派工具，基于 `ctx.subagents` | （注册到 `ctx.tools`） |
 
-接口位于 `subagent/subagent/`。进程内 `subagent-spawn` / `subagent-fork` 后端共享 `subagent-inprocess` 驱动器（一个自身不提供提供方的库：两者都依赖它，彼此不依赖），进程外 `subagent-acp` 后端则构建于 `subagent-subprocess` 库之上（凭据环境变量清理、dispose 阶梯、隔离配置目录）。测试只用包内 fixture（测试前置数据）替换子 agent 边界。
+接口位于 `subagent/subagent/`。进程内 `subagent-spawn` / `subagent-fork` 后端共享 `subagent-inprocess` 驱动器（一个自身不提供提供方的库：两者都依赖它，彼此不依赖），进程外 `subagent-acp` 后端则经由 [`subprocess/`](../subprocess/README.md) seam spawn 其子进程（共享的凭据清除、以进程树为范围的拆卸、dispose（资源释放）阶梯）。测试只用包内 fixture（测试前置数据）替换子 agent 边界。
 
 提案与设计理由见 [.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)。
diff --git a/packages/subagent/subagent-acp/README.i18n.yaml b/packages/subagent/subagent-acp/README.i18n.yaml
index 72377b5f77..10d4b9a7cb 100644
--- a/packages/subagent/subagent-acp/README.i18n.yaml
+++ b/packages/subagent/subagent-acp/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
-README.md: d1ba03cf5256ad4889c4893bfe11af42bd627f9d
-README.zh.md: 5763ee9a22c1d0bfe12c7da2b7d996911b55cc49
+README.md: 317517f64f24d8a3ed01ebae08dcfd13668b9029
+README.zh.md: e10f435b13e7cdabb92ebfa5b4a5d0763f2af18f
diff --git a/packages/subagent/subagent-acp/README.zh.md b/packages/subagent/subagent-acp/README.zh.md
index 5763ee9a22..e10f435b13 100644
--- a/packages/subagent/subagent-acp/README.zh.md
+++ b/packages/subagent/subagent-acp/README.zh.md
@@ -57,7 +57,7 @@ ACP 不声明任何启动时能力，因为当前进程无法强制执行远程
 
 ## 进程边界
 
-子进程环境由 [`buildChildEnv`](../subagent-subprocess/README.md) 构建：先移除名称形似凭据的环境变量，再应用显式 `config.env` 值。ACP 协议是真正的序列化边界；同进程 subagent 值不会为防御目的而克隆。
+子进程经由 [`dsh-subprocess`](../../subprocess/subprocess/README.md) seam spawn：共享的凭据清除先移除名称形似凭据的环境变量，显式 `config.env` 值在清除之后合并（有意转发的 `DEEPSEEK_API_KEY` 会保留下来），stderr 以 inherit 方式直通父进程自身的流，dispose 则以本插件配置的宽限期运行该 seam 的协作式 stdin EOF→SIGTERM→SIGKILL 阶梯。ACP 协议是真正的序列化边界；同进程 subagent 值不会为防御目的而克隆。
 
 本包没有默认导出。否则 Cordis loader 的解包会隐藏具名 `inject` 元数据；见[事故复盘 0001](../../../docs/postmortem/0001-acp-default-export-drops-inject.md)。
 
diff --git a/packages/subprocess/README.i18n.yaml b/packages/subprocess/README.i18n.yaml
index 64edcdc78b..5224774c27 100644
--- a/packages/subprocess/README.i18n.yaml
+++ b/packages/subprocess/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
-README.md: f91609dc6b6e27fc26e5ffb4b7fd68fc9f4de556
-README.zh.md: d4e2cd69d21772834e0e55db2b14e19ea7ce1832
+README.md: 657855aff67230ee22b8137ae3aabc76aff8f860
+README.zh.md: 5281a0d6eddb38974d1225220bab08880224f14b
diff --git a/packages/subprocess/README.zh.md b/packages/subprocess/README.zh.md
index d4e2cd69d2..5281a0d6ed 100644
--- a/packages/subprocess/README.zh.md
+++ b/packages/subprocess/README.zh.md
@@ -2,11 +2,11 @@
 
 [English](README.md) | 中文
 
-spawn 受管子进程组的共用归属位置：完全显式的 spawn spec、附带 spill 文件的有界尾部保留输出、经凭据清除的环境、基于偏移量的增量读取，以及 SIGTERM→宽限期→SIGKILL 的进程组终止。命令默认值补全、shell 语义、deadline 与呈现留在消费方：[bash 执行器家族](../bash/README.md)是第一个消费方，也拥有上述各项。参见[进程管理器 seam Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
+spawn 受管子进程树的共用归属位置：完全显式的 spawn spec，其 stdio 处置方式（disposition）为 Node 形状、按流划分（原始管道、inherit、附带 spill 文件的有界尾部保留收集）；harness 中所有 spawn 调用方共用的那一份凭据清除；基于偏移量的增量读取；以进程树为范围、带 SIGTERM→宽限期→SIGKILL 升级的信号发送；以及协作式 dispose（资源释放）阶梯。命令默认值补全、shell 语义、deadline、协议分帧与呈现留在消费方：[bash 执行器](../bash/README.md)、[LSP 主机](../lsp/README.md)与 [ACP（Agent Client Protocol）subagent 后端](../subagent/README.md)。参见[进程管理器 seam Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
 
 | 包（package） | ctx 键 | 角色 |
 |---|---|---|
-| [`subprocess`](subprocess/README.md)（`@deepseek-ai/dsh-subprocess`） | `ctx.subprocess` | seam 本体：抽象的 `SubprocessService.spawn(spec)`、完全显式的 `SubprocessSpawnSpec`、携带基于偏移量读取器的 `SubprocessHandle`，以及共享的 `DSH_*` 受管环境与 `CollectedOutput` 词汇 |
-| [`subprocess-local`](subprocess-local/README.md)（`@deepseek-ai/dsh-subprocess-local`） | 无 | 本地实现：detached 进程组、附带有界私有 spill 文件的尾部保留截断、凭据清除与 `DSH_*` 合并次序、kill 升级，以及先终止再等待退出的 dispose（资源释放） |
+| [`subprocess`](subprocess/README.md)（`@deepseek-ai/dsh-subprocess`） | `ctx.subprocess` | seam 本体：抽象的 `SubprocessService.spawn(spec)`、完全显式且带按流划分 stdio 处置方式的 `SubprocessSpawnSpec`、`SubprocessHandle`（流、基于偏移量的读取器、kill/terminate/waitForExit/dispose），以及共享的凭据清除 + `DSH_*`/`CollectedOutput` 词汇 |
+| [`subprocess-local`](subprocess-local/README.md)（`@deepseek-ai/dsh-subprocess-local`） | 无 | 本地实现：detached 进程树、按处置方式接线的流、附带有界私有 spill 文件的尾部保留截断、`DSH_*` 合并次序、带升级的进程树信号发送、dispose 阶梯，以及先终止再等待退出的 dispose |
 
 服务拥有跨消费方重载的进程存续期；消费方拥有一个进程的含义（一条 bash 命令、未来的非 shell 运行器）以及塑造它的每一项默认值。
diff --git a/packages/subprocess/subprocess-local/README.i18n.yaml b/packages/subprocess/subprocess-local/README.i18n.yaml
index 4dab94d5b8..2e8c1fdae4 100644
--- a/packages/subprocess/subprocess-local/README.i18n.yaml
+++ b/packages/subprocess/subprocess-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
-README.md: a18772055d33369f6feec1b1a0751bb299303e04
-README.zh.md: bc829d48e846055853753522287967cc9fd42ca6
+README.md: 08cc2ce7d92569222b99992d0f4c43551a2c9623
+README.zh.md: da230ba37d406a6ad4ec669ceead45f2c2dd7069
diff --git a/packages/subprocess/subprocess-local/README.zh.md b/packages/subprocess/subprocess-local/README.zh.md
index bc829d48e8..da230ba37d 100644
--- a/packages/subprocess/subprocess-local/README.zh.md
+++ b/packages/subprocess/subprocess-local/README.zh.md
@@ -2,15 +2,15 @@
 
 [English](README.md) | 中文
 
-[`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam 的本地实现：`LocalSubprocessService` 把每个 spec 的 argv 作为 detached 进程组 spawn，收集有界输出，并用限制大小的完整流 spill 文件保留超量内容，随后针对整个进程组从 SIGTERM 逐步升级为 SIGKILL。该实现没有任何配置：每项限制与目录都随 spawn spec 到达，因此随部署变化的旋钮留在调用方 seam 的配置里（目前是 [`dsh-bash-local`](../../bash/bash-local/README.md)）。
+[`@deepseek-ai/dsh-subprocess`](../subprocess/README.md) seam 的本地实现：`LocalSubprocessService` 把每个 spec 的 argv 作为 detached 进程树 spawn，依照 spec 中按流划分的 stdio 处置方式（disposition）完成接线（原始管道、inherit、附带可选 spill 文件的有界尾部保留收集），并以进程树为范围、按 SIGTERM→SIGKILL 升级发送信号。该实现没有任何配置：每项处置方式、限制与目录都随 spawn spec 到达，因此随部署变化的旋钮留在各调用方 seam 的配置里（[`dsh-bash-local`](../../bash/bash-local/README.md)、[`dsh-lsp-local`](../../lsp/lsp-local/README.md)、[`dsh-subagent-acp`](../../subagent/subagent-acp/README.md)）。
 
 ## 行为（以及设计来源）
 
-- **带升级的 detached 进程组**：子进程使用 `detached` spawn（拥有独立进程组）；终止时先向该组发送 SIGTERM，经过 spec 的宽限期后再发送 SIGKILL（沿用 OpenCode 的升级策略；管道与子 shell 会随父进程一起结束）。组长进程退出后，继承的 stdout/stderr 管道也只获得同样有界的排空宽限期，因此存活的后代进程无法无限期地阻止这次 spawn 结束。系统会容忍 ESRCH；脱离该组重新挂载的 daemon 仍可能存活，这与调研工具的局限相同。
-- **尾部保留截断 + 有界 spill 文件**：输出超过某条流的上限后，内存中保留尾部（错误与结果通常聚集在末尾，沿用 pi/OpenCode 的理由），同时将完整流追加到一个私有临时文件，并在可用时报告该路径。某条流大于 spill 上限时，会丢弃已不完整的 spill，仅返回带截断标记的尾部；最终关闭失败时则不公布路径，以免声称存在不完整的文件。spill 文件权限为 `0600`、名称随机，位于按需延迟创建的 `0700` 每进程目录之下。
+- **带平台正确信号发送的 detached 进程树**：POSIX 子进程使用 `detached` spawn（拥有独立进程组），信号以负 pgid 发送并以直接子进程作为回退；Windows 通过 `taskkill /PID <pid> /T /F` 终止进程树（可为测试注入）。`terminate()` 先发送 SIGTERM，经过 spec 的宽限期后再发送 SIGKILL（沿用 OpenCode 的升级策略；管道与子 shell 会随父进程一起结束）；`kill(signal)` 恰好发送一个信号，结算后为空操作；`dispose(graces)` 以调用方提供的时间窗运行 stdin EOF→SIGTERM→SIGKILL 阶梯，dispose（资源释放）按句柄 memoize 化、只执行一次。组长进程退出后，仍然打开的管道也只获得同样有界的排空宽限期，因此存活的后代进程无法无限期地拖住结果不结算。系统会容忍 ESRCH；脱离该组重新挂载的 daemon 仍可能存活，这与调研工具的局限相同。
+- **按流划分的处置方式**：`'pipe'` 把原始流原样交给调用方（协议分帧仍归消费方所有）；`'inherit'` 直通父进程的描述符；收集模式（collect）在输出超过上限后于内存中保留尾部（错误与结果通常聚集在末尾，沿用 pi/OpenCode 的理由），并在配置了 spill 上限时把完整流追加到一个私有临时文件；省略 `spill` 则只保留尾部，即诊断尾部的形状。某条流大于 spill 上限时，会丢弃已不完整的 spill，仅返回带截断标记的尾部；spill 文件描述符在结算时封存，最终关闭失败时则不公布路径，以免声称存在不完整的文件。spill 文件权限为 `0600`、名称随机，位于按需延迟创建的 `0700` 每进程目录之下。
 - **凭据清除 + 受管 `DSH_*` 合并**：以 `process.env` 为基础，移除形似凭据的变量（`*KEY*`／`*SECRET*`／`*TOKEN*`）和所有环境中已有的 `DSH_*` 名称；spec 的普通 `env` 在清除后合并，但会拒绝 `DSH_*`；受管 `dshEnv` 会拒绝普通名称并最后合并，防止陈旧的嵌套 harness 身份。提供的 stdin 会被写入后关闭；否则 fd 0 指向 `/dev/null`。参见 [stdin/env Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md)与[受管环境 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md)。
-- **基于偏移量的读取**：`SubprocessHandle` 的读取器以全流字节坐标返回增量；服务自身从不持有游标，因此消费方自有的游标（bash 的后台读取路径）与完整流重读可以共存。
-- **先终止再等待退出的 dispose（资源释放）**：服务保留存活句柄，只为让自身的 dispose 能终止每个仍在运行的进程组并等待其退出；已结算与 spawn 失败的句柄在结算时即离开存活集合。
+- **基于偏移量的读取**：收集模式的读取器以全流字节坐标返回增量；服务自身从不持有游标，因此消费方自有的游标（bash 的后台读取路径）与完整流重读可以共存，结算前后皆然。
+- **先终止再等待退出的 dispose**：服务保留存活句柄，只为让自身的 dispose 能对每个仍在运行的进程树执行升级并等待其退出；已结算与 spawn 失败的句柄在结算时即离开存活集合。
 
 ## 模型体验
 
@@ -22,7 +22,7 @@
 
 ## 已知限制与暂缓事项
 
-- **仅支持 POSIX**：detached 进程组、进程组终止以及 SIGTERM→SIGKILL 升级都已硬编码；不支持 Windows。
+- **Windows 进程树支持仅为尽力而为，且未经 CI 测试**：终止经由 `taskkill /PID <pid> /T /F` 完成，所有结果都被就地吸收，不向外抛出（进程树已不存在、竞态、二进制缺失），存活探测则回退到直接子进程边界；测试套件只通过注入的运行器覆盖这条路由，且 `packages/subprocess/*` 被排除在 Windows 测试矩阵之外。
 - **凭据清除依赖名称启发式规则**：只匹配 `*KEY*`／`*SECRET*`／`*TOKEN*`；名称不同的 secret（例如 `*PASSWORD*`）会继续传递，对误删变量引入白名单属于已记录的后续工作。
 - **不会删除已完成的 spill 文件**：有界的完整输出恢复文件（以及每个进程的私有 spill 目录）会在 OS tmpdir 下累积，直到外部机制进行清理；超大的不完整 spill 会被丢弃并立即尝试删除，但清理失败可能留下一个有界文件。
 
diff --git a/packages/subprocess/subprocess/README.i18n.yaml b/packages/subprocess/subprocess/README.i18n.yaml
index adc9ed8cc4..818069e978 100644
--- a/packages/subprocess/subprocess/README.i18n.yaml
+++ b/packages/subprocess/subprocess/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
-README.md: 126f0fd6863739563b8d3cb5b4b958cee47dfb3d
-README.zh.md: fdd5035867316349a91d1700cbf3f521a2bac117
+README.md: 73e0a4abe49e8d3060f246218694faee127668e9
+README.zh.md: c38a1dd7c15e7d1c0f3139f8942911a4cd9f23fe
diff --git a/packages/subprocess/subprocess/README.zh.md b/packages/subprocess/subprocess/README.zh.md
index fdd5035867..c38a1dd7c1 100644
--- a/packages/subprocess/subprocess/README.zh.md
+++ b/packages/subprocess/subprocess/README.zh.md
@@ -6,13 +6,14 @@
 
 ## 契约
 
-- `spawn(spec)` 立即返回一个实时句柄；`done` 在进程关闭时 resolve，仅在 spawn 层面失败时 reject。
-- spec 完全显式（argv、cwd、按流划分的字节上限、spill 上限、宽限期），因为随部署变化的默认值属于调用方 seam 的配置，而不属于某个隐藏的进程管理器默认值（`dsh-bash` 的 request/spec 拆分是这条规则的所属模板）。`argv` 在这里绝不经过 shell 解释；需要 shell 的消费方自行传入 `['bash', '-c', command]`。
-- 输出读取器接受全流字节偏移量且从不消费：独立的读取器不会抢走彼此的增量。偏移量滑出内存尾部窗口的读取标记为 `lossy`，并在完整流 spill 文件存在时指向它。
-- `kill()` 与 spec 的 abort 信号对整个 detached 进程组执行 SIGTERM→宽限期→SIGKILL 升级；服务响应中止但绝不判定原因（deadline 与原因分类归调用方所有）。
-- dispose（资源释放）会终止所有仍在运行的受管进程并等待其退出。
+- `spawn(spec)` 立即返回一个实时句柄；`done` 在进程关闭时以退出事实 resolve（`SubprocessOutcome` 不携带输出，也不携带原因分类），仅在 spawn 层面失败时 reject。
+- spec 完全显式（argv、cwd、按流划分的 stdio 处置方式（disposition）、宽限期），因为随部署变化的默认值属于调用方 seam 的配置，而不属于某个隐藏的进程管理器默认值（`dsh-bash` 的 request/spec 拆分是这条规则的所属模板）。`argv` 绝不经过 shell 解释；需要 shell 的消费方自行传入 `['bash', '-c', command]`。
+- stdio 按流采用 Node 形状：`'pipe'` 把原始流交给调用方做自己的协议分帧（LSP 的 JSON-RPC、ACP（Agent Client Protocol）的 ndjson），`'inherit'` 直通父进程描述符以承载诊断输出，收集模式（collect）`{ maxBytes, spill? }` 则缓冲一段有界尾部，外加可选的完整流 spill 文件。收集模式的读取器接受全流字节偏移量且从不消费，因此独立的读取器不会抢走彼此的增量；偏移量滑出内存尾部窗口的读取标记为 `lossy`，并在 spill 文件存在时指向它。收集到的输出在结算后仍可读取。
+- 终止在每个平台上都以进程树为范围（POSIX 用 detached 进程组并以直接子进程回退；Windows 用 `taskkill /T`）：`kill(signal)` 以 Node 风格只发送一个信号，结算后为空操作；`terminate()`（以及 spec 的 abort 信号）执行 SIGTERM→宽限期→SIGKILL 升级；`waitForExit()` 观察整棵进程树；`dispose(graces)` 运行进程外子进程所需的协作式 stdin EOF→SIGTERM→SIGKILL 阶梯。管理器只响应中止，但绝不判定原因（deadline 与原因分类归调用方所有）。
+- `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` 是唯一一份共享的凭据清除定义：环境中形似凭据的名称与 `DSH_*` 名称都会被丢弃，显式 `env` 在清除之后合并（有意转发的键会保留下来），`dshEnv` 则经由自身带校验的通道携带当前 harness 事实。无法把 spawn 路由到该服务的调用点（node-pty 后端、由 SDK 管理的传输层）改为导入该函数。
+- 服务自身的 dispose（资源释放）会终止所有仍在运行的受管进程并等待其退出。
 
-参见[进程数据结构目录](../../../docs/core-data-structures/subprocess.md)与 [seam Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
+参见[进程管理器数据结构目录](../../../docs/core-data-structures/subprocess.md)与 [seam Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
 
 ## 模型体验
 
@@ -24,5 +25,5 @@
 
 ## 已知限制与暂缓事项
 
-- **目前只有一个消费方家族**：该 seam 的形状仅在 bash 执行器上得到验证；仓库内其他 spawn 调用点（LSP 服务器、PTY 后端、subagent 传输层）继续保留各自专属的进程处理，直到它们的流与生命周期需求对照本契约得到重新审视。
-- **假定 POSIX 进程组语义**：句柄词汇（作为组长的 `pid`、进程组终止、SIGTERM/SIGKILL 升级）没有 Windows 方案。
+- **node-pty 与由 SDK 管理的 spawn 只共享凭据清除**：PTY 后端的终端 fork 与 MCP SDK 自己的 stdio 传输层无法把 spawn 路由到这道 seam（fork/spawn 调用归库所有）；它们改为导入 `scrubbedParentEnv`，使环境策略保持单一来源。
+- **dispose 阶梯假定子进程配合 stdin EOF**：依赖其他信号（SIGHUP 惯例、控制 socket）才能完全停稳的子进程，需要自己的第一阶，通用阶梯才适用。