alissa-tools-github-revloop 0.16.14__tar.gz → 0.16.16__tar.gz

{alissa_tools_github_revloop-0.16.14/src/main/alissa_tools_github_revloop.egg-info → alissa_tools_github_revloop-0.16.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-revloop
-Version: 0.16.14
+Version: 0.16.16
 Summary: ALISSA-TOOLS-GITHUB-REVLOOP
 Home-page: https://alissa.app
 Author: Fahera

alissa_tools_github_revloop-0.16.16/src/main/alissa/tools/github/revloop/version

@@ -0,0 +1 @@
+0.16.16

{alissa_tools_github_revloop-0.16.14 → alissa_tools_github_revloop-0.16.16}/src/main/alissa/tools/github/revloop/webui/__init__.py

@@ -15,14 +15,16 @@ pass writes one `poll_snapshots` row (UI-1, PR #35) carrying the pass timing,
 the candidate count, the decision-summary counts, and the compact per-item
 stage list. The sidecar reads that table through `State.read_snapshots`, plus
 the spawn ledger, the escalation table and the ping ledger (the operator
-inbox), all read-only. Its only live signals are local (`alissa tmux ls`, a
-`/proc` walk of each session's pane-PID tree) or cached (`gh api rate_limit`,
-60s; the PyPI version JSON, 10m) -- so a fleet of operators refreshing the
-dashboard never moves the daemon's rate budget.
+inbox), all read-only. Its only live signals are local (`alissa tmux ls`, one
+`/proc` walk serving both each session's pane-PID tree and the host-wide
+top-by-RSS list, and the container's own cgroup v2 memory charge) or cached
+(`gh api rate_limit`, 60s; the PyPI version JSON, 10m) -- so a fleet of
+operators refreshing the dashboard never moves the daemon's rate budget.
 
 Layout:
   auth.py     -- fail-closed passcode, HMAC-signed sessions, CSRF, login throttle
-  sysinfo.py  -- /proc process-tree CPU%/RSS (sample-free, vanished-PID tolerant)
+  sysinfo.py  -- /proc process-tree CPU%/RSS + host-wide top-by-RSS and the
+                 cgroup memory split (sample-free, vanished-PID tolerant)
   sources.py  -- the read-only data layer + the retry-now UPDATE, cached checks
   page.py     -- the single static HTML page (studio design system, both themes)
   server.py   -- ThreadingHTTPServer wiring, routing, auth/CSRF gating, actions

{alissa_tools_github_revloop-0.16.14 → alissa_tools_github_revloop-0.16.16}/src/main/alissa/tools/github/revloop/webui/page.py

@@ -165,7 +165,7 @@ header.top h1 {
 
 /* stat tiles: seamless 1px-gap grid */
 .tiles {
-  display: grid; grid-template-columns: repeat(4, 1fr); gap: 1px;
+  display: grid; grid-template-columns: repeat(5, 1fr); gap: 1px;
   background: var(--surface-border); border: 1px solid var(--surface-border);
   border-radius: var(--radius-lg); overflow: hidden; margin-bottom: 2rem;
 }
@@ -182,6 +182,9 @@ header.top h1 {
 .meter.crit > span { background: var(--status-cancelled); }
 
 .grid2 { display: grid; grid-template-columns: 1fr 1fr; gap: 1.5rem; }
+/* Five tiles do not fit a laptop viewport at the tile's own type scale; the
+   900px rule below must stay LAST so the narrow case still wins. */
+@media (max-width: 1100px) { .tiles { grid-template-columns: repeat(3, 1fr); } }
 @media (max-width: 900px) { .grid2 { grid-template-columns: 1fr; }
   .tiles { grid-template-columns: repeat(2, 1fr); } }
 
@@ -331,6 +334,11 @@ _DASHBOARD = """<!doctype html>
 
 <section class="panel"><p class="overline">Sessions</p><div id="sessions"></div></section>
 
+<section class="panel">
+  <p class="overline">Top Processes &middot; by RSS, host-wide</p>
+  <div id="topprocs"></div>
+</section>
+
 <section class="panel">
   <p class="overline">Daemon Log &middot; <span id="log-path" class="mono muted"></span></p>
   <div class="log" id="log"></div>
@@ -422,6 +430,36 @@ _JS = r"""
       var vsub = bytes(t.volume.used_bytes) + ' / ' + bytes(t.volume.total_bytes);
       out += tile('Volume', t.volume.percent + '%', vsub, t.volume.percent);
     } else { out += tile('Volume', '--', 'unavailable'); }
+    // The tile a platform memory graph sends you here to read: the headline is
+    // what the container is CHARGED, the sub splits it into what is really
+    // process memory and what is cache the kernel would drop under pressure --
+    // so a "6 GB" plateau reads as "72 MB real + 5.9 GB cache" at a glance.
+    // The meter is the RESIDENT share of the charge, deliberately: it is the
+    // only part of a rising charge that a limit can actually kill for, so the
+    // shared warn/crit thresholds mean the same thing here as on the others.
+    // Gated on ANY of the three, not on `charged`: cgroup_memory reads
+    // memory.current and memory.stat through separate helpers so each degrades
+    // on its own, and a tile keyed to the headline alone would throw away a
+    // breakdown the reader deliberately preserved. The headline and the meter
+    // carry their own null handling, so a missing `charged` costs only itself.
+    var mem = t.memory;
+    if (mem && (mem.charged != null || mem.resident != null || mem.reclaimable != null)) {
+      var msub = (mem.resident == null ? '--' : bytes(mem.resident)) + ' resident · ' +
+        (mem.reclaimable == null ? '--' : bytes(mem.reclaimable)) + ' reclaimable';
+      // shmem is charged, is NOT droppable (swap-backed), and is excluded from
+      // reclaimable -- so it has to be visible, or a tmpfs-heavy container
+      // shows a charge that neither of the other two numbers accounts for.
+      if (mem.shmem) msub += ' · ' + bytes(mem.shmem) + ' shmem';
+      var mpct = (mem.resident == null || !mem.charged) ? null :
+        Math.round(100 * mem.resident / mem.charged);
+      out += tile('Container Memory', bytes(mem.charged), msub, mpct);
+      // 'unavailable', not a cgroup-v2 verdict: this branch is also reached on a
+      // host-namespace deployment (the controller exists, its interface files
+      // are absent from the v2 root) and on a partial read. The console cannot
+      // tell those apart, and a wrong diagnosis sends an operator to check the
+      // wrong thing -- the neighbouring tiles say 'unavailable' for the same
+      // reason, and so does the origin task's acceptance detail.
+    } else { out += tile('Container Memory', '--', 'unavailable'); }
     out += tile('Review Queue', t.queue_depth, 'PRs awaiting me, last poll');
     el('tiles').innerHTML = out;
   }
@@ -524,6 +562,25 @@ _JS = r"""
     });
   }
 
+  // Host-wide, not per session: it names whatever holds a resident charge,
+  // which is routinely not a reviewer at all. Read-only -- no kill button
+  // here, because these PIDs are unmanaged and the sessions panel above is
+  // the only place a process should be killed from.
+  function renderTopProcs(rows) {
+    rows = rows || [];
+    if (!rows.length) {
+      el('topprocs').innerHTML = '<div class="empty">No process data (/proc unreadable).</div>';
+      return;
+    }
+    var head = '<table><thead><tr><th class="num">PID</th><th>Process</th>' +
+      '<th class="num">RSS</th></tr></thead><tbody>';
+    el('topprocs').innerHTML = head + rows.map(function (p) {
+      return '<tr><td class="num mono">' + esc(p.pid) + '</td>' +
+        '<td class="mono">' + esc(p.comm) + '</td>' +
+        '<td class="num">' + bytes(p.rss_bytes) + '</td></tr>';
+    }).join('') + '</tbody></table>';
+  }
+
   function renderLog(log) {
     el('log-path').textContent = log.path || '(no log configured)';
     el('log').textContent = log.lines.length ? log.lines.join('\n') : '(log empty or unavailable)';
@@ -558,6 +615,7 @@ _JS = r"""
     renderPipeline(d.pipeline);
     renderInbox(d.inbox);
     renderSessions(d.sessions);
+    renderTopProcs(d.top_procs);
     renderLog(d.log);
     var when = new Date(d.generated_at * 1000).toLocaleTimeString();
     el('status-line').textContent = 'updated ' + when;

{alissa_tools_github_revloop-0.16.14 → alissa_tools_github_revloop-0.16.16}/src/main/alissa/tools/github/revloop/webui/sources.py

@@ -7,7 +7,10 @@ in strict budget order:
    UI-1 reader), the spawn ledger, the escalation table and the ping ledger. No
    GitHub call: the daemon already wrote everything down.
 2. **Local process state** -- `alissa tmux ls --json` for the session list, and
-   a `/proc` walk (sysinfo) of each session's pane-PID tree for CPU%/RSS.
+   a `/proc` walk (sysinfo) of each session's pane-PID tree for CPU%/RSS, plus
+   the two container-wide reads the per-session sums cannot answer: the cgroup
+   memory charge split into resident vs reclaimable, and the top processes by
+   RSS across the whole host. One `/proc` scan serves both.
 3. **Two cached remote checks** -- `gh api rate_limit` (60s cache) for the rate
    meter, and the PyPI version JSON (10m cache) for the running-vs-latest drift
    chip. These are the *only* network calls, and both are cached so a room full
@@ -61,6 +64,10 @@ from . import sysinfo
 
 # How many recent snapshots feed the sparklines / pipeline board.
 SPARK_POINTS = 60
+# How many processes the host-wide top-by-RSS list carries. Five is the whole
+# point of the panel: it names what is holding a resident charge, it is not a
+# process browser, and every extra row is payload on a ~10s poll.
+TOP_PROCS = 5
 # Cache lifetimes for the remote checks (seconds).
 RATE_CACHE_TTL = 60.0
 VERSION_CACHE_TTL = 600.0
@@ -156,6 +163,7 @@ class Sources:
         run: "Callable[..., str]" = proc_run,
         http_get: "Callable[[str, float], bytes | None]" = _default_http_get,
         proc_root: str = "/proc",
+        cgroup_root: str = "/sys/fs/cgroup",
         clock: Callable[[], float] = time.monotonic,
         wall_clock: Callable[[], float] = time.time,
     ) -> None:
