ring-cli 0.11.0__tar.gz → 0.11.2__tar.gz

{ring_cli-0.11.0 → ring_cli-0.11.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ring-cli
-Version: 0.11.0
+Version: 0.11.2
 Summary: RiNG — Realtime Instance Notification Grid for active agent CLI sessions.
 Keywords: claude-code,codex,tui,dashboard,session,monitor,rich
 Author: Wei Lee
@@ -157,6 +157,7 @@ Completes subcommands, flags, and `config set` keys; `ring focus` prompts for a
   Use `↑/↓` to select, `Enter` / `Space` to jump, `p` to reply to a permission request in place, `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).
+  Claude Code background agents carry a `⚙` badge. They have no terminal to jump to, so selecting one shows a `claude --resume` hint; completed agents are folded into ended sessions by default and remain available via `a`.
 - Otherwise: Rich polling; without Rich, plain text.
 
 ### Jump To A Session
@@ -181,6 +182,8 @@ ones with a "from the … agent" header), and lists the numbered options verbati
 After you pick one, RiNG **captures the screen again** to confirm the dialog is still there and
 unchanged (it may have been answered while you were deciding), only then sends that single
 digit, and re-checks that the dialog actually disappeared.
+Once the reply is verified, the TUI immediately clears that waiting revision. Only a newer hook
+event, such as another permission request, can mark the session as waiting again.
 
 - **Sessions inside tmux**: reads the screen with `tmux capture-pane` and sends keys with
   `tmux send-keys`.

{ring_cli-0.11.0 → ring_cli-0.11.2}/README.en.md

@@ -132,6 +132,7 @@ Completes subcommands, flags, and `config set` keys; `ring focus` prompts for a
   Use `↑/↓` to select, `Enter` / `Space` to jump, `p` to reply to a permission request in place, `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).
+  Claude Code background agents carry a `⚙` badge. They have no terminal to jump to, so selecting one shows a `claude --resume` hint; completed agents are folded into ended sessions by default and remain available via `a`.
 - Otherwise: Rich polling; without Rich, plain text.
 
 ### Jump To A Session
@@ -156,6 +157,8 @@ ones with a "from the … agent" header), and lists the numbered options verbati
 After you pick one, RiNG **captures the screen again** to confirm the dialog is still there and
 unchanged (it may have been answered while you were deciding), only then sends that single
 digit, and re-checks that the dialog actually disappeared.
+Once the reply is verified, the TUI immediately clears that waiting revision. Only a newer hook
+event, such as another permission request, can mark the session as waiting again.
 
 - **Sessions inside tmux**: reads the screen with `tmux capture-pane` and sends keys with
   `tmux send-keys`.

{ring_cli-0.11.0 → ring_cli-0.11.2}/pyproject.toml

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

{ring_cli-0.11.0 → ring_cli-0.11.2}/src/ring/locale/en/LC_MESSAGES/ring.po

@@ -161,6 +161,9 @@ msgstr "terminal tab not found (it may have been closed; if it still appears aft
 msgid "沒有 focuser 接得住（裝 hook，或一個專案只開一個 session 才測得到 tty）"
 msgstr "no focuser handled it (install hooks, or keep one session per project so tty is detectable)"
 
+msgid "背景 agent，沒有終端可跳；用 `claude --resume {session_id}` 接回"
+msgstr "background agent, no terminal to jump to; reconnect with `claude --resume {session_id}`"
+
 # ── install-hooks ──
 msgid "⚠️ {path} 不是合法 JSON，先處理它再來。"
 msgstr "⚠️ {path} is not valid JSON; fix it first."

{ring_cli-0.11.0 → ring_cli-0.11.2}/src/ring/locale/ring.pot

@@ -52,7 +52,7 @@ msgstr[1] ""
 msgid "🎤 RiNG — {sess} · {proc}"
 msgstr ""
 
-#: src/ring/cli.py:163 src/ring/cli.py:216 src/ring/tui.py:274
+#: src/ring/cli.py:163 src/ring/cli.py:216 src/ring/tui.py:279
 msgid "圖例"
 msgstr ""
 
@@ -63,32 +63,32 @@ msgstr ""
 #: src/ring/cli.py:184 src/ring/cli.py:338 src/ring/commands/doctor.py:31
 #: src/ring/commands/doctor.py:68 src/ring/commands/doctor.py:70
 #: src/ring/commands/doctor.py:72 src/ring/commands/doctor.py:134
-#: src/ring/tui.py:229
+#: src/ring/tui.py:234
 msgid "狀態"
 msgstr ""
 
-#: src/ring/cli.py:186 src/ring/cli.py:235 src/ring/tui.py:231
+#: src/ring/cli.py:186 src/ring/cli.py:235 src/ring/tui.py:236
 msgid "工具"
 msgstr ""
 
 #: src/ring/cli.py:187 src/ring/cli.py:235 src/ring/commands/stats.py:60
