From a6b0c585112dcf08e772e4a450e1f5a28f7867c8 Mon Sep 17 00:00:00 2001
From: dedysutanto <dedysutanto@gmail.com>
Date: Thu, 1 Oct 2026 15:55:16 +0700
Subject: [PATCH] docs: note header rebuild gotcha (no -MMD dep tracking)

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

diff --git a/AGENTS.md b/AGENTS.md
index 0ea2785..494ffcf 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -61,6 +61,13 @@ cd tcp-proxy && make
 
 Env knobs (make vars): `ZT_DEBUG`, `ZT_TRACE`, `ZT_SANITIZE`, `ZT_STATIC`, `ZT_OFFICIAL`, `ZT_CONTROLLER`, `ZT_SSO_SUPPORTED` (0 on Linux default → no cargo needed), `ZT_VAULT_SUPPORT`, `ZT_IA32`.
 
+**Build hygiene — no header dependency tracking.** The makefiles emit no `-MMD` `.d` files, so `.o` outputs never rebuild when a header changes. A tree that ships prebuilt objects (root `one.o`, `node/*.o`, `libbackonecore.a` — present in this checkout) plus any `.hpp` edit produces ABI-mismatched objects; symptom is an instant `SIGSEGV` at `Topology::Topology` during `./backone` startup with a null call target. `make clean` after touching any `.hpp`, and verify startup after every build:
+
+```sh
+rm -rf /tmp/bohome && mkdir -p /tmp/bohome
+timeout 8 ./backone -p9999 -U /tmp/bohome   # exit 124 (timeout) = healthy; 139 = crash
+```
+
 ## Code Conventions & Common Patterns
 
 - **Standard: C++17** (`-std=c++17` in all makefiles; `tcp-proxy` is C++11). Ignore stale comments claiming otherwise (`node/README.md` "No C++11", `osdep/BlockingQueue.hpp:30`).