railmux 0.4.0.dev19__tar.gz → 0.4.0.dev21__tar.gz

{railmux-0.4.0.dev19/src/railmux.egg-info → railmux-0.4.0.dev21}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: railmux
-Version: 0.4.0.dev19
+Version: 0.4.0.dev21
 Summary: Terminal UI to navigate, resume, and start Claude Code and Codex sessions
 Author-email: Rightglow <zhang.taian@foxmail.com>
 License-Expression: MIT
@@ -384,10 +384,9 @@ Scrolling a live agent does not enter Preview. Direct `railmux` uses the
 terminal/tmux scrolling behavior; `railmux ssh` keeps its own bounded,
 per-pane history and normally preserves the live terminal's captured styling.
 When Railmux confirms that a running Codex session advanced after rewind or
-steering, it resets only the current terminal view before Codex redraws and
-invalidates that pane's SSH history generation. Retained tmux scrollback is not
-erased; the SSH history for that branched generation uses the canonical
-rollout so its abandoned suffix stays hidden.
+steering, it leaves the live terminal untouched and advances only that pane's
+SSH history generation. The SSH history for that branched generation uses the
+canonical rollout so its abandoned suffix stays hidden.
 
 Preview opens at the latest activity in `less`; large sessions are limited to
 their latest 2,000 saved records. Press `/` to search, `n`/`N` to move between
@@ -446,7 +445,10 @@ Each opened agent runs in a detached tmux session, so switching sessions does
 not interrupt it. To leave agents running when you quit Railmux, press `s` for
 soft quit in the confirmation popup; restarting the same Railmux instance then
 restores the usable workspace when those sessions are still available. A normal
-quit confirmation ends all running sessions instead.
+quit ends all running sessions instead and therefore requires a second
+confirmation. The first chooser has visible mouse buttons, but the final
+destructive confirmation remains keyboard-only; `y` and Enter keep their
+existing confirm meaning in both steps.
 
 All terminals attached to one managed Railmux window view the same UI process.
 Soft Quit therefore closes that shared UI for every attached view, although it

{railmux-0.4.0.dev19 → railmux-0.4.0.dev21}/README.md

@@ -341,10 +341,9 @@ Scrolling a live agent does not enter Preview. Direct `railmux` uses the
 terminal/tmux scrolling behavior; `railmux ssh` keeps its own bounded,
 per-pane history and normally preserves the live terminal's captured styling.
 When Railmux confirms that a running Codex session advanced after rewind or
-steering, it resets only the current terminal view before Codex redraws and
-invalidates that pane's SSH history generation. Retained tmux scrollback is not
-erased; the SSH history for that branched generation uses the canonical
-rollout so its abandoned suffix stays hidden.
+steering, it leaves the live terminal untouched and advances only that pane's
+SSH history generation. The SSH history for that branched generation uses the
+canonical rollout so its abandoned suffix stays hidden.
 
 Preview opens at the latest activity in `less`; large sessions are limited to
 their latest 2,000 saved records. Press `/` to search, `n`/`N` to move between
@@ -403,7 +402,10 @@ Each opened agent runs in a detached tmux session, so switching sessions does
 not interrupt it. To leave agents running when you quit Railmux, press `s` for
 soft quit in the confirmation popup; restarting the same Railmux instance then
 restores the usable workspace when those sessions are still available. A normal
-quit confirmation ends all running sessions instead.
+quit ends all running sessions instead and therefore requires a second
+confirmation. The first chooser has visible mouse buttons, but the final
+destructive confirmation remains keyboard-only; `y` and Enter keep their
+existing confirm meaning in both steps.
 
 All terminals attached to one managed Railmux window view the same UI process.
 Soft Quit therefore closes that shared UI for every attached view, although it

railmux-0.4.0.dev21/src/railmux/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.4.0.dev21"

{railmux-0.4.0.dev19 → railmux-0.4.0.dev21}/src/railmux/cli.py

@@ -45,6 +45,20 @@ _LOCAL_WATCHDOG_INTERVAL = 5.0
 _LOCAL_WATCHDOG_FAILURES = 3
 
 
+def _interactive_terminal_size() -> tuple[int, int] | None:
+    """Return an exact entry TTY size without manufacturing a fallback."""
+    if not sys.stdin.isatty() or not sys.stdout.isatty():
+        return None
+    for stream in (sys.stdout, sys.stdin):
+        try:
+            size = os.get_terminal_size(stream.fileno())
+        except (AttributeError, OSError):
+            continue
+        if 0 < size.columns <= 65535 and 0 < size.lines <= 65535:
+            return size.columns, size.lines
+    return None
+
+
 def _restore_terminal(attributes: list | None) -> None:
     if attributes is None:
         return
