@clinebot/core 0.0.36 → 0.0.37

package/src/hub/server.ts

@@ -9,6 +9,7 @@ import type {
 	SessionRecord as HubSessionRecord,
 	HubToolExecutorName,
 	JsonValue,
+	RuntimeConfigExtensionKind,
 	SessionParticipant,
 	TeamProgressProjectionEvent,
 	ToolApprovalRequest,
@@ -16,6 +17,7 @@ import type {
 } from "@clinebot/shared";
 import { createSessionId } from "@clinebot/shared";
 import { WebSocketServer } from "ws";
+import { CronService, type CronServiceOptions } from "../cron/cron-service";
 import { HubScheduleCommandService } from "../cron/schedule-command-service";
 import {
 	type HubScheduleRuntimeHandlers,
@@ -32,10 +34,11 @@ import { SqliteSessionStore } from "../services/storage/sqlite-session-store";
 import { CoreSessionService } from "../session/session-service";
 import { LocalRuntimeHost } from "../transports/local";
 import { readPersistedMessagesFile } from "../transports/runtime-host-support";
-import type { CoreSessionEvent } from "../types/events";
+import type { CoreSessionEvent, SessionPendingPrompt } from "../types/events";
 import type { SessionRecord as LocalSessionRecord } from "../types/sessions";
 import { BrowserWebSocketHubAdapter } from "./browser-websocket";
 import { verifyHubConnection } from "./client";
+import { resolveDefaultHubPort } from "./defaults";
 import {
 	clearHubDiscovery,
 	createHubServerUrl,
@@ -60,8 +63,15 @@ type NodeWebSocketLike = {
 	once(event: "close", listener: () => void): void;
 };
 
+type NodeUpgradeSocketLike = {
+	destroy(error?: Error): void;
+	write(chunk: string): boolean;
+	end(): void;
+};
+
 type HubSessionState = {
 	createdByClientId: string;
+	interactive: boolean;
 	participants: Map<string, SessionParticipant>;
 };
 
@@ -104,6 +114,37 @@ function wrapWsSocket(socket: NodeWebSocketLike) {
 	};
 }
 
+const RUNTIME_CONFIG_EXTENSION_KINDS = new Set<RuntimeConfigExtensionKind>([
+	"rules",
+	"skills",
+	"plugins",
+]);
+
+function parseRuntimeConfigExtensions(
+	value: unknown,
+): RuntimeConfigExtensionKind[] | undefined {
+	if (!Array.isArray(value)) {
+		return undefined;
+	}
+	const extensions = value
+		.map((item) => (typeof item === "string" ? item.trim() : ""))
+		.filter((item): item is RuntimeConfigExtensionKind =>
+			RUNTIME_CONFIG_EXTENSION_KINDS.has(item as RuntimeConfigExtensionKind),
+		);
+	return [...new Set(extensions)];
+}
+
+function rejectUpgradeSocket(socket: NodeUpgradeSocketLike): void {
+	try {
+		socket.write(
+			"HTTP/1.1 400 Bad Request\r\nConnection: close\r\nContent-Length: 0\r\n\r\n",
+		);
+		socket.end();
+	} catch {
+		socket.destroy();
+	}
+}
+
 function formatHubUptime(ms: number): string {
 	const totalSeconds = Math.max(0, Math.floor(ms / 1000));
 	const days = Math.floor(totalSeconds / 86_400);
@@ -157,6 +198,10 @@ function cloneSessionMetadata(
 	if (session.messagesPath?.trim())
 		metadata.messagesPath = session.messagesPath;
 	if (session.prompt?.trim()) metadata.prompt = session.prompt;
+	if (session.provider?.trim()) metadata.provider = session.provider;
+	if (session.model?.trim()) metadata.model = session.model;
+	if (session.source?.trim()) metadata.source = session.source;
+	if (typeof session.pid === "number") metadata.pid = session.pid;
 	return Object.keys(metadata).length > 0 ? metadata : undefined;
 }
 
@@ -354,6 +399,14 @@ function formatHubStartupError(
 	return wrapped;
 }
 
+function isAddressInUseError(error: unknown): boolean {
+	return (
+		error instanceof Error &&
+		"code" in error &&
+		(error as Error & { code?: string }).code === "EADDRINUSE"
+	);
+}
+
 function serializeToolContext(context: ToolContext): Record<string, unknown> {
 	return {
 		agentId: context.agentId,
@@ -483,8 +536,13 @@ export class HubServerTransport implements NativeHubTransport {
 			}) => void;
 		}
 	>();
+	private readonly suppressNextTerminalEventBySession = new Map<
+		string,
+		string
+	>();
 	private readonly schedules: HubScheduleService;
 	private readonly scheduleCommands: HubScheduleCommandService;
+	private readonly cronService?: CronService;
 	private readonly sessionHost: RuntimeHost;
 	private readonly hubId = createSessionId("hub_");
 	private readonly startedAtMs = Date.now();
@@ -522,27 +580,45 @@ export class HubServerTransport implements NativeHubTransport {
 			},
 		});
 		this.scheduleCommands = new HubScheduleCommandService(this.schedules);
+		if (options.cronOptions) {
+			this.cronService = new CronService({
+				runtimeHandlers: options.runtimeHandlers,
+				...options.cronOptions,
+			});
+		}
 		this.sessionHost.subscribe((event) => {
-			void this.handleSessionEvent(event);
+			void this.handleSessionEvent(event).catch((error) => {
+				logHubBoundaryError("session event handling failed", error);
+			});
 		});
 	}
 
