fix(rivetkit-core): return stopping not starting when sleep/destroy called mid-shutdown

[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]

• chore(kitchen-sink): configurable endpoint #4766 : 3 dependent PRs (#4754 , #4777 , #4778 )
• 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 👈 (View in Graphite)
• 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 Review: fix(rivetkit-core): return stopping not starting when sleep/destroy called mid-shutdown

Overview

This PR fixes a diagnostic accuracy bug in the sleep() and destroy() lifecycle methods. When the lifecycle state machine transitions into SleepGrace or DestroyGrace, it clears the started flag. Any subsequent call to sleep() or destroy() would hit the !started guard and incorrectly return ActorLifecycleError::Starting ("cannot request sleep before actor startup completes") -- misleading callers into thinking the actor never started. The fix correctly disambiguates "never started" vs. "mid-shutdown" by consulting the sleep_requested / destroy_requested flags.

---

Code Quality

Correct and targeted. The three-flag check in destroy() follows naturally from the escalation semantics: destroy() after sleep() is valid and intentional, so the guard must pass through even when started=false.

Non-atomic multi-load pattern is acceptable here. The three atomic reads are not one coherent snapshot, but this only matters for diagnostic classification, not for making a state transition. The actual state transition is governed by the subsequent swap(true) calls.

Comments follow conventions -- complete sentences, no em-dashes, explain the why not the what.

---

Potential Issues

Missing test for the destroy() path. The new test covers sleep() after grace, but the symmetric destroy() scenario has no coverage:

• destroy() called when started=false and sleep_requested=true (escalation path, should succeed).
• destroy() called when started=false and destroy_requested=true (idempotent path, should return Stopping at the swap).

Both branches are reachable in production and meaningfully different from the pre-startup case.

Asymmetry between sleep() and destroy() at the guard level. sleep() classifies and returns Stopping at the guard. destroy() lets the already-stopping case fall through to the destroy_requested.swap(true) check, which also returns Stopping. This is correct, but a short inline comment at the destroy() guard would confirm to future readers that the fall-through is intentional.

---

Suggestions

1. Add a destroy() counterpart test to cover both the escalation path (sleep requested, then destroy) and the idempotent path (destroy requested, then destroy again). The existing sleep_after_grace_clears_started_returns_stopping_not_starting test is a good template.

2. Optional one-liner at the destroy() guard to clarify the fall-through behavior for already-stopping cases.

---

Summary

The core fix is correct, well-commented, and safe. The one material gap is missing test coverage for the destroy() escalation and idempotent paths.

[github-actions]

Preview packages published to npm

Install with:

npm install rivetkit@pr-4757

All packages published as 0.0.0-pr.4757.c15ed18 with tag pr-4757.

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-c15ed18
docker pull rivetdev/engine:full-c15ed18

Individual packages

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