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.
2026-07-26 15:27:59 +08:00
parent fd7e6d4d11
commit 3672cd25b4
57 changed files with 750 additions and 1225 deletions
--- a/packages/subagent/subagent-acp/README.md
+++ b/packages/subagent/subagent-acp/README.md
@@ -55,7 +55,7 @@ ACP advertises no start-time capabilities because this process cannot enforce th

 ## Process boundary

-The child environment is built by [`buildChildEnv`](../subagent-subprocess/README.md): credential-shaped ambient variables are removed, then explicit `config.env` values are applied. The ACP wire is the real serialization boundary; same-process subagent values are not defensively cloned.
+The child spawns through the [`dsh-subprocess`](../../subprocess/subprocess/README.md) seam: credential-shaped ambient variables are removed by the shared scrub, then explicit `config.env` values merge after it (an intended `DEEPSEEK_API_KEY` survives), stderr is inherited to the parent's own stream, and disposal runs the seam's cooperative stdin-EOF→SIGTERM→SIGKILL ladder with this plugin's configured graces. The ACP wire is the real serialization boundary; same-process subagent values are not defensively cloned.

 The package has no default export. Cordis loader unwrapping would otherwise hide the named `inject` metadata; see [postmortem 0001](../../../docs/postmortem/0001-acp-default-export-drops-inject.md).

--- a/packages/subagent/subagent-acp/package.json
+++ b/packages/subagent/subagent-acp/package.json
@@ -32,7 +32,7 @@
    "@deepseek-ai/dsh-llm": "^0.0.1",
    "@deepseek-ai/dsh-session": "^0.0.1",
    "@deepseek-ai/dsh-subagent": "^0.0.1",
-    "@deepseek-ai/dsh-subagent-subprocess": "^0.0.1",
+    "@deepseek-ai/dsh-subprocess": "^0.0.1",
    "cordis": "^4.0.0-rc.7"
  },
  "dependencies": {
@@ -47,7 +47,8 @@
    "@deepseek-ai/dsh-loader-smoke": "workspace:^",
    "@deepseek-ai/dsh-session": "workspace:^",
    "@deepseek-ai/dsh-subagent": "workspace:^",
-    "@deepseek-ai/dsh-subagent-subprocess": "workspace:^",
+    "@deepseek-ai/dsh-subprocess": "workspace:^",
+    "@deepseek-ai/dsh-subprocess-local": "workspace:^",
    "cordis": "^4.0.0-rc.7"
  }
 }
