rivetkit 2.3.0-rc.10 → 2.3.0-rc.12

package/src/engine-client/actor-websocket-client.ts

@@ -2,23 +2,24 @@ import {
 	type ClientConfig,
 	DEFAULT_MAX_QUERY_INPUT_SIZE,
 } from "@/client/config";
+import type { ActorGatewayQuery, CrashPolicy } from "@/client/query";
 import {
+	WS_PROTOCOL_ACTOR,
 	WS_PROTOCOL_CONN_PARAMS,
 	WS_PROTOCOL_ENCODING,
 	WS_PROTOCOL_STANDARD as WS_PROTOCOL_RIVETKIT,
-	WS_PROTOCOL_TARGET,
-	WS_PROTOCOL_ACTOR,
 	WS_PROTOCOL_SKIP_READY_WAIT,
+	WS_PROTOCOL_TARGET,
 	WS_PROTOCOL_TEST_ACK_HOOK,
 	WS_PROTOCOL_TOKEN,
 } from "@/common/actor-router-consts";
+import type { JsonCompatValue } from "@/common/encoding";
 import { importWebSocket } from "@/common/websocket";
 import { setRemoteHibernatableWebSocketAckTestHooks } from "@/common/websocket-test-hooks";
-import type { ActorGatewayQuery, CrashPolicy } from "@/client/query";
 import type { Encoding, UniversalWebSocket } from "@/mod";
 import { encodeCborCompat, uint8ArrayToBase64 } from "@/serde";
 import { combineUrlPath } from "@/utils";