-#: src/ring/tui.py:232
+#: src/ring/tui.py:237
 msgid "專案"
 msgstr ""
 
-#: src/ring/cli.py:188 src/ring/cli.py:235 src/ring/tui.py:232
+#: src/ring/cli.py:188 src/ring/cli.py:235 src/ring/tui.py:237
 msgid "進度"
 msgstr ""
 
-#: src/ring/cli.py:189 src/ring/cli.py:235 src/ring/tui.py:232
+#: src/ring/cli.py:189 src/ring/cli.py:235 src/ring/tui.py:237
 msgid "閒置"
 msgstr ""
 
-#: src/ring/cli.py:190 src/ring/cli.py:235 src/ring/tui.py:232
+#: src/ring/cli.py:190 src/ring/cli.py:235 src/ring/tui.py:237
 msgid "去哪"
 msgstr ""
 
-#: src/ring/cli.py:192 src/ring/cli.py:235 src/ring/tui.py:232
+#: src/ring/cli.py:192 src/ring/cli.py:235 src/ring/tui.py:237
 msgid "動作"
 msgstr ""
 
@@ -349,167 +349,172 @@ msgstr ""
 msgid "⚠️ ring plugin '{name}' 載入失敗：{error}"
 msgstr ""
 
-#: src/ring/tui.py:91
+#: src/ring/tui.py:51
+#, python-brace-format
+msgid "背景 agent，沒有終端可跳；用 `claude --resume {session_id}` 接回"
+msgstr ""
+
+#: src/ring/tui.py:96
 #, python-brace-format
 msgid "為 {project} 命名（Enter 存、Esc 取消、清空移除）"
 msgstr ""
 
-#: src/ring/tui.py:92
+#: src/ring/tui.py:97
 msgid "這個 session 在做什麼…"
 msgstr ""
 
-#: src/ring/tui.py:136
+#: src/ring/tui.py:141
 #, python-brace-format
 msgid "回覆 {project} 的權限請求"
 msgstr ""
 
-#: src/ring/tui.py:141
+#: src/ring/tui.py:146
 msgid "Enter 或數字鍵送出、Esc 取消"
 msgstr ""
 
-#: src/ring/tui.py:164
+#: src/ring/tui.py:169
 msgid "離場"
 msgstr ""
 
-#: src/ring/tui.py:165
+#: src/ring/tui.py:170
 msgid "刷新"
 msgstr ""
 
-#: src/ring/tui.py:166
+#: src/ring/tui.py:171
 msgid "含已離場"
 msgstr ""
 
-#: src/ring/tui.py:167
+#: src/ring/tui.py:172
 msgid "命名"
 msgstr ""
 
-#: src/ring/tui.py:168
+#: src/ring/tui.py:173
 msgid "隱藏"
 msgstr ""
 
-#: src/ring/tui.py:169
+#: src/ring/tui.py:174
 msgid "最久等待"
 msgstr ""
 
-#: src/ring/tui.py:170
+#: src/ring/tui.py:175
 msgid "回覆權限"
 msgstr ""
 
-#: src/ring/tui.py:171 src/ring/tui.py:172
+#: src/ring/tui.py:176 src/ring/tui.py:177
 msgid "跳過去"
 msgstr ""
 
-#: src/ring/tui.py:250
+#: src/ring/tui.py:255
 msgid "💡 同專案開了多個 session，裝 hook 跳轉才精準：ring install-hooks"
 msgstr ""
 
-#: src/ring/tui.py:252
+#: src/ring/tui.py:257
 msgid "↑/↓ 選一列，Enter 或 Space 跳到那個 session 的終端"
 msgstr ""
 
-#: src/ring/tui.py:288
+#: src/ring/tui.py:293
 #, python-brace-format
 msgid "🔔 {names} 在等你回話"
 msgstr ""
 
-#: src/ring/tui.py:329
+#: src/ring/tui.py:334
 #, python-brace-format
 msgid "→ 已跳到 {project}（來自通知）"
 msgstr ""
 
-#: src/ring/tui.py:334
+#: src/ring/tui.py:339
 msgid "那個 session 已不在場"
 msgstr ""
 
-#: src/ring/tui.py:393
+#: src/ring/tui.py:400
 msgid "  ⚠ hook 可能失效：來源檔有更新但沒有 heartbeat"
 msgstr ""
 
-#: src/ring/tui.py:422 src/ring/tui.py:446 src/ring/tui.py:479
-#: src/ring/tui.py:544
+#: src/ring/tui.py:431 src/ring/tui.py:455 src/ring/tui.py:494
+#: src/ring/tui.py:562
 msgid "（沒有選到 session）"
 msgstr ""
 
-#: src/ring/tui.py:453
+#: src/ring/tui.py:462 src/ring/tui.py:470 src/ring/tui.py:500
 #, python-brace-format
-msgid "→ {project}（{where}）"
+msgid "{project}：{msg}"
 msgstr ""
 
