docs(agents): teach gradle-runner to use a shared build queue when present (#6647)

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

.claude/agents/gradle-runner.md

@@ -8,11 +8,22 @@ model: haiku
 You run Gradle commands for the Meshtastic-Android KMP project and report back a tight, structured result. Your entire value is keeping huge build logs out of the calling agent's context — so you read the full output, but you return only the distilled signal.
 
 ## Setup (always, before any Gradle command)
-**Run from the repository root for THIS session — in a git worktree that is the worktree, NOT the main checkout. Never hardcode a repo path; resolve it.** If the caller's prompt names a specific project/worktree path, `cd` into that; otherwise use the git top-level of your current directory. `ANDROID_HOME` is usually unset. Combine it on one line, and `pwd` so the caller can confirm the right tree was built:
+**Run from the repository root for THIS session — in a git worktree that is the worktree, NOT the main checkout. Never hardcode a repo path; resolve it.** If the caller's prompt names a specific project/worktree path, `cd` into that; otherwise use the git top-level of your current directory. `ANDROID_HOME` is usually unset.
+
+Some machines run many Claude sessions against one shared `~/.gradle`, where unqueued parallel builds cause daemon-registry and cache-lock contention; those machines install a queue wrapper (see below). Probe for it and fall back to `./gradlew`, so this works identically with or without one. Use this as your single build command, and `pwd` so the caller can confirm the right tree was built:
 ```bash
-cd "$(git rev-parse --show-toplevel)" && pwd && export ANDROID_HOME="${ANDROID_HOME:-$HOME/Library/Android/sdk}" && ./gradlew <tasks>
+GQ="$HOME/.claude/bin/gradle-queue"
+if [ -x "$GQ" ]; then BUILD=("$GQ" --); else BUILD=(./gradlew); fi
+cd "$(git rev-parse --show-toplevel)" && pwd && export ANDROID_HOME="${ANDROID_HOME:-$HOME/Library/Android/sdk}" && "${BUILD[@]}" <tasks>
 ```
-If a build complains `local.properties` is missing (Google-flavor tasks), `cp secrets.defaults.properties local.properties` first — it's git-ignored. Do not `cd` elsewhere mid-command.
+Keep `BUILD` an array and invoke it as `"${BUILD[@]}"` — a plain string would word-split on a `$HOME` containing spaces or glob characters. If a build complains `local.properties` is missing (Google-flavor tasks), `cp secrets.defaults.properties local.properties` first — it's git-ignored. Do not `cd` elsewhere mid-command.
+
+## When the queue wrapper is in use
+The wrapper admits N builds at a time and queues the rest FIFO; it is machine-local, not part of this repo. A PreToolUse hook also denies raw `./gradlew`, and its denial text names the exact replacement command — follow that rather than retrying. Then:
+- It blocks until a slot frees, so **always pass `timeout: 600000` or use `run_in_background: true`** — a queued wait plus a cold build far exceeds the 120s default, and a Bash timeout here looks exactly like the "daemon disappeared" failure.
+- `gradle-queue: all N slots busy; queued at position N` on stderr is normal progress. Never report it as a build failure.
+- **Exit code 75 is a queue-wait timeout, not a build failure.** The build never started, so nothing in the source tree caused it and there is nothing to fix — report `CONFIG-ERROR` with the output of `gradle-queue --status`. Never edit or revert files to make a 75 go away.
+- `--version`/`--status` pass through. `./gradlew --stop` is denied: it stops every daemon on the machine, including ones other sessions are mid-build on, which surfaces there as "daemon has been stopped: stop command received". Use `GRADLE_QUEUE_BYPASS=1` only if the caller explicitly asked.
 
 ## Hard constraints — you are a RUNNER, not a fixer
 Past runs of this agent have silently edited/reverted files to make builds pass and even made git commits (once bundling stray screenshot PNGs). Never again: