rivetkit 2.3.30 → 3.0.0-preview.2

package/src/registry/config/index.ts

@@ -158,7 +158,7 @@ export const RegistryConfigSchema = z
 		// // created or must be imported async using `await import(...)`
 		// getUpgradeWebSocket: z.custom<GetUpgradeWebSocket>().optional(),
 
-		// MARK: Runner Configuration
+		// MARK: Node Configuration
 		/**
 		 * Endpoint to connect to for Rivet Engine.
 		 *
@@ -251,14 +251,14 @@ export const RegistryConfigSchema = z
 			.default(() => getRivetRunEngineVersion() ?? VERSION),
 		/**
 		 * Starts the first-party Services actor host when RivetKit manages
-		 * a local engine. Defaults to the local-engine decision. Set
-		 * RIVET_RUN_SERVICES=0 or 1 to override it.
+		 * a local engine. Disabled by default. Set RIVET_RUN_SERVICES=1
+		 * or startServices: true to enable it.
 		 */
 		startServices: z.boolean().optional(),
 		/**
 		 * @experimental
 		 *
-		 * Automatically configure serverless envoys in the engine.
+		 * Automatically configure serverless nodes in the engine.
 		 */
 		configurePool: ConfigurePoolSchema.optional(),
 
@@ -266,7 +266,7 @@ export const RegistryConfigSchema = z
 		serverless: ServerlessConfigSchema.optional().default(() =>
 			ServerlessConfigSchema.parse({}),
 		),
