fix(rivetkit): isolate engine envoys and propagate startup failures

[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(engine): publish engine bases in ci #4649 : 3 dependent PRs (#4650 , #4652 , #4666 )
• chore: lockfile lefthook #4647
• fix(rivetkit): surface native sqlite kv errors to callers #4645
• fix(rivetkit): prevent sleep races during disconnect and db work #4644
• fix(rivetkit): isolate engine envoys and propagate startup failures #4643 👈 (View in Graphite)
• test(rivetkit): remove wasm sqlite-only fixtures and coverage #4642
• chore(sqlite-vfs): remove wasm sqlite packages and workspace wiring #4641
• chore(rivetkit): remove wasm sqlite runtime #4614
• fix(sqlite-native): restore native startup kv preload #4639
• fix(sqlite-native): delete metadata before chunk range #4638
• fix(sqlite-native): keep truncate cache coherent #4637
• fix(sqlite-vfs): use delete range for truncate cleanup #4636
• fix(sqlite-native): restore kv error hook #4635
• perf(sqlite-native): avoid cloning cached read chunks #4634
• perf(sqlite-native): gate kv operation labels #4633
• perf(sqlite-native): reuse read cache for partial writes #4632
• perf(sqlite-native): remove delete file existence probe #4631
• fix(sqlite-native): gate native read cache behind env var #4630
• fix(pegboard): isolate runner config dc lookup failures #4625 : 1 other dependent PR (#4626 )
• docs(pegboard): note runner config upsert split write risk #4624
• fix(pegboard): unpack global runner config keys correctly #4623
• fix(pegboard-gateway): enforce tunnel message state #4622
• fix(pegboard-runner): clear terminal tunnel routes #4621
• fix(pegboard): skip protocol version keys in runner pool backfill #4620
• fix(pegboard): create missing normal runner configs #4619
• fix(epoxy): reuse cached optimistic value #4618
• main

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

[claude]

PR Review: fix(rivetkit): isolate engine envoys and propagate startup failures

Overview

This PR makes two focused, related changes:

1. Propagates envoy startup failures rather than silently swallowing them across Rust and TypeScript layers.
2. Isolates engine envoys by always passing notGlobal: true in the EngineActorDriver, preventing multiple driver instances from sharing a global singleton envoy.

Code Quality

handle.rs — started() return type change

Good change. Returning anyhow::Result<()> instead of () is the right call. watch::Receiver::changed() returns Err(RecvError) when all senders are dropped (i.e., the envoy task died), and previously that was silently discarded via let _ = .... The error message is clear and actionable.

envoy_handle.rs — two chained map_err

Correct and complete. The outer map_err handles JoinError from spawn(...).await, and the inner one handles anyhow::Error from handle.started(). The ? between them correctly short-circuits on join failure. No issues.

actor-driver.ts — rejection handling in .then()

Solid fix. Previously, if envoy.started() rejected, it would produce an unhandled promise rejection and leave #envoyStarted unresolved. Now startup failures are forwarded to the deferred and will surface to any caller awaiting the envoy.

actor-driver.ts — notGlobal: true

The isolation intent is clear and matches the GLOBAL_ENVOY singleton avoidance logic in envoy.rs. The field already existed in the config (wrapper.d.ts marks it optional, defaulting to false), so this is a safe, additive change. Every EngineActorDriver now owns its envoy rather than sharing one globally.

Concerns

start_envoy uses .expect() instead of returning Result

pub async fn start_envoy(config: EnvoyConfig) -> EnvoyHandle {
    let handle = start_envoy_sync(config);
    handle
        .started()
        .await
        .expect("envoy failed to start before returning handle");
    handle
}

The function signature returns a bare EnvoyHandle, so a panic is the only option without changing the return type to anyhow::Result<EnvoyHandle>. For an envoy startup failure this will crash the calling task entirely. The panic message is descriptive, but if any callers outside test code use start_envoy (vs. the sync variant), those will panic rather than receive a recoverable Result. Worth a follow-up to change the return type to Result<EnvoyHandle> if this function is called from production paths.

No tests added

The checklist item for tests is unchecked. Testing startup-failure propagation requires intentionally killing the envoy, but even a minimal test verifying that two startEnvoySync calls with notGlobal: true return distinct handles (distinct envoy keys) would strengthen confidence in the isolation change.

Connection overhead from always-isolated envoys

notGlobal: true means every EngineActorDriver instance opens its own WebSocket connection to the envoy. If multiple drivers are created (e.g., in tests or multi-tenant setups), connections multiply. This appears intentional given the PR title, but worth confirming existing callers that relied on the global singleton are not paying unexpected connection costs.

Minor

• The notGlobal field in wrapper.d.ts is typed as notGlobal?: boolean (optional). Making it required, or at least documenting the default-to-global behavior, would help callers avoid accidentally sharing the singleton.

Summary

Clean, focused fix. Error propagation is correct at every layer. The main follow-up worth tracking is making start_envoy return Result<EnvoyHandle> to avoid a potential panic on startup failure in production paths.