From 1aa35974ee883d2ffd39e546d101a24134c79aca Mon Sep 17 00:00:00 2001
From: damocles <damocles@hyperhive.local>
Date: Wed, 26 Aug 2026 23:40:49 +0200
Subject: [PATCH] backendEnvironmentFile: use the harness dir, not state, per
 review

---
 docs/turn-loop/config.md            | 11 +++++++----
 nix/agent-modules/agent-service.nix | 17 +++++++++++------
 2 files changed, 18 insertions(+), 10 deletions(-)

diff --git a/docs/turn-loop/config.md b/docs/turn-loop/config.md
index 113feb32..a6765679 100644
--- a/docs/turn-loop/config.md
+++ b/docs/turn-loop/config.md
@@ -244,7 +244,7 @@ programmatically and do not pass `--message-format json` themselves.
 ```nix
 hyperhive.useApiKey = true;               # default: false
 hyperhive.backendEnvironmentFile =
-  "/agents/myagent/state/openrouter.env"; # default: null
+  "/agents/myagent/harness/openrouter.env"; # default: null
 hyperhive.model = "anthropic/claude-3.5-sonnet"; # provider-specific model string
 ```
 
@@ -275,14 +275,17 @@ the store is world-readable and travels with the flake closure):
 ```sh
 # on the host, once per agent that should use an api-key backend
 sudo install -m 0600 -o root /dev/stdin \
-  /var/lib/hyperhive/agents/<name>/state/openrouter.env <<KEYS
+  /var/lib/hyperhive/agents/<name>/harness/openrouter.env <<KEYS
 ANTHROPIC_BASE_URL=https://openrouter.ai/api/v1
 ANTHROPIC_API_KEY=sk-or-...
 KEYS
 ```
 
-The file lives in the agent's bind-mounted state dir, so it survives
-container rebuilds (not `--purge`) without needing to be re-provisioned.
+The file lives in the agent's bind-mounted **harness** dir, not `state/`
+— `harness/` survives container rebuilds exactly like `state/` does, but
+(unlike `state/`) is never bind-mounted into a parent agent's container
+(see `docs/persistence.md`'s "Parent access to child state"), so an API
+key placed here is reachable by nothing but this agent and the host.
 
 ⚠️ Verified end-to-end against OpenRouter has not happened as of this
 writing — `ANTHROPIC_BASE_URL` support in the shipped Claude CLI is
diff --git a/nix/agent-modules/agent-service.nix b/nix/agent-modules/agent-service.nix
index a4494748..dd2226ed 100644
--- a/nix/agent-modules/agent-service.nix
+++ b/nix/agent-modules/agent-service.nix
@@ -131,7 +131,7 @@ in
   options.hyperhive.backendEnvironmentFile = lib.mkOption {
     type = lib.types.nullOr lib.types.str;
     default = null;
-    example = "/agents/myagent/state/openrouter.env";
+    example = "/agents/myagent/harness/openrouter.env";
     description = ''
       Path (outside the nix store) to a systemd `EnvironmentFile` loaded
       by the harness service — the mechanism for supplying
@@ -148,11 +148,16 @@ in
       ANTHROPIC_BASE_URL=https://openrouter.ai/api/v1
       ```
 
-      Place the file inside the agent's bind-mounted state dir (e.g.
-      `/agents/<name>/state/openrouter.env`) so it survives container
-      rebuilds; permissions should be `0600`, owned by the agent's unix
-      user. Loaded with a leading `-` (optional `EnvironmentFile`), so a
-      path that doesn't exist yet — an operator setting this option
+      Place the file inside the agent's bind-mounted **harness** dir (e.g.
+      `/agents/<name>/harness/openrouter.env`, `$HYPERHIVE_HARNESS_DIR`),
+      not `state/` — `harness/` survives container rebuilds exactly like
+      `state/` does, but is never bind-mounted into a parent agent's
+      container (unlike `state/`, which a parent gets read-write for child
+      recovery — see `docs/persistence.md`'s "Parent access to child
+      state"), so this credential is reachable by nothing but this agent
+      and the host. Permissions should be `0600`, owned by the agent's
+      unix user. Loaded with a leading `-` (optional `EnvironmentFile`),
+      so a path that doesn't exist yet — an operator setting this option
       before creating the file, or a fresh host rebuild before state is
       restored — makes systemd skip it rather than refuse to start the
       harness. See `hyperhive.useApiKey`'s doc for the option this one is