railmux 0.4.2.dev1__tar.gz → 0.4.2.dev2__tar.gz

{railmux-0.4.2.dev1/src/railmux.egg-info → railmux-0.4.2.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: railmux
-Version: 0.4.2.dev1
+Version: 0.4.2.dev2
 Summary: Terminal UI to navigate, resume, and start Claude Code and Codex sessions
 Author-email: Rightglow <zhang.taian@foxmail.com>
 License-Expression: MIT

railmux-0.4.2.dev2/src/railmux/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.4.2.dev2"

{railmux-0.4.2.dev1 → railmux-0.4.2.dev2}/src/railmux/tmux_binding_manager.py

@@ -110,7 +110,7 @@ class SharedTmuxBindingManager:
         selection_hook_index = raw.get("selection_hook_index")
         prefix_valid = (
             isinstance(prefix_backup, dict)
-            and set(prefix_backup) == {"Tab"}
+            and set(prefix_backup) in ({"Tab"}, {"Tab", "Tab.note"})
             and all(value is None or isinstance(value, str)
                     for value in prefix_backup.values())
         )

{railmux-0.4.2.dev1 → railmux-0.4.2.dev2}/src/railmux/tmux_ctl.py

@@ -29,6 +29,7 @@ class ServerSnapshot:
     sessions: frozenset[str]
     panes: frozenset[str]
     session_pids: tuple[tuple[str, int], ...] = ()
+    pane_titles: tuple[tuple[str, str, str], ...] = ()
 
     def pane_pid_for(self, session_name: str) -> int | None:
         """Return the first pane PID captured for *session_name*."""
@@ -37,6 +38,22 @@ class ServerSnapshot:
                 return pid
         return None
 
+    def pane_title_for(self, pane_id: str) -> str | None:
+        """Return one live pane's terminal title from this same snapshot."""
+        titles = {
+            title for _session_name, candidate, title in self.pane_titles
+            if candidate == pane_id
+        }
+        return next(iter(titles)) if len(titles) == 1 else None
+
+    def pane_title_for_session(self, session_name: str) -> str | None:
+        """Return the title of a single-live-pane provider session."""
+        matches = [
+            title for candidate, _pane_id, title in self.pane_titles
+            if candidate == session_name
+        ]
+        return matches[0] if len(matches) == 1 else None
+
 
 @dataclass(frozen=True)
 class PaneIdentity:
@@ -277,7 +294,8 @@ def server_snapshot() -> ServerSnapshot | None:
         out = subprocess.check_output(
             [
                 "tmux", "list-panes", "-a", "-F",
-                "#{session_name}\t#{pane_id}\t#{pane_pid}\t#{pane_dead}",
+                "#{session_name}\t#{pane_id}\t#{pane_pid}\t#{pane_dead}"
+                "\t#{q:pane_title}",
             ],
             stderr=subprocess.DEVNULL,
         ).decode()
@@ -287,26 +305,45 @@ def server_snapshot() -> ServerSnapshot | None:
     sessions: set[str] = set()
     panes: set[str] = set()
     session_pids: dict[str, int] = {}
+    pane_titles: list[tuple[str, str, str]] = []
     for line in out.splitlines():
-        fields = line.split("\t", 3)
-        if len(fields) != 4 or not all(fields):
+        fields = line.split("\t", 4)
+        if (len(fields) != 5 or not fields[0] or not fields[1]
+                or not fields[3]):
             return None
-        session_name, pane_id, raw_pid, pane_dead = fields
+        session_name, pane_id, raw_pid, pane_dead, raw_title = fields
+        if raw_title:
+            try:
+                decoded = shlex.split(raw_title)
+            except ValueError:
+                return None
+            if len(decoded) != 1:
+                return None
+            pane_title = decoded[0]
+        else:
+            pane_title = ""
         if pane_dead not in {"0", "1"}:
             return None
+        if pane_dead == "1":
+            # tmux 3.8 renders pane_pid as empty for a dead remain-on-exit
+            # pane. It is excluded from this live snapshot, so no PID is
+            # required here.
+            continue
         try:
             pane_pid = int(raw_pid)
         except ValueError:
             return None
-        if pane_dead == "1":
-            continue
+        if pane_pid <= 0:
+            return None
         sessions.add(session_name)
         panes.add(pane_id)
         session_pids.setdefault(session_name, pane_pid)
+        pane_titles.append((session_name, pane_id, pane_title))
     return ServerSnapshot(
         frozenset(sessions),
         frozenset(panes),
         tuple(sorted(session_pids.items())),
+        tuple(sorted(pane_titles)),
     )
 
 
@@ -653,13 +690,20 @@ def pane_identity(pane_id: str) -> PaneIdentity | None:
         fields = raw.split("\t")
         if len(fields) != 8:
             return None
+        dead = fields[5] == "1"
+        # tmux 3.8 leaves ``pane_pid`` empty after a pane dies. Keep zero as
+        # an internal dead-pane sentinel so callers can still identify and
+        # reap the exact remain-on-exit pane; live panes retain positive PIDs.
+        pane_pid = 0 if dead and not fields[1] else int(fields[1])
+        if pane_pid < 0 or (not dead and pane_pid == 0):
+            return None
         return PaneIdentity(
             pane_id=fields[0],
-            pane_pid=int(fields[1]),
+            pane_pid=pane_pid,
             session_name=fields[2],
             session_id=fields[3],
             window_id=fields[4],
-            dead=fields[5] == "1",
+            dead=dead,
             width=int(fields[6]),
             height=int(fields[7]),
         )
@@ -735,17 +779,24 @@ def _tmux_state_snapshot(
             ):
                 return None
             attached = int(attached_raw)
+            dead = dead_raw == "1"
+            pane_pid = (
+                0 if dead and not pane_pid_raw else int(pane_pid_raw)
+            )
             pane = PaneIdentity(
                 pane_id=pane_id,
-                pane_pid=int(pane_pid_raw),
+                pane_pid=pane_pid,
                 session_name=actual_name,
                 session_id=session_id,
                 window_id=window_id,
-                dead=dead_raw == "1",
+                dead=dead,
                 width=int(width_raw),
                 height=int(height_raw),
             )
-            if attached < 0 or pane.pane_pid <= 0 or pane.width <= 0 or pane.height <= 0:
+            if (attached < 0
+                    or (pane.dead and pane.pane_pid < 0)
+                    or (not pane.dead and pane.pane_pid <= 0)
+                    or pane.width <= 0 or pane.height <= 0):
                 return None
             key = (actual_name, session_id)
             group = grouped.setdefault(
@@ -3221,6 +3272,37 @@ def read_prefix_target_binding() -> PrefixTargetBindingBackup:
     return {_PREFIX_TARGET_KEY: _read_key_binding("prefix", _PREFIX_TARGET_KEY)}
 
 
+def _prefix_target_note() -> str | None:
+    """Return Prefix-Tab's descriptive note without its rendered key prefix."""
+    if tmux_version() < (3, 2):
+        return None
+    try:
+        raw = subprocess.check_output(
+            ["tmux", "list-keys", "-N", "-T", "prefix", "-1",
+             _PREFIX_TARGET_KEY],
+            stderr=subprocess.DEVNULL,
+        ).decode().strip()
+    except (OSError, subprocess.CalledProcessError, UnicodeError):
+        return None
+    fields = raw.split(None, 2)
+    return fields[2] if len(fields) == 3 else None
+
+
+def _tmux_38_default_prefix_target(binding: str, note: str | None) -> bool:
+    """Whether *binding* is tmux 3.8's annotated stock Prefix-Tab action."""
+    if tmux_version() < (3, 8) or note != "Switch to a window":
+        return False
+    try:
+        command = tuple(shlex.split(_binding_command(binding)))
+    except ValueError:
+        return False
+    return command == (
+        "new-pane", "-E", "-X", "0", "-Y", "0", "-x", "75%", "-y",
+        "30%", ";", "move-pane", "-P", "bottom-centre", ";",
+        "switch-mode", "-kw",
+    )
+
+
 def prepare_prefix_target_binding() -> PrefixTargetBindingBackup | None:
     if tmux_version() < (2, 7):
         return None
@@ -3229,8 +3311,9 @@ def prepare_prefix_target_binding() -> PrefixTargetBindingBackup | None:
     if binding and _PREFIX_TARGET_MARKER in binding:
         return None
     # A server-global wrapper cannot preserve repeat semantics only outside
-    # Railmux. Notes are likewise absent from normal list-keys output and would
-    # be lost on restoration, so leave either kind of user binding untouched.
+    # Railmux. Preserve tmux 3.8's known stock note explicitly; leave unknown
+    # annotated user bindings untouched rather than risking lossy restoration.
+    note: str | None = None
     if binding is not None:
         if re.match(r"^bind-key\s+-r\b", binding):
             return None
@@ -3239,17 +3322,10 @@ def prepare_prefix_target_binding() -> PrefixTargetBindingBackup | None:
         except ValueError:
             return None
         if tmux_version() >= (3, 2):
-            try:
-                note = subprocess.check_output(
-                    ["tmux", "list-keys", "-N", "-T", "prefix", "-1",
-                     _PREFIX_TARGET_KEY],
-                    stderr=subprocess.DEVNULL,
-                ).decode().strip()
-            except (subprocess.CalledProcessError, FileNotFoundError):
-                return None
-            if note:
+            note = _prefix_target_note()
+            if note and not _tmux_38_default_prefix_target(binding, note):
                 return None
-    return backup
+    return {**backup, "Tab.note": note}
 
 
 def set_prefix_target_binding(
@@ -3345,7 +3421,15 @@ def restore_prefix_target_binding(
                 prefix="railmux-prefix-target-", suffix=".conf")
             try:
                 with os.fdopen(fd, "w", encoding="utf-8") as fh:
-                    fh.write(original + "\n")
+                    note = backup.get("Tab.note")
+                    restored = original
+                    if note:
+                        restored = original.replace(
+                            "bind-key",
+                            f"bind-key -N {shlex.quote(note)}",
+                            1,
+                        )
+                    fh.write(restored + "\n")
                 subprocess.check_call(
                     ["tmux", "source-file", path],
                     stdout=subprocess.DEVNULL,

{railmux-0.4.2.dev1 → railmux-0.4.2.dev2}/src/railmux/ui/app.py

@@ -9193,7 +9193,7 @@ class App:
         # clicking it spawns a duplicate session; and `force_projects` above
         # stays stuck True, defeating the 3s project-scan cache. Codex
         # resolution must run too or neither ever clears.
-        self._resolve_placeholders(projects)
+        self._resolve_placeholders(projects, server)
         running_ids = self._running_session_ids()
         if self._selected_project is not None:
             matched = next((p for p in projects if p.encoded_name == self._selected_project.encoded_name), None)
@@ -10002,7 +10002,66 @@ class App:
         ]
         self._running_pane.set_running(entries)
 
-    def _resolve_placeholders(self, projects: list[Project]) -> None:
+    @staticmethod
+    def _codex_terminal_session_title(
+        pane_title: str | None,
+        project: Project,
+    ) -> str | None:
+        """Extract a bounded Codex session title from its terminal title.
+
+        Current Codex releases publish ``<title> | <workspace>`` and prefix
+        the title with one braille spinner cell while a turn is active.  Treat
+        every other shape as untrusted display text: a shell or tool running
+        in the pane can also set the terminal title.
+        """
+        if pane_title is None:
+            return None
+        value = pane_title.strip()
+        if value and "\u2800" <= value[0] <= "\u28ff":
+            value = value[1:].lstrip()
+        suffix = f" | {project.display_name}"
+        if not value.endswith(suffix):
+            return None
+        title = value[:-len(suffix)].strip()
+        if not title or len(title) > 512 or not title.isprintable():
+            return None
+        return title
+
+    def _refresh_codex_placeholder_label(
+        self,
+        running: _Running,
+        project: Project,
+        server: tmux_ctl.ServerSnapshot | None,
+    ) -> None:
+        """Refresh only an unresolved placeholder's human-readable label.
+
+        New Codex app-server releases no longer keep their rollout JSONL open
+        in the pane process tree, so exact UUID promotion can correctly remain
+        unresolved.  The terminal title still belongs to this exact pane and
+        is safe as a *display* hint because it is read from the exact owned
+        pane and accepted only in Codex's workspace-qualified title shape.  It
+        deliberately does not promote identity: Resume/Delete keep their
+        existing fail-closed rules.
+        """
+        if server is None or running.session_type != "codex":
+            return
+        real_pane = self._display_transport().displayed_real_pane(
+            running.tmux_name)
+        pane_title = (
+            server.pane_title_for(real_pane)
+            if isinstance(real_pane, str) and real_pane
+            else server.pane_title_for_session(running.tmux_name)
+        )
+        title = self._codex_terminal_session_title(pane_title, project)
+        if title is None:
+            return
+        running.label = f"{project.display_name}/{title}"
+
+    def _resolve_placeholders(
+        self,
+        projects: list[Project],
+        server: tmux_ctl.ServerSnapshot | None = None,
+    ) -> None:
         """Re-key any `__new__-N` placeholder to its real session_id.
 
         For each live placeholder, look at its project's sessions and pick the
@@ -10059,6 +10118,8 @@ class App:
                 and s.session_id not in r.pre_launch_ids  # another process's (#12)
                 and s.last_mtime + 1.0 >= r.created_at
             ]
+            self._refresh_codex_placeholder_label(
+                r, project, server)
             # #12: prefer EXACT child→rollout correlation over the heuristic. The
             # codex process in this placeholder's pane holds its own rollout open;
             # its filename UUID is the exact session_id. This defeats the

{railmux-0.4.2.dev1 → railmux-0.4.2.dev2/src/railmux.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: railmux
-Version: 0.4.2.dev1
+Version: 0.4.2.dev2
 Summary: Terminal UI to navigate, resume, and start Claude Code and Codex sessions
 Author-email: Rightglow <zhang.taian@foxmail.com>
 License-Expression: MIT

{railmux-0.4.2.dev1 → railmux-0.4.2.dev2}/tests/test_app_codex_placeholder.py

@@ -483,6 +483,66 @@ def test_resolve_placeholders_empty_correlation_waits_not_fallback(monkeypatch):
     assert unrelated not in app._running  # heuristic did NOT fire
 
 
+@pytest.mark.parametrize(
+    "pane_title",
+    (
+        "Real session | test-proj",
+        "\u2827 Real session | test-proj",
+    ),
+)
+def test_unresolved_codex_placeholder_uses_exact_pane_title_for_label(
+    pane_title,
+):
+    """A newer Codex may publish no rollout fd, but its exact pane can still
+    replace the stale ``(new)`` display label without weakening UUID binding."""
+    proj = _project()
+    running = _Running(
+        key="__new__-tok-1",
+        tmux_name="cx-new----tok-1",
+        label="test-proj/(new)",
+        project=proj,
+        placeholder_path=proj.real_path,
+        created_at=999.0,
+        session_type="codex",
+        allow_heuristic_resolution=False,
+    )
+    app = App.__new__(App)
+    app._running = {running.key: running}
+    app._codex_index = MagicMock()
+    # The pane title is available before the background index publishes the
+    # rollout, so display refresh must not depend on candidate discovery.
+    app._codex_index.sessions_for_cwd.return_value = []
+    app._correlate_codex_rollout = MagicMock(return_value=set())
+    app._display_transport_manager = MagicMock()
+    app._display_transport_manager.displayed_real_pane.return_value = None
+    server = tmux_ctl.ServerSnapshot(
+        sessions=frozenset({running.tmux_name}),
+        panes=frozenset({"%7"}),
+        pane_titles=((running.tmux_name, "%7", pane_title),),
+    )
+
+    app._resolve_placeholders([proj], server)
+
+    assert running.key in app._running
+    assert running.is_placeholder
+    assert running.label == "test-proj/Real session"
+
+
+@pytest.mark.parametrize(
+    "pane_title",
+    (
+        "bash",
+        "Real session | another-project",
+        "Real\n session | test-proj",
+    ),
+)
+def test_unresolved_codex_placeholder_rejects_untrusted_pane_title(
+    pane_title,
+):
+    proj = _project()
+    assert App._codex_terminal_session_title(pane_title, proj) is None
+
+
 def test_correlate_codex_rollout_fails_closed_without_config(monkeypatch):
     """A helper failure on procfs must wait, never unlock the heuristic."""
     monkeypatch.setattr(tmux_ctl, "proc_fs_available", lambda: True)

{railmux-0.4.2.dev1 → railmux-0.4.2.dev2}/tests/test_tmux_ctl.py

@@ -195,10 +195,10 @@ def test_copy_to_clipboard_rejects_unsafe_or_unbounded_payload():
 
 def test_server_snapshot_collects_sessions_and_panes():
     output = (
-        "cc-one\t%1\t101\t0\n"
-        "cc-one\t%2\t102\t1\n"
-        "cc-two\t%3\t201\t0\n"
-        "cc-dead\t%4\t301\t1\n"
+        "cc-one\t%1\t101\t0\tReview\\ code\\ \\|\\ repo\n"
+        "cc-one\t%2\t102\t1\told\n"
+        "cc-two\t%3\t201\t0\tSecond\n"
+        "cc-dead\t%4\t301\t1\tdead\n"
     )
     with patch("railmux.tmux_ctl.in_tmux", return_value=True), \
          _mock_check_output(output) as call:
@@ -210,12 +210,30 @@ def test_server_snapshot_collects_sessions_and_panes():
     assert snapshot.session_pids == (("cc-one", 101), ("cc-two", 201))
     assert snapshot.pane_pid_for("cc-one") == 101
     assert snapshot.pane_pid_for("missing") is None
+    assert snapshot.pane_title_for("%1") == "Review code | repo"
+    assert snapshot.pane_title_for_session("cc-one") == "Review code | repo"
+    assert snapshot.pane_title_for_session("missing") is None
     assert call.call_args.args[0] == [
         "tmux", "list-panes", "-a", "-F",
-        "#{session_name}\t#{pane_id}\t#{pane_pid}\t#{pane_dead}",
+        "#{session_name}\t#{pane_id}\t#{pane_pid}\t#{pane_dead}"
+        "\t#{q:pane_title}",
     ]
 
 
+def test_server_snapshot_accepts_tmux_38_empty_dead_pane_pid():
+    output = (
+        "cc-live\t%1\t101\t0\tlive\n"
+        "cc-dead\t%2\t\t1\tdead\n"
+    )
+    with patch("railmux.tmux_ctl.in_tmux", return_value=True), \
+         _mock_check_output(output):
+        snapshot = server_snapshot()
+
+    assert snapshot is not None
+    assert snapshot.sessions == frozenset({"cc-live"})
+    assert snapshot.panes == frozenset({"%1"})
+
+
 def test_server_snapshot_rejects_malformed_output():
     with patch("railmux.tmux_ctl.in_tmux", return_value=True), \
          _mock_check_output("cc-one %1\n"):
@@ -224,7 +242,7 @@ def test_server_snapshot_rejects_malformed_output():
 
 def test_server_snapshot_rejects_unknown_dead_state():
     with patch("railmux.tmux_ctl.in_tmux", return_value=True), \
-         _mock_check_output("cc-one\t%1\t101\tmaybe\n"):
+         _mock_check_output("cc-one\t%1\t101\tmaybe\ttitle\n"):
         assert server_snapshot() is None
 
 
@@ -289,6 +307,15 @@ def test_pane_identity_parses_stable_location_outside_tmux():
         "tmux", "display-message", "-p", "-t", "%7"]
 
 
+def test_pane_identity_accepts_tmux_38_empty_dead_pane_pid():
+    output = "%7\t\tagent\t$2\t@3\t1\t91\t31\n"
+    with _mock_check_output(output):
+        pane = tmux_ctl.pane_identity("%7")
+
+    assert pane == tmux_ctl.PaneIdentity(
+        "%7", 0, "agent", "$2", "@3", True, 91, 31)
+
+
 def test_session_topology_requires_exact_server_results(monkeypatch):
     output = b"agent\t$2\t0\t@3\t%7\t4242\t0\t91\t31\n"
     check = MagicMock(return_value=output)
@@ -1142,6 +1169,22 @@ def test_prefix_target_binding_rejects_unpreservable_user_binding():
         {"Tab": "not replayable tmux config"}, "owner123")
 
 
+def test_prefix_target_binding_accepts_tmux_38_stock_note():
+    stock = (
+        'bind-key -T prefix Tab new-pane -E -X 0 -Y 0 -x "75%" '
+        '-y "30%" \\; move-pane -P bottom-centre \\; switch-mode -kw'
+    )
+    with patch.object(tmux_ctl, "tmux_version", return_value=(3, 8)), \
+            patch.object(tmux_ctl, "read_prefix_target_binding",
+                         return_value={"Tab": stock}), \
+            patch.object(tmux_ctl, "_prefix_target_note",
+                         return_value="Switch to a window"):
+        assert tmux_ctl.prepare_prefix_target_binding() == {
+            "Tab": stock,
+            "Tab.note": "Switch to a window",
+        }
+
+
 def test_unset_window_user_option_requires_exact_owner_value():
     with _mock_check_output("%1"), _mock_check_call() as call:
         assert tmux_ctl.unset_window_user_option_if_value(

{railmux-0.4.2.dev1 → railmux-0.4.2.dev2}/tests/test_tmux_integration.py

@@ -3039,6 +3039,7 @@ def test_real_tmux_binding_manager_round_trip_and_user_reload(
     )
     original = tmux_ctl.read_root_function_bindings()
     original_prefix_tab = tmux_ctl.read_prefix_target_binding()
+    original_prefix_note = tmux_ctl._prefix_target_note()
     original_right_click = tmux_ctl.read_root_right_click_binding()
     original_status_click = tmux_ctl.read_root_status_click_binding()
     original_termux_tap = tmux_ctl.read_root_termux_tap_binding()
@@ -3229,6 +3230,7 @@ def test_real_tmux_binding_manager_round_trip_and_user_reload(
     assert restored["F8"] == original["F8"]
     assert restored["F9"] is not None and "new-user-f9" in restored["F9"]
     assert tmux_ctl.read_prefix_target_binding() == original_prefix_tab
+    assert tmux_ctl._prefix_target_note() == original_prefix_note
     assert tmux_ctl.read_root_right_click_binding() == original_right_click
     assert tmux_ctl.read_root_status_click_binding() == original_status_click
     assert tmux_ctl.read_root_termux_tap_binding() == original_termux_tap

railmux-0.4.2.dev1/src/railmux/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.4.2.dev1"