ring-cli 0.4.0__tar.gz → 0.6.0__tar.gz

{ring_cli-0.4.0 → ring_cli-0.6.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: ring-cli
-Version: 0.4.0
+Version: 0.6.0
 Summary: RiNG — Realtime Instance Notification Grid for active agent CLI sessions.
 Keywords: claude-code,codex,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 :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: MacOS
@@ -57,9 +57,12 @@ RiNG puts them on one board, with sessions waiting for you sorted first.
 
 - **One board for every session**: Claude Code / Codex are built in; other tools can feed `ring hook`.
 - **Waiting first**: sessions that need your response are highlighted and sorted above the rest.
-- **Jump back to the terminal**: in the TUI, select a session and press `Enter` / `Space` to focus tmux, iTerm2, or Terminal.app.
+- **Jump back to the terminal**: in the TUI, select a session and press `Enter` / `Space` to focus tmux, iTerm2, Terminal.app (macOS), or a Linux X11 window (`wmctrl`).
 - **Notifies you without the board open**: with hooks installed, the moment a session turns 🔴 waiting it beeps and fires a system notification — even with no RiNG board running. With `terminal-notifier`, clicking the notification jumps back.
-- **Name your sessions**: press `n` in the TUI to add a local label such as `maigo · auth refactor`.
+- **Name your sessions**: press `n` in the TUI to name a session, e.g. "auth refactor"; once named, the board and notifications show the name instead of the workspace directory.
+- **See what it is waiting for**: in hook mode, a 🔴 waiting session carries the concrete pending item (the command to run, the question asked) — shown in the TUI and in the notification body.
+- **Fits your status bar**: `ring --format oneline` prints a `🔴2 🟢1 🟡3` one-liner for tmux / SwiftBar / waybar; `--format json` feeds scripts.
+- **Rings your phone too**: built-in ntfy / webhook notifiers push 🔴 waiting to your phone when you are away from the desk.
 - **Local and extensible**: RiNG only reads local Claude Code / Codex data and writes `~/.config/ring/`; session sources, focusers, and notifiers are pluggable.
 
 ## Run
@@ -119,12 +122,39 @@ Hooks only apply to new sessions, so restart Claude Code / Codex sessions after
 | `ring doctor` | Read-only environment diagnosis |
 | `ring gc --dry-run` | Preview RiNG-owned stale state cleanup |
 | `ring gc` | Clean RiNG-owned stale state files |
+| `ring --format json` | Machine-readable board snapshot (for jq / scripts) |
+| `ring --format oneline` | `🔴2 🟢1 🟡3` one-liner (for status bars) |
+| `ring stats` | Waiting stats: how long agents kept 🔴 waiting in the last 7 days |
+| `ring completion zsh` | Print a shell completion script (zsh / bash) |
+
+### Status Bar Integration (`--format`)
+
+```sh
+ring --format oneline        # 🔴2 🟢1 🟡3 (empty output when no sessions, so the segment collapses)
+ring --format json | jq '.counts.waiting'
+```
+
+- **tmux**: `set -g status-right '#(ring --format oneline) …'` (with `status-interval 5`).
+- **SwiftBar / xbar / waybar**: wrap `ring --format oneline` or consume the JSON.
+- JSON keys are a stable interface (additive only), safe to script against.
+
+### Shell Completion (`ring completion`)
+
+```sh
+# ~/.zshrc
+eval "$(ring completion zsh)"
+# ~/.bashrc
+eval "$(ring completion bash)"
+```
+
+Completes subcommands, flags, and `config set` keys.
 
 ## Watch Mode
 
 - With **Textual** (`[tui]` extra) in a real terminal: interactive TUI.
   Use `↑/↓` to select, `Enter` / `Space` to jump, `n` to name a session, `a` to toggle ended sessions, `r` to refresh, and `q` to quit.
   If you have vim muscle memory like I do, `j/k` move up/down and `g/G` jump to the first/last row.
+  When the selected row is 🔴 waiting, a line under the table shows **what it is concretely waiting for** (the command to run, the question asked; hook mode only).
 - Otherwise: Rich polling; without Rich, plain text.
 
 ### Jump To A Session
@@ -133,6 +163,7 @@ Select a session and press `Enter`. RiNG focuses the terminal where that session
 
 - **tmux**: switches directly to the pane via `switch-client`.
 - **iTerm2 / Terminal.app** on macOS: uses the session `tty` and AppleScript to focus the matching tab. The first run may ask for macOS Automation permission.
+- **Linux X11 window** (`wmctrl`, best-effort fallback): for Linux without tmux — walks from the `tty` up to the terminal window that owns it and raises it via `wmctrl`. **Limits**: X11 only (usually a no-op on Wayland), raises the whole window but cannot pick the tab, and gnome-terminal's client/server model may not match. Requires `apt install wmctrl`.
 
 TTY matching is most accurate in hook mode. Without hooks, Codex falls back to zero-config matching:
 one live Codex session per cwd can jump correctly; multiple live Codex sessions in the same cwd are shown conservatively to avoid focusing the wrong tab.
@@ -154,6 +185,20 @@ Without it, RiNG falls back to macOS text notifications without click-to-focus.
 Notification sound, repeat timing, and backend selection are configurable; notification backends
 are also pluggable via the `Notifier` extension point.
 
+#### Push To Your Phone (ntfy / webhook)
+
+Desktop notifications do not help when you are away from the desk. Point RiNG at an
+[ntfy](https://ntfy.sh) topic to push to your phone:
+
+```toml
+# ~/.config/ring/config.toml
+notify_ntfy_url = "https://ntfy.sh/my-ring-topic"  # subscribe to the same topic in the ntfy app
+notify_also = ["ntfy"]                             # desktop notification as usual, plus a copy to the phone
+```
+
+`notify_backend = "ntfy"` pushes to the phone only. For Slack / your own bot / IFTTT, set
+`notify_webhook_url` to use the generic webhook backend (JSON POST with a stable, additive-only payload).
+
 ### Cleaning RiNG State Files (`ring gc`)
 
 When RiNG receives `SessionEnd`, it removes its own hook registry entry. If an agent crashes or the
@@ -170,6 +215,19 @@ ring gc --all-ended      # delete every registry file currently classified as en
 `ring gc` only cleans state files RiNG owns under `~/.config/ring/`. It does not touch Claude Code /
 Codex transcripts or state. `ring doctor` remains read-only and never deletes files.
 
+### Waiting Stats (`ring stats`)
+
+In hook mode, RiNG logs session **state transitions** to `~/.config/ring/events.jsonl`
+(transitions only, tiny, self-trimming past a size cap). `ring stats` then tells you, per project,
+how many times an agent 🔴 waited on you and for how long (avg / max / total).
+
+```sh
+ring stats               # last 7 days
+ring stats --since 12h   # custom window
+```
+
+Like precise notifications, 🔴 waiting is invisible to zero-config, so stats also needs hook mode.
+
 ## Session Sources
 
 RiNG collects sessions from registered sources. Built-ins:
@@ -310,7 +368,11 @@ 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
-focusers = ["tmux", "iTerm2", "Terminal"]
+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"]
+focusers = ["tmux", "iTerm2", "Terminal", "linux-wm"]
+plugins = []                     # external plugin modules imported at startup (see Extending)
 
 [colors]
 waiting = "bold red"
@@ -329,16 +391,36 @@ RiNG is not tied to a specific tool or terminal.
 | Extension Point | Purpose | Built-ins |
 |-----------------|---------|-----------|
 | `SessionSource` | find sessions | Claude Code, Codex, hook registry |
-| `Focuser` | jump to terminals | tmux, iTerm2, Terminal.app |
-| `Notifier` | notify when sessions are waiting | terminal-notifier, osascript, notify-send |
+| `Focuser` | jump to terminals | tmux, iTerm2, Terminal.app, Linux X11 (wmctrl) |
+| `Notifier` | notify when sessions are waiting | terminal-notifier, osascript, notify-send, ntfy, webhook |
 
 Each backend is a small module under `ring/sources/`, `ring/focus/`, or `ring/notify/`, registered via `register_*()`.
 
+### Loading Your Plugin Into An Installed `ring`
+
+`register_*()` only counts if something runs it. The installed `ring` command loads plugins from
+two places at startup:
+
+1. **Entry point** (for published packages) — declare it in your package's `pyproject.toml`,
+   pointing at a module or callable (a module registers on import; a callable is invoked once
+   with no arguments):
+
+   ```toml
+   [project.entry-points."ring.plugins"]
+   mytool = "ring_mytool.plugin"
+   ```
+
+2. **Config** (for local scripts) — add `plugins = ["my_module"]` to `~/.config/ring/config.toml`;
+   the module must be importable (site-packages or `PYTHONPATH`).
+
+A broken plugin prints one warning line to stderr and never blocks the board.
+
 ## Platform & Privacy
 
 - **Platform**: macOS / Linux. Windows is not supported.
-- **Privacy**: entirely local. RiNG only reads local `~/.claude/` and `~/.codex/` data and writes
-  `~/.config/ring/`. No network, uploads, or telemetry.
+- **Privacy**: local by default. RiNG only reads local `~/.claude/` and `~/.codex/` data and writes
+  `~/.config/ring/`. No telemetry. The only network calls are the optional ntfy / webhook notifiers,
+  and only to URLs you configure yourself.
 
 ## Name
 

{ring_cli-0.4.0 → ring_cli-0.6.0}/README.en.md

@@ -32,9 +32,12 @@ RiNG puts them on one board, with sessions waiting for you sorted first.
 
 - **One board for every session**: Claude Code / Codex are built in; other tools can feed `ring hook`.
 - **Waiting first**: sessions that need your response are highlighted and sorted above the rest.
-- **Jump back to the terminal**: in the TUI, select a session and press `Enter` / `Space` to focus tmux, iTerm2, or Terminal.app.
+- **Jump back to the terminal**: in the TUI, select a session and press `Enter` / `Space` to focus tmux, iTerm2, Terminal.app (macOS), or a Linux X11 window (`wmctrl`).
 - **Notifies you without the board open**: with hooks installed, the moment a session turns 🔴 waiting it beeps and fires a system notification — even with no RiNG board running. With `terminal-notifier`, clicking the notification jumps back.
-- **Name your sessions**: press `n` in the TUI to add a local label such as `maigo · auth refactor`.
+- **Name your sessions**: press `n` in the TUI to name a session, e.g. "auth refactor"; once named, the board and notifications show the name instead of the workspace directory.
+- **See what it is waiting for**: in hook mode, a 🔴 waiting session carries the concrete pending item (the command to run, the question asked) — shown in the TUI and in the notification body.
+- **Fits your status bar**: `ring --format oneline` prints a `🔴2 🟢1 🟡3` one-liner for tmux / SwiftBar / waybar; `--format json` feeds scripts.
+- **Rings your phone too**: built-in ntfy / webhook notifiers push 🔴 waiting to your phone when you are away from the desk.
 - **Local and extensible**: RiNG only reads local Claude Code / Codex data and writes `~/.config/ring/`; session sources, focusers, and notifiers are pluggable.
 
 ## Run
@@ -94,12 +97,39 @@ Hooks only apply to new sessions, so restart Claude Code / Codex sessions after
 | `ring doctor` | Read-only environment diagnosis |
 | `ring gc --dry-run` | Preview RiNG-owned stale state cleanup |
 | `ring gc` | Clean RiNG-owned stale state files |
+| `ring --format json` | Machine-readable board snapshot (for jq / scripts) |
+| `ring --format oneline` | `🔴2 🟢1 🟡3` one-liner (for status bars) |
+| `ring stats` | Waiting stats: how long agents kept 🔴 waiting in the last 7 days |
+| `ring completion zsh` | Print a shell completion script (zsh / bash) |
+
+### Status Bar Integration (`--format`)
+
+```sh
+ring --format oneline        # 🔴2 🟢1 🟡3 (empty output when no sessions, so the segment collapses)
+ring --format json | jq '.counts.waiting'
+```
+
+- **tmux**: `set -g status-right '#(ring --format oneline) …'` (with `status-interval 5`).
+- **SwiftBar / xbar / waybar**: wrap `ring --format oneline` or consume the JSON.
+- JSON keys are a stable interface (additive only), safe to script against.
+
+### Shell Completion (`ring completion`)
+
+```sh
+# ~/.zshrc
+eval "$(ring completion zsh)"
+# ~/.bashrc
+eval "$(ring completion bash)"
+```
+
+Completes subcommands, flags, and `config set` keys.
 
 ## Watch Mode
 
 - With **Textual** (`[tui]` extra) in a real terminal: interactive TUI.
   Use `↑/↓` to select, `Enter` / `Space` to jump, `n` to name a session, `a` to toggle ended sessions, `r` to refresh, and `q` to quit.
   If you have vim muscle memory like I do, `j/k` move up/down and `g/G` jump to the first/last row.
+  When the selected row is 🔴 waiting, a line under the table shows **what it is concretely waiting for** (the command to run, the question asked; hook mode only).
 - Otherwise: Rich polling; without Rich, plain text.
 
 ### Jump To A Session
@@ -108,6 +138,7 @@ Select a session and press `Enter`. RiNG focuses the terminal where that session
 
 - **tmux**: switches directly to the pane via `switch-client`.
 - **iTerm2 / Terminal.app** on macOS: uses the session `tty` and AppleScript to focus the matching tab. The first run may ask for macOS Automation permission.
+- **Linux X11 window** (`wmctrl`, best-effort fallback): for Linux without tmux — walks from the `tty` up to the terminal window that owns it and raises it via `wmctrl`. **Limits**: X11 only (usually a no-op on Wayland), raises the whole window but cannot pick the tab, and gnome-terminal's client/server model may not match. Requires `apt install wmctrl`.
 
 TTY matching is most accurate in hook mode. Without hooks, Codex falls back to zero-config matching:
 one live Codex session per cwd can jump correctly; multiple live Codex sessions in the same cwd are shown conservatively to avoid focusing the wrong tab.
@@ -129,6 +160,20 @@ Without it, RiNG falls back to macOS text notifications without click-to-focus.
 Notification sound, repeat timing, and backend selection are configurable; notification backends
 are also pluggable via the `Notifier` extension point.
 
+#### Push To Your Phone (ntfy / webhook)
+
+Desktop notifications do not help when you are away from the desk. Point RiNG at an
+[ntfy](https://ntfy.sh) topic to push to your phone:
+
+```toml
+# ~/.config/ring/config.toml
+notify_ntfy_url = "https://ntfy.sh/my-ring-topic"  # subscribe to the same topic in the ntfy app
+notify_also = ["ntfy"]                             # desktop notification as usual, plus a copy to the phone
+```
+
+`notify_backend = "ntfy"` pushes to the phone only. For Slack / your own bot / IFTTT, set
+`notify_webhook_url` to use the generic webhook backend (JSON POST with a stable, additive-only payload).
+
 ### Cleaning RiNG State Files (`ring gc`)
 
 When RiNG receives `SessionEnd`, it removes its own hook registry entry. If an agent crashes or the
@@ -145,6 +190,19 @@ ring gc --all-ended      # delete every registry file currently classified as en
 `ring gc` only cleans state files RiNG owns under `~/.config/ring/`. It does not touch Claude Code /
 Codex transcripts or state. `ring doctor` remains read-only and never deletes files.
 
+### Waiting Stats (`ring stats`)
+
+In hook mode, RiNG logs session **state transitions** to `~/.config/ring/events.jsonl`
+(transitions only, tiny, self-trimming past a size cap). `ring stats` then tells you, per project,
+how many times an agent 🔴 waited on you and for how long (avg / max / total).
+
+```sh
+ring stats               # last 7 days
+ring stats --since 12h   # custom window
+```
+
+Like precise notifications, 🔴 waiting is invisible to zero-config, so stats also needs hook mode.
+
 ## Session Sources
 
 RiNG collects sessions from registered sources. Built-ins:
@@ -285,7 +343,11 @@ 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
-focusers = ["tmux", "iTerm2", "Terminal"]
+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"]
+focusers = ["tmux", "iTerm2", "Terminal", "linux-wm"]
+plugins = []                     # external plugin modules imported at startup (see Extending)
 
 [colors]
 waiting = "bold red"
@@ -304,16 +366,36 @@ RiNG is not tied to a specific tool or terminal.
 | Extension Point | Purpose | Built-ins |
 |-----------------|---------|-----------|
 | `SessionSource` | find sessions | Claude Code, Codex, hook registry |
-| `Focuser` | jump to terminals | tmux, iTerm2, Terminal.app |
-| `Notifier` | notify when sessions are waiting | terminal-notifier, osascript, notify-send |
+| `Focuser` | jump to terminals | tmux, iTerm2, Terminal.app, Linux X11 (wmctrl) |
+| `Notifier` | notify when sessions are waiting | terminal-notifier, osascript, notify-send, ntfy, webhook |
 
 Each backend is a small module under `ring/sources/`, `ring/focus/`, or `ring/notify/`, registered via `register_*()`.
 
+### Loading Your Plugin Into An Installed `ring`
+
+`register_*()` only counts if something runs it. The installed `ring` command loads plugins from
+two places at startup:
+
+1. **Entry point** (for published packages) — declare it in your package's `pyproject.toml`,
+   pointing at a module or callable (a module registers on import; a callable is invoked once
+   with no arguments):
+
+   ```toml
+   [project.entry-points."ring.plugins"]
+   mytool = "ring_mytool.plugin"
+   ```
+
+2. **Config** (for local scripts) — add `plugins = ["my_module"]` to `~/.config/ring/config.toml`;
+   the module must be importable (site-packages or `PYTHONPATH`).
+
+A broken plugin prints one warning line to stderr and never blocks the board.
+
 ## Platform & Privacy
 
 - **Platform**: macOS / Linux. Windows is not supported.
-- **Privacy**: entirely local. RiNG only reads local `~/.claude/` and `~/.codex/` data and writes
-  `~/.config/ring/`. No network, uploads, or telemetry.
+- **Privacy**: local by default. RiNG only reads local `~/.claude/` and `~/.codex/` data and writes
+  `~/.config/ring/`. No telemetry. The only network calls are the optional ntfy / webhook notifiers,
+  and only to URLs you configure yourself.
 
 ## Name
 

{ring_cli-0.4.0 → ring_cli-0.6.0}/pyproject.toml

@@ -2,16 +2,24 @@
 # import 的 module（見 [tool.uv.build-backend] module-name）與 CLI 指令仍是 `ring`。
 [project]
 name = "ring-cli"
-version = "0.4.0"
+version = "0.6.0"
 description = "RiNG — Realtime Instance Notification Grid for active agent CLI sessions."
 readme = "README.en.md"
 requires-python = ">=3.13"
 license = "MIT"
 license-files = ["LICENSE"]
 authors = [{ name = "Wei Lee", email = "weilee.rx@gmail.com" }]
-keywords = ["claude-code", "codex", "tui", "dashboard", "session", "monitor", "rich"]
+keywords = [
+  "claude-code",
+  "codex",
+  "tui",
+  "dashboard",
+  "session",
+  "monitor",
+  "rich",
+]
 classifiers = [
-  "Development Status :: 3 - Alpha",
+  "Development Status :: 4 - Beta",
   "Environment :: Console",
   "Intended Audience :: Developers",
   "Operating System :: MacOS",
@@ -40,7 +48,13 @@ dev = [
   { include-group = "linters" },
 ]
 base = ["poethepoet>=0.41.0", "babel>=2.14"]
-test = ["pytest>=9", "pytest-cov>=4", "pytest-xdist>=3.1.0", "pytest-asyncio>=0.24", "textual>=0.80"]
+test = [
+  "pytest>=9",
+  "pytest-cov>=4",
+  "pytest-xdist>=3.1.0",
+  "pytest-asyncio>=0.24",
+  "textual>=0.80",
+]
 linters = ["ruff>=0.15.1", "mypy>=1.19.1", "prek>=0.3.3", "commitizen>=4.13.9"]
 
 [build-system]

{ring_cli-0.4.0 → ring_cli-0.6.0}/src/ring/cli.py

@@ -10,6 +10,7 @@
 from __future__ import annotations
 
 import argparse
+import json
 import sys
 import time
 from dataclasses import fields
@@ -18,10 +19,12 @@ from typing import Any
 
 from ring import __version__
 from ring.commands._args import strip_lang as _strip_lang
+from ring.commands.completion import run_completion
 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.stats import run_stats
 from ring.config import CONFIG_PATH as CONFIG_PATH
 from ring.config import Config as Config
 from ring.config import ConfigError as ConfigError
@@ -30,6 +33,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.plugins import load_plugins
 from ring.registry import Session, Status, running_agent_pids
 from ring.sources import discover_sessions
 
@@ -134,8 +138,12 @@ def provider_label(provider: str) -> str:
 
 
 def labeled_project(project: str, label: str) -> str:
-    """專案名後接使用者自訂標籤（有的話）：``maigo · 重構登入``。"""
-    return f"{project} · {label}" if label else project
+    """看板顯示名：使用者取過名（TUI 按 ``n``）就用名字，否則用專案（目錄）名。
+
+    名字本來就是「這個 session 在做什麼」的更精準描述，取了就直接取代 workspace 名，
+    不再併排（``maigo · 重構登入`` 太佔欄寬）。
+    """
+    return label or project
 
 
 def show_tool_column(sessions: list[Session]) -> bool:
@@ -234,6 +242,55 @@ def _render_plain(sessions: list[Session], show_legend: bool, show_tool: bool =
     return "\n".join(lines)
 
 
+# ----------------------------------------------------------------------------- machine-readable
+def render_json(sessions: list[Session]) -> str:
+    """整個看板的機器可讀快照（給 jq / 腳本 / 自訂 status bar widget 用）。
+
+    鍵名視為穩定介面：只加不改。``label`` 是使用者在 TUI 按 ``n`` 取的名字，沒取過為空字串。
+    """
+    labels = load_labels()
+    data = {
+        "generated_at": time.time(),
+        "agent_processes": len(running_agent_pids()),
+        "counts": {st.value: sum(1 for s in sessions if s.status is st) for st in Status},
+        "sessions": [
+            {
+                "session_id": s.session_id,
+                "provider": s.provider,
+                "project": s.project,
+                "label": labels.get(s.session_id, ""),
+                "status": s.status.value,
+                "marker": s.status.marker,
+                "cwd": s.cwd,
+                "location": s.location,
+                "tmux_target": s.tmux_target,
+                "tty": s.tty,
+                "idle_seconds": round(s.idle_for, 1),
+                "last_active": s.last_active,
+                "last_action": s.last_action,
+                "waiting_detail": s.waiting_detail,
+                "todo": {"done": s.todo[0], "total": s.todo[1]} if s.todo else None,
+                "source": s.source,
+            }
+            for s in sessions
+        ],
+    }
+    return json.dumps(data, ensure_ascii=False, indent=2)
+
+
+def render_oneline(sessions: list[Session]) -> str:
+    """超精簡單行摘要（給 tmux status bar / SwiftBar / waybar 用）：``🔴2 🟢1 🟡3``。
+
+    只列非零狀態；完全沒 session 時回空字串，讓 status bar 段落自然收起來。
+    """
+    parts = [
+        f"{st.marker}{n}"
+        for st in (Status.WAITING, Status.WORKING, Status.IDLE, Status.ENDED)
+        if (n := sum(1 for s in sessions if s.status is st))
+    ]
+    return " ".join(parts)
+
+
 # ----------------------------------------------------------------------------- entry
 def print_snapshot(sessions: list[Session], show_legend: bool) -> None:
     show_tool = show_tool_column(sessions)
@@ -389,6 +446,8 @@ commands:
   focus SESSION_ID             聚焦指定 session；TUI 在跑時會回到 RiNG 並選中該列
   gc [--dry-run]               清理 RiNG 自己的 stale 狀態檔
   doctor                       顯示環境診斷（唯讀）——hook、通知、focuser、維護提示
+  stats [--since 7d]           等待統計：你讓 agent 🔴 等了多久（hook 模式）
+  completion SHELL             印出 shell 補全腳本（zsh / bash）
 """
     )
 
@@ -443,6 +502,22 @@ options:
 
 唯讀環境診斷：逐節報告 hook 安裝狀態、通知後端可用性、focuser 可用性、維護提示與設定檔位置。
 不寫任何檔案、不安裝、不發通知；固定回傳 0。
+"""
+        ),
+        "stats": _(
+            """usage: ring stats [--since DURATION]
+
+等待統計：最近一段時間各專案讓你回應的次數與 🔴 等待時長（平均 / 最長 / 總計）。
+資料來自 hook 寫的狀態轉換 log（~/.config/ring/events.jsonl），zero-config 測不到等待。
+
+options:
+  --since DURATION  統計時間窗（例如 12h、7d、30d；預設 7d）
+"""
+        ),
+        "completion": _(
+            """usage: ring completion zsh|bash
+
+印出 shell 補全腳本。zsh 放 ~/.zshrc：eval "$(ring completion zsh)"；bash 同理。
 """
         ),
     }
@@ -453,10 +528,12 @@ def main(argv: list[str] | None = None) -> int:
     raw = list(sys.argv[1:] if argv is None else argv)
     cfg = get_config()
     set_lang(_peek_lang(raw) or cfg.lang)  # 在 import ring.tui 前設好，Footer 按鍵說明也跟著語言
+    load_plugins()  # 在任何 dispatch 之前：hook（notifier plugin）與看板（source plugin）都吃得到
 
     if (
         raw
-        and raw[0] in {"hook", "install-hooks", "remove-hooks", "config", "focus", "gc", "doctor"}
+        and raw[0]
+        in {"hook", "install-hooks", "remove-hooks", "config", "focus", "gc", "doctor", "stats", "completion"}
         and any(arg in {"-h", "--help"} for arg in raw[1:])
     ):
         print(_subcommand_help(raw[0]), end="")
@@ -474,6 +551,10 @@ def main(argv: list[str] | None = None) -> int:
         return run_gc(raw[1:])
     if raw and raw[0] == "doctor":
         return run_doctor(raw[1:])
+    if raw and raw[0] == "stats":
+        return run_stats(raw[1:])
+    if raw and raw[0] == "completion":
+        return run_completion(raw[1:])
     if raw and raw[0] == "focus" and len(raw) >= 2:
         return run_focus(raw[1:])
 
@@ -495,8 +576,22 @@ def main(argv: list[str] | None = None) -> int:
         help=_("顯示顏色圖例（--no-legend 關閉）"),
     )
     parser.add_argument("--lang", help=_("語言（如 en / zh-Hant；也吃 config / RING_LANG / LANG）"))
+    parser.add_argument(
+        "--format",
+        choices=["table", "json", "oneline"],
+        default="table",
+        help=_("輸出格式：table（預設）/ json（機器可讀）/ oneline（status bar 單行摘要）"),
+    )
     args = parser.parse_args(raw)
 
+    if args.format != "table":
+        if args.watch:
+            print(_("--format {fmt} 只能用在快照模式，不能配 --watch。", fmt=args.format), file=sys.stderr)
+            return 2
+        sessions = board(args.all)
+        print(render_json(sessions) if args.format == "json" else render_oneline(sessions))
+        return 0
+
     if args.watch:
         if HAVE_TEXTUAL and sys.stdout.isatty():
             from ring.tui import run_tui