docs(serverless): document timeout tuning

Author: NathanFlurry

.agent/notes/driver-test-progress.md

@@ -68,3 +68,11 @@ Scope: DB driver tests only
 - 2026-05-08 16:52 PDT raw-websocket [native/local/bare]: PASS (16 passed, 14.0s). Covers raw websocket callback tracking.
 - 2026-05-08 16:52 PDT actor-conn-state [native/local/bare]: PASS (11 passed, 10.9s). Covers connection lifecycle and disconnect accounting through the work registry.
 - 2026-05-08 16:52 PDT actor-sleep-db [native/local/bare]: PASS (26 passed, 70.9s). Covers DB close timing during sleep shutdown and waitUntil state persistence.
+- 2026-05-09 04:48 PDT DB TESTS RERUN STARTED [native only] - validating async websocket close handler behavior.
+- 2026-05-09 04:48 PDT actor-db rerun [native]: PASS (13 passed, 104 skipped, 18.3s).
+- 2026-05-09 04:48 PDT actor-db-raw rerun [native]: PASS (5 passed, 40 skipped, 4.9s).
+- 2026-05-09 04:48 PDT actor-db-pragma-migration rerun [native]: PASS (4 passed, 32 skipped, 4.3s).
+- 2026-05-09 04:48 PDT actor-sleep-db rerun [native]: PASS (26 passed, 208 skipped, 63.8s). Includes `async websocket close handler can use c.db before sleep completes` and `async websocket addEventListener close handler can use c.db before sleep completes`.
+- 2026-05-09 04:48 PDT actor-db-stress rerun [native]: PASS (5 passed, 40 skipped, 31.3s).
+- 2026-05-09 04:48 PDT actor-db-init-order rerun [native]: PASS (6 passed, 48 skipped, 6.3s).
+- 2026-05-09 04:48 PDT DB TESTS RERUN COMPLETE [native only] - 6/6 DB file groups passed. Async close handler tests included.

website/src/content/docs/general/production-checklist.mdx

@@ -24,7 +24,9 @@ We recommend passing this page to your coding agent to verify your configuration
 - **Verify `/api/rivet/start` body size limits.** Serverless actor starts carry actor config and preloaded KV or SQLite startup data in the request body. Keep `serverless.maxStartPayloadBytes` and your platform or proxy body limit at **16 MiB or higher**, or lower the preload budget if your platform cannot accept that size. See [Limits](/docs/actors/limits#kv-preloading).
 - **Configure max runners.** Go to Settings > Providers > Edit Provider > Max Runners to set the limit. The default is 100,000 runners. This is effectively your max actor count.
 - **Verify your platform rate limit accommodates your actor create and wake frequency.** Actor start requests are sent from Rivet's servers, so they all originate from the same IP. Per-IP rate limits will throttle the engine well before they would throttle real end-user traffic. Size your platform's rate limit to your peak actor create and wake rate, not your end-user request rate.
-- **Configure platform max concurrency if available.** Some platforms (e.g. GCP Cloud Run, AWS Lambda) let you cap the number of concurrent instances. Set this to match your expected concurrent actor count so the platform admits enough instances to host your actors.
+- **Set the per-instance max concurrent actor limit.** Each serverless instance hosts one actor per in-flight `/api/rivet/start` request, so your platform's per-instance concurrency (e.g. GCP Cloud Run `--concurrency`, AWS Lambda reserved concurrency, Vercel `maxDuration` + concurrency) directly caps actors per instance. Pick a value based on per-actor memory and CPU; the platform autoscales out additional instances once existing ones hit the cap.
+- **Tune `requestLifespan` to your platform's hard request timeout.** `requestLifespan` (default `3600`, 60 minutes) is the total lifespan of each serverless request before actors migrate to a fresh instance. Set it just below your platform's hard timeout (e.g. `295` for Vercel Hobby, `3595` for Vercel Pro, `840` for Cloud Run's 15-min cap). Configure via [`configurePool`](/docs/general/registry-configuration). See [Timeouts](/docs/general/runtime-modes#timeouts).
+- **Tune `drainGracePeriod` to cover graceful actor shutdown.** Time reserved at the end of `requestLifespan` for actors to stop gracefully before the request is forcibly closed. Default is 30 minutes from the engine; lower it for short-lived stateless actors, raise it if your actors do non-trivial cleanup or final SQLite writes. Configure via [`configurePool`](/docs/general/registry-configuration). See [Limits](/docs/actors/limits).
 
 ### Runner