ring-cli 0.11.2__tar.gz → 0.11.4__tar.gz

{ring_cli-0.11.2 → ring_cli-0.11.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ring-cli
-Version: 0.11.2
+Version: 0.11.4
 Summary: RiNG — Realtime Instance Notification Grid for active agent CLI sessions.
 Keywords: claude-code,codex,tui,dashboard,session,monitor,rich
 Author: Wei Lee
@@ -319,7 +319,9 @@ Claude Code events:
 | `PermissionRequest` / `PreToolUse` with `AskUserQuestion` | 🔴 waiting |
 | `SessionEnd` | removed from the board |
 
-Codex currently installs the supported interactive events: `PreToolUse`, `PermissionRequest`, and `Stop`.
+Codex currently installs the supported interactive events: `PreToolUse`, `PermissionRequest`, and `Stop`. Codex
+also emits `PermissionRequest` before an existing policy auto-approves the call; a bare event therefore stays
+🟢 working, and it only turns 🔴 waiting when the payload explicitly carries `requires_action` / `waiting_for`.
 
 Verify that hooks are writing:
 

{ring_cli-0.11.2 → ring_cli-0.11.4}/README.en.md

@@ -294,7 +294,9 @@ Claude Code events:
 | `PermissionRequest` / `PreToolUse` with `AskUserQuestion` | 🔴 waiting |
 | `SessionEnd` | removed from the board |
 
-Codex currently installs the supported interactive events: `PreToolUse`, `PermissionRequest`, and `Stop`.
+Codex currently installs the supported interactive events: `PreToolUse`, `PermissionRequest`, and `Stop`. Codex
+also emits `PermissionRequest` before an existing policy auto-approves the call; a bare event therefore stays
+🟢 working, and it only turns 🔴 waiting when the payload explicitly carries `requires_action` / `waiting_for`.
 
 Verify that hooks are writing:
 

{ring_cli-0.11.2 → ring_cli-0.11.4}/pyproject.toml

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

{ring_cli-0.11.2 → ring_cli-0.11.4}/src/ring/hook.py

@@ -44,8 +44,9 @@ from ring.transcript import _extract_todo, _latest_action, _tail_records
 _HOOK_EVENTS = list(HOOK_EVENTS)
 
 # Codex 的 hooks.json 用跟 Claude 同樣的 PascalCase 事件名，但只支援其中一小撮。
-# 保守取有實證可用的：PermissionRequest（→ 🔴 等核可）、PreToolUse（→ 動作/清除）、
-# Stop（→ 🟡 回合結束、清掉 waiting）。多裝 Codex 不認的事件有風險，故不照搬 Claude 全套。
+# 保守取有實證可用的：PermissionRequest（裸事件只代表權限準備判定；明確需互動才 → 🔴）、
+# PreToolUse（→ 動作/清除）、Stop（→ 🟡 回合結束、清掉 waiting）。多裝 Codex 不認的事件
+# 有風險，故不照搬 Claude 全套。
 _CODEX_HOOK_EVENTS = ["PreToolUse", "PermissionRequest", "Stop"]
 
 # hook command 的 timeout（秒）。給足，因為 notify_backend="agent-hooks" 時權限 modal 會

{ring_cli-0.11.2 → ring_cli-0.11.4}/src/ring/hook_protocol.py

@@ -105,6 +105,13 @@ class CommonHookAdapter:
             status = Status.WORKING
         elif explicit_requires_action is not None:
             status = Status.WAITING if explicit_requires_action else Status.IDLE
+        elif event == "PermissionRequest" and self.provider == "codex":
+            # Codex 會在權限「準備判定」時送 PermissionRequest；即使既有 policy
+            # 隨後自動放行、畫面從未停下來等人，也會經過這個 hook。裸事件因此只能
+            # 證明 agent 還在處理工具呼叫，不能當成使用者需要回應。若 payload 有
+            # requires_action / waiting_for 等明確訊號，已由上面的分支判成 WAITING；
+            # 明確的 requires_action=false 也在上面判成 IDLE，不會落到這裡的 WORKING。
+            status = Status.WORKING
         elif event == "Notification":
             status = Status.WAITING if _is_action_required_notification(data) else Status.IDLE
         elif event == "PreToolUse":

{ring_cli-0.11.2 → ring_cli-0.11.4}/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,38 +702,53 @@ def running_claude_pids() -> list[int]:
     return pids
 
 
-def running_foreground_claude_pids() -> list[int]:
+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 running_claude_pids()
-    args_by_pid = {pid: args for pid, args, _is_bg_host in _parse_ps_claude_lines(_ps_claude_snapshot())}
+        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 running_claude_pids()
+        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]:
+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)
@@ -698,30 +782,77 @@ 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=,args="], 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():
-        parts = line.split(None, 2)
-        if len(parts) >= 2 and os.path.basename(parts[1].strip()) == "codex":
-            args = parts[2] if len(parts) == 3 else ""
-            if _is_codex_internal_process(args):
-                continue
-            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()
@@ -735,24 +866,51 @@ def _is_codex_internal_process(args: str) -> bool:
 
 
 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 _pids_cwd(pids: list[int]) -> dict[int, str] | None:
+    """批次查多個 pid 的 cwd：一次 ``lsof -a -p pid1,pid2,... -d cwd -Fn``（N 次 → 1 次）。
 
-def _pid_cwd(pid: int) -> str:
+    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:
@@ -796,41 +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]]:
+def _claude_procs() -> list[tuple[str, str]] | None:
     """每個可聚焦的前景 Claude：(cwd, tty)。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_foreground_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
 
 
@@ -1090,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 覆蓋）
@@ -1119,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():
@@ -1173,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)
@@ -1190,7 +1392,10 @@ def _hook_sessions(
         # 背景 agent 的 process 沒有可聚焦終端，不能拿來替同 cwd 的舊前景 hook row
         # 證明存活；它只精準認領 args 裡明載的 session id。Claude scan 仍使用包含背景
         # agent 的 session-id 配對，因此沒有 hook row 的 agent 也不會從看板消失。
-        background_ids = background_agent_session_ids()
+        # 這次呼叫失敗（``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)
@@ -1201,9 +1406,11 @@ def _hook_sessions(
             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.2 → ring_cli-0.11.4}/src/ring/sources/__init__.py

@@ -56,7 +56,9 @@ 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"

{ring_cli-0.11.2 → ring_cli-0.11.4}/src/ring/sources/claude_code.py

@@ -31,7 +31,13 @@ class ClaudeCodeSource:
         # 背景 agent 的 process cwd 可能仍是 daemon／啟動目錄，不能拿來按 cwd 猜哪些
         # 前景 transcript 活著。前景先只用可聚焦 process 判活，背景再按 session id 認領。
         procs = registry._claude_procs()
-        agent_ids = registry.background_agent_session_ids()
+        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)

ring_cli-0.11.4/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.2/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()