@@ -165,6 +173,7 @@ class Sources:
         self._run = run
         self._http_get = http_get
         self._proc_root = proc_root
+        self._cgroup_root = cgroup_root
         self._clock = clock
         self._wall = wall_clock
         self._rate_cache = _Cache(RATE_CACHE_TTL, clock)
@@ -283,7 +292,11 @@ class Sources:
         rows = self._read_state([], lambda st: st.read_spawns(sessions=names))
         return {row["session"]: row for row in rows}
 
-    def sessions(self, spawns: "list[dict] | None" = None) -> "list[dict]":
+    def sessions(
+        self,
+        spawns: "list[dict] | None" = None,
+        index: "tuple[dict[int, list[int]], dict[int, dict]] | None" = None,
+    ) -> "list[dict]":
         """The managed-session table: liveness from `alissa tmux ls`, footprint
         from /proc, and the PR round each session is reviewing.
 
@@ -296,6 +309,12 @@ class Sources:
         `spawns` supplies the ledger rows directly; when it is None (the
         dashboard's path) they are read here, keyed by the names tmux just
         returned -- which is why the session list is fetched first.
+
+        `index` supplies the `/proc` snapshot. The dashboard now needs one
+        anyway for the host-wide top-process list, so it builds the index once
+        and hands the same one here; passed None (a caller that only wants the
+        table) the old lazy build is unchanged and a table with no live pane
+        still never scans `/proc`.
         """
         raw = self._safe_json(["alissa", "tmux", "ls", "--json"]) or []
         if not isinstance(raw, list):
