fix(runner): log warning instead of closing ws on message index gap

[NathanFlurry]

Summary

• When the engine driver detects a gap in hibernatable WebSocket message indices, it now logs a warning instead of closing the connection with a 1008 error.

Test plan

• Verify that WebSocket connections remain open when message index gaps occur
• Confirm warning is logged with gap details

🤖 Generated with Claude Code

[claude]

PR Review: fix(runner): log warning instead of closing ws on message index gap

The core logic of each change is sound. Here is a breakdown by file.

websocket-tunnel-adapter.ts - Gap handling relaxation

The change to warn-and-continue instead of closing with 1008 is appropriate for hibernation semantics. During migration, messages may have been delivered with indices that appear as gaps to the new runner. Closing on any gap was too aggressive.

One thing worth noting: the private field serverMessageIndex is still updated to the gapped value, so any late-arriving messages in the skipped range will be dropped by the de-dup check (wrappingLteU16). This is correct for at-least-once delivery semantics, but worth documenting with a comment.

tunnel.ts - Hibernatable ws.downstream_closed bypass

The new branch correctly performs the same in-memory cleanup (deleteWebSocket, deletePendingRequest, removeRequestToActor) while intentionally skipping adapter._handleClose() to preserve KV state for the next runner. The logic is sound.

Minor concern: "ws.downstream_closed" is matched as a plain string literal but its canonical definition lives in Rust (engine/packages/pegboard-gateway/src/lib.rs). A comment pointing to the source would prevent silent drift if the string ever changes on the Rust side.

state-manager.ts - saveState bug fix

This is a genuine correctness fix. The early-exit guard in saveState() was inconsistent with the inner savePersistInner() check. The outer guard only checked the persistChanged flag, missing the connsWithPersistChanged.size > 0 condition. This meant connection state changes could be silently dropped when actor state itself had not changed.

Suggestion: this fix has real impact on persistence correctness and would benefit from a unit test. A case where connsWithPersistChanged is non-empty but persistChanged is false, confirming that saveState now triggers a write, would be a good regression test.

mod.ts - Diagnostic logging

The new info-level logs and performance.now() timing around onActorStart are useful for debugging migration issues. Two things to consider:

1. Log level: several of these are fairly verbose for production (e.g. logging every hibernating request individually in a loop). Consider downgrading to debug once the migration issue is resolved.
2. Pre-existing issue: line 355 uses console.error in the onActorStop catch block instead of the structured logger pattern (this.log?.error). Not introduced by this PR, but worth a follow-up cleanup.

Summary

Severity / File / Issue:

• Minor: tunnel.ts - Add comment linking "ws.downstream_closed" to its Rust definition
• Minor: state-manager.ts - No regression test added for the saveState bug fix
• Suggestion: mod.ts - New info-level logs may be too verbose for production long-term
• Pre-existing: mod.ts - console.error in onActorStop catch instead of structured logger

Overall the changes are correct and the saveState fix closes a real persistence gap. The approach for handling message index gaps during hibernation is sound.

[pkg-pr-new]

More templates

• actor-actions
• actor-actions-vercel
• example-agent-os
• example-agent-os-e2e
• ai-agent
• ai-agent-vercel
• example-ai-and-user-generated-actors-freestyle
• chat-room
• chat-room-vercel
• example-cloudflare-workers
• example-cloudflare-workers-hono
• collaborative-document
• collaborative-document-vercel
• cross-actor-actions
• cross-actor-actions-vercel
• example-cursors
• example-cursors-raw-websocket
• example-cursors-raw-websocket-vercel
• example-cursors-vercel
• custom-serverless
• example-elysia
• example-experimental-durable-streams-ai-agent
• example-experimental-durable-streams-ai-agent-vercel
• geo-distributed-database
• geo-distributed-database-vercel
• hello-world
• hello-world-vercel
• example-hono
• hono-react
• hono-react-vercel
• example-kitchen-sink
• example-kitchen-sink-vercel
• multi-region-vercel
• multiplayer-game
• example-multiplayer-game-patterns
• example-multiplayer-game-patterns-vercel
• multiplayer-game-vercel
• native-websockets
• native-websockets-vercel
• next-js
• per-tenant-database
• per-tenant-database-vercel
• example-raw-fetch-handler
• example-raw-fetch-handler-vercel
• example-raw-websocket-handler
• example-raw-websocket-handler-proxy
• example-raw-websocket-handler-proxy-vercel
• example-raw-websocket-handler-vercel
• example-react
• example-react-vercel
• sandbox
• sandbox-coding-agent
• sandbox-coding-agent-vercel
• sandbox-vercel
• scheduling
• scheduling-vercel
• example-sqlite-drizzle
• example-sqlite-raw
• state
• state-vercel
• example-stream
• example-stream-vercel
• example-trpc

@rivetkit/cloudflare-workers

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

@rivetkit/framework-base

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

@rivetkit/next-js

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

@rivetkit/react

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

rivetkit

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

@rivetkit/sql-loader

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

@rivetkit/sqlite-vfs

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/sqlite-vfs@4594

@rivetkit/traces

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

@rivetkit/workflow-engine

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/workflow-engine@4594

@rivetkit/virtual-websocket

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/virtual-websocket@4594

@rivetkit/engine-runner

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

@rivetkit/engine-runner-protocol

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

commit: 16648e0