fix(pegboard): restore hibernating requests on serverful start

[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(pegboard): restore hibernating requests on serverful start #4904 : 2 dependent PRs (#4905 , #4906 ) 👈 (View in Graphite)
• fix(rivetkit): drain shutdown work before sleep #4902 : 1 other dependent PR (#4903 )
• feat(sqlite): wire remote sqlite execute handlers #4897
• test(serverless): avoid pinning header validation order #4896
• chore(driver-test-runner): add native/wasm runtime matrix to skill #4884 : 3 other dependent PRs (#4892 , #4894 , #4901 )
• chroe: rename rivetkit-sqlite to depot-client #4883
• fix(rivetkit-wasm): fix mem leaks #4880
• chore(rivetkit): wasm support #4860
• feat(sqlite): add cold read benchmarks and simplify optimizations #4857
• feat(sqlite): benchmark cold reads #4848 : 1 other dependent PR (#4864 )
• docs(actors): document manual lifecycle controls #4847
• test(sqlite): expand db stress coverage #4846 : 1 other dependent PR (#4849 )
• test(raw-websocket): add serverless smoke coverage #4845
• feat(serverless): configure drain grace period #4844
• fix(publish): enable frontend build for engine target and use turbo build instead of turbo build:engine #4843
• feat(rivetkit): expose conn handle in onWebSocket context #4842
• fix(rivetkit): normalize waitUntil/keepAwake promises to null to avoid serde undefined error #4841
• fix(rivetkit): remove requirement for token #4839 : 1 other dependent PR (#4840 )
• fix(pegboard-envoy): allow sqlite requests across lifecycle states #4838
• fix(pegboard): route scoped actor key reads by runner dc #4837
• fix(sqlite-storage): let sqlite open take over stale owners #4834
• fix(engine-tests): parallelize multi-DC startup + enable 6 multi-DC tests #4833
• fix(api): honor cursor in actor_ids list path #4832
• fix(api): silently filter invalid IDs from actor_ids query instead of 400 #4831
• fix(api-peer): make actors_delete idempotent for already-destroyed actors #4830
• fix(pegboard): use Iterator streaming mode in list_names so limit param is honored #4829
• chore(engine-tests): convert envoy tests to Sleep crash policy + triage ignored #4828
• feat(engine-tests): wire envoy actor names through prepopulate_actor_names #4827
• chore(depot): fault injection tests #4868
• feat(sqlite): pitr & forking #4859 : 1 other dependent PR (#4863 )
• chore(sqlite): stateless storage refactor #4856
• main

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

[claude]

PR Review: fix(pegboard): restore hibernating requests on serverful start

Overview

This PR fixes a bug where hibernating request IDs weren't being restored when a serverful actor starts during envoy reconnect. It introduces a new hibernating_requests module in pegboard-envoy with a reusable hydrate_command_wrapper function, and applies it in two places:

1. conn.rs — the replay path: hydrates missed commands when an envoy reconnects and replays queued startup commands
2. tunnel_to_ws_task.rs — the live path: hydrates commands as they arrive via the tunnel

The approach mirrors the existing logic in the deprecated pegboard-runner, now factored into a shared module.

---

Code Quality

• The new module is clean and well-scoped. The if let CommandStartActor guard is safe — other command types pass through with Ok(()) immediately.
• Splitting the hydration logic into its own module avoids duplication between the two call sites and matches the pattern already present in pegboard-runner/src/tunnel_to_ws_task.rs.
• Error propagation in both call sites is correct: hydration failure aborts the loop and triggers shutdown_conn_actors in the conn replay path.

---

Issues

Stale comments in engine/packages/pegboard/src/workflows/actor/runtime.rs

Six locations in the actor v1 runtime still carry the old comment:

// Empty because request ids are ephemeral. This is intercepted by guard and
// populated before it reaches the runner

The actor2 runtime comment was updated correctly in this PR, but actor v1 was not. Per CLAUDE.md conventions, comments should not document deltas and should reflect the current architecture. These should be updated to match the actor2 wording:

"Request ids are ephemeral. Pegboard-envoy refreshes this on the WebSocket send path immediately before the actor start reaches envoy."

Affected lines: 729–730, 753–754, 845–846, 868–869, 980–981, 1003–1004

---

Performance Notes

The existing // TODO: Parallelize comment in tunnel_to_ws_task.rs (line 127) applies here: each CommandStartActor in a batch now triggers a separate FDB range scan sequentially. This is a pre-existing concern, not introduced by this PR, but the new DB call makes batched starts slightly more expensive.

---

Minor Suggestions

The doc comment on hydrate_command_wrapper mentions why stored serverful commands are empty, but doesn't explain why the live tunnel path also needs hydration (i.e., that the guard no longer fills this in on the envoy path). A brief note there would help future readers understand why hydration is needed in both call sites.

---

Summary

The fix is correct and the code is well-structured. The only item worth addressing before merge is updating the stale actor v1 comments to keep the architecture description consistent across the codebase. No blocking correctness issues.

[NathanFlurry]

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