@@ -627,6 +641,7 @@ def main(argv: list[str] | None = None) -> int:
                         launch_prefix,
                         raw_args,
                         env=client_env,
+                        initial_size=_interactive_terminal_size(),
                     )
                 )
         cmd = tmux_server.launcher_argv(launch_prefix, raw_args)

{railmux-0.4.0.dev19 → railmux-0.4.0.dev21}/src/railmux/fast_display_client.py

@@ -39,7 +39,7 @@ from railmux.fast_display_history import (
     HistoryAction,
     LocalHistoryView,
     PeriodicPrefetchGate,
-    claim_batched_wheel,
+    claim_batched_forwarded_wheel,
     input_may_change_routes,
 )
 from railmux.fast_display_input import (
@@ -1423,6 +1423,73 @@ class TerminalSurface:
         self.interaction_active = False
 
 
+@dataclass
+class _DeferredHistoryPaint:
+    """Collapse one local-input batch into its final history viewport paint."""
+
+    render_history: bool = False
+    restore_live: bool = False
+
+    def defer(self, action: HistoryAction) -> None:
+        self.render_history = self.render_history or action.render_history
+        self.restore_live = self.restore_live or action.restore_live
+
+    def flush(
+        self,
+        surface: TerminalSurface,
+        screen: AppliedScreen | None,
+        overlays: tuple[tuple[HistorySnapshot, tuple[bytes, ...]], ...],
+        selection: tuple[SelectionSegment, ...],
+    ) -> None:
+        if screen is not None:
+            if self.restore_live:
+                # A viewport may have reached the live bottom and another may
+                # still be frozen. Restore the authoritative frame and compose
+                # only the final overlays in one terminal write.
+                surface.paint(full_repaint(screen), overlays, selection)
+            elif self.render_history:
+                surface.paint_overlays(screen, overlays, selection)
+        self.render_history = False
+        self.restore_live = False
+
+
+class _LocalInputBatch:
+    """Preserve local wheel distance while bounding forwarded wheel bursts."""
+
+    def __init__(self) -> None:
+        self._forwarded_wheel_directions: set[int] = set()
+        self._history_paint = _DeferredHistoryPaint()
+
+    def prepare(
+        self,
+        event: SgrMouseEvent,
+        action: HistoryAction,
+    ) -> tuple[HistoryAction | None, _DeferredHistoryPaint | None]:
+        if event.wheel_direction == 0:
+            return action, None
+        if action.forwarded_input:
+            if not claim_batched_forwarded_wheel(
+                event,
+                self._forwarded_wheel_directions,
+            ):
+                return None, None
+            return action, None
+        # Every locally owned history tick has already advanced the viewport.
+        # Defer only its terminal paint so a Windows/RDP read containing
+        # several SGR packets preserves the complete distance without issuing
+        # one synchronous pane repaint per packet.
+        return action, self._history_paint
+
+    def flush(
+        self,
+        surface: TerminalSurface,
+        screen: AppliedScreen | None,
+        overlays: tuple[tuple[HistorySnapshot, tuple[bytes, ...]], ...],
+        selection: tuple[SelectionSegment, ...],
+    ) -> None:
+        self._history_paint.flush(surface, screen, overlays, selection)
+
+
 def _remote_server_args(
     *,
     session: str,
@@ -2605,22 +2672,28 @@ def run(args: argparse.Namespace) -> int:
         if frame is not None:
             send_protocol_frame(frame)
 
-    def apply_history_action(action: HistoryAction) -> None:
+    def apply_history_action(
+        action: HistoryAction,
+        deferred_paint: _DeferredHistoryPaint | None = None,
+    ) -> None:
         nonlocal route_refresh_needed
         nonlocal history_info_until, claude_history_prompt_input
         overlays = history.overlays()
-        if action.restore_live and latest_screen is not None:
-            surface.paint(
-                full_repaint(latest_screen),
-                overlays,
-                selection.segments(),
-            )
-        elif action.render_history and latest_screen is not None:
-            surface.paint_overlays(
-                latest_screen,
-                overlays,
-                selection.segments(),
-            )
+        if deferred_paint is not None:
+            deferred_paint.defer(action)
+        else:
+            if action.restore_live and latest_screen is not None:
+                surface.paint(
+                    full_repaint(latest_screen),
+                    overlays,
+                    selection.segments(),
+                )
+            elif action.render_history and latest_screen is not None:
+                surface.paint_overlays(
+                    latest_screen,
+                    overlays,
+                    selection.segments(),
+                )
         if action.protocol_frame:
             send_protocol_frame(action.protocol_frame)
         if action.forwarded_input:
@@ -2637,7 +2710,7 @@ def run(args: argparse.Namespace) -> int:
 
     def handle_terminal_part(
         part: bytes | SgrMouseEvent,
-        handled_wheels: set[int],
+        input_batch: _LocalInputBatch,
     ) -> None:
         nonlocal route_refresh_needed
         nonlocal claude_history_prompt_input, claude_history_pending_choice
@@ -2900,15 +2973,18 @@ def run(args: argparse.Namespace) -> int:
                     selection_changed_rows(selection_before, selection_after),
                 )
             for replay_event in selection_action.replay_events:
-                if not claim_batched_wheel(replay_event, handled_wheels):
-                    continue
                 replay_action = history.pointer_event(
                     replay_event,
                     focused_pane_id,
                     status_row=status_row,
                     now=time.monotonic(),
                 )
-                apply_history_action(replay_action)
+                replay_action, deferred_paint = input_batch.prepare(
+                    replay_event,
+                    replay_action,
+                )
+                if replay_action is not None:
+                    apply_history_action(replay_action, deferred_paint)
             if selection_action.copy_data is not None:
                 surface.copy_to_clipboard(selection_action.copy_data)
                 character_count = len(
@@ -2944,15 +3020,15 @@ def run(args: argparse.Namespace) -> int:
                     begin_path_open(target)
             if selection_action.handled:
                 return
-            if not claim_batched_wheel(part, handled_wheels):
-                return
             action = history.pointer_event(
                 part,
                 focused_pane_id,
                 status_row=status_row,
                 now=time.monotonic(),
             )
-            apply_history_action(action)
+            action, deferred_paint = input_batch.prepare(part, action)
+            if action is not None:
+                apply_history_action(action, deferred_paint)
             return
         if not part:
             return
@@ -3327,19 +3403,32 @@ def run(args: argparse.Namespace) -> int:
                         data, emergency_exit = split_local_escape(data)
                         if emergency_exit:
                             local_exit = True
-                        handled_wheels: set[int] = set()
+                        input_batch = _LocalInputBatch()
                         for part in terminal_input.feed(data):
                             if isinstance(part, bytes):
                                 for key_part in split_page_key_input(part):
-                                    handle_terminal_part(key_part, handled_wheels)
+                                    handle_terminal_part(key_part, input_batch)
                             else:
-                                handle_terminal_part(part, handled_wheels)
+                                handle_terminal_part(part, input_batch)
+                        input_batch.flush(
+                            surface,
+                            latest_screen,
+                            history.overlays(),
+                            selection.segments(),
+                        )
                         if local_exit:
                             break
                 if not local_exit:
                     for part in terminal_input.flush_pending():
+                        input_batch = _LocalInputBatch()
                         for key_part in split_page_key_input(part):
-                            handle_terminal_part(key_part, set())
+                            handle_terminal_part(key_part, input_batch)
+                        input_batch.flush(
+                            surface,
+                            latest_screen,
+                            history.overlays(),
+                            selection.segments(),
+                        )
                 now = time.monotonic()
                 keyboard_projected = touch_keyboard.keyboard_projected
                 if touch_keyboard.expire(now):

{railmux-0.4.0.dev19 → railmux-0.4.0.dev21}/src/railmux/fast_display_history.py

@@ -109,6 +109,10 @@ class _PendingHistory:
     pane_id: str
     target_lines: int
     requested_at: float
+    # A first wheel-up waits for one cumulative snapshot before freezing the
+    # viewport. This avoids exposing a short hot suffix whose later deep page
+    # may not share a stable anchor while the provider is actively repainting.
+    initial_offset: int | None = None
 
 
 class LocalHistoryView:
@@ -266,8 +270,6 @@ class LocalHistoryView:
         self,
         previous: HistorySnapshot,
         incoming: HistorySnapshot,
-        *,
-        prefer_deeper: bool = False,
     ) -> HistorySnapshot:
         """Retain already-fetched history when a later hot capture shrinks."""
         if not self._same_geometry(
@@ -276,28 +278,13 @@ class LocalHistoryView:
             return incoming
         delta = self._timeline_delta(previous.lines, incoming.lines)
         if delta is None:
-            if prefer_deeper and len(incoming.lines) > len(previous.lines):
-                # A deep response reaches here only after accept() proved that
-                # the user's immutable frozen viewport still exists in it.
-                # Rewind/full-screen diff output can make every individual
-                # line in that viewport non-unique, leaving the generic
-                # timeline voter without two anchors.  The larger cumulative
-                # capture is nevertheless stronger than the 300-line hot
-                # cache; keeping only its live tail would silently discard all
-                # intermediate output above the current screen.
-                lines = incoming.lines
-            else:
-                # Never splice two captures whose timelines cannot be aligned.
-                # Retaining old history and replacing only the live viewport
-                # looked conservative, but it silently omitted every row
-                # produced between those two pieces. That false seam appeared
-                # as discontinuous SSH history until returning to the bottom
-                # forced a fresh deep capture. Keep the newest internally
-                # contiguous hot capture instead; the first wheel-up requests
-                # a cumulative deep page and can recover older rows safely.
-                # An already-frozen viewport owns its immutable snapshot and
-                # therefore remains undisturbed by this cache replacement.
-                lines = incoming.lines
+            # Never splice two captures whose timelines cannot be aligned.
+            # Retaining old history and replacing only the live viewport
+            # looked conservative, but it silently omitted every row produced
+            # between those two pieces. Keep the newest internally contiguous
+            # capture instead. An already-frozen viewport owns its immutable
+            # snapshot and therefore remains undisturbed by cache replacement.
+            lines = incoming.lines
         else:
             start = min(0, delta)
             incoming_end = delta + len(incoming.lines)
@@ -325,8 +312,6 @@ class LocalHistoryView:
     def _remember_content(
         self,
         snapshot: HistorySnapshot,
-        *,
-        prefer_deeper: bool = False,
     ) -> HistorySnapshot:
         assert snapshot.pane_id is not None
         previous = self.content_cache.get(snapshot.pane_id)
@@ -344,8 +329,7 @@ class LocalHistoryView:
             stored = self._merge_content(previous, snapshot) if anchored else snapshot
             self._unverified_after_reconnect.discard(snapshot.pane_id)
         else:
-            stored = self._merge_content(
-                previous, snapshot, prefer_deeper=prefer_deeper)
+            stored = self._merge_content(previous, snapshot)
         # Reinsert an existing pane to keep insertion order as recency order.
         self.content_cache.pop(snapshot.pane_id, None)
         self.content_cache[snapshot.pane_id] = stored
@@ -353,6 +337,15 @@ class LocalHistoryView:
             del self.content_cache[next(iter(self.content_cache))]
         return stored
 
+    def _replace_content(self, snapshot: HistorySnapshot) -> HistorySnapshot:
+        """Install one verified contiguous capture without timeline merging."""
+        assert snapshot.pane_id is not None
+        self.content_cache.pop(snapshot.pane_id, None)
+        self.content_cache[snapshot.pane_id] = snapshot
+        while len(self.content_cache) > _HISTORY_CONTENT_PANES:
+            del self.content_cache[next(iter(self.content_cache))]
+        return snapshot
+
     def invalidate_routes(self) -> bool:
         """Drop pointer authority without discarding bounded pane content."""
         was_active = self.cancel()
@@ -470,29 +463,32 @@ class LocalHistoryView:
         cached = self.content_cache.get(route.pane_id, route)
         if not self._same_geometry(cached, route):
             cached = route
+        loaded_limit = min(len(cached.lines), self.history_limit)
+        target_lines = min(self.history_limit, _HISTORY_INITIAL_LINES)
+        if (
+            cached.more_available
+            and loaded_limit < min(target_lines, _HISTORY_PREFETCH_LINES)
+        ):
+            self.cancel_pane(route.pane_id)
+            request_id = self._allocate_request_id()
+            self._deep_pending[request_id] = _PendingHistory(
+                self.route_epoch,
+                route.pane_id,
+                target_lines,
+                time.monotonic() if now is None else now,
+                max(1, initial_offset),
+            )
+            self._deep_requests += 1
+            # A byte-budgeted or older peer may return less than the normal
+            # coherent routing capture. Keep the live pane intact until one
+            # cumulative response arrives rather than expose a short suffix.
+            return HistoryAction(
+                protocol_frame=encode_history_request(
+                    request_id, event.x, event.y, target_lines
+                )
+            )
         maximum = max(0, len(cached.lines) - cached.height)
         if maximum == 0:
-            if cached.more_available:
-                self.cancel_pane(route.pane_id)
-                target_lines = min(self.history_limit, _HISTORY_INITIAL_LINES)
-                self.viewports[route.pane_id] = _HistoryViewport(
-                    cached,
-                    0,
-                    min(len(cached.lines), self.history_limit),
-                )
-                request_id = self._allocate_request_id()
-                self._deep_pending[request_id] = _PendingHistory(
-                    self.route_epoch,
-                    route.pane_id,
-                    target_lines,
-                    time.monotonic() if now is None else now,
-                )
-                self._deep_requests += 1
-                return HistoryAction(
-                    protocol_frame=encode_history_request(
-                        request_id, event.x, event.y, target_lines
-                    )
-                )
             if cached.transcript_backed:
                 # Claude may not have written its first transcript record yet.
                 # This is a normal transient state, not a Railmux status event:
@@ -503,7 +499,6 @@ class LocalHistoryView:
                 forwarded_input=event.raw if cached.mouse_forwardable else b""
             )
         self.cancel_pane(route.pane_id)
-        loaded_limit = min(len(cached.lines), self.history_limit)
         viewport = _HistoryViewport(
             cached,
             min(maximum, max(1, initial_offset)),
@@ -513,23 +508,15 @@ class LocalHistoryView:
             ),
         )
         self.viewports[route.pane_id] = viewport
