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

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

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: ring-cli
-Version: 0.3.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,8 +57,8 @@ 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.
-- **System notifications**: hook mode can beep and notify when a session starts waiting; with `terminal-notifier`, clicking the notification jumps back.
+- **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,14 +133,17 @@ 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.
 
 ### Notifications
 
-Default behavior: with hooks installed, when a session changes to 🔴 waiting, RiNG beeps and sends
-a system notification. If it keeps waiting, RiNG reminds you again at 30s / 120s / 300s by default.
+Default behavior: with hooks installed, the moment a session changes to 🔴 waiting, the hook beeps
+and sends a system notification right then — **no RiNG board needs to be open**, so it rings you even
+after you close the terminal (notifications are event-driven, not polled). While a TUI is open, it
+also nudges you again in-app at 30s / 120s / 300s if the session keeps waiting.
 
 For clickable notifications on macOS, install `terminal-notifier`:
 
@@ -266,7 +269,8 @@ send `requires_action = true/false` or `waiting_for = "permission" | "options" |
 
 ### agent-hooks
 
-Notification details: `--watch` and the TUI both send notifications. The default backend is `auto`:
+Notification details: system notifications are sent by `ring hook` at the event (both `--watch` and
+the TUI only render the board; they no longer send system notifications). The default backend is `auto`:
 RiNG prefers clickable `terminal-notifier`, then falls back to `osascript` on macOS or `notify-send`
 on Linux. If none are available, RiNG keeps the board running and skips notifications.
 
@@ -307,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"
@@ -326,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.3.0 → ring_cli-0.5.0}/README.en.md

@@ -32,8 +32,8 @@ 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.
-- **System notifications**: hook mode can beep and notify when a session starts waiting; with `terminal-notifier`, clicking the notification jumps back.
+- **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,14 +108,17 @@ 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.
 
 ### Notifications
 
-Default behavior: with hooks installed, when a session changes to 🔴 waiting, RiNG beeps and sends
-a system notification. If it keeps waiting, RiNG reminds you again at 30s / 120s / 300s by default.
+Default behavior: with hooks installed, the moment a session changes to 🔴 waiting, the hook beeps
+and sends a system notification right then — **no RiNG board needs to be open**, so it rings you even
+after you close the terminal (notifications are event-driven, not polled). While a TUI is open, it
+also nudges you again in-app at 30s / 120s / 300s if the session keeps waiting.
 
 For clickable notifications on macOS, install `terminal-notifier`:
 
@@ -241,7 +244,8 @@ send `requires_action = true/false` or `waiting_for = "permission" | "options" |
 
 ### agent-hooks
 
-Notification details: `--watch` and the TUI both send notifications. The default backend is `auto`:
+Notification details: system notifications are sent by `ring hook` at the event (both `--watch` and
+the TUI only render the board; they no longer send system notifications). The default backend is `auto`:
 RiNG prefers clickable `terminal-notifier`, then falls back to `osascript` on macOS or `notify-send`
 on Linux. If none are available, RiNG keeps the board running and skips notifications.
 
@@ -282,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"
@@ -301,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.3.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.3.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.3.0 → ring_cli-0.5.0}/src/ring/cli.py

@@ -331,25 +331,15 @@ def run_config(args: list[str]) -> int:
 
 
 def watch(interval: float, count: int, show_all: bool, show_legend: bool) -> int:
-    from ring.notify import notify_waiting
-    from ring.watcher import WaitingAlertScheduler
-
-    cfg = get_config()
+    # 系統通知由 ``ring hook`` 在 session 轉 🔴 等你的當下就地發出（見 hook._ring_waiting_now）；
+    # watch 只負責顯示看板，不再輪詢發通知——這樣關掉看板也照樣 ring 你。
     frames = 0
     footer_text = _("每 {interval}s 刷新 · Ctrl-C 離場", interval=int(interval))
     if not HAVE_RICH:
-        scheduler = WaitingAlertScheduler(cfg.notify_repeat_seconds, cfg.notify_repeat_max)
         try:
             while True:
                 sys.stdout.write("\033[2J\033[H")
                 sessions = board(show_all)
-                alerts = scheduler.feed(sessions)
-                try:
-                    hint = notify_waiting(alerts)
-                    if hint:
-                        print(hint)
-                except Exception:
-                    pass
                 print(_render_plain(sessions, show_legend, show_tool_column(sessions)))
                 print(f"\n{footer_text}")
                 sys.stdout.flush()
@@ -361,18 +351,10 @@ def watch(interval: float, count: int, show_all: bool, show_legend: bool) -> int
             return 0
 
     console = Console()
-    scheduler = WaitingAlertScheduler(cfg.notify_repeat_seconds, cfg.notify_repeat_max)
     try:
         with Live(console=console, screen=True, auto_refresh=False) as live:
             while True:
                 sessions = board(show_all)
-                alerts = scheduler.feed(sessions)
-                try:
-                    hint = notify_waiting(alerts)
-                    if hint:
-                        print(hint)
-                except Exception:
-                    pass
                 body = _rich_renderable(sessions, show_legend, show_tool_column(sessions))
                 live.update(Group(body, Text(f"\n{footer_text}", style=_MUTED)), refresh=True)
                 frames += 1

{ring_cli-0.3.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.3.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.3.0 → ring_cli-0.5.0}/src/ring/hook.py

