ring-cli 0.7.0__tar.gz → 0.8.1__tar.gz

{ring_cli-0.7.0 → ring_cli-0.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ring-cli
-Version: 0.7.0
+Version: 0.8.1
 Summary: RiNG — Realtime Instance Notification Grid for active agent CLI sessions.
 Keywords: claude-code,codex,tui,dashboard,session,monitor,rich
 Author: Wei Lee
@@ -116,10 +116,11 @@ Hooks only apply to new sessions, so restart Claude Code / Codex sessions after
 | `ring --all` | Show ended sessions too |
 | `ring --no-legend` | Hide the legend |
 | `ring --lang zh-Hant` | Switch UI language |
-| `ring focus SESSION_ID` | Focus a specific session |
+| `ring focus SESSION_ID` | Focus a specific session; unique prefixes work |
 | `ring config` | Show config path and effective settings |
 | `ring config set KEY VALUE` | Write one config value |
 | `ring doctor` | Read-only environment diagnosis |
+| `ring digest --since 4h` | Away summary: recent session state and wait stats |
 | `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) |
@@ -147,19 +148,21 @@ eval "$(ring completion zsh)"
 eval "$(ring completion bash)"
 ```
 
-Completes subcommands, flags, and `config set` keys.
+Completes subcommands, flags, and `config set` keys; `ring focus` prompts for a session id or unique prefix.
 
 ## 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.
+  Use `↑/↓` to select, `Enter` / `Space` to jump, `n` to name a session, `a` to toggle ended sessions, `dd` to hide a session (it reappears automatically once it has new activity), `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
 
-Select a session and press `Enter`. RiNG focuses the terminal where that session is running.
+Select a session and press `Enter`, or run `ring focus SESSION_ID` with a full id or unique prefix.
+RiNG focuses the terminal where that session is running. If the TUI is already open, `ring focus`
+hands the request to the TUI so it selects that session; otherwise it focuses the terminal directly.
 
 - **tmux**: switches directly to the pane via `switch-client`.
 - **Neovim `:terminal`**: uses the terminal job's inherited `$NVIM` server socket to switch to the exact buffer, then lets the outer tmux or terminal focuser raise its pane/window.
@@ -176,6 +179,13 @@ and sends a system notification right then — **no RiNG board needs to be open*
 after you close the terminal (notifications are event-driven, not polled). While a TUI is open, it
 also nudges you again in-app at 30s / 120s / 300s if the session keeps waiting.
 
+A second kind of reminder is 🟡 **idle for too long** (`idle_threshold_seconds`, default 2h): once a
+session has sat idle past the threshold, it notifies once. Unlike waiting, idle is time-based — there
+is no event to hang a hook on, so it can only be detected by polling. That means it **fires only while
+`ring watch` or a TUI is open** (and when both are open, only one of them fires it, never twice). Close
+every board and idle reminders go silent — waiting still rings you, since that path runs off the hook.
+This is a deliberate trade-off: idle is a secondary signal, not worth a resident background process.
+
 For clickable notifications on macOS, install `terminal-notifier`:
 
 ```sh
@@ -363,6 +373,7 @@ legend = true
 active_window_seconds = 21600
 working_threshold_seconds = 90
 waiting_window_seconds = 1800
+idle_threshold_seconds = 7200    # 🟡 remind once idle for this long (default 2h; 0 = off)
 notify_sound = true
 notify_sound_name = "Glass"
 notify_ignore_dnd = false

{ring_cli-0.7.0 → ring_cli-0.8.1}/README.en.md

@@ -91,10 +91,11 @@ Hooks only apply to new sessions, so restart Claude Code / Codex sessions after
 | `ring --all` | Show ended sessions too |
 | `ring --no-legend` | Hide the legend |
 | `ring --lang zh-Hant` | Switch UI language |
-| `ring focus SESSION_ID` | Focus a specific session |
+| `ring focus SESSION_ID` | Focus a specific session; unique prefixes work |
 | `ring config` | Show config path and effective settings |
 | `ring config set KEY VALUE` | Write one config value |
 | `ring doctor` | Read-only environment diagnosis |
+| `ring digest --since 4h` | Away summary: recent session state and wait stats |
 | `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) |
@@ -122,19 +123,21 @@ eval "$(ring completion zsh)"
 eval "$(ring completion bash)"
 ```
 
-Completes subcommands, flags, and `config set` keys.
+Completes subcommands, flags, and `config set` keys; `ring focus` prompts for a session id or unique prefix.
 
 ## 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.
+  Use `↑/↓` to select, `Enter` / `Space` to jump, `n` to name a session, `a` to toggle ended sessions, `dd` to hide a session (it reappears automatically once it has new activity), `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
 
-Select a session and press `Enter`. RiNG focuses the terminal where that session is running.
+Select a session and press `Enter`, or run `ring focus SESSION_ID` with a full id or unique prefix.
+RiNG focuses the terminal where that session is running. If the TUI is already open, `ring focus`
+hands the request to the TUI so it selects that session; otherwise it focuses the terminal directly.
 
 - **tmux**: switches directly to the pane via `switch-client`.
 - **Neovim `:terminal`**: uses the terminal job's inherited `$NVIM` server socket to switch to the exact buffer, then lets the outer tmux or terminal focuser raise its pane/window.
@@ -151,6 +154,13 @@ and sends a system notification right then — **no RiNG board needs to be open*
 after you close the terminal (notifications are event-driven, not polled). While a TUI is open, it
 also nudges you again in-app at 30s / 120s / 300s if the session keeps waiting.
 
+A second kind of reminder is 🟡 **idle for too long** (`idle_threshold_seconds`, default 2h): once a
+session has sat idle past the threshold, it notifies once. Unlike waiting, idle is time-based — there
+is no event to hang a hook on, so it can only be detected by polling. That means it **fires only while
+`ring watch` or a TUI is open** (and when both are open, only one of them fires it, never twice). Close
+every board and idle reminders go silent — waiting still rings you, since that path runs off the hook.
+This is a deliberate trade-off: idle is a secondary signal, not worth a resident background process.
+
 For clickable notifications on macOS, install `terminal-notifier`:
 
 ```sh
@@ -338,6 +348,7 @@ legend = true
 active_window_seconds = 21600
 working_threshold_seconds = 90
 waiting_window_seconds = 1800
+idle_threshold_seconds = 7200    # 🟡 remind once idle for this long (default 2h; 0 = off)
 notify_sound = true
 notify_sound_name = "Glass"
 notify_ignore_dnd = false

{ring_cli-0.7.0 → ring_cli-0.8.1}/pyproject.toml

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

{ring_cli-0.7.0 → ring_cli-0.8.1}/src/ring/__init__.py

@@ -6,7 +6,9 @@ session 需要你回話時，它「響鈴」叫你。
 
 from importlib.metadata import PackageNotFoundError, version
 
+__distribution__ = "ring-cli"
+
 try:
-    __version__ = version("ring")
+    __version__ = version(__distribution__)
 except PackageNotFoundError:  # 直接從原始碼跑、尚未安裝
     __version__ = "0.0.0+dev"

{ring_cli-0.7.0 → ring_cli-0.8.1}/src/ring/cli.py

@@ -20,6 +20,7 @@ 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.digest import run_digest
 from ring.commands.doctor import run_doctor
 from ring.commands.focus import run_focus
 from ring.commands.gc import run_gc
@@ -32,10 +33,12 @@ from ring.config import get_config as get_config
 from ring.config import set_value as set_value
 from ring.i18n import gettext as _
 from ring.i18n import ngettext, set_lang
+from ring.ipc import read_tui_presence
 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
+from ring.watcher import IdleAlertScheduler
 
 try:
     from rich.box import SIMPLE_HEAD
@@ -165,6 +168,11 @@ def _rich_legend() -> Text:
     return Text.assemble(*[(p.plain, p.style) for p in parts])
 
 
+def _status_text(s: Session) -> str:
+    suffix = f" {s.waiting_icon}" if s.status is Status.WAITING and s.waiting_icon else ""
+    return f"{s.status.marker} {status_label(s.status)}{suffix}"
+
+
 def _rich_renderable(sessions: list[Session], show_legend: bool, show_tool: bool = True) -> Group:
     pids = running_agent_pids()
     blocks: list[Any] = [Text(_header(len(sessions), len(pids)), style="bold")]
@@ -187,7 +195,7 @@ def _rich_renderable(sessions: list[Session], show_legend: bool, show_tool: bool
 
     labels = load_labels()
     for s in sessions:
-        status_cell = Text(f"{s.status.marker} {status_label(s.status)}", style=_STATUS_STYLE[s.status])
+        status_cell = Text(_status_text(s), style=_STATUS_STYLE[s.status])
         progress = f"{s.todo[0]}/{s.todo[1]}" if s.todo else "·"
         loc_cell = f"📍{_middle_truncate(s.location, _LOC_MAX)}"
         project_cell = labeled_project(s.project, labels.get(s.session_id, ""))
@@ -216,6 +224,7 @@ def _render_plain(sessions: list[Session], show_legend: bool, show_tool: bool =
     rows = [
         (
             s.status.marker,
+            s.waiting_icon if s.status is Status.WAITING else "",
             provider_label(s.provider),
             labeled_project(s.project, labels.get(s.session_id, "")),
             f"{s.todo[0]}/{s.todo[1]}" if s.todo else "·",
@@ -226,18 +235,19 @@ def _render_plain(sessions: list[Session], show_legend: bool, show_tool: bool =
         for s in sessions
     ]
     c_tool, c_proj, c_prog, c_idle, c_loc, c_act = _("工具"), _("專案"), _("進度"), _("閒置"), _("去哪"), _("動作")
-    w_tool = max(len(c_tool), *(len(r[1]) for r in rows))
-    w_proj = max(len(c_proj), *(len(r[2]) for r in rows))
-    w_prog = max(len(c_prog), *(len(r[3]) for r in rows))
-    w_ago = max(len(c_idle), 3, *(len(r[4]) for r in rows))
-    w_loc = max(len(c_loc), *(len(r[5]) for r in rows))
+    w_tool = max(len(c_tool), *(len(r[2]) for r in rows))
+    w_proj = max(len(c_proj), *(len(r[3]) for r in rows))
+    w_prog = max(len(c_prog), *(len(r[4]) for r in rows))
+    w_ago = max(len(c_idle), 3, *(len(r[5]) for r in rows))
+    w_loc = max(len(c_loc), *(len(r[6]) for r in rows))
     tool_h = f"{c_tool:<{w_tool}}  " if show_tool else ""
     header = f"     {tool_h}{c_proj:<{w_proj}}  {c_prog:>{w_prog}}  {c_idle:>{w_ago}}    {c_loc:<{w_loc}}  {c_act}"
     lines += ["", header]
-    for marker, tool, project, prog, ago, loc, action in rows:
+    for marker, kind_icon, tool, project, prog, ago, loc, action in rows:
         tool_c = f"{tool:<{w_tool}}  " if show_tool else ""
+        marker_c = f"{marker}{kind_icon}"
         lines.append(
-            f"  {marker} {tool_c}{project:<{w_proj}}  {prog:>{w_prog}}  {ago:>{w_ago}}  📍{loc:<{w_loc}}  {action}"
+            f"  {marker_c:<2} {tool_c}{project:<{w_proj}}  {prog:>{w_prog}}  {ago:>{w_ago}}  📍{loc:<{w_loc}}  {action}"
         )
     return "\n".join(lines)
 
@@ -261,6 +271,10 @@ def render_json(sessions: list[Session]) -> str:
                 "label": labels.get(s.session_id, ""),
                 "status": s.status.value,
                 "marker": s.status.marker,
+                "waiting_kind": s.waiting_kind,
+                "waiting_icon": s.waiting_icon,
+                "hook_stale": s.hook_stale,
+                "heartbeat_at": s.heartbeat_at,
                 "cwd": s.cwd,
                 "location": s.location,
                 "tmux_target": s.tmux_target,
@@ -388,15 +402,33 @@ def run_config(args: list[str]) -> int:
 
 
 def watch(interval: float, count: int, show_all: bool, show_legend: bool) -> int:
-    # 系統通知由 ``ring hook`` 在 session 轉 🔴 等你的當下就地發出（見 hook._ring_waiting_now）；
-    # watch 只負責顯示看板，不再輪詢發通知——這樣關掉看板也照樣 ring 你。
+    # 🔴 等你的通知由 ``ring hook`` 在 session 轉態的當下就地發出（見 hook._ring_waiting_now），
+    # 這樣關掉看板也照樣 ring 你；watch 迴圈額外負責輪詢發 🟡 閒置提醒——
+    # 閒置是時間累積出來的，沒有事件可掛，只能靠輪詢偵測。
     frames = 0
     footer_text = _("每 {interval}s 刷新 · Ctrl-C 離場", interval=int(interval))
+    idle_alerts = IdleAlertScheduler(get_config().idle_threshold_seconds)
+
+    def _notify_idle_alerts(sessions: list[Session]) -> None:
+        # scheduler 照常 feed 讓狀態持續前進；但若 TUI（ring tui）也開著，
+        # 就讓它去發、watch 這邊不重複發系統通知——否則同一 session 會被兩個行程各響一次。
+        # 已標記為 due 的 session 在這裡仍算「提醒過」，所以 TUI 關掉後 watch 不會補發。
+        alerts = idle_alerts.feed(sessions)
+        if not alerts or read_tui_presence() is not None:
+            return
+        try:
+            from ring.notify import notify_idle
+
+            notify_idle(alerts)
+        except Exception:
+            pass
+
     if not HAVE_RICH:
         try:
             while True:
                 sys.stdout.write("\033[2J\033[H")
                 sessions = board(show_all)
+                _notify_idle_alerts(sessions)
                 print(_render_plain(sessions, show_legend, show_tool_column(sessions)))
                 print(f"\n{footer_text}")
                 sys.stdout.flush()
@@ -412,6 +444,7 @@ def watch(interval: float, count: int, show_all: bool, show_legend: bool) -> int
         with Live(console=console, screen=True, auto_refresh=False) as live:
             while True:
                 sessions = board(show_all)
+                _notify_idle_alerts(sessions)
                 body = _rich_renderable(sessions, show_legend, show_tool_column(sessions))
                 live.update(Group(body, Text(f"\n{footer_text}", style=_MUTED)), refresh=True)
                 frames += 1
@@ -446,6 +479,7 @@ commands:
   focus SESSION_ID             聚焦指定 session；TUI 在跑時會回到 RiNG 並選中該列
   gc [--dry-run]               清理 RiNG 自己的 stale 狀態檔
   doctor                       顯示環境診斷（唯讀）——hook、通知、focuser、維護提示
+  digest [--since 4h]          離席摘要：彙整最近 session 狀態
   stats [--since 7d]           等待統計：你讓 agent 🔴 等了多久（hook 模式）
   completion SHELL             印出 shell 補全腳本（zsh / bash）
 """
@@ -502,6 +536,16 @@ options:
 
 唯讀環境診斷：逐節報告 hook 安裝狀態、通知後端可用性、focuser 可用性、維護提示與設定檔位置。
 不寫任何檔案、不安裝、不發通知；固定回傳 0。
+"""
+        ),
+        "digest": _(
+            """usage: ring digest [--since DURATION] [--format text|json]
+
+離席摘要：彙整最近一段時間的 session 狀態與等待統計。
+
+options:
+  --since DURATION  摘要時間窗（例如 30m、4h、1d；預設 4h）
+  --format text|json  輸出格式
 """
         ),
         "stats": _(
@@ -533,7 +577,18 @@ def main(argv: list[str] | None = None) -> int:
     if (
         raw
         and raw[0]
-        in {"hook", "install-hooks", "remove-hooks", "config", "focus", "gc", "doctor", "stats", "completion"}
+        in {
+            "hook",
+            "install-hooks",
+            "remove-hooks",
+            "config",
+            "focus",
+            "gc",
+            "doctor",
+            "digest",
+            "stats",
+            "completion",
+        }
         and any(arg in {"-h", "--help"} for arg in raw[1:])
     ):
         print(_subcommand_help(raw[0]), end="")
@@ -551,11 +606,13 @@ 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] == "digest":
+        return run_digest(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:
+    if raw and raw[0] == "focus":
         return run_focus(raw[1:])
 
     parser = argparse.ArgumentParser(

{ring_cli-0.7.0 → ring_cli-0.8.1}/src/ring/commands/completion.py

@@ -28,6 +28,7 @@ _COMMANDS = (
     "focus",
     "gc",
     "doctor",
+    "digest",
     "stats",
     "completion",
 )
@@ -56,6 +57,7 @@ _ring() {{
     'focus:focus a session by id'
     'gc:clean stale RiNG state files'
     'doctor:read-only environment diagnosis'
+    'digest:away summary'
     'stats:waiting-time statistics'
     'completion:print shell completion script'
   )
@@ -76,6 +78,9 @@ _ring() {{
   fi
 
   case $words[2] in
+    focus)
+      _message 'session id or unique prefix'
+      ;;
     hook)
       _arguments '--provider[provider name]:provider:(claude-code codex)'
       ;;
@@ -88,6 +93,11 @@ _ring() {{
         '--older-than[age threshold, e.g. 30m / 2h / 7d]:duration:' \\
         '--all-ended[remove every ended registry]'
       ;;
+    digest)
+      _arguments \\
+        '--since[summary window, e.g. 30m / 4h / 1d]:duration:' \\
+        '--format[output format]:format:(text json)'
+      ;;
     completion)
       (( CURRENT == 3 )) && _values 'shell' zsh bash
       ;;
@@ -120,15 +130,17 @@ _ring_completion() {{
   fi
 
   case "$prev" in
-    --format) COMPREPLY=( $(compgen -W "table json oneline" -- "$cur") ); return ;;
+    --format) COMPREPLY=( $(compgen -W "table json oneline text" -- "$cur") ); return ;;
     --lang) COMPREPLY=( $(compgen -W "en zh-Hant" -- "$cur") ); return ;;
     --provider) COMPREPLY=( $(compgen -W "claude-code codex" -- "$cur") ); return ;;
   esac
 
   case "${{COMP_WORDS[1]}}" in
+    focus) COMPREPLY=() ;;
     hook) COMPREPLY=( $(compgen -W "--provider" -- "$cur") ) ;;
     install-hooks|remove-hooks) COMPREPLY=( $(compgen -W "--dry-run" -- "$cur") ) ;;
     gc) COMPREPLY=( $(compgen -W "--dry-run --older-than --all-ended" -- "$cur") ) ;;
+    digest) COMPREPLY=( $(compgen -W "--since --format" -- "$cur") ) ;;
     completion) [[ $COMP_CWORD -eq 2 ]] && COMPREPLY=( $(compgen -W "zsh bash" -- "$cur") ) ;;
     config)
       if [[ $COMP_CWORD -eq 2 ]]; then