-#: src/ring/tui.py:455
+#: src/ring/tui.py:468
 #, python-brace-format
-msgid "{project}：{msg}"
+msgid "→ {project}（{where}）"
 msgstr ""
 
-#: src/ring/tui.py:463
+#: src/ring/tui.py:478
 msgid "（沒有正在等待的 session）"
 msgstr ""
 
-#: src/ring/tui.py:486
+#: src/ring/tui.py:504
 #, python-brace-format
 msgid "{project}：沒有 tmux 座標，且非 macOS 上的 iTerm2 session，無法就地回覆"
 msgstr ""
 
-#: src/ring/tui.py:493
+#: src/ring/tui.py:511
 #, python-brace-format
 msgid "{project}：讀不到 {backend} 畫面"
 msgstr ""
 
-#: src/ring/tui.py:497
+#: src/ring/tui.py:515
 #, python-brace-format
 msgid "{project}：畫面上沒有可辨識的權限對話框，未送出任何按鍵"
 msgstr ""
 
-#: src/ring/tui.py:526
+#: src/ring/tui.py:544
 #, python-brace-format
 msgid "→ {project}：已回覆權限（{option}）"
 msgstr ""
 
-#: src/ring/tui.py:530
+#: src/ring/tui.py:548
 #, python-brace-format
 msgid "{project}：權限對話框已不在，未送出任何按鍵"
 msgstr ""
 
-#: src/ring/tui.py:531
+#: src/ring/tui.py:549
 #, python-brace-format
 msgid "{project}：對話框內容已變化，未送出；請再按一次 p"
 msgstr ""
 
-#: src/ring/tui.py:532
+#: src/ring/tui.py:550
 #, python-brace-format
 msgid "{project}：tmux send-keys 失敗，沒能回覆"
 msgstr ""
 
-#: src/ring/tui.py:533
+#: src/ring/tui.py:551
 #, python-brace-format
 msgid "{project}：已送出但對話框還在，請跳過去確認"
 msgstr ""
 
-#: src/ring/tui.py:535
+#: src/ring/tui.py:553
 #, python-brace-format
 msgid "{project}：對話框已不在，數字落進輸入框，已補 Backspace 清掉"
 msgstr ""
 
-#: src/ring/tui.py:537
+#: src/ring/tui.py:555
 #, python-brace-format
 msgid "{project}：已送出但拿不到畫面驗證，請跳過去確認"
 msgstr ""
 
-#: src/ring/tui.py:552
+#: src/ring/tui.py:570
 #, python-brace-format
 msgid "再按一次 d 隱藏 {project}（有新活動會自動重新出現）"
 msgstr ""
 
-#: src/ring/tui.py:557
+#: src/ring/tui.py:575
 #, python-brace-format
 msgid "{project} 是仍在執行的 process，無法隱藏；請跳過去結束它"
 msgstr ""
 
-#: src/ring/tui.py:565
+#: src/ring/tui.py:583
 #, python-brace-format
 msgid "已隱藏 {project}，並清掉 RiNG 狀態；有新活動會自動重新出現"
 msgstr ""
 
-#: src/ring/tui.py:567
+#: src/ring/tui.py:585
 #, python-brace-format
 msgid "已隱藏 {project}（沒有 RiNG registry 可清；有新活動會自動重新出現）"
 msgstr ""

{ring_cli-0.11.0 → ring_cli-0.11.2}/src/ring/registry.py

@@ -304,6 +304,7 @@ class Session:
     provider: str = ""
     waiting_kind: str = ""  # permission | question | plan | idle；空代表非 WAITING 或舊 registry
     waiting_detail: str = ""  # 🔴 等你時「到底在等什麼」（權限指令 / 問題內容；hook 模式才有）
+    kind: str = "foreground"  # "foreground" | "agent"；背景 agent（bg-pty-host 承載）由 discover 貼標
     _tail_kind: str = field(default="none", repr=False, compare=False)  # 內部：scan 路徑暫存對話尾判定
     origin_cwd: str = ""  # 開場 cwd（session 第一筆帶 cwd 紀錄），用於歸屬；空時 fallback 到 cwd
 
@@ -518,48 +519,183 @@ def _tmux_process_tree_targets(sessions: list[Session]) -> dict[str, str]:
 
 _pids_cache: tuple[float, list[int]] = (-1.0, [])
 _codex_pids_cache: tuple[float, list[int]] = (-1.0, [])
+_ps_claude_snapshot_cache: tuple[float, str] = (-1.0, "")
+_bg_agent_session_ids_cache: tuple[float, frozenset[str]] = (-1.0, frozenset())
 
+# args 內任一出現即可判定「這是 claude 安裝二進位在跑」的路徑標記。ps comm 對
+# daemon-exec 的二進位常被截斷（如 `/Users/weilee/.l`），單看 comm 不可靠。
+_CLAUDE_PATH_MARKERS = ("ClaudeCode.app", "claude/versions/", "/.claude/")
 
