From 216f1d49a4136684d4cbfb45ea1213934f2b7de0 Mon Sep 17 00:00:00 2001
From: Brennan Benson <79079362+brennanb2025@users.noreply.github.com>
Date: Wed, 29 Jul 2026 16:31:13 -0700
Subject: [PATCH] docs(mobile): document the two per-route reset contracts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Both exported helpers exist for a non-obvious reason — they must be re-created or
re-derived per worktree, or a reused route inherits the previous workspace's
hydration state and the resurrection guard silently disarms.
---
 .../session/use-initial-session-terminal-autocreate.ts    | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/mobile/src/session/use-initial-session-terminal-autocreate.ts b/mobile/src/session/use-initial-session-terminal-autocreate.ts
index 1840261dc31..e71aa8a91aa 100644
--- a/mobile/src/session/use-initial-session-terminal-autocreate.ts
+++ b/mobile/src/session/use-initial-session-terminal-autocreate.ts
@@ -6,6 +6,10 @@ type InitialSessionTerminalAutoCreateState = {
   sawSessionTabs: boolean
 }
 
+/**
+ * Fresh auto-create bookkeeping. The route must re-create this on every worktree
+ * change, or a revisit inherits the previous workspace's `sawSessionTabs`.
+ */
 export function createInitialSessionAutoCreateState(): InitialSessionTerminalAutoCreateState {
   return { autoCreatedForWorktree: null, sawSessionTabs: false }
 }
@@ -81,6 +85,10 @@ export function useInitialSessionTerminalAutoCreate(
   ])
 }
 
+/**
+ * Tracks "tabs hydrated" per worktree so a reused route reports `false` until the
+ * new workspace's own snapshot lands, rather than inheriting the old one's.
+ */
 export function useWorktreeSessionTabsLoaded(
   worktreeId: string
 ): readonly [boolean, (loaded: boolean) => void] {