fix(rivetkit): fix initial hibernation state always being overridden with msgIndex of -1

[NathanFlurry]

No description provided.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
rivetkit-serverless	Ready	Preview	Comment	Nov 6, 2025 5:38am

3 Skipped Deployments

Project	Deployment	Preview	Comments	Updated (UTC)
rivet-cloud	Ignored			Nov 6, 2025 5:38am
rivet-inspector	Ignored	Preview		Nov 6, 2025 5:38am
rivet-site	Ignored	Preview		Nov 6, 2025 5:38am

[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

• chore(agents): add graphite-commit agent for conventional commits #3394
• fix(rivetkit): only trigger onStateChange and inspector updates for actor state changes #3393
• fix(rivetkit): reject all waiters in SinglePromiseQueue #3392
• fix(rivetkit): fix hibernatable websocket last seen message index to be i64 instead of u64 #3391
• fix(rivetkit): gracefully call _onStop for actors on runner shutdown #3390
• fix(rivetkit): fix initial hibernation state always being overridden with msgIndex of -1 #3389 👈 (View in Graphite)
• fix(rivetkit): fix missing duplex in nextjs in development #3388
• chore(runner): add safeguard against duplicate sockets #3387
• chore(runner): explicitly stringify tunnel messages, commands, and events #3386
• fix(runner): do not send websocket close on tunnel shutdown since pegboard-runner takes care of this #3385
• fix(rivetkit): fix actors trying to sleep after stop started #3384
• chore(runner): rename webSocketId -> requestId #3383
• chore(runner): add explicit close reason when client runner shuts down #3382
• fix(guard): fix 1006 when client closes ws connection #3381
• chore(runner): add child logger with runner id #3380
• chore(rivetkit): remove warnings for graceful runner shtudown #3379
• fix(gateway): fix gc logic #3378
• fix: boot dupe runners #3377
• fix(rocksdb): fix txn conflict checker #3376
• main

---

How to use the Graphite Merge Queue

Add the label merge-queue to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

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

[claude]

Code Review

Summary

This PR fixes a critical bug where existing hibernatable WebSocket state was being overridden with a new entry having msgIndex: -1n on every reconnection. The fix properly distinguishes between updating an existing WebSocket's timestamp vs. creating a new entry.

Positive Aspects

✅ Correct Bug Fix: The core issue is properly addressed. Previously, even when existingWs was found and used for the hibernation config, the code would unconditionally push a new entry with msgIndex: -1n, losing the preserved message index state.

✅ Good Logging: Added structured debug logs that will help trace WebSocket hibernation behavior:

• Logs when existing hibernatable websocket is found with its lastMsgIndex
• Logs when no existing websocket is found
• Logs when updating vs. creating entries

✅ Follows Logging Conventions: Properly uses structured logging with the logger().debug() pattern and lowercase messages, consistent with CLAUDE.md guidelines.

✅ Preserves State Correctly: The fix ensures that msgIndex is preserved across reconnections by only updating the lastSeenTimestamp when a websocket already exists.

Issues & Suggestions

1. Race Condition Risk (Minor)

The code directly mutates existingWs.lastSeenTimestamp on line 269. If there are concurrent calls to getActorHibernationConfig for the same WebSocket, this could theoretically cause race conditions. However, this is likely acceptable given the WebSocket lifecycle, but worth noting.

2. Missing Test Coverage (Important)

This is a bug fix for critical state management logic, but there don't appear to be tests for WebSocket hibernation scenarios. Consider adding tests that verify:

• Initial WebSocket creation sets msgIndex: -1n
• Reconnection preserves the existing msgIndex
• lastSeenTimestamp is updated on reconnection
• Multiple WebSockets with different requestIds are handled correctly

The rivetkit-typescript codebase has a driver test suite at packages/rivetkit/src/driver-test-suite/ that would be an appropriate place for these tests.

3. Code Clarity (Minor)

The condition at line 264-280 now has two branches doing different operations. Consider adding a comment explaining why we update vs. create:

// Save or update hibernatable WebSocket
// If this WebSocket already exists (reconnection), only update the timestamp
// to preserve the msgIndex state. Otherwise, create a new entry.
if (existingWs) {
  // ...

Performance Considerations

✅ No performance concerns. The changes are minimal and don't introduce additional iterations or allocations.

Security Considerations

✅ No security concerns identified. The fix properly handles state management without exposing any security risks.

Recommendations

High Priority:

• Add test coverage for WebSocket hibernation scenarios to prevent regression

Low Priority:

• Consider adding a brief comment explaining the update vs. create distinction
• Consider documenting the expected lifecycle of PersistedHibernatableWebSocket entries

Conclusion

This is a solid bug fix that addresses a real state management issue. The logic is correct and the logging additions will aid debugging. The main gap is test coverage to ensure this behavior doesn't regress in the future.

Approval: ✅ Approved with the suggestion to add tests in a follow-up PR.

[pkg-pr-new]

More templates

• example-ai-agent
• example-background-jobs
• example-better-auth-external-db
• example-bots
• chat-room
• example-cloudflare-workers
• example-cloudflare-workers-hono
• example-counter
• example-counter-serverless
• example-crdt
• example-cursors
• example-cursors-raw-websocket
• example-database
• example-deno
• example-sqlite
• example-elysia
• example-express
• example-freestyle
• example-game
• example-hono
• example-hono-bun
• example-hono-react
• example-kitchen-sink
• example-next-js
• example-rate
• example-raw-fetch-handler
• example-raw-websocket-handler
• example-raw-websocket-handler-proxy
• example-react
• starter
• example-stream
• example-sync
• example-tenant
• example-trpc
• example-workflows

@rivetkit/actor

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/actor@3389

@rivetkit/cloudflare-workers

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/cloudflare-workers@3389

@rivetkit/core

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/core@3389

@rivetkit/db

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/db@3389

@rivetkit/framework-base

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/framework-base@3389

@rivetkit/next-js

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/next-js@3389

@rivetkit/react

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/react@3389

rivetkit

pnpm add https://pkg.pr.new/rivet-dev/rivet/rivetkit@3389

@rivetkit/sql-loader

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/sql-loader@3389

@rivetkit/engine-runner

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner@3389

@rivetkit/engine-runner-protocol

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner-protocol@3389

commit: 3acbad4

[graphite-app]

Merge activity

• Nov 6, 5:47 AM UTC: NathanFlurry added this pull request to the Graphite merge queue.
• Nov 6, 5:48 AM UTC: CI is running for this pull request on a draft pull request (#3395) due to your merge queue CI optimization settings.
• Nov 6, 5:50 AM UTC: Merged by the Graphite merge queue via draft PR: #3395.