railmux 0.4.0.dev2__tar.gz → 0.4.0.dev4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: railmux
-Version: 0.4.0.dev2
+Version: 0.4.0.dev4
 Summary: Terminal UI to navigate, resume, and start Claude Code and Codex sessions
 Author-email: Rightglow <zhang.taian@foxmail.com>
 License-Expression: MIT
@@ -21,21 +21,18 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development
 Classifier: Topic :: Terminals
 Classifier: Topic :: Utilities
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: packaging>=23.0
-Requires-Dist: tomlkit<1,>=0.13.2
-Requires-Dist: urwid>=2.6.16
-Requires-Dist: tomli>=2.0.1; python_version < "3.11"
-Requires-Dist: pyte<0.9,>=0.8.2; sys_platform == "win32"
-Requires-Dist: pywinpty<4,>=3.0.5; sys_platform == "win32"
+Requires-Dist: packaging>=23.0; sys_platform != "win32"
+Requires-Dist: tomlkit<1,>=0.13.2; sys_platform != "win32"
+Requires-Dist: urwid>=2.6.16; sys_platform != "win32"
+Requires-Dist: tomli>=2.0.1; python_version < "3.11" and sys_platform != "win32"
 Provides-Extra: ssh
-Requires-Dist: pyte<0.9,>=0.8.2; extra == "ssh"
+Requires-Dist: pyte<0.9,>=0.8.2; sys_platform != "win32" and extra == "ssh"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: build>=1.2; extra == "dev"
@@ -173,12 +170,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).
@@ -211,7 +210,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 |
@@ -303,7 +302,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 |
@@ -367,15 +367,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.4.0.dev2 → railmux-0.4.0.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,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.4.0.dev2 → railmux-0.4.0.dev4}/pyproject.toml