-		envoy: EnvoyConfigSchema.optional().default(() =>
+		node: EnvoyConfigSchema.optional().default(() =>
 			EnvoyConfigSchema.parse({}),
 		),
 
@@ -274,9 +274,9 @@ export const RegistryConfigSchema = z
 		/**
 		 * Graceful shutdown configuration for SIGINT/SIGTERM.
 		 *
-		 * When a persistent envoy is running (Mode A, started via `registry.start()`),
+		 * When a persistent node is running (Mode A, started via `registry.start()`),
 		 * rivetkit installs Node SIGINT/SIGTERM handlers that call into core's
-		 * `shutdown()` and wait up to `gracePeriodMs` for the envoy to drain
+		 * `shutdown()` and wait up to `gracePeriodMs` for the node to drain
 		 * before re-raising the signal to let Node exit via its default path.
 		 *
 		 * Handlers are NOT installed when `handler(request)` is used alone
@@ -289,9 +289,11 @@ export const RegistryConfigSchema = z
 				/**
 				 * Wait this many milliseconds for the serve promise to resolve
 				 * after calling `CoreRegistry::shutdown()`. Defaults to the
-				 * engine-provided actor stop threshold once the envoy connects.
+				 * engine-provided actor stop threshold once the node connects. A
+				 * signal-driven shutdown of a managed local development engine waits
+				 * one second by default so a file watcher can restart promptly.
 				 *
-				 * Must be long enough for rivetkit-core to drain the envoy.
+				 * Set a longer period when a complete graceful node drain is required.
 				 */
 				gracePeriodMs: z.number().int().min(1_000).optional(),
 				/**
@@ -348,12 +350,12 @@ export const RegistryConfigSchema = z
 			});
 		}
 
-		// configurePool requires an engine (via endpoint or startEngine).
-		if (config.configurePool && !parsedEndpoint && !config.startEngine) {
+		// Serverless pool configuration is disabled for v3.
+		if (config.configurePool) {
 			ctx.addIssue({
 				code: "custom",
-				message:
-					"configurePool requires either endpoint or startEngine",
+				message: "serverless is disabled in this version",
+				path: ["configurePool"],
 			});
 		}
 
@@ -366,13 +368,7 @@ export const RegistryConfigSchema = z
 			? localEngineEndpoint
 			: (parsedEndpoint?.endpoint ??
 				(isDevEnv ? localEngineEndpoint : undefined));
-		// Services is another local development actor host. Its default
-		// follows the same local-endpoint decision that causes core to manage the
-		// Engine, while explicit config and RIVET_RUN_SERVICES take precedence.
-		const startServices =
-			config.startServices ??
-			getRivetRunServices() ??
-			Boolean(endpoint && isLocalEngineEndpoint(endpoint));
+		const startServices = config.startServices ?? getRivetRunServices();
 		const validateServerlessEndpoint = Boolean(
 			config.startEngine || parsedEndpoint,
 		);
@@ -422,6 +418,7 @@ export const RegistryConfigSchema = z
 			...config,
 			sqlite,
 			endpoint,
+			engineSpawn: !parsedEndpoint && Boolean(endpoint),
 			startServices,
 			namespace,
 			token,
@@ -468,10 +465,10 @@ export function buildActorNames(
 
 export const DocConfigurePoolSchema = z
 	.object({
-		name: z.string().optional().describe("Name of the runner pool."),
+		name: z.string().optional().describe("Name of the node pool."),
 		url: z
 			.string()
-			.describe("URL of the serverless platform to configure runners."),
+			.describe("URL of the serverless platform to configure nodes."),
 		headers: z
 			.record(z.string(), z.string())
 			.optional()
@@ -504,7 +501,7 @@ export const DocConfigurePoolSchema = z
 			.boolean()
 			.optional()
 			.describe(
-				"Drain runners when a new version is deployed. Defaults to true.",
+				"Drain nodes when a new version is deployed. Defaults to true.",
 			),
 	})
 	.optional();
@@ -547,17 +544,17 @@ export const DocEnvoyConfigSchema = z
 		poolName: z
 			.string()
 			.optional()
-			.describe("Name of this envoy pool. Default: 'default'"),
-		envoyKey: z
+			.describe("Name of this node pool. Default: 'default'"),
+		nodeKey: z
 			.string()
 			.optional()
-			.describe("Deprecated. Authentication key for the envoy."),
+			.describe("Deprecated. Authentication key for the node."),
 		version: z
 			.number()
 			.optional()
-			.describe("Version number of this envoy. Default: 1"),
+			.describe("Version number of this node. Default: 1"),
 	})
-	.describe("Configuration for envoy mode.");
+	.describe("Configuration for node mode.");
 
 export const DocSqliteConfigSchema = z
 	.object({
@@ -658,12 +655,12 @@ export const DocRegistryConfigSchema = z
 			.boolean()
 			.optional()
 			.describe(
-				"Starts Services when RivetKit manages a local Engine. Defaults to the local-Engine decision. Set RIVET_RUN_SERVICES=0 or 1 to override.",
+				"Starts Services when RivetKit manages a local Engine. Disabled by default. Set RIVET_RUN_SERVICES=1 or startServices: true to enable.",
 			),
 		configurePool: DocConfigurePoolSchema.describe(
-			"Automatically configure serverless runners in the engine.",
+			"Automatically configure serverless nodes in the engine.",
 		),
 		serverless: DocServerlessConfigSchema.optional(),
-		envoy: DocEnvoyConfigSchema.optional(),
+		node: DocEnvoyConfigSchema.optional(),
 	})
 	.describe("RivetKit registry configuration.");

package/src/registry/index.ts

@@ -30,6 +30,11 @@ type ShutdownSignal = "SIGINT" | "SIGTERM";
 
 const REGISTRY_READY_TIMEOUT_MS = 30_000;
 
+// Serverless is disabled for v3; keep the implementation for a later release.
+function rejectServerless(): void {
+	throw new Error("serverless is disabled in this version");
+}
+
 function signalExitCode(signal: ShutdownSignal): number {
 	switch (signal) {
 		case "SIGINT":
@@ -190,6 +195,7 @@ export class Registry<A extends RegistryActors> {
 		config: RegistryConfig,
 	): Promise<void> | undefined {
 		if (!config.configurePool) return undefined;
+		rejectServerless();
 
 		if (!this.#configureServerlessPoolPromise) {
 			this.#configureServerlessPoolPromise = configureServerlessPool(
@@ -215,6 +221,7 @@ export class Registry<A extends RegistryActors> {
 	 * ```
 	 */
 	public async handler(request: Request): Promise<Response> {
+		rejectServerless();
 		const config = this.parseConfig();
 		this.#printWelcome(config, "serverless");
 
@@ -413,6 +420,7 @@ export class Registry<A extends RegistryActors> {
 	 * ```
 	 */
 	public serve(): ServerlessHandler {
+		rejectServerless();
 		return {
 			fetch: (request) => this.handler(request),
 		};
@@ -438,6 +446,9 @@ export class Registry<A extends RegistryActors> {
 	 * ```
 	 */
 	public async listen(opts: RegistryListenOptions = {}): Promise<void> {
+		if (!opts.application) {
+			rejectServerless();
+		}
 		const port = opts.port ?? parsePortEnv(process.env.RIVET_PORT) ?? 3000;
 		const publicDir = opts.publicDir ?? getRivetkitPublicDir();
 		const config = this.parseConfig();
@@ -554,6 +565,7 @@ export class Registry<A extends RegistryActors> {
 	 * Returns serverless metadata suitable for mounting in a user-owned router.
 	 */
 	async #metadataRoute(): Promise<Response> {
+		rejectServerless();
 		const configured = await this.#activeConfiguredRegistry();
 		if (!configured) {
 			return new Response("registry not started\n", {
@@ -626,7 +638,7 @@ export class Registry<A extends RegistryActors> {
 	 */
 	#startEnvoy(config: RegistryConfig, printWelcome: boolean) {
 		if (!this.#runtimeServePromise) {
-			const configuredEnvoyVersion = this.#config.envoy?.version;
+			const configuredEnvoyVersion = this.#config.node?.version;
 			const envoyVersionSource =
 				configuredEnvoyVersion !== undefined
 					? "config"
@@ -637,7 +649,7 @@ export class Registry<A extends RegistryActors> {
 			logger().info({
 				msg: "starting rivetkit envoy",
 				rivetkitVersion: VERSION,
-				envoyVersion: config.envoy.version,
+				envoyVersion: config.node.version,
 				envoyVersionSource,
 			});
 
@@ -646,8 +658,8 @@ export class Registry<A extends RegistryActors> {
 				getNodeEnv() === "production"
 			) {
 				logger().error({
-					msg: "envoy version defaulted because neither config.envoy.version nor RIVET_ENVOY_VERSION is set; actors will not drain automatically across deploys. See https://rivet.dev/docs/actors/versions",
-					envoyVersion: config.envoy.version,
+					msg: "node version defaulted because neither config.node.version nor RIVET_NODE_VERSION is set; actors will not drain automatically across deploys. See https://rivet.dev/docs/actors/versions",
+					envoyVersion: config.node.version,
 					envoyVersionSource,
 				});
 			}
@@ -666,7 +678,13 @@ export class Registry<A extends RegistryActors> {
 					// rejection unhandled. Downstream awaits (e.g. #runShutdown's
 					// Promise.race) attach their own catches and still observe
 					// resolution via the race.
-					logger().warn({ error }, "runtime registry serve errored");
+					logger().error({ error }, "runtime registry serve errored");
+					if (
+						typeof process !== "undefined" &&
+						typeof process.exit === "function"
+					) {
+						process.exit(1);
+					}
 				});
 			// Install signal handlers once an envoy lifecycle has begun. Only
 			// Mode A ever reaches here. Mode B (handler(request)) intentionally
@@ -714,7 +732,7 @@ export class Registry<A extends RegistryActors> {
 			finishShutdownSignal(signal);
 			return;
 		}
-		this.#shutdownInFlight = this.#drain(config)
+		this.#shutdownInFlight = this.#drain(config, true)
 			.catch((err) => {
 				logger().warn({ err }, "shutdown error");
 			})
@@ -757,18 +775,28 @@ export class Registry<A extends RegistryActors> {
 		return this.#shutdownInFlight;
 	}
 
-	async #drain(config: RegistryConfig): Promise<void> {
+	async #drain(config: RegistryConfig, signalDriven = false): Promise<void> {
 		const modeAPromise = this.#runtimeServeConfiguredPromise;
 		const modeBPromise = this.#runtimeServerlessPromise;
 		const runtimes = new Set<CoreRuntime>();
 
-		const gracePeriodMs =
-			config.shutdown?.gracePeriodMs ??
-			(await this.#actorStopThresholdMs(modeAPromise ?? modeBPromise)) ??
-			30 * 60 * 1000;
+		const localDevSignal =
+			signalDriven &&
+			getNodeEnv() !== "production" &&
+			config.engineSpawn &&
+			config.endpoint !== undefined &&
+			isLocalEngineEndpoint(config.endpoint);
+		let gracePeriodMs = config.shutdown?.gracePeriodMs;
+		if (gracePeriodMs === undefined) {
+			gracePeriodMs = localDevSignal
+				? 1_000
+				: ((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
-		// actor stop threshold, matching Pegboard's hard cutoff for actors.
+		// a single grace ceiling. Local dev signal shutdowns allow the watcher
+		// to restart promptly; other shutdowns use the engine's actor stop threshold.
 		const drain = async () => {
 			// Shut down every live `CoreRegistry` we know about. Mode A
 			// (`start()`) and Mode B (`handler()`) each build a separate
@@ -887,12 +915,16 @@ export class Registry<A extends RegistryActors> {
 			);
 		}
 		if (this.#runtimeReadyPromise) return this.#runtimeReadyPromise;
-		if (getRivetkitRuntimeMode() === "serverless") {
-			return Promise.reject(
-				new Error(
-					"registry.startAndWait() requires envoy runtime mode; serverless registries become ready per request",
-				),
-			);
+		try {
+			if (getRivetkitRuntimeMode() === "serverless") {
+				return Promise.reject(
+					new Error(
+						"registry.startAndWait() requires envoy runtime mode; serverless registries become ready per request",
+					),
+				);
+			}
+		} catch (error) {
+			return Promise.reject(error);
 		}
 
 		const config = this.parseConfig();

package/src/registry/napi-runtime.ts

@@ -481,8 +481,9 @@ export class NapiCoreRuntime implements CoreRuntime {
 	onCancellationTokenCancelled(
 		token: CancellationTokenHandle,
 		callback: (...args: unknown[]) => unknown,
-	): void {
-		asNativeCancellationToken(token).onCancelled(callback);
+	): () => void {
+		const listener = asNativeCancellationToken(token).onCancelled(callback);
+		return () => listener.release();
 	}
 
 	actorState(ctx: ActorContextHandle): Buffer {

package/src/registry/native.ts

@@ -26,6 +26,7 @@ import {
 } from "@/actor/config";
 import type { AnyActorDefinition } from "@/actor/definition";
 import {
+	actorStopping,
 	decodeBridgeRivetError,
 	encodeBridgeRivetError,
 	forbiddenError,
@@ -126,6 +127,7 @@ import type {
 	RuntimeStateDeltaPayload,
 	WebSocketHandle,
 } from "./runtime";
+import { servicesBinaryUnavailable } from "./runtime";
 import { loadWasmRuntime } from "./wasm-runtime";
 import {
 	createWriteThroughProxy,
@@ -347,6 +349,11 @@ type NativeDestroyGate = {
 type NativeDatabaseClientState = {
 	client: unknown;
 };
+type NativeActorAbort = {
+	signal: AbortSignal;
+	listeners: Set<() => void>;
+};
+
 type NativeActorRuntimeState = {
 	sql?: ReturnType<typeof wrapJsNativeDatabase>;
 	databaseClient?: NativeDatabaseClientState;
@@ -354,6 +361,17 @@ type NativeActorRuntimeState = {
 	vars?: unknown;
 	destroyGate?: NativeDestroyGate;
 	persistState?: NativePersistActorState;
+	// One native actor abort signal shared by every context of the actor. Each
+	// native signal parks a task and a callback handle until the actor stops,
+	// so creating one per request or action leaks both. Per-context listeners
+	// live in `listeners` so the shared signal never collects one listener per
+	// in-flight request.
+	actorAbort?: NativeActorAbort;
+	// Set once shutdown cleanup has cleared this generation's caches. Work that
+	// outlives the generation, such as an untracked timer or a late WebSocket
+	// message handler, then fails with `actor.stopping` instead of reading an
+	// empty bag as if `vars` or the database were never initialized.
+	cleared?: true;
 };
 
 // Keep JS-only actor caches on the NAPI ActorContext runtime-state bag instead
@@ -363,9 +381,10 @@ function getNativeRuntimeState(
 	runtime: CoreRuntime,
 	ctx: ActorContextHandle,
 ): NativeActorRuntimeState {
-	const runtimeState = callNativeSync(() =>
-		runtime.actorRuntimeState(ctx),
-	) as NativeActorRuntimeState;
+	const runtimeState = readNativeRuntimeStateBag(runtime, ctx);
+	if (runtimeState.cleared) {
+		throw actorStopping(callNativeSync(() => runtime.actorId(ctx)));
+	}
 	if (!runtimeState.destroyGate) {
 		runtimeState.destroyGate = {};
 	}
@@ -379,6 +398,22 @@ function getNativeRuntimeState(
 	return runtimeState;
 }
 
+function readNativeRuntimeStateBag(
+	runtime: CoreRuntime,
+	ctx: ActorContextHandle,
+): NativeActorRuntimeState {
+	return callNativeSync(() =>
+		runtime.actorRuntimeState(ctx),
+	) as NativeActorRuntimeState;
+}
+
+function isNativeRuntimeStateCleared(
+	runtime: CoreRuntime,
+	ctx: ActorContextHandle,
+): boolean {
+	return readNativeRuntimeStateBag(runtime, ctx).cleared === true;
+}
+
 function getNativePersistState(
 	runtime: CoreRuntime,
 	ctx: ActorContextHandle,
@@ -521,7 +556,18 @@ function clearNativeRuntimeState(
 	runtime: CoreRuntime,
 	ctx: ActorContextHandle,
 ) {
+	// A coalesced save armed before the clear would otherwise fire against the
+	// cleared bag and throw outside any caller.
+	const pendingSaveHandle = readNativeRuntimeStateBag(runtime, ctx)
+		.persistState?.pendingSaveHandle;
+	if (pendingSaveHandle !== undefined) {
+		clearImmediate(pendingSaveHandle);
+	}
 	callNativeSync(() => runtime.actorClearRuntimeState(ctx));
+	// The runtime hands out a fresh bag after a clear. Each generation has its
+	// own bag, so marking it makes later access from this generation fail typed
+	// without touching any newer generation of the same actor.
+	readNativeRuntimeStateBag(runtime, ctx).cleared = true;
 }
 
 async function cleanupNativeSleepRuntimeState(
@@ -536,8 +582,7 @@ async function cleanupNativeSleepRuntimeState(
 	// the tracked work finishes without a deadline.
 	const drained = await runtime.actorWaitForTrackedShutdownWork(ctx);
 	if (!drained) {
-		await closeNativeDatabaseClient(runtime, ctx);
-		await closeNativeSqlDatabase(runtime, ctx);
+		await detachNativeDatabaseForShutdown(runtime, ctx);
 		void runtime
 			.actorWaitForTrackedShutdownWorkUnbounded(ctx)
 			.then(async () => {
@@ -554,11 +599,26 @@ async function cleanupNativeSleepRuntimeState(
 	}
 
 	await afterTrackedWorkDrained?.();
-	await closeNativeDatabaseClient(runtime, ctx);
-	await closeNativeSqlDatabase(runtime, ctx);
+	await detachNativeDatabaseForShutdown(runtime, ctx);
 	clearNativeRuntimeState(runtime, ctx);
 }
 
+async function detachNativeDatabaseForShutdown(
+	runtime: CoreRuntime,
+	ctx: ActorContextHandle,
+): Promise<void> {
+	const runtimeState = getNativeRuntimeState(runtime, ctx);
+	// Stop JS access without closing the runtime-owned SQLite backend. Rust still
+	// needs it to reconcile scheduled alarms and performs the physical close after
+	// this lifecycle callback returns.
+	await runtimeState.sql?.detachForShutdown();
+	try {
+		await closeNativeDatabaseClient(runtime, ctx);
+	} finally {
+		runtimeState.sql = undefined;
+	}
+}
+
 function closeNativeSqlDatabase(
 	runtime: CoreRuntime,
 	ctx: ActorContextHandle,
@@ -784,7 +844,7 @@ async function loadEngineCli(): Promise<typeof import("@rivetkit/engine-cli")> {
 	return import(["@rivetkit", "engine-cli"].join("/"));
 }
 
-async function loadServices(): Promise<typeof import("@rivet-dev/services")> {
+async function loadServices(): Promise<{ getServicesPath: () => string }> {
 	// Keep the native binary opaque to edge bundlers for the same reason as
 	// engine-cli above.
 	return import(["@rivet-dev", "services"].join("/"));
@@ -3022,22 +3082,28 @@ export class ActorContextHandleAdapter {
 
 	get abortSignal(): AbortSignal {
 		if (!this.#abortSignal) {
-			const actorSignal = this.#createActorAbortSignal();
+			const actorAbort = this.#actorAbort();
+			const actorSignal = actorAbort.signal;
 			if (this.#dispatchCancelToken === undefined) {
 				this.#abortSignal = actorSignal;
 			} else {
 				const controller = new AbortController();
 				let cleanedUp = false;
+				let releaseDispatchListener: (() => void) | undefined;
 				const onActorAbort = () => {
 					cleanup();
 					controller.abort();
 				};
+				// Releasing the native listener on dispose frees it even when the
+				// dispatch token is never cancelled.
 				const cleanup = () => {
 					if (cleanedUp) {
 						return;
 					}
 					cleanedUp = true;
-					actorSignal.removeEventListener("abort", onActorAbort);
+					actorAbort.listeners.delete(onActorAbort);
+					releaseDispatchListener?.();
+					releaseDispatchListener = undefined;
 					this.#abortSignalCleanup = undefined;
 				};
 
@@ -3051,10 +3117,8 @@ export class ActorContextHandleAdapter {
 				} else {
 					const dispatchCancelToken = this.#dispatchCancelToken;
 					this.#abortSignalCleanup = cleanup;
-					actorSignal.addEventListener("abort", onActorAbort, {
-						once: true,
-					});
-					callNativeSync(() =>
+					actorAbort.listeners.add(onActorAbort);
+					releaseDispatchListener = callNativeSync(() =>
 						this.#runtime.onCancellationTokenCancelled(
 							dispatchCancelToken,
 							() => {
@@ -3506,24 +3570,49 @@ export class ActorContextHandleAdapter {
 
 	async dispose(): Promise<void> {
 		// Flush any save coalesced for this tick before the context is torn
-		// down so the request-save and onStateChange always run.
-		this.#flushStateChange();
+		// down so the request-save and onStateChange always run. Shutdown
+		// cleanup may already have cleared the generation, which leaves no
+		// pending save to flush.
+		if (!isNativeRuntimeStateCleared(this.#runtime, this.#ctx)) {
+			this.#flushStateChange();
+		}
 		this.#abortSignalCleanup?.();
 	}
 
-	#createActorAbortSignal(): AbortSignal {
+	#actorAbort(): NativeActorAbort {
+		// An aborted cached signal may belong to a previous generation, so
+		// only a live one is reused.
+		const runtimeState = readNativeRuntimeStateBag(
+			this.#runtime,
+			this.#ctx,
+		);
+		const cached = runtimeState.actorAbort;
+		if (cached && !cached.signal.aborted) {
+			return cached;
+		}
+
 		const nativeSignal = callNativeSync(() =>
 			this.#runtime.actorAbortSignal(this.#ctx),
 		);
 		const controller = new AbortController();
-		if (nativeSignal.aborted) {
+		const actorAbort: NativeActorAbort = {
+			signal: controller.signal,
+			listeners: new Set(),
+		};
+		const abort = () => {
 			controller.abort();
+			for (const listener of actorAbort.listeners) {
+				listener();
+			}
+			actorAbort.listeners.clear();
+		};
+		if (nativeSignal.aborted) {
+			abort();
 		} else {
-			nativeSignal.addEventListener("abort", () => controller.abort(), {
-				once: true,
-			});
+			nativeSignal.addEventListener("abort", abort, { once: true });
 		}
-		return controller.signal;
+		runtimeState.actorAbort = actorAbort;
+		return actorAbort;
 	}
 
 	#readState(): unknown {
@@ -4846,7 +4935,7 @@ export function buildNativeFactory(
 					}
 				} finally {
 					resolveNativeDestroy(runtime, ctx);
-					await actorCtx.closeDatabase();
+					await detachNativeDatabaseForShutdown(runtime, ctx);
 					clearNativeRuntimeState(runtime, ctx);
 					await actorCtx.dispose();
 				}
@@ -5598,11 +5687,12 @@ export async function buildServeConfig(
 	}
 
 	const serveConfig: RuntimeServeConfig = {
-		version: config.envoy.version,
+		version: config.node.version,
 		endpoint: config.endpoint,
+		engineSpawn: config.engineSpawn,
 		token: config.token,
 		namespace: config.namespace,
-		poolName: config.envoy.poolName,
+		poolName: config.node.poolName,
 		startServices: resolveServicesBinary && config.startServices,
 		handleInspectorHttpInRuntime: true,
 		serverlessBasePath: config.serverless.basePath,
@@ -5616,7 +5706,7 @@ export async function buildServeConfig(
 
 	// Always best-effort resolve the npm-installed engine binary and hand its
 	// path to the core. The core alone decides whether to actually spawn a local
-	// engine (its `should_manage_engine`, based on the endpoint + spawn mode), so
+	// engine using the resolved spawn decision, so
 	// JS must not duplicate that decision here. Only JS knows the npm
 	// `node_modules` layout, so it resolves the path; if no binary is available
 	// (remote-only install, unsupported platform, optional deps skipped), leave
@@ -5636,14 +5726,16 @@ export async function buildServeConfig(
 		});
 	}
 	if (resolveServicesBinary && config.startServices) {
-		try {
-			const { getServicesPath } = await loadServices();
-			serveConfig.servicesBinaryPath = getServicesPath();
-		} catch (error) {
-			logger().warn({
-				msg: "could not resolve the Services binary; a local engine will fail with services.binary_unavailable — set RIVET_RUN_SERVICES=0 to disable Services or RIVET_SERVICES_BINARY to a local rivet-services binary",
-				error: stringifyError(error),
-			});
+		const servicesBinary = getEnvUniversal("RIVET_SERVICES_BINARY");
+		if (servicesBinary) {
+			serveConfig.servicesBinaryPath = servicesBinary;
+		} else {
+			try {
+				const { getServicesPath } = await loadServices();
+				serveConfig.servicesBinaryPath = getServicesPath();
+			} catch (error) {
+				throw servicesBinaryUnavailable(error);
+			}
 		}
 	}
 	serveConfig.engineHost = config.engineHost;