-def running_claude_pids() -> list[int]:
-    global _pids_cache
+
+def _is_claude_session_line(comm: str, args: str) -> bool:
+    """判定一行 ``ps`` 輸出是否為 claude session process（承載者或子行程皆算）。
+
+    comm basename 為 ``claude`` 是最常見的情況；但 daemon 承載的 process，ps comm
+    會被截斷成本機路徑片段（例如 ``/Users/weilee/.l``），此時改看 args 是否含可辨識
+    的 claude 安裝路徑標記，或 args 內任一 token 的 basename 為 ``claude``
+    （args 首 token 有時只是版本號如 ``2.1.187``，不能只看 args[0]）。第三個 fallback
+    另外要求 args 內必須有 ``--session-id``，否則像 ``grep -r claude .``、
+    ``less claude`` 這類完全無關但恰好帶 ``claude`` 字面的 process 會被誤收；
+    真正被截斷 comm 的 claude session（daemon 承載者與其子行程）必然帶
+    ``--session-id``，所以這個限定不會犧牲 fallback 能力。
+    """
+    if os.path.basename(comm.strip()) == "claude":
+        return True
+    if any(marker in args for marker in _CLAUDE_PATH_MARKERS):
+        return True
+    tokens = args.split()
+    if "--session-id" not in tokens:
+        return False
+    return any(os.path.basename(tok) == "claude" for tok in tokens)
+
+
+def _ps_claude_snapshot() -> str:
+    """``ps -Ao pid,comm,args`` 的短快取原始輸出，供多個 claude proc 判定函式共用。"""
+    global _ps_claude_snapshot_cache
     now = time.monotonic()
-    if 0.0 <= now - _pids_cache[0] <= _SUBPROCESS_CACHE_TTL:
-        return _pids_cache[1]
+    if 0.0 <= now - _ps_claude_snapshot_cache[0] <= _SUBPROCESS_CACHE_TTL:
+        return _ps_claude_snapshot_cache[1]
     try:
         out = subprocess.run(["ps", "-Ao", "pid,comm,args"], capture_output=True, text=True, timeout=3).stdout
     except (OSError, subprocess.SubprocessError):
         out = ""
-    pids: list[int] = []
+    _ps_claude_snapshot_cache = (now, out)
+    return out
+
+
+def _parse_ps_claude_lines(out: str) -> list[tuple[int, str, bool]]:
+    """把 ``ps`` 輸出解析成 claude session 行：``(pid, args, is_bg_pty_host)``。
+
+    不論是否為背景 process（daemon / bg-spare / bg-pty-host）都收進來——背景判定
+    交給呼叫端各自決定要不要濾除；``_hook_sessions`` 的活性判定與
+    ``running_claude_pids`` 對「該濾誰」的答案不同，不能在這裡先幫忙決定。
+    """
+    entries: list[tuple[int, str, bool]] = []
     for line in out.splitlines()[1:]:
         parts = line.split(None, 2)
-        if len(parts) >= 2 and os.path.basename(parts[1].strip()) == "claude":
-            args = parts[2] if len(parts) == 3 else ""
-            if _is_claude_background_process(args):
-                continue
-            try:
-                pids.append(int(parts[0]))
-            except ValueError:
-                pass
+        if len(parts) < 2:
+            continue
+        comm = parts[1].strip()
+        args = parts[2] if len(parts) == 3 else ""
+        if not _is_claude_session_line(comm, args):
+            continue
+        try:
+            pid = int(parts[0])
+        except ValueError:
+            continue
+        entries.append((pid, args, "--bg-pty-host" in args.split()))
+    return entries
+
+
+def _arg_session_id(args: str) -> str | None:
+    """解析 args 裡 ``--session-id`` 後面的那個 token；沒有就回 ``None``。"""
+    tokens = args.split()
+    for i, tok in enumerate(tokens):
+        if tok == "--session-id" and i + 1 < len(tokens):
+            return tokens[i + 1]
+    return None
+
+
+def running_claude_pids() -> list[int]:
+    """目前活著、使用者可聚焦的 claude CLI pid（daemon / bg-spare / bg 暖機承載者濾除）。
+
+    承載者（``--bg-pty-host`` + ``--session-id``）與其子行程常成對出現、共用同一個
+    session-id：兩者都算「真 session」不濾除，但只留一個 pid，偏好子行程——子行程
+    的 cwd（lsof 量得到）誠實，承載者的 cwd 常是 daemon 自己的 cwd，非專案目錄。
+    只有承載者、沒有子行程時（fallback）仍保留承載者這個 pid，好過整個 session 消失。
+    """
+    global _pids_cache
+    now = time.monotonic()
+    if 0.0 <= now - _pids_cache[0] <= _SUBPROCESS_CACHE_TTL:
+        return _pids_cache[1]
+    entries = _parse_ps_claude_lines(_ps_claude_snapshot())
+
+    pids: list[int] = []
+    sid_index: dict[str, int] = {}  # session-id → 該 pid 在 pids 裡的位置，供子行程晚到時換掉
+    sid_is_bg_host: dict[str, bool] = {}
+    for pid, args, is_bg_host in entries:
+        if _is_claude_background_process(args):
+            continue
+        session_id = _arg_session_id(args)
+        if session_id is None:
+            pids.append(pid)
+            continue
+        if session_id not in sid_index:
+            sid_index[session_id] = len(pids)
+            sid_is_bg_host[session_id] = is_bg_host
+            pids.append(pid)
+        elif sid_is_bg_host[session_id] and not is_bg_host:
+            # 子行程晚到：換掉先記到的承載者 pid，偏好子行程（cwd 誠實）。
+            pids[sid_index[session_id]] = pid
+            sid_is_bg_host[session_id] = False
+
     _pids_cache = (now, pids)
     return pids
 
 
