@oh-my-pi/pi-coding-agent 17.0.1 → 17.0.3

package/src/mcp/transports/stdio.test.ts

@@ -1,6 +1,9 @@
 import { describe, expect, it, spyOn } from "bun:test";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
 
-import { resolveStdioSpawnCommand, StdioTransport } from "./stdio";
+import { resolveStdioSpawnCommand, StdioTransport, terminateStdioProcess } from "./stdio";
 
 describe("resolveStdioSpawnCommand", () => {
 	it("hides Windows executable MCP servers when the host has no console", async () => {
@@ -149,3 +152,268 @@ describe.skipIf(process.platform === "win32")("StdioTransport request write stal
 		}
 	}, 8000);
 });
+
+function processExists(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+// Regression for #5578: `close()` used a bare `this.#process.kill()` (direct
+// SIGTERM, no wait, no escalate, no process-group signal), so a detached
+// session-leader child (or a grandchild it spawned) that ignores/traps
+// SIGTERM survived host exit and became an orphan pinned to PID 1 on Linux.
+// `sleep`/`bun`/POSIX signal semantics are exercised directly here rather
+// than through `StdioTransport.connect()`, because `connect()` derives
+// `detached` from `resolveStdioSpawnCommand()`, which is tied to the host's
+// real `process.platform` — a POSIX detached session cannot be reproduced
+// end-to-end through `connect()` on a non-Linux dev/CI host, but a real
+// detached process group can still be spawned directly on any POSIX host.
+describe.skipIf(process.platform === "win32")("terminateStdioProcess", () => {
+	it("escalates a detached child that traps SIGTERM to SIGKILL", async () => {
+		const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "omp-stdio-kill-solo-"));
+		const scriptPath = path.join(tempDir, "child.mjs");
+		const readyPath = path.join(tempDir, "ready");
+		await fs.writeFile(
+			scriptPath,
+			[
+				"import { writeFileSync } from 'node:fs';",
+				"process.on('SIGTERM', () => {});",
+				`writeFileSync(${JSON.stringify(readyPath)}, '1');`,
+				"setInterval(() => {}, 60_000);",
+			].join("\n"),
+		);
+		const proc = Bun.spawn(["bun", "run", scriptPath], {
+			stdin: "ignore",
+			stdout: "ignore",
+			stderr: "ignore",
+			detached: true,
+		});
+		try {
+			// Wait for the child to actually register its SIGTERM handler before
+			// signaling it: signaling too early races the child's startup and
+			// hits the default (terminate) action instead of exercising the trap.
+			for (let i = 0; i < 100; i++) {
+				try {
+					await fs.access(readyPath);
+					break;
+				} catch {
+					await Bun.sleep(20);
+				}
+			}
+
+			const started = performance.now();
+			await terminateStdioProcess(proc, true);
+			await proc.exited;
+			const elapsedMs = performance.now() - started;
+
+			expect(proc.signalCode).toBe("SIGKILL");
+			// Escalation only fires after the ~1s SIGTERM grace window elapses —
+			// a too-fast exit would mean SIGKILL fired without waiting.
+			expect(elapsedMs).toBeGreaterThanOrEqual(900);
+		} finally {
+			try {
+				process.kill(-proc.pid, "SIGKILL");
+			} catch {
+				// Already gone.
+			}
+			await fs.rm(tempDir, { recursive: true, force: true });
+		}
+	}, 5000);
+
+	it("reaches a SIGTERM-trapping grandchild through the group SIGKILL, not just the direct child", async () => {
+		const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "omp-stdio-group-kill-"));
+		const grandchildScriptPath = path.join(tempDir, "grandchild.mjs");
+		const parentScriptPath = path.join(tempDir, "parent.mjs");
+		const grandchildPidPath = path.join(tempDir, "grandchild.pid");
+
+		// Grandchild also traps SIGTERM, so only an unrestricted SIGKILL to the
+		// whole group — not a signal to the direct (parent) child alone — can
+		// reach and stop it.
+		await fs.writeFile(
+			grandchildScriptPath,
+			[
+				"import { writeFileSync } from 'node:fs';",
+				"process.on('SIGTERM', () => {});",
+				`writeFileSync(${JSON.stringify(grandchildPidPath)}, String(process.pid));`,
+				"setInterval(() => {}, 60_000);",
+			].join("\n"),
+		);
+		await fs.writeFile(
+			parentScriptPath,
+			[
+				"process.on('SIGTERM', () => {});",
+				`Bun.spawn(["bun", "run", ${JSON.stringify(grandchildScriptPath)}], { stdout: "ignore", stderr: "ignore", stdin: "ignore" });`,
+				"setInterval(() => {}, 60_000);",
+			].join("\n"),
+		);
+
+		const proc = Bun.spawn(["bun", "run", parentScriptPath], {
+			stdin: "ignore",
+			stdout: "ignore",
+			stderr: "ignore",
+			detached: true,
+		});
+
+		try {
+			// Polls real wall-clock time rather than an event/promise: the
+			// grandchild process is a real external OS process writing to a real
+			// file, with no in-process signal this test can `await` directly.
+			let grandchildPid: number | undefined;
+			for (let i = 0; i < 100 && grandchildPid === undefined; i++) {
+				try {
+					grandchildPid = Number.parseInt(await fs.readFile(grandchildPidPath, "utf8"), 10);
+				} catch {
+					await Bun.sleep(20);
+				}
+			}
+			if (grandchildPid === undefined) throw new Error("grandchild never reported its pid");
+			expect(processExists(grandchildPid)).toBe(true);
+
+			await terminateStdioProcess(proc, true);
+			await proc.exited;
+			expect(proc.signalCode).toBe("SIGKILL");
+
+			// The group SIGKILL is delivered to every member simultaneously, but
+			// give the kernel a brief window to finish reaping before asserting.
+			let grandchildAlive = processExists(grandchildPid);
+			for (let i = 0; i < 25 && grandchildAlive; i++) {
+				await Bun.sleep(20);
+				grandchildAlive = processExists(grandchildPid);
+			}
+			expect(grandchildAlive).toBe(false);
+		} finally {
+			try {
+				process.kill(-proc.pid, "SIGKILL");
+			} catch {
+				// Already gone.
+			}
+			await fs.rm(tempDir, { recursive: true, force: true });
+		}
+	}, 8000);
+
+	it("still reaps a SIGTERM-trapping grandchild after the detached leader exits cooperatively", async () => {
+		// Regression: the leader exiting within the SIGTERM grace window used to
+		// be treated as proof the whole process group was gone, so `close()`
+		// returned early and never delivered a group SIGKILL — leaving exactly
+		// the orphaned grandchild this change is meant to reap. Unlike the
+		// group-SIGKILL test above, the leader here does NOT trap SIGTERM, so
+		// it exits promptly on its own; only the grandchild ignores signals.
+		const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "omp-stdio-leader-exit-group-kill-"));
+		const grandchildScriptPath = path.join(tempDir, "grandchild.mjs");
+		const parentScriptPath = path.join(tempDir, "parent.mjs");
+		const grandchildPidPath = path.join(tempDir, "grandchild.pid");
+
+		await fs.writeFile(
+			grandchildScriptPath,
+			[
+				"import { writeFileSync } from 'node:fs';",
+				"process.on('SIGTERM', () => {});",
+				`writeFileSync(${JSON.stringify(grandchildPidPath)}, String(process.pid));`,
+				"setInterval(() => {}, 60_000);",
+			].join("\n"),
+		);
+		// No SIGTERM handler here: the default action (terminate) fires as soon
+		// as the group SIGTERM lands, well inside TERM_GRACE_MS.
+		await fs.writeFile(
+			parentScriptPath,
+			[
+				`Bun.spawn(["bun", "run", ${JSON.stringify(grandchildScriptPath)}], { stdout: "ignore", stderr: "ignore", stdin: "ignore" });`,
+				"setInterval(() => {}, 60_000);",
+			].join("\n"),
+		);
+
+		const proc = Bun.spawn(["bun", "run", parentScriptPath], {
+			stdin: "ignore",
+			stdout: "ignore",
+			stderr: "ignore",
+			detached: true,
+		});
+
+		try {
+			let grandchildPid: number | undefined;
+			for (let i = 0; i < 100 && grandchildPid === undefined; i++) {
+				try {
+					grandchildPid = Number.parseInt(await fs.readFile(grandchildPidPath, "utf8"), 10);
+				} catch {
+					await Bun.sleep(20);
+				}
+			}
+			if (grandchildPid === undefined) throw new Error("grandchild never reported its pid");
+			expect(processExists(grandchildPid)).toBe(true);
+
+			const started = performance.now();
+			await terminateStdioProcess(proc, true);
+			await proc.exited;
+			const elapsedMs = performance.now() - started;
+
+			// The leader exits on the initial SIGTERM (no trap), so this must not
+			// block for the ~1s TERM grace window before sweeping the group.
+			expect(elapsedMs).toBeLessThan(700);
+
+			let grandchildAlive = processExists(grandchildPid);
+			for (let i = 0; i < 25 && grandchildAlive; i++) {
+				await Bun.sleep(20);
+				grandchildAlive = processExists(grandchildPid);
+			}
+			expect(grandchildAlive).toBe(false);
+		} finally {
+			try {
+				process.kill(-proc.pid, "SIGKILL");
+			} catch {
+				// Already gone.
+			}
+			await fs.rm(tempDir, { recursive: true, force: true });
+		}
+	}, 8000);
+
+	it("never attempts a process-group signal when the transport did not spawn detached", async () => {
+		const proc = Bun.spawn(["bun", "-e", "await Bun.sleep(60_000)"], {
+			stdin: "ignore",
+			stdout: "ignore",
+			stderr: "ignore",
+			detached: false,
+		});
+		const killSpy = spyOn(process, "kill");
+		try {
+			await terminateStdioProcess(proc, false);
+			await proc.exited;
+
+			// Only the direct-child `Subprocess.kill()` path may run; the global
+			// `process.kill()` (used exclusively for the negative-pid group
+			// signal) must never be reached.
+			expect(killSpy).not.toHaveBeenCalled();
+		} finally {
+			killSpy.mockRestore();
+			try {
+				proc.kill("SIGKILL");
+			} catch {
+				// Already gone.
+			}
+		}
+	}, 5000);
+});
+
+describe.skipIf(process.platform === "win32")("StdioTransport.close teardown", () => {
+	it("closes a well-behaved child promptly without escalating to SIGKILL", async () => {
+		const transport = new StdioTransport({
+			command: "bun",
+			args: ["-e", "await Bun.sleep(60_000)"],
+		});
+		try {
+			await transport.connect();
+			const started = performance.now();
+			await transport.close();
+			const elapsedMs = performance.now() - started;
+
+			// No SIGTERM trap => the child dies almost immediately; close() must
+			// not block for the full ~1s TERM grace window before returning.
+			expect(elapsedMs).toBeLessThan(700);
+		} finally {
+			await transport.close();
+		}
+	}, 5000);
+});

