feat(workflow-engine): add retryOnTimeout opt-in for step timeout retries

[abcxff]

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

[railway-app]

🚅 Deployed to the rivet-pr-5089 environment in rivet-frontend

Service	Status	Web	Updated (UTC)
frontend-cloud	😴 Sleeping (View Logs)	Web	May 23, 2026 at 11:52 pm
website	😴 Sleeping (View Logs)	Web	May 22, 2026 at 7:08 am
kitchen-sink	❌ Build Failed (View Logs)	Web	May 22, 2026 at 5:08 am
ladle	✅ Success (View Logs)	Web	May 21, 2026 at 7:49 pm
mcp-hub	✅ Success (View Logs)	Web	May 21, 2026 at 7:47 pm
frontend-inspector	❌ Build Failed (View Logs)	Web	May 21, 2026 at 7:46 pm

[abcxff]

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

• donotmerge: dummy inspector api #5085
• feat(inspector): insert and clear actor queue #5065
• feat(workflow-engine): add retryOnTimeout opt-in for step timeout retries #5089 👈 (View in Graphite)
• fix(rivetkit): wire CancellationToken through waitForNamesAvailable to eliminate KV busy-polling #5063 : 1 other dependent PR (#5050 )
• fix(rivetkit): fix BigInt serialization in inspector workflow history and state deserialization #5058
• WIP: counter latency monitor #5093
• main

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

[claude]

Review: feat(workflow-engine): add retryOnTimeout opt-in for step timeout retries

This is a clean, minimal feature addition. The core logic is correct and backward-compatible.

Correctness

The implementation looks correct:

• Default retryOnTimeout: false preserves existing behavior exactly (timeout immediate CriticalError with kind: "timeout").
• With retryOnTimeout: true, timeouts go through the normal retry path; when retries exhaust, a StepExhaustedError with kind: "timeout" is thrown.
• TryStepCatchKind already included "timeout" as a valid variant before this PR, so no union drift.

Issue: retryOnTimeout: true changes the thrown error class on exhaustion

Default (retryOnTimeout: false): timeout CriticalError (kind: "timeout")

Opt-in (retryOnTimeout: true + retries exhausted): timeout StepExhaustedError (kind: "timeout")

These are different types, which matters for callers using tryStep or catching errors directly. The docs mention kind: "timeout" but do not call out the class difference. A user who sets retryOnTimeout: true expecting a CriticalError on final exhaustion will be surprised. Worth adding a note to retries.md or the JSDoc.

Issue: Test uses real wall-clock timers in the yield-mode path

Per the repo conventions, flaky timing should use vi.useFakeTimers() rather than real sleeps. The yield-mode section of the new test uses bare await new Promise((resolve) => setTimeout(resolve, 10)) calls. With retryBackoffBase: 1 the backoff is 1 ms, so 10 ms should be plenty in practice, but it is still a wall-clock dependency that can race in slow CI.

Minor: JSDoc comment

The new JSDoc on retryOnTimeout in types.ts is fine for a public API, but consider splitting it across two lines for readability consistency with nearby comments.

---

Overall: the feature is well-scoped and the logic is sound. The two things I would address before merging are (1) a brief note in the docs/JSDoc about the CriticalError vs StepExhaustedError distinction when retryOnTimeout: true exhausts retries, and (2) replacing the manual setTimeout sleeps in the yield-mode test path with fake timers or event-driven coordination.