ring-cli 0.11.1__tar.gz → 0.11.3__tar.gz

{ring_cli-0.11.1 → ring_cli-0.11.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ring-cli
-Version: 0.11.1
+Version: 0.11.3
 Summary: RiNG — Realtime Instance Notification Grid for active agent CLI sessions.
 Keywords: claude-code,codex,tui,dashboard,session,monitor,rich
 Author: Wei Lee
@@ -157,6 +157,7 @@ Completes subcommands, flags, and `config set` keys; `ring focus` prompts for a
   Use `↑/↓` to select, `Enter` / `Space` to jump, `p` to reply to a permission request in place, `n` to name a session, `a` to toggle ended sessions, `dd` to hide a session (it reappears automatically once it has new activity), `r` to refresh, and `q` to quit.
   If you have vim muscle memory like I do, `j/k` move up/down and `g/G` jump to the first/last row.
   When the selected row is 🔴 waiting, a line under the table shows **what it is concretely waiting for** (the command to run, the question asked; hook mode only).
+  Claude Code background agents carry a `⚙` badge. They have no terminal to jump to, so selecting one shows a `claude --resume` hint; completed agents are folded into ended sessions by default and remain available via `a`.
 - Otherwise: Rich polling; without Rich, plain text.
 
 ### Jump To A Session
@@ -181,6 +182,8 @@ ones with a "from the … agent" header), and lists the numbered options verbati
 After you pick one, RiNG **captures the screen again** to confirm the dialog is still there and
 unchanged (it may have been answered while you were deciding), only then sends that single
 digit, and re-checks that the dialog actually disappeared.
+Once the reply is verified, the TUI immediately clears that waiting revision. Only a newer hook
+event, such as another permission request, can mark the session as waiting again.
 
 - **Sessions inside tmux**: reads the screen with `tmux capture-pane` and sends keys with
   `tmux send-keys`.

{ring_cli-0.11.1 → ring_cli-0.11.3}/README.en.md

@@ -132,6 +132,7 @@ Completes subcommands, flags, and `config set` keys; `ring focus` prompts for a
   Use `↑/↓` to select, `Enter` / `Space` to jump, `p` to reply to a permission request in place, `n` to name a session, `a` to toggle ended sessions, `dd` to hide a session (it reappears automatically once it has new activity), `r` to refresh, and `q` to quit.
   If you have vim muscle memory like I do, `j/k` move up/down and `g/G` jump to the first/last row.
   When the selected row is 🔴 waiting, a line under the table shows **what it is concretely waiting for** (the command to run, the question asked; hook mode only).
+  Claude Code background agents carry a `⚙` badge. They have no terminal to jump to, so selecting one shows a `claude --resume` hint; completed agents are folded into ended sessions by default and remain available via `a`.
 - Otherwise: Rich polling; without Rich, plain text.
 
 ### Jump To A Session
@@ -156,6 +157,8 @@ ones with a "from the … agent" header), and lists the numbered options verbati
 After you pick one, RiNG **captures the screen again** to confirm the dialog is still there and
 unchanged (it may have been answered while you were deciding), only then sends that single
 digit, and re-checks that the dialog actually disappeared.
+Once the reply is verified, the TUI immediately clears that waiting revision. Only a newer hook
+event, such as another permission request, can mark the session as waiting again.
 
 - **Sessions inside tmux**: reads the screen with `tmux capture-pane` and sends keys with
   `tmux send-keys`.

{ring_cli-0.11.1 → ring_cli-0.11.3}/pyproject.toml

@@ -2,7 +2,7 @@
 # import 的 module（見 [tool.uv.build-backend] module-name）與 CLI 指令仍是 `ring`。
 [project]
 name = "ring-cli"
-version = "0.11.1"
+version = "0.11.3"
 description = "RiNG — Realtime Instance Notification Grid for active agent CLI sessions."
 readme = "README.en.md"
 requires-python = ">=3.13"

{ring_cli-0.11.1 → ring_cli-0.11.3}/src/ring/registry.py

@@ -70,7 +70,7 @@ HOOK_HEARTBEAT_STALE_GRACE_SECONDS = 60.0
 # 要支援新工具的存活偵測＝註冊一個偵測器，_hook_sessions / sources 零改動。
 # 同義 provider 名先正規化（例如 "claude" → "claude-code"）。
 _PROVIDER_ALIASES: dict[str, str] = {"claude": "claude-code"}
-_PROVIDER_PROCS: dict[str, Callable[[], list[tuple[str, str]]]] = {}
+_PROVIDER_PROCS: dict[str, Callable[[], list[tuple[str, str]] | None]] = {}
 
 
 def _canonical_provider(provider: str) -> str:
