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

ring_cli-0.14.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: ring-cli
+Version: 0.14.0
+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.0/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.0}/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.0"
 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.0}/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.0/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.0}/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.0}/src/ring/hook.py

@@ -154,7 +154,18 @@ def run_hook(provider: str = "claude-code") -> int:
     ``agent-hooks`` 時發生：把原始 payload 透傳給 ``agent-hooks callback``，由它同步出 modal、
     收按鈕、把決策寫到 stdout 回給 Claude（這條路下 ``_ring_waiting_now`` 自動短路、不重複發）。
     其餘情況 RiNG 記狀態 + 發通知後 exit 0（你在終端自己回答）。
+
+    每次執行開頭先嘗試懶惰 flush 合流 queue（見 ``notify_queue.flush_if_due``）——沒有常駐
+    daemon，任何 hook 事件（不限於這次自己是不是 waiting 事件）都是「debounce 視窗過期」的
+    天然觸發點，讓 headless（沒開 TUI）也能補發彙總通知。失敗安靜吞掉，不影響本次事件記錄。
     """
+    try:
+        from ring.notify_queue import flush_if_due
+
+        flush_if_due()
+    except Exception:
+        pass
+
     try:
         raw = sys.stdin.read()
     except OSError:

{ring_cli-0.13.0 → ring_cli-0.14.0}/src/ring/hook_protocol.py

@@ -47,8 +47,9 @@ _ALWAYS_STATUS = {
 }
 
 _ACTION_REQUIRED_NOTIFICATION_TYPES = {
-    "permission_prompt",
+    "agent_needs_input",  # 背景 agent 停下來要使用者輸入（claude 2.1.215 binary 實證有此型別）
     "elicitation_dialog",
+    "permission_prompt",
 }
 
 _ACTION_REQUIRED_WAITING_FOR = {
@@ -245,6 +246,9 @@ def _waiting_kind(data: Mapping[str, Any], event: str, status: Status) -> str:
         # 先於 PermissionRequest 判斷：AskUserQuestion 也會以 PermissionRequest 事件
         # 進來（權限判定包著問題），但使用者要回的是「問題」不是「權限」。
         return "question"
+    if notification_type == "agent_needs_input":
+        # 背景 agent 要使用者輸入，性質是「回答」而非權限核可 → ❓ 而非 🔐。
+        return "question"
     if event == "PermissionRequest" or notification_type == "permission_prompt":
         return "permission"
     if waiting_for in {"approval", "permission"}:

{ring_cli-0.13.0 → ring_cli-0.14.0}/src/ring/locale/en/LC_MESSAGES/ring.po

@@ -239,6 +239,9 @@ msgstr "Change with `ring config set KEY VALUE`, or edit the file above; see the
 msgid "未知的鍵：{key}"
 msgstr "unknown key: {key}"
 
+msgid "⚠️ {path} 有未知的設定鍵（可能打錯字，已忽略）：{keys}"
+msgstr "⚠️ {path} has unknown config keys (likely a typo, ignored): {keys}"
+
 msgid "用法：ring config get KEY"
 msgstr "usage: ring config get KEY"
 
@@ -265,6 +268,10 @@ msgid ""
 "  config                       顯示設定檔位置與目前生效的設定\n"
 "  config get KEY               讀單一設定的目前值\n"
 "  config set KEY VALUE         寫入單一設定（會重寫設定檔，不保留註解）\n"
+"  quiet                        顯示 quiet（暫時全域靜音）現況\n"
+"  quiet on                     開啟 quiet（手動解除前一直靜音）\n"
+"  quiet off                    解除 quiet（立即補發合流的彙總通知）\n"
+"  quiet DURATION               開啟 quiet 一段時間（例如 30m、1h），到期自動解除\n"
 "  focus SESSION_ID             聚焦指定 session；TUI 在跑時會回到 RiNG 並選中該列\n"
 "  gc [--dry-run]               清理 RiNG 自己的 stale 狀態檔\n"
 "  doctor                       顯示環境診斷（唯讀）——hook、通知、focuser、維護提示\n"
@@ -281,6 +288,10 @@ msgstr ""
 "  config                       show config file path and current settings\n"
 "  config get KEY               read one setting's current value\n"
 "  config set KEY VALUE         write one setting (rewrites config file, comments lost)\n"
+"  quiet                        show quiet (temporary global mute) status\n"
+"  quiet on                     turn quiet on (stays muted until manually cleared)\n"
+"  quiet off                    turn quiet off (flushes any coalesced summary right away)\n"
+"  quiet DURATION               turn quiet on for a while (e.g. 30m, 1h), auto-clears on expiry\n"
 "  focus SESSION_ID             focus a session; if TUI is running, returns to RiNG and selects the row\n"
 "  gc [--dry-run]               clean RiNG's own stale state files\n"
 "  doctor                       show environment diagnosis (read-only) — hooks, notify, focuser, maintenance hints\n"
@@ -329,6 +340,26 @@ msgstr ""
 "  get KEY        print the current value of one setting (use colors.<name> for color sub-keys).\n"
 "  set KEY VALUE  write one setting. Note: rewrites the entire config file; existing comments are lost.\n"
 
+msgid ""
+"usage: ring quiet [on | off | DURATION]\n"
+"\n"
+"暫時全域靜音：靜音期間所有轉 🔴 等你的通知都先進 queue，解除時懶惰補發一則彙總。\n"
+"\n"
+"不帶參數：顯示目前 quiet 現況（開/關、剩餘時間）。\n"
+"  on          開啟 quiet，手動解除前一直靜音。\n"
+"  off         解除 quiet，並立即補發合流的彙總通知。\n"
+"  DURATION    開啟 quiet 一段時間（例如 30m、1h），到期自動解除。\n"
+msgstr ""
+"usage: ring quiet [on | off | DURATION]\n"
+"\n"
+"Temporary global mute: while quiet, every 🔴 waiting-for-you notification is queued first,\n"
+"and a coalesced summary is flushed lazily once quiet is cleared.\n"
+"\n"
+"No args: show the current quiet status (on/off, remaining time).\n"
+"  on          turn quiet on; stays muted until manually cleared.\n"
+"  off         turn quiet off, and flush any coalesced summary right away.\n"
+"  DURATION    turn quiet on for a while (e.g. 30m, 1h); auto-clears on expiry.\n"
+
 msgid ""
 "usage: ring focus SESSION_ID\n"
 "\n"
@@ -695,3 +726,55 @@ msgstr "{project}: the dialog was gone and the digit landed in the input box —
 
 msgid "{project}：已送出但拿不到畫面驗證，請跳過去確認"
 msgstr "{project}: key sent but the screen could not be re-read to verify — jump over to check"
+
+# ── notify_queue.py：debounce queue ／ quiet mode ──
+msgid "{s} 秒"
+msgstr "{s}s"
+
+msgid "{m} 分"
+msgstr "{m}m"
+
+msgid "{h} 小時"
+msgstr "{h}h"
+
+# ── notify/__init__.py：合流彙總通知 ──
+msgid "另有 {n} 個 session 在等你"
+msgid_plural "另有 {n} 個 session 在等你"
+msgstr[0] "{n} more session is waiting for you"
+msgstr[1] "{n} more sessions are waiting for you"
+
+# ── notify/base.py：彙總通知標題 ──
+msgid "RiNG · 還有人在等你"
+msgstr "RiNG · someone is waiting for you"
+
+# ── tui.py：quiet ／ queue header badge ──
+msgid "🔇 QUIET"
+msgstr "🔇 QUIET"
+
+msgid "🔇 QUIET · 剩 {remaining}"
+msgstr "🔇 QUIET · {remaining} left"
+
+msgid "queue: {n}"
+msgstr "queue: {n}"
+
+# ── commands/quiet.py：ring quiet CLI ──
+msgid "🔈 quiet：目前關閉"
+msgstr "🔈 quiet: off"
+
+msgid "🔇 quiet：開啟中（手動解除前一直靜音）"
+msgstr "🔇 quiet: on (stays muted until manually cleared)"
+
+msgid "🔇 quiet：開啟中，剩 {remaining}"
+msgstr "🔇 quiet: on, {remaining} left"
+
+msgid "🔇 quiet 已開啟（手動解除前一直靜音）"
+msgstr "🔇 quiet turned on (stays muted until manually cleared)"
+
+msgid "🔈 quiet 已解除"
+msgstr "🔈 quiet turned off"
+
+msgid "無效的 duration：{value}（例如 30m、1h）"
+msgstr "invalid duration: {value} (e.g. 30m, 1h)"
+
+msgid "🔇 quiet 已開啟，{duration} 後自動解除"
+msgstr "🔇 quiet turned on, auto-clears after {duration}"