ring-cli 0.4.0__tar.gz → 0.5.0__tar.gz

{ring_cli-0.4.0 → ring_cli-0.5.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: ring-cli
-Version: 0.4.0
+Version: 0.5.0
 Summary: RiNG — Realtime Instance Notification Grid for active agent CLI sessions.
 Keywords: claude-code,codex,tui,dashboard,session,monitor,rich
 Author: Wei Lee
 Author-email: Wei Lee <weilee.rx@gmail.com>
 License-Expression: MIT
 License-File: LICENSE
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: MacOS
@@ -57,7 +57,7 @@ RiNG puts them on one board, with sessions waiting for you sorted first.
 
 - **One board for every session**: Claude Code / Codex are built in; other tools can feed `ring hook`.
 - **Waiting first**: sessions that need your response are highlighted and sorted above the rest.
-- **Jump back to the terminal**: in the TUI, select a session and press `Enter` / `Space` to focus tmux, iTerm2, or Terminal.app.
+- **Jump back to the terminal**: in the TUI, select a session and press `Enter` / `Space` to focus tmux, iTerm2, Terminal.app (macOS), or a Linux X11 window (`wmctrl`).
 - **Notifies you without the board open**: with hooks installed, the moment a session turns 🔴 waiting it beeps and fires a system notification — even with no RiNG board running. With `terminal-notifier`, clicking the notification jumps back.
 - **Name your sessions**: press `n` in the TUI to add a local label such as `maigo · auth refactor`.
 - **Local and extensible**: RiNG only reads local Claude Code / Codex data and writes `~/.config/ring/`; session sources, focusers, and notifiers are pluggable.
@@ -133,6 +133,7 @@ Select a session and press `Enter`. RiNG focuses the terminal where that session
 
 - **tmux**: switches directly to the pane via `switch-client`.
 - **iTerm2 / Terminal.app** on macOS: uses the session `tty` and AppleScript to focus the matching tab. The first run may ask for macOS Automation permission.
+- **Linux X11 window** (`wmctrl`, best-effort fallback): for Linux without tmux — walks from the `tty` up to the terminal window that owns it and raises it via `wmctrl`. **Limits**: X11 only (usually a no-op on Wayland), raises the whole window but cannot pick the tab, and gnome-terminal's client/server model may not match. Requires `apt install wmctrl`.
 
 TTY matching is most accurate in hook mode. Without hooks, Codex falls back to zero-config matching:
 one live Codex session per cwd can jump correctly; multiple live Codex sessions in the same cwd are shown conservatively to avoid focusing the wrong tab.
@@ -310,7 +311,7 @@ notify_ignore_dnd = false
 notify_backend = "auto"          # auto / terminal-notifier / osascript / notify-send / agent-hooks / none
 notify_repeat_seconds = [30, 120, 300]
 notify_repeat_max = 3
-focusers = ["tmux", "iTerm2", "Terminal"]
+focusers = ["tmux", "iTerm2", "Terminal", "linux-wm"]
 
 [colors]
 waiting = "bold red"
@@ -329,7 +330,7 @@ RiNG is not tied to a specific tool or terminal.
 | Extension Point | Purpose | Built-ins |
 |-----------------|---------|-----------|
 | `SessionSource` | find sessions | Claude Code, Codex, hook registry |
-| `Focuser` | jump to terminals | tmux, iTerm2, Terminal.app |
+| `Focuser` | jump to terminals | tmux, iTerm2, Terminal.app, Linux X11 (wmctrl) |
 | `Notifier` | notify when sessions are waiting | terminal-notifier, osascript, notify-send |
 
 Each backend is a small module under `ring/sources/`, `ring/focus/`, or `ring/notify/`, registered via `register_*()`.

{ring_cli-0.4.0 → ring_cli-0.5.0}/README.en.md

@@ -32,7 +32,7 @@ RiNG puts them on one board, with sessions waiting for you sorted first.
 
 - **One board for every session**: Claude Code / Codex are built in; other tools can feed `ring hook`.
 - **Waiting first**: sessions that need your response are highlighted and sorted above the rest.
-- **Jump back to the terminal**: in the TUI, select a session and press `Enter` / `Space` to focus tmux, iTerm2, or Terminal.app.
+- **Jump back to the terminal**: in the TUI, select a session and press `Enter` / `Space` to focus tmux, iTerm2, Terminal.app (macOS), or a Linux X11 window (`wmctrl`).
 - **Notifies you without the board open**: with hooks installed, the moment a session turns 🔴 waiting it beeps and fires a system notification — even with no RiNG board running. With `terminal-notifier`, clicking the notification jumps back.
 - **Name your sessions**: press `n` in the TUI to add a local label such as `maigo · auth refactor`.
 - **Local and extensible**: RiNG only reads local Claude Code / Codex data and writes `~/.config/ring/`; session sources, focusers, and notifiers are pluggable.
@@ -108,6 +108,7 @@ Select a session and press `Enter`. RiNG focuses the terminal where that session
 
 - **tmux**: switches directly to the pane via `switch-client`.
 - **iTerm2 / Terminal.app** on macOS: uses the session `tty` and AppleScript to focus the matching tab. The first run may ask for macOS Automation permission.
+- **Linux X11 window** (`wmctrl`, best-effort fallback): for Linux without tmux — walks from the `tty` up to the terminal window that owns it and raises it via `wmctrl`. **Limits**: X11 only (usually a no-op on Wayland), raises the whole window but cannot pick the tab, and gnome-terminal's client/server model may not match. Requires `apt install wmctrl`.
 
 TTY matching is most accurate in hook mode. Without hooks, Codex falls back to zero-config matching:
 one live Codex session per cwd can jump correctly; multiple live Codex sessions in the same cwd are shown conservatively to avoid focusing the wrong tab.
@@ -285,7 +286,7 @@ notify_ignore_dnd = false
 notify_backend = "auto"          # auto / terminal-notifier / osascript / notify-send / agent-hooks / none
 notify_repeat_seconds = [30, 120, 300]
 notify_repeat_max = 3
-focusers = ["tmux", "iTerm2", "Terminal"]
+focusers = ["tmux", "iTerm2", "Terminal", "linux-wm"]
 
 [colors]
 waiting = "bold red"
@@ -304,7 +305,7 @@ RiNG is not tied to a specific tool or terminal.
 | Extension Point | Purpose | Built-ins |
 |-----------------|---------|-----------|
 | `SessionSource` | find sessions | Claude Code, Codex, hook registry |
-| `Focuser` | jump to terminals | tmux, iTerm2, Terminal.app |
+| `Focuser` | jump to terminals | tmux, iTerm2, Terminal.app, Linux X11 (wmctrl) |
 | `Notifier` | notify when sessions are waiting | terminal-notifier, osascript, notify-send |
 
 Each backend is a small module under `ring/sources/`, `ring/focus/`, or `ring/notify/`, registered via `register_*()`.

{ring_cli-0.4.0 → ring_cli-0.5.0}/pyproject.toml

@@ -2,7 +2,7 @@
 # import 的 module（見 [tool.uv.build-backend] module-name）與 CLI 指令仍是 `ring`。
 [project]
 name = "ring-cli"
-version = "0.4.0"
+version = "0.5.0"
 description = "RiNG — Realtime Instance Notification Grid for active agent CLI sessions."
 readme = "README.en.md"
 requires-python = ">=3.13"
@@ -11,7 +11,7 @@ license-files = ["LICENSE"]
 authors = [{ name = "Wei Lee", email = "weilee.rx@gmail.com" }]
 keywords = ["claude-code", "codex", "tui", "dashboard", "session", "monitor", "rich"]
 classifiers = [
-  "Development Status :: 3 - Alpha",
+  "Development Status :: 4 - Beta",
   "Environment :: Console",
   "Intended Audience :: Developers",
   "Operating System :: MacOS",

{ring_cli-0.4.0 → ring_cli-0.5.0}/src/ring/config.py

@@ -20,7 +20,7 @@
                                       #   "none" = 完全不發通知（RiNG 當純看板）
     notify_repeat_seconds = [30, 120, 300]  # 持續等你時，多久後重複提醒
     notify_repeat_max = 3             # 重複提醒上限；0 = 不限
-    focusers = ["tmux", "iTerm2", "Terminal"]   # 跳轉嘗試順序；省略＝內建預設
+    focusers = ["tmux", "iTerm2", "Terminal", "linux-wm"]  # 跳轉嘗試順序；省略＝內建預設
 """
 
 from __future__ import annotations

{ring_cli-0.4.0 → ring_cli-0.5.0}/src/ring/focus/__init__.py

@@ -2,7 +2,8 @@
 
 每個終端是一個 ``Focuser``（見 ``base.Focuser``）：core 不認識任何具體終端，
 只依序問每個 focuser「這個 session 歸不歸你管」。要支援新終端＝寫一個模組、
-``register_focuser()`` 註冊，core 零改動。內建：tmux / iTerm2 / Terminal.app。
+``register_focuser()`` 註冊，core 零改動。內建：tmux / iTerm2 / Terminal.app /
+Linux X11 視窗（wmctrl，best-effort fallback）。
 """
 
 from __future__ import annotations
@@ -10,13 +11,20 @@ from __future__ import annotations
 from ring.config import get_config
 from ring.focus.base import Focuser
 from ring.focus.iterm2 import focuser as _iterm2
+from ring.focus.linux_wm import focuser as _linux_wm
 from ring.focus.terminal import focuser as _terminal
 from ring.focus.tmux import focuser as _tmux
 from ring.i18n import gettext as _
 from ring.registry import Session, Status
 
-# 內建 focuser。順序可由 config 的 `focusers` 覆寫。
-_BUILTIN: dict[str, Focuser] = {"tmux": _tmux, "iTerm2": _iterm2, "Terminal": _terminal}
+# 內建 focuser。順序可由 config 的 `focusers` 覆寫。tmux 跨平台、最快，排最前；
+# macOS app 在非 macOS 會自己 return None；linux-wm 殿後當 X11 fallback。
+_BUILTIN: dict[str, Focuser] = {
+    "tmux": _tmux,
+    "iTerm2": _iterm2,
+    "Terminal": _terminal,
+    "linux-wm": _linux_wm,
+}
 
 
 def _initial_focusers() -> list[Focuser]:

ring_cli-0.5.0/src/ring/focus/linux_wm.py

@@ -0,0 +1,117 @@
+"""Linux X11 視窗 focuser（best-effort）：用 session 的 tty 找到擁有它的終端視窗、帶到前景。
+
+定位是 macOS 之外的 fallback——Linux 上沒跑 tmux 的 session 原本完全跳不回去
+（tmux 已由 tmux focuser 處理、iTerm2 / Terminal.app 是 macOS 限定），這個 focuser 補上那個洞。
+
+機制與限制（誠實標明）：
+- 只在 Linux 且裝了 ``wmctrl`` 時接手；否則回 ``None`` 交給別的 focuser。
+- 從 tty 上的 process 往上追到「擁有 X11 視窗」的祖先（多數終端模擬器——xterm / konsole /
+  alacritty / kitty / xfce4-terminal——是 shell 的祖先），用 ``wmctrl`` 把那個視窗帶到前景。
+- **X11 限定**：Wayland 下 ``wmctrl`` 通常無效。
+- **無法選分頁**：只能把整個終端視窗帶到前景，無法切到正確分頁（X11 沒有跨終端的分頁 API）。
+- gnome-terminal 走 client/server，視窗 pid 不在 shell 的祖先鏈上，可能配不到（回 ``None``）。
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+
+from ring.registry import Session
+
+
+def _run(cmd: list[str]) -> str | None:
+    """跑一個唯讀／聚焦指令，成功回 stdout（可能為空字串），失敗回 ``None``。"""
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=3)
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return result.stdout if result.returncode == 0 else None
+
+
+def _tty_pids(tty: str) -> list[int]:
+    """某 tty 上的所有 process pid。``tty`` 形如 ``/dev/pts/3``。"""
+    out = _run(["ps", "-o", "pid=", "-t", tty.removeprefix("/dev/")])
+    if out is None:
+        return []
+    pids = []
+    for tok in out.split():
+        try:
+            pids.append(int(tok))
+        except ValueError:
+            continue
+    return pids
+
+
+def _ppid_map() -> dict[int, int]:
+    """全系統 pid → ppid 對照表。"""
+    out = _run(["ps", "-eo", "pid=,ppid="])
+    if out is None:
+        return {}
+    table: dict[int, int] = {}
+    for line in out.splitlines():
+        parts = line.split()
+        if len(parts) != 2:
+            continue
+        try:
+            table[int(parts[0])] = int(parts[1])
+        except ValueError:
+            continue
+    return table
+
+
+def _ancestors(pid: int, ppid_map: dict[int, int]) -> list[int]:
+    """``pid`` 自身 + 一路往上的祖先（由近到遠），遇環或到 init(1) 即止。"""
+    chain: list[int] = []
+    seen: set[int] = set()
+    cur = pid
+    while cur and cur > 1 and cur not in seen:
+        seen.add(cur)
+        chain.append(cur)
+        cur = ppid_map.get(cur, 0)
+    return chain
+
+
+def _window_pids() -> dict[int, str]:
+    """``wmctrl -lp`` 解析：擁有 X11 視窗的 pid → window id（同 pid 多視窗取第一個）。"""
+    out = _run(["wmctrl", "-lp"])
+    if out is None:
+        return {}
+    mapping: dict[int, str] = {}
+    for line in out.splitlines():
+        parts = line.split(None, 4)  # winid desktop pid host title
+        if len(parts) < 4:
+            continue
+        try:
+            pid = int(parts[2])
+        except ValueError:
+            continue
+        mapping.setdefault(pid, parts[0])
+    return mapping
+
+
+class LinuxWMFocuser:
+    name = "linux-wm"
+
+    def try_focus(self, session: Session) -> tuple[bool, str] | None:
+        tty = session.tty
+        if not sys.platform.startswith("linux") or not tty or not shutil.which("wmctrl"):
+            return None
+        tty_pids = _tty_pids(tty)
+        if not tty_pids:
+            return None
+        ppid_map = _ppid_map()
+        win_pids = _window_pids()
+        for start in tty_pids:
+            for pid in _ancestors(start, ppid_map):
+                winid = win_pids.get(pid)
+                if not winid:
+                    continue
+                if _run(["wmctrl", "-i", "-a", winid]) is not None:
+                    return True, f"{self.name} {winid}"
+                return False, f"wmctrl activate failed for {winid}"
+        return None  # 配不到視窗 → 交給別的 focuser，最後由 jump() 回報 tty 可能已關閉
+
+
+focuser = LinuxWMFocuser()

{ring_cli-0.4.0 → ring_cli-0.5.0}/src/ring/hook.py

@@ -35,11 +35,9 @@ from ring.registry import (
     RING_REGISTRY,
     Session,
     Status,
-    _extract_todo,
-    _latest_action,
     _pid_tty,
-    _tail_records,
 )
+from ring.transcript import _extract_todo, _latest_action, _tail_records
 
 _HOOK_EVENTS = list(HOOK_EVENTS)
 

{ring_cli-0.4.0 → ring_cli-0.5.0}/src/ring/registry.py

@@ -31,6 +31,14 @@ from pathlib import Path
 from typing import Any
 
 from ring.config import get_config
+from ring.transcript import (
+    _conversation_tail_kind,
+    _extract_todo,
+    _head_cwd,
+    _latest_action,
+    _recent_actions,
+    _tail_records,
+)
 
 CLAUDE_PROJECTS = Path.home() / ".claude" / "projects"
 RING_REGISTRY = Path.home() / ".config" / "ring" / "sessions"
@@ -129,189 +137,6 @@ class Session:
         return self.cwd.replace(home, "~", 1) if self.cwd.startswith(home) else self.cwd
 
 
-def _tail_records(path: Path, max_tail: int = 128 * 1024) -> list[dict[str, Any]]:
-    """讀 JSONL 檔尾若干筆合法 JSON 記錄（舊→新），只 seek 檔尾不整檔讀。"""
-    try:
-        size = path.stat().st_size
-        with path.open("rb") as f:
-            if size > max_tail:
-                f.seek(size - max_tail)
-                f.readline()  # 丟掉被切一半的那行
-            chunk = f.read()
-    except OSError:
-        return []
-    out = []
-    for raw in chunk.splitlines():
-        raw = raw.strip()
-        if not raw:
-            continue
-        try:
-            out.append(json.loads(raw))
-        except json.JSONDecodeError:
-            continue
-    return out
-
-
-def _head_cwd(path: Path, max_head: int = 128 * 1024) -> str:
-    """讀 JSONL 檔頭，回傳第一筆含非空 ``cwd`` 欄位的紀錄之 cwd。
-
-    目的：修補 scan 模式「中途 cd 漂移」問題。Claude Code session 中途 ``cd``
-    後，新紀錄的 ``cwd`` 已指向目的地目錄，若只看檔尾（``_tail_records``）會
-    誤判 session 歸屬。改讀檔頭取「開場 cwd」才能把 session 留在它真正所屬的
-    專案列，而非漂到目的地專案。
-
-    跳過 JSONL 裡無 ``cwd`` 的 meta 筆（last-prompt、mode、permission-mode、
-    file-history-snapshot 等）；命中即停，不必整檔讀完。
-
-    :param path:     JSONL 檔案路徑。
-    :param max_head: 從檔頭最多讀取的位元組數，預設 128 KiB，足以涵蓋早期幾十筆紀錄。
-    :returns:        第一筆非空 cwd 字串；找不到（空檔、全無 cwd）回 ``""``。
-    """
-    try:
-        with path.open("rb") as f:
-            chunk = f.read(max_head)
-    except OSError:
-        return ""
-    for raw in chunk.splitlines():
-        raw = raw.strip()
-        if not raw:
-            continue
-        try:
-            record = json.loads(raw)
-        except json.JSONDecodeError:
-            continue
-        cwd = record.get("cwd")
-        if cwd and isinstance(cwd, str):
-            return cwd
-    return ""
-
-
-def _blocks(record: dict[str, Any]) -> list[Any]:
-    msg = record.get("message")
-    if isinstance(msg, dict):
-        content = msg.get("content")
-        if isinstance(content, list):
-            return content
-        if isinstance(content, str):
-            return [{"type": "text", "text": content}]
-    return []
-
-
-_CMD_NOISE = ("<local-command-stdout>", "<command-name>", "<command-message>", "<command-args>")
-
-
-def _clean_text(s: str) -> str:
-    s = s.strip()
-    if any(marker in s for marker in _CMD_NOISE):
-        return ""  # slash-command 的 stdout / 標記，不是真動作
-    return s.splitlines()[0].strip() if s else ""  # 只取第一行，旁白長文不洗版
-
-
-def _tool_summary(block: dict[str, Any]) -> str:
-    """把一個 tool_use 變成簡短摘要，例如 → Edit foo.py / → Bash: git status。"""
-    name = str(block.get("name") or "")
-    if not name:
-        return ""
-    inp = block.get("input")
-    if not isinstance(inp, dict):
-        inp = {}
-    if name in ("Edit", "Write", "Read", "NotebookEdit"):
-        path = inp.get("file_path") or inp.get("notebook_path")
-        if path:
-            return f"→ {name} {Path(str(path)).name}"
-    elif name == "Bash":
-        cmd = str(inp.get("command") or "").strip().replace("\n", " ")
-        if cmd:
-            return f"→ Bash: {cmd[:40]}"
-    elif name in ("Grep", "Glob") and inp.get("pattern"):
-        return f"→ {name} {inp['pattern']}"
-    return f"→ {name}"
-
-
-def _latest_action(records: list[dict[str, Any]]) -> str:
-    """從新到舊找最近一個「真動作」：agent 的 tool_use 優先，其次 agent 的文字。
-
-    跳過 user 訊息、tool_result、slash-command 輸出這類雜訊。
-    """
-    for record in reversed(records):
-        for block in _blocks(record):
-            if isinstance(block, dict) and block.get("type") == "tool_use":
-                summary = _tool_summary(block)
-                if summary:
-                    return summary
-        if record.get("type") == "assistant":
-            for block in _blocks(record):
-                if isinstance(block, dict) and block.get("type") == "text":
-                    txt = _clean_text(str(block.get("text", "")))
-                    if txt:
-                        return txt[:80]
-    return "—"
-
-
-def _extract_todo(records: list[dict[str, Any]]) -> tuple[int, int] | None:
-    """從新到舊找最新的 TodoWrite，回傳 (done, total)。真進度訊號。"""
-    for record in reversed(records):
-        for block in _blocks(record):
-            if not isinstance(block, dict):
-                continue
-            if block.get("type") == "tool_use" and block.get("name") == "TodoWrite":
-                todos = (block.get("input") or {}).get("todos")
-                if isinstance(todos, list) and todos:
-                    done = sum(1 for t in todos if isinstance(t, dict) and t.get("status") == "completed")
-                    return done, len(todos)
-    return None
-
-
-def _conversation_tail_kind(records: list[dict[str, Any]]) -> str:
-    """從對話尾巴往回走，判定最近一個「真訊息紀錄」的性質。
-
-    回傳值（str）：
-    - ``"waiting"``    : 對話最後是 assistant end_turn 收尾，Claude 回完一輪。
-    - ``"working"``    : 對話最後是真人送出的 prompt，輪到 Claude 回應。
-    - ``"interrupted"`` : 工具呼叫進行中（assistant tool_use / user tool_result），尚未完成一輪。
-    - ``"none"``       : 沒有可判定的訊息（空 records、全噪音、無 assistant/user 訊息）。
-
-    演算法：從 ``reversed(records)`` 往回走，跳過噪音，找第一個真訊息紀錄，
-    依 type 與 content 判定後立即 return。絕不直接看 records[-1]——尾巴幾乎都是噪音。
-
-    限制（誠實標明）：靠對話尾巴猜。Notification（卡權限等授權流程）在 JSONL 不留痕跡，
-    scan 模式測不到——那種需要使用者決策的狀態仍需 hook 模式偵測。
-    """
-    for record in reversed(records):
-        t = record.get("type")
-        # --- 跳過噪音 ---
-        if t not in ("user", "assistant"):
-            continue  # file-history-snapshot / system / permission-mode / mode / last-prompt 等
-        if record.get("isMeta") is True:
-            continue
-        if record.get("isSidechain") is True:
-            continue
-        # --- 第一個真訊息紀錄，依 type 判定 ---
-        if t == "assistant":
-            msg = record.get("message")
-            stop_reason = msg.get("stop_reason") if isinstance(msg, dict) else None
-            # assistant 帶 tool_use block → 工具呼叫進行中
-            if any(isinstance(b, dict) and b.get("type") == "tool_use" for b in _blocks(record)):
-                return "interrupted"
-            if stop_reason == "end_turn":
-                return "waiting"
-            # tool_use / stop_sequence / None / 其他 → 視為中途被打斷
-            return "interrupted"
-        # t == "user"
-        # user 帶工具結果（toolUseResult 欄位，或 content 含 tool_result block）→ 中途
-        if record.get("toolUseResult") is not None:
-            return "interrupted"
-        if any(isinstance(b, dict) and b.get("type") == "tool_result" for b in _blocks(record)):
-            return "interrupted"
-        # command 噪音（slash-command stdout）→ 跳過，繼續往回走
-        text_blocks = [b for b in _blocks(record) if isinstance(b, dict) and b.get("type") == "text"]
-        if text_blocks and all(_clean_text(str(b.get("text", ""))) == "" for b in text_blocks):
-            continue
-        # 真人 prompt → 輪到 Claude 回應，不是回合結束
-        return "working"
-    return "none"
-
-
 def _apply_waiting(
     status: Status,
     idle_seconds: float,
@@ -330,15 +155,6 @@ def _apply_waiting(
     return status
 
 
-def _recent_actions(records: list[dict[str, Any]], n: int = 5) -> list[str]:
-    acts = []
-    for record in records:
-        for block in _blocks(record):
-            if isinstance(block, dict) and block.get("type") == "tool_use" and block.get("name"):
-                acts.append(str(block["name"]))
-    return acts[-n:]
-
-
 _tmux_cache: tuple[float, dict[str, str]] = (-1.0, {})
 
 

ring_cli-0.5.0/src/ring/transcript.py

@@ -0,0 +1,204 @@
+"""Transcript 解析層：把 agent CLI 的 JSONL 對話紀錄拆成 RiNG 要的訊號。
+
+純函式、零外部依賴（只 stdlib），不認識 ``Session`` 也不碰 process / tmux——
+那些屬於 ``registry``。把這層獨立出來，``registry`` 才能專注在「抓 session」，
+解析邏輯也好單測。Claude Code 與 Codex 的 transcript 都走這裡的共用 helper。
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+def _tail_records(path: Path, max_tail: int = 128 * 1024) -> list[dict[str, Any]]:
+    """讀 JSONL 檔尾若干筆合法 JSON 記錄（舊→新），只 seek 檔尾不整檔讀。"""
+    try:
+        size = path.stat().st_size
+        with path.open("rb") as f:
+            if size > max_tail:
+                f.seek(size - max_tail)
+                f.readline()  # 丟掉被切一半的那行
+            chunk = f.read()
+    except OSError:
+        return []
+    out = []
+    for raw in chunk.splitlines():
+        raw = raw.strip()
+        if not raw:
+            continue
+        try:
+            out.append(json.loads(raw))
+        except json.JSONDecodeError:
+            continue
+    return out
+
+
+def _head_cwd(path: Path, max_head: int = 128 * 1024) -> str:
+    """讀 JSONL 檔頭，回傳第一筆含非空 ``cwd`` 欄位的紀錄之 cwd。
+
+    目的：修補 scan 模式「中途 cd 漂移」問題。Claude Code session 中途 ``cd``
+    後，新紀錄的 ``cwd`` 已指向目的地目錄，若只看檔尾（``_tail_records``）會
+    誤判 session 歸屬。改讀檔頭取「開場 cwd」才能把 session 留在它真正所屬的
+    專案列，而非漂到目的地專案。
+
+    跳過 JSONL 裡無 ``cwd`` 的 meta 筆（last-prompt、mode、permission-mode、
+    file-history-snapshot 等）；命中即停，不必整檔讀完。
+
+    :param path:     JSONL 檔案路徑。
+    :param max_head: 從檔頭最多讀取的位元組數，預設 128 KiB，足以涵蓋早期幾十筆紀錄。
+    :returns:        第一筆非空 cwd 字串；找不到（空檔、全無 cwd）回 ``""``。
+    """
+    try:
+        with path.open("rb") as f:
+            chunk = f.read(max_head)
+    except OSError:
+        return ""
+    for raw in chunk.splitlines():
+        raw = raw.strip()
+        if not raw:
+            continue
+        try:
+            record = json.loads(raw)
+        except json.JSONDecodeError:
+            continue
+        cwd = record.get("cwd")
+        if cwd and isinstance(cwd, str):
+            return cwd
+    return ""
+
+
+def _blocks(record: dict[str, Any]) -> list[Any]:
+    msg = record.get("message")
+    if isinstance(msg, dict):
+        content = msg.get("content")
+        if isinstance(content, list):
+            return content
+        if isinstance(content, str):
+            return [{"type": "text", "text": content}]
+    return []
+
+
+_CMD_NOISE = ("<local-command-stdout>", "<command-name>", "<command-message>", "<command-args>")
+
+
+def _clean_text(s: str) -> str:
+    s = s.strip()
+    if any(marker in s for marker in _CMD_NOISE):
+        return ""  # slash-command 的 stdout / 標記，不是真動作
+    return s.splitlines()[0].strip() if s else ""  # 只取第一行，旁白長文不洗版
+
+
+def _tool_summary(block: dict[str, Any]) -> str:
+    """把一個 tool_use 變成簡短摘要，例如 → Edit foo.py / → Bash: git status。"""
+    name = str(block.get("name") or "")
+    if not name:
+        return ""
+    inp = block.get("input")
+    if not isinstance(inp, dict):
+        inp = {}
+    if name in ("Edit", "Write", "Read", "NotebookEdit"):
+        path = inp.get("file_path") or inp.get("notebook_path")
+        if path:
+            return f"→ {name} {Path(str(path)).name}"
+    elif name == "Bash":
+        cmd = str(inp.get("command") or "").strip().replace("\n", " ")
+        if cmd:
+            return f"→ Bash: {cmd[:40]}"
+    elif name in ("Grep", "Glob") and inp.get("pattern"):
+        return f"→ {name} {inp['pattern']}"
+    return f"→ {name}"
+
+
+def _latest_action(records: list[dict[str, Any]]) -> str:
+    """從新到舊找最近一個「真動作」：agent 的 tool_use 優先，其次 agent 的文字。
+
+    跳過 user 訊息、tool_result、slash-command 輸出這類雜訊。
+    """
+    for record in reversed(records):
+        for block in _blocks(record):
+            if isinstance(block, dict) and block.get("type") == "tool_use":
+                summary = _tool_summary(block)
+                if summary:
+                    return summary
+        if record.get("type") == "assistant":
+            for block in _blocks(record):
+                if isinstance(block, dict) and block.get("type") == "text":
+                    txt = _clean_text(str(block.get("text", "")))
+                    if txt:
+                        return txt[:80]
+    return "—"
+
+
+def _extract_todo(records: list[dict[str, Any]]) -> tuple[int, int] | None:
+    """從新到舊找最新的 TodoWrite，回傳 (done, total)。真進度訊號。"""
+    for record in reversed(records):
+        for block in _blocks(record):
+            if not isinstance(block, dict):
+                continue
+            if block.get("type") == "tool_use" and block.get("name") == "TodoWrite":
+                todos = (block.get("input") or {}).get("todos")
+                if isinstance(todos, list) and todos:
+                    done = sum(1 for t in todos if isinstance(t, dict) and t.get("status") == "completed")
+                    return done, len(todos)
+    return None
+
+
+def _conversation_tail_kind(records: list[dict[str, Any]]) -> str:
+    """從對話尾巴往回走，判定最近一個「真訊息紀錄」的性質。
+
+    回傳值（str）：
+    - ``"waiting"``    : 對話最後是 assistant end_turn 收尾，Claude 回完一輪。
+    - ``"working"``    : 對話最後是真人送出的 prompt，輪到 Claude 回應。
+    - ``"interrupted"`` : 工具呼叫進行中（assistant tool_use / user tool_result），尚未完成一輪。
+    - ``"none"``       : 沒有可判定的訊息（空 records、全噪音、無 assistant/user 訊息）。
+
+    演算法：從 ``reversed(records)`` 往回走，跳過噪音，找第一個真訊息紀錄，
+    依 type 與 content 判定後立即 return。絕不直接看 records[-1]——尾巴幾乎都是噪音。
+
+    限制（誠實標明）：靠對話尾巴猜。Notification（卡權限等授權流程）在 JSONL 不留痕跡，
+    scan 模式測不到——那種需要使用者決策的狀態仍需 hook 模式偵測。
+    """
+    for record in reversed(records):
+        t = record.get("type")
+        # --- 跳過噪音 ---
+        if t not in ("user", "assistant"):
+            continue  # file-history-snapshot / system / permission-mode / mode / last-prompt 等
+        if record.get("isMeta") is True:
+            continue
+        if record.get("isSidechain") is True:
+            continue
+        # --- 第一個真訊息紀錄，依 type 判定 ---
+        if t == "assistant":
+            msg = record.get("message")
+            stop_reason = msg.get("stop_reason") if isinstance(msg, dict) else None
+            # assistant 帶 tool_use block → 工具呼叫進行中
+            if any(isinstance(b, dict) and b.get("type") == "tool_use" for b in _blocks(record)):
+                return "interrupted"
+            if stop_reason == "end_turn":
+                return "waiting"
+            # tool_use / stop_sequence / None / 其他 → 視為中途被打斷
+            return "interrupted"
+        # t == "user"
+        # user 帶工具結果（toolUseResult 欄位，或 content 含 tool_result block）→ 中途
+        if record.get("toolUseResult") is not None:
+            return "interrupted"
+        if any(isinstance(b, dict) and b.get("type") == "tool_result" for b in _blocks(record)):
+            return "interrupted"
+        # command 噪音（slash-command stdout）→ 跳過，繼續往回走
+        text_blocks = [b for b in _blocks(record) if isinstance(b, dict) and b.get("type") == "text"]
+        if text_blocks and all(_clean_text(str(b.get("text", ""))) == "" for b in text_blocks):
+            continue
+        # 真人 prompt → 輪到 Claude 回應，不是回合結束
+        return "working"
+    return "none"
+
+
+def _recent_actions(records: list[dict[str, Any]], n: int = 5) -> list[str]:
+    acts = []
+    for record in records:
+        for block in _blocks(record):
+            if isinstance(block, dict) and block.get("type") == "tool_use" and block.get("name"):
+                acts.append(str(block["name"]))
+    return acts[-n:]