package/src/mcp/transports/stdio.ts

@@ -54,6 +54,18 @@ export interface StdioSpawnCommand {
 	 * grandchildren keep stdout routed through our pipe (#3544).
 	 */
 	detached: boolean;
+	/**
+	 * Pass argv to `Bun.spawn` verbatim (Windows only), suppressing the
+	 * default libuv backslash-quoting.
+	 *
+	 * Set when `cmd` already holds a `cmd.exe /d /e:ON /v:OFF /c "<line>"`
+	 * command line escaped for `cmd.exe`'s parser (see `buildCmdExeArgv`).
+	 * libuv's quoting targets `CommandLineToArgvW`, not `cmd.exe`, so letting
+	 * it re-quote a batch launch would corrupt arguments and re-open the
+	 * `%VAR%` / quote-injection holes the escaping closes (BatBadBut,
+	 * CVE-2024-24576).
+	 */
+	windowsVerbatimArguments?: boolean;
 }
 
 /** Inputs used to resolve platform-specific stdio spawn behavior. */
@@ -203,23 +215,6 @@ async function resolveWindowsNpmShimCommand(
 	};
 }
 
-function quoteCmdArg(value: string): string {
-	if (value.length === 0) return '""';
-	let result = '"';
-	for (const char of value) {
-		if (char === '"') {
-			result += '^"';
-		} else if (char === "^") {
-			result += "^^";
-		} else if (char === "%") {
-			result += "^%";
-		} else {
-			result += char;
-		}
-	}
-	return `${result}"`;
-}
-
 function isWindowsBatchCommand(command: string): boolean {
 	return WINDOWS_BATCH_EXTENSIONS.has(path.extname(command).toLowerCase());
 }
