From 50c433e82c368b9861a89deecb74e5f29fa50353 Mon Sep 17 00:00:00 2001
From: Igor Soarez <igor@soarez.org>
Date: Tue, 27 Oct 2026 14:12:28 +0200
Subject: mark as unread: make an idle agent done again, to come back to it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

like "mark as unread" in mail: an agent you have seen (idle) becomes done
again, last among done agents of its importance, with no sound or
notification. it stays done until you come back to it: leave its tmux
window and return, or jump to it. marked while you look at it, it holds
until you look away (`held`); a new turn clears it. only idle agents can
be marked.

- daemon: `pane.mark_unread` on the hook socket; the watcher applies it
  after the tick's observations (mark_unread, advance's hold rule).
- `dingger unread [--pane]`: refuses done, working, blocked, and panes
  without an agent; returns once the agent shows as done.
- pi: /unread (refused while the agent works or is blocked).
- panel: right-click an idle agent in the full list, "Mark as unread".
- search: ⌘U or right-click marks the selected idle agent; the footer
  offers ⌘U when it applies; search stays open.

tests: unit (hold, jump, new turn, idle only), e2e step 22 (queue
position, hold, look away and back, jump, refusals, no sound, menu, the
extension), pi-live in real pi 1.4 (a mark, not a turn: an unknown
command would also end done), swift selftest (menu only for idle, footer).
---
 README.md | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 13a7b9c..c0a4c06 100644
--- a/README.md
+++ b/README.md
@@ -41,7 +41,8 @@ than a poll is still a completion.
 - **Floating panel** (`menubar/panel.swift`): an always-on-top HUD that never
   takes focus, on every Space and over full-screen apps. It lists the agents
   waiting for you (blocked, done) and summarizes the rest
-  (`◐ 2 working · ○ 15 idle`); click a row to jump there, drag to move it.
+  (`◐ 2 working · ○ 15 idle`); click a row to jump there, drag to move it,
+  right-click an idle agent in the full list to mark it unread.
   **⌃⌥⌘E** (or "Show Panel" in the menu) turns it on or off; off stays off
   until you turn it back on. While on, "Panel Shows" picks *Only When Agents
   Are Waiting* (default: it hides itself while nothing waits; turning it on
@@ -53,7 +54,8 @@ than a poll is still a completion.
 - **Agent search**: **⌃⌥⇧⌘U** opens a Spotlight-style search over every
   agent. Type to fuzzy-filter (each word must match, letters in order, the
   name, session, window, harness, status, or directory); ↑↓ or ⌃N ⌃P / ⌃J ⌃K
-  select, ↩ or a click jumps, esc closes, ⌃U clears. With nothing typed,
+  select, ↩ or a click jumps, esc closes, ⌃U clears, ⌘U (or a right-click)
+  marks the selected idle agent unread. With nothing typed,
   agents are in the menu's order, so ↩ jumps to the top waiting agent. It
   takes the keyboard without activating dingger, so focus returns where it
   was.
@@ -106,6 +108,13 @@ than a poll is still a completion.
   run `dingger importance high|normal|low` in the agent's pane (in Claude
   Code: `! dingger importance high`), or pass `--pane`; it lasts until the
   agent exits.
+- **Mark as unread**: like in mail, an idle agent (one you have seen) can be
+  made done again, to come back to later: right-click it in the panel's
+  full list, ⌘U in agent search, `/unread` in pi, or `dingger unread
+  [--pane]`. It goes last among done agents of its importance, with no
+  sound or notification, and stays done until you come back to it: you
+  leave its tmux window and return, or jump to it. Only idle agents can be
+  marked: a working, blocked, or done one is left alone.
 
 ## Where state comes from
 
@@ -135,6 +144,7 @@ dingger watch                 # the daemon (run by launchd, see below)
 dingger status                # agents in priority order
 dingger focus [--pane ID]     # jump to an agent (default: the top waiter)
 dingger importance [LEVEL]    # an agent's importance: high, normal, low
+dingger unread [--pane ID]    # mark an idle agent unread (done again)
 dingger install pi            # install the pi state-reporting extension
 dingger install claude        # report Claude Code sessions, for restore
 dingger install zsh           # record typed command lines, for restore
-- 
cgit v1.2.3