From 18d0fbfecb66a1291634aaf7ca9035e03f1bbfbd Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive>
Date: Sun, 31 May 2026 16:04:32 +0200
Subject: [PATCH] hive-sh4re + docs: extract Wake-injection prose (#717 batch
 5)

---
 docs/conventions.md   | 17 +++++++++++++++++
 hive-sh4re/src/lib.rs | 19 ++++++-------------
 2 files changed, 23 insertions(+), 13 deletions(-)

diff --git a/docs/conventions.md b/docs/conventions.md
index a15b4a83..0b30c637 100644
--- a/docs/conventions.md
+++ b/docs/conventions.md
@@ -21,6 +21,23 @@ bind-mount." A sub-agent only sees its own `/run/hive/mcp.sock`; the
 manager has access to its privileged socket; hive-c0re owns the host
 admin socket.
 
+### Wake injection
+
+`AgentRequest::Wake { from, body }` (and the manager-flavour mirror)
+is the wake-event-injection surface. Recipient is implicit — the
+agent the socket belongs to — and `from` is caller-chosen so the
+wake prompt can label the source verbatim (`"matrix: new message in
+#general"`, `"forge: PR #42 opened"`, etc.). Typical caller: an
+in-container background task (the matrix daemon, a scraper, the
+forge-notify webhook subscriber) that needs to signal "external work
+has arrived" without going through the broker as a peer agent.
+
+Identity = socket means anything that can connect to
+`/run/hive/mcp.sock` is implicitly trusted to inject wakes. That's
+fine: the bind-mount only exposes the socket inside the agent's own
+container, so the trust boundary is the container's process
+namespace, not the wire surface.
+
 ## Recipient sentinels
 
 A few recipient names are reserved by the broker and have special
diff --git a/hive-sh4re/src/lib.rs b/hive-sh4re/src/lib.rs
index 0ec71a67..8809c44d 100644
--- a/hive-sh4re/src/lib.rs
+++ b/hive-sh4re/src/lib.rs
@@ -328,15 +328,10 @@ pub enum AgentRequest {
     /// per-agent equivalent of the old dashboard T4LK form, but scoped to
     /// the agent whose page the operator is on.
     OperatorMsg { body: String },
-    /// Wake-up event injected from inside the container — typically an
-    /// extra MCP server (matrix, scraper, webhook bridge) signalling
-    /// that external work has arrived for this agent. Recipient is
-    /// implicit (this agent); `from` is caller-chosen so the wake
-    /// prompt can label the source ("matrix: new message in
-    /// #general"). Identity = socket means anything that can connect
-    /// to `/run/hive/mcp.sock` is implicitly trusted to inject these,
-    /// which is fine: the bind-mount is restricted to the agent's
-    /// own container.
+    /// Wake-up event injected from inside the container. Recipient is
+    /// implicit (this agent); `from` is caller-chosen. See
+    /// `docs/conventions.md::Wake injection` for the trust model and
+    /// typical callers.
     Wake { from: String, body: String },
     /// Last `limit` messages addressed to this agent, newest-first.
     /// Non-mutating — pulls from the broker without delivering. The
@@ -835,10 +830,8 @@ pub enum ManagerRequest {
     /// Mirror of `AgentRequest::RequeueInflight` on the manager
     /// surface — fired exactly once on manager harness boot.
     RequeueInflight,
-    /// Mirror of `AgentRequest::Wake` on the manager surface. Used by
-    /// in-container background tasks (e.g. `forge_notify`) to push a
-    /// message into the manager's own broker inbox. `from` is caller-
-    /// chosen; `body` becomes the wake prompt body.
+    /// Mirror of `AgentRequest::Wake` on the manager surface. See
+    /// `docs/conventions.md::Wake injection`.
     Wake { from: String, body: String },
     /// Queue an approval to run `nix flake update [inputs...]` on the
     /// meta flake. `inputs` is the list of named inputs to update