--- a/packages/subagent/subagent-acp/src/index.ts
+++ b/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.
--- a/packages/subagent/subagent-acp/src/run.ts
+++ b/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) {
--- a/packages/subagent/subagent-acp/tests/subagent-acp.e2e.ts
+++ b/packages/subagent/subagent-acp/tests/subagent-acp.e2e.ts
@@ -21,7 +21,7 @@ const exampleConfig = fileURLToPath(new URL('../../../../examples/acp-agent/cord
 const repoTsconfig = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url))

 // How to launch the child acp-agent (src via tsx / lib via plain node, per DSH_EXAMPLE_MODE).
-// buildChildEnv scrubs ambient creds but keeps these extras, so the model key is
+// The subprocess seam scrubs ambient creds while spec.env merges after it, so the model key is
 // forwarded explicitly; TSX_TSCONFIG_PATH is added by the resolver in src mode only.
 const childLaunch = resolveExampleLaunch({
  srcBin: binScript,
--- a/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts
+++ b/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts
@@ -6,10 +6,11 @@ import { tmpdir } from 'node:os'
 import { join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import SubagentService from '@deepseek-ai/dsh-subagent'
-import { buildChildEnv } from '@deepseek-ai/dsh-subagent-subprocess'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import * as acp from '../src/index.ts'
 import { acpStopReason, acpContentText, DEFAULT_DISPOSE_EOF_GRACE_MS, DEFAULT_DISPOSE_GRACE_MS, startAcpRun, toAcpPrompt, type AcpRunSpec } from '../src/run.ts'
+import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
+import { spawnSubprocess } from '@deepseek-ai/dsh-subprocess-local/src/spawn.ts'

 /**
 * Keyless integration tests for the ACP subagent backend. Each spawns a REAL
@@ -41,6 +42,7 @@ interface SetupEnv {
 async function setup(mockEnv: SetupEnv = {}, permission: 'allow' | 'reject' = 'reject') {
  const ctx = new Context()
  await ctx.plugin(SubagentService)
+  await ctx.plugin(LocalSubprocessService)
  await ctx.plugin(acp, {
    providerName: 'acp',
    command: process.execPath,
@@ -98,19 +100,23 @@ describe('acpContentText / toAcpPrompt', () => {
  })
 })

-describe('buildChildEnv', () => {
-  it('drops credential-shaped ambient vars but keeps the explicit extras', () => {
-    process.env.DSH_ACP_TEST_SECRET_TOKEN = 'leak-me'
+describe('child env layering (through the subprocess seam)', () => {
+  it('drops credential-shaped ambient vars but keeps the explicit extras', async () => {
+    process.env.ACP_TEST_AMBIENT_SECRET_TOKEN = 'leak-me'
    try {
-      const env = buildChildEnv({ DEEPSEEK_API_KEY: 'explicit' })
-      // The credential-shaped ambient var is scrubbed.
-      expect(env.DSH_ACP_TEST_SECRET_TOKEN).toBeUndefined()
-      // The explicitly-supplied key survives (an opt-in for the child's creds).
-      expect(env.DEEPSEEK_API_KEY).toBe('explicit')
-      // A normal ambient var is forwarded.
-      expect(env.PATH).toBe(process.env.PATH)
+      // The spec.env layer merges after the seam's scrub, so the child's own
+      // explicitly-forwarded key survives while ambient credentials do not.
+      const running = spawnSubprocess({
+        argv: ['bash', '-c', 'echo "[${ACP_TEST_AMBIENT_SECRET_TOKEN:-absent}|$DEEPSEEK_API_KEY]"'],
+        cwd: process.cwd(),
+        stdio: { stdin: 'ignore', stdout: { maxBytes: 1000 }, stderr: { maxBytes: 1000 } },
+        graceMs: 1000,
+        env: { DEEPSEEK_API_KEY: 'explicit' },
+      })
+      await running.done
+      expect(running.collected.stdout!.readFrom(0).text.trim()).toBe('[absent|explicit]')
    } finally {
-      delete process.env.DSH_ACP_TEST_SECRET_TOKEN
+      delete process.env.ACP_TEST_AMBIENT_SECRET_TOKEN
    }
  })
 })
@@ -140,6 +146,7 @@ describe('cwd resolution', () => {
    try {
      const ctx = new Context()
      await ctx.plugin(SubagentService)
+      await ctx.plugin(LocalSubprocessService)
      // A command that would create the sentinel if the child were ever spawned.
      await ctx.plugin(acp, { providerName: 'acp', command: 'touch', args: [sentinel], permission: 'reject', env: {} })
      const parent = { id: 'parent', session: { header: {} } } as unknown as Agent
@@ -158,6 +165,7 @@ describe('cwd resolution', () => {
    try {
      const ctx = new Context()
      await ctx.plugin(SubagentService)
+      await ctx.plugin(LocalSubprocessService)
      await ctx.plugin(acp, {
        providerName: 'acp',
        command: process.execPath,
@@ -185,6 +193,7 @@ describe('cwd resolution', () => {
    const absolute = resolve(relative)
    const ctx = new Context()
    await ctx.plugin(SubagentService)
+    await ctx.plugin(LocalSubprocessService)
    await ctx.plugin(acp, {
      providerName: 'acp',
      command: process.execPath,
@@ -204,6 +213,7 @@ describe('cwd resolution', () => {
    // reintroduce the launch-directory fallback this resolution removed.
    const ctx = new Context()
    await ctx.plugin(SubagentService)
+    await ctx.plugin(LocalSubprocessService)
    await expect(ctx.plugin(acp, {
      providerName: 'acp',
      command: 'true',
@@ -224,6 +234,7 @@ describe('cwd resolution', () => {
    try {
      const ctx = new Context()
      await ctx.plugin(SubagentService)
+      await ctx.plugin(LocalSubprocessService)
      await expect(ctx.plugin(acp, {
        providerName: 'acp',
        command: 'true',
@@ -242,6 +253,7 @@ describe('cwd resolution', () => {
  it('rejects a config cwd that is not an accessible directory at load', async () => {
    const ctx = new Context()
    await ctx.plugin(SubagentService)
+    await ctx.plugin(LocalSubprocessService)
    await expect(ctx.plugin(acp, {
      providerName: 'acp',
      command: 'true',
@@ -283,6 +295,7 @@ describe('cwd resolution', () => {
    try {
      const ctx = new Context()
      await ctx.plugin(SubagentService)
+      await ctx.plugin(LocalSubprocessService)
      await ctx.plugin(acp, { providerName: 'acp', command: 'touch', args: [sentinel], permission: 'reject', env: {} })
      const parent = { id: 'parent', session: { header: { cwd: join(tmp, 'vanished') } } } as unknown as Agent
      await expect(ctx.subagents.start('acp', { prompt: [{ type: 'text' as const, text: 'p' }], parent, signal: new AbortController().signal }))
@@ -360,7 +373,7 @@ describe('dsh-subagent-acp', () => {
      await expect(startAcpRun(
        request('p', controller.signal),
        // `touch <sentinel>` — runs only if the process is actually spawned.
-        { command: 'touch', args: [sentinel], cwd: tmp, permission: 'reject', env: {}, disposeEofGraceMs: DEFAULT_DISPOSE_EOF_GRACE_MS, disposeGraceMs: DEFAULT_DISPOSE_GRACE_MS },
+        { command: 'touch', args: [sentinel], cwd: tmp, permission: 'reject', env: {}, disposeEofGraceMs: DEFAULT_DISPOSE_EOF_GRACE_MS, disposeGraceMs: DEFAULT_DISPOSE_GRACE_MS, spawn: spawnSubprocess },
      )).rejects.toThrow('aborted before the ACP child started')
      // The binary was never launched — no sentinel.
      expect(existsSync(sentinel)).toBe(false)
@@ -385,6 +398,7 @@ describe('dsh-subagent-acp', () => {
        },
        disposeEofGraceMs: 1000,
        disposeGraceMs: 100,
+        spawn: spawnSubprocess,
      })).rejects.toThrow('ACP child published without a session id')
      // Startup rejects only after its private child reaches quiescence. The
      // marker proves rollback closed stdin and allowed the child's EOF flush.
@@ -412,6 +426,7 @@ describe('dsh-subagent-acp', () => {
        // small so the whole ladder finishes well within the 4000ms bound.
        disposeEofGraceMs: 150,
        disposeGraceMs: 150,
+        spawn: spawnSubprocess,
      }
      const run = await startAcpRun(request(), spec)
      // Wait until the child has BOOTED AND ARMED THE TRAP (a condition, not a
@@ -459,6 +474,7 @@ describe('dsh-subagent-acp', () => {
        },
        disposeEofGraceMs: 2000,
        disposeGraceMs: 50,
+        spawn: spawnSubprocess,
      }
      const run = await startAcpRun(request(), spec)
      // Wait until the child is fully booted with its prompt in flight (its ACP
@@ -492,6 +508,7 @@ describe('dsh-subagent-acp', () => {
        // Tiny EOF grace so the ignored-EOF window elapses quickly.
        disposeEofGraceMs: 150,
        disposeGraceMs: 2000,
+        spawn: spawnSubprocess,
      }
      const run = await startAcpRun(request(), spec)
      await waitForFile(ready)
@@ -587,7 +604,7 @@ describe('dsh-subagent-acp', () => {
  it('rejects a spawn failure after provider-owned cleanup', async () => {
    await expect(startAcpRun(
      request(),
-      { command: '/nonexistent/acp-agent-binary', args: [], cwd: process.cwd(), permission: 'reject', env: {}, disposeEofGraceMs: DEFAULT_DISPOSE_EOF_GRACE_MS, disposeGraceMs: DEFAULT_DISPOSE_GRACE_MS },
+      { command: '/nonexistent/acp-agent-binary', args: [], cwd: process.cwd(), permission: 'reject', env: {}, disposeEofGraceMs: DEFAULT_DISPOSE_EOF_GRACE_MS, disposeGraceMs: DEFAULT_DISPOSE_GRACE_MS, spawn: spawnSubprocess },
    )).rejects.toThrow()
  })

@@ -601,6 +618,7 @@ describe('dsh-subagent-acp', () => {
    try {
      const ctx = new Context()
      await ctx.plugin(SubagentService)
+      await ctx.plugin(LocalSubprocessService)
      await ctx.plugin(acp, {
        providerName: 'acp',
        command: process.execPath,
@@ -626,6 +644,7 @@ describe('dsh-subagent-acp', () => {
    for (const bad of [{ disposeEofGraceMs: 0 }, { disposeGraceMs: -1 }, { disposeEofGraceMs: Number.NaN }]) {
      const ctx = new Context()
      await ctx.plugin(SubagentService)
+      await ctx.plugin(LocalSubprocessService)
      await expect(ctx.plugin(acp, { providerName: 'acp', command: 'true', args: [], permission: 'reject', env: {}, ...bad }))
        .rejects.toThrow(/subagent-acp: dispose(?:Eof)?GraceMs must be a positive finite number/)
      await ctx.fiber.dispose()
@@ -635,6 +654,7 @@ describe('dsh-subagent-acp', () => {
  it('rejects a startup failure via the provider load path', async () => {
    const ctx = new Context()
    await ctx.plugin(SubagentService)
+    await ctx.plugin(LocalSubprocessService)
    await ctx.plugin(acp, {
      providerName: 'acp',
      command: '/nonexistent/acp-agent-binary',
@@ -661,6 +681,7 @@ describe('dsh-subagent-acp', () => {
        env: { MOCK_CRASH_ON_PROMPT: '1' },
        disposeEofGraceMs: DEFAULT_DISPOSE_EOF_GRACE_MS,
        disposeGraceMs: DEFAULT_DISPOSE_GRACE_MS,
+        spawn: spawnSubprocess,
        onError: (error, stopReason) => { errors.push({ message: error.message, stopReason }) },
      },
    )
@@ -699,6 +720,7 @@ describe('dsh-subagent-acp', () => {
        env: { MOCK_CRASH_ON_PROMPT: '1' },
        disposeEofGraceMs: DEFAULT_DISPOSE_EOF_GRACE_MS,
        disposeGraceMs: DEFAULT_DISPOSE_GRACE_MS,
+        spawn: spawnSubprocess,
        onError: () => { throw new Error('sink boom') },
      },
    )
@@ -763,6 +785,7 @@ describe('dsh-subagent-acp', () => {
  it('unregisters the provider when its fiber is disposed (HMR safety)', async () => {
    const ctx = new Context()
    await ctx.plugin(SubagentService)
+    await ctx.plugin(LocalSubprocessService)
    const fiber = await ctx.plugin(acp, { providerName: 'acp', command: 'x', args: [], permission: 'reject', env: {} })
    expect(ctx.subagents.list()).toEqual(['acp'])
    await fiber.dispose()
@@ -772,7 +795,7 @@ describe('dsh-subagent-acp', () => {
  it('has the namespace-plugin export shape (no stray default)', () => {
    expect('default' in acp).toBe(false)
    expect(acp.name).toBe('subagent-acp')
-    expect(acp.inject).toEqual(['subagents'])
+    expect(acp.inject).toEqual(['subagents', 'subprocess'])
    const loader = Object.create(Loader.prototype) as Loader
    const unwrapped = loader.unwrapExports(acp) as Record<string, unknown>
    expect(unwrapped).toBe(acp)
--- a/packages/subagent/subagent-acp/tsconfig.json
+++ b/packages/subagent/subagent-acp/tsconfig.json
@@ -27,7 +27,7 @@
      "path": "../subagent"
    },
    {
-      "path": "../subagent-subprocess"
+      "path": "../../subprocess/subprocess"
    },
    {
      "path": "../../support/loader-smoke"