agent-ps 0.6.2__tar.gz → 0.6.4__tar.gz

{agent_ps-0.6.2 → agent_ps-0.6.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-ps
-Version: 0.6.2
+Version: 0.6.4
 Summary: A process table for coding agent sessions. Claude Code, Codex, OpenCode, Hermes, Pi, CommandCode and Copilot in one view, with models, idle time, disk use and one key to stop them.
 Author: mkhuda
 License: MIT License
@@ -207,6 +207,7 @@ something.
 | esc | leave filter mode, or close the detail panel |
 | space | pause refreshing |
 | `r` | refresh now |
+| `?` | show or hide this list |
 | `q` | quit |
 
 Those keys live at the bottom of the screen, under a line naming every agent on
@@ -233,9 +234,13 @@ PID     AGENT             SESSION         STATUS MODEL               UPTIME  ACT
 -       claude            notes           ended  opus-5              -       2h22m ago -     -      84M
 
  agents  claude  codex  commandcode  copilot  hermes  opencode  pi        sorted by disk, high to low
- up/down select   enter details   k stop   b background   e hide ended   s sort   S reverse   / filter   q quit
+ up/down move   enter details   k stop   / filter   s sort   e hide ended   ? keys   b background   p prune   S reverse   q quit
 ```
 
+Keys drop from the right as the terminal narrows, `q quit` last of all. Press
+`?` for the ones that never fit: `home`/`end`, `space` to pause, `r` to refresh
+now, `y`/`n` to answer a confirmation.
+
 `v` means descending and `^` ascending; `S` flips it. Numbers start at the
 largest, names start at A, and rows with nothing in that column go to the end
 either way.
@@ -422,7 +427,7 @@ install fetches. The build is reproducible: the same source always produces the
 same bytes, so the committed executable can be checked against the tree.
 
 ```
-fb81708bdedfee2dea7f83bf92cc3b4f32596a02af7d2e6383c92acd57790a4b  agent-ps
+03cc2271187211d38e27773db9067a2a71c5a7055d6776c5d85df178f58f4d0c  agent-ps
 ```
 
 Adding an agent takes one class and one line in the registry. See

{agent_ps-0.6.2 → agent_ps-0.6.4}/README.md

@@ -161,6 +161,7 @@ something.
 | esc | leave filter mode, or close the detail panel |
 | space | pause refreshing |
 | `r` | refresh now |
+| `?` | show or hide this list |
 | `q` | quit |
 
 Those keys live at the bottom of the screen, under a line naming every agent on
@@ -187,9 +188,13 @@ PID     AGENT             SESSION         STATUS MODEL               UPTIME  ACT
 -       claude            notes           ended  opus-5              -       2h22m ago -     -      84M
 
  agents  claude  codex  commandcode  copilot  hermes  opencode  pi        sorted by disk, high to low
- up/down select   enter details   k stop   b background   e hide ended   s sort   S reverse   / filter   q quit
+ up/down move   enter details   k stop   / filter   s sort   e hide ended   ? keys   b background   p prune   S reverse   q quit
 ```
 
+Keys drop from the right as the terminal narrows, `q quit` last of all. Press
+`?` for the ones that never fit: `home`/`end`, `space` to pause, `r` to refresh
+now, `y`/`n` to answer a confirmation.
+
 `v` means descending and `^` ascending; `S` flips it. Numbers start at the
 largest, names start at A, and rows with nothing in that column go to the end
 either way.
@@ -376,7 +381,7 @@ install fetches. The build is reproducible: the same source always produces the
 same bytes, so the committed executable can be checked against the tree.
 
 ```
-fb81708bdedfee2dea7f83bf92cc3b4f32596a02af7d2e6383c92acd57790a4b  agent-ps
+03cc2271187211d38e27773db9067a2a71c5a7055d6776c5d85df178f58f4d0c  agent-ps
 ```
 
 Adding an agent takes one class and one line in the registry. See

{agent_ps-0.6.2 → agent_ps-0.6.4}/agent_ps/__init__.py

@@ -1,3 +1,3 @@
 """agent-ps: a process table for coding agent sessions."""
 
-VERSION = "0.6.2"
+VERSION = "0.6.4"

{agent_ps-0.6.2 → agent_ps-0.6.4}/agent_ps/__main__.py

@@ -299,6 +299,9 @@ def main():
     except UnknownAgent as error:
         print(error, file=sys.stderr)
         return 2
+    # ncurses waits a second after ESC to see if a sequence follows, and esc
+    # cancels the filter, the panel and the confirmation
+    os.environ.setdefault("ESCDELAY", "25")
     try:
         curses.wrapper(lambda screen: Tui(screen, snapshot).loop())
     except KeyboardInterrupt:

{agent_ps-0.6.2 → agent_ps-0.6.4}/agent_ps/ui.py

@@ -32,12 +32,15 @@ AGENT_COLOURS = (
     curses.COLOR_WHITE,
 )
 
-#: A basic terminal has only seven usable colours, and the eighth agent would
-#: have worn the first one's. A terminal offering 256 has room for more without
-#: disturbing the first seven, which people have already learned. The first of
-#: these is the blue Antigravity is branded in, since it lands on that slot.
+#: A terminal offering 256 colours has room for more without disturbing the
+#: first seven, which people have already learned. The first of these is the
+#: blue Antigravity is branded in, since it lands on that slot.
 EXTRA_COLOURS = (69, 208, 141, 84, 173, 205)
 
+#: Attributes that set an agent apart from an earlier one wearing the same
+#: colour, tried in order as the colours run out a second time.
+EXTRA_WEIGHT = (curses.A_UNDERLINE, curses.A_REVERSE)
+
 
 def agent_label(row):
     """Agent name, with the sort of process appended when it is not a session."""
@@ -110,12 +113,22 @@ COLUMNS = [
 ]
 
 
-def _agent_colour(index):
+def _agent_style(index):
+    """A colour, and an attribute that sets it apart from an earlier repeat.
+
+    A basic terminal has seven usable colours, and an eighth agent wearing the
+    first one's is not a hypothetical past this point in the registry. On a
+    256-colour terminal it gets a colour of its own instead; on anything
+    smaller, the same colour with a distinguishing attribute.
+    """
     if index < len(AGENT_COLOURS):
-        return AGENT_COLOURS[index]
+        return AGENT_COLOURS[index], curses.A_BOLD
     if curses.COLORS >= 256:
-        return EXTRA_COLOURS[(index - len(AGENT_COLOURS)) % len(EXTRA_COLOURS)]
-    return AGENT_COLOURS[index % len(AGENT_COLOURS)]
+        colour = EXTRA_COLOURS[(index - len(AGENT_COLOURS)) % len(EXTRA_COLOURS)]
+        return colour, curses.A_BOLD
+    generation = index // len(AGENT_COLOURS)
+    weight = EXTRA_WEIGHT[(generation - 1) % len(EXTRA_WEIGHT)]
+    return AGENT_COLOURS[index % len(AGENT_COLOURS)], curses.A_BOLD | weight
 
 
 def column_span(label):
@@ -155,6 +168,26 @@ SORTS = (
     ("title", "TITLE", _text("title"), False),
 )
 
+#: Everything the key bar has no room for, and every key not in it at all.
+#: Doubles as the documentation for keys that never appear on screen otherwise.
+HELP = (
+    ("up, down, j, K", "move the selection"),
+    ("home, end", "jump to the first or last row"),
+    ("enter", "details for a live session, or reopen an ended one"),
+    ("s", "cycle the sort column"),
+    ("S", "reverse the sort direction"),
+    ("k", "stop the selected process and its children"),
+    ("b", "stop every background helper"),
+    ("p", "remove what an ended session left behind"),
+    ("e", "show or hide ended sessions"),
+    ("/", "filter by session, title, agent, model, directory, or pid"),
+    ("esc", "leave filter mode, or close a panel"),
+    ("space", "pause refreshing"),
+    ("r", "refresh now"),
+    ("y, n", "answer a confirmation"),
+    ("q", "quit"),
+)
+
 
 def format_row(row, width):
     cells = []
@@ -209,8 +242,7 @@ class Tui:
     C_BACKGROUND = 3
     C_SELECTED = 4
     C_WARNING = 5
-    C_SORT = 6
-    C_AGENT_BASE = 7
+    C_AGENT_BASE = 6
 
     def __init__(self, screen, snapshot):
         self.screen = screen
@@ -223,18 +255,48 @@ class Tui:
         self.show_ended = False
         self.filter_text = ""
         self.editing_filter = False
-        # (question, action), so one y/n path serves every destructive key
+        # (verb, detail, action): the verb and [y]/[n] must survive truncation,
+        # so the detail that may not fit comes last
         self.pending = None
+        self.show_help = False
         self.detail = None
         self.sort = 0
         self.descending = True
         self.last_poll = 0.0
-        self.history = {"bytes": 0, "ended": 0, "recent": 0}
+        self.all_rows = []
+        self.history = {"bytes": 0, "ended": 0, "recent": 0, "spare": 0,
+                        "spare_sessions": 0}
+
+    def _put(self, y, x, text, n, attr=0):
+        """addnstr that tolerates a screen too small for what it was told.
+
+        The bottom right cell always raises, even on correct code, and a window
+        that shrank between the layout and the draw raises everywhere.
+        """
+        if n <= 0 or y < 0 or x < 0:
+            return
+        try:
+            self.screen.addnstr(y, x, text, n, attr)
+        except curses.error:
+            pass
 
     def setup(self):
-        curses.curs_set(0)
+        # a terminal whose terminfo has no `civis` raises rather than ignoring
+        try:
+            curses.curs_set(0)
+        except curses.error:
+            pass
         self.agent_colour = {}
         if not curses.has_colors():
+            # attributes work on every terminal, so they are the mechanism and
+            # colour, below, is only ever an enhancement on top of them
+            self.style = {
+                "header": curses.A_REVERSE,
+                "busy": curses.A_BOLD,
+                "background": curses.A_DIM,
+                "selected": curses.A_REVERSE | curses.A_BOLD,
+                "warning": curses.A_BOLD | curses.A_UNDERLINE,
+            }
             self.screen.timeout(200)
             return
         curses.start_color()
@@ -244,20 +306,39 @@ class Tui:
         curses.init_pair(self.C_BACKGROUND, curses.COLOR_BLUE, -1)
         curses.init_pair(self.C_SELECTED, curses.COLOR_BLACK, curses.COLOR_CYAN)
         curses.init_pair(self.C_WARNING, curses.COLOR_YELLOW, -1)
-        # the heading row is black on white, so the sorted column needs its own
-        # background. Cyan rather than yellow, because a light terminal theme
-        # renders a yellow background close enough to white to disappear.
-        curses.init_pair(self.C_SORT, curses.COLOR_BLACK, curses.COLOR_CYAN)
+        self.style = {
+            "header": curses.color_pair(self.C_HEADER),
+            "busy": curses.color_pair(self.C_BUSY),
+            "background": curses.color_pair(self.C_BACKGROUND),
+            "selected": curses.color_pair(self.C_SELECTED),
+            "warning": curses.color_pair(self.C_WARNING),
+        }
         for index, name in enumerate(backends.names()):
+            colour, attr = _agent_style(index)
             pair = self.C_AGENT_BASE + index
-            curses.init_pair(pair, _agent_colour(index), -1)
-            self.agent_colour[name] = curses.color_pair(pair)
+            curses.init_pair(pair, colour, -1)
+            self.agent_colour[name] = curses.color_pair(pair) | attr
         self.screen.timeout(200)
 
     def poll(self):
+        """Read the machine. Everything here touches disk or shells out."""
         # the same window already loaded to pair processes with sessions, so
         # showing all of it costs nothing and makes sorting by size honest
-        rows = self.snapshot.rows(show_ended=self.show_ended, limit=ATTACH_WINDOW)
+        self.all_rows = self.snapshot.rows(show_ended=self.show_ended,
+                                           limit=ATTACH_WINDOW)
+        self.last_poll = time.time()
+        self.history = self.snapshot.history()
+        self.reshape()
+
+    def reshape(self):
+        """Filter and sort what the last poll returned, reading nothing.
+
+        Separate from `poll` because sorting and filtering are questions about
+        rows already in hand. Asking the machine again for every keystroke cost
+        a fifth of a second each time.
+        """
+        held = self.selected()
+        rows = self.all_rows
         if self.filter_text:
             needle = self.filter_text.lower()
             rows = [r for r in rows if matches_filter(r, needle)]
@@ -265,9 +346,11 @@ class Tui:
         if key:
             rows = sorted(rows, key=key, reverse=self.descending)
         self.rows = rows
-        self.cursor = max(0, min(self.cursor, len(self.rows) - 1))
-        self.last_poll = time.time()
-        self.history = self.snapshot.history()
+        # follow the row rather than the position. Under a live sort the order
+        # changes beneath the cursor, and k acts on whatever it is now over.
+        current = self.same_row(held) if held else None
+        self.cursor = (self.rows.index(current) if current
+                       else max(0, min(self.cursor, len(self.rows) - 1)))
         # every pass builds new row objects, so a panel holding one from the
         # last pass would sit there showing the cpu and uptime it had when it
         # was opened
@@ -304,19 +387,31 @@ class Tui:
         self.message = text
         self.message_at = time.time()
 
+    #: Below this there is no layout worth attempting, only a message saying so.
+    MIN_HEIGHT = 6
+    MIN_WIDTH = 40
+
     def draw(self):
         self.screen.erase()
         height, width = self.screen.getmaxyx()
+        if height < self.MIN_HEIGHT or width < self.MIN_WIDTH:
+            self.draw_too_small(height, width)
+            return
         self.draw_summary(width)
+        if self.show_help:
+            self.draw_help(height, width)
+            self.screen.noutrefresh()
+            curses.doupdate()
+            return
         if self.detail and not self.pending:
             self.draw_detail(height, width)
             self.screen.noutrefresh()
             curses.doupdate()
             return
 
-        self.screen.attron(curses.color_pair(self.C_HEADER))
-        self.screen.addnstr(2, 0, format_header(width).ljust(width - 1), width - 1)
-        self.screen.attroff(curses.color_pair(self.C_HEADER))
+        self.screen.attron(self.style["header"])
+        self._put(2, 0, format_header(width).ljust(width - 1), width - 1)
+        self.screen.attroff(self.style["header"])
         self.mark_sorted_column(width)
 
         body = max(1, height - 5)
@@ -324,25 +419,25 @@ class Tui:
         for index, row in enumerate(self.rows[first: first + body]):
             line = format_row(row, width - 1)
             if first + index == self.cursor:
-                attr = curses.color_pair(self.C_SELECTED)
+                attr = self.style["selected"]
                 line = line.ljust(width - 1)
             elif row["kind"] == KIND_ENDED:
                 attr = curses.A_DIM
             elif row["background"]:
-                attr = curses.color_pair(self.C_BACKGROUND)
+                attr = self.style["background"]
             elif row["status"] == STATUS_BUSY:
-                attr = curses.color_pair(self.C_BUSY)
+                attr = self.style["busy"]
             else:
                 attr = curses.A_NORMAL
             screen_row = 3 + index
-            self.screen.addnstr(screen_row, 0, line, width - 1, attr)
+            self._put(screen_row, 0, line, width - 1, attr)
             # the cursor has to stay unmistakable, so a selected row keeps its
             # own colour rather than being broken up by the agent's
             if first + index != self.cursor:
                 self.paint_agent(screen_row, row, width, attr)
 
         if not self.rows:
-            self.screen.addnstr(4, 2, "No coding agent sessions running.", width - 3)
+            self._put(4, 2, self.empty_message(), width - 3)
 
         self.draw_footer(height, width)
         self.screen.noutrefresh()
@@ -362,15 +457,17 @@ class Tui:
         if start >= width - 1:
             return
         text = agent_label(row)[: size - 1].ljust(size)
-        self.screen.addnstr(screen_row, start, text, min(size, width - 1 - start),
-                            colour | (base & curses.A_DIM) | curses.A_BOLD)
+        self._put(screen_row, start, text, min(size, width - 1 - start),
+                            colour | (base & curses.A_DIM))
 
     def mark_sorted_column(self, width):
         """Show which column is sorting, on the column itself.
 
         A word in the summary line says the same thing, but the eye reading a
         table looks at the table, so the marker belongs in the heading it
-        describes.
+        describes. Bold and underlined on top of the header's own colour,
+        rather than a colour of its own: a pair distinct from the header would
+        have needed a background too, and the closest free one is the cursor's.
         """
         label = SORTS[self.sort][1]
         if not label:
@@ -382,8 +479,8 @@ class Tui:
         # the last column has no fixed width, so it is marked to its own length
         cell = size or len(label) + 1
         text = f"{label}{arrow}"[:cell].ljust(cell)
-        self.screen.addnstr(2, start, text, min(cell, width - 1 - start),
-                            curses.color_pair(self.C_SORT) | curses.A_BOLD)
+        self._put(2, start, text, min(cell, width - 1 - start),
+                            self.style["header"] | curses.A_BOLD | curses.A_UNDERLINE)
 
     def detail_groups(self, row, backend):
         """Everything known about one session, in the order it gets asked.
@@ -395,7 +492,7 @@ class Tui:
             ("agent", agent_label(row), self.agent_colour.get(row["agent"], 0)),
             ("session", row["session_id"] or "not matched to a session", 0),
             ("status", status_label(row),
-             curses.color_pair(self.C_BUSY) if row["status"] == STATUS_BUSY else 0),
+             self.style["busy"] if row["status"] == STATUS_BUSY else 0),
             ("model", row["model"] or "-", 0),
             ("title", row["title"] or "-", 0),
             ("directory", row["cwd"] or "-", 0),
@@ -408,7 +505,7 @@ class Tui:
         process.append(("last turn", idle_label(row), 0))
         if row["attach"] == ATTACH_INFERRED:
             process.append(("paired", "matched by working directory, not reported",
-                            curses.color_pair(self.C_WARNING)))
+                            self.style["warning"]))
 
         usage = []
         if row["pid"]:
@@ -438,22 +535,22 @@ class Tui:
         row = self.detail
         backend = self.snapshot.find_backend(row["agent"])
 
-        self.screen.attron(curses.color_pair(self.C_HEADER))
-        self.screen.addnstr(2, 0, " session details".ljust(width - 1), width - 1)
-        self.screen.attroff(curses.color_pair(self.C_HEADER))
+        self.screen.attron(self.style["header"])
+        self._put(2, 0, " session details".ljust(width - 1), width - 1)
+        self.screen.attroff(self.style["header"])
 
         screen_row = 4
         for heading, entries in self.detail_groups(row, backend):
             if not entries or screen_row >= height - 3:
                 continue
-            self.screen.addnstr(screen_row, 2, heading.upper(), 12,
+            self._put(screen_row, 2, heading.upper(), 12,
                                 curses.A_BOLD | curses.A_DIM)
             screen_row += 1
             for label, value, attr in entries:
                 if screen_row >= height - 2:
                     break
                 if label:
-                    self.screen.addnstr(screen_row, 4, f"{label:>11}", 11,
+                    self._put(screen_row, 4, f"{label:>11}", 11,
                                         curses.A_DIM)
                 # the command line is the one field that runs long, so it wraps
                 # instead of being cut off where it stops being useful
@@ -465,15 +562,41 @@ class Tui:
                 for chunk in chunks:
                     if screen_row >= height - 2:
                         break
-                    self.screen.addnstr(screen_row, 17, chunk, width - 18, attr)
+                    self._put(screen_row, 17, chunk, width - 18, attr)
                     screen_row += 1
             screen_row += 1
 
         keys = " enter or esc close"
         if row["pid"]:
             keys += "   k stop this process"
-        self.screen.addnstr(height - 1, 0, keys.ljust(width - 1), width - 1,
-                            curses.color_pair(self.C_HEADER))
+        self._put(height - 1, 0, keys.ljust(width - 1), width - 1,
+                            self.style["header"])
+
+    def draw_too_small(self, height, width):
+        """Say why the table is gone, rather than drawing a broken one."""
+        for offset, text in enumerate((
+                "terminal too small",
+                f"{width}x{height}, need {self.MIN_WIDTH}x{self.MIN_HEIGHT}")):
+            if offset < height:
+                self._put(offset, 0, text, max(0, width - 1))
+        self.screen.noutrefresh()
+        curses.doupdate()
+
+    def draw_help(self, height, width):
+        """Every key, for the ones the footer had no room to name."""
+        self.screen.attron(self.style["header"])
+        self._put(2, 0, " keys".ljust(width - 1), width - 1)
+        self.screen.attroff(self.style["header"])
+        screen_row = 4
+        for key, meaning in HELP:
+            if screen_row >= height - 2:
+                break
+            self._put(screen_row, 4, f"{key:<16}", min(16, max(0, width - 5)),
+                                curses.A_BOLD)
+            self._put(screen_row, 21, meaning, max(0, width - 22))
+            screen_row += 1
+        self._put(height - 1, 0, " press any key to close".ljust(width - 1),
+                            width - 1, self.style["header"])
 
     def draw_summary(self, width):
         """Two lines: what is running, then what it is costing."""
@@ -482,7 +605,10 @@ class Tui:
         background = sum(1 for r in live if r["background"])
         sessions = len(live) - background
 
-        parts = [f"{sessions} session" + ("s" if sessions != 1 else "")]
+        if self.filter_text and len(self.rows) != len(self.all_rows):
+            parts = [f"{len(self.rows)} of {len(self.all_rows)} rows"]
+        else:
+            parts = [f"{sessions} session" + ("s" if sessions != 1 else "")]
         if busy:
             parts.append(f"{busy} busy")
         if background:
@@ -495,23 +621,40 @@ class Tui:
             state = f"/{self.filter_text}   " + state
 
         self.screen.attron(curses.A_BOLD)
-        self.screen.addnstr(0, 1, "agent-ps", width - 2)
+        self._put(0, 1, "agent-ps", width - 2)
         self.screen.attroff(curses.A_BOLD)
-        self.screen.addnstr(0, 10, f"  {'  '.join(parts)}   {state}", width - 11)
+        self._put(0, 10, f"  {'  '.join(parts)}   {state}", width - 11)
 
-        disk = sum(r.get("disk", 0) for r in self.rows)
+        # from live rows, not from self.rows: those are filtered, and a
+        # machine wide total that moves when you type a search term is wrong
+        disk = sum(r.get("disk", 0) for r in live)
         stale = max(0, self.history["bytes"] - disk)
         line = (f" cpu {sum(r['cpu'] for r in live):.1f}%"
                 f"   mem {human_bytes(sum(r['rss'] for r in live), unit_kb=True)}"
                 f"   disk {human_bytes(disk)} active"
                 f"   history {self.history['ended']} sessions, {human_bytes(stale)}")
-        self.screen.addnstr(1, 0, line, width - 1, curses.A_DIM)
+        self._put(1, 0, line, width - 1, curses.A_DIM)
 
         note = self.advisory()
         if note:
             column = min(len(line) + 3, width - 2)
-            self.screen.addnstr(1, column, note, max(0, width - column - 1),
-                                curses.color_pair(self.C_WARNING))
+            self._put(1, column, note, max(0, width - column - 1),
+                                self.style["warning"])
+
+    def empty_message(self):
+        """Why the table has nothing in it, which is not always the same why.
+
+        A filter that matched nothing and no agent being found look identical
+        as an empty table; only the message tells them apart.
+        """
+        if self.filter_text:
+            return f"No rows match /{self.filter_text}. Press esc to clear the filter."
+        ended = self.history["ended"]
+        if not self.show_ended and ended:
+            return (f"No sessions running. {ended} ended session"
+                    f"{'s' if ended != 1 else ''} on record, press e to show them.")
+        return ("No coding agent sessions found. "
+                "Run `agent-ps agents` to see what was detected.")
 
     def advisory(self):
         """One short note when something on screen deserves attention.
@@ -547,26 +690,50 @@ class Tui:
     def draw_footer(self, height, width):
         if self.editing_filter:
             prompt = f" filter: {self.filter_text}"
-            self.screen.addnstr(height - 1, 0, prompt.ljust(width - 1), width - 1,
-                                curses.color_pair(self.C_SELECTED))
+            self._put(height - 1, 0, prompt.ljust(width - 1), width - 1,
+                                self.style["selected"])
             return
         if self.pending:
-            text = f" {self.pending[0]}  [y] confirm  [n] cancel"
-            self.screen.addnstr(height - 1, 0, text.ljust(width - 1), width - 1,
-                                curses.color_pair(self.C_WARNING))
+            verb, detail, _ = self.pending
+            # the answer keys must survive truncation, so they come first and
+            # the detail, which can run long, is what gets cut on a narrow screen
+            prefix = f" [y] {verb}   [n] cancel"
+            room = width - 1 - len(prefix) - 3
+            text = f"{prefix}   {detail[:room]}" if detail and room > 0 else prefix
+            self._put(height - 1, 0, text.ljust(width - 1), width - 1,
+                                self.style["warning"])
             return
         # the note and the legend share a line: a note is worth interrupting the
         # legend for, and it is gone again in a few seconds
         if self.message and time.time() - self.message_at < MESSAGE_SECONDS:
-            self.screen.addnstr(height - 2, 0, f" {self.message}", width - 1,
-                                curses.color_pair(self.C_WARNING))
+            self._put(height - 2, 0, f" {self.message}", width - 1,
+                                self.style["warning"])
         else:
             self.draw_legend(height - 2, width)
+        keys = self.key_bar(width)
+        self._put(height - 1, 0, keys.ljust(width - 1), width - 1,
+                            self.style["header"])
+
+    def key_bar(self, width):
+        """The bottom row, longest first so the least useful key drops first.
+
+        `q quit` is appended after fitting the rest, so a screen too narrow
+        for anything else still has an answer for how to leave.
+        """
         mode = "hide ended" if self.show_ended else "show ended"
-        keys = (" up/down   enter details   k stop   b background   p prune"
-                f"   e {mode}   s sort   S reverse   / filter   q quit")
-        self.screen.addnstr(height - 1, 0, keys.ljust(width - 1), width - 1,
-                            curses.color_pair(self.C_HEADER))
+        # ordered by priority: everything up to and including "e" is kept as
+        # long as there is any room at all, the rest goes as the screen narrows
+        entries = [("up/down", "move"), ("enter", "details"), ("k", "stop"),
+                  ("/", "filter"), ("s", "sort"), ("e", mode), ("?", "keys"),
+                  ("b", "background"), ("p", "prune"), ("S", "reverse")]
+        tail = "q quit"
+        while entries:
+            text = (" " + "   ".join(f"{k} {v}" for k, v in entries)
+                    + "   " + tail)
+            if len(text) <= width - 1:
+                return text
+            entries.pop()
+        return " " + tail
 
     def draw_legend(self, screen_row, width):
         """Which agents are on screen, each in its own colour.
@@ -587,7 +754,7 @@ class Tui:
             placed.append((len(text), agent))
             text += agent + "  "
         text = text.rstrip()
-        self.screen.addnstr(screen_row, 0, text, width - 1, curses.A_DIM)
+        self._put(screen_row, 0, text, width - 1, curses.A_DIM)
 
         # a long agent list leaves no room for a sentence on an 80 column
         # terminal, and dropping the note entirely is worse than abbreviating it
@@ -599,15 +766,15 @@ class Tui:
         for note in (wordy, f"sort: {name} {arrow}" if column else "sort: agent"):
             at = width - len(note) - 2
             if at > len(text) + 3:
-                self.screen.addnstr(screen_row, at, note, len(note),
-                                    curses.color_pair(self.C_SORT) | curses.A_BOLD)
+                self._put(screen_row, at, note, len(note),
+                                    curses.A_BOLD | curses.A_UNDERLINE)
                 break
 
         for at, agent in placed:
             if at >= width - 1:
                 continue
-            self.screen.addnstr(screen_row, at, agent, min(len(agent), width - 1 - at),
-                                self.agent_colour.get(agent, 0) | curses.A_BOLD)
+            self._put(screen_row, at, agent, min(len(agent), width - 1 - at),
+                                self.agent_colour.get(agent, curses.A_BOLD))
 
     def confirm_kill(self, row):
         """Ask before stopping, and say where the process is.
@@ -619,11 +786,11 @@ class Tui:
         # the real process table, not the agent rows: a session's children are
         # MCP servers and helpers, which are not rows and would be orphaned
         order = collect_tree(row["pid"], children_of(proc_table()))
-        note = f" in {short_path(row['cwd'], 40)}" if row["cwd"] else ""
+        detail = short_path(row["cwd"], 40) if row["cwd"] else ""
         if row["attach"] == ATTACH_INFERRED:
-            note += ", session matched by directory"
-        self.pending = (f"Stop {len(order)} process(es){note}?",
-                        lambda: self.apply_kill(order))
+            detail += (", " if detail else "") + "matched by directory"
+        verb = f"stop {len(order)} process" + ("es" if len(order) != 1 else "")
+        self.pending = (verb, detail, lambda: self.apply_kill(order))
 
     def confirm_prune(self, row):
         """Ask before removing what an ended session left behind.
@@ -647,10 +814,10 @@ class Tui:
             return
         total = sum(size for _, _, size in parts)
         labels = sorted({label for label, _, _ in parts})
-        self.pending = (
-            f"Remove {human_bytes(total)} of {', '.join(labels)} from "
-            f"{short_path(name, 24)}? The transcript is kept.",
-            lambda: self.apply_prune(row, parts))
+        verb = f"remove {human_bytes(total)}"
+        detail = (f"{', '.join(labels)} from {short_path(name, 24)}, "
+                  f"transcript kept")
+        self.pending = (verb, detail, lambda: self.apply_prune(row, parts))
 
     def apply_prune(self, row, parts):
         self.detail = None
@@ -709,6 +876,15 @@ class Tui:
         if self.editing_filter:
             return self.handle_filter(key)
 
+        if key == curses.KEY_RESIZE:
+            curses.update_lines_cols()
+            self.cursor = max(0, min(self.cursor, len(self.rows) - 1))
+            return True
+
+        if self.show_help:
+            self.show_help = False
+            return True
+
         # moving around means the last result has been read, so drop the note
         # early rather than leaving it to time out under a different row
         if key in (curses.KEY_UP, curses.KEY_DOWN, curses.KEY_HOME, curses.KEY_END,
@@ -726,7 +902,7 @@ class Tui:
 
         if self.pending:
             if key in (ord("y"), ord("Y")):
-                action = self.pending[1]
+                action = self.pending[2]
                 self.pending = None
                 action()
             elif key in (ord("n"), ord("N"), 27):
@@ -751,12 +927,10 @@ class Tui:
         elif key == ord("s"):
             self.sort = (self.sort + 1) % len(SORTS)
             self.descending = SORTS[self.sort][3]
-            self.cursor = 0
-            self.poll()
+            self.reshape()
         elif key == ord("S"):
             self.descending = not self.descending
-            self.cursor = 0
-            self.poll()
+            self.reshape()
         elif key in (ord("r"), ord("R")):
             self.poll()
             self.message = ""
@@ -767,6 +941,8 @@ class Tui:
             self.poll()
         elif key == ord("/"):
             self.editing_filter = True
+        elif key == ord("?"):
+            self.show_help = True
         elif key == ord("k"):
             row = self.selected()
             if row and row["pid"]:
@@ -782,8 +958,9 @@ class Tui:
         elif key in (ord("b"), ord("B")):
             background = [r["pid"] for r in self.rows if r["background"]]
             if background:
-                self.pending = (f"Stop {len(background)} background process(es)?",
-                                lambda: self.apply_kill(background))
+                verb = ("stop " + str(len(background)) + " background process"
+                        + ("es" if len(background) != 1 else ""))
+                self.pending = (verb, "", lambda: self.apply_kill(background))
             else:
                 self.notify("No background processes.")
         return True
@@ -791,11 +968,10 @@ class Tui:
     def handle_filter(self, key):
         if key in (10, 13, curses.KEY_ENTER):
             self.editing_filter = False
-            self.poll()
         elif key == 27:
             self.editing_filter = False
             self.filter_text = ""
-            self.poll()
+            self.reshape()
         elif key in (curses.KEY_BACKSPACE, 127, 8):
             # backspacing past the last character leaves filter mode, so the key
             # hints come back without needing escape
@@ -805,10 +981,10 @@ class Tui:
                 self.filter_text = self.filter_text[:-1]
                 if not self.filter_text:
                     self.editing_filter = False
-                self.poll()
+                self.reshape()
         elif 32 <= key < 127:
             self.filter_text += chr(key)
-            self.poll()
+            self.reshape()
         return True
 
     def loop(self):

{agent_ps-0.6.2 → agent_ps-0.6.4}/agent_ps.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-ps
-Version: 0.6.2
+Version: 0.6.4
 Summary: A process table for coding agent sessions. Claude Code, Codex, OpenCode, Hermes, Pi, CommandCode and Copilot in one view, with models, idle time, disk use and one key to stop them.
 Author: mkhuda
 License: MIT License
@@ -207,6 +207,7 @@ something.
 | esc | leave filter mode, or close the detail panel |
 | space | pause refreshing |
 | `r` | refresh now |
+| `?` | show or hide this list |
 | `q` | quit |
 
 Those keys live at the bottom of the screen, under a line naming every agent on
@@ -233,9 +234,13 @@ PID     AGENT             SESSION         STATUS MODEL               UPTIME  ACT
 -       claude            notes           ended  opus-5              -       2h22m ago -     -      84M
 
  agents  claude  codex  commandcode  copilot  hermes  opencode  pi        sorted by disk, high to low
- up/down select   enter details   k stop   b background   e hide ended   s sort   S reverse   / filter   q quit
+ up/down move   enter details   k stop   / filter   s sort   e hide ended   ? keys   b background   p prune   S reverse   q quit
 ```
 
+Keys drop from the right as the terminal narrows, `q quit` last of all. Press
+`?` for the ones that never fit: `home`/`end`, `space` to pause, `r` to refresh
+now, `y`/`n` to answer a confirmation.
+
 `v` means descending and `^` ascending; `S` flips it. Numbers start at the
 largest, names start at A, and rows with nothing in that column go to the end
 either way.
@@ -422,7 +427,7 @@ install fetches. The build is reproducible: the same source always produces the
 same bytes, so the committed executable can be checked against the tree.
 
 ```
-fb81708bdedfee2dea7f83bf92cc3b4f32596a02af7d2e6383c92acd57790a4b  agent-ps
+03cc2271187211d38e27773db9067a2a71c5a7055d6776c5d85df178f58f4d0c  agent-ps
 ```
 
 Adding an agent takes one class and one line in the registry. See

{agent_ps-0.6.2 → agent_ps-0.6.4}/agent_ps.egg-info/SOURCES.txt

@@ -28,4 +28,5 @@ tests/test_backends.py
 tests/test_procs.py
 tests/test_prune.py
 tests/test_release_notes.py
+tests/test_terminal.py
 tests/test_ui.py

agent_ps-0.6.4/tests/test_terminal.py

@@ -0,0 +1,127 @@
+"""The TUI against terminals it was not designed for.
+
+These run the real program under a pseudo terminal, because the failures they
+catch are ones no unit test sees: a window that shrinks after the layout was
+computed, and a terminfo that cannot hide the cursor.
+"""
+
+import os
+import re
+import select
+import shutil
+import signal
+import struct
+import subprocess
+import sys
+import tempfile
+import time
+import unittest
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+ESCAPES = re.compile(r"\x1b\[[0-9;?]*[A-Za-z]")
+
+try:
+    import fcntl
+    import pty
+    import termios
+    HAVE_PTY = True
+except ImportError:  # pragma: no cover - Windows has no pty
+    HAVE_PTY = False
+
+
+@unittest.skipUnless(HAVE_PTY, "needs a pseudo terminal")
+class UnderAPseudoTerminal(unittest.TestCase):
+    def setUp(self):
+        # an empty home, not the real one: the first poll otherwise scans
+        # whatever sessions actually exist on this machine, which is slow and
+        # unpredictable, and is exactly what made this suite flaky
+        self.home = tempfile.mkdtemp()
+        self.addCleanup(shutil.rmtree, self.home, ignore_errors=True)
+
+    def run_tui(self, rows, cols, shrink_to=None, term="xterm-256color"):
+        """Start the TUI, optionally resize it, quit, and return its output."""
+        main, sub = pty.openpty()
+        fcntl.ioctl(sub, termios.TIOCSWINSZ, struct.pack("HHHH", rows, cols, 0, 0))
+        child = subprocess.Popen(
+            [sys.executable, "-m", "agent_ps"], stdin=sub, stdout=sub, stderr=sub,
+            cwd=ROOT, env=dict(os.environ, TERM=term, HOME=self.home))
+        os.close(sub)
+
+        def pump(seconds):
+            """Read whatever arrives, for at most this long."""
+            got, until = b"", time.time() + seconds
+            while time.time() < until and child.poll() is None:
+                ready, _, _ = select.select([main], [], [], 0.05)
+                if not ready:
+                    continue
+                try:
+                    chunk = os.read(main, 65536)
+                except OSError:
+                    break
+                if not chunk:
+                    break
+                got += chunk
+                until = min(until, time.time() + 0.3)  # quiet means it settled
+            return got
+
+        out = pump(4.0)
+        if shrink_to and child.poll() is None:
+            fcntl.ioctl(main, termios.TIOCSWINSZ,
+                        struct.pack("HHHH", shrink_to[0], shrink_to[1], 0, 0))
+            child.send_signal(signal.SIGWINCH)
+            out += pump(2.0)
+        if child.poll() is None:
+            try:
+                os.write(main, b"q")
+            except OSError:
+                pass
+            out += pump(1.0)
+        try:
+            child.wait(timeout=3)
+        except subprocess.TimeoutExpired:
+            child.kill()
+            child.wait()
+        try:
+            while True:
+                chunk = os.read(main, 65536)
+                if not chunk:
+                    break
+                out += chunk
+        except OSError:
+            pass
+        os.close(main)
+        return ESCAPES.sub("", out.decode("utf8", "ignore"))
+
+    def assertNoCrash(self, text, what):
+        self.assertNotIn("Traceback", text, f"{what} crashed:\n{text[-600:]}")
+        self.assertNotIn("curses.error", text, f"{what} crashed:\n{text[-600:]}")
+
+    def test_a_normal_terminal(self):
+        self.assertNoCrash(self.run_tui(24, 120), "24x120")
+
+    def test_a_terminal_too_small_to_lay_out(self):
+        for rows, cols in ((4, 100), (1, 80), (2, 30)):
+            with self.subTest(f"{cols}x{rows}"):
+                seen = self.run_tui(rows, cols)
+                self.assertNoCrash(seen, f"{cols}x{rows}")
+                self.assertIn("too small", seen,
+                              "a screen with no room must say so, not go blank")
+
+    def test_shrinking_the_window_while_it_runs(self):
+        # the layout is computed for one size and drawn against another
+        for shrink in ((3, 60), (1, 20)):
+            with self.subTest(f"{shrink[1]}x{shrink[0]}"):
+                self.assertNoCrash(self.run_tui(24, 120, shrink_to=shrink),
+                                   f"resize to {shrink}")
+
+    def test_terminals_that_cannot_hide_the_cursor(self):
+        # curs_set raises rather than returning a failure on these
+        for term in ("vt100", "vt220", "ansi", "dumb"):
+            with self.subTest(term):
+                self.assertNoCrash(self.run_tui(24, 120, term=term), term)
+
+
+if __name__ == "__main__":
+    unittest.main()

{agent_ps-0.6.2 → agent_ps-0.6.4}/tests/test_ui.py

@@ -11,7 +11,7 @@ sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
 import curses
 
 from agent_ps import ui, util
-from agent_ps.ui import Tui
+from agent_ps.ui import SORTS, Tui
 from agent_ps.backends.base import KIND_ENDED, KIND_SESSION, blank_row
 from agent_ps.collect import is_live, idle_seconds
 
@@ -238,10 +238,11 @@ class PruneKey(unittest.TestCase):
         made = self.tui()
         made.confirm_prune(self.row())
         self.assertIsNotNone(made.pending)
-        question = made.pending[0]
-        self.assertIn("web-app", question)
-        self.assertIn("subagents", question)
-        self.assertIn("transcript is kept", question)
+        verb, detail, _ = made.pending
+        self.assertIn("web-app", detail)
+        self.assertIn("subagents", detail)
+        self.assertIn("transcript kept", detail)
+        self.assertIn("remove", verb)
 
     def test_a_running_session_is_refused_and_told_why(self):
         made = self.tui()
@@ -341,3 +342,220 @@ class ReclaimableTotal(unittest.TestCase):
     def test_a_recent_session_is_left_out(self):
         made = self.snapshot([self.session("a", 30), self.session("b", 1)])
         self.assertEqual(made.reclaimable(time.time() - 7 * 86400), (1_000_000, 1))
+
+
+class Resilience(unittest.TestCase):
+    """What the drawing layer does when the screen is not what it expected."""
+
+    class Screen:
+        def __init__(self, fail=False):
+            self.fail, self.calls = fail, []
+
+        def addnstr(self, y, x, text, n, attr=0):
+            self.calls.append((y, x, text, n))
+            if self.fail:
+                raise curses.error("addnwstr() returned ERR")
+
+    def test_a_screen_that_refuses_the_write_does_not_crash(self):
+        tui = Tui.__new__(Tui)
+        tui.screen = self.Screen(fail=True)
+        tui._put(0, 0, "anything", 8)   # must not raise
+
+    def test_nothing_is_written_outside_the_screen(self):
+        tui = Tui.__new__(Tui)
+        tui.screen = self.Screen()
+        for y, x, n in ((-1, 0, 5), (0, -1, 5), (0, 0, 0), (0, 0, -3)):
+            tui._put(y, x, "x", n)
+        self.assertEqual(tui.screen.calls, [], "a doomed write was attempted")
+
+    def test_a_write_that_fits_goes_through(self):
+        tui = Tui.__new__(Tui)
+        tui.screen = self.Screen()
+        tui._put(1, 2, "hello", 5, 0)
+        self.assertEqual(tui.screen.calls, [(1, 2, "hello", 5)])
+
+
+class CursorFollowsTheRow(unittest.TestCase):
+    """Under a live sort the order changes; the cursor must not drift.
+
+    This is a safety property, not a nicety: k acts on whatever the cursor is
+    over, so a cursor that moves on its own stops the wrong session.
+    """
+
+    def tui(self, rows, cursor=0, sort=0):
+        made = Tui.__new__(Tui)
+        made.all_rows = rows
+        made.rows = list(rows)
+        made.cursor = cursor
+        made.filter_text = ""
+        made.sort = sort
+        made.descending = True
+        made.detail = None
+        return made
+
+    def row(self, session, disk=0, **over):
+        return dict(blank_row("claude"), session_id=session, disk=disk, **over)
+
+    def test_the_cursor_stays_on_its_session_when_the_order_changes(self):
+        a, b, c = self.row("a", 10), self.row("b", 20), self.row("c", 30)
+        made = self.tui([a, b, c], cursor=0)
+        made.rows = [a, b, c]
+        held = made.selected()
+        self.assertEqual(held["session_id"], "a")
+        # the same three rows arrive sorted by disk, so "a" is now last
+        made.all_rows = [c, b, a]
+        made.sort = next(i for i, s in enumerate(SORTS) if s[0] == "disk")
+        made.reshape()
+        self.assertEqual(made.selected()["session_id"], "a",
+                         "the cursor followed the position, not the session")
+
+    def test_the_cursor_falls_back_when_its_session_is_gone(self):
+        a, b = self.row("a"), self.row("b")
+        made = self.tui([a, b], cursor=1)
+        made.rows = [a, b]
+        made.all_rows = [a]          # b ended between polls
+        made.reshape()
+        self.assertEqual(made.cursor, 0)
+
+    def test_filtering_keeps_the_cursor_on_a_row_that_survives(self):
+        a, b = self.row("a", title="keep me"), self.row("b", title="other")
+        made = self.tui([a, b], cursor=0)
+        made.rows = [a, b]
+        made.filter_text = "keep"
+        made.reshape()
+        self.assertEqual(made.rows, [a])
+        self.assertEqual(made.cursor, 0)
+
+
+class ReshapeReadsNothing(unittest.TestCase):
+    """Sorting and filtering are questions about rows already in hand."""
+
+    class Exploding:
+        def rows(self, *a, **k):
+            raise AssertionError("reshape asked the machine again")
+
+        def history(self, force=False):
+            raise AssertionError("reshape asked the machine again")
+
+    def test_reshape_never_touches_the_snapshot(self):
+        made = Tui.__new__(Tui)
+        made.snapshot = self.Exploding()
+        made.all_rows = [dict(blank_row("claude"), session_id="a")]
+        made.rows, made.cursor, made.detail = [], 0, None
+        made.filter_text, made.sort, made.descending = "a", 0, True
+        made.reshape()      # must not raise
+
+
+class SummaryArithmetic(unittest.TestCase):
+    def test_history_starts_with_every_key_the_advisory_reads(self):
+        made = Tui.__new__(Tui)
+        Tui.__init__(made, None, None)
+        for key in ("bytes", "ended", "recent", "spare", "spare_sessions"):
+            self.assertIn(key, made.history)
+
+
+class KeyBarPriority(unittest.TestCase):
+    """The key bar drops low priority keys first, and q is never one of them."""
+
+    def bar(self, width, show_ended=False):
+        made = Tui.__new__(Tui)
+        made.show_ended = show_ended
+        return made.key_bar(width)
+
+    def test_everything_fits_on_a_wide_terminal(self):
+        wide = self.bar(250)
+        for key in ("up/down", "enter", "k", "b", "p", "e", "s", "S", "/", "?", "q"):
+            self.assertIn(key, wide.split())
+
+    def test_q_quit_survives_at_80_columns(self):
+        # this used to be the first casualty: the bar was 114 characters
+        bar = self.bar(80)
+        self.assertLessEqual(len(bar), 79)
+        self.assertIn("q quit", bar)
+
+    def test_it_never_exceeds_the_width_it_was_given(self):
+        for width in (250, 120, 100, 80, 60, 45, 40):
+            with self.subTest(width):
+                self.assertLessEqual(len(self.bar(width)), width - 1)
+
+    def test_ended_mode_changes_the_e_label(self):
+        self.assertIn("show ended", self.bar(250, show_ended=False))
+        self.assertIn("hide ended", self.bar(250, show_ended=True))
+
+
+class ConfirmationLayout(unittest.TestCase):
+    """The answer keys must survive truncation; the detail is what gives."""
+
+    def rendered(self, verb, detail, width):
+        prefix = f" [y] {verb}   [n] cancel"
+        room = width - 1 - len(prefix) - 3
+        return f"{prefix}   {detail[:room]}" if detail and room > 0 else prefix
+
+    def test_both_keys_are_present_at_every_realistic_width(self):
+        detail = ("in ~/projects/agent-ps/some/very/long/nested/directory, "
+                 "matched by directory")
+        for width in (250, 100, 80, 60, 45):
+            with self.subTest(width):
+                text = self.rendered("stop 7 processes", detail, width)
+                self.assertIn("[y]", text[:width - 1])
+                self.assertIn("[n]", text[:width - 1])
+
+    def test_the_verb_is_never_truncated_even_with_no_room_for_detail(self):
+        text = self.rendered("stop 7 processes", "somewhere far away", 30)
+        self.assertIn("stop 7 processes", text)
+
+
+class EmptyMessage(unittest.TestCase):
+    def make(self, filter_text="", show_ended=False, ended=0):
+        made = Tui.__new__(Tui)
+        made.filter_text = filter_text
+        made.show_ended = show_ended
+        made.history = {"ended": ended}
+        return made
+
+    def test_a_filter_with_no_matches_says_so(self):
+        said = self.make(filter_text="zzz").empty_message()
+        self.assertIn("/zzz", said)
+        self.assertIn("esc", said)
+
+    def test_hidden_ended_sessions_are_offered(self):
+        said = self.make(ended=12).empty_message()
+        self.assertIn("12", said)
+        self.assertIn("press e", said)
+
+    def test_nothing_at_all_points_at_agents_command(self):
+        said = self.make(show_ended=True).empty_message()
+        self.assertIn("agent-ps agents", said)
+
+    def test_a_filter_takes_priority_over_ended_sessions(self):
+        said = self.make(filter_text="zzz", ended=12).empty_message()
+        self.assertIn("zzz", said)
+        self.assertNotIn("12", said)
+
+
+class AgentStyle(unittest.TestCase):
+    """A colour that repeats must not look identical to the one before it."""
+
+    def test_the_eighth_agent_does_not_match_the_first_on_a_basic_terminal(self):
+        with mock.patch.object(curses, "COLORS", 8, create=True):
+            colour0, attr0 = ui._agent_style(0)
+            colour7, attr7 = ui._agent_style(7)
+            self.assertEqual(colour0, colour7, "the premise: colours do repeat")
+            self.assertNotEqual(attr0, attr7,
+                                "same colour, same attribute: indistinguishable")
+
+    def test_a_256_colour_terminal_gives_the_eighth_agent_its_own_colour(self):
+        with mock.patch.object(curses, "COLORS", 256, create=True):
+            colour0, _ = ui._agent_style(0)
+            colour7, _ = ui._agent_style(7)
+            self.assertNotEqual(colour0, colour7)
+
+
+class HelpOverlay(unittest.TestCase):
+    def test_every_key_in_the_bar_is_documented_somewhere(self):
+        # the bar can drop a key as the terminal narrows; the overlay must
+        # still say what it does
+        from agent_ps.ui import HELP
+        documented = " ".join(k for k, _ in HELP)
+        for key in ("k", "b", "p", "e", "s", "S", "/", "q", "space", "r"):
+            self.assertIn(key, documented)