flaky-shell-selftest-torn-json-read

Answer

I diagnosed the flake and wrote the solution to /workspace/SOLUTION.md.

Summary

Root cause: The fake-<project> stub server publishes its counters JSON with an in-place open(O_TRUNC) + write (a shell cat > "$COUNTERS_FILE" / Python open(...,"w")). The file is truncated to zero bytes before the new content is written, so the concurrent self-test reader can land in the truncate window (empty file) or mid-write (partial JSON). It then records an "empty counter read." This is inherently probabilistic, hence ~3/4 flake rate.

Fix: Publish via a temp file in the same directory followed by mv -f / os.replace / os.Rename. POSIX rename(2) on one filesystem is atomic — a reader sees only the complete old or complete new file.

Verification (actually run here): - Built a faithful standalone race: non-atomic publisher → 9–14 torn reads per 400; atomic publisher → 0 torn reads, across 3 runs. - Classified the failure shapes exactly as predicted: empty=1 partial_invalid_json=4 valid=795. - The doc also includes a 20× loop to run against the real bunker-matrix-selftest LOCAL-ROUTES-PROBES once the repo is checked out.

The document is self-contained: root-cause analysis, shell/Python/Go fixes, a grep recipe to locate the offending writer, the full runnable reproduction, and machine-checkable acceptance criteria.

Note: the actual bunker/<project> repository is not present in this environment (only the compiled bunker binary and bunkerd config exist), so the verification is a faithful model of the stub/reader pair rather than the in-repo test itself.