From 79ada8aaceec5327db04d2ccd523ac961f499fea Mon Sep 17 00:00:00 2001
From: atlas <atlas@hyperhive.local>
Date: Fri, 2 Oct 2026 09:47:52 +0200
Subject: [PATCH] docs: state current behaviour (wake path, subagent todo)

---
 docs/tools/matrix.md   | 17 ++++++++++-------
 docs/tools/subagent.md |  4 ++--
 2 files changed, 12 insertions(+), 9 deletions(-)

diff --git a/docs/tools/matrix.md b/docs/tools/matrix.md
index 16558e10..533df340 100644
--- a/docs/tools/matrix.md
+++ b/docs/tools/matrix.md
@@ -132,16 +132,19 @@ Silently exits when the primary account has no token yet; the
 appears, and, on an agent with a store, a timer restarts it while it's
 down so it re-reads a token the swarm minted into the store.
 
-Incoming room events wake the agent via `AgentRequest::Wake` with
-`from: "matrix"`. The wake body format depends on the unread state:
+**Wake path**: after every sync the daemon upserts a harness-local todo
+on the in-agent socket for each unread room (keyed by its room id) and
+each pending invite (below). A new or changed todo wakes the agent with
+the generic prompt `you have todos — call get_loose_ends to see them`
+(from `todo`). The `[matrix]` lines reach the agent through
+`get_loose_ends`, one per room, as
+`- todo #<id> [matrix <room_id>, <age>s old]: <summary> (cancel_loose_end …)`.
+The summary depends on the room's unread state:
 
-- **Single room, one message**: `[matrix] <sender> in <room>: <body> —
+- **One unread message**: `[matrix] <sender> in <room>: <body> —
   use read_room to view, mark_read to clear`
-- **Single room, multiple messages**: `[matrix] N unread in <room> —
+- **Several unread messages**: `[matrix] N unread in <room> —
   use read_room to view, mark_read to clear`
-- **Multiple rooms**: `[matrix] unread messages:` followed by a
-  bulleted list (`- <room>: <sender>: <body>` or `- <room>: N unread`
-  per room)
 
 **Multi-account prefix**: when the daemon serves more than one account
 (`services.hyperhive.agent.matrixAccounts`), it prefixes every wake body and every invite todo
diff --git a/docs/tools/subagent.md b/docs/tools/subagent.md
index c36cbeed..ae372cc8 100644
--- a/docs/tools/subagent.md
+++ b/docs/tools/subagent.md
@@ -234,8 +234,8 @@ early exit — and on this box both land inside a second, so a `continue`
 that works answers about as fast as it did before. A five-second cap
 bounds the one case neither covers: a child that neither speaks nor
 exits, reported as started, with the end-of-turn todo left to say how it
-goes. That todo carries every failure that happens later in the turn,
-starting after the miss `continue` already handed the caller directly.
+goes. That todo carries every failure that happens after the one
+`continue` already returned to the caller.
 
 ## A killed turn