From 73a58776fa66f949a12f5f2f33e39a64028c1df8 Mon Sep 17 00:00:00 2001 From: lexis Date: Mon, 22 Jun 2026 23:27:33 +0200 Subject: [PATCH] docs(turn-loop): document graceful stop recv behavior (follow-up to #1920) --- docs/turn-loop.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) 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: ""`). Non-blocking — returns a question id; the answer arrives as a `question_answered` system event in the