railmux 0.3.3.dev2__tar.gz → 0.3.3.dev4__tar.gz

{railmux-0.3.3.dev2/src/railmux.egg-info → railmux-0.3.3.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: railmux
-Version: 0.3.3.dev2
+Version: 0.3.3.dev4
 Summary: Terminal UI to navigate, resume, and start Claude Code and Codex sessions
 Author-email: Rightglow <zhang.taian@foxmail.com>
 License-Expression: MIT
@@ -169,12 +169,14 @@ for focus and layout limits.
 |--------|--------|
 | Left-click (non-running) | Preview session history in the Target pane |
 | Left-click (running) | Switch the Target pane to that session |
+| Wheel up over a live agent | Open its canonical current-branch history |
 | Double-click | Open/attach in the Target pane and move focus there |
 | Right-click | Context menu (Open, Preview, Info, Rename, Star, Copy title, Kill, Term, Delete) |
 
 Unavailable context-menu actions are hidden for the selected session state.
-Single-click and `␣` act in the Target pane without moving keyboard focus;
-double-click and `Enter` also move focus there. The terminal must report mouse
+Single-click and `␣` act in the Target pane without moving keyboard focus, but
+`␣` always means history while a click on a running row means live attach.
+Double-click and `Enter` also move focus there. The terminal must report mouse
 buttons to applications for these actions to reach Railmux. Right-click
 reporting is sometimes a separate setting from ordinary mouse reporting; see
 [FAQ 2](#2-mouse-buttons-or-f8f9-dont-work--whats-wrong).
@@ -207,7 +209,7 @@ see [FAQ 1](#1-how-do-i-copy-text-from-the-agent-pane).
 | `T` | Return to that agent's managed Vim viewer, when open |
 | `m` | Switch agent mode (Claude Code ⇄ Codex) |
 | `o` | Open persistent Railmux options |
-| `␣` | Preview stopped or switch running target (like single-click) |
+| `␣` | Preview canonical history for the selected stopped or running session |
 | `F8` | Cycle agent layout: single → side-by-side → stacked |
 | `F9` | Fullscreen the focused agent, managed terminal, or Vim (toggle) |
 | `?` | Full help popup with all keybindings |
@@ -299,7 +301,8 @@ to single leaves Pane 2's agent running in the background.
 
 In a split, focus an agent pane to make it the Target pane. After focus returns
 to the sidebar, single-click or `␣` acts in that pane without moving keyboard
-focus; double-click or `Enter` opens there and transfers focus. The status bar
+focus; a running-row click attaches live while `␣` previews history.
+Double-click or `Enter` opens there and transfers focus. The status bar
 at the bottom-left shows the current layout and Target pane:
 
 | Symbol | Meaning |
@@ -363,15 +366,22 @@ sessions move ahead of the other results.
 ## History preview
 
 For a stopped session, left-click or press `␣` to view conversation history in
-the Target pane without starting or resuming the agent. Preview is read-only: it
-cannot send a message or change the session. User and assistant messages, tool
-calls, and abbreviated tool output are colour-coded, while internal context and
-encrypted reasoning are hidden.
+the Target pane without starting or resuming the agent. For a running session,
+press `␣`, choose **Preview**, or wheel up over its live pane. Preview is
+read-only: it cannot send a message or change the session. User and assistant
+messages, tool calls, and abbreviated tool output are colour-coded, while
+internal context and encrypted reasoning are hidden. Codex rewind lineages and
+Claude Code `parentUuid` branches are projected onto the provider's current
+conversation: the retained prefix and replacement suffix remain visible, while
+the abandoned suffix is hidden. When Railmux observes a running Codex session
+advance to its rewind child, it also removes the abandoned terminal screen and
+tmux scrollback before Codex redraws the live pane.
 
 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
-matches, and `q` to exit and restore the pane. Double-click to skip preview and
-open the session directly.
+matches, and `q` to exit. If preview began from a live pane, `q` restores that
+exact session; otherwise it restores the prior Target pane. Double-click to
+skip preview and open the session directly.
 
 ## Status indicators
 

{railmux-0.3.3.dev2 → railmux-0.3.3.dev4}/README.md

@@ -127,12 +127,14 @@ for focus and layout limits.
 |--------|--------|
 | Left-click (non-running) | Preview session history in the Target pane |
 | Left-click (running) | Switch the Target pane to that session |
+| Wheel up over a live agent | Open its canonical current-branch history |
 | Double-click | Open/attach in the Target pane and move focus there |
 | Right-click | Context menu (Open, Preview, Info, Rename, Star, Copy title, Kill, Term, Delete) |
 
 Unavailable context-menu actions are hidden for the selected session state.
-Single-click and `␣` act in the Target pane without moving keyboard focus;
-double-click and `Enter` also move focus there. The terminal must report mouse
+Single-click and `␣` act in the Target pane without moving keyboard focus, but
+`␣` always means history while a click on a running row means live attach.
+Double-click and `Enter` also move focus there. The terminal must report mouse
 buttons to applications for these actions to reach Railmux. Right-click
 reporting is sometimes a separate setting from ordinary mouse reporting; see
 [FAQ 2](#2-mouse-buttons-or-f8f9-dont-work--whats-wrong).
@@ -165,7 +167,7 @@ see [FAQ 1](#1-how-do-i-copy-text-from-the-agent-pane).
 | `T` | Return to that agent's managed Vim viewer, when open |
 | `m` | Switch agent mode (Claude Code ⇄ Codex) |
 | `o` | Open persistent Railmux options |
-| `␣` | Preview stopped or switch running target (like single-click) |
+| `␣` | Preview canonical history for the selected stopped or running session |
 | `F8` | Cycle agent layout: single → side-by-side → stacked |
 | `F9` | Fullscreen the focused agent, managed terminal, or Vim (toggle) |
 | `?` | Full help popup with all keybindings |
@@ -257,7 +259,8 @@ to single leaves Pane 2's agent running in the background.
 
 In a split, focus an agent pane to make it the Target pane. After focus returns
 to the sidebar, single-click or `␣` acts in that pane without moving keyboard
-focus; double-click or `Enter` opens there and transfers focus. The status bar
+focus; a running-row click attaches live while `␣` previews history.
+Double-click or `Enter` opens there and transfers focus. The status bar
 at the bottom-left shows the current layout and Target pane:
 
 | Symbol | Meaning |
@@ -321,15 +324,22 @@ sessions move ahead of the other results.
 ## History preview
 
 For a stopped session, left-click or press `␣` to view conversation history in
-the Target pane without starting or resuming the agent. Preview is read-only: it
-cannot send a message or change the session. User and assistant messages, tool
-calls, and abbreviated tool output are colour-coded, while internal context and
-encrypted reasoning are hidden.
+the Target pane without starting or resuming the agent. For a running session,
+press `␣`, choose **Preview**, or wheel up over its live pane. Preview is
+read-only: it cannot send a message or change the session. User and assistant
+messages, tool calls, and abbreviated tool output are colour-coded, while
+internal context and encrypted reasoning are hidden. Codex rewind lineages and
+Claude Code `parentUuid` branches are projected onto the provider's current
+conversation: the retained prefix and replacement suffix remain visible, while
+the abandoned suffix is hidden. When Railmux observes a running Codex session
+advance to its rewind child, it also removes the abandoned terminal screen and
+tmux scrollback before Codex redraws the live pane.
 
 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
-matches, and `q` to exit and restore the pane. Double-click to skip preview and
-open the session directly.
+matches, and `q` to exit. If preview began from a live pane, `q` restores that
+exact session; otherwise it restores the prior Target pane. Double-click to
+skip preview and open the session directly.
 
 ## Status indicators
 

railmux-0.3.3.dev4/src/railmux/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.3.3.dev4"

{railmux-0.3.3.dev2 → railmux-0.3.3.dev4}/src/railmux/fast_display_client.py

@@ -1074,7 +1074,7 @@ class TerminalSurface:
         self,
         requested: TerminalMode,
     ) -> TerminalMode:
-        """Mirror only input-affecting modes explicitly carried by protocol v14."""
+        """Mirror only input-affecting modes explicitly carried by protocol v15."""
         disabled = self.terminal_modes & ~requested
         enabled = requested & ~self.terminal_modes
         controls: list[bytes] = []
@@ -2013,7 +2013,7 @@ def _finish_remote_attach(
         raise ProbeError("remote display helper failed before attaching")
 
     _stop_unstarted_remote(process)
-    # A current v14 helper holds the mutex only while registering its exact tmux
+    # A current v15 helper holds the mutex only while registering its exact tmux
     # child. Give that ordinary race one fresh SSH process before presenting
     # the explicit legacy-lock takeover choice.
     time.sleep(_REMOTE_ATTACH_RETRY_DELAY)

{railmux-0.3.3.dev2 → railmux-0.3.3.dev4}/src/railmux/fast_display_history.py

@@ -207,7 +207,11 @@ class LocalHistoryView:
         restore_live = False
         for pane_id, viewport in tuple(self.viewports.items()):
             route = routes.get(pane_id)
-            if route is None or not self._same_geometry(viewport.snapshot, route):
+            if (
+                route is None
+                or not self._same_geometry(viewport.snapshot, route)
+                or not self._history_source_matches(viewport.snapshot, route)
+            ):
                 self.cancel_pane(pane_id)
                 restore_live = True
         return HistoryAction(restore_live=restore_live)
@@ -217,10 +221,11 @@ class LocalHistoryView:
         left: HistorySnapshot,
         right: HistorySnapshot,
     ) -> bool:
-        """Do not combine native, transcript, and undecided history."""
+        """Do not combine different providers or terminal generations."""
         return (
             left.transcript_backed == right.transcript_backed
             and left.history_choice_required == right.history_choice_required
+            and left.generation == right.generation
         )
 
     @staticmethod
@@ -813,7 +818,11 @@ class LocalHistoryView:
             ),
             None,
         )
-        if route is None or not self._same_geometry(route, snapshot):
+        if (
+            route is None
+            or not self._same_geometry(route, snapshot)
+            or not self._history_source_matches(route, snapshot)
+        ):
             return HistoryAction()
         viewport = self.viewports.get(pending.pane_id)
         if viewport is None:

{railmux-0.3.3.dev2 → railmux-0.3.3.dev4}/src/railmux/fast_display_protocol.py

@@ -1,4 +1,4 @@
-"""Private v14 framing for the coalesced full-window SSH display."""
+"""Private v15 framing for the coalesced full-window SSH display."""
 
 from __future__ import annotations
 
@@ -8,9 +8,9 @@ from dataclasses import dataclass
 from enum import IntEnum, IntFlag
 
 
-DISPLAY_MAGIC = b"RMUXD14\x00"
-INPUT_MAGIC = b"RMUXK14\x00"
-PROTOCOL_VERSION = 14
+DISPLAY_MAGIC = b"RMUXD15\x00"
+INPUT_MAGIC = b"RMUXK15\x00"
+PROTOCOL_VERSION = 15
 REMOTE_CONFIG_PROTOCOL = 1
 LENGTH_BYTES = 4
 REMOTE_HELLO_PREFIX = b"RAILMUX-REMOTE/1 "
@@ -28,10 +28,10 @@ MAX_HISTORY_PANES = 8
 MAX_CLIPBOARD_BYTES = 64 * 1024
 MAX_PATH_BYTES = 4096
 _UPDATE_METADATA = struct.Struct(">BIHHHHBHI")
-_HISTORY_METADATA = struct.Struct(">IIHHHHBI")
+_HISTORY_METADATA = struct.Struct(">IIHHHHBQI")
 _HISTORY_REQUEST = struct.Struct(">IHHH")
 _HISTORY_BATCH_METADATA = struct.Struct(">II")
-_HISTORY_PANE_METADATA = struct.Struct(">IHHHHB")
+_HISTORY_PANE_METADATA = struct.Struct(">IHHHHBQ")
 _PREFETCH_HISTORY_REQUEST = struct.Struct(">IH")
 _PATH_REQUEST = struct.Struct(">IIH")
 _PATH_RESULT = struct.Struct(">IBBH")
@@ -143,6 +143,7 @@ class HistorySnapshot:
     more_available: bool = False
     transcript_available: bool = False
     history_choice_required: bool = False
+    generation: int = 0
 
 
 @dataclass(frozen=True)
@@ -302,6 +303,7 @@ def encode_history_snapshot(snapshot: HistorySnapshot) -> bytes:
             snapshot.more_available,
             snapshot.transcript_available,
             snapshot.history_choice_required,
+            snapshot.generation,
         )):
             raise ValueError("a rejected history response must be empty")
         pane_number = 0
