railmux 0.3.3.dev1__tar.gz → 0.3.3.dev3__tar.gz

{railmux-0.3.3.dev1/src/railmux.egg-info → railmux-0.3.3.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: railmux
-Version: 0.3.3.dev1
+Version: 0.3.3.dev3
 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,20 @@ 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.
 
 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.dev1 → railmux-0.3.3.dev3}/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,20 @@ 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.
 
 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.dev3/src/railmux/__init__.py

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

{railmux-0.3.3.dev1 → railmux-0.3.3.dev3}/src/railmux/display_transport.py

@@ -738,6 +738,22 @@ class AgentDisplayTransport:
     def _with_phase(state: SwapState, phase: str) -> SwapState:
         return SwapState(**{**asdict(state), "phase": phase})
 
+    @staticmethod
+    def _fit_home_to_display(state: SwapState) -> None:
+        """Best-effort preserve the provider's visible geometry at home.
+
+        While a real pane is displayed, its named session contains only the
+        inert placeholder.  Resize that detached home window to the real
+        pane's current size before swapping back.  Otherwise background output
+        is formatted at the placeholder's older (often much narrower) launch
+        geometry and later appears as a narrow discontinuity in scrollback.
+
+        Geometry is presentation-only: failure must never weaken or abort the
+        identity-pinned return transaction.
+        """
+        tmux_ctl.fit_session_to_pane(
+            state.agent_tmux_name, state.agent_pane_id)
+
     def park(self, slot: AgentSlot) -> bool:
         """Move one displayed swap agent home without forgetting its slot.
 
@@ -764,6 +780,7 @@ class AgentDisplayTransport:
         parking = self._with_phase(state, "parking")
         if not _write_marker_pair(parking, slot.key):
             return False
+        self._fit_home_to_display(state)
         if not tmux_ctl.swap_panes(
                 state.agent_pane_id, state.placeholder_pane_id):
             _write_marker_pair(state, slot.key)
@@ -857,6 +874,7 @@ class AgentDisplayTransport:
                 return False
             returning = SwapState(**{**asdict(state), "phase": "returning"})
             _write_marker_pair(returning, slot.key)
+            self._fit_home_to_display(state)
             if not tmux_ctl.swap_panes(
                     state.agent_pane_id, state.placeholder_pane_id):
                 return False

{railmux-0.3.3.dev1 → railmux-0.3.3.dev3}/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.dev1 → railmux-0.3.3.dev3}/src/railmux/tmux_ctl.py

@@ -1817,6 +1817,18 @@ _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"
+# 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 +2157,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 +2239,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,

{railmux-0.3.3.dev1 → railmux-0.3.3.dev3}/src/railmux/transcript.py

@@ -295,6 +295,81 @@ def _render_claude_native_tool_results(
         yield RESET
 
 
+def _claude_current_branch(records: list[dict]) -> list[dict]:
+    """Project an append-only Claude JSONL onto its current main branch.
+
+    Claude Code links semantic records with ``uuid`` / ``parentUuid``. Editing
+    or rewinding a prompt appends a second child instead of removing the old
+    suffix, so file order is not conversation order. The newest non-sidechain
+    UUID is the active tip; walking its parents retains the shared prefix and
+    the replacement suffix while excluding abandoned and sub-agent branches.
+
+    UUID-less metadata is retained for the normal renderer filters. If the
+    input is a bounded tail, walking stops safely at the first missing parent.
+    """
+    by_uuid: dict[str, dict] = {}
+    tip: str | None = None
+    for record in records:
+        uuid = record.get("uuid")
+        if not isinstance(uuid, str) or not uuid:
+            continue
+        by_uuid[uuid] = record
+        if record.get("isSidechain") is not True:
+            tip = uuid
+    if tip is None:
+        return records
+
+    current: set[str] = set()
+    cursor: str | None = tip
+    while cursor and cursor not in current:
+        record = by_uuid.get(cursor)
+        if record is None:
+            break
+        current.add(cursor)
+        parent = record.get("parentUuid")
+        cursor = parent if isinstance(parent, str) and parent else None
+
+    return [
+        record for record in records
+        if not isinstance(record.get("uuid"), str)
+        or not record.get("uuid")
+        or record["uuid"] in current
+    ]
+
+
+def _render_claude_records(
+    records: list[dict], *, claude_native: bool,
+):
+    """Render only the active Claude branch from buffered JSONL records."""
+    calls: dict[str, str] = {}
+    for record in _claude_current_branch(records):
+        rtype = record.get("type", "")
+        if rtype in _SKIP_TYPES:
+            continue
+        if _is_real_user(record):
+            rendered = (
+                _render_claude_native_user(record)
+                if claude_native
+                else _render_user(record)
+            )
+            if rendered:
+                yield rendered
+        if rtype == "user":
+            renderer = (
+                _render_claude_native_tool_results
+                if claude_native
+                else _render_claude_tool_results
+            )
+            yield from renderer(record, calls)
+        elif rtype == "assistant":
+            renderer = (
+                _render_claude_native_assistant
+                if claude_native
+                else _render_assistant_blocks
+            )
+            yield from renderer(record, calls)
+
+
 def format_transcript(
     source: Path | object,
     fmt: str | None = None,
@@ -326,7 +401,10 @@ def format_transcript(
     # call_id -> tool name, so Codex tool outputs can be labelled with the
     # call that produced them (issue #3).
     codex_calls: dict[str, str] = {}
-    claude_calls: dict[str, str] = {}
+    # Claude rewind/edit branches live in one append-only JSONL, so those
+    # records must be buffered until the active tip is known. Production
+    # callers bound the input to the latest 2,000 records.
+    claude_records: list[dict] = []
     try:
         if isinstance(source, Path):
             fh = open(source, "r", encoding="utf-8")
@@ -360,33 +438,10 @@ def format_transcript(
             if _codex:
                 yield from _render_codex(record, codex_calls)
                 continue
-
-            # -- Claude format (legacy) --------------------------------
-            if rtype in _SKIP_TYPES:
-                continue
-
-            if _is_real_user(record):
-                rendered = (
-                    _render_claude_native_user(record)
-                    if claude_native
-                    else _render_user(record)
-                )
-                if rendered:
-                    yield rendered
-            if rtype == "user":
-                renderer = (
-                    _render_claude_native_tool_results
-                    if claude_native
-                    else _render_claude_tool_results
-                )
-                yield from renderer(record, claude_calls)
-            elif rtype == "assistant":
-                renderer = (
-                    _render_claude_native_assistant
-                    if claude_native
-                    else _render_assistant_blocks
-                )
-                yield from renderer(record, claude_calls)
+            claude_records.append(record)
+        if _codex is False:
+            yield from _render_claude_records(
+                claude_records, claude_native=claude_native)
     except OSError:
         yield f"{YELLOW}Could not read: {source}{RESET}\n"
     finally: