fix(rivetkit): restore hibernatable sockets and hydrate serverless starts

[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(guard): serialize gateway actor keys correctly #4655
• fix(api): subscribe before namespace workflow dispatch #4654
• fix(rivetkit): restore hibernatable sockets and hydrate serverless starts #4658 👈 (View in Graphite)
• fix(rivetkit-native): expose full hibernation metadata to JS #4657
• fix(pegboard): persist and replay hibernating requests #4656
• fix(rivetkit): keep internal error exposure behavior consistent #4661
• test(rivetkit): stabilize actor db driver tests #4664
• fix(test): stabilize lifecycle, sleep, queue, and run edge cases #4660 : 1 other dependent PR (#4665 )
• test(rivetkit): re-enable gateway URL and direct-registry coverage #4659
• chore(engine): publish engine bases in ci #4649 : 2 other dependent PRs (#4650 , #4652 )
• chore: lockfile lefthook #4647
• fix(rivetkit): surface native sqlite kv errors to callers #4645
• fix(rivetkit): prevent sleep races during disconnect and db work #4644
• fix(rivetkit): isolate engine envoys and propagate startup failures #4643
• test(rivetkit): remove wasm sqlite-only fixtures and coverage #4642
• chore(sqlite-vfs): remove wasm sqlite packages and workspace wiring #4641
• chore(rivetkit): remove wasm sqlite runtime #4614
• fix(sqlite-native): restore native startup kv preload #4639
• fix(sqlite-native): delete metadata before chunk range #4638
• fix(sqlite-native): keep truncate cache coherent #4637
• fix(sqlite-vfs): use delete range for truncate cleanup #4636
• fix(sqlite-native): restore kv error hook #4635
• perf(sqlite-native): avoid cloning cached read chunks #4634
• perf(sqlite-native): gate kv operation labels #4633
• perf(sqlite-native): reuse read cache for partial writes #4632
• perf(sqlite-native): remove delete file existence probe #4631
• fix(sqlite-native): gate native read cache behind env var #4630
• fix(pegboard): isolate runner config dc lookup failures #4625 : 1 other dependent PR (#4626 )
• docs(pegboard): note runner config upsert split write risk #4624
• fix(pegboard): unpack global runner config keys correctly #4623
• fix(pegboard-gateway): enforce tunnel message state #4622
• fix(pegboard-runner): clear terminal tunnel routes #4621
• fix(pegboard): skip protocol version keys in runner pool backfill #4620
• fix(pegboard): create missing normal runner configs #4619
• fix(epoxy): reuse cached optimistic value #4618
• main

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

[claude]

PR Review: fix(rivetkit): restore hibernatable sockets and hydrate serverless starts

This PR restores hibernatable WebSocket connections across serverless actor restarts and improves sleep test reliability. The core idea is sound - persisting connection metadata in KV and injecting it into the serverless start payload enables proper socket rebinding after a cold start. Overall quality is good with a few things worth addressing.

---

What This Does

• Serverless start hydration (#hydrateServerlessStartPayload): reads persisted connection metadata from KV and injects hibernating requests into the CommandStartActor payload before forwarding to the envoy, restoring hibernatable sockets after a serverless restart.
• Binding infrastructure: introduces HibernatableConnectBinding and HibernatableRunnerWebSocketBinding with detach/rebind lifecycle, so connections can be re-wired to a newly started actor instance.
• Proper dispose() on shutdown: replaces #dynamicRuntimes.clear() with await this.#disposeAllDynamicRuntimes(), and adds force-stop of stuck actors during envoy drain.
• Test improvements: polling retry helper (readAfterSleepCycle) replaces fixed-delay waits; toBeGreaterThanOrEqual relaxes brittle exact-count assertions.
• Gateway URL path fix /api/hello to /request/api/hello to match router changes.

---

Issues

waitForHibernatableRegistration is an unexplained magic delay

No comment explains what is being waited for or why 100ms is sufficient. This is a timing assumption that will be flaky in slow CI- A statement explaining the race being guarded against would help; ideally a polling approach (similar to readAfterSleepCycle) would be more robust.

"alarms keep actor awake" test semantics changed

The original test verified the actor did NOT sleep while an alarm was active by checking counts mid-way before the alarm fires. The new version removes that intermediate assertion and only checks that a sleep eventually happens. This no longer verifies the alarm's keep-alive effect - it just confirms baseline sleep behavior. The test name no longer matches its intent.

Logging field name inconsistency

In the dynamic actor start error handler, err: stringifyError(error) is used, but all other error logging in the file uses error:.

dynamic.runtime.disposed handling is inconsistent between binding types

In #bindDynamicHibernatableConnectSocket, the onProxyClose handler only ignores "dynamic.runtime.disposed" when isRestoringHibernatable is true. In #bindDynamicHibernatableRunnerWebSocket, it is always ignored. If intentional, a comment explaining why would prevent future confusion.

Broad try/catch in dynamic actor start masks which step failed

The try/catch wraps rebinding + restoring in one block with a single warning message. If rebinding succeeds but restoreHibernatingRequests fails, the warning is misleading. Consider logging the step name or using separate try/catch blocks per phase.

No version validation in #hydrateServerlessStartPayload

The code slices off a 2-byte version prefix and reassembles the payload after re-encoding without validating what those bytes represent. A comment on the expected prefix format or a defensive assertion would help prevent silent corruption if the format changes.

---

Minor Observations

• readAfterSleepCycle error message prints lastError=undefined when the read never throws but counts never reach threshold - consider omitting lastError when it is not set.
• #disposeDynamicRuntime using finally to guarantee delete even on dispose failure is the right pattern.
• The .sequential() annotation on hibernation tests is correct and necessary.
• toBeGreaterThanOrEqual paired with expect(startCount).toBe(sleepCount + 1) is a good invariant - lenient on absolute counts while still enforcing the relationship.