+def running_foreground_claude_pids() -> list[int]:
+    """目前仍有可聚焦終端的 Claude session pid。
+
+    ``running_claude_pids`` 也包含 agents mode 的背景 session，因為 scan 需要靠它們
+    找到對應 transcript；但 hook registry 不能拿背景 agent 的 cwd／數量替同專案的
+    舊前景 row 證明存活，否則一個 agent 就可能讓 crash 數小時的 session 繼續顯示。
+    """
+    bg_ids = background_agent_session_ids()
+    if not bg_ids:
+        return running_claude_pids()
+    args_by_pid = {pid: args for pid, args, _is_bg_host in _parse_ps_claude_lines(_ps_claude_snapshot())}
+    return [
+        pid
+        for pid in running_claude_pids()
+        if (session_id := _arg_session_id(args_by_pid.get(pid, ""))) is None or session_id not in bg_ids
+    ]
+
+
+def background_agent_session_ids() -> set[str]:
+    """所有背景 agent（``--bg-pty-host`` 承載且已載入真 session）的 session-id 集合。
+
+    給 ``discover_sessions()`` 對應貼 ``kind="agent"`` 標籤用。與 ``running_claude_pids``
+    共用同一份 ``ps`` 快照（``_ps_claude_snapshot``），不額外多打一次 ``ps``。
+    """
+    global _bg_agent_session_ids_cache
+    now = time.monotonic()
+    if 0.0 <= now - _bg_agent_session_ids_cache[0] <= _SUBPROCESS_CACHE_TTL:
+        return set(_bg_agent_session_ids_cache[1])
+    entries = _parse_ps_claude_lines(_ps_claude_snapshot())
+    ids = frozenset(
+        session_id
+        for _pid, args, is_bg_host in entries
+        if is_bg_host and (session_id := _arg_session_id(args)) is not None
+    )
+    _bg_agent_session_ids_cache = (now, ids)
+    return set(ids)
+
+
 def _is_claude_background_process(args: str) -> bool:
-    """Claude daemon / bg pty host / bg-spare 備用 process 不是使用者可聚焦的 CLI session。
+    """Claude daemon / bg pty host 暖機承載者 / bg-spare 不是使用者可聚焦的 CLI session。
 
     ``--bg-spare`` 是 Claude Code 預熱的備用 process（供下一個 ``claude`` 呼叫快速接手），
-    跟 ``--bg-pty-host`` 一樣不代表真正的使用者 session，卻會被 ``_claude_procs`` 合成假
-    session 列上看板，冒出幽靈列。token 形狀（`--bg-spare`，`--` flag，不是位置參數）取自
-    本機 claude CLI 2.1.206 二進位的 strings 掃描（無法用 ``ps`` 現場逮到活體 bg-spare
-    process，掃描時機是巧合——它壽命短、隨用隨滅）：
+    跟尚未載入真 session 的 ``--bg-pty-host`` 承載者一樣不代表真正的使用者 session，卻會
+    被 ``_claude_procs`` 合成假 session 列上看板，冒出幽靈列。token 形狀（`--bg-spare`，
+    `--` flag，不是位置參數）取自本機 claude CLI 2.1.206 二進位的 strings 掃描（無法用
+    ``ps`` 現場逮到活體 bg-spare process，掃描時機是巧合——它壽命短、隨用隨滅）：
     ``[a,...l,"--bg-pty-host",r,"200","50","--",a,...l,"--bg-spare",n]`` spawn 呼叫，
     以及 bg-spare process 自己啟動時對 ``process.argv`` 做的
     ``e.includes("--bg-spare", t+1)`` 檢查，兩處都證實是 ``--`` 前綴的 flag token。
