From 0cd84bfde1116fa8be9dcedd64463146547a1196 Mon Sep 17 00:00:00 2001
From: Brennan Benson <79079362+brennanb2025@users.noreply.github.com>
Date: Sun, 16 Aug 2026 20:17:32 -0700
Subject: [PATCH] docs(mobile-native-chat): name the hydration rebase's
 residual ambiguity

---
 mobile/src/session/mobile-native-chat-pending-baseline.ts | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/mobile/src/session/mobile-native-chat-pending-baseline.ts b/mobile/src/session/mobile-native-chat-pending-baseline.ts
index 4396cf97bc2..d381d9e60a0 100644
--- a/mobile/src/session/mobile-native-chat-pending-baseline.ts
+++ b/mobile/src/session/mobile-native-chat-pending-baseline.ts
@@ -15,6 +15,13 @@ import type { MobileNativeChatPendingMessage } from './mobile-native-chat-pendin
  * the send permanently untrustworthy, which stranded it as a queued bubble and
  * as a glue barrier for its neighbours for the rest of the session — leaves it
  * matching exactly the rows that arrive from now on.
+ *
+ * Residual: if this read was taken AFTER the send already echoed — a re-subscribe
+ * on tab switch or reconnect, when the first load never completed — its own echo
+ * is counted as history and the bubble waits for a row that will not come. The
+ * transport writes keystrokes into a TUI, so there is no client message id to
+ * tell the two apart; the send is bounded instead by serializing submits per PTY
+ * so the glue never forms.
  */
 export function rebaseMobileNativeChatPendingBaselines(
   messages: readonly NativeChatMessage[],