+	getCronService(): CronService | undefined {
+		return this.cronService;
+	}
+
 	getHubId(): string {
 		return this.hubId;
 	}
 
 	async start(): Promise<void> {
 		await this.schedules.start();
+		if (this.cronService) {
+			try {
+				await this.cronService.start();
+			} catch (err) {
+				console.error("[hub] cron service start failed", err);
+			}
+		}
 	}
 
 	async stop(): Promise<void> {
-		for (const approval of this.pendingApprovals.values()) {
-			approval.resolve({
+		for (const approvalId of this.pendingApprovals.keys()) {
+			this.resolvePendingApproval(approvalId, {
 				approved: false,
 				reason: "Hub shutting down before approval was resolved.",
 			});
 		}
-		this.pendingApprovals.clear();
 		for (const pending of this.pendingCapabilityRequests.values()) {
 			pending.resolve({
 				ok: false,
@@ -552,6 +628,13 @@ export class HubServerTransport implements NativeHubTransport {
 		this.pendingCapabilityRequests.clear();
 		await this.sessionHost.dispose("hub_server_stop");
 		await this.schedules.dispose();
+		if (this.cronService) {
+			try {
+				await this.cronService.dispose();
+			} catch (err) {
+				console.error("[hub] cron service stop failed", err);
+			}
+		}
 	}
 
 	async handleCommand(envelope: HubCommandEnvelope): Promise<HubReplyEnvelope> {
@@ -581,10 +664,18 @@ export class HubServerTransport implements NativeHubTransport {
 				return await this.handleSessionDetach(envelope);
 			case "session.get":
 				return await this.handleSessionGet(envelope);
+			case "session.messages":
+				return await this.handleSessionMessages(envelope);
 			case "session.list":
 				return await this.handleSessionList(envelope);
 			case "session.update":
 				return await this.handleSessionUpdate(envelope);
+			case "session.pending_prompts":
+				return await this.handleSessionPendingPrompts(envelope);
+			case "session.update_pending_prompt":
+				return await this.handleSessionUpdatePendingPrompt(envelope);
+			case "session.remove_pending_prompt":
+				return await this.handleSessionRemovePendingPrompt(envelope);
 			case "session.delete":
 				return await this.handleSessionDelete(envelope);
 			case "session.hook":
@@ -748,9 +839,13 @@ export class HubServerTransport implements NativeHubTransport {
 		sessionId: string,
 		clientId: string,
 		role: SessionParticipant["role"],
+		options: { interactive?: boolean } = {},
 	): HubSessionState {
 		const existing = this.sessionState.get(sessionId);
 		if (existing) {
+			if (options.interactive !== undefined) {
+				existing.interactive = options.interactive;
+			}
 			if (!existing.participants.has(clientId)) {
 				existing.participants.set(clientId, {
 					clientId,
@@ -762,6 +857,7 @@ export class HubServerTransport implements NativeHubTransport {
 		}
 		const state: HubSessionState = {
 			createdByClientId: clientId,
+			interactive: options.interactive ?? true,
 			participants: new Map([
 				[
 					clientId,
@@ -877,6 +973,9 @@ export class HubServerTransport implements NativeHubTransport {
 		const advertisedToolExecutors = Array.isArray(runtimeOptions.toolExecutors)
 			? runtimeOptions.toolExecutors.filter(isHubToolExecutorName)
 			: [];
+		const configExtensions = parseRuntimeConfigExtensions(
+			runtimeOptions.configExtensions,
+		);
 		const started = await this.sessionHost.start({
 			source: typeof metadata.source === "string" ? metadata.source : undefined,
 			interactive: metadata.interactive !== false,
@@ -892,6 +991,7 @@ export class HubServerTransport implements NativeHubTransport {
 					loadLatestOnInit: true,
 					loadPrivateOnAuth: true,
 				},
+				configExtensions,
 				defaultToolExecutors: createCapabilityBackedToolExecutors(
 					clientId,
 					advertisedToolExecutors,
@@ -985,7 +1085,9 @@ export class HubServerTransport implements NativeHubTransport {
 						? { "*": { autoApprove: true } }
 						: undefined,
 		});
-		this.ensureSessionState(started.sessionId, clientId, "creator");
+		this.ensureSessionState(started.sessionId, clientId, "creator", {
+			interactive: metadata.interactive !== false,
+		});
 		const session = await this.readHubSessionRecord(started.sessionId);
 		if (session) {
 			this.publish(
@@ -1106,6 +1208,45 @@ export class HubServerTransport implements NativeHubTransport {
 		};
 	}
 
+	private async handleSessionMessages(
+		envelope: HubCommandEnvelope,
+	): Promise<HubReplyEnvelope> {
+		const sessionId =
+			typeof envelope.payload?.sessionId === "string"
+				? envelope.payload.sessionId.trim()
+				: envelope.sessionId?.trim() || "";
+		if (!sessionId) {
+			return {
+				version: envelope.version,
+				requestId: envelope.requestId,
+				ok: false,
+				error: {
+					code: "invalid_session_id",
+					message: "session.messages requires a session id",
+				},
+			};
+		}
+		const session = await this.readHubSessionRecord(sessionId);
+		if (!session) {
+			return {
+				version: envelope.version,
+				requestId: envelope.requestId,
+				ok: false,
+				error: {
+					code: "session_not_found",
+					message: `Unknown session: ${sessionId}`,
+				},
+			};
+		}
+		const messages = await this.sessionHost.readMessages(sessionId);
+		return {
+			version: envelope.version,
+			requestId: envelope.requestId,
+			ok: true,
+			payload: { sessionId, messages },
+		};
+	}
+
 	private async handleSessionList(
 		envelope: HubCommandEnvelope,
 	): Promise<HubReplyEnvelope> {
@@ -1150,6 +1291,81 @@ export class HubServerTransport implements NativeHubTransport {
 		};
 	}
 
+	private async handleSessionPendingPrompts(
+		envelope: HubCommandEnvelope,
+	): Promise<HubReplyEnvelope> {
+		const sessionId =
+			typeof envelope.payload?.sessionId === "string"
+				? envelope.payload.sessionId.trim()
+				: envelope.sessionId?.trim() || "";
+		const prompts = await this.sessionHost.pendingPrompts("list", {
+			sessionId,
+		});
+		return {
+			version: envelope.version,
+			requestId: envelope.requestId,
+			ok: true,
+			payload: { sessionId, prompts },
+		};
+	}
+
+	private async handleSessionUpdatePendingPrompt(
+		envelope: HubCommandEnvelope,
+	): Promise<HubReplyEnvelope> {
+		const sessionId =
+			typeof envelope.payload?.sessionId === "string"
+				? envelope.payload.sessionId.trim()
+				: envelope.sessionId?.trim() || "";
+		const promptId =
+			typeof envelope.payload?.promptId === "string"
+				? envelope.payload.promptId.trim()
+				: "";
+		const prompt =
+			typeof envelope.payload?.prompt === "string"
+				? envelope.payload.prompt
+				: undefined;
+		const delivery =
+			envelope.payload?.delivery === "queue" ||
+			envelope.payload?.delivery === "steer"
+				? envelope.payload.delivery
+				: undefined;
+		const result = await this.sessionHost.pendingPrompts("update", {
+			sessionId,
+			promptId,
+			prompt,
+			delivery,
+		});
+		return {
+			version: envelope.version,
+			requestId: envelope.requestId,
+			ok: true,
+			payload: result as unknown as Record<string, JsonValue | undefined>,
+		};
+	}
+
+	private async handleSessionRemovePendingPrompt(
+		envelope: HubCommandEnvelope,
+	): Promise<HubReplyEnvelope> {
+		const sessionId =
+			typeof envelope.payload?.sessionId === "string"
+				? envelope.payload.sessionId.trim()
+				: envelope.sessionId?.trim() || "";
+		const promptId =
+			typeof envelope.payload?.promptId === "string"
+				? envelope.payload.promptId.trim()
+				: "";
+		const result = await this.sessionHost.pendingPrompts("delete", {
+			sessionId,
+			promptId,
+		});
+		return {
+			version: envelope.version,
+			requestId: envelope.requestId,
+			ok: true,
+			payload: result as unknown as Record<string, JsonValue | undefined>,
+		};
+	}
+
 	private async handleSessionDelete(
 		envelope: HubCommandEnvelope,
 	): Promise<HubReplyEnvelope> {
@@ -1202,6 +1418,9 @@ export class HubServerTransport implements NativeHubTransport {
 			!Array.isArray(payload.attachments)
 				? (payload.attachments as Record<string, unknown>)
 				: undefined;
+		const userFiles = Array.isArray(attachments?.userFiles)
+			? attachments.userFiles.filter((filePath) => typeof filePath === "string")
+			: undefined;
 		const result = await this.sessionHost.send({
 			sessionId,
 			prompt,
@@ -1212,8 +1431,13 @@ export class HubServerTransport implements NativeHubTransport {
 			userImages: Array.isArray(attachments?.userImages)
 				? (attachments.userImages as string[])
 				: undefined,
+			userFiles,
 		});
 		if (result) {
+			this.suppressNextTerminalEventBySession.set(
+				sessionId,
+				result.finishReason,
+			);
 			this.publish(
 				this.buildEvent(
 					"run.completed",
@@ -1283,9 +1507,18 @@ export class HubServerTransport implements NativeHubTransport {
 		request: ToolApprovalRequest,
 	): Promise<{ approved: boolean; reason?: string }> {
 		const approvalId = createSessionId("approval_");
+		const sessionId = request.sessionId;
+		const state = this.sessionState.get(sessionId);
+		if (state?.interactive === false) {
+			return {
+				approved: false,
+				reason:
+					"Tool approval requires an interactive session, but this session is non-interactive.",
+			};
+		}
 		return await new Promise((resolve) => {
 			this.pendingApprovals.set(approvalId, {
-				sessionId: request.conversationId,
+				sessionId,
 				resolve,
 			});
 			this.publish(
@@ -1293,16 +1526,34 @@ export class HubServerTransport implements NativeHubTransport {
 					"approval.requested",
 					{
 						approvalId,
+						sessionId: request.sessionId,
+						agentId: request.agentId,
+						conversationId: request.conversationId,
+						iteration: request.iteration,
 						toolCallId: request.toolCallId,
 						toolName: request.toolName,
 						inputJson: JSON.stringify(request.input ?? null),
+						policy: request.policy,
 					},
-					request.conversationId,
+					sessionId,
 				),
 			);
 		});
 	}
 
+	private resolvePendingApproval(
+		approvalId: string,
+		result: { approved: boolean; reason?: string },
+	): { sessionId: string } | undefined {
+		const pending = this.pendingApprovals.get(approvalId);
+		if (!pending) {
+			return undefined;
+		}
+		this.pendingApprovals.delete(approvalId);
+		pending.resolve(result);
+		return { sessionId: pending.sessionId };
+	}
+
 	private async handleApprovalRespond(
 		envelope: HubCommandEnvelope,
 	): Promise<HubReplyEnvelope> {
@@ -1322,25 +1573,37 @@ export class HubServerTransport implements NativeHubTransport {
 				},
 			};
 		}
-		this.pendingApprovals.delete(approvalId);
 		const reason =
-			envelope.payload?.payload &&
-			typeof envelope.payload.payload === "object" &&
-			!Array.isArray(envelope.payload.payload) &&
-			typeof (envelope.payload.payload as Record<string, unknown>).reason ===
-				"string"
-				? ((envelope.payload.payload as Record<string, unknown>)
-						.reason as string)
-				: undefined;
-		pending.resolve({
+			typeof envelope.payload?.reason === "string"
+				? envelope.payload.reason
+				: envelope.payload?.payload &&
+						typeof envelope.payload.payload === "object" &&
+						!Array.isArray(envelope.payload.payload) &&
+						typeof (envelope.payload.payload as Record<string, unknown>)
+							.reason === "string"
+					? ((envelope.payload.payload as Record<string, unknown>)
+							.reason as string)
+					: undefined;
+		const resolved = this.resolvePendingApproval(approvalId, {
 			approved: envelope.payload?.approved === true,
 			reason,
 		});
+		if (!resolved) {
+			return {
+				version: envelope.version,
+				requestId: envelope.requestId,
+				ok: false,
+				error: {
+					code: "approval_not_found",
+					message: `Unknown approval: ${approvalId}`,
+				},
+			};
+		}
 		this.publish(
 			this.buildEvent(
 				"approval.resolved",
 				{ approvalId, approved: envelope.payload?.approved === true, reason },
-				pending.sessionId,
+				resolved.sessionId,
 			),
 		);
 		return {
@@ -1473,6 +1736,30 @@ export class HubServerTransport implements NativeHubTransport {
 				return;
 			case "agent_event": {
 				const { sessionId, event: agentEvent } = event.payload;
+				if (agentEvent.type === "iteration_start") {
+					this.publish(
+						this.buildEvent(
+							"iteration.started",
+							{ iteration: agentEvent.iteration },
+							sessionId,
+						),
+					);
+					return;
+				}
+				if (agentEvent.type === "iteration_end") {
+					this.publish(
+						this.buildEvent(
+							"iteration.finished",
+							{
+								iteration: agentEvent.iteration,
+								hadToolCalls: agentEvent.hadToolCalls,
+								toolCallCount: agentEvent.toolCallCount,
+							},
+							sessionId,
+						),
+					);
+					return;
+				}
 				if (agentEvent.type === "content_start") {
 					if (
 						agentEvent.contentType === "text" &&
@@ -1531,18 +1818,52 @@ export class HubServerTransport implements NativeHubTransport {
 						return;
 					}
 				}
-				if (
-					agentEvent.type === "content_end" &&
-					agentEvent.contentType === "tool"
-				) {
+				if (agentEvent.type === "content_end") {
+					switch (agentEvent.contentType) {
+						case "text":
+							this.publish(
+								this.buildEvent(
+									"assistant.finished",
+									{ text: agentEvent.text },
+									sessionId,
+								),
+							);
+							break;
+						case "reasoning":
+							this.publish(
+								this.buildEvent(
+									"reasoning.finished",
+									{ reasoning: agentEvent.reasoning },
+									sessionId,
+								),
+							);
+							break;
+						case "tool":
+							this.publish(
+								this.buildEvent(
+									"tool.finished",
+									{
+										toolCallId: agentEvent.toolCallId,
+										toolName: agentEvent.toolName,
+										output: agentEvent.output,
+										error: agentEvent.error,
+									},
+									sessionId,
+								),
+							);
+							break;
+					}
+					return;
+				}
+				if (agentEvent.type === "done") {
 					this.publish(
 						this.buildEvent(
-							"tool.finished",
+							"agent.done",
 							{
-								toolCallId: agentEvent.toolCallId,
-								toolName: agentEvent.toolName,
-								output: agentEvent.output,
-								error: agentEvent.error,
+								reason: agentEvent.reason,
+								text: agentEvent.text,
+								iterations: agentEvent.iterations,
+								usage: agentEvent.usage,
 							},
 							sessionId,
 						),
@@ -1586,6 +1907,35 @@ export class HubServerTransport implements NativeHubTransport {
 				);
 				return;
 			}
+			case "pending_prompts": {
+				this.publish(
+					this.buildEvent(
+						"session.pending_prompts",
+						{
+							sessionId: event.payload.sessionId,
+							prompts: event.payload.prompts,
+						},
+						event.payload.sessionId,
+					),
+				);
+				return;
+			}
+			case "pending_prompt_submitted": {
+				const prompt: SessionPendingPrompt = {
+					id: event.payload.id,
+					prompt: event.payload.prompt,
+					delivery: event.payload.delivery,
+					attachmentCount: event.payload.attachmentCount,
+				};
+				this.publish(
+					this.buildEvent(
+						"session.pending_prompt_submitted",
+						{ sessionId: event.payload.sessionId, prompt },
+						event.payload.sessionId,
+					),
+				);
+				return;
+			}
 			case "status": {
 				const session = await this.readHubSessionRecord(
 					event.payload.sessionId,
@@ -1601,7 +1951,16 @@ export class HubServerTransport implements NativeHubTransport {
 				}
 				return;
 			}
-			case "ended":
+			case "ended": {
+				const suppressDuplicateTerminalEvent =
+					this.suppressNextTerminalEventBySession.get(
+						event.payload.sessionId,
+					) === event.payload.reason;
+				if (suppressDuplicateTerminalEvent) {
+					this.suppressNextTerminalEventBySession.delete(
+						event.payload.sessionId,
+					);
+				}
 				if (event.payload.reason === "completed") {
 					const session = await this.readHubSessionRecord(
 						event.payload.sessionId,
@@ -1611,6 +1970,9 @@ export class HubServerTransport implements NativeHubTransport {
 						this.buildEvent("ui.notify", notification, event.payload.sessionId),
 					);
 				}
+				if (suppressDuplicateTerminalEvent) {
+					return;
+				}
 				this.publish(
 					this.buildEvent(
 						event.payload.reason === "aborted"
@@ -1621,6 +1983,7 @@ export class HubServerTransport implements NativeHubTransport {
 					),
 				);
 				return;
+			}
 			default:
 				return;
 		}
@@ -1653,12 +2016,25 @@ export class HubServerTransport implements NativeHubTransport {
 				if (entry.sessionId && entry.sessionId !== event.sessionId) {
 					continue;
 				}
-				entry.listener(event);
+				try {
+					entry.listener(event);
+				} catch (error) {
+					logHubBoundaryError(
+						`listener threw while publishing ${event.event}`,
+						error,
+					);
+				}
 			}
 		}
 	}
 }
 
+function logHubBoundaryError(message: string, error: unknown): void {
+	const details =
+		error instanceof Error ? error.stack || error.message : String(error);
+	console.error(`[hub] ${message}: ${details}`);
+}
+
 export interface HubWebSocketServerOptions {
 	host?: string;
 	port?: number;
@@ -1667,6 +2043,14 @@ export interface HubWebSocketServerOptions {
 	sessionHost?: RuntimeHost;
 	runtimeHandlers: HubScheduleRuntimeHandlers;
 	scheduleOptions?: Omit<HubScheduleServiceOptions, "runtimeHandlers">;
+	/**
+	 * File-based cron automation options. When provided, the hub starts a
+	 * `CronService` that watches global `~/.cline/cron/` by default, reconciles
+	 * specs into `cron.db`, and executes queued runs through `runtimeHandlers`.
+	 * Pass `cronOptions.specs` to use a different source, including future
+	 * workspace-scoped specs.
+	 */
+	cronOptions?: Omit<CronServiceOptions, "runtimeHandlers">;
 	/**
 	 * Custom `fetch` implementation forwarded to the internally-constructed
 	 * `LocalRuntimeHost` that executes incoming `session.create` traffic.
@@ -1687,7 +2071,9 @@ export interface HubWebSocketServer {
 }
 
 export interface EnsureHubWebSocketServerOptions
-	extends HubWebSocketServerOptions {}
+	extends HubWebSocketServerOptions {
+	allowPortFallback?: boolean;
+}
 
 export interface EnsuredHubWebSocketServerResult {
 	server?: HubWebSocketServer;
@@ -1703,7 +2089,7 @@ export async function startHubWebSocketServer(
 	const owner = options.owner ?? resolveHubOwnerContext();
 	const host = options.host ?? "127.0.0.1";
 	const pathname = options.pathname ?? "/hub";
-	const requestedPort = options.port ?? 25463;
+	const requestedPort = options.port ?? resolveDefaultHubPort();
 	let port = requestedPort;
 	let url = createHubServerUrl(host, requestedPort, pathname);
 	const buildId = resolveHubBuildId();
@@ -1720,6 +2106,43 @@ export async function startHubWebSocketServer(
 		pid: process.pid,
 		startedAt,
 	} as const;
+	let closePromise: Promise<void> | undefined;
+
+	const closeServer = async (): Promise<void> => {
+		if (closePromise) {
+			return closePromise;
+		}
+		closePromise = (async () => {
+			for (const detach of cleanup) {
+				detach();
+			}
+			cleanup.clear();
+			await new Promise<void>((resolve, reject) => {
+				wss.close((error?: Error) => {
+					if (error) {
+						reject(error);
+						return;
+					}
+					resolve();
+				});
+			});
+			await new Promise<void>((resolve, reject) => {
+				server.close((error) => {
+					if (error) {
+						reject(error);
+						return;
+					}
+					resolve();
+				});
+			});
+			await transport.stop();
+			const current = await readHubDiscovery(owner.discoveryPath);
+			if (current?.url === url) {
+				await clearHubDiscovery(owner.discoveryPath);
+			}
+		})();
+		return closePromise;
+	};
 
 	const server = http.createServer((req, res) => {
 		if ((req.url ?? "/") === "/health") {
@@ -1742,6 +2165,15 @@ export async function startHubWebSocketServer(
 			res.end(JSON.stringify(versionPayload));
 			return;
 		}
+		if ((req.url ?? "/") === "/shutdown" && req.method === "POST") {
+			res.statusCode = 202;
+			res.setHeader("content-type", "application/json");
+			res.end(JSON.stringify({ ok: true }));
+			queueMicrotask(() => {
+				void closeServer();
+			});
+			return;
+		}
 		res.statusCode = 404;
 		res.end("Not found");
 	});
@@ -1753,14 +2185,23 @@ export async function startHubWebSocketServer(
 			socket.destroy();
 			return;
 		}
-		wss.handleUpgrade(request, socket, head, (websocket: NodeWebSocketLike) => {
-			const detach = adapter.attach(wrapWsSocket(websocket));
-			cleanup.add(detach);
-			websocket.once("close", () => {
-				detach();
-				cleanup.delete(detach);
-			});
-		});
+		try {
+			wss.handleUpgrade(
+				request,
+				socket,
+				head,
+				(websocket: NodeWebSocketLike) => {
+					const detach = adapter.attach(wrapWsSocket(websocket));
+					cleanup.add(detach);
+					websocket.once("close", () => {
+						detach();
+						cleanup.delete(detach);
+					});
+				},
+			);
+		} catch {
+			rejectUpgradeSocket(socket);
+		}
 	});
 
 	await new Promise<void>((resolve, reject) => {
@@ -1807,35 +2248,7 @@ export async function startHubWebSocketServer(
 		host,
 		port,
 		url,
-		close: async () => {
-			for (const detach of cleanup) {
-				detach();
-			}
-			cleanup.clear();
-			await new Promise<void>((resolve, reject) => {
-				wss.close((error?: Error) => {
-					if (error) {
-						reject(error);
-						return;
-					}
-					resolve();
-				});
-			});
-			await new Promise<void>((resolve, reject) => {
-				server.close((error) => {
-					if (error) {
-						reject(error);
-						return;
-					}
-					resolve();
-				});
-			});
-			await transport.stop();
-			const current = await readHubDiscovery(owner.discoveryPath);
-			if (current?.url === url) {
-				await clearHubDiscovery(owner.discoveryPath);
-			}
-		},
+		close: closeServer,
 	};
 }
 
@@ -1844,7 +2257,7 @@ export async function ensureHubWebSocketServer(
 ): Promise<EnsuredHubWebSocketServerResult> {
 	const owner = options.owner ?? resolveHubOwnerContext();
 	const host = options.host ?? "127.0.0.1";
-	const port = options.port ?? 25463;
+	const port = options.port ?? resolveDefaultHubPort();
 	const pathname = options.pathname ?? "/hub";
 	const expectedUrl = createHubServerUrl(host, port, pathname);
 	const sharedKey = owner.discoveryPath;
@@ -1858,7 +2271,10 @@ export async function ensureHubWebSocketServer(
 
 	return await withHubStartupLock(owner.discoveryPath, async () => {
 		const discovered = await readHubDiscovery(owner.discoveryPath);
-		if (discovered?.url === expectedUrl) {
+		const canReuseDiscovered =
+			discovered?.url &&
+			(discovered.url === expectedUrl || options.allowPortFallback === true);
+		if (canReuseDiscovered) {
 			const healthy = await probeHubServer(discovered.url);
 			if (healthy?.url && (await verifyHubConnection(healthy.url))) {
 				return { url: healthy.url, action: "reuse" };
@@ -1875,14 +2291,27 @@ export async function ensureHubWebSocketServer(
 			await clearHubDiscovery(owner.discoveryPath);
 		}
 
-		const serverPromise = startHubWebSocketServer({ ...options, owner });
-		SHARED_SERVERS.set(sharedKey, serverPromise);
+		const start = async (
+			startOptions: HubWebSocketServerOptions,
+		): Promise<EnsuredHubWebSocketServerResult> => {
+			const serverPromise = startHubWebSocketServer({ ...startOptions, owner });
+			SHARED_SERVERS.set(sharedKey, serverPromise);
+			try {
+				const server = await serverPromise;
+				return { server, url: server.url, action: "started" };
+			} catch (error) {
+				SHARED_SERVERS.delete(sharedKey);
+				throw error;
+			}
+		};
+
 		try {
-			const server = await serverPromise;
-			return { server, url: server.url, action: "started" };
+			return await start(options);
 		} catch (error) {
-			SHARED_SERVERS.delete(sharedKey);
-			throw error;
+			if (!options.allowPortFallback || !isAddressInUseError(error)) {
+				throw error;
+			}
+			return await start({ ...options, port: 0 });
 		}
 	});
 }