From 0d84e11dcd33a2d0b06d6520dc84f65605456ee3 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Fri, 5 Jun 2026 15:15:36 +0200
Subject: [PATCH] docs(persistence): document hyperhive-status in state/ and
 mcp-loose-ends/ in harness/

---
 docs/persistence.md | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

diff --git a/docs/persistence.md b/docs/persistence.md
index c0c1019b..9d850c24 100644
--- a/docs/persistence.md
+++ b/docs/persistence.md
@@ -172,7 +172,16 @@ Under `/var/lib/hyperhive/agents/<name>/`:
 - `state/` — durable notes and `hyperhive-harness.json`. Bind-mounted
   to `/agents/<name>/state` inside the container (uniform for
   sub-agents + manager). The `$HYPERHIVE_STATE_DIR` env var exposes
-  the same path to in-container scripts.
+  the same path to in-container scripts. Notable files written here
+  by the harness:
+  - `hyperhive-status` — single-line free-text status string written
+    by `set_status`; cleared on explicit `set_status("")`. Read by
+    hive-c0re and the per-agent `/api/dashboard-state` endpoint to
+    surface the status chip on the dashboard. Absent when no status
+    is set.
+  - `hyperhive-harness.json` — rate-limited / needs-login flags read
+    by the dashboard's async container-state fetch. See
+    `docs/web-ui/dashboard.md::Container row`.
 - `harness/` — harness-internal ephemeral state; not intended for
   agent consumption. Bind-mounted to `/agents/<name>/harness`
   inside the container (`$HYPERHIVE_HARNESS_DIR`). Contents:
@@ -181,6 +190,13 @@ Under `/var/lib/hyperhive/agents/<name>/`:
     `<id>.json` (status + tails), `<id>.out` / `<id>.err`
     (full captured output). Task files persist until container
     purge.
+  - `mcp-loose-ends/` — JSON files published by external MCP daemons
+    (e.g. `hive-bash-mcp`, `hive-matrix-mcp`) listing their active
+    loose-end summary strings. Each file is `<daemon>.json` containing
+    a JSON array of plain-text lines. Read by `get_loose_ends` to
+    surface active background work without hardcoding per-MCP
+    knowledge in the harness. Files are created/removed by the
+    external daemons themselves.
   - `hyperhive-events.sqlite` — turn-loop event log.
   - `hyperhive-turn-stats.sqlite` — per-turn timing stats.
   - `hyperhive-model` — single-line model name override file.