pi-mcp-extension 1.11.2 → 1.11.3

package/README.md

@@ -20,14 +20,15 @@
 - **Clean cancellation** — `AbortSignal` propagation via `notifications/cancelled`
 - **Smart reconnection** — Fixed delay retry schedule (1s → 3s → 5s → 10s → 30s), configurable max retries, and automatic recovery when a server transport closes unexpectedly
 - **Health checks** — Opt-in periodic pings to detect stale connections
-- **Safe process lifecycle** — Child PID tracking (`StdioClientTransport.pid`) with safety-net `SIGKILL` for orphaned subprocesses
+- **Safe process lifecycle** — Child PID tracking (`StdioClientTransport.pid`) with tree-aware cleanup: descendants of wrapper commands (`npx`, `npm exec`, `uvx`, `sh -c`) are terminated too, and inherited pipes are released so teardown never stalls
 - **Stable tool names** — Sanitized, collision-avoiding names (max 64 chars) that stay constant across reconnects
 - **No tool churn** — Activate/deactivate pattern ensures tools don't flicker during reconnection
-- **Layered config & trust boundary** — Global `<agent dir>/mcp.json`, project `.pi/mcp.json` (loaded only in trusted projects via `ctx.isProjectTrusted()`), and Pi 1.x extension-registered servers (`pi.registerMcpServer()`)
+- **Layered config & trust boundary** — Global `<agent dir>/mcp.json`, project `.pi/mcp.json` (loaded only in trusted projects via `ctx.isProjectTrusted()`, including Pi 1.3.0 partial overrides), and Pi 1.x extension-registered servers (`pi.registerMcpServer()`)
 - **Rich tool results & annotations** — MCP `image` content passthrough (`ImageContent`), plus `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint` surfaced in tool descriptions
-- **On-demand agent tools & commands** — `mcp_status` and `mcp_connect` agent tools plus `/mcp`, `/mcp:start`, `/mcp:stop`, and `/mcp:auth` slash commands with server-name autocomplete
-- **Structured error handling** — Distinct error codes for config, connection, protocol, and tool-level failures
-- **OAuth 2.1** — Browser and headless/SSH authorization with PKCE, protected-resource discovery, Dynamic Client Registration, startup prompts for eager servers, cross-process lock recovery, token refresh, and secure local persistence (see [OAUTH.md](./OAUTH.md))
+- **On-demand agent tools & commands** — `mcp_status` and `mcp_connect` agent tools plus `/mcp`, `/mcp <name>` (with config provenance and failure hints), `/mcp:start`, `/mcp:stop`, and `/mcp:auth` slash commands with server-name autocomplete
+- **Structured error handling** — Distinct error codes (`config`, `connection`, `auth`, `timeout`, `protocol`, `tool`) and actionable failure hints
+- **Redacted debug logging** — Opt-in `PI_MCP_DEBUG=1` JSON Lines log (`<agent dir>/logs/pi-mcp.log`, `0600`, ~2 MB rotation) with automatic secret masking and zero TUI `stderr` noise
+- **OAuth 2.1** — Browser and headless/SSH authorization with PKCE, protected-resource discovery, Dynamic Client Registration, startup prompts for eager servers, cross-process lock recovery, token refresh, and origin/issuer-bound local persistence (see [OAUTH.md](./OAUTH.md))
 
 ## Installation
 
@@ -57,7 +58,7 @@ pi -e npm:pi-mcp-extension
    }
    ```
 
-3. Create a config file at `~/.pi/agent/mcp.json` (global) or `.pi/mcp.json` (project-level):
+3. Create a config file at `~/.pi/agent/mcp.json` (global) or `.pi/mcp.json` (project-level). Both files support **JSONC** (`//` line and `/* ... */` block comments):
    ```jsonc
    {
      "mcpServers": {
@@ -70,11 +71,11 @@ pi -e npm:pi-mcp-extension
    }
    ```
 
-4. Start Pi — your MCP tools are ready. Use `/mcp` to check server status.
+4. Start Pi — your MCP tools are ready. Use `/mcp` to check all servers or `/mcp <name>` to inspect one in detail.
 
 ## Configuration
 
-Servers can be configured via JSON files or registered programmatically by other Pi 1.x extensions:
+Servers can be configured via JSON/JSONC files (`//` and `/* */` comments are supported) or registered programmatically by other Pi 1.x extensions:
 
 | Source | Precedence & Scope |
 |---|---|
@@ -103,7 +104,7 @@ Servers can be configured via JSON files or registered programmatically by other
       "lifecycle": "eager"
     },
     "deepsource": {
-      "url": "https://mcp.deepsource.io/mcp", // "transport" defaults to "streamable-http" when "url" is set
+      "url": "https://mcp.deepsource.com/mcp", // "transport" defaults to "streamable-http" when "url" is set
       "lifecycle": "eager"
     },
 
