fix(test): stabilize lifecycle, sleep, queue, and run edge cases

[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(test): stabilize lifecycle, sleep, queue, and run edge cases #4660 : 2 dependent PRs (#4664 , #4665 ) 👈 (View in Graphite)
• test(rivetkit): re-enable gateway URL and direct-registry coverage #4659
• fix(rivetkit): add lifecycle error retry and gateway HTTP routing #4666
• fix(rivetkit-core): remove legacy timeouts #4799
• docs: add replay guidance notes #4796
• fix(inspector): stream patched state updates #4795
• fix(rivetkit): refresh stale actor handles #4794
• test(rivetkit-napi): move private tests to crate root #4793
• test(rivetkit-core): move private tests to crate root #4792
• test(runner-configs): assert envoy protocol version #4791
• fix(serverless): split metadata protocol errors #4789 : 1 other dependent PR (#4790 )
• chore(sqlite): add open close lifecycle for envoy actors #4788
• fix(rivetkit): share lifecycle shutdown grace #4810
• fix(pegboard): move sqlite v1 migration into actor workflow #4787 : 1 other dependent PR (#4797 )
• test(rivetkit): cover c.db access from onWake/onSleep/onDestroy #4786
• fix(rivetkit-napi): run onMigrate before createState/onCreate/createVars #4785
• refactor(rivetkit-core): merge ready+started into lifecycle_started, drop redundant napi calls #4784
• fix(rivetkit): drain native sleep side tasks reliably #4782 : 1 other dependent PR (#4783 )
• fix(rivetkit): route raw request fetches to actors #4781
• fix(pegboard): refresh runner config after envoy connect #4778 : 2 other dependent PRs (#4779 , #4798 )
• chore(kitchen-sink): configurable endpoint #4766 : 2 other dependent PRs (#4754 , #4777 )
• 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
• 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 #4660 Review: fix(test): stabilize lifecycle, sleep, queue, and run edge cases

Overview

This PR stabilizes driver test flakes across lifecycle, sleep, queue, and run suites. Changes fall into four categories: fixture correctness fixes, test timing/sequencing hardening, API usage fixes, and a sandbox-specific workaround in the kitchen-sink example.

---

Issues

1. isDynamicSandboxRuntime() is a fragile heuristic

File: examples/kitchen-sink/src/actors/testing/inline-client.ts

Detecting the runtime via cwd === "/root" is brittle. Any container or CI environment running from /root silently skips the WebSocket connection path. The two branches also behave differently: the sandbox path collects no events but returns an empty events array as if it did. A dedicated env var or an explicit flag from the test harness would be more reliable than a cwd check.

2. Race window in waitForConnectionOpen

File: examples/kitchen-sink/src/actors/testing/inline-client.ts

There is a TOCTOU race: the connection can transition to "connected" between the connStatus === "connected" guard and the onOpen subscription. If that happens the promise never settles. The guard and subscribe need to be atomic, or onOpen must fire synchronously for already-connected handles.

3. Polling loop without a justification comment

File: rivetkit-typescript/packages/rivetkit/tests/driver/actor-queue.test.ts (new loop around line 310)

CLAUDE.md requires a comment immediately before every polling loop explaining why direct awaiting is insufficient. The new for loop polling parent.getSpawned() lacks that comment. Add one explaining why the run-handler spawn must be polled (e.g. "spawn is queued asynchronously in the run handler so we must poll until it appears").

4. Unsafe type cast on abort error

File: rivetkit-typescript/packages/rivetkit/fixtures/driver-test-suite/queue.ts

error as { group?: string; code?: string } is applied to unknown without a null/object check. Prefer instanceof ActorError or a proper type guard. ActorError is already used in adjacent test files.

5. triggerSleepTwice fixture added but the test remains skipped

File: rivetkit-typescript/packages/rivetkit/fixtures/driver-test-suite/sleep-db.ts

The triggerSleepTwice action is added to all three sleep-db actors, but actor-sleep-db.test.ts still has test.skip("double sleep call is a no-op") pointing at TODO #4705. These fixture additions are dead code until that test is enabled. Either enable the test here or defer the fixture changes to the PR that resolves #4705.

---

Suggestions

onDestroy in start-stop-race.ts - missing error handling. If recordEvent throws during actor shutdown (e.g. observer unavailable), the destroy hook surfaces an unexpected error that can mask the lifecycle event under test. Wrapping the observer call in try/catch and logging on failure is safer than propagating in a test fixture.

describe.sequential in actor-run.test.ts - add a comment. The switch from describe.skipIf to describe.sequential is semantically different (sequential execution vs. skipped). If sequential execution is required to avoid shared actor state collisions, a brief comment on describeRunTests would clarify the non-obvious constraint per CLAUDE.md.

Good changes: sendMessage simplified to c.queue.send() removes unnecessary self-client indirection. Response.json() replaced with explicit new Response(JSON.stringify(...)) is more portable. Moving beforeConnect params from connect() to getOrCreate(undefined, { params: ... }) matches the actual API signature.

---

Summary

The stabilization direction is sound. Actionable items before merge:

1. Replace cwd-based sandbox detection with an explicit mechanism.
2. Fix the race window in waitForConnectionOpen.
3. Add a justification comment before the new polling loop.
4. Enable the double-sleep test or defer triggerSleepTwice fixture additions to the PR resolving Track skipped actor-sleep-db shutdown invariants in driver tests #4705.