-import { shouldSkipReadyWait, type GatewayRequestOptions } from "./driver";
+import { type GatewayRequestOptions, shouldSkipReadyWait } from "./driver";
 import { logger } from "./log";
 
 class BufferedRemoteWebSocket implements UniversalWebSocket {
@@ -302,7 +303,7 @@ function pushInputQueryParam(
 		return;
 	}
 
-	const encodedInput = encodeCborCompat(input);
+	const encodedInput = encodeCborCompat(input as JsonCompatValue);
 	if (encodedInput.byteLength > maxInputSize) {
 		throw new Error(
 			`Actor query input exceeds maxInputSize (${encodedInput.byteLength} > ${maxInputSize} bytes). Increase client maxInputSize to allow larger query payloads.`,

package/src/engine-client/api-endpoints.ts

@@ -107,12 +107,59 @@ export async function getDatacenters(
 	return apiCall<never, DatacentersResponse>(config, "GET", `/datacenters`);
 }
 
+// MARK: Get runner configs
+export interface RunnerConfig {
+	normal?: {
+		drain_on_version_upgrade?: boolean;
+		actor_eviction_period?: number;
+		actor_eviction_rate?: number;
+	};
+	serverless?: {
+		url: string;
+		headers: Record<string, string>;
+		drain_grace_period?: number;
+		max_runners: number;
+		min_runners: number;
+		request_lifespan: number;
+		runners_margin: number;
+		slots_per_runner: number;
+		metadata_poll_interval?: number;
+		drain_on_version_upgrade?: boolean;
+		actor_eviction_period?: number;
+		actor_eviction_rate?: number;
+	};
+	protocol_version?: number;
+}
+
+export interface RunnerConfigDatacenters {
+	datacenters: Record<string, RunnerConfig>;
+}
+
+export interface RunnerConfigsResponse {
+	runner_configs: Record<string, RunnerConfigDatacenters>;
+}
+
+export async function getRunnerConfig(
+	config: ClientConfig,
+	name: string,
+): Promise<RunnerConfigsResponse> {
+	return apiCall<never, RunnerConfigsResponse>(
+		config,
+		"GET",
+		`/runner-configs?runner_name=${name}`,
+	);
+}
+
 // MARK: Update runner config
 export interface RegistryConfigRequest {
 	datacenters: Record<
 		string,
 		{
-			normal?: Record<string, unknown>;
+			normal?: {
+				drain_on_version_upgrade?: boolean;
+				actor_eviction_period?: number;
+				actor_eviction_rate?: number;
+			};
 			serverless?: {
 				url: string;
 				headers: Record<string, string>;
@@ -123,9 +170,11 @@ export interface RegistryConfigRequest {
 				runners_margin: number;
 				slots_per_runner: number;
 				metadata_poll_interval?: number;
+				drain_on_version_upgrade?: boolean;
+				actor_eviction_period?: number;
+				actor_eviction_rate?: number;
 			};
 			metadata?: Record<string, unknown>;
-			drain_on_version_upgrade?: boolean;
 		}
 	>;
 }

package/src/engine-client/api-utils.ts

@@ -1,10 +1,10 @@
 import { z } from "zod/v4";
+import { RivetError } from "@/actor/errors";
 import type { ClientConfig } from "@/client/config";
 import { sendHttpRequest } from "@/client/utils";
-import { RivetError } from "@/actor/errors";
+import type { RegistryConfig } from "@/registry/config";
 import { combineUrlPath } from "@/utils";
 import { logger } from "./log";
-import { RegistryConfig } from "@/registry/config";
 
 export { RivetError as EngineApiError };
 

package/src/engine-client/driver.ts

@@ -1,8 +1,8 @@
 import type { Hono, Context as HonoContext } from "hono";
 import type { ActorKey, Encoding, UniversalWebSocket } from "@/actor/mod";
+import type { ActorQuery, CrashPolicy } from "@/client/query";
 import type { RegistryConfig } from "@/registry/config";
 import type { GetUpgradeWebSocket } from "@/utils";
-import type { ActorQuery, CrashPolicy } from "@/client/query";
 
 export type GatewayTarget = { directId: string } | ActorQuery;
 

package/src/engine-client/mod.ts

@@ -7,9 +7,9 @@ import {
 	PATH_WEBSOCKET_BASE,
 	PATH_WEBSOCKET_PREFIX,
 } from "@/common/actor-router-consts";
+import type { JsonCompatValue } from "@/common/encoding";
 import { noopNext } from "@/common/utils";
 import type { Actor as ApiActor } from "@/engine-api/actors";
-import { shouldSkipReadyWait } from "@/engine-client/driver";
 import type {
 	ActorOutput,
 	CreateInput,
@@ -22,6 +22,7 @@ import type {
 	ListActorsInput,
 	RuntimeDisplayInformation,
 } from "@/engine-client/driver";
+import { shouldSkipReadyWait } from "@/engine-client/driver";
 import type { Encoding, UniversalWebSocket } from "@/mod";
 import { encodeCborCompat, uint8ArrayToBase64 } from "@/serde";
 import { combineUrlPath, type GetUpgradeWebSocket } from "@/utils";
@@ -181,7 +182,9 @@ export class RemoteEngineControlClient implements EngineControlClient {
 			key: serializeActorKey(key),
 			runner_name_selector: this.#config.poolName,
 			input: actorInput
-				? uint8ArrayToBase64(encodeCborCompat(actorInput))
+				? uint8ArrayToBase64(
+						encodeCborCompat(actorInput as JsonCompatValue),
+					)
 				: undefined,
 			crash_policy: crashPolicy ?? "sleep",
 		});
@@ -215,7 +218,7 @@ export class RemoteEngineControlClient implements EngineControlClient {
 			runner_name_selector: this.#config.poolName,
 			key: serializeActorKey(key),
 			input: input
-				? uint8ArrayToBase64(encodeCborCompat(input))
+				? uint8ArrayToBase64(encodeCborCompat(input as JsonCompatValue))
 				: undefined,
 			crash_policy: crashPolicy ?? "sleep",
 		});

package/src/engine-client/ws-proxy.ts

@@ -9,7 +9,7 @@ import { logger } from "./log";
  * Returns Hono `upgradeWebSocket` args that will proxy requests from the client to a destination address.
  */
 export async function createWebSocketProxy(
-	c: HonoContext,
+	_c: HonoContext,
 	targetUrl: string,
 	protocols: string[],
 ): Promise<UpgradeWebSocketArgs> {
@@ -23,7 +23,7 @@ export async function createWebSocketProxy(
 	const state: WsState = {};
 
 	return {
-		onOpen: async (event: any, clientWs: WSContext) => {
+		onOpen: async (_event: any, clientWs: WSContext) => {
 			logger().debug({ msg: "client websocket connected", targetUrl });
 
 			if (clientWs.readyState !== 1) {
@@ -137,7 +137,7 @@ export async function createWebSocketProxy(
 			}
 		},
 
-		onClose: (event: any, clientWs: WSContext) => {
+		onClose: (event: any, _clientWs: WSContext) => {
 			logger().debug({
 				msg: "client websocket closed",
 				targetUrl,
@@ -159,7 +159,7 @@ export async function createWebSocketProxy(
 			}
 		},
 
-		onError: (event: any, clientWs: WSContext) => {
+		onError: (event: any, _clientWs: WSContext) => {
 			logger().error({ msg: "client websocket error", targetUrl, event });
 
 			if (state.targetWs) {

package/src/inspector/client.browser.ts

@@ -198,7 +198,9 @@ const v3ToServerToV4 = (v3Data: v3.ToServer): v4.ToServer =>
 
 const v4ToServerToV3 = (v4Data: v4.ToServer): v3.ToServer => {
 	if (v4Data.body.tag === "WorkflowReplayRequest") {
-		throw new Error("Cannot convert v4-only workflow replay requests to v3");
+		throw new Error(
+			"Cannot convert v4-only workflow replay requests to v3",
+		);
 	}
 
 	return v4Data as unknown as v3.ToServer;
@@ -238,11 +240,7 @@ export const TO_SERVER_VERSIONED = createVersionedDataHandler<v4.ToServer>({
 		v2ToServerToV3,
 		v3ToServerToV4,
 	],
-	serializeConverters: () => [
-		v4ToServerToV3,
-		v3ToServerToV2,
-		v2ToServerToV1,
-	],
+	serializeConverters: () => [v4ToServerToV3, v3ToServerToV2, v2ToServerToV1],
 });
 
 export const TO_CLIENT_VERSIONED = createVersionedDataHandler<v4.ToClient>({
@@ -279,9 +277,5 @@ export const TO_CLIENT_VERSIONED = createVersionedDataHandler<v4.ToClient>({
 		v2ToClientToV3,
 		v3ToClientToV4,
 	],
-	serializeConverters: () => [
-		v4ToClientToV3,
-		v3ToClientToV2,
-		v2ToClientToV1,
-	],
+	serializeConverters: () => [v4ToClientToV3, v3ToClientToV2, v2ToClientToV1],
 });

package/src/inspector/mod.ts

@@ -1,4 +1,5 @@
 export * from "@/common/bare/generated/inspector/v4";
+export type { WorkflowHistory as TransportWorkflowHistory } from "@/common/bare/transport/v1";
 export {
 	decodeWorkflowHistoryTransport,
 	encodeWorkflowHistoryTransport,
@@ -7,6 +8,3 @@ export {
 	createWorkflowInspectorAdapter,
 	type WorkflowInspectorAdapter,
 } from "@/workflow/inspector";
-export type {
-	WorkflowHistory as TransportWorkflowHistory,
-} from "@/common/bare/transport/v1";

package/src/registry/config/envoy.ts

@@ -1,11 +1,10 @@
 import { z } from "zod/v4";
 import { getLogger } from "@/common/log";
 import {
-	isDev,
 	getNodeEnv,
+	getRivetEnvoyVersion,
 	getRivetPool,
 	getRivetTotalSlots,
-	getRivetEnvoyVersion,
 } from "@/utils/env-vars";
 
 let warnedMissingVersion = false;

package/src/registry/config/index.ts

@@ -33,9 +33,7 @@ import {
 
 export const ActorsSchema = z.record(
 	z.string(),
-	z.custom<
-		BaseActorDefinition<any, any, any, any, any, any, any, any, any>
-	>(),
+	z.custom<AnyActorDefinition>(),
 );
 export type RegistryActors = z.infer<typeof ActorsSchema>;
 
@@ -267,13 +265,9 @@ export const RegistryConfigSchema = z
 				 * after calling `CoreRegistry::shutdown()`. Defaults to the
 				 * engine-provided actor stop threshold once the envoy connects.
 				 *
-				 * Must be >= rivetkit-core's drain timeout (20s) + margin.
+				 * Must be long enough for rivetkit-core to drain the envoy.
 				 */
-				gracePeriodMs: z
-					.number()
-					.int()
-					.min(1_000)
-					.optional(),
+				gracePeriodMs: z.number().int().min(1_000).optional(),
 				/**
 				 * If true, rivetkit will not install SIGINT/SIGTERM handlers.
 				 * Use when the host application owns signal policy and will

package/src/registry/index.ts

@@ -1,6 +1,8 @@
+import { Hono } from "hono";
 import { ENGINE_ENDPOINT } from "@/common/engine";
 import { configureServerlessPool } from "@/serverless/configure";
-import { VERSION } from "@/utils";
+import { detectRuntime, VERSION } from "@/utils";
+import { crossPlatformServe, loadRuntimeServeStatic } from "@/utils/serve";
 import {
 	type RegistryActors,
 	type RegistryConfig,
@@ -44,8 +46,18 @@ export interface RegistryRoutes {
 	prometheusMetrics(request?: Request): Promise<Response>;
 }
 
+/**
+ * Injectable dependencies for {@link Registry}. Production code uses the
+ * defaults. Tests override `buildConfiguredRegistry` to drive lifecycle
+ * orchestration against a fake `CoreRuntime` without an engine.
+ */
+export interface RegistryDeps {
+	buildConfiguredRegistry: typeof buildConfiguredRegistry;
+}
+
 export class Registry<A extends RegistryActors> {
 	#config: RegistryConfigInput<A>;
+	#buildConfiguredRegistry: typeof buildConfiguredRegistry;
 	public readonly routes: RegistryRoutes;
 
 	get config(): RegistryConfigInput<A> {
@@ -65,8 +77,10 @@ export class Registry<A extends RegistryActors> {
 	#shutdownInFlight: Promise<void> | null = null;
 	#signalHandlers: Partial<Record<ShutdownSignal, () => void>> = {};
 
-	constructor(config: RegistryConfigInput<A>) {
+	constructor(config: RegistryConfigInput<A>, deps?: Partial<RegistryDeps>) {
 		this.#config = config;
+		this.#buildConfiguredRegistry =
+			deps?.buildConfiguredRegistry ?? buildConfiguredRegistry;
 		this.routes = {
 			health: () => this.#healthRoute(),
 			metadata: () => this.#metadataRoute(),
@@ -75,16 +89,18 @@ export class Registry<A extends RegistryActors> {
 		};
 	}
 
-	#ensureServerlessPoolConfigured(config: RegistryConfig): Promise<void> | undefined {
+	#ensureServerlessPoolConfigured(
+		config: RegistryConfig,
+	): Promise<void> | undefined {
 		if (!config.configurePool) return undefined;
 
 		if (!this.#configureServerlessPoolPromise) {
-			this.#configureServerlessPoolPromise = configureServerlessPool(config).catch(
-				(error) => {
-					this.#configureServerlessPoolPromise = undefined;
-					throw error;
-				},
-			);
+			this.#configureServerlessPoolPromise = configureServerlessPool(
+				config,
+			).catch((error) => {
+				this.#configureServerlessPoolPromise = undefined;
+				throw error;
+			});
 			this.#configureServerlessPoolPromise.catch(() => {});
 		}
 
@@ -106,7 +122,8 @@ export class Registry<A extends RegistryActors> {
 		this.#printWelcome(config, "serverless");
 
 		if (!this.#runtimeServerlessPromise) {
-			this.#runtimeServerlessPromise = buildConfiguredRegistry(config);
+			this.#runtimeServerlessPromise =
+				this.#buildConfiguredRegistry(config);
 		}
 
 		const { runtime, registry, serveConfig } =
@@ -120,12 +137,13 @@ export class Registry<A extends RegistryActors> {
 			serveConfig.serverlessBasePath ?? "/api/rivet",
 		);
 		const isEngineMetadataRequest =
-			request.headers.get("user-agent")?.startsWith("RivetEngine/") ?? false;
+			request.headers.get("user-agent")?.startsWith("RivetEngine/") ??
+			false;
 
 		if (isStartRequest) {
 			try {
 				await this.#ensureServerlessPoolConfigured(config);
-			} catch (error) {
+			} catch (_error) {
 				return new Response(
 					JSON.stringify({
 						group: "guard",
@@ -267,7 +285,7 @@ export class Registry<A extends RegistryActors> {
 		if (isMetadataRequest && !isEngineMetadataRequest) {
 			try {
 				await this.#ensureServerlessPoolConfigured(config);
-			} catch (error) {
+			} catch (_error) {
 				return new Response(
 					JSON.stringify({
 						group: "guard",
@@ -303,6 +321,36 @@ export class Registry<A extends RegistryActors> {
 		};
 	}
 
+	/**
+	 * Starts an HTTP server that dispatches every request through the
+	 * serverless handler. Uses `crossPlatformServe` to pick the right
+	 * runtime (Node, Bun, Deno).
+	 *
+	 * @param opts.port      Port to listen on. Defaults to 3000.
+	 * @param opts.publicDir If set, serves static files from this directory
+	 *                       before falling through to the registry handler.
+	 *
+	 * @example
+	 * ```ts
+	 * await registry.listen();
+	 * await registry.listen({ port: 8080, publicDir: "./public" });
+	 * ```
+	 */
+	public async listen(
+		opts: { port?: number; publicDir?: string } = {},
+	): Promise<void> {
+		const port = opts.port ?? 3000;
+		const config = this.parseConfig();
+		const runtime = detectRuntime();
+		const app = new Hono();
+		if (opts.publicDir) {
+			const serveStatic = await loadRuntimeServeStatic(runtime);
+			app.use("*", serveStatic({ root: opts.publicDir }));
+		}
+		app.all("*", (c) => this.handler(c.req.raw));
+		await crossPlatformServe(config, port, app, runtime);
+	}
+
 	/**
 	 * Returns a health response suitable for mounting in a user-owned router.
 	 */
@@ -392,8 +440,11 @@ export class Registry<A extends RegistryActors> {
 		const candidates = [
 			this.#runtimeServerlessPromise,
 			this.#runtimeServeConfiguredPromise,
-		].filter((candidate): candidate is ReturnType<typeof buildConfiguredRegistry> =>
-			candidate !== undefined
+		].filter(
+			(
+				candidate,
+			): candidate is ReturnType<typeof buildConfiguredRegistry> =>
+				candidate !== undefined,
 		);
 
 		if (candidates.length === 0) return undefined;
@@ -405,35 +456,33 @@ export class Registry<A extends RegistryActors> {
 	 */
 	#startEnvoy(config: RegistryConfig, printWelcome: boolean) {
 		if (!this.#runtimeServePromise) {
-			const configuredRegistryPromise = buildConfiguredRegistry(config);
+			const configuredRegistryPromise =
+				this.#buildConfiguredRegistry(config);
 			this.#runtimeServeConfiguredPromise = configuredRegistryPromise;
 			this.#runtimeServePromise = configuredRegistryPromise
 				.then(async ({ runtime, registry, serveConfig }) => {
 					await runtime.serveRegistry(registry, serveConfig);
 				})
-				.catch((err) => {
+				.catch((error) => {
 					// Always-attached catch so the stored promise never leaves a
 					// rejection unhandled. Downstream awaits (e.g. #runShutdown's
 					// Promise.race) attach their own catches and still observe
 					// resolution via the race.
-					logger().warn({ err }, "runtime registry serve errored");
+					logger().warn({ error }, "runtime registry serve errored");
 				});
 			// Install signal handlers once an envoy lifecycle has begun. Only
 			// Mode A ever reaches here. Mode B (handler(request)) intentionally
 			// does not install handlers because it runs on Workers/Vercel/Deno
 			// Deploy where `process.on` is absent or forbidden; those platforms
 			// own their own signal policy.
-			this.#installSignalHandlers(config, configuredRegistryPromise);
+			this.#installSignalHandlers(config);
 		}
 		if (printWelcome) {
 			this.#printWelcome(config, "serverful");
 		}
 	}
 
-	#installSignalHandlers(
-		config: RegistryConfig,
-		configuredRegistryPromise: ReturnType<typeof buildConfiguredRegistry>,
-	): void {
+	#installSignalHandlers(config: RegistryConfig): void {
 		if (this.#shutdownInstalled) return;
 		if (config.shutdown?.disableSignalHandlers) return;
 		// Guard against non-Node runtimes (Workers/Edge) where `process` may
@@ -448,12 +497,7 @@ export class Registry<A extends RegistryActors> {
 		this.#shutdownInstalled = true;
 
 		const install = (signal: ShutdownSignal) => {
-			const handler = () =>
-				this.#onShutdownSignal(
-					signal,
-					config,
-					configuredRegistryPromise,
-				);
+			const handler = () => this.#onShutdownSignal(signal, config);
 			this.#signalHandlers[signal] = handler;
 			process.on(signal, handler);
 		};
@@ -461,37 +505,67 @@ export class Registry<A extends RegistryActors> {
 		install("SIGTERM");
 	}
 
-	#onShutdownSignal(
-		signal: ShutdownSignal,
-		config: RegistryConfig,
-		configuredRegistryPromise: ReturnType<typeof buildConfiguredRegistry>,
-	): void {
+	#onShutdownSignal(signal: ShutdownSignal, config: RegistryConfig): void {
 		if (this.#shutdownInFlight !== null) {
-			// Second delivery of the same (or another) shutdown signal.
-			// Remove our handler only, preserving any user-installed listeners.
-			// PID 1 must exit directly because re-raised default signals can be
+			// Second delivery of the same (or another) shutdown signal, or a
+			// drain already started by an explicit `shutdown()` call. Remove
+			// our handler only, preserving any user-installed listeners. PID 1
+			// must exit directly because re-raised default signals can be
 			// swallowed by the container signal path.
 			this.#removeSignalHandlers();
 			finishShutdownSignal(signal);
 			return;
 		}
-		this.#shutdownInFlight = this.#runShutdown(
-			signal,
-			config,
-			configuredRegistryPromise,
-		).catch((err) => {
+		this.#shutdownInFlight = this.#drain(config)
+			.catch((err) => {
+				logger().warn({ err }, "shutdown error");
+			})
+			.then(() => {
+				this.#removeSignalHandlers();
+				finishShutdownSignal(signal);
+			});
+	}
+
+	/**
+	 * Gracefully drains all live registries.
+	 *
+	 * Programmatic counterpart to the SIGINT/SIGTERM handlers: tears down
+	 * every live `CoreRegistry` (both `start()` and `handler()` modes) and
+	 * waits for the serve promise to resolve, all bounded by the shutdown
+	 * grace period. Unlike a signal-driven shutdown, this does not re-raise a
+	 * signal or exit the process. The caller owns process lifetime.
+	 *
+	 * Idempotent: concurrent or repeated calls share a single drain. Safe to
+	 * call even if nothing has been started.
+	 *
+	 * @example
+	 * ```ts
+	 * const registry = setup({ use: { counter } });
+	 * registry.start();
+	 * // ...later, on your own shutdown trigger:
+	 * await registry.shutdown();
+	 * ```
+	 */
+	public async shutdown(): Promise<void> {
+		if (this.#shutdownInFlight !== null) return this.#shutdownInFlight;
+		const config = this.parseConfig();
+		// Uninstall our signal handlers so a later SIGINT/SIGTERM does not
+		// re-trigger a drain on already-torn-down registries. Subsequent
+		// signals fall back to Node's default termination behavior.
+		this.#removeSignalHandlers();
+		this.#shutdownInFlight = this.#drain(config).catch((err) => {
 			logger().warn({ err }, "shutdown error");
 		});
+		return this.#shutdownInFlight;
 	}
 
-	async #runShutdown(
-		signal: ShutdownSignal,
-		config: RegistryConfig,
-		configuredRegistryPromise: ReturnType<typeof buildConfiguredRegistry>,
-	): Promise<void> {
+	async #drain(config: RegistryConfig): Promise<void> {
+		const modeAPromise = this.#runtimeServeConfiguredPromise;
+		const modeBPromise = this.#runtimeServerlessPromise;
+
 		const gracePeriodMs =
 			config.shutdown?.gracePeriodMs ??
-			(await this.#actorStopThresholdMs(configuredRegistryPromise)) ??
+			(await this.#actorStopThresholdMs(modeAPromise ?? modeBPromise)) ??
 			30 * 60 * 1000;
 		// Race the entire drain sequence (both modes + serve promise) against
 		// a single grace ceiling. By default, this uses the engine-provided
@@ -499,33 +573,33 @@ export class Registry<A extends RegistryActors> {
 		const drain = async () => {
 			// Shut down every live `CoreRegistry` we know about. Mode A
 			// (`start()`) and Mode B (`handler()`) each build a separate
-			// runtime registry, so one signal handler fans out to both to
-			// honor the spec invariant "single shutdown tears down both modes".
-			const registries: Promise<void>[] = [
-				(async () => {
-					try {
-						const { runtime, registry } =
-							await configuredRegistryPromise;
-						await runtime.shutdownRegistry(registry);
-					} catch (err) {
-						logger().warn(
-							{ err },
-							"runtime registry shutdown errored (mode A)",
-						);
-					}
-				})(),
-			];
-			const runtimeServerlessPromise = this.#runtimeServerlessPromise;
-			if (runtimeServerlessPromise !== undefined) {
+			// runtime registry, so one drain fans out to both to honor the
+			// spec invariant "single shutdown tears down both modes".
+			const registries: Promise<void>[] = [];
+			if (modeAPromise !== undefined) {
 				registries.push(
 					(async () => {
 						try {
-							const { runtime, registry } =
-								await runtimeServerlessPromise;
+							const { runtime, registry } = await modeAPromise;
 							await runtime.shutdownRegistry(registry);
 						} catch (err) {
 							logger().warn(
 								{ err },
+								"runtime registry shutdown errored (mode A)",
+							);
+						}
+					})(),
+				);
+			}
+			if (modeBPromise !== undefined) {
+				registries.push(
+					(async () => {
+						try {
+							const { runtime, registry } = await modeBPromise;
+							await runtime.shutdownRegistry(registry);
+						} catch (err) {
+							logger().warn(
+								{ error: err },
 								"runtime registry shutdown errored (mode B)",
 							);
 						}
@@ -548,13 +622,14 @@ export class Registry<A extends RegistryActors> {
 				setTimeout(resolve, gracePeriodMs).unref?.(),
 			),
 		]);
-		this.#removeSignalHandlers();
-		finishShutdownSignal(signal);
 	}
 
 	async #actorStopThresholdMs(
-		configuredRegistryPromise: ReturnType<typeof buildConfiguredRegistry>,
+		configuredRegistryPromise:
+			| ReturnType<typeof buildConfiguredRegistry>
+			| undefined,
 	): Promise<number | undefined> {
+		if (configuredRegistryPromise === undefined) return undefined;
 		try {
 			const { runtime, registry } = await configuredRegistryPromise;
 			const thresholdMs =
@@ -646,7 +721,10 @@ function isServerlessStartRequest(request: Request, basePath: string): boolean {
 	return parsed.pathname === `${normalizedBase}/start`;
 }
 
-function isServerlessMetadataRequest(request: Request, basePath: string): boolean {
+function isServerlessMetadataRequest(
+	request: Request,
+	basePath: string,
+): boolean {
 	if (request.method !== "GET") return false;
 	const parsed = new URL(request.url);
 	const normalizedBase =