workmap 0.1.0__py3-none-any.whl

workmap/procs.py

@@ -0,0 +1,504 @@
+"""Process and memory facts, straight from the OS.
+
+Portable POSIX territory: ps, lsof, vm_stat, signals. Nothing here knows what
+a Terminal window is."""
+from __future__ import annotations
+
+import os
+import re
+import signal
+import subprocess
+import time
+from collections import defaultdict
+from pathlib import Path
+
+
+def run(cmd: list[str], *, timeout: float = 8.0, **kwargs) -> str:
+    """Capture a command's stdout. Always bounded, lsof on a stale network
+    mount, or a wedged Finder, would otherwise hang the whole tool forever."""
+    return subprocess.check_output(
+        cmd, text=True, stderr=subprocess.DEVNULL, timeout=timeout, **kwargs
+    )
+
+
+def run_safe(cmd: list[str], *, timeout: float = 8.0, default: str = "") -> str:
+    """run() that degrades to `default` instead of propagating."""
+    try:
+        return run(cmd, timeout=timeout)
+    except (subprocess.CalledProcessError, subprocess.TimeoutExpired,
+            OSError, ValueError):
+        return default
+
+
+def run_partial(cmd: list[str], *, timeout: float = 8.0) -> str:
+    """Capture stdout and keep it even when the command exits non-zero.
+
+    For tools that report "I couldn't do all of it" through the exit status
+    while still printing everything they *could* do. lsof is the reason this
+    exists: asked about a batch of pids it exits 1 if a single one is
+    unreadable. `login`, which sits on every macOS Terminal tab, is
+    root-owned and always unreadable. Treating that as total failure threw
+    away the working directory of every other process in the batch, which is
+    how every project ended up in the "other" bucket.
+    """
+    try:
+        proc = subprocess.run(
+            cmd, capture_output=True, text=True, timeout=timeout, check=False
+        )
+    except (subprocess.TimeoutExpired, OSError, ValueError):
+        return ""
+    return proc.stdout or ""
+
+
+# `lstart` is five whitespace-separated tokens on macOS, always, even for a
+# single-digit day, where ps pads with a second space that split() collapses.
+# That fixed width is what lets it sit in front of the command in one pass.
+_LSTART_FIELDS = 5
+_PS_FORMAT = "pid=,ppid=,rss=,tty=,lstart=,command="
+
+
+def _start_time(raw: str) -> str:
+    """A start time in one spelling, whoever read it.
+
+    ps pads the day to two columns, so a process started on the 8th reports
+    "Wed Jul  8 07:14:41 2026" with two spaces. The scan reads lstart with
+    split(), which collapses that; the kill-time recheck read it with
+    split(None, 1), which kept it. The two never matched again, and since a
+    start time is what identity means here, every process started on the first
+    nine days of a month looked like a recycled pid and was spared. Measured on
+    this machine: 200 of 400 live pids. `workmap kill` reported the memory it
+    had freed and had signalled nothing.
+
+    One function, both readers, so they cannot drift apart again.
+    """
+    return " ".join(raw.split())
+
+
+def process_snapshot() -> tuple[list[dict], dict[int, list[int]]]:
+    """One `ps` pass for both the process table and the parent→child map.
+
+    These used to be two separate full-table scans of the same data.
+
+    An empty table means `ps` did not answer, because a machine always has
+    processes on it. Callers have to treat it as a failure rather than as an
+    idle machine: everything the scan knows is derived from this, so no rows
+    means no windows, no owners and no orphans, which draws exactly the desk
+    of somebody with nothing open. `ps` missing its timeout on a loaded
+    machine is the likely way in, and the Terminal query is fine at the time,
+    so the guard that already exists for that does not fire.
+    """
+    out = run_safe(["ps", "-axo", _PS_FORMAT], timeout=6.0)
+    rows: list[dict] = []
+    kids: dict[int, list[int]] = defaultdict(list)
+    fields = 5 + _LSTART_FIELDS
+    for line in out.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        parts = line.split(None, fields - 1)
+        if len(parts) < fields:
+            continue
+        pid_s, ppid_s, rss_s, tty = parts[:4]
+        started = _start_time(" ".join(parts[4:4 + _LSTART_FIELDS]))
+        cmd = parts[4 + _LSTART_FIELDS]
+        try:
+            pid, ppid, rss = int(pid_s), int(ppid_s), int(rss_s)
+        except ValueError:
+            continue
+        rows.append({
+            "pid": pid,
+            "ppid": ppid,
+            "rss_kb": rss,
+            "tty": tty if tty != "??" else "",
+            "started": started,
+            "cmd": cmd,
+        })
+        kids[ppid].append(pid)
+    return rows, kids
+
+
+def process_table() -> list[dict]:
+    return process_snapshot()[0]
+
+
+def children_map() -> dict[int, list[int]]:
+    return process_snapshot()[1]
+
+
+def descendant_pids(root: int, kids: dict[int, list[int]]) -> set[int]:
+    seen: set[int] = set()
+    stack = [root]
+    while stack:
+        pid = stack.pop()
+        if pid in seen:
+            continue
+        seen.add(pid)
+        stack.extend(kids.get(pid, []))
+    return seen
+
+
+def _parse_size_kb(text: str) -> int | None:
+    """top's size column: "26M", "1261M", "6167M+", "512K", "1.2G"."""
+    s = text.strip().rstrip("+-")
+    if not s:
+        return None
+    unit, digits = s[-1].upper(), s[:-1]
+    scale = {"K": 1, "M": 1024, "G": 1024 * 1024, "B": 1 / 1024}.get(unit)
+    if scale is None:
+        unit, digits, scale = "B", s, 1 / 1024
+    try:
+        return int(float(digits) * scale)
+    except ValueError:
+        return None
+
+
+def footprint_by_pid() -> dict[int, int]:
+    """Per-pid phys_footprint in KB, the number Activity Monitor shows.
+
+    `ps -o rss` is not what it sounds like on macOS. It reports resident
+    *dirty* pages: it excludes the dyld shared cache a process has mapped
+    (~180 MB of shared __TEXT per process, which is right: that memory is
+    shared, not per-process), but it also excludes anything the compressor has
+    taken, which is wrong. On a machine under pressure that is most of the
+    heap: a node process here showed 34 MB resident against 363 MB compressed.
+
+    phys_footprint counts compressed pages and still excludes shared clean
+    ones, so it is both the honest number and the comparable one. One `top`
+    pass costs ~0.9s for the whole table; callers overlap it with other work.
+    Returns {} if top is unavailable, callers fall back to ps.
+    """
+    out: dict[int, int] = {}
+    raw = run_partial(["top", "-l", "1", "-stats", "pid,mem"], timeout=15.0)
+    started = False
+    for line in raw.splitlines():
+        fields = line.split()
+        if not started:
+            # Skip the system summary; the table starts at its header row.
+            started = bool(fields) and fields[0] == "PID"
+            continue
+        if len(fields) < 2 or not fields[0].isdigit():
+            continue
+        kb = _parse_size_kb(fields[1])
+        if kb is not None:
+            out[int(fields[0])] = kb
+    return out
+
+
+def tree_mb(pids: set[int], rows: list[dict],
+            footprint: dict[int, int] | None = None) -> int:
+    """Memory held by a process tree, in MB.
+
+    Summing across a tree is only honest because the per-process figure
+    excludes shared pages: the framework a parent and six children all map is
+    counted once by the kernel, not seven times. See footprint_by_pid().
+    """
+    by_pid = {r["pid"]: r["rss_kb"] for r in rows}
+    fp = footprint or {}
+    # Per-pid fallback, not all-or-nothing: top and ps are separate samples, so
+    # a process can appear in one and not the other.
+    return sum(fp.get(pid) or by_pid.get(pid, 0) for pid in pids) // 1024
+
+
+def cwd_for_pid(pid: int) -> Path | None:
+    return cwd_for_pids([pid]).get(pid)
+
+
+def cwd_for_pids(pids: list[int]) -> dict[int, Path]:
+    """One lsof for many pids (per-pid lsof was a big slice of refresh cost)."""
+    out: dict[int, Path] = {}
+    uniq = []
+    seen: set[int] = set()
+    for pid in pids:
+        if pid and pid not in seen:
+            seen.add(pid)
+            uniq.append(pid)
+    if not uniq:
+        return out
+    # lsof has an argument length limit, so chunk
+    for i in range(0, len(uniq), 40):
+        chunk = uniq[i : i + 40]
+        # lsof exits non-zero when any pid in the batch is gone or unreadable,
+        # having already printed the rest. Keep stdout regardless. It can
+        # also block on stale network mounts, hence the timeout.
+        raw = run_partial(
+            ["lsof", "-a", "-d", "cwd", "-p", ",".join(str(p) for p in chunk), "-Fn"],
+            timeout=6.0,
+        )
+        if not raw:
+            continue
+        cur_pid: int | None = None
+        for line in raw.splitlines():
+            if line.startswith("p"):
+                try:
+                    cur_pid = int(line[1:])
+                except ValueError:
+                    cur_pid = None
+            elif line.startswith("n") and cur_pid is not None:
+                p = Path(line[1:])
+                if cur_pid not in out and _still_there(p):
+                    out[cur_pid] = p
+    return out
+
+
+def _still_there(path: Path) -> bool:
+    """Does this directory exist? Only "no such file" counts as no.
+
+    The check is here to drop a working directory that has been deleted since
+    the process entered it. A directory nobody may traverse is a different
+    answer: lsof has just said a live process is sitting in it, so it is
+    there.
+
+    Asked with stat() rather than exists(), because exists() does not mean the
+    same thing on the two interpreters this ships against. On 3.9, the floor
+    and the one it installs into, it propagates EACCES, so one project
+    directory with its permissions changed took down every scan, which is
+    every keypress in the desk. On 3.12 and later it swallows that and answers
+    False, which is quieter and still wrong: the process is dropped and its
+    project goes unnamed. stat() raises both, and the two are told apart here,
+    so the answer is the same wherever it runs.
+    """
+    try:
+        path.stat()
+        return True
+    except FileNotFoundError:
+        return False
+    except OSError:
+        return True
+
+
+def unix_socket_paths(pids: list[int]) -> dict[int, list[str]]:
+    """Which unix-domain sockets each of these processes is listening on.
+
+    cwd_for_pids() batched the same way for the same reason: one lsof, not one
+    per pid. This one answers "where do I talk to that server", which is how
+    panes.py reaches a multiplexer without guessing at a socket directory.
+
+    Only names that are paths are kept. lsof reports the other end of a
+    connected socket as a kernel address (`->0xcfedb109393bb6a6`), which names
+    nothing anything can be asked through.
+    """
+    out: dict[int, list[str]] = {}
+    uniq = [p for p in dict.fromkeys(pids) if p]
+    if not uniq:
+        return out
+    for i in range(0, len(uniq), 40):
+        chunk = uniq[i:i + 40]
+        raw = run_partial(
+            ["lsof", "-a", "-U", "-p", ",".join(str(p) for p in chunk), "-Fn"],
+            timeout=6.0,
+        )
+        cur_pid: int | None = None
+        for line in raw.splitlines():
+            if line.startswith("p"):
+                try:
+                    cur_pid = int(line[1:])
+                except ValueError:
+                    cur_pid = None
+            elif line.startswith("n") and cur_pid is not None:
+                name = line[1:]
+                # One socket can appear on several descriptors, so the same
+                # path comes back more than once and would be asked twice.
+                if name.startswith("/") and name not in out.get(cur_pid, ()):
+                    out.setdefault(cur_pid, []).append(name)
+    return out
+
+
+def mem_summary() -> dict:
+    free_mb: int | str = "?"
+    swap_mb: str = "?"
+    try:
+        vm = run(["vm_stat"])
+        page_size = 4096
+        m = re.search(r"page size of (\d+) bytes", vm)
+        if m:
+            page_size = int(m.group(1))
+        m = re.search(r"Pages free:\s+(\d+)", vm)
+        if m:
+            free_mb = int(m.group(1)) * page_size // 1024 // 1024
+    except Exception:
+        pass
+    try:
+        swap = run(["sysctl", "-n", "vm.swapusage"])
+        m = re.search(r"used = ([0-9.]+)M", swap)
+        if m:
+            swap_mb = m.group(1)
+    except Exception:
+        pass
+    return {"free_mb": free_mb, "swap_mb": swap_mb}
+
+
+def pid_alive(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+        return True
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True  # exists, just not ours
+
+
+def killable_pids(pids: list[int]) -> list[int]:
+    """Drop pids we must never signal: ourselves, our parent, our process
+    group leader, and init.
+
+    Not "our own ancestry", which is what this used to claim: it has no
+    process table, so it cannot walk one. Everything further up is protected
+    a layer earlier, by scan.build_projects(), which never offers a process
+    descended from the terminal or from a running application. This is the
+    last net, and it is worth saying what it actually catches.
+    """
+    forbidden = {0, 1, os.getpid(), os.getppid()}
+    try:
+        forbidden.add(os.getpgid(0))
+    except OSError:
+        pass
+    out: list[int] = []
+    for pid in pids:
+        if pid and pid > 1 and pid not in forbidden and pid not in out:
+            out.append(pid)
+    return out
+
+
+def current_starts(pids: list[int]) -> dict[int, str]:
+    """When each of these pids started, for pids we can read.
+
+    `lstart` goes last here so its spaces cannot be confused with a field
+    boundary.
+    """
+    out: dict[int, str] = {}
+    if not pids:
+        return out
+    raw = run_partial(
+        ["ps", "-o", "pid=,lstart=", "-p", ",".join(str(p) for p in pids)],
+        timeout=6.0,
+    )
+    for line in raw.splitlines():
+        parts = line.strip().split(None, 1)
+        if len(parts) == 2 and parts[0].isdigit():
+            out[int(parts[0])] = _start_time(parts[1])
+    return out
+
+
+def still_the_same(pids: list[int], expected: dict[int, str],
+                   live: dict[int, str] | None = None) -> list[int]:
+    """Drop pids that are not the process we recorded.
+
+    A scan can sit on screen for hours before the user acts on it, and macOS
+    hands pids back out after ~99k more processes. Without this, `k` signals
+    whatever inherited the number, which on a dev machine is something that
+    started *since* the scan: the newest thing the user is working on.
+
+    Identity is the start time, not the command line. A command line is not an
+    identity: a process can rewrite its own argv (plenty of servers do), which
+    would make a live process look recycled and quietly un-killable. A start
+    time cannot be rewritten, and a recycled pid necessarily started later
+    than the scan that recorded it.
+
+    A pid `ps` answered about but did not list has exited, and keeping it costs
+    nothing: os.kill reports it already gone. A `ps` that answered about *none*
+    of them is a different thing, and used to be treated as the same one. It is
+    not evidence that all of them are fine, it is the absence of evidence, and
+    this check is the only thing standing between an hours-old scan and a
+    signal sent to whatever now holds those numbers. So nothing is signalled:
+    if they really are all gone there is nothing to lose, and if `ps` merely
+    timed out there is everything.
+    """
+    if not expected:
+        return pids
+    if live is None:
+        live = current_starts(pids)
+    if pids and not live:
+        return []
+    out = []
+    for pid in pids:
+        want = expected.get(pid)
+        now = live.get(pid)
+        if want is None:
+            # No identity was recorded for this pid, so there is nothing to
+            # compare against and this guard cannot vouch for it. It used to
+            # be kept, which let exactly the pid the guard exists for through
+            # the one check meant to catch it. The scanner only records a
+            # start time for pids `ps` listed, so a pid it could not read is
+            # spared instead. Same reasoning as the empty-`live` case above:
+            # if it really has gone there is nothing to lose by not
+            # signalling it, and if it has been reused there is everything.
+            continue
+        if now is None or now == want:
+            out.append(pid)
+    return out
+
+
+def kill_pids(pids: list[int], expected: dict[int, str] | None = None, *,
+              dry_run: bool = False, outcomes: list[dict] | None = None) -> int:
+    """SIGTERM, wait, then SIGKILL only what is still alive.
+
+    The liveness re-check matters: the old code SIGKILLed every pid
+    unconditionally after the grace period, so a pid that had already exited
+    and been recycled by the OS could take an unrelated process with it. The
+    same hazard applies to the opening SIGTERM, which is what `expected`
+    guards. See still_the_same().
+
+    `dry_run` runs every check and reports what it would do without sending a
+    signal. `outcomes`, if given, is filled with one record per pid so the
+    caller can write them to the audit log; the reason a pid was spared is
+    part of the record, since "nothing happened" has several causes worth
+    telling apart.
+    """
+    log = outcomes if outcomes is not None else []
+    asked = list(dict.fromkeys(p for p in pids if p))
+    # Read the identities once, so the log can tell "this pid is not the
+    # process we recorded" apart from "we could not find out". Both spare the
+    # pid; only one of them is a fact about the pid.
+    live = current_starts(asked) if (asked and expected) else {}
+    unchecked = bool(asked) and bool(expected) and not live
+    survivors = still_the_same(asked, expected or {}, live)
+    uniq = killable_pids(survivors)
+    for pid in asked:
+        if pid not in survivors:
+            if unchecked:
+                why = "skipped-unchecked"
+            elif expected and pid not in expected:
+                # Spared because nothing was recorded about it, which is a
+                # different fact from "the pid was reused" and used to be
+                # reported as one.
+                why = "skipped-unrecorded"
+            else:
+                why = "skipped-recycled"
+            log.append({"pid": pid, "signal": None, "result": why})
+        elif pid not in uniq:
+            log.append({"pid": pid, "signal": None, "result": "skipped-protected"})
+
+    if dry_run:
+        for pid in uniq:
+            log.append({"pid": pid, "signal": "SIGTERM", "result": "dry-run"})
+        return len(uniq)
+
+    n = 0
+    for pid in uniq:
+        try:
+            os.kill(pid, signal.SIGTERM)
+            n += 1
+            log.append({"pid": pid, "signal": "SIGTERM", "result": "sent"})
+        except ProcessLookupError:
+            log.append({"pid": pid, "signal": "SIGTERM", "result": "already-gone"})
+        except PermissionError:
+            log.append({"pid": pid, "signal": "SIGTERM", "result": "not-permitted"})
+    if not uniq:
+        return 0
+    # Give them a moment to go quietly, then re-check before escalating.
+    deadline = time.time() + 0.5
+    while time.time() < deadline:
+        if not any(pid_alive(p) for p in uniq):
+            return n
+        time.sleep(0.05)
+    for pid in uniq:
+        if not pid_alive(pid):
+            continue
+        try:
+            os.kill(pid, signal.SIGKILL)
+            log.append({"pid": pid, "signal": "SIGKILL", "result": "sent"})
+        except ProcessLookupError:
+            log.append({"pid": pid, "signal": "SIGKILL", "result": "already-gone"})
+        except PermissionError:
+            log.append({"pid": pid, "signal": "SIGKILL", "result": "not-permitted"})
+    return n