@@ -123,6 +124,7 @@ Servers can be configured via JSON files or registered programmatically by other
     "context7": {
       "command": "npx",
       "args": ["-y", "@context7/mcp"],
+      "cwd": "./",
       "transport": "stdio",
       "lifecycle": "lazy"
     },
@@ -184,14 +186,14 @@ An override may set `enabled`, `lifecycle`, and Pi's `exposure` / `toolExposure`
 
 ### OAuth Config
 
-Configured under `auth` (or `oauth`). Token and client state are persisted per server in `<agent dir>/mcp-auth/<hash>.json` (`0700` directory, `0600` files on POSIX) with atomic writes and automatic backup of corrupt state files. See [OAUTH.md](./OAUTH.md) for architecture and troubleshooting details.
+Configured under `auth` (or `oauth`). Token and client state are persisted per server in `<agent dir>/mcp-auth/<hash>.json` (`0700` directory, `0600` files on POSIX) with atomic writes, origin (`serverUrl`) and authorization-server (`issuer`) binding, and automatic backup of corrupt state files. See [OAUTH.md](./OAUTH.md) for architecture and troubleshooting details.
 
 | Field | Type | Default | Description |
 |---|---|---|---|
 | `type` | `"oauth"` | `"oauth"` | Authentication type |
 | `scope` | `string` | discovered | Requested scope when the server does not advertise one in `WWW-Authenticate` |
 | `clientId` | `string` | dynamic registration | Pre-registered OAuth client ID (skips Dynamic Client Registration) |
-| `clientSecret` | `string` | — | Secret for a pre-registered confidential client |
+| `clientSecret` | `string` | — | Secret for a pre-registered confidential client (used in memory; never written to disk) |
 | `clientName` (or `oauth.clientName`) | `string` | `pi-mcp/<server name>` | `client_name` sent with Dynamic Client Registration, for servers that only accept known clients |
 | `redirectUrl` (or `oauth.callbackUrl` / `oauth.callbackPort`) | `string` | `http://127.0.0.1:19876/callback` | Local HTTP loopback callback (`localhost`, `127.0.0.1`, or `::1` with path `/callback` and an explicit non-zero port; `callbackPort` maps to `http://127.0.0.1:<port>/callback`). Scans forward from `19876` when omitted; binds the exact host and port when configured. |
 
@@ -199,7 +201,7 @@ Configured under `auth` (or `oauth`). Token and client state are persisted per s
 
 Server-name arguments provide autocomplete suggestions from the configured MCP servers. `/mcp:auth` suggests only servers configured for OAuth.
 
-| Command | Description |
+| Slash Command | Description |
 |---|---|
 | `/mcp` | Show status summary of all configured servers |
 | `/mcp <name>` | Show detailed status for one server: config source, transport/lifecycle, tool activation, OAuth credential status, failure hint, and stderr log |
@@ -208,7 +210,12 @@ Server-name arguments provide autocomplete suggestions from the configured MCP s
 | `/mcp:auth <name>` | Connect with stored OAuth credentials and client registration; request browser authorization only if needed |
 | `/mcp:auth <name> --reset` | Discard stored tokens and client registration (re-running Dynamic Client Registration) and request fresh authorization |
 
-Agent tools `mcp_status` and `mcp_connect` let Pi inspect configured servers and connect one named server without routine slash commands. `mcp_status` reports lifecycle, connection state, discovered and active tool counts, credential presence, config source, and safe action hints without returning tokens, headers, or authorization URLs. `mcp_connect` activates discovered tools before returning success. Connection failures return fixed actionable categories instead of raw server response text.
+In addition to user slash commands, two built-in **agent tools** let the LLM inspect and connect configured servers directly:
+
+| Agent Tool | Parameters | Description |
+|---|---|---|
+| `mcp_status` | `{}` | List configured servers with `lifecycle`, `state`, `tools` (`discovered` / `active`), `auth` credential presence, `source` (`global` / `project` / `extension`), and safe `error` action hints (never returns tokens, headers, or authorization URLs) |
+| `mcp_connect` | `{ name: string }` | Connect one named server, run interactive OAuth if needed, and verify that discovered tools are active before returning success (returns fixed actionable categories on failure instead of raw server response text) |
 
 ### Inspecting one server (`/mcp <name>`)
 
@@ -276,39 +283,53 @@ While a Pi UI is active, the extension never writes diagnostics to Pi's stderr (
 
 ## How It Works
 
