refactor(subprocess): keep terminate() as the seam's only termination verb

Delete kill(signal?) from SubprocessHandle: consumers stop a process only
through terminate()'s tree-scoped SIGTERM→graceMs→SIGKILL escalation
(idempotent, also driven by the spec's abort signal, a no-op once the tree
is gone). The single-signal verb had exactly one consumer family —
lsp-local — and what it bought there was a private re-implementation of
the same escalation. The internal kill closure stays in spawn.ts as the
dispose ladder's tier primitive; terminate() now routes through it too.

lsp-local collapses onto the seam's escalation:
- LspConnection replaces its terminate()/kill() pair with one terminate()
  that delegates to handle.terminate(). Behavior change: the
  framing-failure path terminates instead of instant SIGKILL, so a
  misbehaving server now gets SIGTERM plus the killGraceMs window to
  flush before SIGKILL.
- ConnectionSpec.pipeDrainGraceMs becomes killGraceMs: one grace, the
  spawn spec's graceMs, drives both the escalation window and post-exit
  pipe draining (the provider already passed killGraceMs for it).
- LspInstance.forceTerminate() drops its hand-rolled bounded first wait
  (LSP_KILL_GRACE) and escalateProcessTree (deleted with its export and
  unit test): the seam's escalation already commits to SIGKILL after
  killGraceMs, so only the unbounded quiescence awaits stay load-bearing.

Tests: kill()-shaped spawn specs become terminate()-shaped or fold into
the terminate() suites (group-wide delivery; the settled no-op case was
already pinned by 'terminate() after the tree died'); tree-survivor
coverage is intact. A stderr-'inherit' disposition test completes the
stdout/stderr symmetry so the scoped subprocess+lsp coverage gate stands
alone instead of leaning on subagent-acp's cross-package runs.

Docs: SubprocessHandle type-equiv block, seam/impl/group READMEs, and the
consumer-migration Agent Note lose the kill(signal?) vocabulary (zh pairs
re-recorded); cordis api/services catalogs regenerated.

packages/lsp/lsp-local/src/connection.ts

@@ -30,11 +30,11 @@ export interface ConnectionSpec {
   /** Largest stderr tail retained for diagnostics. */
   readonly maxStderrBytes: number
   /**
-   * Bound (ms) for draining pipes a surviving helper still holds after the
-   * server exits; the instance passes its kill grace so exit observation is
-   * never slower than the escalation it feeds.
+   * The subprocess spec's `graceMs`: the SIGTERM→SIGKILL window of
+   * {@link LspConnection.terminate}'s escalation, and the bound for draining
+   * pipes a surviving helper still holds after the server exits.
    */
-  readonly pipeDrainGraceMs: number
+  readonly killGraceMs: number
   /** Static answer to every `workspace/configuration` item. */
   readonly configuration: unknown
 }
@@ -98,7 +98,7 @@ export class LspConnection {
         stdout: 'pipe',
         stderr: { maxBytes: spec.maxStderrBytes },
       },
-      graceMs: spec.pipeDrainGraceMs,
+      graceMs: spec.killGraceMs,
       // spec.env mixes the scrubbed base with explicit config entries; a
       // configured DSH_* fact takes the managed channel the seam reserves.
       ...splitEnvChannels(spec.env),
@@ -210,14 +210,9 @@ export class LspConnection {
     return this.nextId
   }
 
-  /** Request termination of the server's process tree (SIGTERM, no escalation). */
+  /** Terminate the server's process tree (the seam's SIGTERM→grace→SIGKILL escalation; idempotent). */
   terminate(): void {
-    this.handle.kill('SIGTERM')
-  }
-
-  /** Force termination of the server's process tree. */
-  kill(): void {
-    this.handle.kill('SIGKILL')
+    this.handle.terminate()
   }
 
   /**
@@ -235,9 +230,10 @@ export class LspConnection {
       messages = this.decoder.push(chunk)
     } catch (error) {
       // A framing/JSON failure corrupts the stream position irrecoverably: fail the instance and
-      // SIGKILL the whole group so helper processes don't outlive the leader.
+      // terminate the whole group so helper processes don't outlive the leader (SIGTERM first, then
+      // the kill grace's SIGKILL — a misbehaving server still gets its bounded flush window).
       this.fail(asError(error))
-      this.handle.kill('SIGKILL')
+      this.handle.terminate()
       return
     }
     for (const message of messages) this.dispatch(message)

packages/lsp/lsp-local/src/index.ts

@@ -285,8 +285,6 @@ class LocalLspProvider implements LspProvider {
       initializationOptions: this.config.initializationOptions,
       maxMessageBytes: this.config.maxMessageBytes,
       maxStderrBytes: this.config.maxStderrBytes,
-      // Exit observation must never be slower than the escalation it feeds.
-      pipeDrainGraceMs: this.config.killGraceMs,
       shutdownTimeoutMs: this.config.shutdownTimeoutMs,
       killGraceMs: this.config.killGraceMs,
     }

packages/lsp/lsp-local/src/instance.ts

@@ -35,17 +35,6 @@ export interface InstanceSpec extends ConnectionSpec {
   readonly initializationOptions: unknown
   /** Graceful `shutdown`/`exit` budget before escalation (ms). */
   readonly shutdownTimeoutMs: number
