@oh-my-pi/pi-coding-agent 17.0.0 → 17.0.2

package/src/internal-urls/__tests__/agent-protocol-nested.test.ts

@@ -66,3 +66,76 @@ it("agent:// resolves a depth-2 subagent's .md output while its session is live
 	const resource = await new AgentProtocolHandler().resolve(new URL(`agent://${grandchildId}`) as never);
 	expect(resource.content).toBe("full report content");
 });
+
+it("agent:// slash form resolves a nested subagent child (hierarchy separator)", async () => {
+	const root = tempDir.path();
+	const rootSessionFile = path.join(root, "slash-session.jsonl");
+	const rootArtifactsDir = rootSessionFile.slice(0, -6);
+	await fs.mkdir(rootArtifactsDir, { recursive: true });
+	const sharedArtifactManager = new ArtifactManager(rootArtifactsDir);
+
+	// Parent subagent adopts the root ArtifactManager; its own children are
+	// written one level deeper under its sessionFile-derived dir, dot-qualified.
+	const parentSessionFile = path.join(rootArtifactsDir, "Parent.jsonl");
+	const parentOwnDir = parentSessionFile.slice(0, -6);
+	await fs.mkdir(parentOwnDir, { recursive: true });
+	await fs.writeFile(path.join(parentOwnDir, "Parent.Child.md"), "child capsule");
+	// Parent output may be in the root dir; the nested child must still win.
+	await fs.writeFile(path.join(rootArtifactsDir, "Parent.md"), JSON.stringify({ Child: "wrong base output" }));
+
+	const fakeSession = {
+		sessionManager: { getArtifactsDir: () => sharedArtifactManager.dir },
+	} as unknown as AgentSession;
+	const registry = AgentRegistry.global();
+	registry.register({
+		id: "Main",
+		displayName: "main",
+		kind: "main",
+		session: fakeSession,
+		sessionFile: rootSessionFile,
+	});
+	registry.register({
+		id: "Parent",
+		displayName: "sub",
+		kind: "sub",
+		parentId: "Main",
+		session: fakeSession,
+		sessionFile: parentSessionFile,
+	});
+
+	const handler = new AgentProtocolHandler();
+	// Slash form is a hierarchy hop, not a jq extraction.
+	const slash = await handler.resolve(new URL("agent://Parent/Child") as never);
+	expect(slash.content).toBe("child capsule");
+	expect(slash.contentType).toBe("text/markdown");
+	// The canonical dotted id resolves to the same output.
+	const dotted = await handler.resolve(new URL("agent://Parent.Child") as never);
+	expect(dotted.content).toBe("child capsule");
+});
+
+it("agent:// path form falls back to JSON extraction when no nested output matches", async () => {
+	const root = tempDir.path();
+	const rootSessionFile = path.join(root, "json-session.jsonl");
+	const rootArtifactsDir = rootSessionFile.slice(0, -6);
+	await fs.mkdir(rootArtifactsDir, { recursive: true });
+	const sharedArtifactManager = new ArtifactManager(rootArtifactsDir);
+	await fs.writeFile(path.join(rootArtifactsDir, "Worker.md"), JSON.stringify({ result: { ok: true } }));
+
+	const fakeSession = {
+		sessionManager: { getArtifactsDir: () => sharedArtifactManager.dir },
+	} as unknown as AgentSession;
+	const registry = AgentRegistry.global();
+	registry.register({
+		id: "Main",
+		displayName: "main",
+		kind: "main",
+		session: fakeSession,
+		sessionFile: rootSessionFile,
+	});
+
+	const handler = new AgentProtocolHandler();
+	// `result` names no nested output, so the path extracts JSON from Worker.md.
+	const extracted = await handler.resolve(new URL("agent://Worker/result") as never);
+	expect(extracted.contentType).toBe("application/json");
+	expect(JSON.parse(extracted.content)).toEqual({ ok: true });
+});

package/src/internal-urls/agent-protocol.ts

@@ -8,7 +8,11 @@
  *
  * URL forms:
  * - agent://<id> - Full output content
- * - agent://<id>/<path> - JSON extraction via path form
+ * - agent://<id>/<child> - Nested subagent output (hierarchy separator; the
+ *   registry allocates a subagent's own children as dot-qualified ids, so
+ *   `agent://Parent/Child` resolves `Parent.Child.md`)
+ * - agent://<id>/<path> - JSON extraction via path form (fallback when no
+ *   nested output matches the path)
  * - agent://<id>?q=<query> - JSON extraction via query form
  */
 import * as fs from "node:fs/promises";
