From 448b703995dfacacd8c905405150ad305a934a05 Mon Sep 17 00:00:00 2001
From: atlas <atlas@hyperhive.local>
Date: Sat, 7 Nov 2026 22:58:56 +0100
Subject: [PATCH] hivectl agent watch: document control-char replacement and
 the quiet exit on a closed pipe

---
 docs/2-handbook/hives/hivectl-cli.md | 2 +-
 docs/2-handbook/hives/hivectl.md     | 5 +++++
 hivectl/src/cli.rs                   | 4 +++-
 3 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/docs/2-handbook/hives/hivectl-cli.md b/docs/2-handbook/hives/hivectl-cli.md
index f3b19a15..1dea875e 100644
--- a/docs/2-handbook/hives/hivectl-cli.md
+++ b/docs/2-handbook/hives/hivectl-cli.md
@@ -193,7 +193,7 @@ A fresh session by default, or resume a prior one. Requires root or `hive-admin`
 
 Follow this agent's live turn/tool-call event stream from the CLI.
 
-Prints one compact line per event as they happen. `Ctrl-C` to stop. Requires the agent to be running.
+Prints one compact line per event as they happen. Control characters in agent-written text print as U+FFFD. A closed stdout (`watch | head`) ends the watch with exit 0. `Ctrl-C` to stop. Requires the agent to be running.
 
 **Usage:** `hivectl agent watch`
 
diff --git a/docs/2-handbook/hives/hivectl.md b/docs/2-handbook/hives/hivectl.md
index a316f961..0643d959 100644
--- a/docs/2-handbook/hives/hivectl.md
+++ b/docs/2-handbook/hives/hivectl.md
@@ -157,3 +157,8 @@ the harness already stamps onto stream-json events for the web UI
 glyph-prefixed lines instead of raw JSON. Not an attempt at the web
 UI's full collapsible-details rendering (`docs/4-implementation/web-ui/terminal-rendering.md`)
 — that's presentation for a browser, this is a `tail -f`.
+
+Agents write these lines, so hivectl replaces every control character except
+tab with U+FFFD before printing; an escape sequence in a summary
+can't reach your terminal. When stdout closes, as in `watch | head`, the
+watch ends with exit 0 and no output.
diff --git a/hivectl/src/cli.rs b/hivectl/src/cli.rs
index 169e5ee0..867820ba 100644
--- a/hivectl/src/cli.rs
+++ b/hivectl/src/cli.rs
@@ -272,7 +272,9 @@ pub enum AgentCmd {
     },
     /// Follow this agent's live turn/tool-call event stream from the CLI.
     ///
-    /// Prints one compact line per event as they happen. `Ctrl-C` to stop.
+    /// Prints one compact line per event as they happen. Control characters
+    /// in agent-written text print as U+FFFD. A closed stdout (`watch | head`)
+    /// ends the watch with exit 0. `Ctrl-C` to stop.
     /// Requires the agent to be running.
     Watch,
     /// This agent's disk accounting + optional quota via btrfs qgroups.