+
+    ``--bg-pty-host`` 本身不再一律濾除：暖機階段（spare sock，無 ``--session-id``）仍
+    濾除；一旦掛上真正的 ``--session-id``（使用者已進入 agents、真背景 session），就不
+    再視為背景 process——那是一個真人在跑的背景 agent，該讓它現身，只是要標成
+    ``kind="agent"``（見 ``background_agent_session_ids``）。
     """
     tokens = args.split()
     if len(tokens) >= 3 and tokens[1:3] == ["daemon", "run"]:
         return True
-    return "--bg-pty-host" in tokens or "--bg-spare" in tokens
+    if "--bg-spare" in tokens:
+        return True
+    if "--bg-pty-host" in tokens:
+        return _arg_session_id(args) is None
+    return False
 
 
 def running_codex_pids() -> list[int]:
@@ -568,13 +704,16 @@ def running_codex_pids() -> list[int]:
     if 0.0 <= now - _codex_pids_cache[0] <= _SUBPROCESS_CACHE_TTL:
         return _codex_pids_cache[1]
     try:
-        out = subprocess.run(["ps", "-Ao", "pid,comm"], capture_output=True, text=True, timeout=3).stdout
+        out = subprocess.run(["ps", "-Ao", "pid=,comm=,args="], capture_output=True, text=True, timeout=3).stdout
     except (OSError, subprocess.SubprocessError):
         out = ""
     pids: list[int] = []
-    for line in out.splitlines()[1:]:
-        parts = line.split(None, 1)
-        if len(parts) == 2 and os.path.basename(parts[1].strip()) == "codex":
+    for line in out.splitlines():
+        parts = line.split(None, 2)
+        if len(parts) >= 2 and os.path.basename(parts[1].strip()) == "codex":
+            args = parts[2] if len(parts) == 3 else ""
+            if _is_codex_internal_process(args):
+                continue
             try:
                 pids.append(int(parts[0]))
             except ValueError:
@@ -583,6 +722,18 @@ def running_codex_pids() -> list[int]:
     return pids
 
 
+def _is_codex_internal_process(args: str) -> bool:
+    """Codex app 為工具呼叫啟動的同名內部 process，不是獨立互動 session。"""
+    tokens = args.split()
+    if not tokens:
+        return False
+    try:
+        command_index = next(i for i, token in enumerate(tokens) if os.path.basename(token) == "codex")
+    except StopIteration:
+        return False
+    return command_index + 1 < len(tokens) and tokens[command_index + 1] in {"app-server", "sandbox"}
+
+
 def running_agent_pids() -> list[int]:
     """所有內建來源看得到的 live agent CLI 行程。"""
     return [*running_claude_pids(), *running_codex_pids()]
@@ -658,14 +809,15 @@ def _pid_tty(pid: int) -> str:
 
 
 def _claude_procs() -> list[tuple[str, str]]:
-    """每個還活著的 claude：(cwd, tty)。cwd 判活躍/分流，tty 給終端跳轉。
+    """每個可聚焦的前景 Claude：(cwd, tty)。cwd 判活躍/分流，tty 給終端跳轉。
 
-    claude 不會把 session 的 jsonl 一直開著（lsof 看不到），但給得到 cwd 與 tty。
+    背景 agent 不在這裡按 cwd 配對；它們由 source 依 process args 的 session id 精準
+    認領，避免背景 process 的啟動 cwd 讓同專案舊 transcript 誤判成仍在場。
     同一個 cwd 可能同時開好幾個 session，所以之後在 cwd 群組裡只有 mtime 最新的
     這幾個算活著，其餘同專案的舊 session＝已離場。
     """
     procs: list[tuple[str, str]] = []
-    for pid in running_claude_pids():
+    for pid in running_foreground_claude_pids():
         cwd = _pid_cwd(pid)
         if cwd:
             procs.append((cwd, _pid_tty(pid)))