-        target_lines = min(self.history_limit, _HISTORY_INITIAL_LINES)
-        if loaded_limit >= target_lines:
-            return HistoryAction(
-                protocol_frame=self._extend_history(viewport, now=now),
-                render_history=True,
-            )
-        request_id = self._allocate_request_id()
-        self._deep_pending[request_id] = _PendingHistory(
-            self.route_epoch,
-            route.pane_id,
-            target_lines,
-            time.monotonic() if now is None else now,
-        )
-        self._deep_requests += 1
+        # A complete 300-row routing capture is already one coherent history
+        # source. Paint it synchronously, then fetch a cumulative page only as
+        # the viewport approaches its top. This removes an SSH round trip from
+        # the first wheel tick without reintroducing a hot/deep splice.
         return HistoryAction(
-            protocol_frame=encode_history_request(
-                request_id, event.x, event.y, target_lines
+            protocol_frame=self._extend_history(
+                viewport,
+                now=now,
+                request_position=(event.x, event.y),
             ),
             render_history=True,
         )
@@ -539,6 +526,7 @@ class LocalHistoryView:
         viewport: _HistoryViewport,
         *,
         now: float | None = None,
+        request_position: tuple[int, int] | None = None,
     ) -> bytes:
         """Request the next cumulative page when a viewport nears its top."""
         snapshot = viewport.snapshot