@@ -229,10 +224,93 @@ function resolveComSpec(env: Record<string, string | undefined>): string {
 	return comspec && comspec.length > 0 ? comspec : "cmd.exe";
 }
 
-/** `cmd /s /c` strips one outer quote pair; keep inner argv quotes intact. */
-function buildCmdExeCommand(command: string, args: readonly string[]): string {
-	const quotedCommand = [command, ...args].map(quoteCmdArg).join(" ");
-	return `"${quotedCommand}"`;
+// Argument bytes cmd.exe delivers unchanged without quoting. Anything outside
+// this set (spaces, quotes, `%`, shell metacharacters, non-ASCII) forces the
+// quoted+escaped path below. Mirrors the fuzz-tested allow-list from Zig's
+// BatBadBut mitigation.
+const CMD_SAFE_ARG = /^[A-Za-z0-9#$*+\-./:?@\\_]+$/;
+
+/**
+ * Escape the interior of a `cmd.exe`-quoted token: neutralize `%VAR%` expansion
+ * and double any backslash run that precedes a quote (including the caller's
+ * closing quote) so `CommandLineToArgvW` delivers the backslashes literally.
+ *
+ * `cmd.exe` re-parses the whole `/c` string and expands `%…%` *before* the
+ * batch shim's own argv split runs, so both the command path and every argument
+ * must pass through this. Percent → `%%cd:~,%` (which expands to nothing,
+ * leaving a literal `%`) and `"` → `""` are the documented BatBadBut mitigation
+ * (CVE-2024-24576). The caller supplies the surrounding double quotes.
+ *
+ * @see https://flatt.tech/research/posts/batbadbut-you-cant-securely-execute-commands-on-windows/
+ */
+function escapeCmdQuotedInterior(value: string): string {
+	let out = "";
+	let backslashes = 0;
+	for (const ch of value) {
+		if (ch === "\\") {
+			backslashes += 1;
+			out += ch;
+		} else if (ch === '"') {
+			out += "\\".repeat(backslashes);
+			out += '""';
+			backslashes = 0;
+		} else if (ch === "%") {
+			out += "%%cd:~,%";
+			backslashes = 0;
+		} else {
+			backslashes = 0;
+			out += ch;
+		}
+	}
+	// Double the trailing backslash run so it stays literal before the closing
+	// quote the caller appends.
+	out += "\\".repeat(backslashes);
+	return out;
+}
+
+/** Reject bytes that cannot round-trip through `cmd.exe`'s `/c` command line. */
+function assertCmdBatchToken(value: string, kind: "command" | "argument"): void {
+	// NUL/LF act as an end-of-command marker and CR is stripped, so any of them
+	// would silently truncate or corrupt the launch.
+	if (/[\0\r\n]/.test(value)) {
+		throw new Error(`Windows batch MCP ${kind} cannot contain NUL, CR, or LF characters`);
+	}
+}
+
+/**
+ * Escape one argument for `cmd.exe`'s command-line pre-parse so a `.cmd`/`.bat`
+ * shim receives it verbatim. Quotes only when the argument is empty, ends in a
+ * backslash, or holds a byte outside {@link CMD_SAFE_ARG}; the quoted body is
+ * escaped by {@link escapeCmdQuotedInterior}.
+ *
+ * @throws when the argument contains NUL, CR, or LF (see {@link assertCmdBatchToken}).
+ */
+function escapeCmdBatchArg(arg: string): string {
+	assertCmdBatchToken(arg, "argument");
+	const needsQuotes = arg.length === 0 || arg.endsWith("\\") || !CMD_SAFE_ARG.test(arg);
+	// An unquoted arg is pure allow-list bytes (no `%`, `"`, or trailing `\`), so
+	// it needs no interior escaping.
+	return needsQuotes ? `"${escapeCmdQuotedInterior(arg)}"` : arg;
+}
+
+/**
+ * Build the `cmd.exe` argv for a Windows `.cmd`/`.bat` (or unresolved bare)
+ * MCP command.
+ *
+ * The trailing element is a single `/c` string wrapped in an outer quote pair
+ * that `cmd.exe` strips (its opening-quote rule). The command token is always
+ * quoted and, like every argument, escaped so a `%` in the resolved path (e.g.
+ * `C:\work\%TOKEN%\server.cmd`) is not expanded before the shim launches.
+ * `/e:ON` keeps command extensions on (required for the `%%cd:~,%` trick) and
+ * `/v:OFF` disables delayed expansion. The result MUST be spawned with
+ * `windowsVerbatimArguments` so libuv passes it through unmodified.
+ */
+function buildCmdExeArgv(comspec: string, command: string, args: readonly string[]): string[] {
+	assertCmdBatchToken(command, "command");
+	let line = `""${escapeCmdQuotedInterior(command)}"`;
+	for (const arg of args) line += ` ${escapeCmdBatchArg(arg)}`;
+	line += '"';
+	return [comspec, "/d", "/e:ON", "/v:OFF", "/c", line];
 }
 
 /**
@@ -245,7 +323,7 @@ function buildCmdExeCommand(command: string, args: readonly string[]): string {
  * only appends `.exe` for extensionless names — `.cmd`/`.bat` are never
  * tried, so `npx` (which exists only as `npx.cmd` on Windows) crashes the
  * subprocess immediately. When the resolver can't pin the command down,
- * route through `cmd.exe /d /s /c` so Windows's own PATHEXT lookup runs.
+ * route through `cmd.exe` so Windows's own PATHEXT lookup runs.
  */
 export async function resolveStdioSpawnCommand(
 	config: MCPStdioServerConfig,
@@ -271,9 +349,10 @@ export async function resolveStdioSpawnCommand(
 	if (!needsCmdExe) return { cmd: [resolvedCommand, ...args], windowsHide, detached };
 
 	return {
-		cmd: [resolveComSpec(options.env), "/d", "/s", "/c", buildCmdExeCommand(resolvedCommand, args)],
+		cmd: buildCmdExeArgv(resolveComSpec(options.env), resolvedCommand, args),
 		windowsHide,
 		detached,
+		windowsVerbatimArguments: true,
 	};
 }
 
@@ -325,6 +404,132 @@ export function writeFrame(stdin: FrameSink, frame: string): boolean {
 	}
 }
 
+/** Grace window to observe a cooperative exit after SIGTERM before escalating to SIGKILL. */
+const TERM_GRACE_MS = 1000;
+/** Grace window to observe SIGKILL taking effect before `close()` gives up and returns. */
+const KILL_GRACE_MS = 500;
+
+/**
+ * The subset of `Subprocess` that termination needs. Decoupled from the
+ * `Subprocess<In, Out, Err>` stdio generics — `#process`'s pipes are
+ * irrelevant to signaling — so tests can exercise it against a plain
+ * `Bun.spawn(cmd, { stdio: "ignore" })` child without fighting the generics.
+ */
+interface KillableSubprocess {
+	readonly pid: number;
+	readonly exited: Promise<number>;
+	kill(signal?: number | NodeJS.Signals): void;
+}
+
+/**
+ * Race `exited` against a timer. Resolves `true` once the process has exited
+ * within `timeoutMs`, `false` if the timer wins first. `exited` resolving OR
+ * rejecting both count as "exited" — mirrors `waitForExit()` in
+ * `lsp/client.ts`, which treats the same ambiguity (Bun documents
+ * `Subprocess.exited` as resolve-only, but a settle either way means there is
+ * nothing left to wait on).
+ *
+ * The timer is always cleared before returning — win or lose — so a process
+ * that exits promptly never leaves a dangling `timeoutMs` timer holding the
+ * event loop open behind it.
+ */
+async function waitForProcessExit(exited: Promise<number>, timeoutMs: number): Promise<boolean> {
+	const { promise: timedOut, resolve: resolveTimedOut } = Promise.withResolvers<false>();
+	const timer = setTimeout(() => resolveTimedOut(false), timeoutMs);
+	try {
+		return await Promise.race([
+			exited.then(
+				() => true,
+				() => true,
+			),
+			timedOut,
+		]);
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
+/** `true` when `error` is a Node errno exception carrying the given `code`. */
+function isErrnoCode(error: unknown, code: string): boolean {
+	if (typeof error !== "object" || error === null || !("code" in error)) return false;
+	return error.code === code;
+}
+
+/**
+ * Signal `signal` to `proc`. When `detached` is true on a POSIX platform,
+ * targets the whole process group via the negative-pid convention
+ * (`process.kill(-pid, signal)`) so a detached session leader's descendants —
+ * not just the direct child — receive it too; a bare direct-child signal
+ * never reaches grandchildren the child itself spawned.
+ *
+ * `ESRCH` from the group signal means the group is already gone — that is a
+ * success (nothing left to signal), not a failure — so it does not fall
+ * through. Any other group-signal failure (e.g. `EPERM`) falls back to
+ * signaling the direct child as a last resort. Non-detached transports
+ * (macOS, Windows, or POSIX where detach did not apply) always signal the
+ * direct child only: a negative-pid signal outside a detached session could
+ * hit an unrelated process group.
+ */
+function signalStdioProcess(
+	proc: KillableSubprocess,
+	detached: boolean,
+	signal: NodeJS.Signals,
+	platform: NodeJS.Platform,
+): void {
+	if (detached && platform !== "win32") {
+		try {
+			process.kill(-proc.pid, signal);
+			return;
+		} catch (error) {
+			if (isErrnoCode(error, "ESRCH")) return;
+			// Fall through to the direct-child signal below.
+		}
+	}
+	try {
+		proc.kill(signal);
+	} catch {
+		// Already gone.
+	}
+}
+
+/**
+ * Terminate an MCP stdio subprocess: SIGTERM (process-group when `detached`
+ * on POSIX, direct child otherwise), wait up to `TERM_GRACE_MS` for a
+ * cooperative exit, then escalate to SIGKILL — waiting up to `KILL_GRACE_MS`
+ * more only when the leader itself hadn't already exited. A detached
+ * leader's cooperative exit does not prove the whole process group is gone
+ * (a grandchild can outlive it and ignore SIGTERM), so detached transports
+ * always fire the group SIGKILL sweep, even after a clean SIGTERM exit.
+ * Every step is a no-op-safe signal against an already-exited target, so
+ * repeat calls (idempotent `close()`) never throw.
+ *
+ * Exported so tests can exercise group-signal escalation with an explicit
+ * `detached`/`platform` pair: `StdioTransport.connect()` derives `detached`
+ * from `resolveStdioSpawnCommand()`, which is tied to the host's real
+ * `process.platform`, so a POSIX detached session cannot be reproduced
+ * end-to-end through `connect()` on a non-Linux dev/CI host.
+ */
+export async function terminateStdioProcess(
+	proc: KillableSubprocess,
+	detached: boolean,
+	platform: NodeJS.Platform = process.platform,
+): Promise<void> {
+	signalStdioProcess(proc, detached, "SIGTERM", platform);
+	const exitedOnTerm = await waitForProcessExit(proc.exited, TERM_GRACE_MS);
+	// A non-detached transport has no process group beyond the leader itself:
+	// once it exits, there is nothing left to signal. A detached transport's
+	// leader exiting is NOT proof the group is empty — a grandchild it spawned
+	// can still be alive and ignoring SIGTERM — so detached transports always
+	// fall through to the group SIGKILL, even on a cooperative leader exit.
+	if (exitedOnTerm && !detached) return;
+	signalStdioProcess(proc, detached, "SIGKILL", platform);
+	// Once the leader has already exited there is no further `exited` signal
+	// to wait on for this call — the SIGKILL above is a fire-and-forget sweep
+	// for any surviving group members — so only block on the grace window
+	// when the leader itself is still the thing being escalated against.
+	if (!exitedOnTerm) await waitForProcessExit(proc.exited, KILL_GRACE_MS);
+}
+
 /**
  * Stdio transport for MCP servers.
  * Spawns a subprocess and communicates via stdin/stdout.
@@ -340,6 +545,12 @@ export class StdioTransport implements MCPTransport {
 	>();
 	#connected = false;
 	#readLoop: Promise<void> | null = null;
+	/**
+	 * Set from `resolveStdioSpawnCommand()`'s `detached` flag in `connect()`.
+	 * Gates process-group signaling in `close()` — only a transport that
+	 * actually spawned into its own session may target it.
+	 */
+	#detached = false;
 
 	onClose?: () => void;
 	onError?: (error: Error) => void;
@@ -388,7 +599,9 @@ export class StdioTransport implements MCPTransport {
 			stderr: "pipe",
 			windowsHide: spawnCommand.windowsHide,
 			detached: spawnCommand.detached,
+			windowsVerbatimArguments: spawnCommand.windowsVerbatimArguments,
 		});
+		this.#detached = spawnCommand.detached;
 
 		this.#connected = true;
 
@@ -650,8 +863,26 @@ export class StdioTransport implements MCPTransport {
 		}
 
 		if (this.#process) {
-			this.#process.kill();
+			// Grab the handle and null the field immediately (before any
+			// `await`) so a concurrent/repeat `close()` sees `#process` already
+			// cleared and skips straight past this block — no double-signal.
+			const proc = this.#process;
 			this.#process = null;
+
+			// 1. Cooperative EOF first: a well-behaved server sees stdin close
+			// and can exit on its own before any signal is sent. Guarded — the
+			// sink can throw if the pipe is already closed/dead (e.g. the child
+			// already exited and the read loop got there first).
+			try {
+				proc.stdin.end();
+			} catch {
+				// Already closed/dead.
+			}
+
+			// 2-3. Group-aware SIGTERM (when this transport actually spawned
+			// detached), bounded wait, then escalate to SIGKILL. See
+			// `terminateStdioProcess` for the exact signaling/escalation rules.
+			await terminateStdioProcess(proc, this.#detached);
 		}
 
 		if (this.#readLoop) {