@@ -1035,11 +1187,17 @@ def _hook_sessions(
                     proc_ttys.setdefault(key, set()).add(tty)
                 proc_cwds_by_provider.setdefault(pk, []).append(real_cwd)
 
+        # 背景 agent 的 process 沒有可聚焦終端，不能拿來替同 cwd 的舊前景 hook row
+        # 證明存活；它只精準認領 args 裡明載的 session id。Claude scan 仍使用包含背景
+        # agent 的 session-id 配對，因此沒有 hook row 的 agent 也不會從看板消失。
+        background_ids = background_agent_session_ids()
         rows_by_key: dict[tuple[str, str], list[Session]] = {}
         for s in out:
             pk = _canonical_provider(s.provider)
             if pk not in _PROVIDER_PROCS:
                 continue  # 沒有 proc 偵測器 → 無法驗活性 → fail-open，交給 SessionEnd
+            if pk == "claude-code" and s.session_id in background_ids:
+                continue
             rows_by_key.setdefault((pk, _real(s.cwd)), []).append(s)
 
         for key, rows in rows_by_key.items():

{ring_cli-0.11.0 → ring_cli-0.11.2}/src/ring/sources/__init__.py

@@ -56,6 +56,16 @@ def discover_sessions() -> list[Session]:
             found.append(s)
         # 否則：仍在隱藏保留期內、沒有新活動 → 不收進看板。
 
+    bg_agent_ids = registry.background_agent_session_ids()
+    for s in found:
+        if s.session_id in bg_agent_ids:
+            s.kind = "agent"
+            # 背景 agent 跑完後不會像前景 session 一樣停在終端等下一輪輸入；它只會由
+            # daemon 暫留 process。繼續顯示成「跑完停著」既無法跳轉也無事可處理，反而
+            # 把已完成工作混進在場清單。歸入 ENDED 後預設收起，`--all` / TUI 的 a 仍可查。
+            if s.status is Status.IDLE:
+                s.status = Status.ENDED
+
     bound_targets = registry._tmux_pane_targets()
     process_targets = registry._tmux_process_tree_targets(found)
     targets = registry._tmux_targets()

ring_cli-0.11.2/src/ring/sources/claude_code.py

@@ -0,0 +1,46 @@
+"""Claude Code：掃 ``~/.claude/projects`` 的 JSONL。"""
+
+from __future__ import annotations
+
+import time
+
+import ring.registry as registry
+from ring.registry import Session
+
+
+def _activate_background_agents(sessions: list[Session], agent_ids: set[str]) -> None:
+    """只依明確 session id 恢復仍有 process 的背景 agent，不用它們的 cwd 猜前景活性。"""
+    now = time.time()
+    for session in sessions:
+        if session.session_id not in agent_ids:
+            continue
+        idle = now - session.last_active
+        session.status = registry._scan_status(idle)
+        session.status = registry._apply_waiting(
+            session.status,
+            idle,
+            session._tail_kind,
+            registry.WAITING_WINDOW_SECONDS,
+        )
+
+
+class ClaudeCodeSource:
+    name = "claude-code"
+
+    def discover(self) -> list[Session]:
+        # 背景 agent 的 process cwd 可能仍是 daemon／啟動目錄，不能拿來按 cwd 猜哪些
+        # 前景 transcript 活著。前景先只用可聚焦 process 判活，背景再按 session id 認領。
+        procs = registry._claude_procs()
+        agent_ids = registry.background_agent_session_ids()
+        merged: dict[str, Session] = {}
+        scanned = registry._scan_sessions(procs)
+        _activate_background_agents(scanned, agent_ids)
+        for s in scanned:
+            merged.setdefault(s.session_id, s)
+        existing = list(merged.values())
+        for s in registry._synthetic_sessions(procs, existing):
+            merged.setdefault(s.session_id, s)  # 合成列只填無 row 的 cwd
+        return list(merged.values())
+
+
+source = ClaudeCodeSource()

{ring_cli-0.11.0 → ring_cli-0.11.2}/src/ring/tui.py

@@ -46,6 +46,11 @@ from ring.watcher import WaitingAlertScheduler
 _ORDER = (Status.WAITING, Status.WORKING, Status.IDLE, Status.ENDED)
 
 
+def _agent_resume_hint(session_id: str) -> str:
+    """背景 agent（無終端可跳）的誠實提示：講清楚沒有畫面可跳，附接回指令。"""
+    return _("背景 agent，沒有終端可跳；用 `claude --resume {session_id}` 接回", session_id=session_id)
+
+
 class _Grid(DataTable[Text]):
     """看板表格。在 DataTable 既有的方向鍵之外，加上 vim 風的 j/k/g/G 導覽。
 
@@ -192,6 +197,9 @@ class RingApp(App[None]):
         self._own_tty: str = self._detect_own_tty()
         self._delete_armed_sid: str | None = None
         self._delete_armed_until: float = 0.0
+        # p 已確認終端對話框消失，但 provider 尚未送後續 hook 時，別讓同一筆舊
+        # PermissionRequest 又把列拉回 WAITING。value 是已回覆那筆 row 的 last_active revision。
+        self._permission_acks: dict[str, float] = {}
 
     @staticmethod
     def _detect_own_tty() -> str:
@@ -340,6 +348,7 @@ class RingApp(App[None]):
         # 退回去跳 session 自己的終端（scan 模式常沒 tty → 跳轉失敗）。
         write_tui_presence()
         self._sessions = board(self._show_all)
+        self._apply_permission_acks()
         table = self.query_one(DataTable)
         # cursor 快照要在「任何」clear 之前取：clear(columns=True) 會把 cursor_row reset 成 0。
         cursor = table.cursor_row
@@ -368,6 +377,8 @@ class RingApp(App[None]):
             suffix = f" {s.waiting_icon}" if s.status is Status.WAITING and s.waiting_icon else ""
             if s.hook_stale:
                 suffix += " ⚠"
+            if s.kind == "agent":
+                suffix += " ⚙"
             status_cell = Text(f"{marker}{s.status.marker} {status_label(s.status)}{suffix}", style=style)
             progress = f"{s.todo[0]}/{s.todo[1]}" if s.todo else "·"
             loc_cell = f"📍{_middle_truncate(s.location, _LOC_MAX)}"
@@ -382,6 +393,30 @@ class RingApp(App[None]):
         self._update_detail()
         self._poll_focus_request()
 
+    def _apply_permission_acks(self) -> None:
+        """以終端回覆結果蓋過同一 revision 的 stale WAITING，直到 provider 送來新事件。"""
+        present_ids = {s.session_id for s in self._sessions}
+        for session_id in set(self._permission_acks) - present_ids:
+            del self._permission_acks[session_id]
+
+        for s in self._sessions:
+            acknowledged_revision = self._permission_acks.get(s.session_id)
+            if acknowledged_revision is None:
+                continue
+            if s.last_active > acknowledged_revision:
+                # 新 hook event（可能是下一個權限請求）已到，重新採信 provider 狀態。
+                del self._permission_acks[s.session_id]
+                continue
+            if s.status is Status.WAITING:
+                # 終端畫面已證實原對話框消失；provider 尚未回報後續狀態時先視為處理中。
+                s.status = Status.WORKING
+                s.waiting_kind = ""
+                s.waiting_detail = ""
+            else:
+                # provider 已用同 revision 清掉 WAITING，不再需要本地 acknowledgment。
+                del self._permission_acks[s.session_id]
+        self._sessions.sort(key=lambda s: (s.status.rank, s.idle_for))
+
     def _update_detail(self) -> None:
         """detail 列：選中的 session 在 🔴 等什麼（hook 有給具體內容才顯示）。
 
@@ -395,6 +430,8 @@ class RingApp(App[None]):
         if s is not None and s.status is Status.WAITING and s.waiting_detail:
             icon = s.waiting_icon or "🔴"
             widget.update(Text(f"  {icon} {s.waiting_detail}", style=_STATUS_STYLE[Status.WAITING]))
+        elif s is not None and s.kind == "agent":
+            widget.update(Text(f"  ⚙ {_agent_resume_hint(s.session_id)}", style="grey50"))
         else:
             widget.update("")
 
@@ -447,8 +484,14 @@ class RingApp(App[None]):
             return
         if s.session_id == self._focused_sid:
             self._focused_sid = None  # 你已親自跳過去處理，解除通知標記
-        ok, msg = focus_jump(s)
         name = self._display_name(s)
+        if s.kind == "agent" and not s.tmux_target and not s.tty:
+            # 背景 agent 本就無終端可跳，不呼叫 focus_jump（沒有畫面可假裝跳得過去）。
+            text = _("{project}：{msg}", project=name, msg=_agent_resume_hint(s.session_id))
+            self._set_status(text)
+            self.notify(text, severity="warning", timeout=10)
+            return
+        ok, msg = focus_jump(s)
         if ok:
             text = _("→ {project}（{where}）", project=name, where=msg)
         else:
@@ -481,12 +524,15 @@ class RingApp(App[None]):
         name = self._display_name(s)
         backend = permission.select_backend(s)
         if backend is None:
-            self._toast(
-                _(
-                    "{project}：沒有 tmux 座標，且非 macOS 上的 iTerm2 session，無法就地回覆",
-                    project=name,
+            if s.kind == "agent":
+                self._toast(_("{project}：{msg}", project=name, msg=_agent_resume_hint(s.session_id)))
+            else:
+                self._toast(
+                    _(
+                        "{project}：沒有 tmux 座標，且非 macOS 上的 iTerm2 session，無法就地回覆",
+                        project=name,
+                    )
                 )
-            )
             return
         screen = backend.capture()
         if screen is None:
@@ -523,6 +569,7 @@ class RingApp(App[None]):
         if outcome is permission.ReplyOutcome.OK:
             if s.session_id == self._focused_sid:
                 self._focused_sid = None  # 已就地回覆，解除通知標記
+            self._permission_acks[s.session_id] = s.last_active
             self._toast(_("→ {project}：已回覆權限（{option}）", project=name, option=option), ok=True)
             self._reload()
             return

ring_cli-0.11.0/src/ring/sources/claude_code.py

@@ -1,23 +0,0 @@
-"""Claude Code：掃 ``~/.claude/projects`` 的 JSONL。"""
-
-from __future__ import annotations
-
-import ring.registry as registry
-from ring.registry import Session
-
-
-class ClaudeCodeSource:
-    name = "claude-code"
-
-    def discover(self) -> list[Session]:
-        procs = registry._claude_procs()
-        merged: dict[str, Session] = {}
-        for s in registry._scan_sessions(procs):
-            merged.setdefault(s.session_id, s)
-        existing = list(merged.values())
-        for s in registry._synthetic_sessions(procs, existing):
-            merged.setdefault(s.session_id, s)  # 合成列只填無 row 的 cwd
-        return list(merged.values())
-
-
-source = ClaudeCodeSource()