ring-cli 0.9.0__tar.gz → 0.10.0__tar.gz

{ring_cli-0.9.0 → ring_cli-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ring-cli
-Version: 0.9.0
+Version: 0.10.0
 Summary: RiNG — Realtime Instance Notification Grid for active agent CLI sessions.
 Keywords: claude-code,codex,tui,dashboard,session,monitor,rich
 Author: Wei Lee
@@ -336,8 +336,14 @@ RiNG prefers clickable `terminal-notifier`, then falls back to `osascript` on ma
 on Linux. If none are available, RiNG keeps the board running and skips notifications.
 
 Config keys include `notify_sound`, `notify_sound_name`, `notify_ignore_dnd`,
-`notify_repeat_seconds`, `notify_repeat_max`, and `notify_backend`. Custom notification channels
-can be added by registering another `Notifier`.
+`notify_repeat_seconds`, `notify_repeat_max`, `notify_backend`, and `waiting_cooldown_seconds`.
+Custom notification channels can be added by registering another `Notifier`.
+
+Background subagent permission requests can make a session flap between waiting and working in
+quick succession. `waiting_cooldown_seconds` (180s by default) stops `ring hook`'s system
+notification and the TUI's bell/reminder from firing again the instant a session re-enters waiting
+within the cooldown window of its last alert; set it to `0` to disable the cooldown (alert on
+every re-entry, the old behavior).
 
 `agent-hooks` is an optional external hook helper / decision UI. If it is installed and
 `notify_backend = "agent-hooks"`, `ring hook` still writes RiNG registry state, then passes the
@@ -372,6 +378,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
+waiting_cooldown_seconds = 180   # suppress an immediate re-alert on re-entering waiting within this window; 0 = off
 notify_ntfy_url = ""             # full ntfy topic URL enables phone push (e.g. https://ntfy.sh/my-topic)
 notify_webhook_url = ""          # URL enables the generic webhook backend (JSON POST)
 notify_also = []                 # extra backends fired besides the primary, e.g. ["ntfy"]

{ring_cli-0.9.0 → ring_cli-0.10.0}/README.en.md

@@ -311,8 +311,14 @@ RiNG prefers clickable `terminal-notifier`, then falls back to `osascript` on ma
 on Linux. If none are available, RiNG keeps the board running and skips notifications.
 
 Config keys include `notify_sound`, `notify_sound_name`, `notify_ignore_dnd`,
-`notify_repeat_seconds`, `notify_repeat_max`, and `notify_backend`. Custom notification channels
-can be added by registering another `Notifier`.
+`notify_repeat_seconds`, `notify_repeat_max`, `notify_backend`, and `waiting_cooldown_seconds`.
+Custom notification channels can be added by registering another `Notifier`.
+
+Background subagent permission requests can make a session flap between waiting and working in
+quick succession. `waiting_cooldown_seconds` (180s by default) stops `ring hook`'s system
+notification and the TUI's bell/reminder from firing again the instant a session re-enters waiting
+within the cooldown window of its last alert; set it to `0` to disable the cooldown (alert on
+every re-entry, the old behavior).
 
 `agent-hooks` is an optional external hook helper / decision UI. If it is installed and
 `notify_backend = "agent-hooks"`, `ring hook` still writes RiNG registry state, then passes the
@@ -347,6 +353,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
+waiting_cooldown_seconds = 180   # suppress an immediate re-alert on re-entering waiting within this window; 0 = off
 notify_ntfy_url = ""             # full ntfy topic URL enables phone push (e.g. https://ntfy.sh/my-topic)
 notify_webhook_url = ""          # URL enables the generic webhook backend (JSON POST)
 notify_also = []                 # extra backends fired besides the primary, e.g. ["ntfy"]

{ring_cli-0.9.0 → ring_cli-0.10.0}/pyproject.toml

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

{ring_cli-0.9.0 → ring_cli-0.10.0}/src/ring/config.py

@@ -20,6 +20,8 @@
                                       #   "none" = 完全不發通知（RiNG 當純看板）
     notify_repeat_seconds = [30, 120, 300]  # 持續等你時，多久後重複提醒
     notify_repeat_max = 3             # 重複提醒上限；0 = 不限
+    waiting_cooldown_seconds = 180    # session 離開 WAITING 又轉回時，距上次提醒未滿這段時間就
+                                      #   不再當「新轉入」立即提醒（防翻轉轟炸）；0 = 關閉（現行為）
     notify_ntfy_url = "https://ntfy.sh/my-topic"   # 設了才啟用 ntfy 後端（推到手機）
     notify_webhook_url = "https://example.com/hook"  # 設了才啟用 webhook 後端（JSON POST）
     notify_also = ["ntfy"]            # 主後端之外「加發」的後端（例如桌面通知＋手機各一份）
@@ -69,6 +71,7 @@ class Config:
     notify_backend: str = "auto"
     notify_repeat_seconds: tuple[int, ...] = (30, 120, 300)
     notify_repeat_max: int = 3  # 0 = 不限
+    waiting_cooldown_seconds: int = 180  # 離開 WAITING 又轉回時的提醒冷卻期；0 = 關閉（現行為）
     notify_ntfy_url: str = ""  # 完整 ntfy topic URL；空＝ntfy 後端不可用
     notify_webhook_url: str = ""  # webhook URL；空＝webhook 後端不可用
     notify_also: tuple[str, ...] = ()  # 主後端之外加發的後端名（如 ["ntfy"]）
@@ -138,6 +141,7 @@ def load(path: Path | None = None) -> Config:
         notify_ignore_dnd=_as_bool(raw.get("notify_ignore_dnd"), d.notify_ignore_dnd),
         notify_repeat_seconds=_as_positive_int_tuple(raw.get("notify_repeat_seconds"), d.notify_repeat_seconds),
         notify_repeat_max=max(0, _as_int(raw.get("notify_repeat_max"), d.notify_repeat_max)),
+        waiting_cooldown_seconds=max(0, _as_int(raw.get("waiting_cooldown_seconds"), d.waiting_cooldown_seconds)),
         notify_backend=notify_backend,
         notify_ntfy_url=(raw["notify_ntfy_url"] if isinstance(raw.get("notify_ntfy_url"), str) else ""),
         notify_webhook_url=(raw["notify_webhook_url"] if isinstance(raw.get("notify_webhook_url"), str) else ""),
@@ -208,6 +212,7 @@ _SETTERS: dict[str, Callable[[str], object]] = {
     "notify_backend": str,
     "notify_repeat_seconds": _coerce_int_list,
     "notify_repeat_max": _coerce_int,
+    "waiting_cooldown_seconds": _coerce_int,
     "notify_ntfy_url": str,
     "notify_webhook_url": str,
     "notify_also": _coerce_str_list,

{ring_cli-0.9.0 → ring_cli-0.10.0}/src/ring/hook.py

@@ -169,7 +169,8 @@ def _record_session_state(data: dict[str, Any], selected_provider: str) -> None:
 
     unhide_session(event.session_id)
     path = RING_REGISTRY / f"{quote(event.session_id, safe=':')}.json"
-    prev_status = _previous_status(path)
+    prev_row = _previous_row(path)
+    prev_status = str(prev_row["status"]) if "status" in prev_row else None
     if event.status is Status.ENDED:
         path.unlink(missing_ok=True)  # 乾淨離場：直接消失
         if prev_status is not None and prev_status != Status.ENDED.value:
@@ -213,6 +214,19 @@ def _record_session_state(data: dict[str, Any], selected_provider: str) -> None:
     if tty:
         payload["tty"] = tty
 
+    # waiting 通知冷卻（防翻轉轟炸）：hook 是短命 process，冷卻狀態持久化在 registry row
+    # 的 waiting_notified_at（上次 waiting 通知的 epoch 時間戳）。離開 WAITING 也要把時間戳
+    # 帶進新 row（payload 每次重建，不帶會遺失），快速翻回 WAITING 時才判得出「還在冷卻期」。
+    # 舊 row 沒這欄位 = 從未通知過 → 照發。並發寫沿用既有 tmp+replace 的 last-write-wins。
+    last_notified = _as_epoch(prev_row.get("waiting_notified_at"))
+    if last_notified is not None:
+        payload["waiting_notified_at"] = last_notified
+    should_ring = False
+    if event.status is Status.WAITING:
+        should_ring = _waiting_ring_allowed(last_notified, now)
+        if should_ring:
+            payload["waiting_notified_at"] = now
+
     RING_REGISTRY.mkdir(parents=True, exist_ok=True)
     tmp = path.with_suffix(".json.tmp")
     tmp.write_text(json.dumps(payload))
@@ -221,17 +235,35 @@ def _record_session_state(data: dict[str, Any], selected_provider: str) -> None:
     if prev_status != event.status.value:
         log_transition(event.session_id, event.provider, event.cwd, event.status.value)
 
-    if event.status is Status.WAITING:
+    if should_ring:
         _ring_waiting_now(event, payload, last_action)
 
 
-def _previous_status(path: Path) -> str | None:
-    """讀 registry 檔目前的狀態值（給轉換偵測用）；沒檔 / 壞檔回 None。"""
+def _previous_row(path: Path) -> dict[str, Any]:
+    """讀 registry 檔目前的內容（給轉換偵測與通知冷卻用）；沒檔 / 壞檔回空 dict。"""
     try:
         data = json.loads(path.read_text())
-        return str(data["status"])
+        return data if isinstance(data, dict) else {}
     except Exception:
-        return None
+        return {}
+
+
+def _as_epoch(v: Any) -> float | None:
+    """把 row 欄位值安全轉成 epoch float；缺欄位 / 型別不對回 None（視為從未通知）。"""
+    return float(v) if isinstance(v, (int, float)) and not isinstance(v, bool) else None
+
+
+def _waiting_ring_allowed(last_notified: float | None, now: float) -> bool:
+    """hook 的 waiting 通知是否放行：距上次通知未滿 ``waiting_cooldown_seconds`` 就不發。
+
+    背景 subagent 的權限請求會讓 session 以 30 秒～2 分鐘頻率在 working↔waiting 間翻轉，
+    每次轉入都發一則系統通知會轟炸使用者。cooldown=0 = 關閉（維持現行為：每次轉入都發）；
+    從未通知過（``last_notified`` 為 None，含舊版 row 沒有該欄位）一律放行。
+    """
+    cooldown = get_config().waiting_cooldown_seconds
+    if cooldown <= 0 or last_notified is None:
+        return True
+    return now - last_notified >= cooldown
 
 
 def _ring_waiting_now(event: Any, payload: dict[str, Any], last_action: str) -> None:

{ring_cli-0.9.0 → ring_cli-0.10.0}/src/ring/registry.py

@@ -545,11 +545,21 @@ def running_claude_pids() -> list[int]:
 
 
 def _is_claude_background_process(args: str) -> bool:
-    """Claude daemon / bg pty host 不是使用者可聚焦的 CLI session。"""
+    """Claude daemon / bg pty host / bg-spare 備用 process 不是使用者可聚焦的 CLI session。
+
+    ``--bg-spare`` 是 Claude Code 預熱的備用 process（供下一個 ``claude`` 呼叫快速接手），
+    跟 ``--bg-pty-host`` 一樣不代表真正的使用者 session，卻會被 ``_claude_procs`` 合成假
+    session 列上看板，冒出幽靈列。token 形狀（`--bg-spare`，`--` flag，不是位置參數）取自
+    本機 claude CLI 2.1.206 二進位的 strings 掃描（無法用 ``ps`` 現場逮到活體 bg-spare
+    process，掃描時機是巧合——它壽命短、隨用隨滅）：
+    ``[a,...l,"--bg-pty-host",r,"200","50","--",a,...l,"--bg-spare",n]`` spawn 呼叫，
+    以及 bg-spare process 自己啟動時對 ``process.argv`` 做的
+    ``e.includes("--bg-spare", t+1)`` 檢查，兩處都證實是 ``--`` 前綴的 flag token。
+    """
     tokens = args.split()
     if len(tokens) >= 3 and tokens[1:3] == ["daemon", "run"]:
         return True
-    return "--bg-pty-host" in tokens
+    return "--bg-pty-host" in tokens or "--bg-spare" in tokens
 
 
 def running_codex_pids() -> list[int]:
@@ -610,6 +620,30 @@ def _real(path: str) -> str:
         return path
 
 
+def _is_ancestor_dir(ancestor: str, path: str) -> bool:
+    """``ancestor`` 是否為 ``path`` 本身或其祖先目錄（兩者皆須已用 ``_real`` 正規化）。
+
+    純字串 ``startswith`` 裸比對會誤判 ``/foo`` 命中 ``/foobar``；用尾斜線組出前綴
+    （或直接相等）才能正確界定「目錄」邊界。
+    """
+    if not ancestor or not path:
+        return False
+    if ancestor == path:
+        return True
+    prefix = ancestor if ancestor.endswith(os.sep) else ancestor + os.sep
+    return path.startswith(prefix)
+
+
+def _has_ancestor_live_process(row_cwd: str, live_cwds: list[str]) -> bool:
+    """``live_cwds`` 裡是否有任一筆是 ``row_cwd`` 本身或其祖先目錄。
+
+    用於：使用者在 session 裡 cd 進子目錄後，hook payload 記的 cwd 變成子目錄，但
+    claude process 實際 cwd（lsof 量到的）仍停在啟動目錄——子目錄底下量不到 live
+    process，不代表 session 已離場，只是 process 沒跟著 cd。
+    """
+    return any(_is_ancestor_dir(live_cwd, row_cwd) for live_cwd in live_cwds)
+
+
 def _pid_tty(pid: int) -> str:
     """claude process 的控制終端，正規化成 iTerm2 認得的 "/dev/ttysNNN"。"""
     try:
@@ -990,13 +1024,16 @@ def _hook_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]] = {}
         for pk in _PROVIDER_PROCS:
             provider_procs = procs_by_provider.get(pk, []) if procs_by_provider is not None else (procs or [])
             for cwd, tty in provider_procs:
