pi-cursor-sdk 0.5.3 → 0.5.4

package/src/cursor-fallback-models.generated.ts

@@ -1,6 +1,6 @@
 import type { ModelListItem } from "@cursor/sdk";
 
-// Generated with @cursor/sdk@1.0.37 from 46 Cursor models.
+// Generated with @cursor/sdk@1.0.37 from 48 Cursor models.
 // Refresh with: npm run refresh:cursor-snapshots -- --write
 // Do not add secrets; this file stores public model metadata only.
 export const FALLBACK_MODEL_ITEMS = [
@@ -6518,6 +6518,60 @@ export const FALLBACK_MODEL_ITEMS = [
 			}
 		]
 	},
+	{
+		id: "gemini-4-argon",
+		displayName: "Gemini 4 Argon",
+		parameters: [
+			{
+				id: "reasoning_effort",
+				displayName: "Effort",
+				values: [
+					{
+						value: "low",
+						displayName: "Low"
+					},
+					{
+						value: "medium",
+						displayName: "Medium"
+					},
+					{
+						value: "high",
+						displayName: "High"
+					}
+				]
+			}
+		],
+		variants: [
+			{
+				params: [
+					{
+						id: "reasoning_effort",
+						value: "low"
+					}
+				],
+				displayName: "Gemini 4 Argon Low"
+			},
+			{
+				params: [
+					{
+						id: "reasoning_effort",
+						value: "medium"
+					}
+				],
+				displayName: "Gemini 4 Argon Medium",
+				isDefault: true
+			},
+			{
+				params: [
+					{
+						id: "reasoning_effort",
+						value: "high"
+					}
+				],
+				displayName: "Gemini 4 Argon High"
+			}
+		]
+	},
 	{
 		id: "glm-5.2",
 		displayName: "GLM 5.2",
@@ -10157,5 +10211,214 @@ export const FALLBACK_MODEL_ITEMS = [
 				displayName: "Muse Spark 1.3"
 			}
 		]
+	},
+	{
+		id: "muse-wonder-1.0",
+		displayName: "Muse Wonder",
+		parameters: [
+			{
+				id: "context",
+				displayName: "Context",
+				values: [
+					{
+						value: "300k",
+						displayName: "300K"
+					},
+					{
+						value: "1m",
+						displayName: "1M"
+					}
+				]
+			},
+			{
+				id: "reasoning_effort",
+				displayName: "Reasoning",
+				values: [
+					{
+						value: "minimal",
+						displayName: "Minimal"
+					},
+					{
+						value: "low",
+						displayName: "Low"
+					},
+					{
+						value: "medium",
+						displayName: "Medium"
+					},
+					{
+						value: "high",
+						displayName: "High"
+					},
+					{
+						value: "xhigh",
+						displayName: "Extra High"
+					},
+					{
+						value: "max",
+						displayName: "Max"
+					}
+				]
+			}
+		],
+		variants: [
+			{
+				params: [
+					{
+						id: "context",
+						value: "300k"
+					},
+					{
+						id: "reasoning_effort",
+						value: "minimal"
+					}
+				],
+				displayName: "Muse Wonder  Minimal"
+			},
+			{
+				params: [
+					{
+						id: "context",
+						value: "300k"
+					},
+					{
+						id: "reasoning_effort",
+						value: "low"
+					}
+				],
+				displayName: "Muse Wonder  Low"
+			},
+			{
+				params: [
+					{
+						id: "context",
+						value: "300k"
+					},
+					{
+						id: "reasoning_effort",
+						value: "medium"
+					}
+				],
+				displayName: "Muse Wonder  Medium"
+			},
+			{
+				params: [
+					{
+						id: "context",
+						value: "300k"
+					},
+					{
+						id: "reasoning_effort",
+						value: "high"
+					}
+				],
+				displayName: "Muse Wonder  High"
+			},
+			{
+				params: [
+					{
+						id: "context",
+						value: "300k"
+					},
+					{
+						id: "reasoning_effort",
+						value: "xhigh"
+					}
+				],
+				displayName: "Muse Wonder  Extra High"
+			},
+			{
+				params: [
+					{
+						id: "context",
+						value: "300k"
+					},
+					{
+						id: "reasoning_effort",
+						value: "max"
+					}
+				],
+				displayName: "Muse Wonder  Max"
+			},
+			{
+				params: [
+					{
+						id: "context",
+						value: "1m"
+					},
+					{
+						id: "reasoning_effort",
+						value: "minimal"
+					}
+				],
+				displayName: "Muse Wonder 1M Minimal"
+			},
+			{
+				params: [
+					{
+						id: "context",
+						value: "1m"
+					},
+					{
+						id: "reasoning_effort",
+						value: "low"
+					}
+				],
+				displayName: "Muse Wonder 1M Low"
+			},
+			{
+				params: [
+					{
+						id: "context",
+						value: "1m"
+					},
+					{
+						id: "reasoning_effort",
+						value: "medium"
+					}
+				],
+				displayName: "Muse Wonder 1M Medium"
+			},
+			{
+				params: [
+					{
+						id: "context",
+						value: "1m"
+					},
+					{
+						id: "reasoning_effort",
+						value: "high"
+					}
+				],
+				displayName: "Muse Wonder 1M High"
+			},
+			{
+				params: [
+					{
+						id: "context",
+						value: "1m"
+					},
+					{
+						id: "reasoning_effort",
+						value: "xhigh"
+					}
+				],
+				displayName: "Muse Wonder 1M Extra High",
+				isDefault: true
+			},
+			{
+				params: [
+					{
+						id: "context",
+						value: "1m"
+					},
+					{
+						id: "reasoning_effort",
+						value: "max"
+					}
+				],
+				displayName: "Muse Wonder 1M Max"
+			}
+		]
 	}
 ] satisfies ModelListItem[];

