fix(rivetkit): refresh stale actor handles

[NathanFlurry]

Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

[NathanFlurry]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• fix(test): stabilize lifecycle, sleep, queue, and run edge cases #4660 : 2 dependent PRs (#4664 , #4665 )
• test(rivetkit): re-enable gateway URL and direct-registry coverage #4659
• fix(rivetkit): keep internal error exposure behavior consistent #4661
• fix(rivetkit): add lifecycle error retry and gateway HTTP routing #4666
• fix(rivetkit-core): remove legacy timeouts #4799
• chore: add CLAUDE.md guidance on test fixtures, SDK regen, and TS client layer #4796
• fix(inspector): stream patched state updates #4795
• fix(rivetkit): refresh stale actor handles #4794 👈 (View in Graphite)
• test(rivetkit-napi): move private tests to crate root #4793
• test(rivetkit-core): move private tests to crate root #4792
• test(runner-configs): assert envoy protocol version #4791
• fix(serverless): split metadata protocol errors #4789 : 1 other dependent PR (#4790 )
• chore(sqlite): add open close lifecycle for envoy actors #4788
• fix(rivetkit): share lifecycle shutdown grace #4810
• fix(pegboard): move sqlite v1 migration into actor workflow #4787 : 1 other dependent PR (#4797 )
• test(rivetkit): cover c.db access from onWake/onSleep/onDestroy #4786
• fix(rivetkit-napi): run onMigrate before createState/onCreate/createVars #4785
• refactor(rivetkit-core): merge ready+started into lifecycle_started, drop redundant napi calls #4784
• fix(rivetkit): drain native sleep side tasks reliably #4782 : 1 other dependent PR (#4783 )
• fix(rivetkit): route raw request fetches to actors #4781
• fix(pegboard): refresh runner config after envoy connect #4778 : 2 other dependent PRs (#4779 , #4798 )
• chore(kitchen-sink): configurable endpoint #4766 : 2 other dependent PRs (#4754 , #4777 )
• refactor(rivetkit-core): rename StopReason to ShutdownKind and kill enum fallthroughs #4765
• chore(envoy-client): log command and event payloads #4751
• fix(rivetkit): minor sleep-cleanup follow-ups #4761
• docs(rivetkit): clean up stale setPreventSleep references in docs and JSDoc #4760
• docs(rivetkit): document keepAwake/waitUntil counter-arm race and surface bridge errors #4759
• test(engine): force overdue branch in alarm-during-sleep test with negative offset #4758
• fix(rivetkit-core): return stopping not starting when sleep/destroy called mid-shutdown #4757
• test(rivetkit): remove sleepWithPreventSleep fixture and tests #4756
• test(engine): add regression test for alarm-during-sleep-transition race #4755
• test(rivetkit-core): cover sleep/destroy guards and prevent_sleep no-op #4750
• docs: add keepAwake vs waitUntil table and internal sleep-sequence invariants #4749
• feat(rivetkit): expose c.keepAwake(promise) through native path #4748
• refactor(rivetkit): deprecate setPreventSleep to no-op in TypeScript #4747
• fix(rivetkit-core): enumerate non-drained counters in grace deadline warn log #4746
• fix(rivetkit-core): abort graceful cleanup task when grace deadline elapses #4745
• fix(rivetkit-core): error on sleep/destroy before startup or already-requested #4743
• fix(rivetkit-core): cap SerializeState shutdown timeout at 15s #4742
• refactor(rivetkit-core): remove prevent_sleep field and deprecate set_prevent_sleep to no-op #4741
• fix(api-public): remove orphan import_export actors module #4764
• main

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

[claude]

PR #4794 Review: fix(rivetkit): refresh stale actor handles

Files changed: 2 TypeScript files, 110 additions, 61 deletions.

Summary: Wraps #sendQueueMessage in an AsyncMutex to serialize concurrent queue sends; adds #shouldRetryQueueDispatchOverload to retry on actor/overloaded; adds not_configured and dropped_reply to the stale-actor error set in both actor-handle.ts and actor-query.ts.

---

Issues Found

1. Severe throughput regression: mutex serializes all concurrent queue sends

The entire #sendQueueMessage body, including the retry loop and each #waitForRetryWindow() call, runs inside #queueSendMutex.run(...). All concurrent send() calls on the same ActorHandleRaw instance are now fully serialized — happy-path sends (no retries needed) still queue up behind each other.