@@ -311,9 +330,8 @@ class Sources:
         out: list[dict] = []
         # ONE /proc snapshot for the whole table: the index is identical for
         # every session in this build, so rebuilding it per session would make
-        # the walk O(sessions x processes). Built lazily -- a table with no
-        # live pane never scans /proc at all.
-        index: "tuple[dict[int, list[int]], dict[int, dict]] | None" = None
+        # the walk O(sessions x processes). Built lazily when the caller did
+        # not supply one -- a table with no live pane never scans /proc at all.
         for entry in raw:
             if not isinstance(entry, dict):
                 continue
@@ -479,9 +497,24 @@ class Sources:
         snaps = self.snapshots(SPARK_POINTS)
         latest = snaps[0] if snaps else None
         ledgers = self.ledgers()
-        sessions = self.sessions()
+        # ONE /proc scan for this whole build: the session table walks pane
+        # trees out of it and the top-process list ranks the same snapshot, so
+        # the two panels can never disagree about a process that exited between
+        # them -- and the host pays for one walk per poll, not two.
+        #
+        # The cost on the other side of that trade, so nobody reorders this
+        # thinking it is free: the snapshot is now taken BEFORE `sessions()`
+        # shells out to tmux, so a pane that starts inside that window is
+        # missing from `stats` and its row shows "--" for CPU%/RSS for one
+        # poll. Self-healing in ~10s, and cheaper than walking /proc twice.
+        proc_index = sysinfo.build_index(self._proc_root)
+        sessions = self.sessions(index=proc_index)
         rate = self.rate_limit()
         disk = sysinfo.disk_usage(self.config.workspace_root)
+        memory = sysinfo.cgroup_memory(self._cgroup_root)
+        top_procs = sysinfo.top_procs(
+            TOP_PROCS, proc_root=self._proc_root, index=proc_index
+        )
 
         # Sparklines want oldest -> newest for left-to-right drawing. "Active"
         # counts both buckets a live reviewer session sits in: a round enqueued
@@ -522,6 +555,11 @@ class Sources:
                 "live_sessions": sum(1 for s in sessions if s["live"]),
                 "rate": rate,
                 "volume": disk,
+                # The container's own charge, split three ways. Every field is
+                # None on a host without cgroup v2 (dev laptop, macOS) and the
+                # tile renders "unavailable" -- the console must not require
+                # Linux to load.
+                "memory": memory,
                 "queue_depth": latest["candidates"] if latest else 0,
             },
             "sparklines": sparklines,
