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

docs/gateway.md

@@ -84,21 +84,22 @@ unix-domain socket as each agent opts in. The mechanism:
    harness's `unlink + bind(2)` cycle on socket replace. Per-agent
    subdir keeps each agent's container blind to siblings' sockets.
 3. **Marker gate**. After successful `bind_unix`, the harness drops
-   `<dir>/.bound` next to the socket. c0re's `agent_sockets::write`
-   filters its JSON map by marker presence — only agents whose
-   harness has actually bound the socket appear there. Without this
-   filter, the gateway would `proxy_pass` to a non-existent socket
-   for every sub-agent that hasn't opted in yet.
+   `<dir>/hyperhive-socket-bound` next to the socket. c0re's
+   `agent_sockets::write` filters its JSON map by marker presence —
+   only agents whose harness has actually bound the socket appear there.
+   Without this filter, the gateway would `proxy_pass` to a non-existent
+   socket for every sub-agent that hasn't opted in yet. (Legacy name
+   `.bound` also accepted during the transition window.)
 4. **Gateway side**. `gateway_nginx::write` generates
    `/var/lib/hyperhive/agents.conf` — a plain nginx include file with
    one `location /agent/<name>/` block per agent. UDS upstream
-   (`http://unix:/run/hive-agent/<name>/web.sock:/`) when `.bound`
-   marker present; TCP loopback otherwise. The gateway container
-   bind-mounts `/var/lib/hyperhive/` at `/run/hive-state/`; nginx
-   includes `/run/hive-state/agents.conf`. A systemd path unit
-   (`hive-gateway-agents-conf.path`) inside the container watches the
-   file and fires `nginx -s reload` on every atomic rename from c0re
-   — no `nixos-rebuild` needed (#869).
+   (`http://unix:/run/hive-agent/<name>/web.sock:/`) when
+   `hyperhive-socket-bound` marker present; TCP loopback otherwise.
+   The gateway container bind-mounts `/var/lib/hyperhive/` at
+   `/run/hive-state/`; nginx includes `/run/hive-state/agents.conf`.
+   A systemd path unit (`hive-gateway-agents-conf.path`) inside the
+   container watches the file and fires `nginx -s reload` on every
+   atomic rename from c0re — no `nixos-rebuild` needed.
 
 c0re regenerates `agents.conf` (and fires the path unit → reload) on
 two triggers: every topology change (new/removed agents) and every

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)