@@ -44,65 +48,56 @@ export class AgentProtocolHandler implements ProtocolHandler {
 		}
 
 		const dirs = artifactsDirsFromRegistry();
-
 		if (dirs.length === 0) {
 			throw new Error("No session - agent outputs unavailable");
 		}
 
-		let foundPath: string | undefined;
-		let anyDirExists = false;
-		const availableIds = new Set<string>();
-
-		for (const dir of dirs) {
-			try {
-				await fs.stat(dir);
-				anyDirExists = true;
-			} catch (err) {
-				if (isEnoent(err)) continue;
-				throw err;
-			}
-			const candidate = path.join(dir, `${outputId}.md`);
+		// A subagent allocates its own children as dot-qualified ids
+		// (`Parent.Child`), so the slash path form is first tried as a hierarchy
+		// separator: `agent://Parent/Child` resolves `Parent.Child.md`. Only when
+		// no such nested output exists does the path fall back to jq-style JSON
+		// extraction on `<outputId>.md`. Query form (`?q=`) is always extraction.
+		const pathSegments = hasPathExtraction ? urlPath.split("/").filter(Boolean) : [];
+		const decodedSegments = pathSegments.map(segment => {
 			try {
-				await fs.stat(candidate);
-				foundPath = candidate;
-				break;
-			} catch (err) {
-				if (!isEnoent(err)) throw err;
-				try {
-					const files = await fs.readdir(dir);
-					for (const f of files) {
-						if (f.endsWith(".md")) availableIds.add(f.replace(/\.md$/, ""));
-					}
-				} catch {
-					// Listing failures are non-fatal; continue searching.
-				}
+				return decodeURIComponent(segment);
+			} catch {
+				return segment;
 			}
-		}
+		});
+		const nestedId =
+			decodedSegments.length > 0 && decodedSegments.every(segment => !segment.includes("."))
+				? [outputId, ...decodedSegments].join(".")
+				: undefined;
 
