From e0e7370beabe4150dbdca12149b26c12a97a1b08 Mon Sep 17 00:00:00 2001
From: Teknium <127238744+teknium1@users.noreply.github.com>
Date: Fri, 17 Jul 2026 06:27:30 -0700
Subject: [PATCH] docs(agents): document the file-retry flake policy

---
 AGENTS.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 63247b2bf47..49596b9b41b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1294,6 +1294,14 @@ scripts/run_tests.sh tests/agent/test_foo.py::test_x  # one test
 scripts/run_tests.sh -v --tb=long                     # pass-through pytest flags
 ```
 
+**Flake policy:** the runner auto-retries a failing test FILE once in a fresh
+subprocess (`--file-retries`, default 1; `HERMES_TEST_FILE_RETRIES=0` to
+disable). Pass-on-retry counts as green but is printed in a `⚠ FLAKY` summary
+section with both attempts' output. A FLAKY report is a bug to fix, not noise
+to ignore — timing-sensitive tests must not assume a quiet runner (loose
+wall-clock bounds ≥ 2s, event-based sync, no `assert not _wait_until(...)`
+negative-timing races).
+
 #### Subprocess-per-test-file isolation
 
 Every test file runs in a freshly-spawned Python subprocess via `run_tests_parallel.py`. This means module-level dicts/sets and