#waitForRetryWindow() sleeps 100 ms per attempt; with max attempt counts of 24 (getForKey) and 60 (getOrCreate), a single failing send can hold the mutex for up to 2.4-6 seconds, blocking all concurrent senders for that duration. ActorConnRaw.#sendQueueMessage in actor-conn.ts has no such mutex, creating a surprising asymmetry.

The mutex is only needed to protect shared mutable state #resolvedActorId / #resolvingActorId during retry paths. Consider a narrower fix: acquire the mutex only on the retry/re-resolve path (around #clearResolvedActorId + re-resolution), not the entire send loop.

2. #shouldRetryQueueDispatchOverload does not clear the cached actor ID

When this returns true, #clearResolvedActorId() is never called. If an actor is overloaded because it is shutting down, the client will keep hammering the same instance until maxAttempts is exhausted rather than re-resolving. Contrast with #shouldRetryDynamicLifecycleError, which always clears the cached ID and sets useQueryTarget = true. Since overload retries now fire before lifecycle retries, this can exhaust all attempts before re-resolution is attempted.

3. dropped_reply in stale-handle detection may cause unnecessary actor recreation

actor/dropped_reply fires when a Rust Reply channel is dropped before a response is sent — this can happen during normal in-progress shutdown. Adding it to the stale-error set causes #resolvedActorId to be cleared and retried with useQueryTarget = true. For getOrCreate, this could inadvertently create a second actor if the first is mid-destruction but not yet removed from the registry. Additionally, dispatch.rs server-side already suppresses dropped_reply from workflow dispatch results (Ok((false, None))), making client-side and server-side handling asymmetric. A comment explaining why dropped_reply should trigger handle refresh would help.

4. not_configured in the lifecycle retry set is overly broad

actor/not_configured is returned when a capability like SQLite or WebSocket is not wired up — a permanent configuration error, not a transient lifecycle state. Retrying it will consume all attempts (up to 60 x 100 ms = 6 seconds) before surfacing the error, misleading developers about what went wrong. All other codes in this list (starting, stopping, destroyed_*, not_found) are transient. Either exclude not_configured, or add a comment explaining why retrying is expected to eventually succeed.

5. #sendActionNow and #fetchWithResolvedActor still have the race condition

#sendQueueMessage is now serialized via mutex, but the action() and fetch() paths also mutate #resolvedActorId via #clearResolvedActorId() / #invalidateResolvedActorId() and still have the original race. If the motivation was protecting shared resolved-actor state, the mutex should be extended to cover those methods or the resolution should be addressed uniformly.

6. AsyncMutex imported from a database module

import { AsyncMutex } from "@/common/database/shared";

AsyncMutex is a general-purpose utility living alongside SQLite binding helpers. Importing it into a client-facing networking module creates unexpected coupling. Consider moving it to @/common/utils or re-exporting from a neutral utilities entry point.

7. No tests for new behavior

No new or updated tests cover:

• Serialization behavior of the new #queueSendMutex (concurrent sends are ordered; second send sees updated actor ID from first retry).
• #shouldRetryQueueDispatchOverload retry logic on actor/overloaded.
• New stale-error codes not_configured and dropped_reply triggering handle refresh.

---

Minor / Non-blocking

• Retry ordering shift is undocumented. shouldRetryQueueDispatchOverload now fires before shouldRetryDynamicLifecycleError. An inline comment explaining the priority order (overload retries then lifecycle retries then stale-ID invalidation) would make this easier to maintain.
• isDynamicActorQuery guard in #shouldRetryQueueDispatchOverload is redundant for static queries (getForId returns maxAttempts = 1, making attempt >= maxAttempts - 1 always true). The guard is correct but a clarifying comment would help.
• PR description is empty. Type-of-change, test plan, and checklist are all unfilled, making it hard to understand the intended behavior and verification approach.

[github-actions]

Preview packages published to npm

Install with:

npm install rivetkit@pr-4794

All packages published as 0.0.0-pr.4794.efd07f2 with tag pr-4794.

Engine binary is shipped via @rivetkit/engine-cli on linux-x64-musl, linux-arm64-musl, darwin-x64, and darwin-arm64. Windows users should use the release installer or set RIVET_ENGINE_BINARY.

Docker images:

docker pull rivetdev/engine:slim-efd07f2
docker pull rivetdev/engine:full-efd07f2

Individual packages

npm install rivetkit@pr-4794
npm install @rivetkit/react@pr-4794
npm install @rivetkit/rivetkit-napi@pr-4794
npm install @rivetkit/workflow-engine@pr-4794

[NathanFlurry]

Landed in main via stack-merge fast-forward push. Commits are in main; closing to match.