-		if (!anyDirExists) {
+		const scan = await this.#findOutput(dirs, nestedId ? [nestedId, outputId] : [outputId]);
+		if (!scan.anyDirExists) {
 			throw new Error("No artifacts directory found");
 		}
-
-		if (!foundPath) {
-			const availableStr = availableIds.size > 0 ? [...availableIds].join(", ") : "none";
-			throw new Error(`Not found: ${outputId}\nAvailable: ${availableStr}`);
+		if (!scan.foundPath) {
+			const target = nestedId ?? outputId;
+			const availableStr = scan.availableIds.size > 0 ? [...scan.availableIds].join(", ") : "none";
+			throw new Error(`Not found: ${target}\nAvailable: ${availableStr}`);
 		}
 
-		const rawContent = await Bun.file(foundPath).text();
+		const rawContent = await Bun.file(scan.foundPath).text();
 		const notes: string[] = [];
 		let content = rawContent;
 		let contentType: InternalResource["contentType"] = "text/markdown";
 
-		if (hasPathExtraction || hasQueryExtraction) {
+		// Extraction applies only when the URL did NOT resolve to a nested output
+		// (a slash that named a real child is a hierarchy hop, not a jq path).
+		const extract = hasQueryExtraction || (hasPathExtraction && scan.matchedId !== nestedId);
+		if (extract) {
 			let jsonValue: unknown;
 			try {
 				jsonValue = JSON.parse(rawContent);
 			} catch (err) {
 				const message = err instanceof Error ? err.message : String(err);
-				throw new Error(`Output ${outputId} is not valid JSON: ${message}`);
+				throw new Error(`Output ${scan.matchedId} is not valid JSON: ${message}`);
 			}
 
-			const query = hasPathExtraction ? pathToQuery(urlPath) : queryParam!;
+			const query = hasQueryExtraction ? queryParam! : pathToQuery(urlPath);
 			if (query) {
 				const extracted = applyQuery(jsonValue, query);
 				try {
@@ -122,11 +117,50 @@ export class AgentProtocolHandler implements ProtocolHandler {
 			content,
 			contentType,
 			size: Buffer.byteLength(content, "utf-8"),
-			sourcePath: foundPath,
+			sourcePath: scan.foundPath,
 			notes,
 		};
 	}
 
+	/**
+	 * Scan every registered artifacts dir for the first `<id>.md` among
+	 * `candidateIds` (tried in order, so a hierarchy match wins over the base
+	 * id). Returns the resolved path and the id it matched, plus the set of
+	 * available ids gathered from the scanned dirs for the not-found message.
+	 */
+	async #findOutput(
+		dirs: string[],
+		candidateIds: string[],
+	): Promise<{ foundPath?: string; matchedId?: string; anyDirExists: boolean; availableIds: Set<string> }> {
+		// Build a full id→path map across every registered dir before picking, so
+		// candidate priority is global: a nested id in a deeper dir must win over
+		// the base id even when the base id's dir is scanned first.
+		const byId = new Map<string, string>();
+		let anyDirExists = false;
+		for (const dir of dirs) {
+			let files: string[];
+			try {
+				files = await fs.readdir(dir);
+			} catch (err) {
+				if (isEnoent(err)) continue;
+				throw err;
+			}
+			anyDirExists = true;
+			for (const f of files) {
+				if (!f.endsWith(".md")) continue;
+				const id = f.slice(0, -3);
+				if (!byId.has(id)) byId.set(id, path.join(dir, f));
+			}
+		}
+		for (const id of candidateIds) {
+			const foundPath = byId.get(id);
+			if (foundPath) {
+				return { foundPath, matchedId: id, anyDirExists, availableIds: new Set(byId.keys()) };
+			}
+		}
+		return { anyDirExists, availableIds: new Set(byId.keys()) };
+	}
+
 	async complete(): Promise<UrlCompletion[]> {
 		const ids = new Set<string>();
 		for (const dir of artifactsDirsFromRegistry()) {

package/src/irc/bus.ts

@@ -127,12 +127,31 @@ export class IrcBus {
 			};
 		}
 
+		// A `parked` recipient always needs the lifecycle to revive it — this is
+		// read from *this* bus's registry, so it holds for any registry. The
+		// mid-park / adopted checks below query the lifecycle's own state, which
+		// only describes the registry it manages: consult them only when the
+		// lifecycle owns this bus's registry, otherwise a custom-registry bus
+		// (fallen back to the global manager) would gate a live recipient on
+		// unrelated global park state. Main/non-adopted live peers skip the gate,
+		// and pending waiters still win without a session.
+		const lifecycle = this.#lifecycle();
+		const lifecycleOwnsRegistry = lifecycle.manages(this.#registry);
+		const needsLifecycleGate =
+			ref.status === "parked" ||
+			(lifecycleOwnsRegistry && (lifecycle.isParking(message.to) || lifecycle.has(message.to)));
+
+		const priorSession = ref.session;
 		let revived = false;
-		if (ref.status === "parked") {
+		if (needsLifecycleGate) {
 			try {
-				await this.#lifecycle().ensureLive(message.to);
-				revived = true;
+				const liveSession = await lifecycle.ensureLive(message.to);
+				// Revival = we did not keep the same live instance (parked start, or
+				// park completed and a fresh session was rebuilt).
+				revived = !priorSession || liveSession !== priorSession;
 			} catch (error) {
+				// Not revivable / released / revive failed. Do not buffer: a permanent
+				// failure must not inflate unread counts or pretend delivery is pending.
 				return {
 					to: message.to,
 					outcome: "failed",

package/src/launch/broker.ts

@@ -3,7 +3,7 @@ import * as net from "node:net";
 import * as os from "node:os";
 import * as path from "node:path";
 import { Process, type PtyRunResult, PtySession } from "@oh-my-pi/pi-natives";
-import { isEexist, isEnoent, logger, postmortem, sanitizeText } from "@oh-my-pi/pi-utils";
+import { isEexist, isEnoent, logger, postmortem, procmgr, sanitizeText } from "@oh-my-pi/pi-utils";
 import { truncateHead, truncateHeadBytes, truncateTail, truncateTailBytes } from "../session/streaming-output";
 import { workerEnvFromParent } from "../subprocess/worker-client";
 import { daemonBrokerEndpoint } from "./paths";
@@ -555,7 +555,8 @@ class DaemonBroker {
 				`printf '%s' "$$" > ${quoteShellArg(pidPath)}`,
 				`exec ${argv.map(quoteShellArg).join(" ")}`,
 			].join("; ");
-			run = session.start({ command, shell: process.env.SHELL, ...options }, onChunk);
+			const shell = procmgr.getShellConfig().shell;
+			run = session.start({ command, shell, ...options }, onChunk);
 		}
 		void run
 			.then(result => this.#onPtyExit(record, generation, result))

package/src/launch/client.ts

@@ -2,7 +2,7 @@ import * as fs from "node:fs/promises";
 import * as net from "node:net";
 import * as os from "node:os";
 import * as path from "node:path";
-import { isEexist, isEnoent, postmortem } from "@oh-my-pi/pi-utils";
+import { isEexist, isEisdir, isEnoent, postmortem } from "@oh-my-pi/pi-utils";
 import { resolveWorkerSpawnCmd, workerEnvFromParent } from "../subprocess/worker-client";
 import { daemonBrokerEndpoint, daemonRuntimeDir } from "./paths";
 import {
@@ -49,7 +49,7 @@ async function canonicalProjectDir(projectDir: string): Promise<string> {
 	try {
 		return await fs.realpath(resolved);
 	} catch (error) {
-		if (isEnoent(error)) return resolved;
+		if (isEnoent(error) || isEisdir(error)) return resolved;
 		throw error;
 	}
 }

package/src/launch/presence.ts

@@ -1,6 +1,6 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import { isEnoent, postmortem } from "@oh-my-pi/pi-utils";
+import { isEisdir, isEnoent, postmortem } from "@oh-my-pi/pi-utils";
 import { daemonRuntimeDir } from "./paths";
 
 const CLIENTS_DIR = "clients";
@@ -15,7 +15,7 @@ async function canonicalProjectDir(projectDir: string): Promise<string> {
 	try {
 		return await fs.realpath(resolved);
 	} catch (error) {
-		if (isEnoent(error)) return resolved;
+		if (isEnoent(error) || isEisdir(error)) return resolved;
 		throw error;
 	}
 }

package/src/lib/xai-http.ts

@@ -16,7 +16,14 @@ export function ohMyPiXAIUserAgent(): string {
 	return "oh-my-pi/xai";
 }
 
-type XAIProvider = "xai-oauth" | "xai";
+/** xAI provider ids supported by shared HTTP tool transport resolution. */
+export type XAIHttpProvider = "xai-oauth" | "xai";
+
+/** Resolved endpoint and configured headers for an xAI HTTP tool request. */
+export interface XAIHttpTransport {
+	baseURL: string;
+	headers?: Record<string, string>;
+}
 
 /**
  * Resolve the HTTP base URL for an xAI tool call.
@@ -48,7 +55,11 @@ type XAIProvider = "xai-oauth" | "xai";
  * let xai-oauth entries hijack a xai tool call (or vice versa) when the
  * same model id ships under both descriptors.
  */
-function resolveXAIBaseURL(modelRegistry: ModelRegistry, provider: XAIProvider, modelId: string | undefined): string {
+function resolveXAIBaseURL(
+	modelRegistry: ModelRegistry,
+	provider: XAIHttpProvider,
+	modelId: string | undefined,
+): string {
 	if (modelId) {
 		const merged = modelRegistry.getAll().find(m => m.id === modelId && m.provider === provider);
 		if (merged?.baseUrl) {
@@ -68,6 +79,21 @@ function resolveXAIBaseURL(modelRegistry: ModelRegistry, provider: XAIProvider,
 	}
 	return ($env.XAI_BASE_URL || DEFAULT_BASE_URL).replace(/\/$/, "");
 }
+/**
+ * Resolve an xAI tool endpoint and its provider/model header overrides.
+ */
+export function resolveXAIHttpTransport(
+	modelRegistry: ModelRegistry,
+	provider: XAIHttpProvider,
+	modelId?: string,
+): XAIHttpTransport {
+	return {
+		baseURL: resolveXAIBaseURL(modelRegistry, provider, modelId),
+		headers:
+			(modelId ? modelRegistry.find(provider, modelId)?.headers : undefined) ??
+			modelRegistry.getProviderHeaders(provider),
+	};
+}
 
 /**
  * Resolve xAI credentials for HTTP tool calls.

package/src/lsp/client.ts

@@ -428,7 +428,7 @@ async function handleConfigurationRequest(client: LspClient, message: LspJsonRpc
 	const items = params?.items ?? [];
 	const result = items.map(item => {
 		const section = item.section ?? "";
-		return client.config.settings?.[section] ?? {};
+		return client.config.settings?.[section] ?? null;
 	});
 	await sendResponse(client, message.id, result, "workspace/configuration");
 }

package/src/main.ts

@@ -59,6 +59,7 @@ import type { PrintModeOptions } from "./modes/print-mode";
 import { CURRENT_SETUP_VERSION } from "./modes/setup-version";
 import { initTheme, stopThemeWatcher } from "./modes/theme/theme";
 import type { SubmittedUserInput } from "./modes/types";
+import { createWarpEventBridgeExtension } from "./modes/warp-events";
 import { AgentLifecycleManager } from "./registry/agent-lifecycle";
 import {
 	type CreateAgentSessionOptions,
@@ -76,7 +77,7 @@ import { executeBuiltinSlashCommand } from "./slash-commands/builtin-registry";
 import { shouldShowStartupSplash } from "./startup-splash";
 import { discoverTitleSystemPromptFile, resolvePromptInput } from "./system-prompt";
 import { createPersistedSubagentReviverFactory } from "./task/persisted-revive";
-import { initTelemetryExport, isTelemetryExportEnabled } from "./telemetry-export";
+import { createTelemetryExportConfig, initTelemetryExport, isTelemetryExportEnabled } from "./telemetry-export";
 import { concreteThinkingLevel, parseConfiguredThinkingLevel } from "./thinking";
 import type { LspStartupServerInfo } from "./tools";
 import {
@@ -1350,15 +1351,13 @@ export async function runRootCommand(
 	sessionOptions.hasUI = isInteractive || mode === "rpc-ui";
 	sessionOptions.settings = settingsInstance;
 
-	// OTEL: register the global OTLP trace exporter when an OTLP endpoint is
-	// configured via env, then switch on the agent loop's telemetry so its
-	// GenAI spans (invoke_agent / chat / execute_tool) are actually emitted.
-	// Both are no-ops when OTEL_EXPORTER_OTLP_ENDPOINT is unset. An empty config
-	// is enough to enable telemetry — content capture is governed by the
-	// standard OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT env var.
+	// OTEL: register global OTLP exporters when an endpoint is configured via
+	// env, then switch on the agent loop's telemetry hooks so traces, run-level
+	// metrics, and structured logs have source events to export. Content capture
+	// remains governed by OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT.
 	await logger.time("initTelemetryExport", initTelemetryExport);
 	if (isTelemetryExportEnabled()) {
-		sessionOptions.telemetry = {};
+		sessionOptions.telemetry = createTelemetryExportConfig(sessionOptions.telemetry);
 	}
 
 	// Handle CLI --api-key as runtime override (not persisted)
@@ -1407,6 +1406,10 @@ export async function runRootCommand(
 		// string-flag value such as `--target @notes.md` is the flag's value, not a
 		// file — and the same result is handed to createAgentSession via
 		// `preloadedExtensions` so the discovery work is not repeated.
+		if (isInteractive) {
+			sessionOptions.extensions = [...(sessionOptions.extensions ?? []), createWarpEventBridgeExtension()];
+		}
+
 		const eventBus = new EventBus();
 		const extensionsResult = await loadSessionExtensions(sessionOptions, cwd, settingsInstance, eventBus);
 		const extensionFlagSink: ExtensionFlagSink = {

package/src/mcp/manager.ts

@@ -572,8 +572,14 @@ export class MCPManager {
 		};
 	}
 
+	/**
+	 * Ownership is matched via `mcpServerName`, never a `mcp__${name}_` name
+	 * prefix: tool names are lossy-sanitized, so one server's sanitized name
+	 * can prefix another's (`atlassian` vs `atlassian:atlassian`) and a name
+	 * with sanitized characters never prefix-matches its own tools at all.
+	 */
 	#replaceServerTools(name: string, tools: CustomTool<TSchema, MCPToolDetails>[]): void {
-		this.#tools = this.#tools.filter(t => !t.name.startsWith(`mcp__${name}_`));
+		this.#tools = this.#tools.filter(t => t.mcpServerName !== name);
 		this.#tools.push(...tools);
 		// Stable sort by name so reconnect order does not perturb the array.
 		// See `sortMCPToolsByName` for the cache-stability rationale.
@@ -762,8 +768,8 @@ export class MCPManager {
 		}
 
 		// Remove tools from this server and notify consumers
-		const hadTools = this.#tools.some(t => t.name.startsWith(`mcp__${name}_`));
-		this.#tools = this.#tools.filter(t => !t.name.startsWith(`mcp__${name}_`));
+		const hadTools = this.#tools.some(t => t.mcpServerName === name);
+		this.#tools = this.#tools.filter(t => t.mcpServerName !== name);
 		if (hadTools) this.#onToolsChanged?.(this.#tools);
 
 		// Notify prompt consumers so stale commands are cleared

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,
 	};
 }
 
@@ -388,6 +467,7 @@ export class StdioTransport implements MCPTransport {
 			stderr: "pipe",
 			windowsHide: spawnCommand.windowsHide,
 			detached: spawnCommand.detached,
+			windowsVerbatimArguments: spawnCommand.windowsVerbatimArguments,
 		});
 
 		this.#connected = true;