fix(rivetkit): preserve query gateway skip ready wait

[NathanFlurry]

Stack Context

Standalone fix for query-backed RivetKit gateway requests with skipReadyWait.

What?

• Keeps query-backed actor handles on the gateway rvt-* URL path when skipReadyWait is enabled.
• Preserves direct actor ID optimized routing for normal getForId handles.
• Adds HTTP and websocket regression coverage for query-backed skip-ready-wait routing.

Why?

skipReadyWait was causing query-backed handles to resolve through the actor API first, which turned a single gateway round trip into an extra resolve/create request. The gateway URL path already supports rvt-skip-ready-wait, so the client should pass the query through and let the gateway resolve it.

Verification

• pnpm --dir rivetkit-typescript/packages/rivetkit exec vitest run tests/remote-engine-client-public-token.test.ts
• pnpm --dir rivetkit-typescript/packages/rivetkit exec tsc --noEmit --pretty false
• git diff --check

[railway-app]

🚅 Deployed to the rivet-pr-5008 environment in rivet-frontend

Service	Status	Web	Updated (UTC)
kitchen-sink	❌ Build Failed (View Logs)	Web	May 9, 2026 at 7:33 am
website	😴 Sleeping (View Logs)	Web	May 9, 2026 at 6:39 am
frontend-cloud	❌ Build Failed (View Logs)	Web	May 9, 2026 at 6:34 am
frontend-inspector	❌ Build Failed (View Logs)	Web	May 9, 2026 at 6:33 am
ladle	❌ Build Failed (View Logs)	Web	May 9, 2026 at 6:28 am
mcp-hub	✅ Success (View Logs)	Web	May 9, 2026 at 6:28 am

[NathanFlurry]

• feat(envoy-client): add ping health check #5001
• chore(engine): roxiproxi tests #4864
• fix(rivetkit): preserve query gateway skip ready wait #5008 👈 (View in Graphite)
• fix(depot-client): only fatal sqlite vfs on fence mismatch #5007 : 1 other dependent PR (#5009 )
• fix(rivetkit): preserve internal bridge errors #4993 : 1 other dependent PR (#4997 )
• fix(sqlite): quiet startup database miss #5005
• refactor(metrics): split server metrics crate #5004 : 1 other dependent PR (#5006 )
• fix(rivetkit): use unbounded actor channels #5003
• chore(envoy-client): add envoy key tracing context #5002
• chore(rivetkit): rewrite work registry + fix waituntil not preventing sleep #4990
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[claude]

Code Review

Overview

This PR fixes two related bugs where skipReadyWait for query-backed actor handles (e.g., getOrCreate) was causing an unnecessary extra resolve/create round trip to the actor API before the real gateway request. The gateway already supports rvt-skip-ready-wait in the URL query params, so the client should pass the query through and let the gateway handle resolution.

---

Bug Fix Correctness

actor-conn.ts — The removed #resolveGatewayTargetForSkipReadyWait() was calling resolveGatewayTarget() (i.e., the actor API) for query-backed handles under skipReadyWait, defeating its own purpose. Replacing it with an unconditional getGatewayTarget(this.#actorResolutionState) is correct since getGatewayTarget already handles the getForId case by returning a directId target.

actor-handle.ts — inverted condition was a real bug. The old WebSocket path had:

const target = gatewayOptions.skipReadyWait
    ? await this.#resolveActionTarget(false)   // resolved through API when skipReadyWait=true — wrong
    : getGatewayTarget(this.#actorResolutionState);  // used query target when skipReadyWait=false — wrong

The new #resolveGatewayRequestTarget helper corrects this and unifies the logic across HTTP, queue, and WebSocket paths. Good cleanup.

---

Issues

Test isolation: new WebSocket coverage is appended inside an existing test.

The HTTP test is correctly a standalone test() block. But the WebSocket coverage was appended at the end of "uses metadata clientToken for actor websocket gateway requests", relying on mocks, globals, and socket counts (expect(sockets).toHaveLength(4)) established earlier in that test. This has a few problems:

• If the parent test ever gains another WebSocket call, the toHaveLength(4) assertion will fail for an unrelated reason.
• The new scenario can't be run or debugged in isolation via a Vitest filter.
• It makes the existing test harder to read — it now tests two distinct behaviors.

Recommend extracting the new scenario into its own test("query handle websocket keeps skip ready wait on gateway URL", ...) that sets up its own sockets array and mocks, following the same pattern as the HTTP test added in this same PR.

---

Minor Notes

• Import reordering (createClient moved up) is a nice touch for consistency.
• The resolveGatewayTarget import removal from actor-conn.ts is correct — it was only used by the deleted method.
• #resolveGatewayRequestTarget takes gatewayOptions as a parameter rather than closing over this.#gatewayOptions — this is fine since callers already have the resolved options in scope and it keeps the method pure.

---

Summary

The core fix is correct and the simplification is an improvement. The one thing worth addressing before merge is extracting the WebSocket regression test into its own test() block for isolation and readability.