pi-mcp-extension 1.11.2 → 1.11.4

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.4",
   "description": "MCP (Model Context Protocol) client extension for the Pi coding agent — connect Pi to any MCP server",
   "type": "module",
   "keywords": [

package/src/connection-coordinator.ts

@@ -73,6 +73,24 @@ type InteractiveAuthParams = {
   reset: boolean;
 };
 
+/**
+ * Whether a declined server still deserves the `run /mcp:auth <name>` footer hint.
+ *
+ * WHY: A decline records "this server needed authorization at some point", which stays
+ * true until there is positive evidence otherwise. `ready` is that evidence, and so is a
+ * `stopped` server whose `lastError` is now a non-auth failure (`ECONNREFUSED`, timeout) —
+ * that failure overwrote `AuthRequiredError`, so authorization is no longer the problem
+ * and the hint would send the user down the wrong path. An unknown server drops out too.
+ * Anything ambiguous (no `lastError` yet, still `starting`) keeps the hint, because
+ * clearing it on doubt would hide a pending authorization the user was just told about.
+ */
+function retainsAuthHint(server: Pick<ManagedServer, "state" | "lastError"> | undefined): boolean {
+  if (!server || server.state === "ready") return false;
+  const lastError = server.lastError;
+  if (!lastError || lastError instanceof AuthRequiredError) return true;
+  return server.state !== "stopped";
+}
+
 export class ConnectionCoordinator {
   private readonly deps: ConnectionCoordinatorDeps;
   private readonly connectAttempts = new Map<string, ConnectAttemptEntry>();
@@ -124,7 +142,7 @@ export class ConnectionCoordinator {
   syncStatus(ctx: ExtensionContext | undefined = this.activeCtx): void {
     for (const declinedName of Array.from(this.declinedStartupAuth)) {
       const server = this.deps.manager.getServer(declinedName);
-      if (!server || server.state === "ready") {
+      if (!retainsAuthHint(server)) {
         this.declinedStartupAuth.delete(declinedName);
       }
     }
@@ -147,18 +165,23 @@ export class ConnectionCoordinator {
 
   handleRecoveryFailed(serverName: string, error: unknown): void {
     if (error instanceof AuthRequiredError) {
-      this.declinedStartupAuth.add(serverName);
       this.activeCtx?.ui.notify(
         `pi-mcp: ${serverName} requires re-authorization — run /mcp:auth ${serverName}`,
         "warning",
       );
-      this.syncStatus(this.activeCtx);
-    } else {
-      this.activeCtx?.ui.notify(
-        `pi-mcp: Lost connection to ${serverName} — ${formatErrorMessage(error)}`,
-        "error",
-      );
+      // WHY: Route through markAuthRequired so a mid-session 401 (reported by
+      // ServerManager.handleUnauthorizedServerError) lands in the declined set and
+      // repaints the footer hint exactly like a declined startup prompt.
+      this.markAuthRequired(serverName);
+      return;
     }
+    this.activeCtx?.ui.notify(
+      `pi-mcp: Lost connection to ${serverName} — ${formatErrorMessage(error)}`,
+      "error",
+    );
+    // WHY: The failure just overwrote lastError, so a hint left over from an earlier
+    // decline now points at authorization that is not the problem — clear it.
+    this.syncStatus(this.activeCtx);
   }
 
   cancelServer(serverName: string): void {
@@ -325,6 +348,9 @@ export class ConnectionCoordinator {
         try {
           await this.deps.manager.startServer(name, ctx.cwd);
         } catch (err) {
+          // WHY: A cancelled start means the user stopped the server (/mcp:stop) or the
+          // session is tearing down; reporting it as a start failure would be a bogus error.
+          if (err instanceof AuthCancelledError) return;
           if (err instanceof AuthRequiredError && cfg.auth && ctx.hasUI) {
             authRequiredServers.add(name);
             return;
@@ -335,12 +361,14 @@ export class ConnectionCoordinator {
       }),
     );
 
+    // WHY: Reconcile the footer hint once every eager start has settled — a declined
+    // server may have connected cleanly or failed with a non-auth error, and either
+    // outcome makes "run /mcp:auth <name>" stale.
+    this.syncStatus(ctx);
+
     for (const [name] of serversToStart) {
       if (!authRequiredServers.has(name)) continue;
-      if (this.declinedStartupAuth.has(name)) {
-        this.syncStatus(ctx);
-        continue;
-      }
+      if (this.declinedStartupAuth.has(name)) continue;
       this.enqueueStartupAuthPrompt(name, ctx);
     }
 
@@ -483,8 +511,13 @@ export class ConnectionCoordinator {
       await this._startAndGuardAbort(serverName, ctx, controller.signal);
       return true;
     } catch (err) {
-      if (!(err instanceof AuthRequiredError) || !serverConfig.auth) throw err;
-      return false;
+      if (err instanceof AuthRequiredError && serverConfig.auth) return false;
+      // WHY: A non-auth connect failure (e.g. ECONNREFUSED) overwrites lastError, so a
+      // hint left over from an earlier decline no longer describes this server's problem.
+      if (!(err instanceof AuthCancelledError)) {
+        this.syncStatus(ctx);
+      }
+      throw err;
     }
   }
 
@@ -493,7 +526,17 @@ export class ConnectionCoordinator {
     this._ensureActive(controller.signal, serverName);
     await this.deps.authorize(serverName, ctx, controller.signal, reset);
     this._ensureActive(controller.signal, serverName);
-    await this._startAndGuardAbort(serverName, ctx, controller.signal);
+    try {
+      await this._startAndGuardAbort(serverName, ctx, controller.signal);
+    } catch (err) {
+      // WHY: Authorization can succeed and the reconnect still fail for a non-auth reason
+      // (ECONNREFUSED, timeout). lastError now names that failure, so a hint left over from
+      // the earlier decline would tell the user to authorize a server that just authorized.
+      if (!(err instanceof AuthCancelledError)) {
+        this.syncStatus(ctx);
+      }
+      throw err;
+    }
   }
 
   private async _startAndGuardAbort(

package/src/index.ts

@@ -162,8 +162,20 @@ export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string;
   manager.setRecoveryFailedCallback((serverName, error) => {
     coordinator.handleRecoveryFailed(serverName, error);
   });
+  manager.setServerReadyCallback(() => {
+    // WHY: Eager starts and background _recover() reconnects never pass through
+    // coordinator.connect(), so without this the "run /mcp:auth <name>" footer hint
+    // survives a server that has since connected cleanly.
+    coordinator.syncStatus();
+  });
   bridge.setAuthErrorCallback(async (serverName) => {
-    await manager.handleUnauthorizedServerError(serverName);
+    const authError = await manager.handleUnauthorizedServerError(serverName);
+    if (authError) {
+      // WHY: A mid-session 401/403 stops the server synchronously, which cancels the
+      // deferred _recover() that would have called onRecoveryFailed — so report the
+      // failure here or the re-auth warning and the footer hint never appear.
+      coordinator.handleRecoveryFailed(serverName, authError);
+    }
   });
 
   // ── 3. Session lifecycle ──────────────────────────────────────────────────

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 {
@@ -104,6 +106,17 @@ export type ToolRefreshCallback = (
 /** Called when background auto-recovery after a disconnect or health check fails. */
 export type RecoveryFailedCallback = (serverName: string, error: Error) => void;
 
+/**
+ * Called every time a server reaches `ready`, whether the transition came from an
+ * explicit connect, an eager startup, or background `_recover()`.
+ *
+ * WHY: Readiness is the only state change that makes a previously declined
+ * `run /mcp:auth <name>` footer hint obsolete, and eager starts plus background
+ * recovery bypass `ConnectionCoordinator.connect()`, which is where the hint is
+ * otherwise repainted.
+ */
+export type ServerReadyCallback = (serverName: string) => void;
+
 interface HandshakeParams {
   server: ManagedServer;
   client: Client;
@@ -204,6 +217,7 @@ export class ServerManager {
   private onToolRefresh: ToolRefreshCallback | null = null;
   private onServerStopped: ((name: string) => void) | null = null;
   private onRecoveryFailed: RecoveryFailedCallback | null = null;
+  private onServerReady: ServerReadyCallback | null = null;
 
   constructor(config: McpConfig, private readonly storageDir?: string) {
     this.settings = config.settings;
@@ -237,6 +251,11 @@ export class ServerManager {
     this.onRecoveryFailed = cb;
   }
 
+  /** Register callback invoked whenever a server reaches the `ready` state. */
+  setServerReadyCallback(cb: ServerReadyCallback): void {
+    this.onServerReady = cb;
+  }
+
   private _resolveTimeoutMs(server: ManagedServer): number {
     return server.config.requestTimeoutMs ?? this.settings.requestTimeoutMs;
   }
@@ -333,11 +352,29 @@ export class ServerManager {
   /**
     * Mark an OAuth server as requiring re-authorization when a mid-session
     * request (tools/list or tools/call) fails with 401/403 insufficient_scope.
+    *
+    * Returns the {@link AuthRequiredError} when a server that was already `ready`
+    * lost its credentials mid-session, and `undefined` otherwise (unknown server,
+    * non-OAuth server, or a server that is not `ready` — see below).
+    *
+    * Only a `ready` server is handled here. For any other state this is a no-op and
+    * must NOT touch the server: a 401/403 during a connect attempt (`initialize` ok,
+    * `tools/list` 401 while `starting`) arrives while that attempt owns the
+    * lifecycle, and shutting the server down here would abort the attempt's own
+    * signal. `classifyConnectFailure` then sees `aborted` first and reports
+    * `AuthCancelledError` instead of `auth-required`, which suppresses the startup
+    * auth prompt, the interactive authorization, and the recovery failure alike.
+    * Left alone, the attempt's `_raiseAuthRequired` invalidates the tokens, records
+    * the `AuthRequiredError`, and reports it exactly once.
     */
-  async handleUnauthorizedServerError(name: string): Promise<void> {
+  async handleUnauthorizedServerError(name: string): Promise<AuthRequiredError | undefined> {
     const server = this.servers.get(name);
     if (!server || !server.config.auth || server.config.transport === "stdio") {
-      return;
+      return undefined;
+    }
+    if (server.state !== "ready") {
+      // WHY: See the JSDoc above — an in-flight connect attempt reports its own 401.
+      return undefined;
     }
     const authError = new AuthRequiredError(name);
     // WHY: Shut down immediately before async disk I/O so server.generation increments
@@ -346,6 +383,7 @@ export class ServerManager {
     server.lastError = authError;
     await invalidateStoredTokens(name, this.storageDir, server.config.url);
     server.lastError = authError;
+    return authError;
   }
 
   /** Get recent stderr output for a server. */
@@ -555,30 +593,9 @@ export class ServerManager {
     );
 
     // tools/list_changed: re-discover tools and update Pi registrations
-    client.setNotificationHandler(
-      ToolListChangedNotificationSchema,
-      async () => {
-        if (!signal.aborted && this.onToolRefresh && server.state === "ready" && server.client === client) {
-          try {
-            const refreshTimeoutMs = this._resolveTimeoutMs(server);
-            await this.onToolRefresh(server.name, server.client, {
-              requestTimeoutMs: refreshTimeoutMs,
-              signal,
-            });
-          } catch (err) {
-            const { kind, message } = describeError(err);
-            reportDiagnostic({
-              level: "error",
-              event: "server.tools_refresh_failed",
-              server: server.name,
-              message: `Failed to refresh tools for ${server.name}: ${message}`,
-              fields: { kind },
-              notify: true,
-            });
-          }
-        }
-      },
-    );
+    client.setNotificationHandler(ToolListChangedNotificationSchema, async () => {
+      await this._handleToolListChanged(server, client, signal);
+    });
 
     // notifications/message: structured logging from MCP servers
     client.setNotificationHandler(
@@ -606,6 +623,48 @@ export class ServerManager {
     return client;
   }
 
+  /**
+   * Re-discover tools after a `notifications/tools/list_changed` from a ready server.
+   *
+   * Extracted from the notification handler so the handler registration stays a single
+   * guarded call.
+   */
+  private async _handleToolListChanged(
+    server: ManagedServer,
+    client: Client,
+    signal: AbortSignal,
+  ): Promise<void> {
+    const onToolRefresh = this.onToolRefresh;
+    if (signal.aborted || !onToolRefresh || server.state !== "ready" || server.client !== client) {
+      return;
+    }
+    try {
+      const refreshTimeoutMs = this._resolveTimeoutMs(server);
+      await onToolRefresh(server.name, server.client, {
+        requestTimeoutMs: refreshTimeoutMs,
+        signal,
+      });
+    } catch (err) {
+      const { kind, message } = describeError(err);
+      // WHY: Two failures here are already accounted for and must not toast: a cancelled
+      // refresh (/mcp:stop, session teardown) is expected, and a 401/403 was just reported
+      // by handleUnauthorizedServerError as a re-authorization warning plus the footer hint
+      // — a second "Failed to refresh tools" error would read as an unrelated problem.
+      const alreadyReported =
+        err instanceof AuthCancelledError ||
+        signal.aborted ||
+        server.lastError instanceof AuthRequiredError;
+      reportDiagnostic({
+        level: alreadyReported ? "info" : "error",
+        event: "server.tools_refresh_failed",
+        server: server.name,
+        message: `Failed to refresh tools for ${server.name}: ${message}`,
+        fields: { kind },
+        notify: !alreadyReported,
+      });
+    }
+  }
+
   private async _handshakeAndDiscover(params: HandshakeParams): Promise<void> {
     const { server, client, transport, timeoutMs, signal, currentCwd } = params;
     await this._connectWithTimeoutAndSignal(client, transport, timeoutMs, signal, server.name);
@@ -624,6 +683,9 @@ export class ServerManager {
     this._setState(server, "ready");
     server.retryCount = 0;
     server.lastError = null;
+    // WHY: Fire only after the server is observably ready with a cleared lastError, so a
+    // listener that repaints session state never sees a half-transitioned server.
+    this.onServerReady?.(server.name);
     if (server.cwd && server.cwd !== currentCwd) {
       void client.sendRootsListChanged().catch(() => {
         // WHY: Best-effort notification if cwd was updated while handshake was in flight.
@@ -827,6 +889,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 +921,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 +1163,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);
 }
-