package/src/cursor-live-run-coordinator.ts

@@ -39,6 +39,8 @@ export interface CursorLiveSdkRun {
 export interface CursorLiveRun {
 	id: string;
 	agent: SDKAgent;
+	/** Effective ordinary main-loop policy captured when this SDK run was created. */
+	nativeToolsEnabled?: boolean;
 	bridgeRun?: CursorPiToolBridgeRun;
 	sessionBridgeRun?: CursorPiToolBridgeRun;
 	sessionAgentScopeKey: string;
@@ -65,6 +67,8 @@ export interface CursorLiveRun {
 export interface CursorLiveRunCreateParams {
 	id: string;
 	agent: SDKAgent;
+	/** Effective ordinary main-loop policy captured when this SDK run was created. */
+	nativeToolsEnabled?: boolean;
 	bridgeRun?: CursorPiToolBridgeRun;
 	sessionBridgeRun?: CursorPiToolBridgeRun;
 	sessionAgentScopeKey?: string;
@@ -293,6 +297,7 @@ export function createCursorLiveRunCoordinator(deps: CursorLiveRunCoordinatorDep
 			const run: CursorLiveRun = {
 				id: params.id,
 				agent: params.agent,
+				nativeToolsEnabled: params.nativeToolsEnabled !== false,
 				bridgeRun: params.bridgeRun,
 				sessionBridgeRun: params.sessionBridgeRun,
 				sessionAgentScopeKey,

package/src/cursor-mcp-timeout-override.ts

@@ -8,12 +8,6 @@ const CURSOR_MCP_TOOL_TIMEOUT_SECONDS_ENV = "PI_CURSOR_MCP_TOOL_TIMEOUT_SECONDS"
 const CURSOR_MCP_CONNECT_TIMEOUT_MS_ENV = "PI_CURSOR_MCP_CONNECT_TIMEOUT_MS";
 const CURSOR_MCP_CONNECT_TIMEOUT_SECONDS_ENV = "PI_CURSOR_MCP_CONNECT_TIMEOUT_SECONDS";
 
-interface CursorMcpToolTimeoutOverrideOptions {
-	timeoutMs?: number;
-	connectTimeoutMs?: number;
-	env?: Record<string, string | undefined>;
-}
-
 interface CursorMcpToolTimeoutOverrideState {
 	installed: boolean;
 	timeoutMs: number;
@@ -61,7 +55,7 @@ function normalizeConnectTimeoutMs(timeoutMs: number): number {
 	);
 }
 
-export function resolveCursorMcpConnectTimeoutMs(
+function resolveCursorMcpConnectTimeoutMs(
 	env: Record<string, string | undefined> = process.env,
 ): number {
 	const explicitMs = parsePositiveNumber(env[CURSOR_MCP_CONNECT_TIMEOUT_MS_ENV]);
@@ -81,7 +75,7 @@ function isCursorSdkMcpProtocolTimeoutStack(stack: string | undefined): boolean
 	);
 }
 
-export function isCursorSdkMcpToolTimeoutStack(stack: string | undefined): boolean {
+function isCursorSdkMcpToolTimeoutStack(stack: string | undefined): boolean {
 	if (!stack) return false;
 	return (
 		isCursorSdkMcpProtocolTimeoutStack(stack) &&
@@ -89,7 +83,7 @@ export function isCursorSdkMcpToolTimeoutStack(stack: string | undefined): boole
 	);
 }
 
-export function isCursorSdkMcpConnectTimeoutStack(stack: string | undefined): boolean {
+function isCursorSdkMcpConnectTimeoutStack(stack: string | undefined): boolean {
 	if (!stack || !isCursorSdkMcpProtocolTimeoutStack(stack)) return false;
 	// The SDK minifies the Client class name; the protocol method and SDK
 	// frame, not that constructor's spelling, establish this timeout purpose.
@@ -121,15 +115,9 @@ function patchedSetTimeout(
 	return Reflect.apply(delegate, globalThis, [handler, nextDelay, ...args]) as ReturnType<GlobalSetTimeout>;
 }
 
-export function installCursorMcpToolTimeoutOverride(
-	options: CursorMcpToolTimeoutOverrideOptions = {},
-): CursorMcpToolTimeoutOverrideState {
-	installedToolTimeoutMs = normalizeOverrideTimeoutMs(
-		options.timeoutMs ?? resolveCursorMcpToolTimeoutMs(options.env),
-	);
-	installedConnectTimeoutMs = normalizeConnectTimeoutMs(
-		options.connectTimeoutMs ?? resolveCursorMcpConnectTimeoutMs(options.env),
-	);
+export function installCursorMcpToolTimeoutOverride(): CursorMcpToolTimeoutOverrideState {
+	installedToolTimeoutMs = resolveCursorMcpToolTimeoutMs();
+	installedConnectTimeoutMs = resolveCursorMcpConnectTimeoutMs();
 
 	if (!originalSetTimeout) {
 		originalSetTimeout = globalThis.setTimeout;
@@ -152,15 +140,3 @@ export function restoreCursorMcpToolTimeoutOverride(): void {
 	installedToolTimeoutMs = DEFAULT_CURSOR_MCP_TOOL_TIMEOUT_MS;
 	installedConnectTimeoutMs = DEFAULT_CURSOR_MCP_CONNECT_TIMEOUT_MS;
 }
-
-export const cursorMcpToolTimeoutOverrideDefaults = {
-	cursorSdkDefaultTimeoutMs: CURSOR_SDK_MCP_DEFAULT_TIMEOUT_MS,
-	defaultOverrideTimeoutMs: DEFAULT_CURSOR_MCP_TOOL_TIMEOUT_MS,
-	defaultConnectTimeoutMs: DEFAULT_CURSOR_MCP_CONNECT_TIMEOUT_MS,
-	minConnectTimeoutMs: MIN_CURSOR_MCP_CONNECT_TIMEOUT_MS,
-	maxNodeTimerDelayMs: MAX_NODE_TIMER_DELAY_MS,
-	timeoutMsEnv: CURSOR_MCP_TOOL_TIMEOUT_MS_ENV,
-	timeoutSecondsEnv: CURSOR_MCP_TOOL_TIMEOUT_SECONDS_ENV,
-	connectTimeoutMsEnv: CURSOR_MCP_CONNECT_TIMEOUT_MS_ENV,
-	connectTimeoutSecondsEnv: CURSOR_MCP_CONNECT_TIMEOUT_SECONDS_ENV,
-} as const;

package/src/cursor-native-tool-display-replay.ts

@@ -34,14 +34,12 @@ export type {
 } from "./cursor-replay-tool-details.js";
 export {
 	isCursorReplayNativeEditDetails,
-	isCursorReplayGenerateImageDetails,
-	isCursorReplayActivityDetails,
 	isCursorReplayNativeWriteDetails,
 	parseCursorReplayToolDetails,
 } from "./cursor-replay-tool-details.js";
 
 export const CURSOR_REPLAY_COLLAPSED_PREVIEW_LINES = 8;
-export const CURSOR_REPLAY_PREVIEW_MAX_CHARS = 4000;
+const CURSOR_REPLAY_PREVIEW_MAX_CHARS = 4000;
 export const CURSOR_REPLAY_PREVIEW_MAX_LINE_CHARS = 240;
 const CURSOR_REPLAY_HIGHLIGHT_MAX_CHARS = 12000;
 export const cursorReplayToolSchema = Type.Object({}, { additionalProperties: true });
@@ -75,7 +73,7 @@ function buildImageReplayComponent(text: string, imageData: string, mimeType: st
 	};
 }
 
-export function getCursorReplayPath(
+function getCursorReplayPath(
 	args: Record<string, unknown> | undefined,
 	details: Pick<CursorReplayNativeEditDetails, "path"> | Pick<CursorReplayNativeWriteDetails, "path"> | undefined,
 ): string {
@@ -282,7 +280,7 @@ function formatCursorReplayActivityPreview(
 	return stripHeader ? formatCursorReplayPreview(text, theme, maxLines, true) : formatMutedBlock(text, theme);
 }
 
-export function formatCursorReplayPreview(
+function formatCursorReplayPreview(
 	text: string,
 	theme: CursorReplayRenderTheme,
 	maxLines = CURSOR_REPLAY_COLLAPSED_PREVIEW_LINES,
@@ -330,7 +328,7 @@ function getCursorReplayCardTitle(toolName: CursorReplayToolName, args: Record<s
 	return "Cursor activity";
 }
 
-export function renderCursorReplayCall(
+function renderCursorReplayCall(
 	toolName: CursorReplayToolName,
 	args: Record<string, unknown> | undefined,
 	theme: CursorReplayRenderTheme,

package/src/cursor-native-tools.ts

@@ -0,0 +1,14 @@
+import { parseEnvBoolean } from "./cursor-env-boolean.js";
+
+export const CURSOR_NATIVE_TOOLS_ENV = "PI_CURSOR_NATIVE_TOOLS";
+
+/** Default preserves the SDK toolset; false selects the public MCP-only main loop. */
+export function resolveCursorNativeToolsEnabled(env: Record<string, string | undefined> = process.env): boolean {
+	return parseEnvBoolean(env[CURSOR_NATIVE_TOOLS_ENV], true);
+}
+
+export function assertCursorNativeToolsRuntime(runtime: "local" | "cloud", nativeToolsEnabled: boolean): void {
+	if (runtime === "cloud" && !nativeToolsEnabled) {
+		throw new Error("PI_CURSOR_NATIVE_TOOLS=0 requires local runtime; Cursor Cloud does not support the SDK tools restriction. Select local runtime or remove the opt-out.");
+	}
+}

package/src/cursor-pi-tool-bridge-env.ts

@@ -2,8 +2,8 @@ import { parseEnvBoolean } from "./cursor-env-boolean.js";
 import { resolveCursorMcpToolTimeoutMs } from "./cursor-mcp-timeout-override.js";
 
 export const CURSOR_PI_TOOL_BRIDGE_ENV = "PI_CURSOR_PI_TOOL_BRIDGE";
-export const CURSOR_PI_TOOL_BRIDGE_BUILTINS_ENV = "PI_CURSOR_EXPOSE_BUILTIN_TOOLS";
-export const CURSOR_PI_TOOL_BRIDGE_CALL_TIMEOUT_MS_ENV = "PI_CURSOR_PI_BRIDGE_CALL_TIMEOUT_MS";
+const CURSOR_PI_TOOL_BRIDGE_BUILTINS_ENV = "PI_CURSOR_EXPOSE_BUILTIN_TOOLS";
+const CURSOR_PI_TOOL_BRIDGE_CALL_TIMEOUT_MS_ENV = "PI_CURSOR_PI_BRIDGE_CALL_TIMEOUT_MS";
 
 export function resolveCursorPiToolBridgeEnabled(env: Record<string, string | undefined> = process.env): boolean {
 	return parseEnvBoolean(env[CURSOR_PI_TOOL_BRIDGE_ENV], true);
@@ -19,3 +19,32 @@ export function resolveCursorPiToolBridgeCallTimeoutMs(env: Record<string, strin
 	if (!Number.isFinite(parsed) || parsed <= 0) return mcpToolTimeoutMs;
 	return Math.min(Math.max(Math.trunc(parsed), 1), mcpToolTimeoutMs);
 }
+
+const CURSOR_PI_TOOL_BRIDGE_HOST_ENV = "PI_CURSOR_PI_TOOL_BRIDGE_HOST";
+const CURSOR_PI_TOOL_BRIDGE_PORT_ENV = "PI_CURSOR_PI_TOOL_BRIDGE_PORT";
+const DEFAULT_URL_HOST = "127.0.0.1";
+const PORT_PATTERN = /^\d{1,5}$/;
+
+export interface CursorPiToolBridgePortRange {
+	readonly first: number;
+	readonly last: number;
+}
+
+export function resolveCursorPiToolBridgeUrlHost(env: Record<string, string | undefined> = process.env): string {
+	return env[CURSOR_PI_TOOL_BRIDGE_HOST_ENV]?.trim().toLowerCase() === "localhost" ? "localhost" : DEFAULT_URL_HOST;
+}
+
+function parsePort(text: string): number | undefined {
+	if (!PORT_PATTERN.test(text)) return undefined;
+	const port = Number(text);
+	return port >= 1 && port <= 65535 ? port : undefined;
+}
+
+export function resolveCursorPiToolBridgePortRange(env: Record<string, string | undefined> = process.env): CursorPiToolBridgePortRange | undefined {
+	const parts = env[CURSOR_PI_TOOL_BRIDGE_PORT_ENV]?.trim().split("-");
+	if (!parts || parts.length > 2) return undefined;
+	const first = parsePort(parts[0]!);
+	const last = parts.length === 2 ? parsePort(parts[1]!) : first;
+	if (first === undefined || last === undefined || first > last) return undefined;
+	return { first, last };
+}

package/src/cursor-pi-tool-bridge-server.ts

@@ -6,6 +6,10 @@ import type {
 	CursorPiToolBridgeRunOptions,
 	CursorPiToolBridgeSnapshotApi,
 } from "./cursor-pi-tool-bridge-types.js";
+import {
+	resolveCursorPiToolBridgePortRange,
+	resolveCursorPiToolBridgeUrlHost,
+} from "./cursor-pi-tool-bridge-env.js";
 import { asRecord } from "./cursor-record-utils.js";
 import { CursorPiToolBridgeRunImpl } from "./cursor-pi-tool-bridge-run.js";
 import {
@@ -16,15 +20,54 @@ import {
 	resolveCursorPiToolBridgeEnabled,
 } from "./cursor-pi-tool-bridge-snapshot.js";
 
-export const LOOPBACK_HOST = "127.0.0.1";
+const LOOPBACK_HOST = "127.0.0.1";
 const HTTP_SERVER_CLOSE_GRACE_MS = 250;
+const EPHEMERAL_BIND_ATTEMPTS = 10;
+
+function listenOnce(server: HttpServer, port: number, host = LOOPBACK_HOST): Promise<void> {
+	return new Promise<void>((resolve, reject) => {
+		const onError = (error: Error) => {
+			server.off("listening", onListening);
+			reject(error);
+		};
+		const onListening = () => {
+			server.off("error", onError);
+			resolve();
+		};
+		server.once("error", onError);
+		server.once("listening", onListening);
+		server.listen({ port, host, ipv6Only: host === "::1" });
+	});
+}
+
+async function closeServers(servers: readonly HttpServer[]): Promise<void> {
+	await Promise.all(servers.map(async (server) => {
+		if (!server.listening) return;
+		await new Promise<void>((resolve, reject) => {
+			let settled = false;
+			const settle = (error?: Error): void => {
+				if (settled) return;
+				settled = true;
+				clearTimeout(closeTimer);
+				if (error) reject(error);
+				else resolve();
+			};
+			const closeTimer = setTimeout(() => settle(), HTTP_SERVER_CLOSE_GRACE_MS);
+			closeTimer.unref?.();
+			server.close((error) => settle(error ?? undefined));
+			server.closeIdleConnections();
+			server.closeAllConnections();
+		});
+	}));
+}
 
 export class CursorPiToolBridgeRegistry implements CursorPiToolBridge {
 	private readonly pi: CursorPiToolBridgeSnapshotApi;
 	private readonly env: Record<string, string | undefined>;
 	private readonly runs = new Set<CursorPiToolBridgeRunImpl>();
 	private readonly routes = new Map<string, CursorPiToolBridgeRunImpl>();
-	private httpServer?: HttpServer;
+	private httpServers: HttpServer[] = [];
+	private advertisedHost?: string;
 	private listenPromise?: Promise<void>;
 	private serverLifecycle = Promise.resolve();
 
@@ -57,7 +100,14 @@ export class CursorPiToolBridgeRegistry implements CursorPiToolBridge {
 			: createEmptySnapshot();
 		const run = new CursorPiToolBridgeRunImpl(this, this.env, snapshot, bridgeEnabled && snapshot.tools.length > 0, options);
 		this.runs.add(run);
-		await run.start();
+		try {
+			await run.start();
+		} catch (error) {
+			try { await run.dispose(); }
+			catch { /* Preserve the original startup failure, not a secondary cleanup error. */ }
+			this.runs.delete(run);
+			throw error;
+		}
 		run.emitStartDiagnostics(bridgeEnabled);
 		return run;
 	}
@@ -74,8 +124,8 @@ export class CursorPiToolBridgeRegistry implements CursorPiToolBridge {
 			await this.ensureHttpServer();
 			this.routes.set(pathname, run);
 			const address = this.getHttpServerAddress();
-			if (!address) throw new Error("Cursor pi tool bridge HTTP server is not listening");
-			return `http://${LOOPBACK_HOST}:${address.port}${pathname}`;
+			if (!address || !this.advertisedHost) throw new Error("Cursor pi tool bridge HTTP server is not listening");
+			return `http://${this.advertisedHost}:${address.port}${pathname}`;
 		});
 	}
 
@@ -94,7 +144,7 @@ export class CursorPiToolBridgeRegistry implements CursorPiToolBridge {
 	}
 
 	getHttpServerAddress(): AddressInfo | undefined {
-		const address = asRecord(this.httpServer?.address());
+		const address = asRecord(this.httpServers[0]?.address());
 		if (typeof address?.port !== "number") return undefined;
 		return {
 			address: typeof address.address === "string" ? address.address : LOOPBACK_HOST,
@@ -123,7 +173,8 @@ export class CursorPiToolBridgeRegistry implements CursorPiToolBridge {
 
 	private async ensureHttpServer(): Promise<void> {
 		this.listenPromise ??= this.startHttpServer().catch((error: unknown) => {
-			this.httpServer = undefined;
+			this.httpServers = [];
+			this.advertisedHost = undefined;
 			this.listenPromise = undefined;
 			throw error;
 		});
@@ -131,6 +182,9 @@ export class CursorPiToolBridgeRegistry implements CursorPiToolBridge {
 	}
 
 	private async startHttpServer(): Promise<void> {
+		// A hostname is a listener policy, not a mutable per-run URL preference.
+		const advertisedHost = resolveCursorPiToolBridgeUrlHost(this.env);
+		const range = resolveCursorPiToolBridgePortRange(this.env);
 		const [{ getRequestListener }, { createMcpHonoApp }] = await Promise.all([
 			import("@hono/node-server"),
 			import("@modelcontextprotocol/hono"),
@@ -142,49 +196,39 @@ export class CursorPiToolBridgeRegistry implements CursorPiToolBridge {
 			).get("parsedBody");
 			return this.handleHttpRequest(context.req.raw, parsedBody);
 		});
-		const server = createServer(getRequestListener(app.fetch, { overrideGlobalObjects: false }));
-		this.httpServer = server;
-		await new Promise<void>((resolve, reject) => {
-			const onError = (error: Error) => {
-				server.off("listening", onListening);
-				reject(error);
-			};
-			const onListening = () => {
-				server.off("error", onError);
-				resolve();
-			};
-			server.once("error", onError);
-			server.once("listening", onListening);
-			server.listen(0, LOOPBACK_HOST);
-		});
+		const listener = getRequestListener(app.fetch, { overrideGlobalObjects: false });
+		const attempts = range ? range.last - range.first + 1 : advertisedHost === "localhost" ? EPHEMERAL_BIND_ATTEMPTS : 1;
+		for (let attempt = 0; attempt < attempts; attempt += 1) {
+			const servers = [createServer(listener)];
+			try {
+				await listenOnce(servers[0]!, range ? range.first + attempt : 0);
+				if (advertisedHost === "localhost") {
+					const port = (servers[0]!.address() as AddressInfo).port;
+					const ipv6 = createServer(listener);
+					servers.push(ipv6);
+					// Own both explicit loopbacks before publishing any tokenized URL.
+					await listenOnce(ipv6, port, "::1");
+				}
+				this.httpServers = servers;
+				this.advertisedHost = advertisedHost;
+				return;
+			} catch (error) {
+				try { await closeServers(servers); }
+				catch { throw error; } // Never retry or replace the bind failure when rollback fails.
+				if ((error as NodeJS.ErrnoException).code !== "EADDRINUSE" || (!range && advertisedHost !== "localhost")) throw error;
+			}
+		}
+		if (range) throw new Error(`Cursor pi tool bridge could not listen on any port in ${range.first}-${range.last} (all in use)`);
+		throw new Error("Cursor pi tool bridge could not own both localhost loopback listeners on an ephemeral port");
 	}
 
 	private async closeHttpServer(): Promise<void> {
 		await this.listenPromise?.catch(() => undefined);
-		const server = this.httpServer;
-		if (!server) return;
-		this.httpServer = undefined;
+		const servers = this.httpServers;
+		this.httpServers = [];
+		this.advertisedHost = undefined;
 		this.listenPromise = undefined;
-		await new Promise<void>((resolve, reject) => {
-			let settled = false;
-			let closeTimer: ReturnType<typeof setTimeout> | undefined;
-			const settle = (error?: Error): void => {
-				if (settled) return;
-				settled = true;
-				if (closeTimer) clearTimeout(closeTimer);
-				if (error) reject(error);
-				else resolve();
-			};
-
-			closeTimer = setTimeout(() => settle(), HTTP_SERVER_CLOSE_GRACE_MS);
-			closeTimer.unref?.();
-
-			server.close((error) => {
-				settle(error ?? undefined);
-			});
-			server.closeIdleConnections();
-			server.closeAllConnections();
-		});
+		await closeServers(servers);
 	}
 
 	private async handleHttpRequest(request: Request, parsedBody?: unknown): Promise<Response> {

package/src/cursor-pi-tool-bridge-snapshot.ts

@@ -6,7 +6,6 @@ import type {
 } from "./cursor-pi-tool-bridge-types.js";
 import { createMcpToolName, normalizeMcpInputSchema, stableNameHash } from "./cursor-pi-tool-bridge-mcp.js";
 export {
-	CURSOR_PI_TOOL_BRIDGE_BUILTINS_ENV,
 	CURSOR_PI_TOOL_BRIDGE_ENV,
 	resolveCursorPiToolBridgeBuiltinsEnabled,
 	resolveCursorPiToolBridgeEnabled,