-```
-┌─────────────────────────────────────────────────────────┐
-│  Pi Agent                                               │
-│                                                         │
-│  ┌──────────┐    ┌────────────────┐    ┌─────────────┐  │
-│  │ index.ts │───▶│ server-manager │───▶│ tool-bridge  │  │
-│  │ (entry)  │    │ (lifecycle)    │    │ (MCP → Pi)   │  │
-│  └──────────┘    └───────┬────────┘    └──────┬──────┘  │
-│       │                  │                     │         │
-│       ▼                  ▼                     ▼         │
-│  ┌──────────┐    ┌──────────────┐    ┌──────────────┐   │
-│  │ config   │    │ MCP SDK      │    │ TypeBox      │   │
-│  │ (Zod)    │    │ (transport)  │    │ (schema)     │   │
-│  └──────────┘    └──────────────┘    └──────────────┘   │
-└─────────────────────────────────────────────────────────┘
-         │                  │
-         ▼                  ▼
-   Global/Project    ┌──────────────┐
-   mcp.json files    │ MCP Servers  │
-   + Extensions      │ (stdio/http) │
-                     └──────────────┘
+```text
+┌─────────────────────────────────────────────────────────────────────────┐
+│  Pi Agent (TUI / RPC, ExtensionAPI)                                     │
+│                                                                         │
+│  ┌────────────────────┐    ┌────────────────────────┐                   │
+│  │ index.ts           │───▶│ register-commands      │ (/mcp, :start,    │
+│  │ (entry & mcp_*     │    │ (/mcp* slash commands) │  :stop, :auth)    │
+│  │  agent tools)      │    └───────────┬────────────┘                   │
+│  └────┬──────────┬────┘                │                                │
+│       │          └──────────────┐      │                                │
+│       │                         ▼      ▼                                │
+│       │                    ┌────────────────────────┐                   │
+│       │                    │ connection-coordinator │                   │
+│       │                    │ (in-flight connects,   │                   │
+│       │                    │  authQueue, teardown)  │                   │
+│       │                    └───────────┬────────────┘                   │
+│       │                                │                                │
+│       │                                ▼                                │
+│       │                    ┌────────────────────────┐    ┌───────────┐  │
+│       │                    │ server-manager         │───▶│tool-bridge│  │
+│       │                    │ (stopped → starting    │    │(MCP → Pi) │  │
+│       │                    │  → ready lifecycle)    │    └─────┬─────┘  │
+│       ▼                    └───────────┬────────────┘          │        │
+│  ┌────────────────────┐                ▼                       ▼        │
+│  │ config             │    ┌────────────────────────┐    ┌───────────┐  │
+│  │ (Zod + JSONC)      │    │ transport-factory &    │    │ TypeBox   │  │
+│  └────────┬───────────┘    │ oauth-provider (SDK)   │    │ (schema)  │  │
+│           │                └───────────┬────────────┘    └───────────┘  │
+└───────────┼────────────────────────────┼────────────────────────────────┘
+            │                            │
+            ▼                            ▼
+   Global/Project mcp.json       ┌──────────────┐
+   + Registered Extensions       │ MCP Servers  │
+                                 │ (stdio/http) │
+                                 └──────────────┘
 ```
 
 1. **Config is loaded** from global `<agent dir>/mcp.json`, trusted project `.pi/mcp.json` (checked via `ctx.isProjectTrusted()` on `session_start`), and extension-registered servers (`pi.getMcpServers()` / `mcp_servers_change`), with `mcp.json` taking precedence over extension-registered servers and project entries overriding global ones
-2. **Eager servers connect** at `session_start` (offering a sequential `Authorize now` / `Not now` prompt when an eager OAuth server needs authorization in an interactive session); lazy servers wait for `mcp_connect`, `/mcp:start`, or `/mcp:auth`
+2. **Eager servers connect** at `session_start` via `ConnectionCoordinator` (offering a sequential `Authorize now` / `Not now` prompt when an eager OAuth server needs authorization in an interactive session); lazy servers wait for `mcp_connect`, `/mcp:start`, or `/mcp:auth`
 3. **Tools are discovered** via paginated `tools/list` calls (cursor-based, up to 100 pages) before a server enters `ready`
-4. **JSON Schema → TypeBox** conversion registers tools with Pi-compatible parameter schemas
+4. **JSON Schema → TypeBox** conversion registers tools with Pi-compatible parameter schemas (preserving nullable union ordering, resolving `$ref`s cycle-safely, and inferring/flattening `allOf` object schemas)
 5. **Pi tools are registered** as `<prefix>_<server>_<tool>` (sanitized, max 64 chars with hash suffix) and pass through text and `image` content blocks (`ImageContent`)
 6. **Tools activate/deactivate** automatically as servers connect/disconnect
 7. **AbortSignal** is wired through to `notifications/cancelled` for clean cancellation
 8. **Reconnection & recovery** uses a fixed delay schedule with configurable max retries on initial failure, health check failure, or unexpected transport close (`client.onclose`)
 9. **`list_changed` notifications** trigger re-discovery, deactivating stale tools automatically
-10. **Session shutdown** cancels pending auth/connection flows, stops the callback server, deactivates all tools, and cleanly stops all servers (with a `SIGKILL` safety net for `stdio` child processes)
+10. **Session shutdown** cancels pending auth/connection flows, stops the callback server, deactivates all tools, flushes the debug log, and cleanly stops all servers (with a `SIGKILL` safety net for `stdio` child processes)
 
 ## MCP Spec Compliance
 
@@ -340,30 +361,38 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup, workflow, and the pre-merge
 ## Development
 
 ```bash
