From ca194f5c91fecea117682ca2721e452bcf239696 Mon Sep 17 00:00:00 2001
From: atlas <atlas@hyperhive.local>
Date: Wed, 28 Oct 2026 02:22:55 +0100
Subject: [PATCH] state the heal_own_dir cause in the backend env comments

---
 nix/agent-modules/backend-env.nix |  5 +++--
 swarm-secret-client/src/policy.rs | 11 ++++++-----
 2 files changed, 9 insertions(+), 7 deletions(-)

diff --git a/nix/agent-modules/backend-env.nix b/nix/agent-modules/backend-env.nix
index 806fab19..57e548df 100644
--- a/nix/agent-modules/backend-env.nix
+++ b/nix/agent-modules/backend-env.nix
@@ -21,8 +21,9 @@
 # The leaf's create grant cannot constrain content, so while the leaf is empty
 # the agent's own process can also create it with any text, and the store's
 # value then wins over the file. That is no wider than the file the agent
-# already owns: `./user.nix`'s `heal_own_dir` chowns the harness dir to the
-# agent at every activation, a gap the issue tracker has an open bug for.
+# already owns: the container activation's `heal_own_dir` (`./user.nix`)
+# re-owns the harness dir to the agent recursively at every boot, so the agent
+# already controls the legacy file.
 #
 # The unit runs as root because the file is root-owned `0600` where an operator
 # placed it. Root can still read the agent's `0400` store identity.
diff --git a/swarm-secret-client/src/policy.rs b/swarm-secret-client/src/policy.rs
index 4303cfd4..0bb4e263 100644
--- a/swarm-secret-client/src/policy.rs
+++ b/swarm-secret-client/src/policy.rs
@@ -209,11 +209,12 @@ const ENTITY_NAME_TEMPLATE: &str = "{{identity.entity.name}}";
 /// process holds the identity, so while the leaf is empty it can also create it
 /// with any text, and the store's value then wins over the file. That is no
 /// wider than the harness-dir file the agent already owns:
-/// `nix/agent-modules/user.nix`'s `heal_own_dir` chowns that dir to the agent at
-/// every activation, a gap the issue tracker has an open bug for. Any other
-/// write would let an agent hand itself an identity it was never issued. An agent has no business with another agent's
-/// credentials, a hive's, a service's, or the controller's, so none of
-/// [`render_shared_hives`]'s breadth applies. A hive still reads this
+/// the container activation's `heal_own_dir` (`nix/agent-modules/user.nix`)
+/// re-owns that dir to the agent recursively at every boot, so the agent
+/// already controls the legacy file. Any other write would let an agent hand
+/// itself an identity it was never issued. An agent has no business with
+/// another agent's credentials, a hive's, a service's, or the controller's, so
+/// none of [`render_shared_hives`]'s breadth applies. A hive still reads this
 /// agent's secrets, and closing that is its own decision.
 #[must_use]
 pub fn render_shared_agent() -> String {