diff --git a/docs/turn-loop.md b/docs/turn-loop.md
index 2a435269..31457e47 100644
--- a/docs/turn-loop.md
+++ b/docs/turn-loop.md
@@ -505,7 +505,11 @@ ttl_seconds?, to?)`, `answer(id, answer)`.
   immediately. Positive value parks the turn up to that many seconds
   (cap 180) — incoming messages wake instantly. `max` (default 1, cap
   32) drains up to N rows; `wait_seconds` applies to the first, then
-  drains up to `max` total.
+  drains up to `max` total. **Graceful shutdown**: when the harness
+  receives a stop signal, the inbox becomes fenced and `recv` returns an
+  explicit `from: "graceful-stop"` message instead of an empty inbox.
+  This unmissably directs the agent to flush durable state (`/state`
+  files) and end the turn — the container exits when the turn completes.
 - `ask` — surface a structured question to the operator (default) or
   a peer agent (`to: "<agent>"`). Non-blocking — returns a question
   id; the answer arrives as a `question_answered` system event in the