-# Install dependencies
-npm install
+# Install dependencies (clean lockfile install)
+npm ci
 
-# Lint (type-aware ESLint)
+# Lint (type-aware ESLint + structural/complexity checks)
 npm run lint
 
 # Type check (strict mode)
 npm run typecheck
 
-# Run all tests
+# Run all test suites
 npm test
 
+# Run all test suites with coverage floor (95% lines / 85% branches / 83% functions)
+npm run test:coverage
+
 # Run integration tests only (real stdio server)
 npm run test:integration
+
+# Verify npm tarball contents
+npm pack --dry-run
 ```
 
 ### Testing
 
 The test suite includes:
-- **Config & Pi 1.x compatibility** — Zod schema, `$PI_CODING_AGENT_DIR` resolution, global/project merge, project trust boundary (`ctx.isProjectTrusted()`), Pi 1.x schema aliases (`type: "http"`, URL-only HTTP, `oauth`, `timeout`), and dynamic `pi.getMcpServers()` / `mcp_servers_change`
-- **Server lifecycle & coordination** — Connect, retry, unexpected close recovery, shutdown with PID `SIGKILL` safety net, health check, concurrent connect/reset coordination, and cancellation
-- **OAuth 2.1 & auth locks** — Challenge discovery, PKCE, Dynamic Client Registration, startup authorization prompts, headless/SSH redirect URL paste-back, URL scheme validation, cross-process lock heartbeat and stale lock reclamation
-- **Tool bridge & management tools** — JSON Schema → TypeBox conversion, name sanitization, image content passthrough, `isError` filtering, activate/deactivate, `mcp_status` / `mcp_connect`, and slash command completions
-- **End-to-end integration** — Real mock MCP and OAuth servers over stdio and HTTP with tool discovery and execution
+- **Config & Pi 1.x / 1.3.0 compatibility** (`tests/config.test.ts`, `tests/pi-1x-compat.test.ts`) — Zod schema, JSONC comments, `$PI_CODING_AGENT_DIR` resolution, global/project merge, project trust boundary (`ctx.isProjectTrusted()`), Pi 1.3.0 `enabled: false` and partial project overrides, `stdio` `cwd`, `oauth.clientName`, Pi 1.x schema aliases (`type: "http"`, URL-only HTTP, `oauth`, `timeout`), and dynamic `pi.getMcpServers()` / `mcp_servers_change`
+- **Server lifecycle & coordination** (`tests/server-manager.test.ts`, `tests/stdio-process.test.ts`, `tests/transport-factory.test.ts`, `tests/connection-coordinator.test.ts`, `tests/connection-coordination.test.ts`) — Connect, retry, unexpected close recovery, shutdown with PID `SIGKILL` safety net, health check, concurrent connect/reset coordination, and cancellation
+- **OAuth 2.1 & auth locks** (`tests/oauth-fixes.test.ts`, `tests/authorize-flow.test.ts`, `tests/auth-lock.test.ts`, `tests/auth-commands.test.ts`, `tests/auth-arguments.test.ts`, `tests/fake-oauth-server.test.ts`) — Challenge discovery, PKCE, Dynamic Client Registration, origin and issuer binding, startup authorization prompts, headless/SSH redirect URL paste-back, URL scheme validation, cross-process lock heartbeat, and stale lock reclamation
+- **Tool bridge, status diagnostics & debug log** (`tests/tool-bridge.test.ts`, `tests/management-tools.test.ts`, `tests/server-status.test.ts`, `tests/status-commands.test.ts`, `tests/completions.test.ts`, `tests/debug-log.test.ts`) — JSON Schema → TypeBox conversion (`allOf` object inference, `$ref` cycle protection, union `null` ordering), name sanitization, image content passthrough, `isError` filtering, activate/deactivate, `mcp_status` / `mcp_connect`, `/mcp <name>` config provenance and failure hints, slash command completions, and redacted `PI_MCP_DEBUG=1` JSONL logging
+- **Property-based fuzzing** (`tests/fuzz.test.ts`) — `fast-check` properties covering JSONC comment stripping, callback/redirect URL validation, `WWW-Authenticate` challenge parsing, JSON Schema → TypeBox conversion, tool naming, terminal/log secret sanitization, and custom header merging
+- **Release flow & repository policy** (`tests/release.test.ts`, `tests/ruleset-audit.test.ts`, `tests/repo-policy.test.ts`) — Release PR orchestration and npm/git self-healing (`scripts/release.ts`), live GitHub ruleset drift auditing (`scripts/ruleset-audit.ts`), and CI/ESLint/Qlty policy invariants
+- **End-to-end integration** — Real mock MCP and OAuth servers over `stdio` and HTTP with tool discovery and execution
 
 ## Security
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mcp-extension",
-  "version": "1.11.2",
+  "version": "1.11.3",
   "description": "MCP (Model Context Protocol) client extension for the Pi coding agent — connect Pi to any MCP server",
   "type": "module",
   "keywords": [

package/src/server-manager.ts

@@ -29,8 +29,10 @@ import type { ToolRefreshOptions } from "./tool-bridge.js";
 import { sanitizeTerminalText, type SanitizeTerminalTextOptions } from "./terminal-text.js";
 import { describeError, reportDiagnostic } from "./debug-log.js";
 import {
+  destroyStdioStreams,
   ensurePidTerminated,
   instrumentStdioTransport,
+  waitForChildClose,
 } from "./stdio-process.js";
 import { createTransport } from "./transport-factory.js";
 import {
@@ -827,6 +829,26 @@ export class ServerManager {
     };
   }
 
+  /**
+   * Terminate the stdio child process tree, then release the child's pipe handles.
+   *
+   * WHY: `client.close()` waits for the child's `'close'` event, which never fires while a
+   * leaked grandchild still holds the inherited stdout/stderr write ends — the SDK then
+   * burns its full 2 × 2,000ms escalation budget. Killing the tree first and destroying the
+   * pipes afterwards keeps teardown bounded even if a descendant escaped the tree kill.
+   */
+  private async _terminateStdioTree(
+    pid: number | null,
+    transport: Transport | undefined,
+  ): Promise<void> {
+    try {
+      await ensurePidTerminated(pid);
+      await waitForChildClose(transport);
+    } finally {
+      destroyStdioStreams(transport);
+    }
+  }
+
   private async _cleanupFailedConnect(
     server: ManagedServer,
     client: Client,
@@ -839,7 +861,7 @@ export class ServerManager {
     server.childPid = null;
     await Promise.allSettled([
       client.close(),
-      ensurePidTerminated(pid),
+      this._terminateStdioTree(pid, transport),
     ]);
     // WHY: Secondary safety check to guarantee PID termination even if transport.close()
     // or child process exit raced during the initial Promise.allSettled.
@@ -1081,13 +1103,14 @@ export class ServerManager {
       server.childPid ??
       (server.transport as unknown as { _process?: { pid?: number } })?._process?.pid ??
       null;
+    const transport = server.transport;
     server.client = null;
     server.transport = undefined;
     server.childPid = null;
 
     await Promise.allSettled([
       client?.close(),
-      ensurePidTerminated(pid),
+      this._terminateStdioTree(pid, transport),
     ]);
     await ensurePidTerminated(pid);
   }

package/src/stdio-process.ts

@@ -3,13 +3,20 @@
  *
  * Provides pure StringDecoder-based line splitting across chunk boundaries,
  * StdioClientTransport instrumentation (early PID capture, memoized close,
- * stderr wiring), and deterministic SIGTERM → bounded wait → SIGKILL cleanup
- * with injectable process/timer dependencies.
+ * stderr wiring), descendant process-tree discovery for wrappers such as
+ * `npx`, `uvx`, or `sh -c`, and deterministic SIGTERM → bounded wait → SIGKILL
+ * cleanup with injectable process/timer dependencies.
  */
 
+import { execFile } from "node:child_process";
+import { readFile, readdir } from "node:fs/promises";
 import { StringDecoder } from "node:string_decoder";
+import { promisify } from "node:util";
+import type { ChildProcess } from "node:child_process";
 import type { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 
+const execFileAsync = promisify(execFile);
+
 // ─── Line Splitting ───────────────────────────────────────────────────────────
 
 export interface LineSplitter {
@@ -27,6 +34,7 @@ export function createLineSplitter(onLine: (line: string) => void): LineSplitter
 
   return {
     write(chunk: Buffer): void {
+      flushed = false;
       remainder += decoder.write(chunk);
       const lines = remainder.split("\n");
       remainder = lines.pop() ?? "";
@@ -49,6 +57,25 @@ export function createLineSplitter(onLine: (line: string) => void): LineSplitter
 
 // ─── Transport Instrumentation ────────────────────────────────────────────────
 
+/** Grace window for an exited child's pipes to drain naturally before force-destroying them. */
+const PIPE_DRAIN_GRACE_MS = 100;
+
+interface StdioChildRecord {
+  process: ChildProcess;
+  closed: boolean;
+  /** Flush the buffered partial stderr line before the pipe is destroyed. */
+  flushStderr(): void;
+}
+
+/**
+ * Child processes of instrumented transports, keyed by transport.
+ *
+ * WHY: `StdioClientTransport.close()` clears `_process` synchronously, so the child
+ * handle is gone by the time teardown needs its pipes and its stderr flush. A WeakMap
+ * keeps both reachable without pinning a closed transport in memory.
+ */
+const childRecords = new WeakMap<object, StdioChildRecord>();
+
 export interface InstrumentStdioTransportOptions {
   onPid(pid: number): void;
   onStderrLine(line: string): void;
@@ -66,17 +93,35 @@ export function instrumentStdioTransport(
   // WHY: Capture child PID immediately when StdioClientTransport spawns the process
   // (before `initialize` is sent), so a timeout or cancellation during `initialize`
   // can still terminate the child process deterministically before retrying.
+  const spawnedProcess = (): ChildProcess | undefined =>
+    (transport as unknown as { _process?: ChildProcess })._process;
+
+  let flushStderr: (() => void) | null = null;
+
+  const recordProcess = (proc: ChildProcess | undefined): void => {
+    if (!proc?.pid) return;
+    if (!childRecords.has(transport)) {
+      const record: StdioChildRecord = {
+        process: proc,
+        closed: false,
+        flushStderr: () => flushStderr?.(),
+      };
+      proc.once?.("close", () => {
+        record.closed = true;
+      });
+      childRecords.set(transport, record);
+    }
+    onPid(proc.pid);
+  };
+
   const origStart = transport.start.bind(transport);
   transport.start = async () => {
     const startPromise = origStart();
-    const earlyProc = (transport as unknown as { _process?: { pid?: number } })._process;
-    if (earlyProc?.pid) {
-      onPid(earlyProc.pid);
-    }
+    recordProcess(spawnedProcess());
     await startPromise;
-    const proc = (transport as unknown as { _process?: { pid?: number } })._process;
+    const proc = spawnedProcess();
     if (proc?.pid) {
-      onPid(proc.pid);
+      recordProcess(proc);
     } else if (transport.pid) {
       onPid(transport.pid);
     }
@@ -99,26 +144,212 @@ export function instrumentStdioTransport(
     transport.stderr.on("data", (chunk: Buffer) => {
       splitter.write(chunk);
     });
-    const flushStderr = (): void => {
+    const flush = (): void => {
       splitter.end();
     };
-    transport.stderr.on("end", flushStderr);
-    transport.stderr.on("close", flushStderr);
+    flushStderr = flush;
+    transport.stderr.on("end", flush);
+    transport.stderr.on("close", flush);
+  }
+}
+
+/**
+ * Wait briefly for an exited child process to drain its stdio pipes and emit `'close'`
+ * naturally before `destroyStdioStreams` force-destroys the parent's pipe read ends.
+ *
+ * WHY: On Windows, `process.stderr` is an overlapped named pipe whose final bytes can
+ * still be in flight in libuv when `TerminateProcess` completes. Letting `'close'` fire
+ * naturally preserves trailing stderr output when no grandchild holds the pipe open, while
+ * bounding the wait to `PIPE_DRAIN_GRACE_MS` when a surviving grandchild keeps it open.
+ */
+export async function waitForChildClose(
+  transport: object | null | undefined,
+  timeoutMs = PIPE_DRAIN_GRACE_MS,
+): Promise<void> {
+  if (!transport) return;
+  const record = childRecords.get(transport);
+  if (!record || record.closed || typeof record.process.once !== "function") return;
+  await new Promise<void>((resolve) => {
+    const timer = setTimeout(() => {
+      record.process.removeListener?.("close", onClose);
+      resolve();
+    }, timeoutMs);
+    const onClose = (): void => {
+      clearTimeout(timer);
+      resolve();
+    };
+    record.process.once("close", onClose);
+  });
+}
+
+/**
+ * Destroy the child's `stdout`/`stderr` pipes once the process tree is gone.
+ *
+ * WHY: A surviving grandchild (e.g. a server spawned by an `npx` wrapper) inherits the
+ * wrapper's pipe write ends, so Node never emits `'close'` for the wrapper and
+ * `StdioClientTransport.close()` burns its full 4000ms escalation budget waiting for the
+ * `'close'` event. Destroying the parent's read ends lets `close()` resolve immediately
+ * even when a descendant escaped the tree kill. `stdin` is left alone: it is our write
+ * end and the SDK still ends it as part of its own close sequence.
+ */
+export function destroyStdioStreams(transport: object | null | undefined): void {
+  if (!transport) return;
+  const record = childRecords.get(transport);
+  if (!record) return;
+  childRecords.delete(transport);
+  // WHY: Flush the buffered partial stderr line first. Destroying our read end keeps the
+  // SDK's PassThrough from ever emitting 'end', so without this a forced teardown drops the
+  // server's last words (the buffered remainder of a line with no trailing newline).
+  record.flushStderr();
+  record.process.stdout?.destroy();
+  record.process.stderr?.destroy();
+}
+
+// ─── Descendant Discovery ─────────────────────────────────────────────────────
+
+/**
+ * Upper bound on tracked descendants.
+ *
+ * WHY: A wrapper that respawns children while we walk the tree could otherwise make
+ * discovery unbounded; teardown only needs the tree as it stood when we snapshotted it.
+ */
+const MAX_DESCENDANTS = 256;
+
+/** Read the direct child PIDs of `pid` from Linux `/proc`. */
+async function readProcChildren(pid: number): Promise<number[]> {
+  // WHY: /proc/<pid>/task/<tid>/children lists each thread's direct children, so a
+  // multithreaded wrapper is covered without scanning every process in /proc.
+  const taskDir = `/proc/${pid}/task`;
+  const tids = await readdir(taskDir);
+  const children: number[] = [];
+  for (const tid of tids) {
+    const raw = await readChildrenFile(`${taskDir}/${tid}/children`);
+    for (const token of raw.split(/\s+/)) {
+      if (token) children.push(Number(token));
+    }
+  }
+  return children;
+}
+
+async function readChildrenFile(path: string): Promise<string> {
+  try {
+    return await readFile(path, "utf8");
+  } catch (err) {
+    // WHY: A thread can exit between readdir() and readFile(), and a process that dies
+    // mid-walk simply has no children left to report.
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return "";
+    throw err;
   }
 }
 
+/** Timeout for a single `ps` process-table snapshot on non-Linux POSIX systems. */
+const PS_TIMEOUT_MS = 1_000;
+
+/**
+ * Read the full `ps` process table and index it as `parentPid → childPids`.
+ *
+ * WHY: macOS and other non-Linux POSIX systems have no `/proc`; `ps -A -o pid=,ppid=`
+ * dumps the entire process table in one call so a single snapshot can serve the whole
+ * tree walk without spawning `ps` once per node.
+ */
+async function readPsProcessTable(): Promise<Map<number, number[]>> {
+  const { stdout } = await execFileAsync("ps", ["-A", "-o", "pid=,ppid="], {
+    maxBuffer: 16 * 1024 * 1024,
+    timeout: PS_TIMEOUT_MS,
+  });
+  return indexProcessTable(stdout);
+}
+
+/** Index `ps -A -o pid=,ppid=` output as a parent PID → child PIDs map. */
+export function indexProcessTable(stdout: string): Map<number, number[]> {
+  const childrenOf = new Map<number, number[]>();
+  for (const line of stdout.split("\n")) {
+    const match = /^\s*(\d+)\s+(\d+)\s*$/.exec(line);
+    if (!match) continue;
+    const childPid = Number(match[1]);
+    const parentPid = Number(match[2]);
+    const siblings = childrenOf.get(parentPid);
+    if (siblings) {
+      siblings.push(childPid);
+    } else {
+      childrenOf.set(parentPid, [childPid]);
+    }
+  }
+  return childrenOf;
+}
+
+function createPlatformChildReader(): (pid: number) => Promise<number[]> {
+  if (process.platform === "linux") return readProcChildren;
+  if (process.platform === "win32") {
+    // WHY: Windows has no `/proc` or `ps`, and the portable tree kill (`taskkill /T`)
+    // must be driven by the caller's own signal semantics. Discovery reports nothing so
+    // teardown falls back to killing the top-level PID plus destroying the pipes.
+    return () => Promise.resolve([]);
+  }
+  let tablePromise: Promise<Map<number, number[]>> | null = null;
+  return async (pid: number): Promise<number[]> => {
+    tablePromise ??= readPsProcessTable();
+    const childrenOf = await tablePromise;
+    return childrenOf.get(pid) ?? [];
+  };
+}
+
+/**
+ * Snapshot the descendant PIDs of `pid`, deepest generation first.
+ *
+ * Returns `[]` when discovery is unavailable (Windows, containers without `ps` or
+ * `/proc`), which leaves the caller's single-PID teardown intact.
+ */
+export async function listDescendantPids(
+  pid: number,
+  readChildren: (pid: number) => Promise<number[]> = createPlatformChildReader(),
+): Promise<number[]> {
+  try {
+    const descendants = await walkDescendants(pid, readChildren);
+    // Breadth-first order reversed: each generation is signalled before its parent, so a
+    // wrapper cannot respawn or reap a child that is still being torn down.
+    return descendants.reverse();
+  } catch {
+    // WHY: Discovery is best-effort by design: the PID can exit between the liveness check
+    // and the `/proc` walk, and minimal containers ship neither `ps` nor `/proc`. A tree we
+    // cannot read must never fail the caller's shutdown path — teardown still kills the
+    // root PID and releases the inherited pipes.
+    return [];
+  }
+}
+
+async function walkDescendants(
+  pid: number,
+  readChildren: (pid: number) => Promise<number[]>,
+): Promise<number[]> {
+  const descendants: number[] = [];
+  const seen = new Set<number>([pid]);
+  const pending = await readChildren(pid);
+  while (pending.length > 0 && descendants.length < MAX_DESCENDANTS) {
+    const next = pending.shift();
+    if (next === undefined || seen.has(next)) continue;
+    seen.add(next);
+    descendants.push(next);
+    pending.push(...(await readChildren(next)));
+  }
+  return descendants;
+}
+
 // ─── Process Supervision ──────────────────────────────────────────────────────
 
 export interface StdioProcessDeps {
   kill(pid: number, signal?: NodeJS.Signals | number): void | boolean;
   sleep(ms: number): Promise<void>;
   now(): number;
+  /** Snapshot descendant PIDs of `pid`, deepest first. Resolves `[]` when unavailable. */
+  listDescendantPids(pid: number): Promise<number[]>;
 }
 
 const defaultDeps: StdioProcessDeps = {
   kill: (pid, signal) => process.kill(pid, signal),
   sleep: (ms) => new Promise<void>((resolve) => setTimeout(resolve, ms)),
   now: () => Date.now(),
+  listDescendantPids: (pid) => listDescendantPids(pid),
 };
 
 function resolveDeps(deps?: Partial<StdioProcessDeps>): StdioProcessDeps {
@@ -127,6 +358,7 @@ function resolveDeps(deps?: Partial<StdioProcessDeps>): StdioProcessDeps {
     kill: deps.kill ?? defaultDeps.kill,
     sleep: deps.sleep ?? defaultDeps.sleep,
     now: deps.now ?? defaultDeps.now,
+    listDescendantPids: deps.listDescendantPids ?? defaultDeps.listDescendantPids,
   };
 }
 
@@ -146,29 +378,68 @@ export function isPidAlive(
   }
 }
 
-async function signalAndWaitForExit(
-  pid: number,
-  signal: NodeJS.Signals,
-  timeoutMs: number,
-  d: StdioProcessDeps,
-): Promise<boolean> {
+/** Send `signal` to one PID; `false` when the PID was already gone (ESRCH). */
+function signalPid(pid: number, signal: NodeJS.Signals, d: StdioProcessDeps): boolean {
   try {
     d.kill(pid, signal);
+    return true;
   } catch (err) {
     if ((err as NodeJS.ErrnoException).code === "ESRCH") {
-      return true;
+      return false;
     }
+    // WHY: EPERM and platform refusals mean this PID cannot be signalled (a recycled PID
+    // or a sandboxed process). Teardown still has to signal the rest of the tree within
+    // the bounded wait instead of rejecting the caller's shutdown path.
+    return true;
+  }
+}
+
+function allExited(pids: readonly number[], d: StdioProcessDeps): boolean {
+  return pids.every((pid) => !isPidAlive(pid, d));
+}
+
+async function signalAndWaitForExit(
+  pids: readonly number[],
+  signal: NodeJS.Signals,
+  timeoutMs: number,
+  d: StdioProcessDeps,
+): Promise<boolean> {
+  const attempted = pids.map((pid) => signalPid(pid, signal, d));
+  // Every target reported ESRCH: the tree is already gone, so there is nothing to wait for.
+  if (!attempted.some(Boolean)) {
+    return true;
   }
 
   const deadline = d.now() + timeoutMs;
   while (d.now() < deadline) {
-    if (!isPidAlive(pid, d)) {
+    if (allExited(pids, d)) {
       return true;
     }
     await d.sleep(25);
   }
 
-  return !isPidAlive(pid, d);
+  return allExited(pids, d);
+}
+
+/**
+ * Escalate to SIGKILL across the surviving tree.
+ *
+ * WHY: The wrapper can spawn new children while it ignores SIGTERM, so the tree is
+ * re-snapshotted; the original snapshot still covers descendants of a wrapper that
+ * already exited (they were re-parented to init and are no longer discoverable).
+ */
+async function escalateToSigkill(
+  rootPid: number,
+  descendants: readonly number[],
+  d: StdioProcessDeps,
+): Promise<void> {
+  const rescanned = await d.listDescendantPids(rootPid);
+  const survivors = [...new Set([...rescanned, ...descendants])].filter((candidate) =>
+    isPidAlive(candidate, d),
+  );
+  const targets = [...survivors, rootPid].filter((candidate) => isPidAlive(candidate, d));
+  if (targets.length === 0) return;
+  await signalAndWaitForExit(targets, "SIGKILL", 200, d);
 }
 
 export async function ensurePidTerminated(
@@ -180,10 +451,12 @@ export async function ensurePidTerminated(
     return;
   }
 
-  if (await signalAndWaitForExit(pid, "SIGTERM", 500, d)) {
+  // WHY: Snapshot before signalling any PID: a wrapper that exits first re-parents its
+  // children to init, after which they can no longer be found by parent PID.
+  const descendants = await d.listDescendantPids(pid);
+  if (await signalAndWaitForExit([...descendants, pid], "SIGTERM", 500, d)) {
     return;
   }
 
-  await signalAndWaitForExit(pid, "SIGKILL", 200, d);
+  await escalateToSigkill(pid, descendants, d);
 }
-