Merge remote-tracking branch 'origin/worktree-process-service-seam' into subprocess-simpl/d-one-env-channel

# Conflicts: # docs/cordis-catalog/services.md # docs/core-data-structures/subprocess.i18n.yaml # packages/lsp/lsp-local/src/connection.ts # packages/subagent/subagent-acp/README.i18n.yaml # packages/subprocess/subprocess-local/README.i18n.yaml # packages/subprocess/subprocess-local/src/spawn.ts # packages/subprocess/subprocess/README.i18n.yaml # packages/subprocess/subprocess/README.md # packages/subprocess/subprocess/README.zh.md # packages/subprocess/subprocess/tests/service.spec.ts
2026-08-15 21:04:50 +00:00 · 2026-07-27 11:31:38 +08:00
parent 5717726835 69171f7d85
commit eaa9ced271
40 changed files with 288 additions and 428 deletions
--- 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: db4ab49ea953bfcf9ae59ede3187795eb71f0268
-subprocess.zh.md: 3f0a6c798056865ead1352f87328fb9dad6d5c0f
+subprocess.md: 922e7ad0ee8b5c0dbcd0a6a4553c9d2a580f3ee2
+subprocess.zh.md: 5befdcdfc9b0e1d2a9adc825b177c90e53269def
--- a/docs/core-data-structures/subprocess.md
+++ b/docs/core-data-structures/subprocess.md
@@ -127,7 +127,7 @@ interface SubprocessSpawnSpec {

 ## Handles: streams, readers, and tree-scoped termination

-A spawn returns a live handle immediately. Collect-mode readers take whole-stream byte offsets and never consume, so independent readers cannot steal one another's deltas; piped streams belong to the caller. Termination is tree-scoped on every platform: `kill(signal)` sends one signal Node-style, `terminate()` escalates SIGTERM→grace→SIGKILL, `waitForExit()` observes the whole tree, and `dispose(graces)` runs the cooperative stdin-EOF→SIGTERM→SIGKILL ladder out-of-process children need.
+A spawn returns a live handle immediately. Collect-mode readers take whole-stream byte offsets and never consume, so independent readers cannot steal one another's deltas; piped streams belong to the caller. Termination is tree-scoped on every platform: `terminate()` — the only termination verb — escalates SIGTERM→grace→SIGKILL, and `waitForExit()` observes the whole tree — enough for a consumer to build its own teardown ladder (the ACP backend's stdin-EOF-first `disposeAcpChild` is the template).

 ```ts type-equiv
 /**
@@ -152,17 +152,11 @@ interface SubprocessHandle {
  readonly collected: SubprocessCollectedOutputs
  /** Resolves at process close with exit facts; rejects only for spawn-level failures. */
  readonly done: Promise<SubprocessOutcome>
-  /**
-   * 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.
+   * (Windows force-terminates immediately) — the seam's only termination
+   * verb. Idempotent, a no-op once the tree is gone (the pid may be reused),
+   * and also triggered by the spec's abort signal.
   */
  terminate(): void
  /**
@@ -172,15 +166,6 @@ interface SubprocessHandle {
   * @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>
 }
 ```

@@ -228,31 +213,6 @@ interface SubprocessCollectedOutputs {
 }
 ```

-```ts type-equiv
-/**
- * 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
-}
-```

 ## Outcomes carry exit facts only

--- a/docs/core-data-structures/subprocess.zh.md
+++ b/docs/core-data-structures/subprocess.zh.md
@@ -127,7 +127,7 @@ interface SubprocessSpawnSpec {

 ## 句柄：流、读取器与以进程树为范围的终止

-spawn 会立即返回一个实时句柄。收集模式的读取器接受全流字节偏移量且从不消费，因此独立的读取器不会抢走彼此的增量；管道化的流归调用方所有。终止在每个平台上都以进程树为范围：`kill(signal)` 以 Node 风格只发送一个信号，`terminate()` 执行 SIGTERM→宽限期→SIGKILL 升级，`waitForExit()` 观察整棵进程树，`dispose(graces)` 运行进程外子进程所需的协作式 stdin EOF→SIGTERM→SIGKILL 阶梯。
+spawn 会立即返回一个实时句柄。收集模式的读取器接受全流字节偏移量且从不消费，因此独立的读取器不会抢走彼此的增量；管道化的流归调用方所有。终止在每个平台上都以进程树为范围：`terminate()`（唯一的终止动词）执行 SIGTERM→宽限期→SIGKILL 升级，`waitForExit()` 观察整棵进程树——这足以让消费方构建自己的拆卸阶梯（ACP 后端以 stdin EOF 打头的 `disposeAcpChild` 即是模板）。

 ```ts type-equiv
 /**
@@ -152,17 +152,11 @@ interface SubprocessHandle {
  readonly collected: SubprocessCollectedOutputs
  /** Resolves at process close with exit facts; rejects only for spawn-level failures. */
  readonly done: Promise<SubprocessOutcome>
-  /**
-   * 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.
+   * (Windows force-terminates immediately) — the seam's only termination
+   * verb. Idempotent, a no-op once the tree is gone (the pid may be reused),
+   * and also triggered by the spec's abort signal.
   */
  terminate(): void
  /**
@@ -172,15 +166,6 @@ interface SubprocessHandle {
   * @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>
 }
 ```

@@ -228,31 +213,6 @@ interface SubprocessCollectedOutputs {
 }
 ```

-```ts type-equiv
-/**
- * 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
-}
-```

 ## 结果只承载退出事实