@@ -533,6 +571,9 @@ class Sources:
             },
             "inbox": self._inbox(ledgers["escalations"], ledgers["pings"]),
             "sessions": sessions,
+            # Host-wide, not per session: when the memory tile says the charge
+            # IS resident, this is what names the holder.
+            "top_procs": top_procs,
             "log": self.log_tail(),
         }
 

alissa_tools_github_revloop-0.16.16/src/main/alissa/tools/github/revloop/webui/sysinfo.py

@@ -0,0 +1,356 @@
+"""Per-session resource accounting off `/proc`, plus workspace disk and
+container-memory usage.
+
+The sessions panel wants CPU% and RSS for each managed tmux session. tmux hands
+us a pane PID; the real work runs in that pane's child tree (a shell, the agent,
+its subprocesses), so we sum over the whole tree rooted at the pane PID.
+
+Two deliberate properties:
+
+* **Sample-free CPU.** Instantaneous CPU% needs two `/proc` reads spaced apart;
+  a dashboard endpoint polled every ~10s should not block sampling. Instead we
+  report the *cumulative average* since the pane started:
+  `100 * (utime+stime)/CLK_TCK / (uptime - starttime/CLK_TCK)`. It answers "how
+  hot has this session run over its life", which is the operator question, and
+  needs a single read.
+* **Vanished-PID tolerant.** Between listing `/proc` and reading a PID's `stat`,
+  the process can exit. Every read that fails (gone, permission, malformed) is
+  skipped -- a disappearing reviewer contributes nothing and never raises.
+
+The `/proc` root is a parameter so the parsing is testable against a crafted
+fixture directory (including a PID that is indexed but whose `stat` was deleted
+mid-walk -- the vanished-PID case the mutation bar pins).
+
+Per-session accounting cannot answer the question a platform memory graph
+asks. A Railway-style flat multi-GB plateau with zero reviewer sessions is
+CONTAINER-wide, and the per-pane sums (tens of MB) say nothing about it, so
+`cgroup_memory` reads the container's own cgroup v2 charge and splits it into
+the three numbers that settle "is that a leak?": what the container is charged
+for, what is really process memory, and what is page cache the kernel would
+drop the moment anything asked for it. `top_procs` is the same question one
+level down -- the whole `/proc`, not one pane tree -- so a charge that IS
+resident can be attributed to a process without shelling into the container.
+Both follow the module's conventions: roots are parameters, every read
+degrades to None instead of raising (a dev laptop or macOS has no cgroup v2
+and must still render the console), and neither samples.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+from pathlib import Path
+
+_CLK_TCK = os.sysconf("SC_CLK_TCK") if hasattr(os, "sysconf") else 100
+_PAGE_SIZE = os.sysconf("SC_PAGE_SIZE") if hasattr(os, "sysconf") else 4096
+
+# Field offsets INTO the tail of /proc/<pid>/stat (everything after the
+# "(comm)" field, which itself is field 3 == index 0 of the tail). See
+# proc(5): utime=14, stime=15, starttime=22, rss=24 -> tail indices below.
+_TAIL_PPID = 1
+_TAIL_UTIME = 11
+_TAIL_STIME = 12
+_TAIL_STARTTIME = 19
+_TAIL_RSS = 21
+_TAIL_MIN_LEN = 22
+
+# The cgroup v2 files the memory tile reads, and the `memory.stat` keys it
+# keeps. Deliberately a fixed, small set: `memory.stat` carries ~40 keys and
+# the tile answers one question, so parsing the rest would be payload we never
+# render. `anon` is process memory, `file` is page cache, `slab_reclaimable` is
+# kernel cache the shrinkers can free -- together they are the split between a
+# real footprint and a charge the kernel would give back under pressure.
+_CGROUP_CURRENT = "memory.current"
+_CGROUP_STAT = "memory.stat"
+_CGROUP_STAT_KEYS = (
+    "anon",
+    "file",
+    "inactive_file",
+    "shmem",
+    "slab_reclaimable",
+    "slab_unreclaimable",
+)
+
+
+def read_stat(proc_root: "str | os.PathLike[str]", pid: int) -> "dict | None":
+    """Parse one `/proc/<pid>/stat`, or None if the PID has vanished or the
+    line is malformed. The `comm` field can contain spaces and parentheses, so
+    we split on the LAST ')' before tokenising -- the canonical safe parse.
+
+    `comm` is carried in the row (between the FIRST '(' and that last ')', the
+    mirror of the same parse) purely for the top-process list: the tree sums
+    need only the numbers, but a top-5 by RSS that shows bare PIDs tells an
+    operator nothing about what is holding the memory.
+    """
+    try:
+        data = (Path(proc_root) / str(pid) / "stat").read_text()
+    except (OSError, ValueError):
+        return None
+    rparen = data.rfind(")")
+    lparen = data.find("(")
+    if rparen == -1 or lparen == -1 or lparen > rparen:
+        return None
+    tail = data[rparen + 1:].split()
+    if len(tail) < _TAIL_MIN_LEN:
+        return None
+    try:
+        return {
+            "pid": int(pid),
+            "comm": data[lparen + 1:rparen],
+            "ppid": int(tail[_TAIL_PPID]),
+            "cpu_ticks": int(tail[_TAIL_UTIME]) + int(tail[_TAIL_STIME]),
+            "starttime": int(tail[_TAIL_STARTTIME]),
+            "rss_pages": int(tail[_TAIL_RSS]),
+        }
+    except (ValueError, IndexError):
+        return None
+
+
+def read_uptime(proc_root: "str | os.PathLike[str]") -> "float | None":
+    try:
+        return float((Path(proc_root) / "uptime").read_text().split()[0])
+    except (OSError, ValueError, IndexError):
+        return None
+
+
+def build_index(
+    proc_root: "str | os.PathLike[str]",
+) -> "tuple[dict[int, list[int]], dict[int, dict]]":
+    """Scan `/proc` once: return (ppid -> [child pids], pid -> stat). Numeric
+    entries only; anything that vanishes mid-scan is silently skipped."""
+    children: dict[int, list[int]] = {}
+    stats: dict[int, dict] = {}
+    try:
+        entries = os.listdir(proc_root)
+    except OSError:
+        return children, stats
+    for name in entries:
+        if not name.isdigit():
+            continue
+        st = read_stat(proc_root, int(name))
+        if st is None:
+            continue
+        stats[st["pid"]] = st
+        children.setdefault(st["ppid"], []).append(st["pid"])
+    return children, stats
+
+
+def tree_pids(root_pid: int, children: "dict[int, list[int]]") -> "set[int]":
+    """Every PID in the subtree rooted at `root_pid` (inclusive). Iterative and
+    cycle-guarded -- a corrupt ppid loop can never spin forever."""
+    seen: set[int] = set()
+    stack = [root_pid]
+    while stack:
+        pid = stack.pop()
+        if pid in seen:
+            continue
+        seen.add(pid)
+        stack.extend(children.get(pid, ()))
+    return seen
+
+
+def tree_usage(
+    root_pid: "int | None",
+    *,
+    proc_root: "str | os.PathLike[str]" = "/proc",
+    index: "tuple[dict[int, list[int]], dict[int, dict]] | None" = None,
+) -> dict:
+    """CPU% (cumulative average since the pane started) and summed RSS for the
+    whole process tree under `root_pid`. Returns None/None when the root has
+    already vanished -- "unknown", the same thing the caller shows for a
+    session with no pane at all, so the column reads consistently.
+
+    `index` is the (children, stats) pair from `build_index`. Pass it when
+    accounting SEVERAL trees from one snapshot of `/proc`: the index is
+    identical for every session in one dashboard build, and rebuilding it per
+    session makes the walk O(sessions x processes) -- on a busy reviewer host
+    thousands of `stat` reads every poll, stolen from the reviewer agents the
+    console exists to watch. Omitted, it is built once for this call.
+    """
+    empty = {"pids": 0, "rss_bytes": None, "cpu_percent": None}
+    if root_pid is None:
+        return empty
+    children, stats = index if index is not None else build_index(proc_root)
+    if root_pid not in stats:
+        return empty
+    uptime = read_uptime(proc_root)
+    rss_pages = 0
+    cpu_ticks = 0
+    counted = 0
+    for pid in tree_pids(root_pid, children):
+        st = stats.get(pid)
+        if st is None:
+            continue
+        counted += 1
+        rss_pages += st["rss_pages"]
+        cpu_ticks += st["cpu_ticks"]
+    cpu_percent = None
+    if uptime is not None and _CLK_TCK:
+        wall = uptime - stats[root_pid]["starttime"] / _CLK_TCK
+        if wall > 0:
+            cpu_seconds = cpu_ticks / _CLK_TCK
+            cpu_percent = round(100.0 * cpu_seconds / wall, 1)
+    return {
+        "pids": counted,
+        "rss_bytes": rss_pages * _PAGE_SIZE,
+        "cpu_percent": cpu_percent,
+    }
+
+
+def top_procs(
+    n: int = 5,
+    *,
+    proc_root: "str | os.PathLike[str]" = "/proc",
+    index: "tuple[dict[int, list[int]], dict[int, dict]] | None" = None,
+) -> "list[dict]":
+    """The n biggest processes on the HOST by RSS: [{pid, comm, rss_bytes}],
+    largest first.
+
+    Deliberately the whole `/proc` and not a pane tree: the memory tile's
+    question is container-wide, so when the charge really is resident the
+    operator needs to see whatever is holding it -- which is routinely not a
+    reviewer session at all (the daemon itself, a stray build, the shell that
+    started everything).
+
+    `index` is the same (children, stats) pair `tree_usage` takes, so a
+    dashboard build that already scanned `/proc` for its session table ranks
+    processes off that ONE snapshot instead of walking every PID twice.
+    Vanished PIDs never appear: `build_index` has already dropped them, and a
+    process that exits after the scan simply ranks with its last-known RSS.
+
+    Ties break on PID so the order is total -- an equal-RSS pair must not
+    reshuffle between polls and make a still list look like it is churning.
+    """
+    if n <= 0:
+        return []
+    _, stats = index if index is not None else build_index(proc_root)
+    ranked = sorted(stats.values(), key=lambda st: (-st["rss_pages"], st["pid"]))
+    return [
+        {
+            "pid": st["pid"],
+            "comm": st.get("comm") or "?",
+            "rss_bytes": st["rss_pages"] * _PAGE_SIZE,
+        }
+        for st in ranked[:n]
+    ]
+
+
+def _read_int_file(path: Path) -> "int | None":
+    """One cgroup scalar file as an int, or None when it is absent, unreadable
+    or not a number. cgroup v2 writes the literal `max` in some files, which is
+    exactly the malformed case this returns None for."""
+    try:
+        return int(path.read_text().strip())
+    except (OSError, ValueError):
+        return None
+
+
+def _read_stat_keys(path: Path, keys: "tuple[str, ...]") -> "dict[str, int | None]":
+    """The requested `key value` lines of a cgroup `*.stat` file. Every key is
+    present in the result whether or not the file had it, so the payload shape
+    never depends on the kernel version -- a missing or unparseable key is
+    None, the same thing the whole-file failure produces."""
+    out: "dict[str, int | None]" = {key: None for key in keys}
+    try:
+        text = path.read_text()
+    except (OSError, ValueError):
+        return out
+    wanted = set(keys)
+    for line in text.splitlines():
+        name, _, value = line.partition(" ")
+        if name not in wanted:
+            continue
+        try:
+            out[name] = int(value.strip())
+        except ValueError:
+            out[name] = None
+    return out
+
+
+def _sum_or_none(*values: "int | None") -> "int | None":
+    """Sum only when EVERY part is known. A partial sum would be reported as a
+    whole bucket and read as a smaller cache than the container really holds --
+    an unknown number must stay unknown rather than become a wrong one."""
+    if any(value is None for value in values):
+        return None
+    return sum(value for value in values if value is not None)
+
+
+def _drop_shmem(file_bytes: "int | None", shmem: "int | None") -> "int | None":
+    """The droppable part of `file`. `shmem` unknown means the droppable part
+    is unknown -- publishing `file` whole would be the reassuring-direction
+    error the split exists to prevent."""
+    if file_bytes is None or shmem is None:
+        return None
+    return max(0, file_bytes - shmem)
+
+
+def cgroup_memory(
+    cgroup_root: "str | os.PathLike[str]" = "/sys/fs/cgroup",
+) -> dict:
+    """The container's own memory charge, split for the operator.
+
+    Answers the question a platform memory graph raises and cannot settle: a
+    flat multi-GB plateau is `charged` (cgroup v2 `memory.current`), but most
+    of it is routinely cache the kernel would drop under pressure, not a leak.
+    So we also report:
+
+    * `resident` -- `anon`, the process memory that is really in use.
+    * `reclaimable` -- `(file - shmem) + slab_reclaimable`: the page cache plus
+      the shrinkable kernel caches, the "not really in use" bucket.
+    * `shmem` -- broken out of `file` rather than left inside it, because it is
+      not droppable: tmpfs, shm segments and shared anonymous mmaps are
+      swap-backed, so with swap disabled or capped (the normal container case)
+      the kernel cannot reclaim them under pressure -- they are what the
+      container gets OOM-killed for. Counting them as reclaimable is the one
+      way this reader can be wrong in the REASSURING direction, telling an
+      operator "5.9 GB of cache, no leak" about pages nothing can free. Issue
+      #74's scope text prescribes `file + slab_reclaimable` verbatim; the same
+      sentence calls the result the "not really in use" bucket, and where the
+      formula and the words disagree the words are the requirement. Surfaced as
+      its own magnitude instead of folded into `resident`, because "5 GB of
+      tmpfs" and "5 GB of process heap" are different operator problems even
+      though neither is droppable.
+
+    The raw keys ride along for a spot check against an in-container
+    `memory.stat`. Note the summary numbers do NOT partition the charge --
+    kernel stacks, pagetables and sockets are charged too -- they are the
+    magnitudes an operator compares, not a balance sheet.
+
+    Never raises. On a host without cgroup v2 -- a dev laptop, macOS, a v1
+    cgroup tree -- every field is None and the console renders "unavailable";
+    the root is a parameter so all of that is testable off a fixture dir.
+    """
+    root = Path(cgroup_root)
+    charged = _read_int_file(root / _CGROUP_CURRENT)
+    stat = _read_stat_keys(root / _CGROUP_STAT, _CGROUP_STAT_KEYS)
+    out: "dict[str, int | None]" = {
+        "charged": charged,
+        "resident": stat["anon"],
+        # `shmem` is a SUBSET of `file` in cgroup v2, so it is subtracted, not
+        # added. Clamped at zero: the two keys are sampled from one read of one
+        # file and cannot legitimately cross, but a negative "cache" number
+        # would be a worse thing to render than a zero if a kernel ever
+        # disagreed with that.
+        "reclaimable": _sum_or_none(
+            _drop_shmem(stat["file"], stat["shmem"]), stat["slab_reclaimable"]
+        ),
+    }
+    out.update(stat)
+    return out
+
+
+def disk_usage(path: "str | os.PathLike[str]") -> "dict | None":
+    """Workspace volume usage for the stat tile, or None if the path is
+    unreadable. Percent is used/total, rounded -- the meter the console fills."""
+    try:
+        usage = shutil.disk_usage(os.fspath(path))
+    except OSError:
+        return None
+    percent = round(100.0 * usage.used / usage.total, 1) if usage.total else None
+    return {
+        "total_bytes": usage.total,
+        "used_bytes": usage.used,
+        "free_bytes": usage.free,
+        "percent": percent,
+    }

{alissa_tools_github_revloop-0.16.14 → alissa_tools_github_revloop-0.16.16/src/main/alissa_tools_github_revloop.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-revloop
-Version: 0.16.14
+Version: 0.16.16
 Summary: ALISSA-TOOLS-GITHUB-REVLOOP
 Home-page: https://alissa.app
 Author: Fahera

alissa_tools_github_revloop-0.16.14/src/main/alissa/tools/github/revloop/version

@@ -1 +0,0 @@
-0.16.14

alissa_tools_github_revloop-0.16.14/src/main/alissa/tools/github/revloop/webui/sysinfo.py

@@ -1,174 +0,0 @@
-"""Per-session resource accounting off `/proc`, plus workspace disk usage.
-
-The sessions panel wants CPU% and RSS for each managed tmux session. tmux hands
-us a pane PID; the real work runs in that pane's child tree (a shell, the agent,
-its subprocesses), so we sum over the whole tree rooted at the pane PID.
-
-Two deliberate properties:
-
-* **Sample-free CPU.** Instantaneous CPU% needs two `/proc` reads spaced apart;
-  a dashboard endpoint polled every ~10s should not block sampling. Instead we
-  report the *cumulative average* since the pane started:
-  `100 * (utime+stime)/CLK_TCK / (uptime - starttime/CLK_TCK)`. It answers "how
-  hot has this session run over its life", which is the operator question, and
-  needs a single read.
-* **Vanished-PID tolerant.** Between listing `/proc` and reading a PID's `stat`,
-  the process can exit. Every read that fails (gone, permission, malformed) is
-  skipped -- a disappearing reviewer contributes nothing and never raises.
-
-The `/proc` root is a parameter so the parsing is testable against a crafted
-fixture directory (including a PID that is indexed but whose `stat` was deleted
-mid-walk -- the vanished-PID case the mutation bar pins).
-"""
-
-from __future__ import annotations
-
-import os
-import shutil
-from pathlib import Path
-
-_CLK_TCK = os.sysconf("SC_CLK_TCK") if hasattr(os, "sysconf") else 100
-_PAGE_SIZE = os.sysconf("SC_PAGE_SIZE") if hasattr(os, "sysconf") else 4096
-
-# Field offsets INTO the tail of /proc/<pid>/stat (everything after the
-# "(comm)" field, which itself is field 3 == index 0 of the tail). See
-# proc(5): utime=14, stime=15, starttime=22, rss=24 -> tail indices below.
-_TAIL_PPID = 1
-_TAIL_UTIME = 11
-_TAIL_STIME = 12
-_TAIL_STARTTIME = 19
-_TAIL_RSS = 21
-_TAIL_MIN_LEN = 22
-
-
-def read_stat(proc_root: "str | os.PathLike[str]", pid: int) -> "dict | None":
-    """Parse one `/proc/<pid>/stat`, or None if the PID has vanished or the
-    line is malformed. The `comm` field can contain spaces and parentheses, so
-    we split on the LAST ')' before tokenising -- the canonical safe parse."""
-    try:
-        data = (Path(proc_root) / str(pid) / "stat").read_text()
-    except (OSError, ValueError):
-        return None
-    rparen = data.rfind(")")
-    if rparen == -1:
-        return None
-    tail = data[rparen + 1:].split()
-    if len(tail) < _TAIL_MIN_LEN:
-        return None
-    try:
-        return {
-            "pid": int(pid),
-            "ppid": int(tail[_TAIL_PPID]),
-            "cpu_ticks": int(tail[_TAIL_UTIME]) + int(tail[_TAIL_STIME]),
-            "starttime": int(tail[_TAIL_STARTTIME]),
-            "rss_pages": int(tail[_TAIL_RSS]),
-        }
-    except (ValueError, IndexError):
-        return None
-
-
-def read_uptime(proc_root: "str | os.PathLike[str]") -> "float | None":
-    try:
-        return float((Path(proc_root) / "uptime").read_text().split()[0])
-    except (OSError, ValueError, IndexError):
-        return None
-
-
-def build_index(
-    proc_root: "str | os.PathLike[str]",
-) -> "tuple[dict[int, list[int]], dict[int, dict]]":
-    """Scan `/proc` once: return (ppid -> [child pids], pid -> stat). Numeric
-    entries only; anything that vanishes mid-scan is silently skipped."""
-    children: dict[int, list[int]] = {}
-    stats: dict[int, dict] = {}
-    try:
-        entries = os.listdir(proc_root)
-    except OSError:
-        return children, stats
-    for name in entries:
-        if not name.isdigit():
-            continue
-        st = read_stat(proc_root, int(name))
-        if st is None:
-            continue
-        stats[st["pid"]] = st
-        children.setdefault(st["ppid"], []).append(st["pid"])
-    return children, stats
-
-
-def tree_pids(root_pid: int, children: "dict[int, list[int]]") -> "set[int]":
-    """Every PID in the subtree rooted at `root_pid` (inclusive). Iterative and
-    cycle-guarded -- a corrupt ppid loop can never spin forever."""
-    seen: set[int] = set()
-    stack = [root_pid]
-    while stack:
-        pid = stack.pop()
-        if pid in seen:
-            continue
-        seen.add(pid)
-        stack.extend(children.get(pid, ()))
-    return seen
-
-
-def tree_usage(
-    root_pid: "int | None",
-    *,
-    proc_root: "str | os.PathLike[str]" = "/proc",
-    index: "tuple[dict[int, list[int]], dict[int, dict]] | None" = None,
-) -> dict:
-    """CPU% (cumulative average since the pane started) and summed RSS for the
-    whole process tree under `root_pid`. Returns None/None when the root has
-    already vanished -- "unknown", the same thing the caller shows for a
-    session with no pane at all, so the column reads consistently.
-
-    `index` is the (children, stats) pair from `build_index`. Pass it when
-    accounting SEVERAL trees from one snapshot of `/proc`: the index is
-    identical for every session in one dashboard build, and rebuilding it per
-    session makes the walk O(sessions x processes) -- on a busy reviewer host
-    thousands of `stat` reads every poll, stolen from the reviewer agents the
-    console exists to watch. Omitted, it is built once for this call.
-    """
-    empty = {"pids": 0, "rss_bytes": None, "cpu_percent": None}
-    if root_pid is None:
-        return empty
-    children, stats = index if index is not None else build_index(proc_root)
-    if root_pid not in stats:
-        return empty
-    uptime = read_uptime(proc_root)
-    rss_pages = 0
-    cpu_ticks = 0
-    counted = 0
-    for pid in tree_pids(root_pid, children):
-        st = stats.get(pid)
-        if st is None:
-            continue
-        counted += 1
-        rss_pages += st["rss_pages"]
-        cpu_ticks += st["cpu_ticks"]
-    cpu_percent = None
-    if uptime is not None and _CLK_TCK:
-        wall = uptime - stats[root_pid]["starttime"] / _CLK_TCK
-        if wall > 0:
-            cpu_seconds = cpu_ticks / _CLK_TCK
-            cpu_percent = round(100.0 * cpu_seconds / wall, 1)
-    return {
-        "pids": counted,
-        "rss_bytes": rss_pages * _PAGE_SIZE,
-        "cpu_percent": cpu_percent,
-    }
-
-
-def disk_usage(path: "str | os.PathLike[str]") -> "dict | None":
-    """Workspace volume usage for the stat tile, or None if the path is
-    unreadable. Percent is used/total, rounded -- the meter the console fills."""
-    try:
-        usage = shutil.disk_usage(os.fspath(path))
-    except OSError:
-        return None
-    percent = round(100.0 * usage.used / usage.total, 1) if usage.total else None
-    return {
-        "total_bytes": usage.total,
-        "used_bytes": usage.used,
-        "free_bytes": usage.free,
-        "percent": percent,
-    }