Serialize Gradle and test runs

AGENTS.md

@@ -277,12 +277,13 @@ The fast loop for grammar work:
   `ls -l build/classes/java/main/dev/hgh/jai/parser/JaiParser.class
   src/main/gen/dev/hgh/jai/parser/JaiParser.java`. The build wiring in
   `build.gradle.kts` should prevent both, but `rm -rf build` settles it.
-- **Concurrent Gradle runs corrupt the test results.** If something else (an
-  IDE, an agent's background checker) runs `test` at the same time, one of the
-  two dies with `java.io.EOFException` or
-  `NoSuchFileException: .../in-progress-results-generic.bin`, and no XML is
-  written. It is infrastructure, not a test failure — `./jaitest` retries once
-  automatically. Do not go debugging the test that "failed".
+- **Concurrent Gradle runs corrupt the test results.** `./jaigradle` and
+  `./jaitest` serialize project Gradle work with the atomic `.gradle-test.lock`
+  lock, including test-result cleanup and retries. Never run `./gradlew`
+  directly: it bypasses both the JDK wrapper and this lock. If an interrupted
+  process leaves a lock behind, confirm no Gradle run is active, then remove
+  `.gradle-test.lock` and rerun. The JUnit wrapper still retries once for
+  unexpected no-XML failures; do not debug a test until the XML exists.
 - **A poisoned build cache can make tests silently vanish.** Symptom:
   `BUILD SUCCESSFUL`, `:compileTestKotlin FROM-CACHE`, `:test NO-SOURCE`, and
   `build/classes/kotlin/test` is empty. The cache stored an empty output
@@ -293,7 +294,7 @@ The fast loop for grammar work:
 
   ```bash
   ./jaigradle --stop
-  rm -rf build .gradle ~/.gradle/caches/build-cache-1
+  rm -rf .gradle-test.lock build .gradle ~/.gradle/caches/build-cache-1
   ./jaitest
   ```