docs(agents): the firmware tree and the bench are shared, and tests can reach them

[jamesarich]

Two hazards AGENTS.md did not cover, both hit during 2.8.0 soak prep.

One firmware tree, shared by every session. MESHTASTIC_FIRMWARE_ROOT names a single checkout and clients set it identically for every session and worktree on the machine, so concurrent agents build in one .pio tree. PlatformIO rewrites project.checksum and cleans .pio/build/* when the env changes — on 2026-08-26 a finished 8-minute seeed-xiao-s3 artifact was deleted by another session between build_poll returning done and the next ls. A done build is perishable: flash immediately.

Tests can reach the bench. A unit-test run in a worktree shelled out to a real pio run -e meshnology_w10 -t upload --upload-port /dev/cu.usbmodem1201 — a macOS path on a Linux host — and orphaned it to systemd --user. An invalid port is exactly what sends PlatformIO to auto-detect, the failure #73 fixed at the source (the 2026-08-25 meshnology_w10 image that boot-looped a Heltec Wireless Tracker V2). Recorded as an anti-pattern so the next test does not reinvent it.

Docs only.

Summary by CodeRabbit

• Documentation
  • Added guidance for coordinating shared firmware builds and multi-device sessions.
  • Documented the need to flash completed builds promptly and verify builder availability.
  • Added testing guidelines requiring mocked subprocesses and prohibiting access to real hardware or invalid upload ports.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: ea00008f-30e9-43eb-91e9-c062fd80fb2c

📥 Commits

Reviewing files that changed from the base of the PR and between 150f7aa and f0a006e.

📒 Files selected for processing (1)

• AGENTS.md

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

AGENTS.md now documents firmware-build concurrency controls and requires mocked PlatformIO upload subprocesses in tests.

Changes

Development Safety Guidance

Layer / File(s)	Summary
Build and test safety rules AGENTS.md	The guidance requires one shared firmware checkout and .pio tree, immediate flashing after builds, checks for concurrent pio run processes, and mocked PlatformIO uploads in tests.

Estimated code review effort: 1 (Trivial) | ~3 minutes

Merge Risk: ⚪ Minimal · up to f0a00

This is a docs-only change with no runtime or deployment impact; the remaining issue is a localized wording correction about explicit upload ports, so no actionable merge-blocking risk remains.

Suggested reviewers: garthvh, caveman99, thebentern

Poem

A rabbit checks the builder’s light

And keeps shared paths in sight
Fresh builds flash before they fade
Mocked uploads keep paws well stayed
Safe firmware hops through the night

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the documentation changes about the shared firmware tree, shared bench, and tests reaching hardware.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (1 skipped: 1 unsupported.)

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}