@@ -253,7 +253,7 @@ def prune_hidden_sessions(
         return stale
 
 
-def register_provider_procs(provider: str, detector: Callable[[], list[tuple[str, str]]]) -> None:
+def register_provider_procs(provider: str, detector: Callable[[], list[tuple[str, str]] | None]) -> None:
     """註冊某 provider 的 live-process 偵測器（回傳 ``[(cwd, tty), …]``）。
 
     有偵測器的 provider 才會在 ``_hook_sessions`` 走 process-based 存活清理；沒註冊的
@@ -262,8 +262,12 @@ def register_provider_procs(provider: str, detector: Callable[[], list[tuple[str
     _PROVIDER_PROCS[_canonical_provider(provider)] = detector
 
 
-def collect_provider_procs() -> dict[str, list[tuple[str, str]]]:
-    """所有已註冊 provider 的當下 live procs，鍵為標準 provider 名。"""
+def collect_provider_procs() -> dict[str, list[tuple[str, str]] | None]:
+    """所有已註冊 provider 的當下 live procs，鍵為標準 provider 名。
+
+    值為 ``None`` 代表該 provider 這輪偵測失敗（未知），呼叫端（``_hook_sessions``）
+    必須把它與「真的偵測到零個 live process」分開處理，不能兩者都判離場。
+    """
     return {provider: detector() for provider, detector in _PROVIDER_PROCS.items()}
 
 
@@ -520,12 +524,33 @@ def _tmux_process_tree_targets(sessions: list[Session]) -> dict[str, str]:
 _pids_cache: tuple[float, list[int]] = (-1.0, [])
 _codex_pids_cache: tuple[float, list[int]] = (-1.0, [])
 _ps_claude_snapshot_cache: tuple[float, str] = (-1.0, "")
+_ps_codex_snapshot_cache: tuple[float, str] = (-1.0, "")
 _bg_agent_session_ids_cache: tuple[float, frozenset[str]] = (-1.0, frozenset())
 
 # args 內任一出現即可判定「這是 claude 安裝二進位在跑」的路徑標記。ps comm 對
 # daemon-exec 的二進位常被截斷（如 `/Users/weilee/.l`），單看 comm 不可靠。
 _CLAUDE_PATH_MARKERS = ("ClaudeCode.app", "claude/versions/", "/.claude/")
 
+# Claude Code 每次 Bash 工具呼叫都會 spawn 一個短命（0-10 秒）的 shell 承載
+# `source ~/.claude/shell-snapshots/snapshot-*.sh` 之類的初始化腳本，cwd 就是
+# 專案目錄——外觀酷似真正的 claude session。這個 shell 的 comm 是完整路徑
+# （例如 `/bin/zsh`），但 args 裡含 `/.claude/` 子字串，會命中上面的
+# `_CLAUDE_PATH_MARKERS`，被誤判為 claude session process，導致 board 上 session
+# 數在每次任何 session 跑指令時 flap（synthetic row 出現又消失 / live 名額被灌水）。
+# 真實樣本見 2026-07-13/14 現場取證（proc_logger.log）。這裡的守門：comm basename
+# 一旦是已知 shell 名稱，一律不是 claude session——真正的 claude session comm
+# 只會是 `claude` 或被截斷的安裝路徑片段（如 `/Users/weilee/.l`），從不會是
+# shell 執行檔本身。
+_SHELL_COMM_BASENAMES = frozenset({"sh", "bash", "zsh", "dash", "ksh", "csh", "tcsh", "fish"})
+
+
+def _is_shell_comm(comm: str) -> bool:
+    """comm basename 是否為常見 shell（含 login shell 的 ``-`` 前綴，如 ``-zsh``）。"""
+    base = os.path.basename(comm.strip())
+    if base.startswith("-"):
+        base = base[1:]
+    return base in _SHELL_COMM_BASENAMES
+
 
 def _is_claude_session_line(comm: str, args: str) -> bool:
     """判定一行 ``ps`` 輸出是否為 claude session process（承載者或子行程皆算）。
@@ -538,9 +563,15 @@ def _is_claude_session_line(comm: str, args: str) -> bool:
     ``less claude`` 這類完全無關但恰好帶 ``claude`` 字面的 process 會被誤收；
     真正被截斷 comm 的 claude session（daemon 承載者與其子行程）必然帶
     ``--session-id``，所以這個限定不會犧牲 fallback 能力。
+
+    comm basename 為 shell（見 ``_is_shell_comm``）時提前回傳 ``False``：Bash 工具
+    呼叫 spawn 的 shell wrapper args 常含 ``/.claude/``（source shell-snapshots 腳本），
+    會誤觸下面的 path marker 分支，必須在那之前擋下。
     """
     if os.path.basename(comm.strip()) == "claude":
         return True
+    if _is_shell_comm(comm):
+        return False
     if any(marker in args for marker in _CLAUDE_PATH_MARKERS):
         return True
     tokens = args.split()
@@ -549,44 +580,76 @@ def _is_claude_session_line(comm: str, args: str) -> bool:
     return any(os.path.basename(tok) == "claude" for tok in tokens)
 
 
-def _ps_claude_snapshot() -> str:
-    """``ps -Ao pid,comm,args`` 的短快取原始輸出，供多個 claude proc 判定函式共用。"""
+def _ps_claude_snapshot() -> str | None:
+    """``ps -Ao pid,comm,args`` 的短快取原始輸出，供多個 claude proc 判定函式共用。
+
+    回傳 ``None`` 代表這次 ``ps`` 呼叫失敗（逾時／例外）——這是「不知道」，不是
+    「系統上沒有任何 process」，呼叫端必須分開處理，不能把 ``None`` 當空字串解析出
+    零筆存活 process。失敗一律不進快取，好讓下一輪立刻重試，不會被短 TTL 快取卡住。
+    """
     global _ps_claude_snapshot_cache
     now = time.monotonic()
     if 0.0 <= now - _ps_claude_snapshot_cache[0] <= _SUBPROCESS_CACHE_TTL:
         return _ps_claude_snapshot_cache[1]
     try:
-        out = subprocess.run(["ps", "-Ao", "pid,comm,args"], capture_output=True, text=True, timeout=3).stdout
+        result = subprocess.run(["ps", "-Ao", "pid,tty,comm,args"], capture_output=True, text=True, timeout=3)
     except (OSError, subprocess.SubprocessError):
-        out = ""
-    _ps_claude_snapshot_cache = (now, out)
-    return out
+        return None
+    if result.returncode != 0:
+        # 非零 exit 跟逾時／例外一樣是「這次沒問到」，不是「問到了、答案是沒有 process」。
+        return None
+    _ps_claude_snapshot_cache = (now, result.stdout)
+    return result.stdout
 
 
-def _parse_ps_claude_lines(out: str) -> list[tuple[int, str, bool]]:
-    """把 ``ps`` 輸出解析成 claude session 行：``(pid, args, is_bg_pty_host)``。
+def _normalize_tty(raw: str) -> str:
+    """把 ``ps`` 的 tty 欄位正規化成 iTerm2 認得的 ``/dev/ttysNNN``；查無 tty 回空字串。"""
+    tty = raw.strip()
+    if not tty or tty in ("??", "?"):
+        return ""
+    return tty if tty.startswith("/dev/") else f"/dev/{tty}"
+
+
+def _parse_ps_claude_lines(out: str) -> list[tuple[int, str, str, bool]]:
+    """把 ``ps`` 輸出解析成 claude session 行：``(pid, tty, args, is_bg_pty_host)``。
+
+    tty 欄位（``ps -Ao pid,tty,comm,args`` 的第二欄）已正規化，供 ``_claude_procs``
+    直接查表用，不必再對每個 pid 各開一次 ``ps -o tty= -p PID``。
 
     不論是否為背景 process（daemon / bg-spare / bg-pty-host）都收進來——背景判定
     交給呼叫端各自決定要不要濾除；``_hook_sessions`` 的活性判定與
     ``running_claude_pids`` 對「該濾誰」的答案不同，不能在這裡先幫忙決定。
     """
-    entries: list[tuple[int, str, bool]] = []
+    entries: list[tuple[int, str, str, bool]] = []
     for line in out.splitlines()[1:]:
-        parts = line.split(None, 2)
-        if len(parts) < 2:
+        parts = line.split(None, 3)
+        if len(parts) < 3:
             continue
-        comm = parts[1].strip()
-        args = parts[2] if len(parts) == 3 else ""
+        tty = _normalize_tty(parts[1])
+        comm = parts[2].strip()
+        args = parts[3] if len(parts) == 4 else ""
         if not _is_claude_session_line(comm, args):
             continue
         try:
             pid = int(parts[0])
         except ValueError:
             continue
-        entries.append((pid, args, "--bg-pty-host" in args.split()))
+        entries.append((pid, tty, args, "--bg-pty-host" in args.split()))
     return entries
 
 
+def _claude_tty_map() -> dict[int, str] | None:
+    """pid → tty，來自 ``_ps_claude_snapshot()`` 共用的快照，不再多開一次 ``ps``。
+
+    回傳 ``None`` 代表這輪 ``ps`` 掃描失敗（未知）；成功但某 pid 沒出現在快照裡
+    （已死）時，該 pid 直接不在回傳 dict 內——呼叫端用 ``.get(pid, "")`` 取值即可。
+    """
+    snapshot = _ps_claude_snapshot()
+    if snapshot is None:
+        return None
+    return {pid: tty for pid, tty, _args, _is_bg_host in _parse_ps_claude_lines(snapshot)}
+
+
 def _arg_session_id(args: str) -> str | None:
     """解析 args 裡 ``--session-id`` 後面的那個 token；沒有就回 ``None``。"""
     tokens = args.split()
@@ -596,24 +659,30 @@ def _arg_session_id(args: str) -> str | None:
     return None
 
 
-def running_claude_pids() -> list[int]:
+def running_claude_pids() -> list[int] | None:
     """目前活著、使用者可聚焦的 claude CLI pid（daemon / bg-spare / bg 暖機承載者濾除）。
 
     承載者（``--bg-pty-host`` + ``--session-id``）與其子行程常成對出現、共用同一個
     session-id：兩者都算「真 session」不濾除，但只留一個 pid，偏好子行程——子行程
     的 cwd（lsof 量得到）誠實，承載者的 cwd 常是 daemon 自己的 cwd，非專案目錄。
     只有承載者、沒有子行程時（fallback）仍保留承載者這個 pid，好過整個 session 消失。
+
+    回傳 ``None`` 代表這輪 ``ps`` 掃描失敗（未知），不是「沒有任何 claude process」；
+    呼叫端不得把 ``None`` 當空清單使用來判定 session 離場。失敗不快取，下一輪重試。
     """
     global _pids_cache
     now = time.monotonic()
     if 0.0 <= now - _pids_cache[0] <= _SUBPROCESS_CACHE_TTL:
         return _pids_cache[1]
-    entries = _parse_ps_claude_lines(_ps_claude_snapshot())
+    snapshot = _ps_claude_snapshot()
+    if snapshot is None:
+        return None
+    entries = _parse_ps_claude_lines(snapshot)
 
     pids: list[int] = []
     sid_index: dict[str, int] = {}  # session-id → 該 pid 在 pids 裡的位置，供子行程晚到時換掉
     sid_is_bg_host: dict[str, bool] = {}
-    for pid, args, is_bg_host in entries:
+    for pid, _tty, args, is_bg_host in entries:
         if _is_claude_background_process(args):
             continue
         session_id = _arg_session_id(args)
@@ -633,20 +702,53 @@ def running_claude_pids() -> list[int]:
     return pids
 
 
-def background_agent_session_ids() -> set[str]:
+def running_foreground_claude_pids() -> list[int] | None:
+    """目前仍有可聚焦終端的 Claude session pid。
+
+    ``running_claude_pids`` 也包含 agents mode 的背景 session，因為 scan 需要靠它們
+    找到對應 transcript；但 hook registry 不能拿背景 agent 的 cwd／數量替同專案的
+    舊前景 row 證明存活，否則一個 agent 就可能讓 crash 數小時的 session 繼續顯示。
+
+    回傳 ``None`` 代表這輪掃描失敗（未知），呼叫端不得當空清單處理。
+    """
+    bg_ids = background_agent_session_ids()
+    if bg_ids is None:
+        return None
+    base_pids = running_claude_pids()
+    if base_pids is None:
+        return None
+    if not bg_ids:
+        return base_pids
+    snapshot = _ps_claude_snapshot()
+    if snapshot is None:
+        return None
+    args_by_pid = {pid: args for pid, _tty, args, _is_bg_host in _parse_ps_claude_lines(snapshot)}
+    return [
+        pid
+        for pid in base_pids
+        if (session_id := _arg_session_id(args_by_pid.get(pid, ""))) is None or session_id not in bg_ids
+    ]
+
+
+def background_agent_session_ids() -> set[str] | None:
     """所有背景 agent（``--bg-pty-host`` 承載且已載入真 session）的 session-id 集合。
 
     給 ``discover_sessions()`` 對應貼 ``kind="agent"`` 標籤用。與 ``running_claude_pids``
     共用同一份 ``ps`` 快照（``_ps_claude_snapshot``），不額外多打一次 ``ps``。
+
+    回傳 ``None`` 代表這輪掃描失敗（未知），不是「沒有背景 agent」。
     """
     global _bg_agent_session_ids_cache
     now = time.monotonic()
     if 0.0 <= now - _bg_agent_session_ids_cache[0] <= _SUBPROCESS_CACHE_TTL:
         return set(_bg_agent_session_ids_cache[1])
-    entries = _parse_ps_claude_lines(_ps_claude_snapshot())
+    snapshot = _ps_claude_snapshot()
+    if snapshot is None:
+        return None
+    entries = _parse_ps_claude_lines(snapshot)
     ids = frozenset(
         session_id
-        for _pid, args, is_bg_host in entries
+        for _pid, _tty, args, is_bg_host in entries
         if is_bg_host and (session_id := _arg_session_id(args)) is not None
     )
     _bg_agent_session_ids_cache = (now, ids)
@@ -680,46 +782,135 @@ def _is_claude_background_process(args: str) -> bool:
     return False
 
 
-def running_codex_pids() -> list[int]:
+def _ps_codex_snapshot() -> str | None:
+    """``ps -Ao pid=,tty=,comm=,args=`` 的短快取原始輸出，供 codex pid／tty 共用。
+
+    含 tty 欄，讓 ``_codex_tty_map`` 能從同一份快照查表，不必再對每個 pid 各開一次
+    ``ps -o tty= -p PID``。回傳 ``None`` 代表這次 ``ps`` 呼叫失敗（逾時／例外／非零
+    exit）——是「不知道」，不是「沒有任何 process」；失敗不快取，下一輪重試。
+    """
+    global _ps_codex_snapshot_cache
+    now = time.monotonic()
+    if 0.0 <= now - _ps_codex_snapshot_cache[0] <= _SUBPROCESS_CACHE_TTL:
+        return _ps_codex_snapshot_cache[1]
+    try:
+        result = subprocess.run(["ps", "-Ao", "pid=,tty=,comm=,args="], capture_output=True, text=True, timeout=3)
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if result.returncode != 0:
+        # 非零 exit 跟逾時／例外一樣是「這次沒問到」，不是「問到了、答案是沒有 process」。
+        return None
+    _ps_codex_snapshot_cache = (now, result.stdout)
+    return result.stdout
+
+
+def _parse_ps_codex_lines(out: str) -> list[tuple[int, str, str]]:
+    """把 ``_ps_codex_snapshot()`` 的輸出解析成 ``(pid, tty, args)``（僅 comm 為 codex 的行）。"""
+    entries: list[tuple[int, str, str]] = []
+    for line in out.splitlines():
+        parts = line.split(None, 3)
+        if len(parts) < 3 or os.path.basename(parts[2].strip()) != "codex":
+            continue
+        tty = _normalize_tty(parts[1])
+        args = parts[3] if len(parts) == 4 else ""
+        try:
+            pid = int(parts[0])
+        except ValueError:
+            continue
+        entries.append((pid, tty, args))
+    return entries
+
+
+def running_codex_pids() -> list[int] | None:
+    """目前活著的 codex CLI pid。回傳 ``None`` 代表這輪 ``ps`` 掃描失敗（未知），
+    不是「沒有任何 codex process」；失敗不快取，下一輪重試。
+    """
     global _codex_pids_cache
     now = time.monotonic()
     if 0.0 <= now - _codex_pids_cache[0] <= _SUBPROCESS_CACHE_TTL:
         return _codex_pids_cache[1]
-    try:
-        out = subprocess.run(["ps", "-Ao", "pid,comm"], capture_output=True, text=True, timeout=3).stdout
-    except (OSError, subprocess.SubprocessError):
-        out = ""
+    snapshot = _ps_codex_snapshot()
+    if snapshot is None:
+        return None
     pids: list[int] = []
-    for line in out.splitlines()[1:]:
-        parts = line.split(None, 1)
-        if len(parts) == 2 and os.path.basename(parts[1].strip()) == "codex":
-            try:
-                pids.append(int(parts[0]))
-            except ValueError:
-                pass
+    for pid, _tty, args in _parse_ps_codex_lines(snapshot):
+        if _is_codex_internal_process(args):
+            continue
+        pids.append(pid)
     _codex_pids_cache = (now, pids)
     return pids
 
 
+def _codex_tty_map() -> dict[int, str] | None:
+    """pid → tty，來自 ``_ps_codex_snapshot()`` 共用的快照，不再多開一次 ``ps``。
+
+    回傳 ``None`` 代表這輪掃描失敗（未知）；成功但某 pid 沒出現在快照裡（已死）
+    時，該 pid 直接不在回傳 dict 內——呼叫端用 ``.get(pid, "")`` 取值即可。
+    """
+    snapshot = _ps_codex_snapshot()
+    if snapshot is None:
+        return None
+    return {pid: tty for pid, tty, _args in _parse_ps_codex_lines(snapshot)}
+
+
+def _is_codex_internal_process(args: str) -> bool:
+    """Codex app 為工具呼叫啟動的同名內部 process，不是獨立互動 session。"""
+    tokens = args.split()
+    if not tokens:
+        return False
+    try:
+        command_index = next(i for i, token in enumerate(tokens) if os.path.basename(token) == "codex")
+    except StopIteration:
+        return False
+    return command_index + 1 < len(tokens) and tokens[command_index + 1] in {"app-server", "sandbox"}
+
+
 def running_agent_pids() -> list[int]:
-    """所有內建來源看得到的 live agent CLI 行程。"""
-    return [*running_claude_pids(), *running_codex_pids()]
+    """所有內建來源看得到的 live agent CLI 行程（顯示用途的彙總計數）。
+
+    這裡刻意攤平 ``None``（掃描失敗／未知）成空清單——本函式只餵給 header 計數等
+    顯示用途，不是存活判定；真正的 ENDED 判定路徑（``_hook_sessions``）用的是
+    未攤平的 ``running_claude_pids`` / ``running_codex_pids`` 原始回傳值。
+    """
+    return [*(running_claude_pids() or []), *(running_codex_pids() or [])]
 
 
-def _pid_cwd(pid: int) -> str:
+def _pids_cwd(pids: list[int]) -> dict[int, str] | None:
+    """批次查多個 pid 的 cwd：一次 ``lsof -a -p pid1,pid2,... -d cwd -Fn``（N 次 → 1 次）。
+
+    PoC 已驗證（本機 lsof 4.91／macOS）：``-p`` 接受逗號分隔的多 pid；輸出以
+    ``p<pid>`` 分段、其後 ``n<path>`` 行給該 pid 的 cwd。**其中一個 pid 已死時，
+    lsof 對整批呼叫仍回傳 exit code 1**（連全部都死也是 1），但存活 pid 的區段照樣
+    完整輸出——所以本函式刻意不看 ``returncode``，只要 subprocess 本身沒丟例外就
+    解析 stdout。
+
+    回傳 ``None`` 代表這次 lsof **呼叫本身**失敗（逾時／例外）——是「這輪不知道任何
+    pid 的 cwd」（未知），呼叫端不得把它當「都沒有 cwd」用來判定 session 離場。
+    批次呼叫成功但某個 pid 沒出現在輸出裡＝那個 pid 剛死／查無 cwd，是真資訊，不是
+    未知，直接不進回傳的 dict（呼叫端用 ``.get(pid, "")`` 取值，缺項自然視為無 cwd）。
+    """
+    if not pids:
+        return {}
     try:
         out = subprocess.run(
-            ["lsof", "-a", "-p", str(pid), "-d", "cwd", "-Fn"],
+            ["lsof", "-a", "-p", ",".join(str(pid) for pid in pids), "-d", "cwd", "-Fn"],
             capture_output=True,
             text=True,
             timeout=3,
         ).stdout
     except (OSError, subprocess.SubprocessError):
-        return ""
+        return None
+    result: dict[int, str] = {}
+    current_pid: int | None = None
     for line in out.splitlines():
-        if line.startswith("n"):
-            return line[1:]
-    return ""
+        if line.startswith("p"):
+            try:
+                current_pid = int(line[1:])
+            except ValueError:
+                current_pid = None
+        elif line.startswith("n") and current_pid is not None:
+            result.setdefault(current_pid, line[1:])
+    return result
 
 
 def _real(path: str) -> str:
@@ -763,40 +954,70 @@ def _has_ancestor_live_process(row_cwd: str, live_cwds: list[str]) -> bool:
 
 
 def _pid_tty(pid: int) -> str:
-    """claude process 的控制終端，正規化成 iTerm2 認得的 "/dev/ttysNNN"。"""
+    """claude process 的控制終端，正規化成 iTerm2 認得的 "/dev/ttysNNN"。
+
+    單 pid、按需查詢用（例如 hook 事件當下要跳轉終端）；``discover_sessions()``
+    每輪刷新的熱路徑改走 ``_claude_tty_map`` / ``_codex_tty_map``，不逐 pid 開 ``ps``。
+    """
     try:
-        tty = subprocess.run(
-            ["ps", "-o", "tty=", "-p", str(pid)], capture_output=True, text=True, timeout=3
-        ).stdout.strip()
+        tty = subprocess.run(["ps", "-o", "tty=", "-p", str(pid)], capture_output=True, text=True, timeout=3).stdout
     except (OSError, subprocess.SubprocessError):
         return ""
-    if not tty or tty in ("??", "?"):
-        return ""
-    return tty if tty.startswith("/dev/") else f"/dev/{tty}"
+    return _normalize_tty(tty)
 
 
-def _claude_procs() -> list[tuple[str, str]]:
-    """每個還活著的 claude：(cwd, tty)。cwd 判活躍/分流，tty 給終端跳轉。
+def _claude_procs() -> list[tuple[str, str]] | None:
+    """每個可聚焦的前景 Claude：(cwd, tty)。cwd 判活躍/分流，tty 給終端跳轉。
 
-    claude 不會把 session 的 jsonl 一直開著（lsof 看不到），但給得到 cwd 與 tty。
+    背景 agent 不在這裡按 cwd 配對；它們由 source 依 process args 的 session id 精準
+    認領，避免背景 process 的啟動 cwd 讓同專案舊 transcript 誤判成仍在場。
     同一個 cwd 可能同時開好幾個 session，所以之後在 cwd 群組裡只有 mtime 最新的
     這幾個算活著，其餘同專案的舊 session＝已離場。
+
+    cwd／tty 各只批次查一次（``_pids_cwd`` 一次 lsof、``_claude_tty_map`` 沿用共用
+    ps 快照），不再逐 pid 各開一次 lsof + 一次 ps。
+
+    回傳 ``None`` 代表這輪掃描失敗（未知）——``ps``（pid 清單／tty）或 lsof（cwd）
+    任一整批失敗都算，呼叫端（尤其是 ``_hook_sessions`` 的存活判定）不得把它當
+    「沒有任何 claude process」處理。批次呼叫成功但個別 pid 沒查到 cwd/tty（剛死）
+    不算未知，那個 pid 直接不貢獻一列，語意與逐 pid 版本一致。
     """
+    pids = running_foreground_claude_pids()
+    if pids is None:
+        return None
+    cwd_by_pid = _pids_cwd(pids)
+    if cwd_by_pid is None:
+        return None
+    tty_by_pid = _claude_tty_map()
+    if tty_by_pid is None:
+        return None
     procs: list[tuple[str, str]] = []
-    for pid in running_claude_pids():
-        cwd = _pid_cwd(pid)
+    for pid in pids:
+        cwd = cwd_by_pid.get(pid, "")
         if cwd:
-            procs.append((cwd, _pid_tty(pid)))
+            procs.append((cwd, tty_by_pid.get(pid, "")))
     return procs
 
 
-def _codex_procs() -> list[tuple[str, str]]:
-    """每個還活著的 Codex CLI：(cwd, tty)。"""
+def _codex_procs() -> list[tuple[str, str]] | None:
+    """每個還活著的 Codex CLI：(cwd, tty)。回傳 ``None`` 代表這輪掃描失敗（未知）。
+
+    cwd／tty 各只批次查一次，理由與 ``_claude_procs`` 相同。
+    """
+    pids = running_codex_pids()
+    if pids is None:
+        return None
+    cwd_by_pid = _pids_cwd(pids)
+    if cwd_by_pid is None:
+        return None
+    tty_by_pid = _codex_tty_map()
+    if tty_by_pid is None:
+        return None
     procs: list[tuple[str, str]] = []
-    for pid in running_codex_pids():
-        cwd = _pid_cwd(pid)
+    for pid in pids:
+        cwd = cwd_by_pid.get(pid, "")
         if cwd:
-            procs.append((cwd, _pid_tty(pid)))
+            procs.append((cwd, tty_by_pid.get(pid, "")))
     return procs
 
 
@@ -1056,7 +1277,7 @@ def _synthetic_sessions(procs: list[tuple[str, str]], existing: list[Session]) -
     out: list[Session] = []
     seen: set[str] = set()
     for cwd, tty in procs:
-        if not cwd:  # _pid_cwd 失敗的情況，沒 cwd 撐不起一列
+        if not cwd:  # _pids_cwd 查無此 pid cwd 的情況，沒 cwd 撐不起一列
             continue
         rkey = _real(cwd)
         if rkey in existing_cwds:  # 已經有 row 了（hook 或 scan 覆蓋）
@@ -1085,7 +1306,7 @@ def _synthetic_sessions(procs: list[tuple[str, str]], existing: list[Session]) -
 def _hook_sessions(
     procs: list[tuple[str, str]] | None = None,
     *,
-    procs_by_provider: dict[str, list[tuple[str, str]]] | None = None,
+    procs_by_provider: dict[str, list[tuple[str, str]] | None] | None = None,
     purge_session_start_phantoms: bool = True,
 ) -> list[Session]:
     if not RING_REGISTRY.is_dir():
@@ -1139,12 +1360,27 @@ def _hook_sessions(
     #   3. 該 cwd 只有「單一」hook row 時，無論 tty 是否對得上都不靠 tty 殺——hook 寫進來
     #      的 tty 不一定可靠（終端 tty 會被作業系統重配，甚至跨 session 錯置），拿它隱藏
     #      唯一活著的 session 會讓整列憑空消失。
+    #   4. 「這個 provider 這輪 ps／lsof 掃描失敗」（值為 ``None``）是「未知」，不是
+    #      「真的偵測到零個 live process」——未知時完全不動這個 provider 底下任何一筆
+    #      row 的狀態，保留既有狀態，避免單次系統瞬間卡頓（ps timeout）把整版 session
+    #      誤判 ENDED（見 ring-vanishing-sessions 診斷）。
     if out:
         proc_counts: dict[tuple[str, str], int] = {}
         proc_ttys: dict[tuple[str, str], set[str]] = {}
         proc_cwds_by_provider: dict[str, list[str]] = {}
+        unknown_providers: set[str] = set()
         for pk in _PROVIDER_PROCS:
-            provider_procs = procs_by_provider.get(pk, []) if procs_by_provider is not None else (procs or [])
+            if procs_by_provider is not None:
+                provider_procs = procs_by_provider.get(pk, [])
+            else:
+                # 沒有帶 procs_by_provider 時，直接沿用 procs 這個 sentinel-None（單純
+                # 代表「呼叫端沒給」，不是「這輪掃描失敗」），維持既有「當空清單」語意。
+                provider_procs = procs if procs is not None else []
+            if provider_procs is None:
+                # 這輪掃描失敗（ps/lsof timeout 或例外）——標成未知，底下的存活判定
+                # 對這個 provider 一律跳過，不把任何 row 判 ENDED。
+                unknown_providers.add(pk)
+                continue
             for cwd, tty in provider_procs:
                 real_cwd = _real(cwd)
                 key = (pk, real_cwd)
@@ -1153,17 +1389,28 @@ def _hook_sessions(
                     proc_ttys.setdefault(key, set()).add(tty)
                 proc_cwds_by_provider.setdefault(pk, []).append(real_cwd)
 
+        # 背景 agent 的 process 沒有可聚焦終端，不能拿來替同 cwd 的舊前景 hook row
+        # 證明存活；它只精準認領 args 裡明載的 session id。Claude scan 仍使用包含背景
+        # agent 的 session-id 配對，因此沒有 hook row 的 agent 也不會從看板消失。
+        # 這次呼叫失敗（``None``＝未知）時保守當成「沒有已知背景 agent」——claude-code
+        # 這個 provider 本身這輪多半也偵測失敗，會被上面的 unknown_providers 整批保護，
+        # 這裡的 fallback 只是避免拿 None 做 in 運算炸掉。
+        background_ids = background_agent_session_ids() or set()
         rows_by_key: dict[tuple[str, str], list[Session]] = {}
         for s in out:
             pk = _canonical_provider(s.provider)
             if pk not in _PROVIDER_PROCS:
                 continue  # 沒有 proc 偵測器 → 無法驗活性 → fail-open，交給 SessionEnd
+            if pk == "claude-code" and s.session_id in background_ids:
+                continue
             rows_by_key.setdefault((pk, _real(s.cwd)), []).append(s)
 
         for key, rows in rows_by_key.items():
+            pk, row_cwd = key
+            if pk in unknown_providers:
+                continue  # 這輪掃描失敗，未知不等於離場，保留既有狀態
             live_n = proc_counts.get(key, 0)
             if live_n == 0:
-                pk, row_cwd = key
                 if _has_ancestor_live_process(row_cwd, proc_cwds_by_provider.get(pk, [])):
                     # hook payload 的 cwd 落在使用者 cd 進去的子目錄，但 claude process 實際
                     # cwd（lsof 量到的）仍停在啟動目錄——兩者都正規化過，子目錄底下自然量不到

{ring_cli-0.11.1 → ring_cli-0.11.3}/src/ring/sources/__init__.py

@@ -56,10 +56,17 @@ def discover_sessions() -> list[Session]:
             found.append(s)
         # 否則：仍在隱藏保留期內、沒有新活動 → 不收進看板。
 
-    bg_agent_ids = registry.background_agent_session_ids()
+    # None＝這輪掃描失敗（未知）；保守當成「沒有已知背景 agent」，不影響上面已經
+    # 由 hook/scan 各自來源判定好的 status，只影響 kind="agent" 標籤與 IDLE→ENDED 降級。
+    bg_agent_ids = registry.background_agent_session_ids() or set()
     for s in found:
         if s.session_id in bg_agent_ids:
             s.kind = "agent"
+            # 背景 agent 跑完後不會像前景 session 一樣停在終端等下一輪輸入；它只會由
+            # daemon 暫留 process。繼續顯示成「跑完停著」既無法跳轉也無事可處理，反而
+            # 把已完成工作混進在場清單。歸入 ENDED 後預設收起，`--all` / TUI 的 a 仍可查。
+            if s.status is Status.IDLE:
+                s.status = Status.ENDED
 
     bound_targets = registry._tmux_pane_targets()
     process_targets = registry._tmux_process_tree_targets(found)

ring_cli-0.11.3/src/ring/sources/claude_code.py

@@ -0,0 +1,52 @@
+"""Claude Code：掃 ``~/.claude/projects`` 的 JSONL。"""
+
+from __future__ import annotations
+
+import time
+
+import ring.registry as registry
+from ring.registry import Session
+
+
+def _activate_background_agents(sessions: list[Session], agent_ids: set[str]) -> None:
+    """只依明確 session id 恢復仍有 process 的背景 agent，不用它們的 cwd 猜前景活性。"""
+    now = time.time()
+    for session in sessions:
+        if session.session_id not in agent_ids:
+            continue
+        idle = now - session.last_active
+        session.status = registry._scan_status(idle)
+        session.status = registry._apply_waiting(
+            session.status,
+            idle,
+            session._tail_kind,
+            registry.WAITING_WINDOW_SECONDS,
+        )
+
+
+class ClaudeCodeSource:
+    name = "claude-code"
+
+    def discover(self) -> list[Session]:
+        # 背景 agent 的 process cwd 可能仍是 daemon／啟動目錄，不能拿來按 cwd 猜哪些
+        # 前景 transcript 活著。前景先只用可聚焦 process 判活，背景再按 session id 認領。
+        procs = registry._claude_procs()
+        if procs is None:
+            # 這輪 ps/lsof 掃描失敗（未知）。掃描結果未知時，scan 只能把每個 transcript
+            # 判成 ENDED；那批 ENDED row 會經由 _merge_duplicate_session 覆蓋掉 hook
+            # 已保護好的 WAITING row，session 就從看板上消失。未知不等於離場——這輪
+            # 不貢獻任何 row。
+            return []
+        agent_ids = registry.background_agent_session_ids() or set()
+        merged: dict[str, Session] = {}
+        scanned = registry._scan_sessions(procs)
+        _activate_background_agents(scanned, agent_ids)
+        for s in scanned:
+            merged.setdefault(s.session_id, s)
+        existing = list(merged.values())
+        for s in registry._synthetic_sessions(procs, existing):
+            merged.setdefault(s.session_id, s)  # 合成列只填無 row 的 cwd
+        return list(merged.values())
+
+
+source = ClaudeCodeSource()

ring_cli-0.11.3/src/ring/sources/codex.py

@@ -0,0 +1,21 @@
+"""Codex CLI：讀 ``~/.codex/state_5.sqlite`` threads，並用 live ``codex`` process 配 tty。"""
+
+from __future__ import annotations
+
+import ring.registry as registry
+from ring.registry import Session
+
+
+class CodexSource:
+    name = "codex"
+
+    def discover(self) -> list[Session]:
+        procs = registry._codex_procs()
+        if procs is None:
+            # 這輪 ps 掃描失敗（未知）。拿空清單去掃會把每個 thread 判成 ENDED，
+            # 覆蓋掉 hook 已保護的 row。未知不等於離場——這輪不貢獻任何 row。
+            return []
+        return registry._codex_threads(procs)
+
+
+source = CodexSource()

{ring_cli-0.11.1 → ring_cli-0.11.3}/src/ring/tui.py

@@ -197,6 +197,9 @@ class RingApp(App[None]):
         self._own_tty: str = self._detect_own_tty()
         self._delete_armed_sid: str | None = None
         self._delete_armed_until: float = 0.0
+        # p 已確認終端對話框消失，但 provider 尚未送後續 hook 時，別讓同一筆舊
+        # PermissionRequest 又把列拉回 WAITING。value 是已回覆那筆 row 的 last_active revision。
+        self._permission_acks: dict[str, float] = {}
 
     @staticmethod
     def _detect_own_tty() -> str:
@@ -345,6 +348,7 @@ class RingApp(App[None]):
         # 退回去跳 session 自己的終端（scan 模式常沒 tty → 跳轉失敗）。
         write_tui_presence()
         self._sessions = board(self._show_all)
+        self._apply_permission_acks()
         table = self.query_one(DataTable)
         # cursor 快照要在「任何」clear 之前取：clear(columns=True) 會把 cursor_row reset 成 0。
         cursor = table.cursor_row
@@ -389,6 +393,30 @@ class RingApp(App[None]):
         self._update_detail()
         self._poll_focus_request()
 
+    def _apply_permission_acks(self) -> None:
+        """以終端回覆結果蓋過同一 revision 的 stale WAITING，直到 provider 送來新事件。"""
+        present_ids = {s.session_id for s in self._sessions}
+        for session_id in set(self._permission_acks) - present_ids:
+            del self._permission_acks[session_id]
+
+        for s in self._sessions:
+            acknowledged_revision = self._permission_acks.get(s.session_id)
+            if acknowledged_revision is None:
+                continue
+            if s.last_active > acknowledged_revision:
+                # 新 hook event（可能是下一個權限請求）已到，重新採信 provider 狀態。
+                del self._permission_acks[s.session_id]
+                continue
+            if s.status is Status.WAITING:
+                # 終端畫面已證實原對話框消失；provider 尚未回報後續狀態時先視為處理中。
+                s.status = Status.WORKING
+                s.waiting_kind = ""
+                s.waiting_detail = ""
+            else:
+                # provider 已用同 revision 清掉 WAITING，不再需要本地 acknowledgment。
+                del self._permission_acks[s.session_id]
+        self._sessions.sort(key=lambda s: (s.status.rank, s.idle_for))
+
     def _update_detail(self) -> None:
         """detail 列：選中的 session 在 🔴 等什麼（hook 有給具體內容才顯示）。
 
@@ -541,6 +569,7 @@ class RingApp(App[None]):
         if outcome is permission.ReplyOutcome.OK:
             if s.session_id == self._focused_sid:
                 self._focused_sid = None  # 已就地回覆，解除通知標記
+            self._permission_acks[s.session_id] = s.last_active
             self._toast(_("→ {project}：已回覆權限（{option}）", project=name, option=option), ok=True)
             self._reload()
             return

ring_cli-0.11.1/src/ring/sources/claude_code.py

@@ -1,23 +0,0 @@
-"""Claude Code：掃 ``~/.claude/projects`` 的 JSONL。"""
-
-from __future__ import annotations
-
-import ring.registry as registry
-from ring.registry import Session
-
-
-class ClaudeCodeSource:
-    name = "claude-code"
-
-    def discover(self) -> list[Session]:
-        procs = registry._claude_procs()
-        merged: dict[str, Session] = {}
-        for s in registry._scan_sessions(procs):
-            merged.setdefault(s.session_id, s)
-        existing = list(merged.values())
-        for s in registry._synthetic_sessions(procs, existing):
-            merged.setdefault(s.session_id, s)  # 合成列只填無 row 的 cwd
-        return list(merged.values())
-
-
-source = ClaudeCodeSource()

ring_cli-0.11.1/src/ring/sources/codex.py

@@ -1,16 +0,0 @@
-"""Codex CLI：讀 ``~/.codex/state_5.sqlite`` threads，並用 live ``codex`` process 配 tty。"""
-
-from __future__ import annotations
-
-import ring.registry as registry
-from ring.registry import Session
-
-
-class CodexSource:
-    name = "codex"
-
-    def discover(self) -> list[Session]:
-        return registry._codex_threads(registry._codex_procs())
-
-
-source = CodexSource()