@@ -33,12 +33,11 @@ from ring.i18n import gettext as _
 from ring.i18n import set_lang
 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)
 
@@ -127,11 +126,13 @@ def _session_tty(process_names: tuple[str, ...]) -> str:
 
 
 def run_hook(provider: str = "claude-code") -> int:
-    """讀一次 stdin → 寫 RiNG registry 狀態（看板）→（可選）把決策委派給 agent-hooks。
+    """讀一次 stdin → 寫 RiNG registry 狀態（看板）→ 轉等你時就地發通知 →（可選）委派 agent-hooks。
 
-    委派只在 ``notify_backend == "agent-hooks"`` 且 PATH 上有 ``agent-hooks`` 時發生：
-    把原始 payload 透傳給 ``agent-hooks callback``，由它同步出 modal、收按鈕、把決策
-    寫到 stdout 回給 Claude。其餘情況 RiNG 只記狀態、exit 0（你在終端自己回答）。
+    轉 🔴 等你的事件，會在當下直接發系統通知（見 ``_ring_waiting_now``）——不必開著看板，
+    關掉終端也照樣 ring 你。委派只在 ``notify_backend == "agent-hooks"`` 且 PATH 上有
+    ``agent-hooks`` 時發生：把原始 payload 透傳給 ``agent-hooks callback``，由它同步出 modal、
+    收按鈕、把決策寫到 stdout 回給 Claude（這條路下 ``_ring_waiting_now`` 自動短路、不重複發）。
+    其餘情況 RiNG 記狀態 + 發通知後 exit 0（你在終端自己回答）。
     """
     try:
         raw = sys.stdin.read()
@@ -191,6 +192,40 @@ def _record_session_state(data: dict[str, Any], selected_provider: str) -> None:
     tmp.write_text(json.dumps(payload))
     tmp.replace(path)  # atomic
 
+    if event.status is Status.WAITING:
+        _ring_waiting_now(event, payload, last_action)
+
+
+def _ring_waiting_now(event: Any, payload: dict[str, Any], last_action: str) -> None:
+    """session 轉 🔴 等你的當下，就地由 hook 發系統通知——不必等 RiNG 看板輪詢。
+
+    WAITING 只會從 hook 來（scan 模式永不標 WAITING），所以 hook 是第一手知道「等你」
+    的地方；在事件當下通知最即時，也不依賴看板有沒有開著（看板沒開時舊版根本不會 ring
+    你）。backend=none / agent-hooks 由 notify_waiting → _select_notifier 自動短路
+    （agent-hooks 改走 _delegate_to_agent_hooks 的 modal 委派），不會重複發。
+    失敗安靜吞掉，絕不擋住 session。
+    """
+    try:
+        from ring.notify import notify_waiting
+
+        notify_waiting(
+            [
+                Session(
+                    session_id=event.session_id,
+                    cwd=event.cwd,
+                    status=Status.WAITING,
+                    last_active=float(payload.get("last_active", time.time())),
+                    last_action=last_action,
+                    source="hook",
+                    tty=payload.get("tty"),
+                    provider=event.provider,
+                    origin_cwd=event.cwd,
+                )
+            ]
+        )
+    except Exception:
+        pass
+
 
 def _delegate_to_agent_hooks(raw: str, selected_provider: str) -> int:
     """notify_backend=="agent-hooks" 且 agent-hooks 在 PATH → 透傳 payload 給它出決策。

{ring_cli-0.3.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, {})
 
 
@@ -590,7 +406,7 @@ def _codex_threads(procs: list[tuple[str, str]]) -> list[Session]:
             continue
         updated_ms = int(row["updated_at_ms"] or 0)
         last_active = updated_ms / 1000 if updated_ms else float(row["updated_at"] or 0)
-        if now - last_active > ACTIVE_WINDOW_SECONDS and counts.get(cwd, 0) == 0:
+        if now - last_active > ACTIVE_WINDOW_SECONDS and counts.get(_real(cwd), 0) == 0:
             continue
         rollout_path = Path(str(row["rollout_path"] or ""))
         records = _tail_records(rollout_path) if rollout_path else []

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:]

{ring_cli-0.3.0 → ring_cli-0.5.0}/src/ring/tui.py

@@ -36,7 +36,6 @@ from ring.i18n import gettext as _
 from ring.i18n import set_lang
 from ring.ipc import clear_tui_presence, read_focus_request, write_tui_presence
 from ring.labels import get_label, load_labels, set_label
-from ring.notify import notify_waiting
 from ring.registry import Session, Status, running_agent_pids
 from ring.watcher import WaitingAlertScheduler
 
@@ -280,14 +279,10 @@ class RingApp(App[None]):
             cur = next((s for s in self._sessions if s.session_id == self._focused_sid), None)
             if cur is None or cur.status is not Status.WAITING:
                 self._focused_sid = None
+        # 系統通知（toast）改由 ``ring hook`` 在事件當下發出（見 hook._ring_waiting_now）；
+        # 這裡只留 TUI 自己的 in-app 響鈴 / 訊息列與醒目標記，不重複發系統通知。
         alerts = self._alerts.feed(self._sessions)
         self._ring_on_waiting_alerts(alerts)
-        try:
-            hint = notify_waiting(alerts)
-            if hint:
-                self.notify(hint, timeout=10)
-        except Exception:
-            pass
         self.sub_title = _header(len(self._sessions), len(running_agent_pids()))
         labels = load_labels()
         table.clear()