@@ -317,6 +319,8 @@ def encode_history_snapshot(snapshot: HistorySnapshot) -> bytes:
             raise ValueError("invalid history position")
         if len(snapshot.lines) < snapshot.height:
             raise ValueError("history snapshot is shorter than its viewport")
+        if not 0 <= snapshot.generation <= 0xFFFFFFFFFFFFFFFF:
+            raise ValueError("invalid history generation")
     raw_lines = _pack_history_lines(snapshot.lines)
     compressed = zlib.compress(raw_lines, level=3)
     metadata = _HISTORY_METADATA.pack(
@@ -327,6 +331,7 @@ def encode_history_snapshot(snapshot: HistorySnapshot) -> bytes:
         snapshot.width,
         snapshot.height,
         _history_capabilities(snapshot),
+        snapshot.generation,
         len(raw_lines),
     )
     payload = bytes((int(OutputKind.HISTORY),)) + metadata + compressed
@@ -360,6 +365,8 @@ def encode_history_batch(batch: HistoryBatch) -> bytes:
             raise ValueError("invalid history position")
         if len(snapshot.lines) < snapshot.height:
             raise ValueError("history snapshot is shorter than its viewport")
+        if not 0 <= snapshot.generation <= 0xFFFFFFFFFFFFFFFF:
+            raise ValueError("invalid history generation")
         packed_lines = _pack_history_lines(snapshot.lines)
         pane_metadata = _HISTORY_PANE_METADATA.pack(
             pane_number,
@@ -368,6 +375,7 @@ def encode_history_batch(batch: HistoryBatch) -> bytes:
             snapshot.width,
             snapshot.height,
             _history_capabilities(snapshot),
+            snapshot.generation,
         )
         total += len(pane_metadata) + len(packed_lines)
         if total > MAX_SCREEN_BYTES:
@@ -611,6 +619,7 @@ class ServerMessageDecoder:
                         width,
                         height,
                         raw_capabilities,
+                        generation,
                         raw_size,
                     ) = (
                         _HISTORY_METADATA.unpack(body[:_HISTORY_METADATA.size])
@@ -628,6 +637,7 @@ class ServerMessageDecoder:
                             height,
                             lines,
                             raw_capabilities,
+                            generation,
                         )):
                             raise ValueError("invalid rejected history response")
                         pane_id = None
@@ -662,6 +672,7 @@ class ServerMessageDecoder:
                         history_choice_required=bool(
                             raw_capabilities & _HISTORY_CHOICE_REQUIRED
                         ),
+                        generation=generation,
                     ))
                     continue
                 if output_kind is OutputKind.HISTORY_BATCH:
@@ -691,6 +702,7 @@ class ServerMessageDecoder:
                             width,
                             height,
                             raw_capabilities,
+                            generation,
                         ) = _HISTORY_PANE_METADATA.unpack(
                             raw[offset:offset + _HISTORY_PANE_METADATA.size]
                         )
@@ -729,6 +741,7 @@ class ServerMessageDecoder:
                             history_choice_required=bool(
                                 raw_capabilities & _HISTORY_CHOICE_REQUIRED
                             ),
