workmap 0.1.0__py3-none-any.whl

workmap/scan.py

@@ -0,0 +1,413 @@
+"""Build the desk map: which projects exist, and what each one is holding.
+
+This is the one expensive call in the tool (~1s, dominated by AppleScript).
+Everything downstream takes the result as an argument rather than calling it
+again. See actions.py."""
+from __future__ import annotations
+
+import re
+import threading
+from collections import defaultdict
+from pathlib import Path
+
+from . import multiplexer, procs, terminal
+from .config import (ORPHAN_FLOOR_MB, build_project_index, load_config,
+                     profile_for, same_name)
+from .model import (REPORTABLE_HOLDS, SHELLS, Hold, Project, Session,
+                    _program_name, classify_cmd, clean_label, held_note,
+                    holder, is_gui_app, is_self_process, multiplexer_name,
+                    strongest, traceable, tty_short)
+from .procs import (cwd_for_pid, cwd_for_pids, descendant_pids,
+                    footprint_by_pid, process_snapshot, tree_mb)
+
+
+def title_label(raw_title: str, procs_on_tty: list[dict]) -> str:
+    """The human-meaningful part of a Terminal window name.
+
+    Terminal builds the name from em-dash separated pieces: the working
+    directory or user, any custom title (which is where an agent writes what
+    it is working on), and the commands currently running on the tty. Only the
+    middle piece is worth showing, so the other two have to be recognised.
+
+    The running-command piece used to be matched against a hard-coded list of
+    tool names, which failed the moment anything else was in the foreground.
+    A window doing chess work showed up as "sourcekit-lsp ◂ claude
+    --dangerously-skip-permissions". We already know what is running on this
+    tty, so ask the process table instead of guessing.
+    """
+    title = re.sub(r"\s—\s*\d+×\d+\s*$", "", raw_title or "")
+    if not title.strip():
+        return ""
+    running = {_program_name(r["cmd"].split()[0]) for r in procs_on_tty
+               if r["cmd"].split()}
+    running.discard("")
+
+    def is_command_list(part: str) -> bool:
+        """Does this piece just name processes that are running right here?"""
+        # Terminal joins concurrent commands with "◂".
+        names = [chunk.strip().split()[0] for chunk in part.split("◂")
+                 if chunk.strip()]
+        return bool(names) and all(_program_name(n) in running for n in names)
+
+    parts = [p.strip() for p in title.split("—") if p.strip()]
+    kept = [p for p in parts if not is_command_list(p)]
+    if not kept:
+        return ""
+    # Terminal only prepends the directory/user piece when it has something to
+    # prepend it to. So a lone survivor that was the *first* of several is that
+    # prefix and says nothing. A title with no separators at all is a
+    # custom one somebody set, and is the whole point.
+    if len(parts) > 1 and kept == parts[:1]:
+        return ""
+    pretty = kept[-1]
+    if pretty in ("zsh", "-zsh", "login", Path.home().name):
+        return ""
+    pretty = clean_label(pretty)
+    # A title we set ourselves reads "project · what"; keep the what.
+    if " · " in pretty:
+        pretty = pretty.split(" · ", 1)[1].strip() or pretty
+    return pretty
+
+
+def build_projects(*, held: list[Hold] | None = None) -> list[Project]:
+    """The desk: every project with something running, and what it is holding.
+
+    `held` is filled, if given, with one Hold per process this scan recognised
+    and declined to offer because something has a claim on it that the desk
+    does not show. That is how a caller can tell "nothing is running here"
+    apart from "something is running here and a tmux pane has it", which read
+    identically before and are not the same news. Same out-parameter shape as
+    procs.kill_pids(outcomes=), for the same reason: the answer is a side
+    channel, not the thing the caller asked for.
+    """
+    cfg = load_config()
+    # One directory listing per configured root, and one resolve() per project
+    # in them. Measured at 2ms for 44 projects against a scan of about a
+    # second, which is what it costs to be able to answer for a project
+    # reached through a symlink. See config.ProjectIndex.
+    index = build_project_index()
+    # `top` and AppleScript each cost about a second and neither needs the
+    # other, so the memory sample runs while Terminal is being queried.
+    mem_sample: dict[int, int] = {}
+
+    def _sample_memory() -> None:
+        mem_sample.update(footprint_by_pid())
+
+    sampler = threading.Thread(target=_sample_memory, daemon=True)
+    sampler.start()
+    tabs = terminal.list_terminal_tabs()
+    rows, kids = process_snapshot()  # one ps pass, not two
+    if not rows:
+        # A machine always has processes on it, so no rows means `ps` did not
+        # answer. Everything below is derived from it, so carrying on draws
+        # the desk of somebody with nothing open and offers nothing to quit:
+        # a silent all clear on a machine nobody managed to read. Same shape
+        # as the Terminal guard further down, and it has to be separate,
+        # because Terminal answering fine is exactly the case.
+        return []
+    by_tty: dict[str, list[dict]] = defaultdict(list)
+    for r in rows:
+        if r["tty"]:
+            by_tty[r["tty"]].append(r)
+
+    projects: dict[str, Project] = {}
+    claimed_pids: set[int] = set()
+
+    def ensure(name: str, path: Path | None) -> Project:
+        if name not in projects:
+            projects[name] = Project(
+                name=name,
+                path=path,
+                # profile_for, not ensure_: a scan must not write to disk.
+                profile=profile_for(name, cfg),
+            )
+        elif path and projects[name].path is None:
+            projects[name].path = path
+        return projects[name]
+
+    # Batch cwd lookups for every tty process once (not lsof-per-pid in the loop).
+    tty_pids: list[int] = []
+    for tab in tabs:
+        for r in by_tty.get(tty_short(tab["tty"]), []):
+            tty_pids.append(r["pid"])
+    cwd_by_pid = cwd_for_pids(tty_pids)
+
+    # Wait for the memory sample as late as possible: `top` costs about 0.9s
+    # and is now the longest single thing in a scan, so every call above that
+    # does not need it belongs in front of this line rather than behind it.
+    sampler.join(timeout=15.0)
+
+    for tab in tabs:
+        tty = tty_short(tab["tty"])
+        procs_on_tty = by_tty.get(tty, [])
+        cwd = None
+        # The shell first, because its working directory is the one the person
+        # is in. Read from the program name rather than by looking for "zsh"
+        # anywhere in the line: a tmux server started with a `-c <dir>` in a
+        # project whose path contains it matched, and so did every command
+        # with a zsh script somewhere in its arguments.
+        for r in sorted(procs_on_tty,
+                        key=lambda x: 0 if _program_name(
+                            (x["cmd"].split() or [""])[0]) in SHELLS else 1):
+            cwd = cwd_by_pid.get(r["pid"])
+            if cwd:
+                break
+        # A window belongs on the desk wherever it is, so a directory that is
+        # not a project still gets somewhere to go. An orphan gets no such
+        # fallback: no project means not offered, which is the safe direction.
+        found = index.of_path(cwd)
+        name, path = ((found.name, found.path) if found
+                      else index.bucket_for(cwd))
+        if cwd is None and tab["title"]:
+            # Terminal puts the working directory in front of its own title,
+            # so a tab whose processes will not say where they are can still
+            # be placed by what it is called. Through the index like every
+            # other reading of a name, so it can only name a project that is
+            # there: it used to accept any directory at all under a root.
+            prefix = tab["title"].split("—", 1)[0].strip()
+            named = index.named(prefix) if prefix else None
+            if named is not None:
+                name, path = named.name, named.path
+
+        label = "shell"
+        session_pids: set[int] = set()
+        for r in procs_on_tty:
+            session_pids |= descendant_pids(r["pid"], kids)
+            kind = classify_cmd(r["cmd"])
+            if kind in ("claude", "codex", "cursor-agent"):
+                label = kind
+            elif kind and label == "shell":
+                label = kind
+        if not session_pids:
+            session_pids = {r["pid"] for r in procs_on_tty}
+
+        # Skip the workmap desk window itself: the one running workmap, not
+        # every window that mentions it. This asks whether a process here *is*
+        # workmap, because the cost of being wrong is a live window vanishing
+        # off the desk with its memory uncounted. The looser _is_self(), which
+        # reads every token, is for the other question: never make this a
+        # target. Two decisions, two costs, two rules.
+        if any(is_self_process(r["cmd"]) for r in procs_on_tty):
+            claimed_pids |= session_pids
+            continue
+
+        pretty = title_label(tab["title"], procs_on_tty) or label
+
+        mb = tree_mb(session_pids, rows, mem_sample)
+        claimed_pids |= session_pids
+        proj = ensure(name, path)
+        proj.sessions.append(Session(
+            kind="window",
+            label=pretty if pretty != label else label,
+            mb=mb,
+            window_id=tab["window_id"],
+            tty=tty,
+            title=tab["title"],
+            profile=tab.get("profile") or None,
+            pids=sorted(session_pids),
+            cmds={r["pid"]: r["cmd"] for r in rows if r["pid"] in session_pids},
+            starts={r["pid"]: r["started"] for r in rows
+                    if r["pid"] in session_pids},
+        ))
+
+    # "Nothing owns this" is only knowable if we could ask what the windows
+    # own. When the Terminal query fails every process on the machine looks
+    # unowned, which is the one situation where a kill list must not be built:
+    # the tool would offer to quit the dev server of the tab you are sitting
+    # in. An empty-but-successful answer is different: that is a desk with no
+    # windows left, which is exactly when orphans matter most.
+    if not terminal.terminal_status()["ok"]:
+        return _finish(projects)
+
+    # An orphan is a process nothing has a claim on any more. What can have
+    # one, and why each is a different fact with a different lifetime, is
+    # written down in model.Hold. Built here, most general first, so the most
+    # specific claim on a pid is the one that survives.
+    #
+    # A running application was free once: Terminal.app is a .app bundle, so
+    # the application rule covered the terminal too. That made the protection
+    # an accident of this driver rather than a property of the tool, and a
+    # driver whose emulator is a plain binary would have had none of it.
+    # terminal.owner_pids() states it instead.
+    #
+    # A multiplexer is not the driver's to answer, which is why it is here
+    # rather than behind that seam: a multiplexer is not the terminal you are
+    # in, it is a second one running inside it, and every driver inherits the
+    # same blind spot. What changed is which part of it holds anything. The
+    # server used to, which is far too much: a server outlives its panes, so
+    # everything it ever started stayed claimed forever. Measured: a
+    # `tmux run-shell -b` job hangs directly off the server with no pane at
+    # all, and was invisible to the sweep for as long as the server ran.
+    # A live pane holds its own subtree, and the server holds nothing unless
+    # it could not be asked.
+    holds: dict[int, Hold] = {}
+
+    def claim(hold: Hold) -> None:
+        """Record a claim. Which one survives is model.strongest()'s to say,
+        not the order these lines happen to be written in."""
+        holds[hold.pid] = strongest(holds.get(hold.pid), hold)
+
+    for r in rows:
+        if is_gui_app(r["cmd"]):
+            claim(Hold(r["pid"], "app", "part of a running app"))
+    for pid in terminal.owner_pids(rows):
+        claim(Hold(pid, "window", "open in a Terminal window"))
+    found = multiplexer.live_panes(rows)
+    for pid in found.unasked:
+        name = next((multiplexer_name(r["cmd"]) for r in rows
+                     if r["pid"] == pid), "") or "a terminal multiplexer"
+        claim(Hold(pid, "multiplexer",
+                   f"inside {name}, which could not say what it holds"))
+    for pid in found.asked:
+        # A server that answered keeps only what it is showing. Everything in
+        # a pane is claimed by that pane below; this covers what tmux draws
+        # without giving it a pane of its own, which is a popup, and it is
+        # told apart from a job the server merely runs by whether the server
+        # gave it a terminal. See model.Hold.
+        claim(Hold(pid, "shown", "shown by tmux", needs_tty=True))
+    for pane in found.live:
+        claim(Hold(pane.pid, "pane", f"open in {pane.where}"))
+    parent_of = {r["pid"]: r["ppid"] for r in rows}
+
+    # Only tree *roots* are orphans. Walking rows in ps order and claiming
+    # greedily made this depend on pid ordering: a child whose pid is lower
+    # than its parent's (they wrap around) got claimed first, and the parent
+    # was then skipped for overlapping. It reported a subtree and left the
+    # process that respawns it alive.
+    candidates = {}
+    for r in rows:
+        # An early out, not a guard. Everything a window accounted for is in
+        # claimed_pids along with its descendants, and the overlap check below
+        # refuses the same set again, so removing this line changes no answer.
+        # It is kept because skipping the work is cheaper than undoing it, and
+        # said out loud because a test cannot tell the two apart: this is one
+        # of the two lines here that no test can be written against, and
+        # pretending otherwise is worse than saying so.
+        if r["pid"] not in claimed_pids:
+            kind = classify_cmd(r["cmd"])
+            if not kind:
+                continue
+            # Asked once, read twice. Deciding "not an orphan" and reporting
+            # why are the same fact, and computing them separately is how
+            # under_a_root() and project_from_path() drifted apart.
+            hold = holder(r["pid"], holds, parent_of, on_a_tty=bool(r["tty"]))
+            if hold is None:
+                # Nothing was found on the way up, which is only an answer if
+                # the way up was there to walk. A chain that ran out of table
+                # or turned back on itself has not said "nobody has this", it
+                # has failed to look, and the difference matters because the
+                # word for a process nobody has is a target. Same rule as the
+                # multiplexer nobody could ask: not knowing protects.
+                if not traceable(r["pid"], parent_of):
+                    continue
+                candidates[r["pid"]] = kind
+            elif held is not None and hold.kind in REPORTABLE_HOLDS:
+                held.append(hold)
+
+    def has_candidate_ancestor(pid: int) -> bool:
+        seen: set[int] = set()
+        pid = parent_of.get(pid, 0)
+        while pid and pid > 1 and pid not in seen:
+            if pid in candidates:
+                return True
+            seen.add(pid)
+            pid = parent_of.get(pid, 0)
+        return False
+
+    by_pid = {r["pid"]: r for r in rows}
+    # One lsof for every candidate, the way the tab loop above already does
+    # it. Asking per candidate is a subprocess each, with a 6s timeout each,
+    # on the hot path of every keypress that refreshes.
+    roots_of_candidates = [pid for pid in candidates
+                           if not has_candidate_ancestor(pid)]
+    cwd_by_candidate = cwd_for_pids(roots_of_candidates)
+
+    for pid in roots_of_candidates:
+        kind = candidates[pid]
+        cmd = by_pid[pid]["cmd"]
+        # Where it is running first, what its arguments say second. The other
+        # order let any flag value that happened to contain a configured root
+        # (--config, --watch, a cache directory, a log path) decide which
+        # project a kill hits, and promote a process that its real working
+        # directory would have placed outside every root. Reading a project
+        # out of an argument is the mistake this codebase keeps finding; it
+        # stays only as the fallback for a process whose cwd cannot be read.
+        #
+        # An orphan belongs to a project, and no project means it is not
+        # offered. That used to be two questions with two different answers,
+        # "is it under a root" and "which project is it in", and a path could
+        # pass the first and be given a project by the second that does not
+        # exist. One lookup now, and None is a real answer.
+        project = index.of_path(cwd_by_candidate.get(pid)) or index.in_cmd(cmd)
+        if project is None:
+            continue
+        name, proj_path = project.name, project.path
+        pids = descendant_pids(pid, kids)
+        if pids & claimed_pids:
+            continue
+        mb = tree_mb(pids, rows, mem_sample)
+        # The floor is calibrated against phys_footprint, which is what `top`
+        # gives. Without that sample tree_mb falls back to `ps` RSS, and the
+        # floor sat *above* most real dev servers when it was measured against
+        # RSS: eleven orphaned astro servers holding 1.6 GB reported 1-2 MB
+        # each. So when the sample did not arrive the floor is not applied at
+        # all, because filtering on a number it does not describe is worse
+        # than not filtering. See config.ORPHAN_FLOOR_MB.
+        if mem_sample and mb < ORPHAN_FLOOR_MB:
+            continue
+        claimed_pids |= pids
+        proj = ensure(name, proj_path)
+        proj.sessions.append(Session(
+            kind="bg",
+            label=kind,
+            mb=mb,
+            pids=sorted(pids),
+            cmds={p: by_pid[p]["cmd"] for p in sorted(pids) if p in by_pid},
+            starts={p: by_pid[p]["started"] for p in sorted(pids)
+                    if p in by_pid},
+        ))
+
+    return _finish(projects)
+
+
+def _finish(projects: dict[str, Project]) -> list[Project]:
+    items = list(projects.values())
+    items.sort(key=lambda p: (-bool(p.window_ids), -p.mb, p.name))
+    for p in items:
+        p.sessions.sort(key=lambda s: (0 if s.kind == "window" else 1, -s.mb, s.label))
+    return items
+
+
+def background_sessions(
+    project_name: str | None = None, *, projects: list[Project] | None = None
+) -> list[tuple[str, Session]]:
+    out: list[tuple[str, Session]] = []
+    for p in projects if projects is not None else build_projects():
+        # same_name, not ==: a project read off the disk and the same name
+        # typed at a prompt can differ by unicode normalisation alone.
+        if project_name is not None and not same_name(p.name, project_name):
+            continue
+        for s in p.sessions:
+            if s.kind == "bg":
+                out.append((p.name, s))
+    return out
+
+
+def snapshot() -> dict:
+    held: list[Hold] = []
+    projects = build_projects(held=held)
+    # Read before list_profiles(), which is cheaper than the desk query and
+    # writes the same status. Asking afterwards reported the profile query's
+    # success in place of the desk query's failure.
+    status = terminal.terminal_status()
+    mem = procs.mem_summary()
+    tracked = sum(p.mb for p in projects)
+    return {
+        "mem": mem,
+        "terminal": status,
+        "tracked_mb": tracked,
+        "profiles": terminal.list_profiles(),
+        "projects": [p.to_dict() for p in projects if p.sessions],
+        # Why the list above is shorter than the machine, if it is.
+        "held": held_note(held),
+    }