Run the suite in randomized order in CI and document the rule

A file order that happens to work is not evidence of isolation; only
running with --randomize catches a test that leans on another file's
side effects. Fixing the leaks this uncovered is only durable if the
check keeps running, so add a CI step alongside the canonical run and
write the underlying rule into AGENTS.md.

Author: TheGreatAxios

.github/workflows/ci.yml

@@ -41,3 +41,9 @@ jobs:
       # inference package (vendor/) is out of scope for this repo's CI.
       - name: Test
         run: bun run test
+
+      # Catches tests that only pass because of the default file order (shared
+      # module-level state, an unrestored global mock, a leaked env var). The
+      # seed is fixed so a failure here reproduces locally with the same flag.
+      - name: Test (randomized order)
+        run: bun test ./src ./tests ./evals --randomize --seed 424242

AGENTS.md

@@ -33,6 +33,7 @@ When refactoring replaces an old path, delete the old one. No back-compat shims,
 - Add or update tests with every behavior change.
 - Bug fixes start with a failing test that reproduces the bug. Do not start by patching.
 - `tests/unit/` shared unit tests and helpers · co-located `src/**/*.test.ts` for module logic · `tests/fixtures/` fixture repos · `tests/integration/` reactor/permission harness. Planned: `tests/e2e/` (fixture-repo runs).
+- A test must not depend on another file having run, or on the default file order. It must pass under `bun test ./src ./tests ./evals --randomize`. If a test mutates module-level state or calls `mock.module`, it must restore that state itself (`afterEach`/`afterAll`), not rely on the process happening to reset it. When capturing a module's real exports to restore later, shallow-copy them at capture time (`{ ...(await import(path)) }`) — Bun mutates the live namespace object in place when the module is mocked, so holding a bare reference to it silently turns into the mocked exports.
 
 ## Build & Validation