+                            generation=generation,
                         ))
                     if offset != len(raw):
                         raise ValueError("trailing history batch data")
@@ -843,7 +856,7 @@ class ServerMessageDecoder:
 
 
 class ScreenUpdateDecoder:
-    """Compatibility view which ignores v14 control-response messages."""
+    """Compatibility view which ignores v15 control-response messages."""
 
     def __init__(self) -> None:
         self._decoder = ServerMessageDecoder()

{railmux-0.3.3.dev2 → railmux-0.3.3.dev4}/src/railmux/fast_display_server.py

@@ -45,6 +45,7 @@ from railmux import (
     __version__,
     local_open,
     restart_state,
+    tmux_ctl,
     tmux_health,
     tmux_server,
 )
@@ -403,6 +404,7 @@ class _PaneGeometry:
     transcript_source: str | None = None
     transcript_backed: bool = False
     claude_history_policy: str = "ask"
+    history_generation: int = 0
 
 
 @dataclass(frozen=True)
@@ -421,6 +423,24 @@ _INFERRED_TRANSCRIPT_LIMIT = 8
 _TRANSCRIPT_MAX_BYTES = 32 * 1024 * 1024
 _SESSION_BINDING_OPTION = "@railmux_binding_v1"
 _SWAP_OPTIONS = ("@railmux_swap_primary", "@railmux_swap_secondary")
