refactor(#838): consolidate harness state files into hyperhive-harness.json

docs/persistence.md

@@ -104,17 +104,28 @@ the turn loop continue.
 No host-side vacuum yet — tracked separately. Target retention
 ~90 days, age-only sweep like events_vacuum.
 
-### `/state/hyperhive-rate-limited` (per agent)
+### `/state/hyperhive-harness.json` (per agent)
 
-Sentinel file written by `Bus::emit_status("rate_limited")` when the
-harness detects a 429 / rate-limit response from the Claude API, and
-removed when the retry sleep expires (any subsequent status emit
-clears it). The file's presence is checked by hive-c0re's
-`container_view::is_rate_limited` on each `build_all` sweep (~10s) to
-populate `ContainerView.rate_limited` for the dashboard. Survives a
-harness restart (the Bus reads it back at boot and restores the flag),
-so the badge remains accurate if hive-c0re restarts while the harness
-is mid-sleep.
+Consolidated harness state file written atomically (`.tmp` + rename) by
+`Bus::emit_status` whenever rate-limited or login-failed flags change.
+Shape:
+
+```json
+{ "rate_limited": false, "needs_login": false }
+```
+
+- `rate_limited` — set when the harness detects a 429 from the Claude
+  API; cleared by any subsequent status emit. Drives
+  `ContainerView.rate_limited` on the dashboard.
+- `needs_login` — set when a turn hits 401 (expired OAuth credentials);
+  cleared by `"online"` status (re-auth completed). Drives the
+  `needs_login` flag alongside the `claude_has_session` check.
+
+hive-c0re reads this file on each `build_all` sweep (~10s) via
+`container_view::read_harness_flags`. Falls back to the legacy individual
+sentinel files (`hyperhive-rate-limited`, `hyperhive-needs-login`) if the
+JSON is absent, so existing containers keep working through the transition
+window before their next rebuild.
 
 ### `/state/hyperhive-model` (per agent)