@@ -27,23 +27,20 @@ classifiers = [
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
-  "Programming Language :: Python :: 3.14",
   "Topic :: Software Development",
   "Topic :: Terminals",
   "Topic :: Utilities",
 ]
 dependencies = [
-  "packaging>=23.0",
-  "tomlkit>=0.13.2,<1",
-  "urwid>=2.6.16",
-  "tomli>=2.0.1; python_version < '3.11'",
-  "pyte>=0.8.2,<0.9; sys_platform == 'win32'",
-  "pywinpty>=3.0.5,<4; sys_platform == 'win32'",
+  "packaging>=23.0; sys_platform != 'win32'",
+  "tomlkit>=0.13.2,<1; sys_platform != 'win32'",
+  "urwid>=2.6.16; sys_platform != 'win32'",
+  "tomli>=2.0.1; python_version < '3.11' and sys_platform != 'win32'",
 ]
 
 [project.optional-dependencies]
 ssh = [
-  "pyte>=0.8.2,<0.9",
+  "pyte>=0.8.2,<0.9; sys_platform != 'win32'",
 ]
 dev = [
   "pytest>=8.0",
@@ -54,7 +51,7 @@ dev = [
 ]
 
 [project.scripts]
-railmux = "railmux.cli:main"
+railmux = "railmux.entrypoint:main"
 
 [project.urls]
 Homepage = "https://rightglow.github.io/Railmux/"

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

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

{railmux-0.4.0.dev2 → railmux-0.4.0.dev4}/src/railmux/__main__.py

@@ -1,4 +1,4 @@
-from railmux.cli import main
+from railmux.entrypoint import main
 
 if __name__ == "__main__":
     raise SystemExit(main())

{railmux-0.4.0.dev2 → railmux-0.4.0.dev4}/src/railmux/cli.py

@@ -1,18 +1,18 @@
 from __future__ import annotations
 
 import argparse
-import os
 import shutil
 import subprocess
 import sys
+import termios
 import time
 from dataclasses import replace
 from pathlib import Path
 
 from railmux import __version__
 from railmux.config import ConfigError, default_config_path, load_config
+from railmux.diagnostics import is_ssh_session, run_doctor
 from railmux.pane_surface import render_startup_surface
-from railmux.platform import python_support_error
 from railmux.runtime_config import (
     activate_runtime_environment,
     check_executable,
@@ -37,29 +37,9 @@ _LOCAL_WATCHDOG_INTERVAL = 5.0
 _LOCAL_WATCHDOG_FAILURES = 3
 
 
-def _native_windows() -> bool:
-    return os.name == "nt"
-
-
-def is_ssh_session(environment: dict[str, str] | None = None) -> bool:
-    """Lazy compatibility wrapper that keeps POSIX diagnostics import-clean."""
-    from railmux.diagnostics import is_ssh_session as detect
-
-    return detect(environment)
-
-
-def run_doctor(*args: object, **kwargs: object) -> int:
-    """Lazy compatibility wrapper for the established CLI test/repair hook."""
-    from railmux.diagnostics import run_doctor as doctor
-
-    return doctor(*args, **kwargs)
-
-
 def _restore_terminal(attributes: list | None) -> None:
     if attributes is None:
         return
-    import termios
-
     try:
         termios.tcsetattr(sys.stdin.fileno(), termios.TCSADRAIN, attributes)
     except (OSError, termios.error):
@@ -87,8 +67,6 @@ def _run_tmux_client_with_watchdog(
     """Keep one monitor outside tmux so a frozen server cannot trap the TTY."""
     attributes = None
     if sys.stdin.isatty():
-        import termios
-
         try:
             attributes = termios.tcgetattr(sys.stdin.fileno())
         except (OSError, termios.error):
@@ -174,10 +152,6 @@ def _run_tmux_client_with_watchdog(
 
 
 def main(argv: list[str] | None = None) -> int:
-    support_error = python_support_error()
-    if support_error is not None:
-        print(f"error: {support_error}", file=sys.stderr)
-        return 2
     raw_args = list(sys.argv[1:] if argv is None else argv)
     if raw_args and raw_args[0] == "config":
         from railmux.config_cli import main as config_main
@@ -364,18 +338,6 @@ def main(argv: list[str] | None = None) -> int:
             file=sys.stderr,
         )
         return 2
-    if _native_windows():
-        # Native Windows owns no local tmux server. The detached daemon keeps
-        # ConPTY handles alive while this terminal remains a disposable client.
-        activate_runtime_environment(replace(config, tmux_binary="tmux"))
-        if not args.inside_tmux:
-            from railmux.self_update import maybe_upgrade_before_launch
-            from railmux.settings import Settings
-
-            maybe_upgrade_before_launch(raw_args, Settings())
-        from railmux.winlocal.client import main as native_main
-
-        return native_main(raw_args, config=config)
     if config.tmux_binary != "tmux":
         tmux_check = check_executable("tmux", config.tmux_binary)
         if not tmux_check.valid:

{railmux-0.4.0.dev2 → railmux-0.4.0.dev4}/src/railmux/codex_index.py

@@ -13,21 +13,19 @@ import hashlib
 import json
 import math
 import os
+import stat
 import time
 from dataclasses import dataclass, replace
 from pathlib import Path
 
 from railmux.atomic_file import atomic_write_text
-from railmux.platform.file_security import (
-    prepare_private_directory,
-    private_regular_file,
-)
 from railmux.models import (
     AttentionCategory,
     AttentionState,
     Project,
     SessionMeta,
 )
+from railmux.provider_paths import provider_path
 from railmux.renames import Renames
 
 # Codex has no reliable provider-neutral signal that distinguishes a long
@@ -100,9 +98,10 @@ class HiddenCodexStatus:
 def persistent_cache_path(codex_home: Path) -> Path:
     """Return a private cache path unique to one Codex sessions root."""
     raw_base = os.environ.get("XDG_CACHE_HOME")
+    requested_base = provider_path(raw_base).expanduser() if raw_base else None
     base = (
-        Path(raw_base).expanduser()
-        if raw_base and Path(raw_base).expanduser().is_absolute()
+        requested_base
+        if requested_base is not None and requested_base.is_absolute()
         else Path.home() / ".cache"
     )
     try:
@@ -460,7 +459,9 @@ class CodexIndex:
         try:
             info = path.lstat()
             if (
-                not private_regular_file(info)
+                not stat.S_ISREG(info.st_mode)
+                or info.st_uid != os.getuid()
+                or info.st_mode & 0o077
                 or info.st_size > _PERSISTENT_CACHE_MAX_BYTES
             ):
                 return
@@ -515,7 +516,17 @@ class CodexIndex:
         path = self._cache_path
         if path is None:
             return False
-        return prepare_private_directory(path.parent)
+        parent = path.parent
+        try:
+            parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+            info = parent.lstat()
+            if not stat.S_ISDIR(info.st_mode) or info.st_uid != os.getuid():
+                return False
+            if info.st_mode & 0o077:
+                os.chmod(parent, stat.S_IMODE(info.st_mode) & ~0o077)
+            return True
+        except OSError:
+            return False
 
     def _save_persistent_cache(self) -> None:
         path = self._cache_path
@@ -1027,7 +1038,7 @@ def _parse_codex_session(
     cwd_str = payload.get("cwd")
     if not isinstance(cwd_str, str) or not cwd_str.strip():
         return None
-    cwd = Path(cwd_str)
+    cwd = provider_path(cwd_str)
     forked_from = payload.get("forked_from_id")
     forked_from_id = (
         forked_from

{railmux-0.4.0.dev2 → railmux-0.4.0.dev4}/src/railmux/config.py

@@ -6,8 +6,6 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
-from railmux.platform.config_paths import default_config_path as _platform_config_path
-
 try:
     import tomllib
 except ModuleNotFoundError:  # Python 3.9-3.10
@@ -20,6 +18,7 @@ from railmux.setting_contracts import (
     bounds_for,
     choices_for,
 )
+from railmux.provider_paths import provider_path
 
 
 class ConfigError(ValueError):
@@ -49,7 +48,7 @@ class Config:
         and relative paths are made absolute before a launched Codex changes to
         its project cwd. The directory is not required to exist.
         """
-        path = Path(self.codex_home).expanduser()
+        path = provider_path(self.codex_home).expanduser()
         try:
             return path.resolve()
         except OSError:
@@ -57,7 +56,7 @@ class Config:
 
 
 def default_config_path() -> Path:
-    return _platform_config_path()
+    return Path.home() / ".config" / "railmux" / "config.toml"
 
 
 def _table(data: dict[str, Any], name: str) -> dict[str, Any]:

{railmux-0.4.0.dev2 → railmux-0.4.0.dev4}/src/railmux/discovery.py

@@ -7,8 +7,7 @@ from pathlib import Path
 
 from railmux.atomic_file import atomic_write_text
 from railmux.models import Project
-from railmux.path_codec import _claude_encode_path, decode
-from railmux.platform.config_paths import config_dir
+from railmux.path_codec import decode, is_encoded_project_name
 from railmux.session_index import _looks_like_uuid, _scan_session
 
 
@@ -38,7 +37,7 @@ def _path_cache_file() -> Path:
     Decoding an encoded project name is expensive on an NFS home (see
     path_codec), and the mapping is stable, so we persist it across launches.
     """
-    return config_dir() / "path-cache.json"
+    return Path.home() / ".config" / "railmux" / "path-cache.json"
 
 
 def _load_path_cache() -> dict[str, str]:
@@ -95,7 +94,7 @@ def list_projects(claude_home: Path) -> list[Project]:
         for entry in scan:
             if not entry.is_dir(follow_symlinks=False):
                 continue
-            if os.name != "nt" and not entry.name.startswith("-"):
+            if not is_encoded_project_name(entry.name):
                 continue
             seen.add(entry.name)
 
@@ -107,16 +106,10 @@ def list_projects(claude_home: Path) -> list[Project]:
             if cached is not None and Path(cached).is_dir():
                 real_path = Path(cached)
             else:
-                decoded = None
-                if os.name == "nt":
-                    decoded = _windows_project_path_from_transcript(
-                        Path(entry.path), entry.name
-                    )
-                else:
-                    try:
-                        decoded = decode(entry.name)
-                    except ValueError:
-                        pass
+                try:
+                    decoded = decode(entry.name)
+                except ValueError:
+                    decoded = None
                 # Skip projects whose original directory no longer exists on
                 # this machine (deleted or moved). They can't be launched —
                 # `cd` into a missing dir fails — so don't list them, and drop
@@ -163,58 +156,6 @@ def list_projects(claude_home: Path) -> list[Project]:
     return results
 
 
-def _windows_project_path_from_transcript(
-    claude_dir: Path,
-    encoded_name: str,
-) -> Path | None:
-    """Recover a Windows project cwd from provider-owned transcript metadata.
-
-    Drive letters and UNC roots do not fit the POSIX path backtracker. Claude
-    records the exact cwd in its JSONL, so validate that bounded value against
-    the enclosing encoded directory instead of guessing a Windows path.
-    """
-    try:
-        candidates = sorted(
-            claude_dir.glob("*.jsonl"),
-            key=lambda path: path.stat().st_mtime_ns,
-            reverse=True,
-        )[:8]
-    except OSError:
-        return None
-    for path in candidates:
-        try:
-            with path.open("r", encoding="utf-8", errors="replace") as stream:
-                for _line_number in range(64):
-                    line = stream.readline(64 * 1024 + 1)
-                    if not line:
-                        break
-                    if len(line) > 64 * 1024:
-                        continue
-                    try:
-                        record = json.loads(line)
-                    except (json.JSONDecodeError, ValueError):
-                        continue
-                    raw_cwd = record.get("cwd") if isinstance(record, dict) else None
-                    if (
-                        not isinstance(raw_cwd, str)
-                        or not raw_cwd
-                        or len(raw_cwd) > 32768
-                        or "\0" in raw_cwd
-                    ):
-                        continue
-                    candidate = Path(raw_cwd)
-                    if (
-                        candidate.is_absolute()
-                        and candidate.is_dir()
-                        and _claude_encode_path(str(candidate)).casefold()
-                        == encoded_name.casefold()
-                    ):
-                        return candidate
-        except OSError:
-            continue
-    return None
-
-
 def _count_and_latest_mtime(claude_dir: Path, real_path: Path) -> tuple[int, float]:
     """Count sessions that pass every ``_scan_session`` filter and return the max
     JSONL mtime.  Uses ``_scan_session`` so the count exactly matches the

{railmux-0.4.0.dev2 → railmux-0.4.0.dev4}/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.4.0.dev4/src/railmux/entrypoint.py

@@ -0,0 +1,21 @@
+"""Platform-safe public console entry point."""
+from __future__ import annotations
+
+import os
+from collections.abc import Sequence
+
+
+def main(
+    argv: Sequence[str] | None = None,
+    *,
+    platform_name: str = os.name,
+) -> int:
+    """Dispatch before importing modules that require a POSIX terminal."""
+    if platform_name == "nt":
+        from railmux.windows_bootstrap import main as windows_main
+
+        return windows_main(argv)
+
+    from railmux.cli import main as posix_main
+
+    return posix_main(list(argv) if argv is not None else None)