workmap 0.1.0__py3-none-any.whl

workmap/tui/app.py

@@ -0,0 +1,1090 @@
+"""The Desk: screen state, key handling, and frame assembly."""
+from __future__ import annotations
+
+import os
+import select
+import sys
+import termios
+import tty
+
+from .. import actions, procs, scan, terminal
+from ..themes import PROFILE_ANSI
+from ..model import Project, Session, fmt_mb, fmt_mem, held_note, plural
+from ..config import SESSION_VISIBLE, roots_advice
+from ..model import clean_label
+from .text import (ALT_OFF, ALT_ON, AMBER, BOLD, BORDER, CLEAR_LINE, DIM, GOOD,
+                   HIDE, HOME, RESET, REV, SHOW, TAG, cell, disp_width, fg,
+                   pad_ansi, strip_ansi, visible_len, wrap_plain)
+from .widgets import (CHIP_W, META_GAP, PROJ_W, RAIL_OFF, RAIL_ON, RAIL_W,
+                      RAM_W, TABLE_MIN, THEME_W, box_bot, box_row, box_top,
+                      boxed, chip, cmd_cell, fit_strip, flat_panel,
+                      frame_width, inner_width, longest_label, panel,
+                      project_row, session_row, side_by_side)
+
+
+UNNAMED = "unsorted"  # projects with no root of their own
+
+
+def term_size() -> tuple[int, int]:
+    try:
+        sz = os.get_terminal_size()
+        return max(40, sz.columns), max(12, sz.lines)
+    except Exception:
+        return 80, 24
+
+
+class Desk:
+    def __init__(self) -> None:
+        self.projects: list[Project] = []
+        self.mem: dict = {}
+        self.tracked = 0
+        self.bg_all = 0  # orphan count from the last refresh (render must not rescan)
+        self.profiles: list[str] = []
+        self.cursor = 0  # index into projects, or -1 if nothing selected
+        self.scroll = 0  # first body line index into full body buffer
+        self.expanded: set[str] = set()
+        self.mode = "list"  # list | color
+        self.color_cursor = 0
+        self.message = ""
+        self.pending: str | None = None  # confirm: kill_bg | stop | close_wins
+        self._armed_sessions: list[Session] = []  # exactly what `y` will kill
+        self.blocked = ""  # why Terminal couldn't be read, if it couldn't
+        self.blocked_fix = ""  # and what the reader can do about that one
+        self.advice = ""   # why nothing can be an orphan, if nothing can
+        self.held = ""     # why something running is not on the desk
+        self._fd = sys.stdin.fileno()
+        self._old = None
+
+    # ------------------------------------------------------------------ data
+    def refresh_data(self) -> None:
+        """Full desk scan. Call on start / r / after mutating actions, never on ↑↓."""
+        keep = self.current().name if self.current() else None
+        cleared = self.cursor < 0
+        # One build_projects() pass (snapshot() would scan again for dict export).
+        held: list = []
+        self.projects = [p for p in scan.build_projects(held=held)
+                         if p.sessions]
+        # Immediately: every driver call writes the same status global, and
+        # list_profiles() below is cheaper than the desk query and can succeed
+        # where it failed. Reading afterwards erased the failure this field
+        # exists to report.
+        status = terminal.terminal_status()
+        self.mem = procs.mem_summary()
+        self.tracked = sum(p.mb for p in self.projects)
+        self.bg_all = sum(
+            1 for p in self.projects for s in p.sessions if s.kind == "bg"
+        )
+        self.profiles = [p["name"] for p in terminal.list_profiles()]
+        # An empty desk and a wedged Terminal look identical otherwise. So do
+        # an empty desk and a desk with no roots configured, where nothing can
+        # ever be an orphan.
+        self.blocked = "" if status["ok"] else status["reason"]
+        self.blocked_fix = "" if status["ok"] else status.get("fix", "")
+        self.advice = terminal.unsupported_host() or roots_advice()
+        # Why the desk is shorter than the machine, if it is.
+        self.held = held_note(held)
+        if cleared:
+            self.cursor = -1
+        elif keep is not None:
+            for i, p in enumerate(self.projects):
+                if p.name == keep:
+                    self.cursor = i
+                    break
+            else:
+                self.cursor = 0 if self.projects else -1
+        elif not self.projects:
+            self.cursor = -1
+        elif self.cursor >= len(self.projects):
+            self.cursor = len(self.projects) - 1
+        elif self.cursor < 0:
+            self.cursor = 0
+
+    def current(self) -> Project | None:
+        if self.cursor < 0 or not self.projects:
+            return None
+        if self.cursor >= len(self.projects):
+            return None
+        return self.projects[self.cursor]
+
+    def rail(self, profile: str) -> int:
+        return PROFILE_ANSI.get(profile, 250)
+
+    @staticmethod
+    def label_of(p: Project) -> str:
+        return p.name or UNNAMED
+
+    # --------------------------------------------------------------- commands
+    def always_items(self) -> list[tuple[str, str, str]]:
+        items = [
+            ("t", "rename all windows", "rename windows"),
+            ("O", "organize all", "organize all"),
+            ("r", "refresh", "refresh"),
+            ("q", "quit workmap", "quit"),
+        ]
+        if self.current() is None:
+            # Nothing selected: `k` means every project, and there is no
+            # selection to clear, so don't offer a key that does nothing.
+            count = f" {DIM}·{self.bg_all}{RESET}" if self.bg_all else ""
+            items.insert(1, ("k", "quit all orphans" + count,
+                             "quit orphans" + count))
+        else:
+            items.insert(3, ("Esc", "clear selection", "clear pick"))
+        return items
+
+    def project_items(self, p: Project) -> list[tuple[str, str, str]]:
+        bg_n = sum(1 for s in p.sessions if s.kind == "bg")
+        tag = f" {DIM}·{bg_n}{RESET}" if bg_n else ""
+        expanded = p.name in self.expanded
+        return [
+            ("f", "bring to front", "bring to front"),
+            ("o", "organize windows", "organize"),
+            ("c", "change theme", "change theme"),
+            ("x", "collapse sessions" if expanded else "expand sessions",
+             "collapse" if expanded else "expand"),
+            ("k", "quit orphans" + tag, "quit orphans" + tag),
+            ("s", "stop servers + orphans", "stop servers"),
+            ("w", "close windows", "close windows"),
+        ]
+
+    def _command_block(self, cols: int) -> list[str]:
+        """Always / For <project> as two distinct panels, stacked or side by side."""
+        frame = frame_width(cols)
+        inner = frame - 4
+        p = self.current()
+        always = self.always_items()
+        title_a = f"{DIM}Always{RESET}"
+        title_p = ""
+        if p is not None:
+            title_p = (
+                f"{DIM}For{RESET} {fg(self.rail(p.profile))}{BOLD}"
+                f"{self.label_of(p)}{RESET}"
+            )
+
+        if not boxed(cols):
+            w = inner_width(cols)
+            out = flat_panel(w, title_a, always, short=True)
+            if p is not None:
+                out += [""] + flat_panel(w, title_p, self.project_items(p),
+                                         short=True)
+            return out
+
+        if p is None:
+            block = panel(frame, title_a, always,
+                          columns=2 if inner >= 2 * (CHIP_W + 16) + 2 else 1)
+            if not self.projects:
+                return block
+            hint = "↑↓ pick a project for its own commands"
+            return block + [f"  {DIM}{cell(hint, max(0, cols - 2))}{RESET}"]
+
+        proj = self.project_items(p)
+        for short in (False, True):
+            need_a = 4 + CHIP_W + longest_label(always, short)
+            need_p = 4 + CHIP_W + longest_label(proj, short)
+            if need_a + 1 + need_p <= frame:
+                slack = frame - 1 - need_a - need_p
+                lw = need_a + slack // 2
+                rw = frame - 1 - lw
+                tall = max(len(always), len(proj))
+                return side_by_side(
+                    panel(lw, title_a, always, short=short, min_rows=tall), lw,
+                    panel(rw, title_p, proj, short=short, min_rows=tall), rw,
+                )
+        cols_n = 2 if inner >= 2 * (CHIP_W + longest_label(proj, True)) + 2 else 1
+        return (
+            panel(frame, title_a, always, columns=cols_n, short=True)
+            + panel(frame, title_p, proj, columns=cols_n, short=True)
+        )
+
+    # Both keys that answer, named. `_handle_list` takes Return for yes and
+    # Esc for cancel as well as the letters, and the screen used to offer
+    # only the letters: a keystroke that sends SIGTERM was on no screen
+    # anywhere. Setup has had the rule that a prompt names what Enter does
+    # since its first version; this is the prompt where it matters most.
+    CONFIRM_KEYS = (("y", "yes or Enter"), ("n", "cancel or Esc"))
+
+    def _confirm_block(self, cols: int) -> list[str]:
+        frame = frame_width(cols)
+        inner = frame - 4
+        if not boxed(cols):
+            w = inner_width(cols)
+            return (
+                [f" {AMBER}{BOLD}Confirm{RESET}"]
+                + [f" {ln}" for ln in wrap_plain(self.message, w - 1)]
+                + [" " + fit_strip(self.CONFIRM_KEYS, w - 1)]
+            )
+        lines = [box_top(inner, title=f"{AMBER}{BOLD}Confirm{RESET}")]
+        for line in wrap_plain(self.message, inner):
+            lines.append(box_row(inner, line))
+        for line in self._armed_preview(inner):
+            lines.append(box_row(inner, line))
+        lines.append(box_row(inner, ""))
+        keys = "".join(cmd_cell(k, label, CHIP_W + 13)
+                       for k, label in self.CONFIRM_KEYS)
+        lines.append(box_row(inner, keys))
+        lines.append(box_bot(inner))
+        return lines
+
+    # How many armed processes to name before summarising the rest.
+    PREVIEW_ROWS = 5
+
+    def _armed_preview(self, inner: int) -> list[str]:
+        """Name the processes `y` will signal.
+
+        A count and a size are not consent. The whole class of bug this tool
+        shipped with was killing the wrong thing while reporting a plausible
+        number, and a number is exactly what the user could not check.
+        """
+        rows: list[tuple[int, str]] = []
+        for s in self._armed_sessions:
+            for pid in s.pids:
+                rows.append((pid, s.cmds.get(pid) or s.label))
+        if not rows:
+            return []
+        # What the word means, here, where it is being acted on. The desk
+        # carries a legend saying it, and `_footer` returns this block
+        # instead of the legend, so the definition was on screen for as long
+        # as the reader was browsing and gone the moment they were asked.
+        # Same sentence `workmap kill -n` already prints above the same list.
+        why = "These have no Terminal window left to close:"
+        out = ["", f"{DIM}{cell(why, inner)}{RESET}"]
+        for pid, cmd in rows[: self.PREVIEW_ROWS]:
+            out.append(f"{DIM}{cell(f'{pid:>7}  {cmd}', inner)}{RESET}")
+        hidden = len(rows) - self.PREVIEW_ROWS
+        if hidden > 0:
+            # What the number counts, and how to reach the rest from here.
+            # It used to name `workmap kill -n` alone, which cannot be run
+            # from inside a full-screen program: a reader told there is more
+            # they cannot see, by a prompt they cannot leave, answers "no".
+            # The footer cannot scroll, so saying how to get out is the
+            # honest way to finish it.
+            more = f"+{hidden} more; press n and run `workmap kill -n`"
+            out.append(f"{DIM}{cell(more, inner)}{RESET}")
+        return out
+
+    def _compact_block(self, cols: int) -> list[str]:
+        """Short terminals: one command strip so the list keeps the screen."""
+        p = self.current()
+        if self.pending:
+            bits = list(self.CONFIRM_KEYS)
+        elif p is None:
+            bits = [("k", "quit all orphans"), ("t", "rename tabs"),
+                    ("r", "refresh"), ("q", "quit")]
+        else:
+            bits = [("f", "front"), ("k", "orphans"), ("c", "theme"),
+                    ("r", "refresh"), ("q", "quit")]
+        strip = fit_strip(bits, cols - 2)
+        head = (
+            f"{AMBER}{cell(self.message, cols - 2)}{RESET}" if self.pending else ""
+        )
+        return ([f" {head}"] if head else []) + [f" {strip}"]
+
+    # ----------------------------------------------------------------- render
+    def _headline(self) -> tuple[str, str]:
+        """The two figures the header exists to show, wherever it is drawn.
+
+        One function for both widths. The wide header was rewritten to drop
+        "tracked" and "free", and the narrow one was not, so a terminal under
+        46 columns still said "workmap · 2.1G tracked · free 214M" long after
+        the reasons for removing both were written down next door.
+
+        The second figure is empty when Terminal could not be read: an empty
+        desk and an unreadable one look identical from here, and "nothing
+        orphaned" is a claim about a machine nobody managed to look at.
+        """
+        held = f"{BOLD}{fmt_mb(self.tracked)}{RESET} {DIM}in use{RESET}"
+        if self.blocked:
+            return held, ""
+        orphan_mb = sum(s.mb for p in self.projects
+                        for s in p.sessions if s.kind == "bg")
+        # Amber only when there is something to reclaim, so the eye goes to it
+        # exactly when pressing `k` would do something.
+        freeable = (f"{AMBER}{fmt_mb(orphan_mb)} orphaned{RESET}" if orphan_mb
+                    else f"{DIM}nothing orphaned{RESET}")
+        return held, freeable
+
+    def _top_bar(self, inner: int) -> str:
+        """Two numbers worth having, in words that mean something.
+
+        This used to read "2.1G tracked   free 214M   swap 6.5G", which is
+        three figures a reader cannot act on. "tracked" is an internal word for
+        the sum of what happens to be on screen. Worse, macOS keeps free
+        memory deliberately low, so "free 214M" looks alarming on a machine
+        that is perfectly happy, and reading it as a problem is the wrong
+        lesson to teach on the first screen.
+
+        What is worth knowing is how much the sessions are holding, and how
+        much of that is already dead and can be had back. The second number is
+        the one the whole tool exists to produce.
+        """
+        held, freeable = self._headline()
+        swap_raw = self.mem.get("swap_mb", "?")
+        try:
+            swap_warn = float(swap_raw) > 3000
+        except (TypeError, ValueError):
+            swap_warn = False
+        swap_bit = f"{AMBER if swap_warn else DIM}swap {fmt_mem(swap_raw)}{RESET}"
+        title = f"{BOLD}workmap{RESET}"
+        stats = [
+            f"{held}   {freeable}   {swap_bit}" if freeable else
+            f"{held}   {swap_bit}",
+            f"{held}   {freeable}" if freeable else f"{held}",
+            f"{held}",
+        ]
+        for tail in stats:
+            if 4 + visible_len(title) + visible_len(tail) + 4 <= inner + 2:
+                return box_top(inner, title=title, tail=tail)
+        return box_top(inner, title=title)
+
+    def _column_head(self, inner: int) -> str:
+        gutter = max(META_GAP, inner - TABLE_MIN + META_GAP)
+        return (
+            " " * RAIL_W
+            + DIM
+            + cell("PROJECT", PROJ_W)
+            + " "
+            + cell("THEME", THEME_W)
+            + " " * gutter
+            + cell("RAM", RAM_W, align="right")
+            + RESET
+        )
+
+    def _header_lines(self, cols: int) -> list[str]:
+        inner = inner_width(cols)
+        p = self.current()
+        if not boxed(cols):
+            if self.mode == "color":
+                who = self.label_of(p) if p else ""
+                return [f"{BOLD}Theme{RESET} {DIM}for{RESET} {BOLD}{who}{RESET}",
+                        DIM + "─" * inner + RESET]
+            held, freeable = self._headline()
+            head = f"{BOLD}workmap{RESET}  {held}"
+            if freeable and visible_len(head) + visible_len(freeable) + 3 <= inner:
+                head = f"{head}   {freeable}"
+            if not self.projects:
+                return [head, DIM + "─" * inner + RESET]
+            return [head, self._column_head(inner)]
+        if self.mode == "color":
+            who = self.label_of(p) if p else ""
+            return [
+                box_top(inner, title=f"{BOLD}Theme{RESET}",
+                        tail=f"{DIM}for{RESET} {BOLD}{who}{RESET}" if who else ""),
+                box_row(inner, f"{DIM}↑↓ choose   Enter apply   Esc cancel{RESET}"),
+            ]
+        if not self.projects:  # no rows to head
+            return [self._top_bar(inner)]
+        return [self._top_bar(inner), box_row(inner, self._column_head(inner))]
+
+    def _project_block(self, p: Project, selected: bool,
+                       inner: int) -> list[str]:
+        # The colour rail is the project's theme; it thickens on selection so
+        # the highlight reads without touching column positions.
+        c = self.rail(p.profile)
+        rail = fg(c) + (RAIL_ON if selected else RAIL_OFF) + RESET
+        name = self.label_of(p)
+        out = [
+            project_row(name, p.profile, fmt_mb(p.mb), inner,
+                        rail=rail, selected=selected)
+        ]
+
+        show_all = p.name in self.expanded
+        visible = p.sessions if show_all else p.sessions[: SESSION_VISIBLE]
+        hidden = 0 if show_all else max(0, len(p.sessions) - SESSION_VISIBLE)
+
+        for j, s in enumerate(visible):
+            last = j == len(visible) - 1 and hidden == 0
+            branch = "└─" if last else "├─"
+            # A window is the norm and goes unmarked; only flag the exception,
+            # in the same word the command uses: an "orphan" is what `k` quits.
+            where = "" if s.kind == "window" else "orphaned"
+            label = clean_label(s.label.replace("\n", " "))
+            out.append(session_row(rail, f" {branch} {label}", where,
+                                   fmt_mb(s.mb), inner))
+        if hidden:
+            out.append(session_row(rail, f" └─ +{hidden} more", "x to show",
+                                   "", inner))
+        return out
+
+    def _color_body(self, inner: int) -> list[str]:
+        p = self.current()
+        if not p:
+            return [f"{DIM}No project selected.{RESET}"]
+        names = self.profiles or list(PROFILE_ANSI.keys())
+        lines = []
+        for i, name in enumerate(names):
+            c = self.rail(name)
+            cur = i == self.color_cursor
+            check = "●" if name == p.profile else "○"
+            body = f"{fg(c)}{check}{RESET} " + cell(name, max(1, inner - 5))
+            lines.append(f" {REV} {RESET} {body}" if cur else f"   {body}")
+        return lines
+
+    def _build_body(self, cols: int) -> tuple[list[str], list[tuple[int, int]]]:
+        """The scrollable region, and where each project sits inside it.
+
+        The spans come back with the lines rather than being left on the
+        instance: scrolling needs to know where the selected project starts,
+        and reading that from state written by the *last* render is only
+        correct as long as nobody reorders draw(). Returning it removes the
+        rule instead of documenting it.
+        """
+        inner = inner_width(cols)
+        if self.mode == "color":
+            return self._color_body(inner), []
+        if not self.projects:
+            if self.blocked:
+                # The follow-up belongs to the reason. Only one of the
+                # driver's failures is a permission problem, and these lines
+                # sent everyone to Automation whatever had gone wrong.
+                # Wrapped, not cut. This is the one screen whose whole job
+                # is an instruction, and the instruction is 65 columns while
+                # the panel is 62, so it arrived as "... > Automat..." at
+                # every terminal size. The word it lost was the name of the
+                # pane the reader has to go and find.
+                fix = getattr(self, "blocked_fix", "")
+                said = [f"{DIM}{ln}{RESET}"
+                        for ln in wrap_plain(f"{self.blocked}.", inner)]
+                said += [f"{DIM}{ln}{RESET}"
+                         for ln in wrap_plain(fix, inner)] if fix else []
+                return [
+                    "",
+                    f"{AMBER}{BOLD}Can't read Terminal{RESET}",
+                    "",
+                ] + said + [
+                    f"{DIM}Press{RESET} {BOLD}r{RESET}{DIM} to try again.{RESET}",
+                    "",
+                ], []
+            msg = self.message or "Nothing open right now"
+            # Only ever name things this package ships. This used to say
+            # "Start one with `work <name>`", which was a shell function on the
+            # author's machine, not part of workmap and not installable with
+            # it. The empty desk is the first screen a new user sees, which
+            # makes it the worst possible place to point at something that
+            # does not exist for them.
+            return [
+                "",
+                f"{BOLD}{msg}{RESET}",
+                "",
+                f"{DIM}Open a Terminal window in a project directory,{RESET}",
+                f"{DIM}then press{RESET}  {BOLD}r{RESET}  {DIM}to remap the desk{RESET}",
+                "",
+            ], []
+        body: list[str] = []
+        spans: list[tuple[int, int]] = []
+        for i, p in enumerate(self.projects):
+            if body:
+                body.append("")  # one breath between projects, none at the ends
+            start = len(body)
+            body.extend(self._project_block(p, i == self.cursor, inner))
+            spans.append((start, len(body)))
+        return body, spans
+
+    def _scroll_for(self, body_len: int, view_h: int,
+                    spans: list[tuple[int, int]]) -> int:
+        """Where the viewport has to sit for the selection to be on screen."""
+        scroll = self.scroll
+        def clamp(v: int) -> int:
+            return max(0, min(v, max(0, body_len - view_h)))
+        if view_h <= 0:
+            return scroll
+        if self.mode == "color":
+            row = self.color_cursor
+            if row < scroll:
+                scroll = row
+            elif row >= scroll + view_h:
+                scroll = row - view_h + 1
+            return clamp(scroll)
+        if self.cursor < 0 or not (0 <= self.cursor < len(spans)):
+            return clamp(scroll)
+        start, end = spans[self.cursor]
+        if start < scroll:
+            scroll = start
+        elif end > scroll + view_h:
+            # Never past the project's own row. It carries the name, the theme
+            # and the total, and a project with more sessions than the viewport
+            # has lines used to scroll all three off the top so that its last
+            # session could be on screen: you were looking at rows belonging to
+            # something the screen no longer named.
+            scroll = min(start, max(0, end - view_h))
+        if start >= scroll + view_h:
+            scroll = start
+        return clamp(scroll)
+
+    def _footer(self, cols: int) -> list[str]:
+        if self.mode == "color":
+            return []
+        if self.pending:
+            return [""] + self._confirm_block(cols)
+        # Wrapped rather than cut. Every one of these is a sentence written
+        # to explain something, and at Terminal's own 80 columns they were
+        # all cut at about the point the explanation started: "Closed 2 of 3
+        # windows for acme-api. Terminal is asking about what's still run…"
+        # is the reader left with a window that would not close and a
+        # sentence that stops mid-word.
+        def said(text, colour):
+            return [f" {colour}{ln}{RESET}"
+                    for ln in wrap_plain(text, max(1, cols - 2))]
+
+        if self.blocked and self.projects:
+            note = said(self.blocked, AMBER)
+        elif self.advice and not self.message:
+            note = said(self.advice, AMBER)
+        elif self.message and self.projects:
+            note = said(self.message, GOOD)
+        elif self.held:
+            # Above the legend, because the legend explains a word that is on
+            # screen and this explains something that is not. A desk with
+            # nothing on it and a desk whose orphans are all inside a tmux
+            # pane drew the same picture.
+            note = said(self.held, AMBER)
+        elif self.bg_all:
+            # The row above the commands was a blank line for spacing. It is
+            # better spent saying what the word on those rows means: the first
+            # person shown this screen asked what a marked row was, and there
+            # was nowhere on it that said.
+            legend = ("orphaned: still running, with no Terminal window left "
+                      "to close")
+            note = said(legend, DIM)
+        else:
+            note = [""]  # one breath between the map and its commands
+        return note + self._command_block(cols)
+
+    def _fit_footer(self, cols: int, rows: int, chrome: int,
+                    body_n: int) -> list[str]:
+        """Full panels only when a real list still fits above them."""
+        full = self._footer(cols)
+        compact = self._compact_block(cols) if self.mode != "color" else []
+        # A confirmation is modal: _handle_list ignores every other key while
+        # one is up, so there is no list behind it worth keeping. Budgeting it
+        # like ordinary footer chrome meant that at Terminal's own default
+        # 80x24, arming "quit all 24 orphans" dropped the panel naming them and
+        # asked for a SIGKILL against a count and a size. That is precisely
+        # what _armed_preview exists to prevent.
+        if self.pending and chrome + len(full) + 1 <= rows:
+            return full
+        min_body = min(10, max(3, body_n))
+        if chrome + len(full) + min_body <= rows:
+            return full
+        if compact and chrome + len(compact) + 1 <= rows:
+            return compact
+        if self.mode == "color":
+            return []
+        return [f" {chip('q', 3)} quit  {chip('r', 3)} refresh"]
+
+    def draw(self) -> None:
+        """Paint one frame. Always paints something.
+
+        Composing the frame touches every formatting path in the package. If
+        one of them raises, a blank screen is the worst possible answer: the
+        user is left with a frozen desk and no way to tell whether the tool is
+        working. Show the error and keep the keys live instead.
+        """
+        cols, rows = term_size()
+        try:
+            frame_lines = self._compose(cols, rows)
+        except (KeyboardInterrupt, SystemExit):
+            raise
+        except Exception as exc:  # noqa: BLE001 - see docstring
+            frame_lines = self._error_frame(exc, cols)
+
+        out = [HOME, HIDE]
+        for r in range(rows):
+            out.append(f"\033[{r + 1};1H{CLEAR_LINE}")
+            if r < len(frame_lines):
+                out.append(pad_ansi(frame_lines[r], cols).rstrip() + RESET)
+        sys.stdout.write("".join(out))
+        sys.stdout.flush()
+
+    def _error_frame(self, exc: Exception, cols: int) -> list[str]:
+        """The last-resort screen: plain strings, no layout helpers."""
+        return [
+            f"{AMBER}{BOLD}workmap hit an error drawing this screen{RESET}",
+            "",
+            f"{DIM}{type(exc).__name__}: {exc}{RESET}"[: cols + 20],
+            "",
+            f"{BOLD}r{RESET}{DIM} to rescan   {RESET}{BOLD}q{RESET}{DIM} to quit{RESET}",
+        ]
+
+    def _compose(self, cols: int, rows: int) -> list[str]:
+        inner = inner_width(cols)
+        narrow = not boxed(cols)
+
+        header = self._header_lines(cols)
+        body, spans = self._build_body(cols)
+        close = [] if narrow else [box_bot(inner)]
+        footer = self._fit_footer(cols, rows, len(header) + len(close), len(body))
+
+        view_h = max(1, rows - len(header) - len(close) - len(footer))
+        self.scroll = self._scroll_for(len(body), view_h, spans)
+
+        window = body[self.scroll : self.scroll + view_h]
+        more_below = self.scroll + len(window) < len(body)
+        more_above = self.scroll > 0
+        hint = ("↑" if more_above else " ") + ("↓" if more_below else " ")
+        if close and (more_above or more_below):
+            close = [box_bot(inner, tail=f"{DIM}{hint.strip()} more{RESET}")]
+
+        rendered = (
+            [pad_ansi(ln, inner) for ln in window] if narrow
+            else [box_row(inner, ln) for ln in window]
+        )
+        if narrow and (more_above or more_below):
+            # The hint rides the bottom edge, and a narrow terminal has no
+            # edges. Without this the list simply stopped, with nothing saying
+            # there was more of it: the one place the desk can hide a project
+            # is the one place it never said so.
+            rendered = rendered[:-1] + [
+                f"{DIM}{hint.strip()} more{RESET}"] if len(rendered) > 1 else rendered
+        return header + rendered + close + footer
+
+    # ------------------------------------------------------------------ input
+    def run(self) -> None:
+        self._old = termios.tcgetattr(self._fd)
+        sys.stdout.write(ALT_ON + HIDE)
+        sys.stdout.flush()
+        try:
+            tty.setcbreak(self._fd)
+            # Paint immediately so large windows aren't a blank void during scan.
+            self.message = "Scanning Terminal…"
+            self.draw()
+            self._guard(self.refresh_data)
+            if self.message == "Scanning Terminal…":
+                self.message = ""
+            while True:
+                self._guard(self.draw)
+                try:
+                    key = self._read_key()
+                except (KeyboardInterrupt, SystemExit):
+                    raise
+                except Exception:
+                    # No way left to read the keyboard, so there is no way for
+                    # the user to quit. Leaving is the only honest response.
+                    break
+                if not self._guard(self._handle_key, key, default=True):
+                    break
+        except KeyboardInterrupt:
+            pass
+        finally:
+            if self._old is not None:
+                termios.tcsetattr(self._fd, termios.TCSADRAIN, self._old)
+            sys.stdout.write(ALT_OFF + SHOW + RESET)
+            sys.stdout.flush()
+
+    def _handle_key(self, key: str) -> bool:
+        """Dispatch one key, then say anything the action left to be said.
+
+        The notice is picked up here rather than inside `t`, `o` and `O`
+        because it belongs to the run and not to the key: three keys reach the
+        profile rewrite today, and the fourth will be added by somebody who
+        has not read this. It is appended rather than substituted, so pressing
+        `t` still tells you how many windows were renamed.
+        """
+        handle = (self._handle_color if self.mode == "color"
+                  else self._handle_list)
+        alive = handle(key)
+        notice = actions.take_title_notice()
+        if notice:
+            self.message = f"{self.message} {notice}".strip()
+        return alive
+
+    def _guard(self, fn, *args, default=None):
+        """Run one step of the loop; survive anything it raises.
+
+        Every refresh shells out to ps, lsof, top and AppleScript. A single
+        malformed line or an OS hiccup used to end the session with a
+        traceback, which for a tool you leave open all day is the difference
+        between a blip and losing your place. Errors become a message on the
+        bar; the loop keeps going so `r` and `q` still work.
+
+        SystemExit and KeyboardInterrupt are deliberately not caught: those
+        are someone asking to leave.
+        """
+        try:
+            return fn(*args)
+        except (KeyboardInterrupt, SystemExit):
+            raise
+        except Exception as exc:  # noqa: BLE001 - a TUI must not die here
+            self.pending = None
+            self._armed_sessions = []
+            self.message = f"{type(exc).__name__}: {exc}"[:200] or "error"
+            return default
+
+    def _read_key(self) -> str:
+        ch = os.read(self._fd, 1)
+        if ch == b"\x1b":
+            rest = b""
+            if select.select([self._fd], [], [], 0.05)[0]:
+                rest += os.read(self._fd, 8)
+            if rest.startswith(b"[A"):
+                return "up"
+            if rest.startswith(b"[B"):
+                return "down"
+            if rest.startswith(b"[C"):
+                return "right"
+            if rest.startswith(b"[D"):
+                return "left"
+            return "esc"
+        try:
+            return ch.decode()
+        except Exception:
+            return ""
+
+    def _move(self, delta: int) -> None:
+        n = len(self.projects)
+        if n == 0:
+            self.cursor = -1
+            return
+        if self.cursor < 0:
+            self.cursor = 0 if delta > 0 else n - 1
+        else:
+            self.cursor = (self.cursor + delta) % n
+        self.pending = None
+
+    def _drop_what_was_typed_before_the_question(self) -> None:
+        """Throw away input that arrived before this prompt was on screen.
+
+        _read_key takes one byte at a time out of whatever the tty already
+        holds, so two adjacent bytes of a paste were a whole authorisation:
+        `s`, `w` or `k` arms, and the Return that ends any pasted command line
+        answers yes. Nobody read the prompt, because it had not been drawn
+        yet. Pasting `git status` and a newline into the desk was enough.
+
+        An answer has to be typed after the question, so anything already
+        queued when it goes up is not an answer to it.
+        """
+        fd = getattr(self, "_fd", None)
+        if fd is None:
+            return
+        try:
+            while select.select([fd], [], [], 0)[0]:
+                if not os.read(fd, 4096):
+                    break
+        except (OSError, ValueError):
+            pass
+
+    def _arm(self, kind: str, message: str,
+             sessions: list[Session] | None = None) -> None:
+        # Pin the sessions now: `y` must kill what the prompt just quoted.
+        self.pending = kind
+        self.message = message
+        self._armed_sessions = list(sessions or [])
+        self._drop_what_was_typed_before_the_question()
+
+    def _cancel_pending(self) -> None:
+        self.pending = None
+        self._armed_sessions = []
+        self.message = "Cancelled, nothing was quit"
+
+    def _confirm_pending(self) -> None:
+        kind = self.pending
+        self.pending = None
+        p = self.current()
+        if kind == "kill_bg_all":
+            result = actions.kill_sessions(self._armed_sessions,
+                                           reason="orphans:all")
+            self.refresh_data()
+            self.message = (
+                f"Quit {plural(result['sessions'], 'orphan')} across every "
+                f"project, freeing about {fmt_mb(result['mb'])}"
+            )
+            return
+        if kind == "kill_bg" and p:
+            result = actions.kill_sessions(self._armed_sessions,
+                                           reason=f"orphans:{p.name}")
+            self.refresh_data()
+            self.message = (
+                f"Quit {plural(result['sessions'], 'orphan')} on "
+                f"{self.label_of(p)}, freeing about {fmt_mb(result['mb'])}"
+            )
+            return
+        if kind == "stop" and p:
+            result = actions.stop_project_stack(p.name, projects=self.projects)
+            quit_n = result["background"]["sessions"]
+            self.refresh_data()
+            if result["servers_stopped"]:
+                self.message = (f"Stopped the servers and "
+                                f"{plural(quit_n, 'orphan')} on "
+                                f"{self.label_of(p)}.")
+            else:
+                # `devstack` is a separate tool this key asks to bring servers
+                # down, and it is named nowhere a user would have read. Say
+                # what happened to them, not what the program is called.
+                why = result["reason"]
+                if not why:
+                    note = "There were no servers to stop."
+                elif why == "devstack not installed":
+                    note = ("No server manager is installed, so only the "
+                            "orphans were quit.")
+                elif why == "devstack timed out":
+                    note = ("The server manager took too long, so only the "
+                            "orphans were quit.")
+                else:
+                    note = f"The server manager could not stop them: {why}."
+                self.message = (f"Quit {plural(quit_n, 'orphan')} on "
+                                f"{self.label_of(p)}. {note}")
+            return
+        if kind == "close_wins" and p:
+            asked = list(p.window_ids)
+            n = actions.close_project_windows(p.name, projects=self.projects)
+            # Before the refresh, which runs its own queries over the same
+            # status global. close_windows() answers 0 both for "none of them
+            # closed" and for "Terminal never answered", and only one of those
+            # means Terminal is holding a sheet open.
+            asked_ok = terminal.terminal_status()
+            self.refresh_data()
+            if not asked_ok["ok"]:
+                self.message = (f"Couldn't ask Terminal to close those "
+                                f"windows: {asked_ok['reason']}.")
+                return
+            # Which of them are still there, asked fresh, rather than
+            # `asked - n`. A window id comes off the last scan, so one of
+            # them can have been closed by hand between that scan and this
+            # keypress: it is a window that had already gone, not a window
+            # Terminal is holding a sheet over, and saying otherwise points
+            # the reader at a dialog that is not on their screen.
+            after = next((q for q in self.projects if q.name == p.name), None)
+            waiting = len(set(asked) & set(after.window_ids)) if after else 0
+            if waiting:
+                # Terminal is holding a sheet open on these, asking whether to
+                # terminate what is running in them. Saying so beats a number
+                # that does not match what is on screen.
+                self.message = (
+                    f"Closed {n} of {plural(len(asked), 'window')} for "
+                    f"{self.label_of(p)}. Terminal is asking about what's "
+                    f"still running in the other {waiting}."
+                )
+            else:
+                self.message = (
+                    f"Closed {plural(n, 'Terminal window')} for "
+                    f"{self.label_of(p)}.")
+            return
+        self.message = ""
+
+    def _handle_list(self, key: str) -> bool:
+        if self.pending:
+            if key in ("y", "Y", "\r", "\n"):
+                self._confirm_pending()
+                return True
+            if key in ("n", "N", "esc"):
+                self._cancel_pending()
+                return True
+            if key not in ("up", "down"):
+                return True  # modal: ignore everything else
+            # Navigating away is a decision too, so drop the prompt and move on.
+            # Only ever resolves toward "don't kill anything".
+            self._cancel_pending()
+            self.message = ""
+
+        if key in ("q", "Q", "\x03"):
+            return False
+        if key == "esc":
+            self.cursor = -1
+            self.message = ""
+            self.pending = None
+            return True
+        if key in ("r", "R"):
+            self.refresh_data()
+            self.message = "Remapped the desk"
+            return True
+        if key == "up":
+            self._move(-1)
+            self.message = ""
+            return True
+        if key == "down":
+            self._move(1)
+            self.message = ""
+            return True
+
+        p = self.current()
+
+        # General commands (footer), nothing to do with the selection
+        if key == "t":
+            n = actions.retitle_all(projects=self.projects)
+            self.refresh_data()
+            self.message = (f"Renamed {plural(n, 'Terminal window')} to "
+                            f"project + what.")
+            return True
+
+        if key in ("k", "K"):
+            # One key, one meaning: selected project → that project only;
+            # nothing selected → all orphans. (No overlapping k / K.)
+            if p is not None:
+                sessions = [s for s in p.sessions if s.kind == "bg"]
+                if not sessions:
+                    self.message = (f"Nothing on {self.label_of(p)} is "
+                                    f"running without a window")
+                    return True
+                mb = sum(s.mb for s in sessions)
+                self._arm(
+                    "kill_bg",
+                    f"Quit {plural(len(sessions), 'orphan')} on "
+                    f"{self.label_of(p)}, holding about {fmt_mb(mb)}?",
+                    sessions,
+                )
+                return True
+            sessions = [
+                s for proj in self.projects for s in proj.sessions if s.kind == "bg"
+            ]
+            if not sessions:
+                self.message = ("Nothing anywhere is running without a "
+                                "window, so there is nothing to quit")
+                return True
+            mb = sum(s.mb for s in sessions)
+            self._arm(
+                "kill_bg_all",
+                f"Quit all {plural(len(sessions), 'orphan')}, across every "
+                f"project, holding about {fmt_mb(mb)}?",
+                sessions,
+            )
+            return True
+
+        if key == "O":
+            result = actions.organize_all(projects=self.projects)
+            self.refresh_data()
+            if not result.get("ok"):
+                self.message = (f"Nothing to lay out: "
+                                f"{result.get('reason', 'no Terminal windows')}.")
+            else:
+                self.message = (
+                    f"Laid out {plural(result.get('projects', 0), 'project')}, "
+                    f"each in its own region of the screen"
+                )
+                stuck = actions.stuck_words(result)
+                if stuck:
+                    self.message = f"{self.message}. {stuck}"
+            return True
+
+        # Project-only commands
+        if not p:
+            return True
+
+        if key in ("f", "F"):
+            if p.window_ids:
+                actions.focus_project(p)
+                self.message = f"Brought {self.label_of(p)} to the front"
+            else:
+                self.message = (f"{self.label_of(p)} has no Terminal "
+                                f"windows open")
+            return True
+        if key == "o":
+            if not p.window_ids:
+                self.message = (f"{self.label_of(p)} has no Terminal "
+                                f"windows to lay out.")
+                return True
+            result = actions.organize_project(p.name, projects=self.projects)
+            self.refresh_data()
+            if not result.get("ok"):
+                self.message = (f"Nothing to lay out for {self.label_of(p)}: "
+                                f"{result.get('reason', 'no Terminal windows')}.")
+            elif result.get("merged"):
+                self.message = f"Gathered {self.label_of(p)} into one window"
+            else:
+                stuck = actions.stuck_words(result)
+                if stuck:
+                    self.message = (
+                        f"Laid out {result.get('placed', 0)} of "
+                        f"{plural(result.get('windows', 0), 'window')} for "
+                        f"{self.label_of(p)}. {stuck}"
+                    )
+                else:
+                    self.message = (
+                        f"Laid out {plural(result.get('windows', 0), 'window')} "
+                        f"for {self.label_of(p)}"
+                    )
+            return True
+        if key in ("c", "C"):
+            self.mode = "color"
+            self.scroll = 0
+            try:
+                self.color_cursor = self.profiles.index(p.profile)
+            except ValueError:
+                self.color_cursor = 0
+            self.message = ""
+            return True
+        if key in ("x", "X", " "):
+            if p.name in self.expanded:
+                self.expanded.discard(p.name)
+            else:
+                self.expanded.add(p.name)
+            return True
+        if key in ("s", "S"):
+            n = sum(1 for s in p.sessions if s.kind == "bg")
+            self._arm(
+                "stop",
+                f"Stop {self.label_of(p)}'s servers and quit its "
+                f"{plural(n, 'orphan')}?",
+                [s for s in p.sessions if s.kind == "bg"],
+            )
+            return True
+        if key in ("w", "W"):
+            if not p.window_ids:
+                self.message = (f"{self.label_of(p)} has no Terminal "
+                                f"windows to close")
+                return True
+            self._arm(
+                "close_wins",
+                # Not "nothing is lost": closing a window does end what is
+                # running in it, which is exactly why Terminal puts up a sheet
+                # first. Say who asks and when.
+                f"Close {plural(len(p.window_ids), 'Terminal window')} for "
+                f"{self.label_of(p)}? Terminal will ask before ending "
+                f"anything still running.",
+            )
+            return True
+        return True
+
+    def _handle_color(self, key: str) -> bool:
+        names = self.profiles or list(PROFILE_ANSI.keys())
+        if key in ("esc", "q", "Q"):
+            self.mode = "list"
+            self.scroll = 0
+            return True
+        if key == "up":
+            self.color_cursor = (self.color_cursor - 1) % max(1, len(names))
+            return True
+        if key == "down":
+            self.color_cursor = (self.color_cursor + 1) % max(1, len(names))
+            return True
+        if key in ("\r", "\n", " "):
+            p = self.current()
+            if p and names:
+                profile = names[self.color_cursor]
+                actions.set_project_profile(p.name, profile, apply=True,
+                                         projects=self.projects)
+                self.refresh_data()
+                self.message = f"{self.label_of(p)} is now {profile}"
+            self.mode = "list"
+            self.scroll = 0
+            return True
+        return True
+
+
+class NoTerminalToDrawOn(Exception):
+    """There is no terminal here, or there is one that will not go raw.
+
+    Carried to the caller rather than handled here. Falling back to the text
+    snapshot meant this module importing cli, which is the top layer reaching
+    back into an entry point: the one dependency the layer order forbids and
+    the layering test could not see, because `cli` is not one of the layers.
+    Deciding what to do instead of the map is the entry point's job.
+    """
+
+
+def run() -> int:
+    """Draw the interactive map.
+
+    Raises NoTerminalToDrawOn if this is not a terminal it can take over.
+    """
+    if not sys.stdin.isatty():
+        raise NoTerminalToDrawOn(
+            "The map needs a terminal to draw on, and this is being piped. "
+            "Here it is as text; `workmap list` prints the same thing without "
+            "this line.")
+    try:
+        Desk().run()
+    except (termios.error, OSError) as exc:
+        # isatty() said yes but the terminal will not go raw: a pty that does
+        # not support it, a detached session, some CI shells.
+        raise NoTerminalToDrawOn(
+            f"workmap could not take this terminal over ({exc}). "
+            f"Here is the same map as text.") from exc
+    return 0