From 89030ff1e1b22c01c40eefbc1f9c713b00977b4b Mon Sep 17 00:00:00 2001
From: damocles <damocles@hyperhive>
Date: Mon, 1 Jun 2026 09:44:43 +0200
Subject: [PATCH] docs: clarify per-agent user comment in harness-base.nix

---
 nix/templates/harness-base.nix | 18 ++++++------------
 1 file changed, 6 insertions(+), 12 deletions(-)

diff --git a/nix/templates/harness-base.nix b/nix/templates/harness-base.nix
index ae45bb96..b14ae3ff 100644
--- a/nix/templates/harness-base.nix
+++ b/nix/templates/harness-base.nix
@@ -702,18 +702,12 @@ in
       }
     ];
 
-    # Per-agent unix user (#658). Runs the hive-ag3nt / hive-m1nd
-    # harness + co-process daemons (hive-matrix-daemon) under a
-    # non-root principal. The user name follows
-    # `hyperhive.user.name` — defaults to `"agent"` for standalone
-    # eval, overridden per-agent by the meta-flake to the agent's
-    # own label so each container has a uniquely-named user.
-    #
-    # UID auto-assigned by NixOS (per mara's #8109: "no hardcoded
-    # uids"). Home is `/home/${userName}`. `wheel` membership +
-    # the sudoers rule below grants `NOPASSWD: ALL` when
-    # `passwordlessSudo` is true — same blast radius as the
-    # previous root-by-default shape, just explicit.
+    # Per-agent unix user. Runs the hive-ag3nt / hive-m1nd harness +
+    # co-process daemons under a non-root principal. UID auto-assigned by
+    # NixOS. The container activation script (hive-agent-user-migrate)
+    # chowns the bind-mounted state dir — including credential files
+    # written by hive-c0re before the container was built — to this user
+    # on every boot, so agent processes can always read their own tokens.
     users.users.${userName} = {
       isNormalUser = true;
       home = homeDir;