workmap 0.1.0__py3-none-any.whl

workmap/model.py

@@ -0,0 +1,719 @@
+"""Data shapes, and what a process is.
+
+Nothing here runs a program, signals one, or touches a disk, which is the
+property that matters: the rules that decide what a process *is* are the rules
+that decide what gets killed, and they are worth being able to test without a
+machine underneath them. Every function here is a total function of its
+arguments, with no exception. There used to be one, project_from_path(), which
+resolved paths and read the configured roots: deciding which project a
+directory belongs to is a question about a disk, so it has gone to config.py
+where the disk already lives. See config.ProjectIndex.
+
+Two questions are answered here and they are worth keeping apart. What kind of
+work a process is doing, which is classify_cmd() and the rules around it. And
+what still has a claim on it, which is Hold."""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .config import SESSION_VISIBLE
+from .themes import PROFILE_SWATCHES
+
+
+@dataclass
+
+
+class Session:
+    kind: str
+    label: str
+    mb: int
+    window_id: int | None = None
+    tty: str | None = None
+    title: str = ""
+    profile: str | None = None
+    pids: list[int] = field(default_factory=list)
+    # What each pid was running when the scan saw it. For the audit log and
+    # the confirmation prompt: this is description, not identity.
+    cmds: dict[int, str] = field(default_factory=dict)
+    # When each pid started. This *is* identity. A scan can sit on screen for
+    # hours before someone presses `k`, and macOS recycles pids, so it is
+    # rechecked at kill time. See procs.still_the_same().
+    starts: dict[int, str] = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return {
+            "kind": self.kind,
+            "label": self.label,
+            "mb": self.mb,
+            "window_id": self.window_id,
+            "tty": self.tty,
+            "title": self.title,
+            "profile": self.profile,
+        }
+
+
+@dataclass
+
+
+class Project:
+    name: str
+    path: Path | None
+    sessions: list[Session] = field(default_factory=list)
+    profile: str = "Basic"
+
+    @property
+    def mb(self) -> int:
+        return sum(s.mb for s in self.sessions)
+
+    @property
+    def window_ids(self) -> list[int]:
+        seen: list[int] = []
+        for s in self.sessions:
+            if s.window_id is not None and s.window_id not in seen:
+                seen.append(s.window_id)
+        return seen
+
+    def to_dict(self) -> dict:
+        sw = PROFILE_SWATCHES.get(self.profile, PROFILE_SWATCHES["Basic"])
+        visible = self.sessions[:SESSION_VISIBLE]
+        hidden = self.sessions[SESSION_VISIBLE:]
+        return {
+            "name": self.name,
+            "path": str(self.path) if self.path else None,
+            "mb": self.mb,
+            "profile": self.profile,
+            "swatch": sw,
+            "window_ids": self.window_ids,
+            "window_count": len(self.window_ids),
+            "session_count": len(self.sessions),
+            "sessions": [s.to_dict() for s in visible],
+            "hidden_sessions": [s.to_dict() for s in hidden],
+            "hidden_count": len(hidden),
+        }
+
+
+def tty_short(tty: str) -> str:
+    return tty.replace("/dev/", "") if tty else ""
+
+
+@dataclass(frozen=True)
+class Hold:
+    """A live thing with a claim on a process, and why it has one.
+
+    The orphan sweep asks one question of every process it recognises: is
+    there still a way back to this. A hold is a yes, and the shape of the yes
+    matters, because the three that exist are not the same kind of fact:
+
+      app          it belongs to a running application, so it was never a
+                   terminal session at all. Quitting it is useless, the
+                   application respawns it, and harmful, it force-quits part
+                   of something live.
+      window       a Terminal window has it. Somebody is sitting there.
+      pane         a multiplexer pane has it. Somebody can sit there: a
+                   detached session is still one `tmux attach` away, which is
+                   exactly what an orphan is not.
+      multiplexer  a multiplexer is running and could not be asked what it is
+                   holding, so it is treated as holding everything under it.
+
+    That last one is the reason this is a record rather than the set of pids
+    it replaced. A set can say "held" and "not held" and cannot say "I could
+    not find out", so the code answered the third case by permanently treating
+    every multiplexer server as a pane. Naming it makes the fallback both
+    conservative and temporary: the moment tmux answers, the server stops
+    holding anything and its panes hold their own.
+
+    `why` is a sentence rather than a code because the desk shows it. It is
+    written to follow a count: "2 processes are ...".
+
+    `needs_tty` narrows a claim to the processes its holder is *showing*. It
+    exists for one measured shape: a tmux server that answered gives a pty to
+    everything it displays and to nothing it merely runs, so a `run-shell -b`
+    job comes back with no controlling terminal (measured: tty `??`) while
+    everything in a pane has one. Without it, removing the server's blanket
+    claim would also uncover a `display-popup` job, which is on somebody's
+    screen at the time.
+    """
+    pid: int
+    kind: str
+    why: str
+    needs_tty: bool = False
+
+
+# Every kind, least specific first. Which claim a pid keeps when two of them
+# reach it is decided by this order and not by which line ran last.
+SPECIFIC = ("app", "window", "multiplexer", "shown", "pane")
+
+# Holds worth telling the reader about: the ones whose holder is not itself on
+# the desk. Every Terminal window is already a row, and an application is not
+# workmap's business, so naming either would be noise. Everything a
+# multiplexer holds is neither shown nor out of scope, which makes it the one
+# case where "nothing here" and "hidden because something has it" look
+# identical and are not. A kind not listed here says nothing, which is the
+# right default for one nobody has thought about yet.
+REPORTABLE_HOLDS = frozenset({"pane", "shown", "multiplexer"})
+
+
+def strongest(seen: "Hold | None", fresh: Hold) -> Hold:
+    """Of two claims on one pid, the one that says more.
+
+    A pid can attract two. Terminal.app's own process is both a running
+    application and the emulator, and a tmux server inside another one's pane
+    is both a multiplexer nobody could ask and a pane somebody can reach.
+    Under the flat set of pids this replaced, the overlap was invisible and
+    harmless; now that each claim carries a sentence the desk shows, which one
+    survives is an answer on screen, and deciding it by which line of
+    build_projects() ran last is the trap two configured roots used to set.
+    """
+    if seen is None:
+        return fresh
+    return fresh if SPECIFIC.index(fresh.kind) > SPECIFIC.index(seen.kind) else seen
+
+
+def ancestry(pid: int, parent_of: dict) -> "tuple[list[int], bool]":
+    """Every pid from this one upward, and whether the walk got to the top.
+
+    The top is pid 1 or pid 0. Reaching it means the table really did have
+    the whole line, so "nothing up there has a claim" is an answer. The walk
+    ends early in two other ways, and they are the same fact wearing two
+    hats: `ps` had no row for the next parent, or the links turned back on
+    themselves. Either way the table does not say what is above this process,
+    and the honest reading of that is not "nothing".
+
+    `ps` is a snapshot of a moving target. A parent that exits while the walk
+    is being generated leaves a child pointing at a row that never gets
+    emitted, so this is a race rather than an impossibility.
+    """
+    chain: list[int] = []
+    seen: set = set()
+    while pid and pid > 1 and pid not in seen:
+        seen.add(pid)
+        chain.append(pid)
+        pid = parent_of.get(pid, -1)
+    return chain, pid in (0, 1)
+
+
+def holder(pid: int, holds: dict, parent_of: dict, *,
+           on_a_tty: bool = True) -> "Hold | None":
+    """What has a claim on this process, walking up from it. None if nothing.
+
+    The nearest claim wins, which is what makes its `why` true: a pane inside
+    a Terminal window is a better answer than the window.
+
+    `on_a_tty` is whether the process being asked about has a controlling
+    terminal. A `needs_tty` claim does not reach one that has none, and the
+    walk carries on past it rather than stopping, because a claim that does
+    not apply is not an answer.
+
+    None here means "found nothing on the way up", which is not the same as
+    "there is nothing". Ask `traceable()` before reading it as the second.
+    """
+    for up in ancestry(pid, parent_of)[0]:
+        hit = holds.get(up)
+        if hit is not None and (on_a_tty or not hit.needs_tty):
+            return hit
+    return None
+
+
+def traceable(pid: int, parent_of: dict) -> bool:
+    """Did the walk above this process reach the top of the tree.
+
+    Shares `ancestry()` with `holder()` on purpose. Deciding "nobody holds
+    this" and deciding "the table could say" are two readings of one walk,
+    and two walks written separately are how `under_a_root()` and
+    `project_from_path()` drifted apart.
+    """
+    return ancestry(pid, parent_of)[1]
+
+
+def executable_of(cmd: str) -> str:
+    """Best-effort executable path: everything before the first flag.
+
+    Split on " -" rather than whitespace, macOS executable paths are full of
+    spaces ("Codex (Renderer)"), so splitting on space would truncate them.
+    """
+    return cmd.split(" -", 1)[0].strip()
+
+
+def _executable_names(cmd: str) -> tuple:
+    """The names this command's executable could be going by.
+
+    There are two readings of where the executable ends and neither is right
+    on its own, because `ps` does not quote:
+
+        /Users/ada smith/bin/tmux -L work    the path runs past the first word
+        tmux new-session -d                  the span runs past the executable
+
+    executable_of() takes everything before the first flag, which is right for
+    the first and wrong for the second; the first word is right for the second
+    and wrong for the first. Telling them apart means asking the disk, and
+    these are the rules that are meant not to. So a rule that decides "leave
+    it alone" reads both, where being wrong costs a missed orphan, and a rule
+    that decides "this is a target" reads neither and goes through _subject().
+    """
+    tokens = cmd.split()
+    if not tokens:
+        return ()
+    first = _program_name(tokens[0])
+    span = _program_name(executable_of(cmd))
+    return (first,) if first == span else (first, span)
+
+
+def is_gui_app(cmd: str) -> bool:
+    """Is this a piece of a running macOS application?
+
+    A GUI application's helper processes are never terminal orphans. They
+    have a live parent that respawns them the instant they die, so "quitting"
+    them is useless *and* harmful: it force-quits pieces of a running app.
+
+    Checking only the executable matters: ChatGPT.app's renderer carries
+    `--user-data-dir=.../Application Support/Codex --standard-schemes=...`,
+    whose literal `codex --` fragment matched the agent patterns below and got
+    six of its processes SIGKILLed on a loop.
+
+    An interpreter is the exception, because a `.app` around one is packaging
+    rather than an application. Every Python on macOS lives in
+    `Python.framework/.../Python.app/Contents/MacOS/Python`, including the one
+    at /usr/bin/python3, so treating that as an app made every Python dev
+    server invisible to the sweep. The tool was blind to a whole language's
+    worth of exactly what it exists to find.
+
+    That narrowing is safe because it is not what protects an app's helpers.
+    scan.build_projects() walks a candidate's ancestry looking for an owner,
+    and an interpreter a real application launched still has that application
+    above it. Checked against the live process table: of ~1050 processes only
+    five change answer here, and the two that are genuinely ChatGPT.app's
+    (`Contents/Resources/cua_node/bin/node`) stay owned through their parent.
+    """
+    if ".app/Contents/" not in executable_of(cmd):
+        return False
+    tokens = cmd.split()
+    program = _program_name(tokens[0]) if tokens else ""
+    return program not in INTERPRETERS
+
+
+def multiplexer_name(cmd: str) -> str:
+    """Which terminal multiplexer this is, or "" if it is not one.
+
+    A tmux or screen pane is a session somebody is sitting in, exactly like a
+    tab, and the emulator cannot see it. Both of them daemonise their server
+    to pid 1 and give each pane a pty of their own, so a pane is neither on a
+    tty the driver reports nor descended from the emulator: the two things
+    that make a process somebody's both miss at once, and the sweep offers
+    live work for killing. Verified: a `vite` started in a pane under a
+    configured root was listed as an orphan and `workmap kill -n` named it,
+    while the pane was on screen and attached.
+
+    The name, not just yes or no, because only some of them can be asked what
+    they are holding and multiplexer.py has to know which it is looking at.
+    screen on macOS renames its own server process to `SCREEN` in capitals,
+    which is why this reads through _program_name rather than comparing the
+    token.
+
+    Read from the executable, like every other rule here that reads a command
+    line, so `screencapture` is not `screen`. Both spellings of it: see
+    _executable_names. Reading only executable_of() meant `tmux new-session
+    -d`, which is how a server is usually started, was not a multiplexer at
+    all, because the subcommand carries no leading dash and so was swallowed
+    into the executable. Every pane under such a server was offered for
+    killing. This one decides "leave it alone", where being wrong the other
+    way costs a missed orphan.
+    """
+    for name in _executable_names(cmd):
+        if name in MULTIPLEXERS:
+            return name
+    return ""
+
+
+def is_multiplexer(cmd: str) -> bool:
+    return bool(multiplexer_name(cmd))
+
+
+MULTIPLEXERS = frozenset({
+    "tmux", "screen", "zellij", "dtach", "abduco", "byobu",
+})
+
+# A shell's arguments are an opaque program, not a command line we can read.
+# `/bin/zsh -c source ~/.claude/shell-snapshots/snapshot-zsh-….sh && …` is a
+# shell, not an agent. Matching "claude" anywhere in that string is how a
+# plain shell got classified as a running claude session.
+SHELLS = frozenset({"sh", "bash", "zsh", "dash", "ksh", "csh", "tcsh", "fish"})
+
+# Programs that run *another* program named by their first non-flag argument.
+INTERPRETERS = frozenset({
+    "node", "nodejs", "bun", "deno", "python", "python2", "python3", "ruby",
+    "perl", "php", "env",
+})
+
+# Package runners: `npm run dev`, `npx vite`, `pnpm exec astro`.
+RUNNERS = frozenset({"npm", "npx", "pnpm", "yarn", "bun", "deno"})
+RUNNER_VERBS = frozenset({"run", "exec", "x", "run-script", "task"})
+
+AGENTS = {"claude": "claude", "codex": "codex", "cursor-agent": "cursor-agent"}
+DEV_TOOLS = {
+    "vite": "vite",
+    "esbuild": "esbuild",
+    "astro": "astro",
+    "next": "node-dev",
+    "next-server": "node-dev",
+    "webpack": "node-dev",
+    "webpack-dev-server": "node-dev",
+    "rollup": "node-dev",
+    "parcel": "node-dev",
+    "nodemon": "node-dev",
+    "wrangler": "node-dev",
+}
+
+# Never a target, however it was invoked. Matched loosely on purpose, see
+# _is_self() for why this one rule gets to look at the whole command line.
+SELF = frozenset({"workmap", "devstack"})
+
+_SCRIPT_EXT = (".js", ".mjs", ".cjs", ".ts", ".mts", ".cts", ".py", ".rb")
+
+
+def _program_name(token: str) -> str:
+    """The name a path or bare word refers to, minus decoration.
+
+    `/opt/homebrew/bin/node` → node, `-zsh` → zsh, `./bin/vite.js` → vite,
+    `…/node_modules/.bin/astro` → astro.
+    """
+    name = token.rsplit("/", 1)[-1].lstrip("-")
+    for ext in _SCRIPT_EXT:
+        if name.endswith(ext):
+            name = name[: -len(ext)]
+            break
+    return name.lower()
+
+
+def _package_of(token: str) -> str:
+    """The npm package a script path belongs to, if it names one.
+
+    `…/node_modules/wrangler/wrangler-dist/cli.js` is wrangler, not "cli".
+    The last `node_modules/` wins: it is the innermost package that owns
+    the file.
+    """
+    marker = "/node_modules/"
+    idx = token.rfind(marker)
+    if idx < 0:
+        return ""
+    rest = token[idx + len(marker):].split("/")
+    if not rest or not rest[0]:
+        return ""
+    if rest[0] == ".bin":
+        return rest[1].lower() if len(rest) > 1 else ""
+    return rest[0].lower()
+
+
+def _names_self(token: str) -> bool:
+    """Does this argv token *name* workmap, rather than merely pass through it?
+
+    The name a token refers to is its last path segment. `python3 -m
+    workmap.cli` names the module, so the dotted head counts too.
+    """
+    name = _program_name(token)
+    return name in SELF or name.split(".", 1)[0] in SELF
+
+
+def _is_self(cmd: str) -> bool:
+    """Is this workmap (or the devstack it drives) in any form?
+
+    Deliberately the one rule that scans every token rather than only the
+    executable: this decides "leave it alone", so a false positive costs a
+    missed orphan and a false negative costs the tool killing its own process
+    tree. `npx workmap` has to match, and it is not the executable.
+
+    What it reads of each token is the name that token refers to, not every
+    directory the token passes through. Those are different questions, and
+    reading the second one is the third outing of the mistake that once had
+    ChatGPT.app classified as codex: `workmap` is itself a project directory
+    here, so a dev server started in it carried our name in its path and was
+    treated as us. Its whole Terminal window dropped off the desk, and it
+    could never be swept.
+    """
+    return any(_names_self(token) for token in cmd.split())
+
+
+def is_self_process(cmd: str) -> bool:
+    """Is this process workmap itself?
+
+    Narrower than _is_self(), and the difference is the point. _is_self()
+    answers "never make this a target", where being wrong costs one missed
+    orphan, so it reads every token. This answers "this is the desk window,
+    leave it off the map", where being wrong costs a live Terminal window
+    disappearing along with the memory it is holding, so it reads only the
+    argv positions any rule here is allowed to read: the executable, and the
+    one argument an interpreter or a package runner is running.
+
+    `npm run dev --prefix ~/dev/workmap` names us in an argument and is not
+    us.
+    """
+    program, runs = _subject(cmd)
+    if any(_names_self(name) for name in (program, runs) if name):
+        return True
+    # `python3 share/workmap/tui.py` runs a module of ours from a checkout.
+    # The one directory that counts is the one holding the script, which is
+    # the package it belongs to, and only for a Python file: a `.js` sitting
+    # in a directory called workmap is somebody's project, not our package.
+    if program in INTERPRETERS:
+        script = _script_of(cmd.split()[1:])
+        if script.endswith(".py"):
+            parts = script.rsplit("/", 2)
+            if len(parts) > 1 and _names_self(parts[-2]):
+                return True
+    return False
+
+
+def _subject(cmd: str) -> tuple[str, str]:
+    """(program, what that program was asked to run).
+
+    Both are plain names taken from argv positions we can defend: the
+    executable, and the first non-flag argument of an interpreter or package
+    runner. Never a substring of an arbitrary argument.
+    """
+    tokens = cmd.split()
+    if not tokens:
+        return "", ""
+    program = _program_name(tokens[0])
+    args = tokens[1:]
+
+    if program in RUNNERS:
+        rest = _without_flag_values(args)
+        if rest and rest[0].lower() in RUNNER_VERBS:
+            rest = rest[1:]
+        return program, (_program_name(rest[0]) if rest else "")
+
+    if program in INTERPRETERS:
+        span = _script_words(args)
+        if not span:
+            return program, ""
+        # The shortest prefix that names an npm package wins. Taking the whole
+        # span as one path made `node .../.bin/astro dev` a script called
+        # "astro dev", which is not a name anything matches, so a dev server
+        # invoked with a subcommand classified as nothing and was never swept.
+        # The span still has to be allowed to be long, because a path can
+        # contain spaces and ps does not quote: reading only the first word of
+        # "/Users/ada smith/dev/app/node_modules/.bin/vite" finds "ada".
+        for n in range(1, len(span) + 1):
+            package = _package_of(" ".join(span[:n]))
+            if package:
+                return program, package
+        return program, _program_name(" ".join(span))
+
+    return program, ""
+
+
+def _without_flag_values(args: list[str]) -> list[str]:
+    """Arguments with the flags, and the values they take, removed.
+
+    Dropping only the tokens that start with a dash leaves the *value* of the
+    ones that take one, and then reads it as the thing being run: `npm
+    --prefix /opt/vite ci` was classified as a running vite, which is a rule
+    that decides "this IS a target" reading a flag value. That is the mistake
+    this file keeps finding, so a bare flag takes the word after it with it.
+    A flag written with an `=` carries its own value and takes nothing.
+    """
+    out: list[str] = []
+    skip = False
+    for tok in args:
+        if skip:
+            skip = False
+            continue
+        if tok.startswith("-"):
+            skip = "=" not in tok and tok != "--"
+            continue
+        out.append(tok)
+    return out
+
+
+# Interpreter flags whose value names *another* module, which is not the
+# program being run. Everything else a `node` flag can be is either a boolean
+# or a number, so reading the word after it as the script is only wrong for
+# these. Kept as a list rather than as "the word after any flag", because
+# `node --experimental-vm-modules app.js` is far commoner than any of them and
+# that rule would read `app.js` as the flag's value.
+_MODULE_FLAGS = frozenset({
+    "-r", "--require", "--import", "--loader", "--experimental-loader",
+})
+
+
+def _script_words(args: list[str]) -> list[str]:
+    """The words of the path an interpreter was asked to run.
+
+    Runs to the next flag rather than the next word, because a path can
+    contain spaces. Empty when it was given no script: `-c <code>` is an
+    inline program, not something we can name.
+    """
+    skip = False
+    for i, tok in enumerate(args):
+        if skip:
+            skip = False
+            continue
+        if tok.startswith("-"):
+            if tok == "-c":
+                return []
+            skip = tok in _MODULE_FLAGS
+            continue
+        rest = args[i:]
+        end = next((j for j, t in enumerate(rest) if t.startswith("-")),
+                   len(rest))
+        return rest[:end]
+    return []
+
+
+def _script_of(args: list[str]) -> str:
+    """_script_words joined back into a path."""
+    return " ".join(_script_words(args))
+
+
+def classify_cmd(cmd: str) -> str | None:
+    """What kind of work this process is, or None if it is not ours to track.
+
+    Reads the executable and (for interpreters and package runners) the one
+    argument naming what they run. It never searches the whole command line:
+    arguments carry paths, cache directories and flag values that collide with
+    every tool name worth matching. Two live examples this rule exists for:
+
+      /bin/zsh -c source ~/.claude/shell-snapshots/…       → a shell, not claude
+      …/Codex (Renderer) --user-data-dir=…/Codex --standard-schemes=…
+                                                           → a GUI app, not codex
+    """
+    if is_gui_app(cmd):  # subsumes the old per-app Cursor exclusion
+        return None
+    if _is_self(cmd):
+        return None
+
+    program, runs = _subject(cmd)
+    if not program or program in SHELLS:
+        # A shell's argument is a program in another language. Whatever it
+        # spawns shows up in the process table on its own and is classified
+        # there, so there is nothing to lose by declining to guess here.
+        return None
+
+    for name in (program, runs):
+        if name in AGENTS:
+            return AGENTS[name]
+    for name in (program, runs):
+        if name in DEV_TOOLS:
+            return DEV_TOOLS[name]
+
+    if program in RUNNERS:
+        return f"{program} {runs}" if runs else None
+    return None
+
+
+SPINNERS = "✳✱*·•◦⠂⠐←◂◀▷▹►"
+
+# Leading spinner glyphs, and the spaces between them. Only those: the class
+# in front of the glyph used to be `[\W_\d]*`, which is every digit and every
+# punctuation mark, so anything a title opened with was eaten as long as a
+# glyph turned up later on the line. "#42 • fix the parser" arrived as "fix
+# the parser" with the issue number gone, while "v1.2.3 • release" kept all of
+# itself, the only difference being that one starts with a letter. Whatever
+# the rule is, it cannot be that.
+_LEADING_NOISE = re.compile(rf"^(?:\s*[{SPINNERS}])+\s*")
+
+
+def clean_label(label: str) -> str:
+    """Strip spinner glyphs and the space around them from agent titles."""
+    s = _LEADING_NOISE.sub("", label.strip())
+    s = re.sub(r"\s+", " ", s).strip()
+    if s in ("-zsh", "zsh"):
+        return "shell"
+    return s
+
+
+# The agent names worth collapsing a whole title down to, and what to show
+# for each. `cursor-agent` and `cursor` are one tool under two spellings.
+AGENT_TITLES = {"claude": "claude", "codex": "codex",
+                "cursor": "cursor", "cursor-agent": "cursor"}
+
+
+def short_tool(label: str, kind: str) -> str:
+    """A few words naming what is in this tab, for the title workmap sets.
+
+    The agent name is read from the *first word* of the label and not from
+    anywhere inside it. A window title is written by the agent sitting in that
+    window, which makes it the least trustworthy text this tool reads, and
+    searching all of it answered "claude" for "fix the unclaudeable bug" and
+    "cursor" for "precursor analysis". Same rule as classify_cmd(), for the
+    same reason: a name that appears somewhere in a string is not the name of
+    the thing.
+
+    A background service is answered before the agent names are consulted at
+    all. Its label is already the answer classify_cmd() worked out, so `npm
+    run claude-watch` came back correctly as "npm claude-watch" and was then
+    relabelled "claude", naming the wrong program on the one line somebody
+    reads before deciding to quit it.
+    """
+    if kind == "bg":
+        return clean_label(label).removesuffix(" (bg)").strip() or "service"
+    cleaned = clean_label(label)
+    words = cleaned.split()
+    if words and words[0].lower() in AGENT_TITLES:
+        return AGENT_TITLES[words[0].lower()]
+    if cleaned == "shell":
+        return "shell"
+    # task-style title from the agent, keep it short
+    if len(cleaned) > 42:
+        return cleaned[:41] + "…"
+    return cleaned
+
+
+def plural(n: int, noun: str) -> str:
+    """"1 orphan", "3 orphans", "3 processes".
+
+    Cheaper than writing "orphan(s)", which asks the reader to do the
+    agreement in their head on every line it appears on, and which appeared on
+    every confirmation prompt in the tool.
+    """
+    if n == 1:
+        return f"{n} {noun}"
+    ending = "es" if noun.endswith(("s", "x", "z", "ch", "sh")) else "s"
+    return f"{n} {noun}{ending}"
+
+
+def held_note(held: list) -> str:
+    """One line saying why something running is not on the desk. "" if none.
+
+    The desk could say "nothing is running without a window" and be describing
+    two different machines: one with nothing to quit, and one where a tmux
+    pane has the thing you were looking for. They read identically, and only
+    one of them means everything is fine.
+
+    A multiplexer that could not be asked comes first when both are true. A
+    pane holding something is the tool working; not being able to ask is the
+    tool admitting it cannot see, which is the more urgent of the two and the
+    only one that gets better if you try again.
+    """
+    if not held:
+        return ""
+    unasked = [h for h in held if h.kind == "multiplexer"]
+    if unasked:
+        names = sorted({h.why.split(",", 1)[0].replace("inside ", "")
+                        for h in unasked})
+        which = " and ".join(names) or "a terminal multiplexer"
+        verb = "is" if len(unasked) == 1 else "are"
+        return (f"{plural(len(unasked), 'process')} {verb} inside {which}, "
+                f"which could not say what it is holding.")
+    verb, them = ("is", "it") if len(held) == 1 else ("are", "they")
+    return (f"{plural(len(held), 'process')} {verb} open in a tmux pane, "
+            f"so {them} {verb} not orphaned.")
+
+
+def fmt_mb(mb: int) -> str:
+    if mb >= 1024:
+        return f"{mb/1024:.1f}G"
+    return f"{mb}M"
+
+
+def fmt_mem(value) -> str:
+    """Format system figures that arrive as str/float (sysctl gives "6498.25").
+
+    Same units as fmt_mb so every size on screen reads the same way.
+    """
+    try:
+        mb = float(value)
+    except (TypeError, ValueError):
+        return str(value)
+    return f"{mb / 1024:.1f}G" if mb >= 1024 else f"{int(round(mb))}M"