hivectl agent watch: document control-char replacement and the quiet exit on a closed pipe

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`
 

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.

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.