-                key = (pk, _real(cwd))
+                real_cwd = _real(cwd)
+                key = (pk, real_cwd)
                 proc_counts[key] = proc_counts.get(key, 0) + 1
                 if tty:
                     proc_ttys.setdefault(key, set()).add(tty)
+                proc_cwds_by_provider.setdefault(pk, []).append(real_cwd)
 
         rows_by_key: dict[tuple[str, str], list[Session]] = {}
         for s in out:
@@ -1008,6 +1045,14 @@ def _hook_sessions(
         for key, rows in rows_by_key.items():
             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 量到的）仍停在啟動目錄——兩者都正規化過，子目錄底下自然量不到
+                    # live proc。祖先目錄有活 process 時保守判定「還活著」，不殺，避免把正常
+                    # cd 進子目錄的 session 誤判 ENDED（見
+                    # test_hook_sessions_keeps_live_session_when_cwd_moved_to_subdir）。
+                    continue
                 for s in rows:
                     s.status = Status.ENDED
                 continue

{ring_cli-0.9.0 → ring_cli-0.10.0}/src/ring/tui.py

@@ -125,7 +125,9 @@ class RingApp(App[None]):
         # 通知點過來時指向的 session：那一列要持續醒目標記，直到它離開 WAITING（你回應了）或不在場。
         self._focused_sid: str | None = None
         cfg = get_config()
-        self._alerts = WaitingAlertScheduler(cfg.notify_repeat_seconds, cfg.notify_repeat_max)
+        self._alerts = WaitingAlertScheduler(
+            cfg.notify_repeat_seconds, cfg.notify_repeat_max, cooldown_seconds=cfg.waiting_cooldown_seconds
+        )
         self.title = "RiNG 🎤"
         # 記下自己的 controlling tty，供 _poll_focus_request activate 視窗用。
         self._own_tty: str = self._detect_own_tty()

{ring_cli-0.9.0 → ring_cli-0.10.0}/src/ring/watcher.py

@@ -55,6 +55,11 @@ class WaitingAlertScheduler:
 
     第一輪只 prime，不通知既有 waiting；之後新轉 waiting 立即通知，持續 waiting 則依
     ``repeat_seconds`` 做最多 ``repeat_max`` 次提醒（0 = 不限）。
+
+    ``cooldown_seconds``：session 離開 WAITING 後若很快又轉回（例如背景 subagent 的權限
+    請求在 working/waiting 間快速翻轉），距上次通知未滿冷卻期就不當「新轉入」立即通知——
+    否則翻轉一次響一次。冷卻期只抑制「重新轉入」這一次的通知，state 仍照常建立，冷卻期滿
+    後的 repeat 邏輯不受影響。0 = 關閉（回到「離開就丟狀態、再轉入必響」的舊行為）。
     """
 
     def __init__(
@@ -63,11 +68,16 @@ class WaitingAlertScheduler:
         repeat_max: int = 0,
         *,
         now: Callable[[], float] = time.time,
+        cooldown_seconds: int = 0,
     ) -> None:
         self._repeat_seconds = repeat_seconds
         self._repeat_max = max(0, repeat_max)
         self._now = now
+        self._cooldown_seconds = max(0, cooldown_seconds)
         self._states: dict[str, _AlertState] = {}
+        # sid → 上次通知時間；離開 WAITING 後 self._states 會丟掉該 sid，但這裡保留給
+        # 冷卻判斷用。只增不減地跟著 feed() 清理過期條目，避免無界成長。
+        self._recently_alerted: dict[str, float] = {}
         self._primed = False
 
     def feed(self, sessions: list[Session]) -> list[Session]:
@@ -76,6 +86,7 @@ class WaitingAlertScheduler:
 
         if not self._primed:
             self._states = {sid: _AlertState(first_seen=now, last_alert=now) for sid in current}
+            self._recently_alerted = {sid: now for sid in current}
             self._primed = True
             return []
 
@@ -84,19 +95,35 @@ class WaitingAlertScheduler:
         for sid, session in current.items():
             state = self._states.get(sid)
             if state is None:
-                next_states[sid] = _AlertState(first_seen=now, last_alert=now)
-                due.append(session)
+                last_alert = self._recently_alerted.get(sid)
+                if self._cooldown_seconds > 0 and last_alert is not None and now - last_alert < self._cooldown_seconds:
+                    # 冷卻中：不通知，但仍建立 state 追蹤，冷卻期滿後 repeat 邏輯照舊接手。
+                    next_states[sid] = _AlertState(first_seen=now, last_alert=last_alert)
+                else:
+                    next_states[sid] = _AlertState(first_seen=now, last_alert=now)
+                    self._recently_alerted[sid] = now
+                    due.append(session)
                 continue
 
             if self._should_repeat(state, now):
                 state.last_alert = now
                 state.repeats_sent += 1
                 due.append(session)
+                self._recently_alerted[sid] = now
             next_states[sid] = state
 
         self._states = next_states
+        self._prune_recently_alerted(now)
         return due
 
+    def _prune_recently_alerted(self, now: float) -> None:
+        """清掉超過冷卻期的 recently-alerted 條目，避免長跑 process 無界成長。"""
+        if not self._cooldown_seconds:
+            self._recently_alerted.clear()
+            return
+        cutoff = now - self._cooldown_seconds
+        self._recently_alerted = {sid: t for sid, t in self._recently_alerted.items() if t >= cutoff}
+
     def _should_repeat(self, state: _AlertState, now: float) -> bool:
         if not self._repeat_seconds:
             return False