ring-cli 0.13.0__tar.gz → 0.14.1__tar.gz

ring_cli-0.14.1/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: ring-cli
+Version: 0.14.1
+Summary: RiNG — Realtime Instance Notification Grid for active agent CLI sessions.
+Keywords: claude-code,codex,ollama,llama-cpp,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 :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Dist: rich>=13
+Requires-Dist: textual>=0.80 ; extra == 'tui'
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/Lee-W/ring
+Project-URL: Repository, https://github.com/Lee-W/ring
+Project-URL: Documentation, https://lee-w.github.io/ring/
+Provides-Extra: tui
+Description-Content-Type: text/markdown
+
+# RiNG 🎤
+
+[台灣華語](README.md) · **English**
+
+[![PyPI](https://img.shields.io/pypi/v/ring-cli?label=PyPI)](https://pypi.org/project/ring-cli/)
+[![Python](https://img.shields.io/pypi/pyversions/ring-cli)](https://pypi.org/project/ring-cli/)
+[![License](https://img.shields.io/pypi/l/ring-cli)](LICENSE)
+
+> **R**ealtime **I**nstance **N**otification **G**rid
+> — one local board for all active agent-CLI sessions.
+
+When several Claude Code, Codex, or local-model sessions are running, RiNG shows which ones are working, idle, or waiting for you. Sessions that need a response are sorted first.
+
+```text
+🎤 RiNG — 3 sessions on stage · 2 agent processes running
+
+  🔴 maigo            12s  → waiting for permission
+  🟢 pelican-osm       3s  → Edit
+  🟡 commitizen        8m  turn finished, idle
+```
+
+## What It Does
+
+- **One board for session state**: built-in sources for Claude Code, Codex, Ollama, and llama.cpp.
+- **Puts waiting sessions first**: shows what 🔴 sessions need and sends desktop or phone notifications.
+- **Returns you to the right terminal**: focuses tmux, iTerm2, Terminal.app, Neovim terminals, or Linux X11 windows from the TUI.
+- **Avoids an extra context switch**: reply to permission requests in supported terminals and assign session names from the board.
+- **Fits existing workflows**: status-bar output, JSON, a provider-neutral hook, and plugin extension points.
+
+## Get Started in Three Steps
+
+Requires Python 3.13+:
+
+```sh
+uv tool install 'ring-cli[tui]'
+ring --watch
+ring install-hooks
+```
+
+1. `ring --watch` opens the interactive board. Select a session and press `Enter` to return to its terminal.
+2. `ring install-hooks` installs Claude Code and Codex hooks for precise 🔴 waiting states and system notifications.
+3. Restart agent sessions after installing hooks. RiNG can then notify you even while its board is closed.
+
+Use `pipx install 'ring-cli[tui]'` if you prefer pipx. Run `ring` for a one-shot snapshot.
+
+## Common Operations
+
+| Operation | Purpose |
+|-----------|---------|
+| `ring` | Print a snapshot of every current session |
+| `ring --watch` | Open the continuously updating interactive TUI |
+| `Enter` / `Space` | Return to the selected session's terminal |
+| `p` | Reply to the selected session's permission request in place |
+| `n` | Name the selected session |
+| `ring doctor` | Check hooks, notifications, and terminal focus support |
+| `ring --format oneline` | Produce a summary for tmux, SwiftBar, or waybar |
+
+Zero-config mode works without hooks. Precise 🔴 waiting states, pending details, and immediate notifications require hooks. Restart Claude Code or Codex sessions after installing or updating them.
+
+## Learn More
+
+- [Full guide](https://lee-w.github.io/ring/guide/): commands, TUI controls, hooks, notifications, configuration, extensions, and privacy
+- [Session states](https://lee-w.github.io/ring/session-states/): how RiNG derives 🔴/🟢/🟡/⚫
+- [Contributing guide](CONTRIBUTING.md): development setup, tests, and PR checklist
+
+RiNG supports macOS and Linux; Windows is not yet supported. By default it only reads local agent data and writes `~/.config/ring/`. Network access occurs only for ntfy or webhook notifiers you configure.
+
+## License
+
+MIT

ring_cli-0.14.1/README.en.md

@@ -0,0 +1,70 @@
+# RiNG 🎤
+
+[台灣華語](README.md) · **English**
+
+[![PyPI](https://img.shields.io/pypi/v/ring-cli?label=PyPI)](https://pypi.org/project/ring-cli/)
+[![Python](https://img.shields.io/pypi/pyversions/ring-cli)](https://pypi.org/project/ring-cli/)
+[![License](https://img.shields.io/pypi/l/ring-cli)](LICENSE)
+
+> **R**ealtime **I**nstance **N**otification **G**rid
+> — one local board for all active agent-CLI sessions.
+
+When several Claude Code, Codex, or local-model sessions are running, RiNG shows which ones are working, idle, or waiting for you. Sessions that need a response are sorted first.
+
+```text
+🎤 RiNG — 3 sessions on stage · 2 agent processes running
+
+  🔴 maigo            12s  → waiting for permission
+  🟢 pelican-osm       3s  → Edit
+  🟡 commitizen        8m  turn finished, idle
+```
+
+## What It Does
+
+- **One board for session state**: built-in sources for Claude Code, Codex, Ollama, and llama.cpp.
+- **Puts waiting sessions first**: shows what 🔴 sessions need and sends desktop or phone notifications.
+- **Returns you to the right terminal**: focuses tmux, iTerm2, Terminal.app, Neovim terminals, or Linux X11 windows from the TUI.
+- **Avoids an extra context switch**: reply to permission requests in supported terminals and assign session names from the board.
+- **Fits existing workflows**: status-bar output, JSON, a provider-neutral hook, and plugin extension points.
+
+## Get Started in Three Steps
+
+Requires Python 3.13+:
+
+```sh
+uv tool install 'ring-cli[tui]'
+ring --watch
+ring install-hooks
+```
+
+1. `ring --watch` opens the interactive board. Select a session and press `Enter` to return to its terminal.
+2. `ring install-hooks` installs Claude Code and Codex hooks for precise 🔴 waiting states and system notifications.
+3. Restart agent sessions after installing hooks. RiNG can then notify you even while its board is closed.
+
+Use `pipx install 'ring-cli[tui]'` if you prefer pipx. Run `ring` for a one-shot snapshot.
+
+## Common Operations
+
+| Operation | Purpose |
+|-----------|---------|
+| `ring` | Print a snapshot of every current session |
+| `ring --watch` | Open the continuously updating interactive TUI |
+| `Enter` / `Space` | Return to the selected session's terminal |
+| `p` | Reply to the selected session's permission request in place |
+| `n` | Name the selected session |
+| `ring doctor` | Check hooks, notifications, and terminal focus support |
+| `ring --format oneline` | Produce a summary for tmux, SwiftBar, or waybar |
+
+Zero-config mode works without hooks. Precise 🔴 waiting states, pending details, and immediate notifications require hooks. Restart Claude Code or Codex sessions after installing or updating them.
+
+## Learn More
+
+- [Full guide](https://lee-w.github.io/ring/guide/): commands, TUI controls, hooks, notifications, configuration, extensions, and privacy
+- [Session states](https://lee-w.github.io/ring/session-states/): how RiNG derives 🔴/🟢/🟡/⚫
+- [Contributing guide](CONTRIBUTING.md): development setup, tests, and PR checklist
+
+RiNG supports macOS and Linux; Windows is not yet supported. By default it only reads local agent data and writes `~/.config/ring/`. Network access occurs only for ntfy or webhook notifiers you configure.
+
+## License
+
+MIT

{ring_cli-0.13.0 → ring_cli-0.14.1}/pyproject.toml

@@ -2,7 +2,7 @@
 # import 的 module（見 [tool.uv.build-backend] module-name）與 CLI 指令仍是 `ring`。
 [project]
 name = "ring-cli"
-version = "0.13.0"
+version = "0.14.1"
 description = "RiNG — Realtime Instance Notification Grid for active agent CLI sessions."
 readme = "README.en.md"
 requires-python = ">=3.13"
@@ -35,6 +35,7 @@ dependencies = ["rich>=13"]
 [project.urls]
 Homepage = "https://github.com/Lee-W/ring"
 Repository = "https://github.com/Lee-W/ring"
+Documentation = "https://lee-w.github.io/ring/"
 
 [project.optional-dependencies]
 # live TUI 進階版用 Textual（建在 Rich 之上）。
@@ -58,6 +59,7 @@ test = [
   "textual>=0.80",
 ]
 linters = ["ruff>=0.15.1", "mypy>=1.19.1", "prek>=0.3.3", "commitizen>=4.13.9"]
+docs = ["mkdocs-material>=9,<10", "mkdocs-static-i18n>=1.3,<2"]
 
 [build-system]
 requires = ["uv_build >= 0.10.3, <0.12.0"]
@@ -112,14 +114,20 @@ ci.env = { SKIP = "no-commit-to-branch" }
 setup-pre-commit.help = "Install pre-commit hooks"
 setup-pre-commit.cmd = "prek install"
 
-i18n-extract.help = "從原始碼抽出可翻譯字串到 .pot（改字串後重抽。不要用 pybabel update：會塞空 msgstr 進 .po，弄壞 i18n 測試。新字串請手動把已翻譯條目加進各 .po）"
-i18n-extract.cmd = "pybabel extract -F babel.cfg -o src/ring/locale/ring.pot src/ring"
+"i18n:extract".help = "從原始碼抽出可翻譯字串到 .pot（改字串後重抽。不要用 pybabel update：會塞空 msgstr 進 .po，弄壞 i18n 測試。新字串請手動把已翻譯條目加進各 .po）"
+"i18n:extract".cmd = "pybabel extract -F babel.cfg -o src/ring/locale/ring.pot src/ring"
 
-i18n-check.help = "列出原始碼有、但某語言 .po 還沒翻譯的字串（純資訊，不失敗）。先跑 i18n-extract"
-i18n-check.cmd = "python scripts/i18n_check.py"
+"i18n:check".help = "列出原始碼有、但某語言 .po 還沒翻譯的字串（純資訊，不失敗）。先跑 i18n:extract"
+"i18n:check".cmd = "python scripts/i18n_check.py"
 
-i18n-compile.help = "把各語言的 .po 編成 .mo（改 .po 後要重編並 commit）"
-i18n-compile.cmd = "pybabel compile -d src/ring/locale -D ring"
+"i18n:compile".help = "把各語言的 .po 編成 .mo（改 .po 後要重編並 commit）"
+"i18n:compile".cmd = "pybabel compile -d src/ring/locale -D ring"
+
+"docs:serve".help = "Serve the docs site locally with live reload"
+"docs:serve".cmd = "mkdocs serve"
+
+"docs:build".help = "Build the docs site into site/"
+"docs:build".cmd = "mkdocs build --strict"
 
 [tool.commitizen]
 name = "cz_conventional_commits"

{ring_cli-0.13.0 → ring_cli-0.14.1}/src/ring/cli.py

@@ -25,6 +25,7 @@ from ring.commands.doctor import run_doctor
 from ring.commands.focus import run_focus
 from ring.commands.gc import run_gc
 from ring.commands.hook import run_hook_command, run_install_hooks, run_remove_hooks
+from ring.commands.quiet import run_quiet
 from ring.commands.stats import run_stats
 from ring.config import CONFIG_PATH as CONFIG_PATH
 from ring.config import Config as Config
@@ -34,6 +35,7 @@ from ring.config import set_value as set_value
 from ring.i18n import gettext as _
 from ring.i18n import ngettext, set_lang
 from ring.labels import load_labels
+from ring.notify_queue import flush_if_due
 from ring.plugins import load_plugins
 from ring.registry import Session, Status, running_agent_pids
 from ring.sources import discover_sessions
@@ -399,16 +401,32 @@ def run_config(args: list[str]) -> int:
     return 2
 
 
+def _watch_flush_if_due() -> None:
+    """headless watch 輪詢時的懶惰 flush 觸發點（同 hook.py / tui.py 既有呼叫慣例）。
+
+    quiet active 或仍在 debounce 視窗內時，``flush_if_due`` 內部本來就會 skip（跟
+    ``test_run_hook_does_not_flush_while_quiet_active`` 同機制），這裡不需另外判斷。
+    失敗安靜吞掉，不影響看板本身。
+    """
+    try:
+        flush_if_due()
+    except Exception:
+        pass
+
+
 def watch(interval: float, count: int, show_all: bool, show_legend: bool) -> int:
     # 系統通知由 ``ring hook`` 在 session 轉 🔴 等你的當下就地發出（見 hook._ring_waiting_now）；
     # watch 只負責顯示看板，不再輪詢發通知——這樣關掉看板也照樣 ring 你。
     # 例外：codex 核可等待是讀取側的靜默逾時判定，沒有 hook 事件可發通知，由 TUI 的
     # 提醒排程器代發（tui._ring_on_waiting_alerts）；headless watch 仍不發，是已知限制。
+    # debounce/quiet 合流 queue 的懶惰 flush：headless watch 沒有 hook 事件也沒有 TUI 輪詢
+    # 可以觸發，每輪自己補上一次，否則純 headless 使用者開了 quiet/debounce 通知會無限期卡住。
     frames = 0
     footer_text = _("每 {interval}s 刷新 · Ctrl-C 離場", interval=int(interval))
     if not HAVE_RICH:
         try:
             while True:
+                _watch_flush_if_due()
                 sys.stdout.write("\033[2J\033[H")
                 sessions = board(show_all)
                 print(_render_plain(sessions, show_legend, show_tool_column(sessions)))
@@ -425,6 +443,7 @@ def watch(interval: float, count: int, show_all: bool, show_legend: bool) -> int
     try:
         with Live(console=console, screen=True, auto_refresh=False) as live:
             while True:
+                _watch_flush_if_due()
                 sessions = board(show_all)
                 body = _rich_renderable(sessions, show_legend, show_tool_column(sessions))
                 live.update(Group(body, Text(f"\n{footer_text}", style=_MUTED)), refresh=True)
@@ -457,6 +476,10 @@ commands:
   config                       顯示設定檔位置與目前生效的設定
   config get KEY               讀單一設定的目前值
   config set KEY VALUE         寫入單一設定（會重寫設定檔，不保留註解）
+  quiet                        顯示 quiet（暫時全域靜音）現況
+  quiet on                     開啟 quiet（手動解除前一直靜音）
+  quiet off                    解除 quiet（立即補發合流的彙總通知）
+  quiet DURATION               開啟 quiet 一段時間（例如 30m、1h），到期自動解除
   focus SESSION_ID             聚焦指定 session；TUI 在跑時會回到 RiNG 並選中該列
   gc [--dry-run]               清理 RiNG 自己的 stale 狀態檔
   doctor                       顯示環境診斷（唯讀）——hook、通知、focuser、維護提示
@@ -493,6 +516,17 @@ def _subcommand_help(name: str) -> str:
 不帶參數：顯示設定檔位置（~/.config/ring/config.toml）與目前生效的所有設定。
   get KEY        印出單一設定的目前值（colors 子鍵用 colors.<name>）。
   set KEY VALUE  寫入單一設定。注意：會重寫整個設定檔，原有註解不會保留。
+"""
+        ),
+        "quiet": _(
+            """usage: ring quiet [on | off | DURATION]
+
+暫時全域靜音：靜音期間所有轉 🔴 等你的通知都先進 queue，解除時懶惰補發一則彙總。
+
+不帶參數：顯示目前 quiet 現況（開/關、剩餘時間）。
+  on          開啟 quiet，手動解除前一直靜音。
+  off         解除 quiet，並立即補發合流的彙總通知。
+  DURATION    開啟 quiet 一段時間（例如 30m、1h），到期自動解除。
 """
         ),
         "focus": _(
@@ -569,6 +603,7 @@ def main(argv: list[str] | None = None) -> int:
             "digest",
             "stats",
             "completion",
+            "quiet",
         }
         and any(arg in {"-h", "--help"} for arg in raw[1:])
     ):
@@ -583,6 +618,8 @@ def main(argv: list[str] | None = None) -> int:
         return run_remove_hooks(raw[1:])
     if raw and raw[0] == "config":
         return run_config(raw[1:])
+    if raw and raw[0] == "quiet":
+        return run_quiet(raw[1:])
     if raw and raw[0] == "gc":
         return run_gc(raw[1:])
     if raw and raw[0] == "doctor":

ring_cli-0.14.1/src/ring/commands/quiet.py

@@ -0,0 +1,54 @@
+"""``ring quiet`` command handler：暫時全域靜音（跟 debounce 共用同一份 queue／flush 機制）。"""
+
+from __future__ import annotations
+
+import sys
+import time
+
+from ring.commands._args import strip_lang
+from ring.gc import parse_duration
+from ring.i18n import gettext as _
+from ring.notify_queue import clear_quiet, flush_if_due, format_remaining, quiet_active, quiet_remaining, set_quiet
+
+
+def _print_status(now: float) -> None:
+    if not quiet_active(now):
+        print(_("🔈 quiet：目前關閉"))
+        return
+    remaining = quiet_remaining(now)
+    if remaining is None:
+        print(_("🔇 quiet：開啟中（手動解除前一直靜音）"))
+    else:
+        print(_("🔇 quiet：開啟中，剩 {remaining}", remaining=format_remaining(remaining)))
+
+
+def run_quiet(args: list[str]) -> int:
+    """不帶參數→顯示現況；``on``→無限靜音；``off``→解除並立即 flush；``<duration>``→限時靜音。"""
+    args = strip_lang(args)
+    now = time.time()
+
+    if not args:
+        _print_status(now)
+        return 0
+
+    action = args[0]
+    if action == "on":
+        set_quiet(None)
+        print(_("🔇 quiet 已開啟（手動解除前一直靜音）"))
+        return 0
+
+    if action == "off":
+        clear_quiet()
+        flush_if_due(force=True)
+        print(_("🔈 quiet 已解除"))
+        return 0
+
+    try:
+        seconds = parse_duration(action)
+    except ValueError:
+        print(_("無效的 duration：{value}（例如 30m、1h）", value=action), file=sys.stderr)
+        return 2
+
+    set_quiet(now + seconds)
+    print(_("🔇 quiet 已開啟，{duration} 後自動解除", duration=action))
+    return 0

{ring_cli-0.13.0 → ring_cli-0.14.1}/src/ring/config.py

@@ -8,7 +8,7 @@
     legend = true
     active_window_seconds = 21600     # 只看最近這段時間動過的 session（預設 6h）
     working_threshold_seconds = 90    # 多久沒動就從 🟢 工作中 變 🟡 閒置
-    waiting_window_seconds = 1800     # 跑完停著升等你的時間窗上限（預設 30 分）
+    waiting_window_seconds = 1800     # 零設定掃描中，近期回合結束列收斂成 IDLE 的時間窗
     codex_permission_wait_seconds = 10  # Codex 裸 PermissionRequest 後 hook 靜默超過這秒數
                                       #   → 看板判定真的停下來等核可（🔴 等你）；0 = 關閉
     detect_stop_questions = true      # Stop 事件時，若最後一則 assistant 訊息「結尾」是純文字
@@ -27,6 +27,10 @@
     notify_repeat_max = 3             # 重複提醒上限；0 = 不限
     waiting_cooldown_seconds = 180    # session 離開 WAITING 又轉回時，距上次提醒未滿這段時間就
                                       #   不再當「新轉入」立即提醒（防翻轉轟炸）；0 = 關閉（現行為）
+    notify_debounce_seconds = 0       # 多個 session 同時轉 🔴 等你時的通知合流窗口（秒）：窗口內
+                                      #   第一批立即發（leading edge），之後的合併成一則彙總，由下個
+                                      #   hook 事件 / TUI 輪詢 / quiet 解除懶惰 flush；0 = 關閉（現行為，
+                                      #   向後相容，每次轉入都各自發）
     notify_ntfy_url = "https://ntfy.sh/my-topic"   # 設了才啟用 ntfy 後端（推到手機）
     notify_webhook_url = "https://example.com/hook"  # 設了才啟用 webhook 後端（JSON POST）
     notify_also = ["ntfy"]            # 主後端之外「加發」的後端（例如桌面通知＋手機各一份）
@@ -40,12 +44,15 @@
 
 from __future__ import annotations
 
+import sys
 import tomllib
 from collections.abc import Callable
-from dataclasses import dataclass, field
+from dataclasses import dataclass, field, fields
 from functools import lru_cache
 from pathlib import Path
 
+from ring.i18n import gettext as _
+
 CONFIG_PATH = Path.home() / ".config" / "ring" / "config.toml"
 
 # Rich 樣式字串。深淺底都看得到（避開 dim / ANSI blue）。config 的 [colors] 可逐項覆寫。
@@ -68,7 +75,7 @@ class Config:
     legend: bool = True
     active_window_seconds: int = 6 * 60 * 60
     working_threshold_seconds: int = 90
-    waiting_window_seconds: int = 1800  # 跑完停著升等你的時間窗上限（預設 30 分）
+    waiting_window_seconds: int = 1800  # 零設定掃描中，近期回合結束列收斂成 IDLE 的時間窗
     # Codex 的 hook 沒有「使用者已核可」事件也沒有心跳（0.144.4 實證）：policy 自動放行時
     # 下一個事件幾秒內就到；真的停下來等人時 hook 通道完全靜默。所以「最後一個事件是
     # PermissionRequest 且已靜默超過這個門檻」就判定在等核可。0 = 關閉這個判定。
@@ -88,6 +95,7 @@ class Config:
     notify_repeat_seconds: tuple[int, ...] = (30, 120, 300)
     notify_repeat_max: int = 3  # 0 = 不限
     waiting_cooldown_seconds: int = 180  # 離開 WAITING 又轉回時的提醒冷卻期；0 = 關閉（現行為）
+    notify_debounce_seconds: int = 0  # 跨 session 通知合流窗口（秒）；0 = 關閉（現行為，向後相容）
     notify_ntfy_url: str = ""  # 完整 ntfy topic URL；空＝ntfy 後端不可用
     notify_webhook_url: str = ""  # webhook URL；空＝webhook 後端不可用
     notify_also: tuple[str, ...] = ()  # 主後端之外加發的後端名（如 ["ntfy"]）
@@ -97,6 +105,21 @@ class Config:
     colors: dict[str, str] = field(default_factory=lambda: dict(_DEFAULT_COLORS))
 
 
+# config.toml 頂層合法鍵（含巢狀 table 名，如 "colors"）——都是 Config dataclass 的欄位名。
+_KNOWN_KEYS = {f.name for f in fields(Config)}
+
+
+def _warn_unknown_keys(raw: dict[str, object], path: Path) -> None:
+    """未知的頂層鍵（多半是打錯字）→ 印一次警告到 stderr；只警告，絕不 raise、不影響載入。"""
+    unknown = sorted(k for k in raw if k not in _KNOWN_KEYS)
+    if not unknown:
+        return
+    print(
+        _("⚠️ {path} 有未知的設定鍵（可能打錯字，已忽略）：{keys}", path=path, keys=", ".join(unknown)),
+        file=sys.stderr,
+    )
+
+
 def _as_int(v: object, default: int) -> int:
     return v if isinstance(v, int) and not isinstance(v, bool) else default
 
@@ -137,6 +160,7 @@ def load(path: Path | None = None) -> Config:
         raw = tomllib.loads(p.read_text())
     except (OSError, tomllib.TOMLDecodeError):
         return Config()
+    _warn_unknown_keys(raw, p)
     d = Config()
     lang = raw.get("lang")
     # 任意非空字串都接受（後端名稱由 notify 層的可插拔 registry 決定）；認不得的名稱
@@ -163,6 +187,7 @@ def load(path: Path | None = None) -> Config:
         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_debounce_seconds=max(0, _as_int(raw.get("notify_debounce_seconds"), d.notify_debounce_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 ""),
@@ -237,6 +262,7 @@ _SETTERS: dict[str, Callable[[str], object]] = {
     "notify_repeat_seconds": _coerce_int_list,
     "notify_repeat_max": _coerce_int,
     "waiting_cooldown_seconds": _coerce_int,
+    "notify_debounce_seconds": _coerce_int,
     "notify_ntfy_url": str,
     "notify_webhook_url": str,
     "notify_also": _coerce_str_list,

{ring_cli-0.13.0 → ring_cli-0.14.1}/src/ring/focus/__init__.py

@@ -15,6 +15,7 @@ from ring.focus.linux_wm import focuser as _linux_wm
 from ring.focus.neovim import focuser as _neovim
 from ring.focus.terminal import focuser as _terminal
 from ring.focus.tmux import focuser as _tmux
+from ring.focus.trace import log_jump
 from ring.i18n import gettext as _
 from ring.registry import Session, Status
 
@@ -53,33 +54,53 @@ def focusers() -> list[Focuser]:
 
 
 def jump(session: Session) -> tuple[bool, str]:
-    """依序問每個 focuser，誰先接手就用誰。回傳 (成功?, 訊息)。"""
+    """依序問每個 focuser，誰先接手就用誰。回傳 (成功?, 訊息)。
+
+    每次跳轉（不論成敗）都記一行到 focus.jsonl，供事後歸因間歇性的跳不過去（見 ``trace``）。
+    """
     if session.status is Status.ENDED:
         return False, _("已離場的 session 無法跳轉")
     failures: list[str] = []
     preparations: list[str] = []
+    attempts: list[tuple[str, str]] = []
+
+    def _done(ok: bool, msg: str) -> tuple[bool, str]:
+        log_jump(
+            session_id=session.session_id,
+            provider=session.provider,
+            tty=session.tty or "",
+            tmux_target=session.tmux_target or "",
+            attempts=attempts,
+            ok=ok,
+            msg=msg,
+        )
+        return ok, msg
+
     for focuser in _FOCUSERS:
         result = focuser.try_focus(session)
         if result is None:
+            attempts.append((focuser.name, "skip"))
             continue
         ok, msg = result
         if ok:
+            attempts.append((focuser.name, "ok"))
             if getattr(focuser, "continue_after_success", False):
                 preparations.append(msg)
                 continue
             if preparations:
-                return True, "; ".join([*preparations, msg])
-            return True, msg
+                return _done(True, "; ".join([*preparations, msg]))
+            return _done(True, msg)
+        attempts.append((focuser.name, f"fail: {msg}"))
         failures.append(f"{focuser.name}: {msg}")
     if preparations and failures:
-        return False, "; ".join([*preparations, *failures])
+        return _done(False, "; ".join([*preparations, *failures]))
     if preparations:
-        return True, "; ".join(preparations)
+        return _done(True, "; ".join(preparations))
     if failures:
-        return False, "; ".join(failures)
+        return _done(False, "; ".join(failures))
     if session.tty:
-        return False, _("找不到這個終端分頁（可能已關閉；刷新後若仍存在，請裝 hook 取得更精準狀態）")
-    return False, _("沒有 focuser 接得住（裝 hook，或一個專案只開一個 session 才測得到 tty）")
+        return _done(False, _("找不到這個終端分頁（可能已關閉；刷新後若仍存在，請裝 hook 取得更精準狀態）"))
+    return _done(False, _("沒有 focuser 接得住（裝 hook，或一個專案只開一個 session 才測得到 tty）"))
 
 
 __all__ = ["Focuser", "focusers", "jump", "register_focuser"]

{ring_cli-0.13.0 → ring_cli-0.14.1}/src/ring/focus/applescript.py

@@ -8,6 +8,7 @@ from __future__ import annotations
 
 import shutil
 
+from ring.i18n import gettext as _
 from ring.osascript import osascript
 from ring.registry import Session
 
@@ -16,6 +17,9 @@ class AppleScriptTTYFocuser:
     """用 session 的 tty 在某個 macOS 終端 app 裡找到對應分頁並聚焦。
 
     各 app 提供自己的 AppleScript（用 ``is running`` 守衛，沒在跑的 app 不會被喚醒）。
+
+    script 的回傳值三選一：``ok``（找到且已在前景）、``notfound``（不歸這個 app 管）、
+    ``unraised``（找到分頁但視窗沒浮到前景——腳本自己驗過才回這個，見 iterm2 模組）。
     """
 
     def __init__(self, app: str, script: str) -> None:
@@ -31,4 +35,8 @@ class AppleScriptTTYFocuser:
             return True, f"{self.name} {tty}"
         if rc == 0 and out == "notfound":
             return None  # 這個 app 沒有這個 tty → 換下一個 focuser
+        if rc == 0 and out == "unraised":
+            # 分頁在，但視窗沒被帶到前景（多半在別的 Space 或全螢幕）。照實回失敗，
+            # 不要讓 TUI 顯示「跳過去了」卻什麼都沒發生。
+            return False, _("{app} 找到分頁了，但視窗沒浮到前景（可能在別的 Space 或全螢幕）", app=self.name)
         return False, err or out or f"returncode={rc}"

ring_cli-0.14.1/src/ring/focus/iterm2.py

@@ -0,0 +1,82 @@
+"""iTerm2 focuser（macOS）：用 tty 找到對應分頁並帶到前景。
+
+跨視窗（不是同一視窗換分頁）跳轉踩過三個坑，腳本的形狀都是為了繞開它們（皆 2026-07-25 實測）：
+
+1. **位置型 specifier 會在迴圈中途失效**。``repeat with w in windows`` 的迴圈變數其實是
+   ``item M of every window`` 這種「按位置」的參照；一旦 windows 的順序在掃描途中變動
+   （剛跳過一次視窗、使用者手動點了別的視窗都會），下一次取值就噴
+   ``Invalid index (-1719)``，跳轉整個失敗——這正是「不同視窗有時抓不到」的主因。
+   對策：掃描包在 ``try`` 裡、順序被動到就重掃；``select`` 之後不再用掃描時的位置，
+   改以 ``current window`` 為根重找一次分頁。
+2. **``select`` 是非同步的**：送出後立刻讀狀態會讀到舊值。所以最後隔 0.1 秒回頭驗
+   ``current session of current window``，最多等 1 秒。驗不到就回 ``unraised``，讓上層
+   照實說「沒帶到前景」（例如視窗在別的 Space），而不是假裝跳成功。
+3. **不能用的兩招**：``set frontmost of w to true``（Terminal.app 那招）在 iTerm2 噴
+   AppleEvent handler failed (-10000)；``set index of w to 1`` 會主動重排 windows，
+   等於自己製造第 1 點的 -1719。
+
+縮到 Dock 的視窗 ``select`` 就叫得回來（實測），``miniaturized`` 那段只是保險。
+"""
+
+from __future__ import annotations
+
+from ring.focus.applescript import AppleScriptTTYFocuser
+
+_SCRIPT = """
+if application "iTerm2" is running then
+  tell application "iTerm2"
+    repeat 3 times
+      try
+        set wIdx to 0
+        set tIdx to 0
+        set sIdx to 0
+        repeat with wi from 1 to (count of windows)
+          repeat with ti from 1 to (count of tabs of window wi)
+            repeat with si from 1 to (count of sessions of tab ti of window wi)
+              if tty of session si of tab ti of window wi is "{tty}" then
+                set wIdx to wi
+                set tIdx to ti
+                set sIdx to si
+                exit repeat
+              end if
+            end repeat
+            if wIdx is not 0 then exit repeat
+          end repeat
+          if wIdx is not 0 then exit repeat
+        end repeat
+        if wIdx is 0 then return "notfound"
+        activate
+        try
+          if miniaturized of window wIdx then set miniaturized of window wIdx to false
+        end try
+        select window wIdx
+        tell current window
+          repeat with ti2 from 1 to (count of tabs)
+            repeat with si2 from 1 to (count of sessions of tab ti2)
+              if tty of session si2 of tab ti2 is "{tty}" then
+                select tab ti2
+                select session si2 of tab ti2
+                exit repeat
+              end if
+            end repeat
+          end repeat
+        end tell
+        repeat 10 times
+          delay 0.1
+          try
+            if tty of current session of current window is "{tty}" then return "ok"
+          end try
+        end repeat
+        return "unraised"
+      on error number errNum
+        if errNum is -128 then error number -128
+        delay 0.2
+      end try
+    end repeat
+    return "unraised"
+  end tell
+end if
+return "notfound"
+"""
+
+focuser = AppleScriptTTYFocuser("iTerm2", _SCRIPT)