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): keep internal error exposure behavior consistent #4661
• fix(rivetkit): add lifecycle error retry and gateway HTTP routing #4666
• fix(rivetkit-core): remove legacy timeouts #4799
• chore: add CLAUDE.md guidance on test fixtures, SDK regen, and TS client layer #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

Summary: This PR stabilizes a set of test fixtures and test files for the driver test suite, addressing race conditions, polling gaps, abort-signal handling, API call ordering, and a sandbox-environment workaround. Several changes are clear improvements; the items below flag issues worth addressing before merge.

Medium Issues

1. queue.ts - Duck-typed error discrimination instead of canonical RivetError check

Per CLAUDE.md: only passthrough canonical structured errors. The cast and string-field comparison is fragile. The check should use instanceof RivetError or the __type tag. If RivetError is not importable from a fixture context, that gap is the deeper issue; the workaround should include a comment explaining why.

2. sleep-db.ts - triggerSleepTwice is dead code tied to a still-skipped test

The new triggerSleepTwice action is added to sleepWithDb, sleepWithDbConn, and sleepWithDbAction, but the corresponding test is still test.skip with a TODO(#4705) comment. This adds unverified fixture code with no live coverage. Either lift the skip if the semantics are now correct, or defer these fixture additions to the PR that removes the skip.

3. start-stop-race.ts - Unguarded async RPC in onDestroy

An awaited outgoing RPC in onDestroy can fail silently during eviction or engine shutdown. If recordEvent times out or errors, destroyCalled is true but the observer event is missing and the test will not catch the gap. Per the Fail-By-Default Runtime principle, required lifecycle operations should surface failures explicitly. At minimum, wrap this in a try/catch that re-throws, or assert the observer event count in the test to catch the silent drop.

4. inline-client.ts - isDynamicSandboxRuntime() is an undocumented, fragile heuristic

The check process.cwd() === "/root" silently switches the entire connectToCounterAndIncrement implementation (no WebSocket connection in the sandbox path) based on a hardcoded CWD string. If the sandbox CWD changes or this actor is tested in a different environment, the test takes the wrong branch silently. This warrants a comment explaining the capability gap in the sandbox runtime that necessitates the workaround, and ideally a TODO linking to a tracked issue for removing this once the capability gap is closed.

Low / Style Issues

5. actor-queue.test.ts - Polling loop lacks a justification comment

CLAUDE.md requires a one-line comment on every vi.waitFor call explaining why polling is used instead of direct awaiting. The new for loop polling getSpawned() uses the local waitFor helper rather than vi.waitFor, so the linter will not flag it. A one-line comment explaining why event-driven coordination is not possible here should be added.

6. actor-run.test.ts - describe.sequential choice is unexplained

All run tests now execute sequentially even when skip?.sleep is false. The reason is not documented. Is it because tests share actor keys, or because the sandbox environment is single-threaded? A brief comment would help the next reader understand the tradeoff.

7. inline-client.ts - Potential race in waitForConnectionOpen

In waitForConnectionOpen, if the connection transitions to connected between the connStatus check and the new Promise subscription, onOpen fires its callback via queueMicrotask before unsubscribeOpen/unsubscribeError are initialized and the cleanup could call undefined. This is an existing pattern issue but worth noting since this PR introduces the helper.

Positive Changes

• access-control.ts / destroy.ts: Replacing Response.json with new Response(JSON.stringify) is the right fix for runtime compatibility.
• run.ts: Simplifying sendMessage to use c.queue.send directly removes unnecessary client-indirection back to the actors own queue.
• actor-handle.test.ts: Adding await handle.increment(0) after create correctly ensures actor startup before the second create call, fixing the race.
• lifecycle-hooks.test.ts: Moving connection params from connect to getOrCreate(undefined, params) is the correct API usage.
• actor-queue.test.ts: Adding explicit timeout values to the two new test() calls provides clear timeout semantics.

---

Overall this is a solid stabilization pass. The main asks before merge are: canonical error checking in queue.ts, guarding the async RPC in onDestroy, and either enabling or deferring the triggerSleepTwice dead code.

[NathanFlurry]

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