+_HISTORY_GENERATION_RE = re.compile(
+    r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-"
+    r"[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
+)
+
+
+def _history_generation(marker: str) -> int:
+    """Map one validated provider UUID to a bounded opaque wire epoch."""
+    if not _HISTORY_GENERATION_RE.fullmatch(marker):
+        return 0
+    return int.from_bytes(
+        hashlib.blake2b(
+            marker.lower().encode("ascii"),
+            digest_size=8,
+            person=b"railmux-history",
+        ).digest(),
+        "big",
+    )
 
 
 _ANSI_FG = {
@@ -834,6 +854,7 @@ def _list_agent_panes(
                 "#{history_size} #{alternate_on} #{mouse_any_flag} "
                 f"#{{{tmux_server.HISTORY_SOURCE_OPTION}}} "
                 f"#{{{tmux_server.TRANSCRIPT_SOURCE_OPTION}}} "
+                f"#{{{tmux_ctl.RAILMUX_HISTORY_GENERATION_OPTION}}} "
                 f"#{{{TOOL_PANE_OPTION}}}",
             ),
             stderr=subprocess.DEVNULL,
@@ -849,7 +870,7 @@ def _list_agent_panes(
     for raw_row in output.splitlines():
         fields = raw_row.split(" ")
         if (
-            len(fields) != 16
+            len(fields) != 17
             or fields[0] != session_id
             or fields[2] not in ("0", "1")
             or fields[3] not in ("0", "1")
@@ -880,7 +901,7 @@ def _list_agent_panes(
         ):
             return ()
         seen.add(pane_id)
-        if is_tool_pane_marker(fields[15], outer_session_id=session_id):
+        if is_tool_pane_marker(fields[16], outer_session_id=session_id):
             continue
         history_server = None
         history_pane_id = None
@@ -931,6 +952,7 @@ def _list_agent_panes(
                     transcript_source=transcript_marker,
                     transcript_backed=transcript_backed,
                     claude_history_policy=claude_history_policy,
+                    history_generation=_history_generation(fields[15]),
                 ),
             )
         )
@@ -1376,6 +1398,7 @@ def _capture_pane_history(
                 else pane.history_size + pane.height > len(lines)
             )
         ),
+        generation=pane.history_generation,
     )
 
 
@@ -1916,7 +1939,7 @@ def render_rows(screen: object) -> tuple[bytes, ...]:
 
 
 def terminal_modes_for_screen(screen: object) -> TerminalMode:
-    """Project pyte's private-mode set onto the bounded v14 wire allowlist."""
+    """Project pyte's private-mode set onto the bounded v15 wire allowlist."""
     terminal_modes = TerminalMode.NONE
     if 2004 << 5 in screen.mode:
         terminal_modes |= TerminalMode.BRACKETED_PASTE

{railmux-0.3.3.dev2 → railmux-0.3.3.dev4}/src/railmux/mouse_manager.py

@@ -157,6 +157,14 @@ class RootWheelForwardingManager:
                             state["backup"], token=token)
                         self._remove_state()
                         state = None
+                    elif not tmux_ctl.root_wheel_bindings_are_current(token):
+                        # The ownership transaction can survive a soft upgrade
+                        # in the same tmux pane. Refresh only an exactly-owned
+                        # wrapper so the new pane-local history route becomes
+                        # active without treating it as a user binding.
+                        if not tmux_ctl.set_root_wheel_forwarding(
+                                state["backup"], token):
+                            return False
                     if state is not None:
                         state["owners"] = sorted(
                             {*state["owners"], self._owner_pane_id})