-  /** SIGTERM→SIGKILL grace after graceful shutdown fails (ms). */
-  readonly killGraceMs: number
-}
-
-/**
- * Force-kill a process tree only when graceful termination did not make it exit.
- * @param treeExited - whether the tree exited within its grace period.
- * @param forceKill - forceful process-tree termination primitive.
- */
-export function escalateProcessTree(treeExited: boolean, forceKill: () => void): void {
-  if (!treeExited) forceKill()
 }
 
 /**
@@ -311,17 +300,14 @@ export class LspInstance {
     await abortable(this.connection.closed, signal)
   }
 
-  /** Terminate the tree, escalate after `killGraceMs`, then await leader and helper exit. */
+  /**
+   * Terminate the tree (the seam escalates SIGTERM→`killGraceMs`→SIGKILL),
+   * then await leader and helper exit. The awaits are unbounded on purpose:
+   * the seam's escalation already committed to SIGKILL, so quiescence — not
+   * another timer — is the postcondition disposal owes its callers.
+   */
   private async forceTerminate(): Promise<void> {
     this.connection.terminate()
-    const graceDeadline = deadline(undefined, this.spec.killGraceMs, 'LSP_KILL_GRACE')
-    let treeExited: boolean
-    try {
-      treeExited = await this.connection.waitForProcessTreeExit(graceDeadline.signal)
-    } finally {
-      graceDeadline[Symbol.dispose]()
-    }
-    escalateProcessTree(treeExited, this.connection.kill.bind(this.connection))
     await Promise.all([
       this.connection.closed,
       this.connection.waitForProcessTreeExit(),

packages/lsp/lsp-local/tests/connection.spec.ts

@@ -14,7 +14,7 @@ let open: LspConnection[] = []
 
 afterEach(async () => {
   for (const conn of open) {
-    conn.kill()
+    conn.terminate()
     await conn.closed
   }
   open = []
@@ -33,7 +33,7 @@ function connect(
     env: { ...scrubbedParentEnv(), ...env },
     maxMessageBytes: 16_000_000,
     maxStderrBytes: 100_000,
-    pipeDrainGraceMs: 3_000,
+    killGraceMs: 3_000,
     configuration: { setting: 42 },
   }, spawnSubprocess, (method, params) => {
     seen?.push({ method, params })
@@ -66,10 +66,10 @@ describe('LspConnection', () => {
     await expect(conn.request('textDocument/hover', {})).rejects.toThrow(/server refused the request/)
   })
 
-  it('treats signaling an already-closed child as a teardown race', async () => {
+  it('treats terminating an already-closed child as a teardown race', async () => {
     const conn = connectScript('')
     await conn.closed
-    expect(() => { conn.kill() }).not.toThrow()
+    expect(() => { conn.terminate() }).not.toThrow()
   })
 
   it('answers a server workspace/configuration request from static config', async () => {
@@ -152,7 +152,7 @@ function connectScript(script: string, maxStderrBytes = 100_000, writer?: Connec
     env: scrubbedParentEnv(),
     maxMessageBytes: 16_000_000,
     maxStderrBytes,
-    pipeDrainGraceMs: 3_000,
+    killGraceMs: 3_000,
     configuration: null,
   }, spawnSubprocess, () => Promise.resolve(null), writer)
   open.push(conn)
@@ -168,7 +168,7 @@ describe('LspConnection edge behavior', () => {
       env: {},
       maxMessageBytes: 1000,
       maxStderrBytes: 1000,
-      pipeDrainGraceMs: 3_000,
+      killGraceMs: 3_000,
       configuration: null,
     }, spawnSubprocess, () => Promise.resolve(null))
     open.push(conn)

packages/lsp/lsp-local/tests/instance.spec.ts

@@ -1,4 +1,4 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
 import { mkdtemp, mkdir, readFile, rm, writeFile, realpath } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
@@ -6,7 +6,6 @@ import { pathToFileURL, fileURLToPath } from 'node:url'
 import { LspInstance, readHostSource } from '@deepseek-ai/dsh-lsp-local'
 import { encodeMessage } from '@deepseek-ai/dsh-lsp-local'
 import type { ConnectionWriter } from '@deepseek-ai/dsh-lsp-local/src/connection.ts'
-import { escalateProcessTree } from '@deepseek-ai/dsh-lsp-local/src/instance.ts'
 import type { InstanceSpec } from '@deepseek-ai/dsh-lsp-local/src/instance.ts'
 import type { LspProviderQuery, LspQueryResult } from '@deepseek-ai/dsh-lsp'
 import { scrubbedParentEnv } from '@deepseek-ai/dsh-subprocess'
@@ -45,7 +44,6 @@ function makeInstance(
     initializationOptions: { init: true },
     maxMessageBytes: 16_000_000,
     maxStderrBytes: 100_000,
-    pipeDrainGraceMs: 200,
     shutdownTimeoutMs: 200,
     killGraceMs: 200,
     ...overrides,
@@ -75,7 +73,6 @@ function scriptInstance(script: string, overrides: Partial<InstanceSpec> = {}):
     initializationOptions: null,
     maxMessageBytes: 16_000_000,
     maxStderrBytes: 100_000,
-    pipeDrainGraceMs: 150,
     shutdownTimeoutMs: 150,
     killGraceMs: 150,
     ...overrides,
@@ -258,14 +255,6 @@ describe('LspInstance query and abort', () => {
 })
 
 describe('LspInstance disposal', () => {
-  it('escalates only when the process tree survives its grace period', () => {
-    const forceKill = vi.fn()
-    escalateProcessTree(false, forceKill)
-    expect(forceKill).toHaveBeenCalledOnce()
-    escalateProcessTree(true, forceKill)
-    expect(forceKill).toHaveBeenCalledOnce()
-  })
-
   it('lets a server finish protocol exit before signal escalation', async () => {
     const marker = join(root, 'graceful-exit.log')
     const instance = makeInstance({