diff --git a/docs/test-toolchain.md b/docs/test-toolchain.md
index b9c7d95..0e65974 100644
--- a/docs/test-toolchain.md
+++ b/docs/test-toolchain.md
@@ -9,6 +9,21 @@ Run tests with `npm test` or `npx vitest run`. The repository config disables th
 browser mode explicitly. It does not configure the public mockerPlugin/interceptorPlugin,
 a Vitest UI or a browser-test dev server. Do not expose these test tools as a service.
 
+A test gets 30 seconds unless it names its own budget. The number is a hang detector, not a
+performance claim. On 27 September vitest's default of 5 s failed four tests that take 0.4 to 1.7 s
+on an idle machine, while another session's build and tests held the load average at 8 on four
+threads:
+
+| Test | Idle | Loaded |
+|---|---|---|
+| `weather.test.ts`, an uncertain absent batch | 401 ms | over 5 s |
+| `frozen-verification.live.test.ts`, the request captured before metadata calls | 784 ms | over 5 s |
+| `frozen-verification.live.test.ts`, a target-only row | 1114 ms | over 5 s |
+| `generation-migration.live.test.ts`, historical epochs from PostgreSQL | 1724 ms | over 5 s |
+
+A bound a client depends on is asserted by its own test, as in `tests/failure.test.ts`, never by
+this setting.
+
 ## Audit record, 15 September 2026
 
 The previous Vitest 1.6 toolchain produced four npm audit findings: one critical, one high
diff --git a/typescript/vitest.config.ts b/typescript/vitest.config.ts
index f1dd14c..f38d6bc 100644
--- a/typescript/vitest.config.ts
+++ b/typescript/vitest.config.ts
@@ -9,5 +9,11 @@ export default defineConfig({
     // The conformance runner reads files from ../conformance, which is outside this package. That is
     // deliberate: the vectors are shared, so they cannot live inside any one language's tree.
     root: '.',
+    // A hang detector, not a performance assertion: a hung test never finishes, so this number only
+    // decides how long it takes to say so. vitest's default of 5 s failed four tests on
+    // 27 September that take 0.4-1.7 s on an idle machine, while another session's build and tests
+    // held the load average at 8 on four threads. A test that names its own budget keeps it, and a
+    // bound a client depends on is asserted by its test (failure.test.ts), not by this setting.
+    testTimeout: 30_000,
   },
 })