ring_cli-0.8.1/src/ring/commands/digest.py

@@ -0,0 +1,142 @@
+"""``ring digest`` command handler——回座時快速掃過目前狀態。"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+from dataclasses import dataclass
+from typing import Literal
+
+from ring.commands._args import strip_lang
+from ring.gc import parse_duration
+from ring.i18n import gettext as _
+from ring.registry import Session, Status
+from ring.sources import discover_sessions
+from ring.stats import collect_waits
+
+
+@dataclass(frozen=True)
+class Digest:
+    since: str
+    since_seconds: float
+    generated_at: float
+    waiting: list[Session]
+    idle: list[Session]
+    ended: list[Session]
+    waits: int
+    wait_seconds: float
+    ongoing_waits: int
+
+
+def _rel(seconds: float) -> str:
+    s = int(max(0, seconds))
+    if s < 60:
+        return f"{s}s"
+    if s < 3600:
+        return f"{s // 60}m"
+    return f"{s // 3600}h{(s % 3600) // 60:02d}m"
+
+
+def _session_line(s: Session) -> str:
+    detail = f" — {s.waiting_detail}" if s.waiting_detail else ""
+    kind = f"{s.waiting_icon} " if s.waiting_icon else ""
+    return f"{kind}{s.project} ({_rel(s.idle_for)}){detail}"
+
+
+def build_digest(*, since: str, since_seconds: float, now: float | None = None) -> Digest:
+    generated_at = time.time() if now is None else now
+    cutoff = generated_at - since_seconds
+    sessions = [s for s in discover_sessions() if s.last_active >= cutoff or s.status is Status.WAITING]
+    waits = collect_waits(since_seconds, now=generated_at)
+    return Digest(
+        since=since,
+        since_seconds=since_seconds,
+        generated_at=generated_at,
+        waiting=sorted((s for s in sessions if s.status is Status.WAITING), key=lambda s: s.last_active),
+        idle=sorted((s for s in sessions if s.status is Status.IDLE), key=lambda s: s.last_active, reverse=True),
+        ended=sorted((s for s in sessions if s.status is Status.ENDED), key=lambda s: s.last_active, reverse=True),
+        waits=len(waits),
+        wait_seconds=sum(w.seconds for w in waits),
+        ongoing_waits=sum(1 for w in waits if w.ongoing),
+    )
+
+
+def render_text(digest: Digest) -> str:
+    lines = [_("🎤 RiNG digest — 最近 {since}", since=digest.since)]
+    if not (digest.waiting or digest.idle or digest.ended or digest.waits):
+        lines.append(_("  （這段時間沒有 session 活動。）"))
+        return "\n".join(lines)
+
+    if digest.waiting:
+        lines.append(_("  🔴 正在等你：{n}", n=len(digest.waiting)))
+        lines.extend(f"    - {_session_line(s)}" for s in digest.waiting[:5])
+    if digest.idle:
+        lines.append(_("  🟡 已停著：{n}", n=len(digest.idle)))
+        lines.extend(f"    - {_session_line(s)}" for s in digest.idle[:5])
+    if digest.ended:
+        lines.append(_("  ⚫ 已離場：{n}", n=len(digest.ended)))
+        lines.extend(f"    - {_session_line(s)}" for s in digest.ended[:5])
+    if digest.waits:
+        lines.append(_("  等待統計：{n} 次，共 {duration}", n=digest.waits, duration=_rel(digest.wait_seconds)))
+        if digest.ongoing_waits:
+            lines.append(_("  其中 {n} 段還在等你。", n=digest.ongoing_waits))
+    return "\n".join(lines)
+
+
+def render_json(digest: Digest) -> str:
+    def _pack(s: Session) -> dict[str, object]:
+        return {
+            "session_id": s.session_id,
+            "project": s.project,
+            "status": s.status.value,
+            "last_active": s.last_active,
+            "idle_seconds": round(s.idle_for, 1),
+            "waiting_kind": s.waiting_kind,
+            "waiting_detail": s.waiting_detail,
+            "source": s.source,
+        }
+
+    return json.dumps(
+        {
+            "generated_at": digest.generated_at,
+            "since": digest.since,
+            "since_seconds": digest.since_seconds,
+            "waiting": [_pack(s) for s in digest.waiting],
+            "idle": [_pack(s) for s in digest.idle],
+            "ended": [_pack(s) for s in digest.ended],
+            "waits": {
+                "count": digest.waits,
+                "total_seconds": round(digest.wait_seconds, 1),
+                "ongoing": digest.ongoing_waits,
+            },
+        },
+        ensure_ascii=False,
+        indent=2,
+    )
+
+
+def run_digest(args: list[str]) -> int:
+    args = strip_lang(args)
+    parser = argparse.ArgumentParser(prog="ring digest", description=_("離席摘要：彙整最近一段時間的 session 狀態。"))
+    parser.add_argument(
+        "--since",
+        default="4h",
+        metavar="DURATION",
+        help=_("摘要時間窗（例如 30m、4h、1d；預設 4h）"),
+    )
+    parser.add_argument("--format", choices=["text", "json"], default="text", help=_("輸出格式：text / json"))
+    try:
+        ns = parser.parse_args(args)
+        since_seconds = parse_duration(ns.since)
+    except SystemExit as e:
+        return e.code if isinstance(e.code, int) else 2
+    except ValueError:
+        print(_("無效的 --since：{value}", value=ns.since), file=sys.stderr)
+        return 2
+
+    digest = build_digest(since=ns.since, since_seconds=since_seconds)
+    fmt: Literal["text", "json"] = ns.format
+    print(render_json(digest) if fmt == "json" else render_text(digest))
+    return 0

{ring_cli-0.7.0 → ring_cli-0.8.1}/src/ring/commands/doctor.py

@@ -10,7 +10,7 @@ from ring.config import CONFIG_PATH, get_config
 from ring.gc import DEFAULT_OLDER_THAN_SECONDS
 from ring.gc import collect_candidates as gc_collect_candidates
 from ring.i18n import gettext as _
-from ring.sources import sources
+from ring.sources import discover_sessions, sources
 
 
 def run_doctor(args: list[str]) -> int:
@@ -60,6 +60,18 @@ def run_doctor(args: list[str]) -> int:
         print(f"  {label:<{width_hook}}  {msg}")
     print()
 
+    print(_("Hook 心跳偵測"))
+    try:
+        stale_hooks = [s for s in discover_sessions() if s.hook_stale]
+        if stale_hooks:
+            sample = ", ".join(s.project for s in stale_hooks[:3])
+            print(f"  {_('狀態')}：{_('可能失效')}（{_('{n} 個 session', n=len(stale_hooks))}：{sample}）")
+        else:
+            print(f"  {_('狀態')}：{_('正常')}")
+    except Exception:
+        print(f"  {_('狀態')}：{_('偵測失敗')}")
+    print()
+
     print(_("通知後端"))
     print(f"  {_('目前設定')}：{cfg.notify_backend}")
     notifier_list = notifiers()

ring_cli-0.8.1/src/ring/commands/focus.py

@@ -0,0 +1,53 @@
+"""``ring focus`` command handler."""
+
+from __future__ import annotations
+
+import sys
+
+from ring.i18n import gettext as _
+from ring.registry import Session
+
+
+def _resolve_session(query: str) -> tuple[Session | None, str | None, int]:
+    from ring.sources import discover_sessions, get_by_id
+
+    exact = get_by_id(query)
+    if exact is not None:
+        return exact, None, 0
+
+    matches = [s for s in discover_sessions() if s.session_id.startswith(query)]
+    if len(matches) == 1:
+        return matches[0], None, 0
+    if len(matches) > 1:
+        sample = ", ".join(s.session_id for s in matches[:5])
+        more = _(" 等 {n} 筆", n=len(matches)) if len(matches) > 5 else ""
+        return (
+            None,
+            _("session id 前綴不唯一：{query}（符合：{matches}{more}）", query=query, matches=sample, more=more),
+            2,
+        )
+    return None, _("找不到 session：{query}", query=query), 1
+
+
+def run_focus(args: list[str]) -> int:
+    if len(args) < 1:
+        print(_("用法：ring focus SESSION_ID"), file=sys.stderr)
+        return 2
+
+    from ring.focus import jump as focus_jump
+    from ring.ipc import read_tui_presence, write_focus_request
+
+    query = args[0]
+    session, error, error_code = _resolve_session(query)
+    if session is None:
+        print(error or _("找不到 session：{query}", query=query), file=sys.stderr)
+        return error_code
+    presence = read_tui_presence()
+    if presence is not None:
+        write_focus_request(session.session_id)
+    else:
+        ok, message = focus_jump(session)
+        if not ok:
+            print(message, file=sys.stderr)
+            return 1
+    return 0

{ring_cli-0.7.0 → ring_cli-0.8.1}/src/ring/commands/gc.py

@@ -43,4 +43,19 @@ def run_gc(args: list[str]) -> int:
         print(f"{prefix}{candidate.path} ({candidate.reason})")
     for candidate, error in result.errors:
         print(f"  ! {candidate.path} ({error})", file=sys.stderr)
+
+    if result.hidden_stale:
+        hidden_action = _("將清掉") if result.dry_run else _("已清掉")
+        print(
+            _(
+                "隱藏清單：{action} {count} 筆過期／找不到的條目",
+                action=hidden_action,
+                count=len(result.hidden_stale),
+            )
+        )
+        for sid in result.hidden_stale:
+            prefix = "  - " if result.dry_run else "  ✓ "
+            print(f"{prefix}{sid}")
+    print(_("目前隱藏中：{count} 個 session", count=result.hidden_remaining))
+
     return 1 if result.errors else 0

{ring_cli-0.7.0 → ring_cli-0.8.1}/src/ring/config.py

@@ -9,6 +9,7 @@
     active_window_seconds = 21600     # 只看最近這段時間動過的 session（預設 6h）
     working_threshold_seconds = 90    # 多久沒動就從 🟢 工作中 變 🟡 閒置
     waiting_window_seconds = 1800     # 跑完停著升等你的時間窗上限（預設 30 分）
+    idle_threshold_seconds = 7200     # 🟡 閒置多久後提醒一次（預設 2h；0 = 關閉）
     notify_sound = true               # 系統通知帶聲音
     notify_sound_name = "Glass"       # macOS / terminal-notifier sound name
     notify_ignore_dnd = false         # terminal-notifier 是否加 -ignoreDnD（穿透勿擾 / Focus）
@@ -58,6 +59,7 @@ class Config:
     active_window_seconds: int = 6 * 60 * 60
     working_threshold_seconds: int = 90
     waiting_window_seconds: int = 1800  # 跑完停著升等你的時間窗上限（預設 30 分）
+    idle_threshold_seconds: int = 2 * 60 * 60  # 🟡 閒置多久後提醒一次；0 = 關閉
     notify_sound: bool = True
     notify_sound_name: str = "Glass"
     notify_ignore_dnd: bool = False
@@ -131,6 +133,7 @@ def load(path: Path | None = None) -> Config:
         active_window_seconds=_as_int(raw.get("active_window_seconds"), d.active_window_seconds),
         working_threshold_seconds=_as_int(raw.get("working_threshold_seconds"), d.working_threshold_seconds),
         waiting_window_seconds=_as_int(raw.get("waiting_window_seconds"), d.waiting_window_seconds),
+        idle_threshold_seconds=max(0, _as_int(raw.get("idle_threshold_seconds"), d.idle_threshold_seconds)),
         notify_sound=_as_bool(raw.get("notify_sound"), d.notify_sound),
         notify_sound_name=(
             raw["notify_sound_name"] if isinstance(raw.get("notify_sound_name"), str) else d.notify_sound_name
@@ -202,6 +205,7 @@ _SETTERS: dict[str, Callable[[str], object]] = {
     "active_window_seconds": _coerce_int,
     "working_threshold_seconds": _coerce_int,
     "waiting_window_seconds": _coerce_int,
+    "idle_threshold_seconds": _coerce_int,
     "notify_sound": _coerce_bool,
     "notify_sound_name": str,
     "notify_ignore_dnd": _coerce_bool,