{railmux-0.3.3.dev2 → railmux-0.3.3.dev4}/src/railmux/tmux_ctl.py

@@ -8,6 +8,7 @@ from __future__ import annotations
 
 import os
 import re
+import signal
 import shlex
 import shutil
 import subprocess
@@ -302,6 +303,12 @@ _ROLLOUT_UUID_RE = re.compile(
 )
 
 
+def rollout_uuid_from_path(path: Path) -> str | None:
+    """Return the filename UUID for a canonical Codex rollout path."""
+    match = _ROLLOUT_UUID_RE.search(path.name)
+    return match.group(1) if match is not None else None
+
+
 def pane_pid_for_session(session_name: str) -> int | None:
     """Return the first pane's PID for *session_name*, or None.
 
@@ -1817,6 +1824,19 @@ _PREFIX_TARGET_KEY = "Tab"
 _PREFIX_TARGET_MARKER = "railmux-target-toggle-v1"
 RAILMUX_CONTROLLER_OPTION = "@railmux_controller_pane"
 RAILMUX_TARGET_OPTION = "@railmux_target_pane"
+RAILMUX_HISTORY_PREVIEW_OPTION = "@railmux_history_preview_v1"
+RAILMUX_HISTORY_GENERATION_OPTION = "@railmux_history_generation_v1"
+# tmux names function keys only through F12. Private controller routes use
+# canonical xterm sequences in literal mode, so they cannot be confused with
+# user input forwarded to an agent pane.
+RAILMUX_HISTORY_PREVIEW_KEYS = {
+    "primary": ("F21", "\x1b[35~"),
+    "secondary": ("F22", "\x1b[36~"),
+}
+RAILMUX_HISTORY_RESTORE_KEYS = {
+    "primary": ("F23", "\x1b[42~"),
+    "secondary": ("F24", "\x1b[43~"),
+}
 RAILMUX_SELECTION_KEY_OPTION = "@railmux_selection_key"
 RAILMUX_SELECTION_PEER_OPTION = "@railmux_selection_peer"
 RAILMUX_SELECTION_FROZEN_OPTION = "@railmux_selection_frozen_by"
@@ -2145,28 +2165,69 @@ def set_root_wheel_forwarding(
     backup: RootWheelBindingBackup,
     token: str,
 ) -> bool:
-    """Forward both wheel directions to mouse-aware pane applications.
+    """Open canonical live history on wheel-up, otherwise preserve tmux input.
 
     The literal marker makes crash recovery able to distinguish Railmux's
     wrapper from a binding the user installed while Railmux was running.
+    A pane-local primary/secondary marker routes the first live-agent wheel-up
+    to Railmux's controller; the transcript viewer clears that marker, so its
+    subsequent wheel events are forwarded normally.
     Non-mouse-aware panes retain the exact stock fallback; WheelDownPane was
     unbound by default and therefore has no false branch.
     """
     marker = f"{_ROOT_WHEEL_MARKER}-{token}"
