diff --git a/server/src/session/claude.rs b/server/src/session/claude.rs
index 2b57f02..99c7803 100644
--- a/server/src/session/claude.rs
+++ b/server/src/session/claude.rs
@@ -695,6 +695,17 @@ async fn follow(
 /// The offset only ever advances by this, which is what lets a read land
 /// anywhere -- mid-line, mid-character -- without the reader losing its
 /// place. See the call site for why the remainder is not kept.
+///
+/// A line ends at `\n` and at nothing else, deliberately. This stream is
+/// JSONL: a record is a line, and something terminated by a bare `\r` is
+/// not a record, so treating one as a line would hand `serde_json` a
+/// fragment. The accepted consequence is that such a line is held here
+/// forever rather than being reported -- and it is worth knowing what
+/// that would look like, because it looks like nothing: the session goes
+/// quiet with the process healthy, no error anywhere, and the cause is a
+/// line splitter, which is not where anybody would look. A progress
+/// indicator is the usual reason a program writes one (`\r` is how it
+/// redraws in place), and the CLI has never written one here.
 fn complete_lines(bytes: &[u8]) -> usize {
     bytes
         .iter()