fix(gateway): split actor response wait errors

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

• fix(pegboard): align drain grace defaults with stop threshold #4958 : 2 dependent PRs (#4960 , #4966 )
• fix(rivetkit): preserve bridge error messages #4959
• fix(rivetkit): fire abort signal on shutdown finalize #4957
• fix(rivetkit): use startup kv preload #4956
• fix(client): flatten skipReadyWait option #4955
• ci(publish): add manual preview publish flow #4954
• fix(depot): add ltx decode diagnostics #4953
• fix(universaldb): preserve plain set values #4952
• fix(universaldb): align versionstamp operand encoding #4951
• fix(rivetkit): export database provider types #4950
• wip: kitchen sink agentic loop finish #4949
• chore(rivetkit): note duplicate admission logic #4948
• test(rivetkit): cover bypass fetch header forwarding #4947
• feat(kitchen-sink): add actor probe controls #4946
• fix(gateway): split actor response wait errors #4945 👈 (View in Graphite)
• fix(guard): handle bypass preflight before query parse #4944
• feat(kitchen-sink): add mock agent event log copy #4943
• fix(kitchen-sink): default mock agent to local endpoint #4942
• test(rivetkit): enable driver lifecycle regressions #4941
• test(rivetkit): verify cached websocket db refs exceed grace #4940
• fix(rivetkit-core): keep sleeping actors reachable during grace #4939
• test(rivetkit): cover async websocket close db access #4938
• fix(rivetkit): keep actors awake until keepAwake work finishes #4937
• fix(rivetkit): persist native onSleep state on errors #4936
• fix(rivetkit-core): allow dispatch during sleep grace #4935
• fix(rivetkit): make duplicate sleep requests idempotent #4934
• main

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

[claude]

Code Review: fix(gateway): split actor response wait errors

Overview

This PR replaces the generic ServiceUnavailable error with five distinct, semantically precise error types for actor response wait failures in the gateway. It also improves the retry logic and TypeScript client classification, and adds documentation for all new error codes.

---

Strengths

• Clear error semantics: Splitting a single catch-all into ActorStoppedWhileWaiting, TunnelRequestAborted, TunnelMessageTimeout, TunnelResponseClosed, and GatewayResponseStartTimeout makes the failure mode visible in logs and to API consumers.
• Bug fix in TunnelResponseClosed: The old break in the None select arm (both gateways) silently fell through to a generic ServiceUnavailable; the new return Err(TunnelResponseClosed.build()) is explicit and more precise.
• Stricter should_retry_request_inner: The new implementation validates the x-rivet-error header content rather than just checking its presence, preventing spurious retries on unrelated 503s.
• TypeScript test added verifying the retryable classification of all new codes.
• Documentation updated with the new error codes.

---

Issues

1. Missing newline at end of file

Every new .json file under engine/artifacts/errors/ ends without a trailing newline. All existing artifacts in that directory include a trailing newline; these should match.

2. actor_ready_timeout inconsistency between Rust and TypeScript

The Rust helper includes actor_ready_timeout as retryable but the TypeScript counterpart does not. This means guard.actor_ready_timeout is retried by the gateway internal Rust retry loop but not by the TypeScript client. If the intent is for the TS client to retry on it too, add the code; if not, remove it from the Rust list or document why the two diverge.

3. No Rust unit tests

The Rust-side changes are meaningfully testable:

• is_retryable_guard_http_error is a pure function, so a small table-driven test would guard against future regression.
• should_retry_request_inner now has non-trivial header parsing logic; tests covering retryable vs. non-retryable cases (missing header, wrong group, unknown code, 504 with valid code) would be valuable.

4. Duplicate retryable-codes list

The list of retryable guard codes now lives in three places: Rust (utils.rs), TypeScript (lifecycle-errors.ts), and implicitly in the documentation. A future error addition must be updated in all three simultaneously. A brief inline cross-reference comment would reduce the risk of drift.

---

Minor

• The new comment on should_retry_request_inner uses a colon-fragment style. CLAUDE.md asks for complete sentences.
• actor_ready_timeout is absent from the documentation new error-code list even though it was already present in the original paragraph.

---

Summary

The core change is solid: cleaner error taxonomy, a real bug fix in the None/break path, and good test coverage on the TypeScript side. The main actionable items before merge are: fix the trailing newlines in the JSON artifacts, resolve the actor_ready_timeout inconsistency between Rust and TypeScript, and consider adding Rust unit tests for the new retry helpers.