-    condition = (
+    mouse_condition = (
         "#{&&:#{mouse_any_flag},"
         f"#{{==:{marker},{marker}}}}}"
     )
+    controller_present = f"#{{!=:#{{{RAILMUX_CONTROLLER_OPTION}}},}}"
+
+    def _preview_condition(slot_key: str) -> str:
+        return (
+            "#{&&:"
+            f"#{{==:#{{{RAILMUX_HISTORY_PREVIEW_OPTION}}},{slot_key}}},"
+            f"{controller_present}}}"
+        )
+
+    def _send_preview(slot_key: str) -> str:
+        _key, sequence = RAILMUX_HISTORY_PREVIEW_KEYS[slot_key]
+        return (
+            f"send-keys -l -t '#{{{RAILMUX_CONTROLLER_OPTION}}}' -- "
+            f"'{sequence}'"
+        )
+
     try:
         for key in _ROOT_WHEEL_KEYS:
+            binding = backup.get(key)
+            fallback = _binding_command(binding) if binding is not None else ""
+            mouse_fallback = (
+                f"if-shell -F -t = '{mouse_condition}' 'send-keys -M'"
+            )
+            if fallback:
+                mouse_fallback += f" '{fallback}'"
             args = [
                 "tmux", "bind-key", "-T", "root", key,
-                "if-shell", "-F", "-t", "=", condition,
-                "send-keys -M",
             ]
-            binding = backup.get(key)
-            if binding is not None:
-                args.append(_binding_command(binding))
+            if key == "WheelUpPane":
+                secondary_fallback = (
+                    "if-shell -F -t = "
+                    f"'{_preview_condition('secondary')}' "
+                    f"\"{_send_preview('secondary')}\" "
+                    f"\"{mouse_fallback}\""
+                )
+                args.extend([
+                    "if-shell", "-F", "-t", "=",
+                    _preview_condition("primary"),
+                    _send_preview("primary"),
+                    secondary_fallback,
+                ])
+            else:
+                args.extend([
+                    "if-shell", "-F", "-t", "=", mouse_condition,
+                    "send-keys -M",
+                ])
+                if fallback:
+                    args.append(fallback)
             subprocess.check_call(
                 args, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
     except (ValueError, subprocess.CalledProcessError, FileNotFoundError):
@@ -2186,6 +2247,28 @@ def root_wheel_bindings_owned_by(token: str) -> bool:
     )
 
 
+def root_wheel_bindings_are_current(token: str) -> bool:
+    """Whether the owned wrapper includes canonical-history routing."""
+    bindings = read_root_wheel_bindings()
+    up = bindings.get("WheelUpPane")
+    marker = f"{_ROOT_WHEEL_MARKER}-{token}"
+    return (
+        all(
+            binding is not None
+            and marker in binding
+            and "mouse_any_flag" in binding
+            and "send-keys -M" in binding
+            for binding in bindings.values()
+        )
+        and up is not None
+        and RAILMUX_HISTORY_PREVIEW_OPTION in up
+        and all(
+            sequence in up or sequence.replace("\x1b", r"\033") in up
+            for _key, sequence in RAILMUX_HISTORY_PREVIEW_KEYS.values()
+        )
+    )
+
+
 def root_wheel_binding_is_original_or_owned(
     key: str,
     binding: str | None,
@@ -3272,6 +3355,47 @@ def exact_pane_alive(identity: PaneIdentity) -> bool:
     )
 
 
+def reset_pane_history(identity: PaneIdentity) -> bool:
+    """Reset visible bytes and scrollback for the exact observed live pane.
+
+    Revalidate the immutable session, pane process, and window before issuing
+    one tmux command queue that resets the terminal model and clears history.
+    Then send the pane's foreground process group an ordinary same-size
+    ``SIGWINCH`` so its TUI repaints and reasserts terminal modes without a
+    geometry change or injected keyboard input.
+    """
+    current = pane_identity(identity.pane_id)
+    if (current is None or current.dead
+            or current.pane_pid != identity.pane_pid
+            or current.session_id != identity.session_id
+            or current.window_id != identity.window_id):
+        return False
+    try:
+        subprocess.check_call(
+            [
+                "tmux", "send-keys", "-R", "-t", identity.pane_id,
+                ";", "clear-history", "-t", identity.pane_id,
+            ],
+            stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+        )
+    except (OSError, subprocess.CalledProcessError):
+        return False
+
+    current = pane_identity(identity.pane_id)
+    if (current is None or current.dead
+            or current.pane_pid != identity.pane_pid
+            or current.session_id != identity.session_id
+            or current.window_id != identity.window_id):
+        return True
+    try:
+        os.killpg(os.getpgid(current.pane_pid), signal.SIGWINCH)
+    except (OSError, ValueError):
+        # The presentation cache is already clean. A provider that exited or
+        # cannot be signalled will repaint on its next ordinary terminal write.
+        pass
+    return True
+
+
 def kill_session_identity(identity: PaneIdentity) -> bool:
     """Kill an exact immutable tmux session, never a reused session name."""
     current = pane_identity(identity.pane_id)