StatusWriter: detect two processes writing one status file

[ampledata]

Three separate gateway integrations hit the same hazard independently today — dronecot (6 capture workers), aprscot (APRSWorker + SensorWorker) and sikw00fcot (three entry points, only two of which Conflicts= each other). Each integrator worked it out for themselves, which is a good sign the library should say it rather than leaving it to be rediscovered a fourth time.

The hazard

Every write serialises a whole document, so two processes sharing an app_name do not merge. The file alternates between two disjoint sets of counters once a second, and every reader sees whichever wrote last.

A UI shows figures flickering between two gateways' worth of traffic, and nothing anywhere reports a fault. It isn't a crash — which is exactly what makes it nasty.

What this adds

The rule is now stated in the module docstring: give the writer to the single choke point the workers feed, not to each worker.

And because a docstring only helps someone who reads it, StatusWriter now detects the case. Before replacing the file it checks whether the document there carries a different pid that is still alive; if so it warns once and records contended_with in its own output, so a UI can report that the figures may not be this gateway's.

Status file /run/sikw00fcot/status.json is also being written by PID 1443.
Each write replaces the whole document, so the two will overwrite one another
and readers will see only whichever wrote last. Give the StatusWriter to a
single choke point rather than to each worker.

Deliberately narrow, to avoid crying wolf

• a dead pid is not contention — that's our own previous run, and taking the file over is correct after a restart
• our own pid is not contention
• an absent or half-written file concludes nothing
• rate-limited to every 30 s, and stops entirely once it has something to say, so the common correct case costs nothing

Liveness uses os.kill(pid, 0), which sends no signal. A pid that exists but isn't ours to signal still counts as live.

Tests

6 new (29 in the module, 131 in the suite). All five mutations tried were caught:

Mutation	Caught
never detects contention	✅
warns per-write instead of once	✅
treats a dead pid as live	✅
flags our own pid	✅
drops the field from the document	✅

🤖 Generated with Claude Code

https://claude.ai/code/session_0197da7dhvcPoHxYKamrYqyM