feat(subprocess): migrate lsp-local, subagent-acp, and the env scrubs onto the seam

Review direction (tianyicui, PR #660): in a stacked PR, change all other
process-running places to use the new service.

- lsp-local: LspConnection spawns through ctx.subprocess (piped protocol
  streams + a no-spill collected stderr tail); its private process-tree
  helpers (POSIX group signalling, Windows taskkill, liveness polling) are
  deleted in favor of the seam's handle verbs, and its buildChildEnv now
  rides scrubbedParentEnv (LSP children also stop inheriting stale DSH_*).
  The plugin injects 'subprocess'; compositions/tests mount
  dsh-subprocess-local.
- subagent-acp: the ACP child spawns through the seam (piped ndjson streams,
  inherited stderr); spawn failure surfaces through done-rejection into the
  same startup race; disposal is handle.dispose with the plugin's configured
  graces. dsh-subagent-subprocess is DELETED — its dispose ladder and scrub
  are the seam's, and the isolated-config-dir helper had no consumer.
- mcp-client, pty-local, sdk-helper: adopt scrubbedParentEnv as the one
  scrub definition (their spawns stay put by ownership: the MCP SDK and
  node-pty own those calls; the SDK wizard runs outside any composition).
- Coverage: per-file 100% over every touched src file, with each v8 ignore
  carrying a platform or contract reason; new suites cover stdio
  dispositions, the dispose ladder tiers, injected-win32 tree semantics,
  waitForExit, settled-kill/terminate no-ops, and spawn-failure disposal.
- Docs: consumer-migration Agent Note (en; zh follows in this PR), seam note
  updated in place, subprocess.md rewritten for the reshaped vocabulary
  (type-equiv re-registered), READMEs and SERVICE_ROLES updated, taskkill
  added to knip ignoreBinaries.

packages/subagent/subagent-acp/src/index.ts

@@ -15,7 +15,7 @@ import type { SubagentCapabilities, SubagentProvider, SubagentStartRequest } fro
 import { type AcpRunSpec, DEFAULT_DISPOSE_EOF_GRACE_MS, DEFAULT_DISPOSE_GRACE_MS, type PermissionPolicy, startAcpRun } from './run.ts'
 
 export const name = 'subagent-acp'
-export const inject = ['subagents']
+export const inject = ['subagents', 'subprocess']
 
 /** Config: how to spawn and drive the child ACP agent process. */
 export interface Config {
@@ -152,6 +152,7 @@ class AcpProvider implements SubagentProvider {
       env: this.config.env,
       disposeEofGraceMs: this.config.disposeEofGraceMs,
       disposeGraceMs: this.config.disposeGraceMs,
+      spawn: spec => this.ctx.subprocess.spawn(spec),
       onError: (error, stopReason) => {
         // The seam forbids `result` rejecting, so a child-level failure is
         // flattened to a stop reason — preserve it here rather than losing it.

packages/subagent/subagent-acp/src/run.ts

@@ -8,9 +8,8 @@
  * @module @deepseek-ai/dsh-subagent-acp/run
  */
 
-import { spawn } from 'node:child_process'
 import { randomUUID } from 'node:crypto'
-import { Readable, Writable } from 'node:stream'
+import { Readable as NodeReadable, Writable as NodeWritable } from 'node:stream'
 import {
   ClientSideConnection,
   ndJsonStream,
@@ -26,7 +25,7 @@ import {
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import type { SubagentResult, SubagentRun, SubagentStartRequest, SubagentStopReason } from '@deepseek-ai/dsh-subagent'
-import { buildChildEnv, disposeChildProcess, spawnFailure } from '@deepseek-ai/dsh-subagent-subprocess'
+import type { SubprocessHandle, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess'
 
 /** Fixed response to child permission requests: reject by default, or select the first allow option. */
 export type PermissionPolicy = 'allow' | 'reject'
@@ -47,9 +46,9 @@ export interface AcpRunSpec {
   permission: PermissionPolicy
   /**
    * Extra environment variables to ADD for the child (e.g. the child harness's
-   * `DEEPSEEK_API_KEY`). Merged on top of the scrubbed ambient env — see
-   * {@link buildChildEnv}. A value here is forwarded even if its name matches
-   * the credential-scrub pattern (an explicit opt-in for the child's own creds).
+   * `DEEPSEEK_API_KEY`). Merged on top of the subprocess seam's scrubbed
+   * parent env. A value here is forwarded even if its name matches the
+   * credential-scrub pattern (an explicit opt-in for the child's own creds).
    */
   env: Record<string, string>
   /**
@@ -65,6 +64,12 @@ export interface AcpRunSpec {
    * fills this from its `disposeGraceMs` config.
    */
   disposeGraceMs: number
+  /**
+   * Spawn function from the subprocess seam (`ctx.subprocess.spawn`), so the
+   * child rides the shared scrub, tree-scoped teardown, and service-owned
+   * lifetime instead of a package-local child_process path.
+   */
+  spawn: (spec: SubprocessSpawnSpec) => SubprocessHandle
   /**
    * Sink for a child-level failure that the run flattened into a stop reason
    * (the seam contract forbids `result` rejecting). The driver calls this with
@@ -159,20 +164,33 @@ export async function startAcpRun(request: SubagentStartRequest, spec: AcpRunSpe
   // each other or with a local agent that happens to use the same session id.
   const id = SessionId(randomUUID())
 
-  // Keep diagnostics on parent stderr; only ACP output contributes to the result.
-  const child = spawn(spec.command, spec.args, {
+  // Keep diagnostics on parent stderr ('inherit'); only ACP output contributes
+  // to the result. The seam's scrub drops ambient credentials while spec.env
+  // (the child's own key) merges after it.
+  const child = spec.spawn({
+    argv: [spec.command, ...spec.args],
     cwd: spec.cwd,
-    env: buildChildEnv(spec.env),
-    stdio: ['pipe', 'pipe', 'inherit'],
+    stdio: { stdin: 'pipe', stdout: 'pipe', stderr: 'inherit' },
+    graceMs: spec.disposeGraceMs,
+    env: spec.env,
   })
-  // Capture the child-process error event immediately.
-  const spawnFailed = spawnFailure(child)
+  /* v8 ignore start -- 'pipe' dispositions expose both streams by the seam contract; defensive. */
+  if (child.stdin === undefined || child.stdout === undefined) {
+    throw new Error('subagent-acp: subprocess implementation dropped a piped protocol stream')
+  }
+  /* v8 ignore stop */
+  // Spawn-level failure surfaces as `done` rejecting into the startup race; a
+  // clean exit must never win it, so the success arm parks forever.
+  /* v8 ignore start -- the success arm's never-settling executor is intentionally empty. */
+  const spawnFailed: Promise<never> = child.done.then(() => new Promise<never>(() => {}), (err: unknown) => Promise.reject(toError(err)))
+  /* v8 ignore stop */
+  spawnFailed.catch(() => { /* observed by the startup race; never unhandled */ })
 
   // Startup rollback and the published handle share one process teardown.
   let processDisposal: Promise<void> | undefined
-  const disposeProcess = (): Promise<void> => (processDisposal ??= disposeChildProcess(child, {
-    disposeEofGraceMs: spec.disposeEofGraceMs,
-    disposeGraceMs: spec.disposeGraceMs,
+  const disposeProcess = (): Promise<void> => (processDisposal ??= child.dispose({
+    eofGraceMs: spec.disposeEofGraceMs,
+    graceMs: spec.disposeGraceMs,
   }))
 
   // Accumulate the child's streamed assistant text — the SubagentResult output.
@@ -207,8 +225,8 @@ export async function startAcpRun(request: SubagentStartRequest, spec: AcpRunSpe
   const conn = new ClientSideConnection(
     makeClient,
     ndJsonStream(
-      Writable.toWeb(child.stdin) as WritableStream<Uint8Array>,
-      Readable.toWeb(child.stdout) as ReadableStream<Uint8Array>,
+      NodeWritable.toWeb(child.stdin) as WritableStream<Uint8Array>,
+      NodeReadable.toWeb(child.stdout) as ReadableStream<Uint8Array>,
     ),
   )
 
@@ -252,7 +270,7 @@ export async function startAcpRun(request: SubagentStartRequest, spec: AcpRunSpe
         sessionId = returnedSessionId
         if (flags.cancelled) throw new Error('subagent cancelled before the ACP session started')
       })(),
-      spawnFailed.then((err): never => { throw err }),
+      spawnFailed,
       cancelSettled.then((): never => { throw new Error('subagent cancelled before the ACP session started') }),
     ])
   } catch (error: unknown) {