@@ -572,7 +560,9 @@ class LocalHistoryView:
             return b""
         target_lines = min(
             self.history_limit,
-            max(_HISTORY_INITIAL_LINES, viewport.loaded_limit) + _HISTORY_PAGE_LINES,
+            _HISTORY_INITIAL_LINES
+            if viewport.loaded_limit < _HISTORY_INITIAL_LINES
+            else viewport.loaded_limit + _HISTORY_PAGE_LINES,
         )
         request_id = self._allocate_request_id()
         self._deep_pending[request_id] = _PendingHistory(
@@ -582,10 +572,14 @@ class LocalHistoryView:
             requested_at,
         )
         self._deep_requests += 1
-        return encode_history_request(
-            request_id,
+        request_x, request_y = request_position or (
             snapshot.x + 1,
             snapshot.y + 1,
+        )
+        return encode_history_request(
+            request_id,
+            request_x,
+            request_y,
             target_lines,
         )
 
@@ -602,6 +596,45 @@ class LocalHistoryView:
         if direction > 0 and route.history_choice_required:
             return HistoryAction(claude_history_prompt=event.raw)
         viewport = self.viewports.get(route.pane_id)
+        initial_request = next(
+            (
+                (request_id, pending)
+                for request_id, pending in self._deep_pending.items()
+                if pending.pane_id == route.pane_id
+                and pending.initial_offset is not None
+            ),
+            None,
+        )
+        if initial_request is not None:
+            request_id, pending = initial_request
+            requested_at = time.monotonic() if now is None else now
+            if requested_at - pending.requested_at >= _HISTORY_DEEP_TIMEOUT:
+                self._deep_pending.pop(request_id, None)
+                self._timeouts += 1
+                if direction < 0:
+                    return HistoryAction()
+                assert pending.initial_offset is not None
+                distance = min(
+                    self.history_limit,
+                    pending.initial_offset + max(1, distance),
+                )
+                initial_request = None
+        if viewport is None and initial_request is not None:
+            if direction < 0:
+                # The live pane never left the screen, so reversing direction
+                # simply cancels the pending entry. A late response is ignored.
+                self.cancel_pane(route.pane_id)
+                return HistoryAction()
+            request_id, pending = initial_request
+            assert pending.initial_offset is not None
+            self._deep_pending[request_id] = replace(
+                pending,
+                initial_offset=min(
+                    self.history_limit,
+                    pending.initial_offset + max(1, distance),
+                ),
+            )
+            return HistoryAction()
         if viewport is not None:
             maximum = max(0, len(viewport.snapshot.lines) - viewport.snapshot.height)
             viewport.offset = max(
@@ -828,8 +861,26 @@ class LocalHistoryView:
             return HistoryAction()
         viewport = self.viewports.get(pending.pane_id)
         if viewport is None:
-            self._remember_content(snapshot)
-            return HistoryAction()
+            if pending.initial_offset is None:
+                self._remember_content(snapshot)
+                return HistoryAction()
+            maximum = max(0, len(snapshot.lines) - snapshot.height)
+            if maximum == 0:
+                self._remember_content(snapshot)
+                return HistoryAction()
+            stored = self._replace_content(snapshot)
+            maximum = max(0, len(stored.lines) - stored.height)
+            viewport = _HistoryViewport(
+                stored,
+                min(maximum, pending.initial_offset),
+                min(self.history_limit, max(pending.target_lines, len(stored.lines))),
+                exhausted=not snapshot.more_available,
+            )
+            self.viewports[pending.pane_id] = viewport
+            return HistoryAction(
+                protocol_frame=self._extend_history(viewport),
+                render_history=True,
+            )
         maximum = max(0, len(snapshot.lines) - snapshot.height)
         if maximum == 0:
             self._remember_content(snapshot)
@@ -843,7 +894,11 @@ class LocalHistoryView:
             # snapshot instead of jumping to newer or unrelated text.
             self._anchor_rejects += 1
             return HistoryAction()
-        stored = self._remember_content(snapshot, prefer_deeper=True)
+        # The response is one cumulative capture and its exact visible anchor
+        # was just proved above. Replace the cached timeline as a whole instead
+        # of merging it with the older hot generation; this keeps every row's
+        # text and background styling from one server render.
+        stored = self._replace_content(snapshot)
         stored_offset = self._aligned_offset(stored, anchor)
         if stored_offset is None:
             # The raw response was valid, so this can only be an ambiguous
@@ -892,7 +947,7 @@ class LocalHistoryView:
             return matched_offset
 
         # Agent status rows (for example a Codex spinner) can change between
-        # the 300-line hot snapshot and the first deep response. Requiring the
+        # the hot snapshot and a deep response. Requiring the
         # entire visible viewport to remain byte-identical then strands the
         # user at the hot-cache boundary. Align on a majority of stable,
         # non-blank lines instead, but only when each evidence line occurs
@@ -966,18 +1021,15 @@ class LocalHistoryView:
         return was_active
 
 
-def claim_batched_wheel(
+def claim_batched_forwarded_wheel(
     event: SgrMouseEvent,
     handled_directions: set[int],
 ) -> bool:
-    """Admit at most one wheel tick per direction from one terminal read.
-
-    Trackpads commonly report several identical SGR wheel packets together.
-    If painting is briefly busy with fresh agent output, those packets can
-    accumulate in stdin and then move a frozen local-history viewport many
-    lines at once.  Bounding each read preserves the established one-line
-    local scroll feel without using a timing heuristic; a later read remains
-    immediately eligible.
+    """Admit at most one forwarded wheel tick per direction in one read.
+
+    Remote sidebar/modal owners need one bounded event rather than a stale
+    backlog. Locally owned agent history must not use this helper: it retains
+    the complete reported distance and coalesces only its terminal paint.
     """
     direction = event.wheel_direction
     if direction == 0: