From 73bf7bef95716590637c87f50617f7bf7fa835e7 Mon Sep 17 00:00:00 2001
From: damocles <damocles@hyperhive>
Date: Mon, 1 Jun 2026 13:56:46 +0200
Subject: [PATCH] docs: document harness/ dir layout including bash-tasks

---
 docs/persistence.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/docs/persistence.md b/docs/persistence.md
index 386e9e0c..bc77d7b8 100644
--- a/docs/persistence.md
+++ b/docs/persistence.md
@@ -174,6 +174,18 @@ Under `/var/lib/hyperhive/agents/<name>/`:
   inside the container (uniform for sub-agents + manager).
   The `$HYPERHIVE_STATE_DIR` env var exposes the same path to
   in-container scripts.
+- `harness/` — harness-internal ephemeral state; not intended for
+  agent consumption. Bind-mounted to `/agents/<name>/harness`
+  inside the container (`$HYPERHIVE_HARNESS_DIR`). Contents:
+  - `bash-tasks/` — task JSON + stdout/stderr files for
+    background `bash_run` jobs. JSON files are
+    `<id>.json` (status + tails), `<id>.out` / `<id>.err`
+    (full captured output). Cleaned up by the agent after
+    inspecting with `bash_status`.
+  - `hyperhive-events.sqlite` — turn-loop event log.
+  - `hyperhive-turn-stats.sqlite` — per-turn timing stats.
+  - `hyperhive-harness.json` — consolidated flags (rate-limited,
+    model override, etc.) written atomically on each turn.
 
 Under `/var/lib/hyperhive/applied/<name>/` — the hive-c0re-only
 applied repo. Tracks `flake.nix` (module-only boilerplate; never