nodeview-slurm 0.1.0__py3-none-any.whl

nodeview/render.py

@@ -0,0 +1,688 @@
+"""Content rendering.
+
+These are rich renderables, not Textual widgets: the same functions serve the
+interactive TUI and the static --once snapshot without duplicating anything.
+Each function returns the *content* of a panel; the caller adds the frame.
+
+On the use of color see palette.py: here we just ask it for the right hue for
+the right job, and never let a color travel alone.
+"""
+from __future__ import annotations
+
+from rich import box
+from rich.console import Group
+from rich.table import Table
+from rich.text import Text
+
+from . import analysis as an
+from . import manual as manual_data
+from .i18n import t
+from . import palette
+from .source import Snapshot
+
+BUSY, FREE = "●", "○"          # single GPUs: the shape tells them apart even without color
+BLOCK, EMPTY = "█", "▁"        # continuous meters
+
+# internal key -> (icon, color role). The displayed text comes from the
+# catalog: the key must not change when the language changes.
+STATUS = {
+    'free':      ("✓", 'good'),
+    'cpu_only':  ("✓", 'good'),
+    'partial':   ("◐", 'ink_soft'),
+    'full':      ("●", 'serious'),
+    'reserved':  ("⏸", 'warning'),
+    'drain':     ("▲", 'warning'),
+    'down':      ("✖", 'critical'),
+}
+
+LEVEL_ICON = {'info': "●", 'warn': "▲", 'bad': "✖"}
+LEVEL_ROLE = {'info': 'ink_muted', 'warn': 'warning', 'bad': 'critical'}
+
+
+def _p():
+    return palette.active()
+
+
+def muted() -> str:
+    return _p().ink_muted
+
+
+def soft() -> str:
+    return _p().ink_soft
+
+
+def meter(used: float, total: float, width: int = 14) -> Text:
+    """Quantity: a single hue, from light to dark. No traffic lights."""
+    pal = _p()
+    if total <= 0:
+        return Text(t('na'), style=pal.ink_muted)
+    ratio = max(0.0, min(1.0, used / total))
+    filled = min(width, max(0, round(width * ratio)))
+    if used > 0 and filled == 0:
+        filled = 1
+    out = Text()
+    out.append(BLOCK * filled, style=pal.fill(ratio))
+    out.append(EMPTY * (width - filled), style=pal.rule)
+    return out
+
+
+def gpu_slots(node, occupants) -> Text:
+    """One dot per GPU, colored like whoever is using it.
+
+    The indices come from Slurm (`GresUsed` on the node) and the owner from
+    the job details (`scontrol -d show job`, which lists for each job the
+    indices assigned on each node): position and identity are both real,
+    not reconstructed. The colors match the chips and the legend, so you can
+    tell at a glance who holds what.
+    """
+    pal = _p()
+    out = Text()
+    if node.gpus_total <= 0:
+        return Text("-", style=pal.ink_muted)
+
+    busy_idx = set(node.gpu_indices_used)
+    owners = node.gpu_owners or {}
+    # GPUs the node reports as busy but with no known owner: happens when a
+    # job ends between one read and the next
+    orphans = len(busy_idx - set(owners))
+
+    for i in range(node.gpus_total):
+        user = owners.get(i)
+        busy = i in busy_idx or user is not None
+        if not busy and orphans > 0:
+            busy, orphans = True, orphans - 1
+        if not busy:
+            out.append(FREE, style=pal.rule)
+        elif user:
+            out.append(occupants.shape(user), style=occupants.style(user))
+        else:
+            out.append(BUSY, style=pal.fill(0.8))
+    return out
+
+
+def chips(node, occupants) -> Text:
+    """Colored chips for whoever is on the node: color plus name, never the
+    color alone. Beyond three, the rest is summed up."""
+    pal = _p()
+    out = Text()
+    totals = {}
+    for occ in node.occupants:
+        totals[occ.user] = totals.get(occ.user, 0) + occ.gpus
+    if not totals:
+        return Text(t('node.empty'), style=pal.ink_muted)
+
+    ranked = sorted(totals.items(), key=lambda kv: (-kv[1], kv[0]))
+    for i, (user, gpus) in enumerate(ranked[:3]):
+        if i:
+            out.append("  ")
+        out.append(occupants.shape(user) + " ", style=occupants.style(user))
+        label = user if len(user) <= 14 else user[:13] + "…"
+        mine = user == occupants.me
+        out.append(label, style=("bold " + pal.ink) if mine else pal.ink_soft)
+        out.append(f"×{gpus}" if gpus else t('node.cpu_job'), style=pal.ink_muted)
+    if len(ranked) > 3:
+        out.append(f"  +{len(ranked) - 3}", style=pal.ink_muted)
+    return out
+
+
+def status_cell(node) -> Text:
+    pal = _p()
+    if node.status == 'down':
+        key = 'down'
+    elif node.status == 'drain':
+        key = 'drain'
+    elif node.reserved != 'no':
+        key = 'reserved'
+    elif node.gpus_free == 0:
+        key = 'full'
+    elif node.gpus_used == 0:
+        # all GPUs free, but if the CPUs are taken the node isn't empty:
+        # just calling it "free" would be misleading
+        key = 'cpu_only' if node.cpus_alloc else 'free'
+    else:
+        key = 'partial'
+    icon, role = STATUS[key]
+    return Text(f"{icon} {t('node.' + key)}", style=getattr(pal, role))
+
+
+def gb(mb: float) -> str:
+    return f"{mb / 1024:.0f}G"
+
+
+def tb(mb: float) -> str:
+    return f"{mb / 1024 / 1024:.1f}T"
+
+
+def join_nodes(nodes, limit: int = 6) -> str:
+    names = [n.name for n in nodes]
+    if len(names) <= limit:
+        return ", ".join(names)
+    return ", ".join(names[:limit]) + f"  +{len(names) - limit}"
+
+
+def _table(*columns, **kwargs) -> Table:
+    tbl = Table(box=box.SIMPLE_HEAD, expand=True, pad_edge=False,
+              header_style=f"bold {muted()}", **kwargs)
+    for col in columns:
+        tbl.add_column(**col)
+    return tbl
+
+
+# --------------------------------------------------------------------------
+# "me" screen
+# --------------------------------------------------------------------------
+
+def my_jobs(snap: Snapshot):
+    pal = _p()
+    mine = snap.my_jobs
+    blocks = []
+
+    if not mine:
+        blocks.append(Text(t('job.none'), style=pal.ink_muted))
+    else:
+        tbl = _table(
+            dict(header=t('col.id'), style=pal.ink_muted, no_wrap=True),
+            dict(header=t('col.name'), ratio=3, no_wrap=True, overflow="ellipsis"),
+            dict(header=t('col.state'), justify="center", no_wrap=True),
+            dict(header=t('col.gpu'), justify="right", no_wrap=True),
+            dict(header=t('col.ram'), justify="right", no_wrap=True),
+            dict(header=t('col.time'), justify="right", no_wrap=True),
+            dict(header=t('col.where_why'), ratio=4, overflow="ellipsis"),
+        )
+        for job in sorted(mine, key=lambda j: (j.pending, j.jobid)):
+            if job.running:
+                state = Text(t('job.running_short'), style=f"bold {pal.good}")
+                where = Text(", ".join(sorted(set(job.nodes))) or "-", style=pal.ink)
+            else:
+                state = Text(t('job.pending_short'), style=f"bold {pal.warning}")
+                label, detail = an.explain_reason(job.reason)
+                where = Text(label, style=pal.warning)
+                if detail:
+                    where.append(f" · {detail}", style=pal.ink_muted)
+            tbl.add_row(job.jobid, job.name, state, str(job.gpus),
+                      gb(job.mem_mb), job.runtime, where)
+        blocks.append(tbl)
+
+    quota = an.my_quota(snap)
+    line = Text()
+    line.append(t('job.quota'), style=pal.ink_muted)
+    if quota.limit is None:
+        line.append(t('job.no_limit'), style=pal.ink_muted)
+    else:
+        line.append(f"{quota.used}/{int(quota.limit)} ", style=pal.ink)
+        line.append(meter(quota.used, int(quota.limit), 12))
+        room = quota.headroom
+        line.append(t('job.can_ask'), style=pal.ink_muted)
+        line.append(t('job.gpus', n=room),
+                    style=f"bold {pal.good if room else pal.critical}")
+    blocks.append(line)
+
+    groups = an.gpus_by_group(snap)
+    if groups:
+        gl = Text(t('job.by_group'), style=pal.ink_muted)
+        for i, (name, n) in enumerate(groups[:5]):
+            if i:
+                gl.append("  ·  ", style=pal.ink_muted)
+            gl.append(f"{name} ", style=pal.ink_muted)
+            gl.append(str(n), style=f"bold {pal.ink}")
+        blocks.append(gl)
+    return Group(*blocks)
+
+
+def where_do_i_fit(snap: Snapshot):
+    pal = _p()
+    rows = []
+    for fit in an.fits(snap):
+        label = Text(f"{fit.gpus:>2} {t('col.gpu')}  ", style=f"bold {pal.ink}")
+        if fit.over_user_quota:
+            quota = an.my_quota(snap)
+            label.append(t('fit.over_quota', limit=int(quota.limit)), style=pal.critical)
+            label.append(t('fit.left', n=quota.headroom), style=f"bold {pal.critical}")
+        elif not fit.nodes:
+            label.append(t('fit.none'), style=pal.warning)
+        else:
+            best = fit.nodes[0]
+            label.append(t('fit.now_on'), style=pal.good)
+            label.append(join_nodes(fit.nodes), style=f"bold {pal.good}")
+            label.append(t('fit.roomiest', node=best.name, gpus=best.gpus_free,
+                           mem=gb(best.mem_unalloc_mb)), style=pal.ink_muted)
+        rows.append(label)
+
+    roomy = sorted([n for n in snap.nodes if n.schedulable],
+                   key=lambda n: -n.mem_unalloc_mb)[:3]
+    if roomy:
+        mem = Text(t('fit.free_ram'), style=pal.ink_muted)
+        mem.append("  ·  ".join(f"{n.name} {gb(n.mem_unalloc_mb)}" for n in roomy),
+                   style=pal.ink_soft)
+        rows.append(mem)
+    return Group(*rows)
+
+
+def cluster(snap: Snapshot):
+    pal = _p()
+    used, total = snap.gpus_used, snap.gpus_total
+    ratio = used / total if total else 0.0
+
+    head = Text()
+    head.append(t('col.gpu') + "  ", style=pal.ink_muted)
+    head.append(f"{used}/{total} ", style=pal.ink)
+    head.append(meter(used, total, 20))
+    head.append(f" {ratio * 100:.0f}%", style=f"bold {pal.ink}")
+    head.append(t('cluster.free'), style=pal.ink_muted)
+    head.append(str(snap.gpus_free), style=f"bold {pal.good}")
+    head.append(t('cluster.queued'), style=pal.ink_muted)
+    head.append(str(len(snap.pending_jobs)), style=f"bold {pal.ink}")
+    head.append(t('cluster.running'), style=pal.ink_muted)
+    head.append(str(len(snap.running_jobs)), style=f"bold {pal.ink}")
+
+    blocks = [head]
+
+    story = an.headline(snap)
+    if story:
+        blocks.append(Text(story, style=f"bold {pal.fill(0.75)}"))
+
+    for level, text in an.warnings(snap):
+        line = Text(f" {LEVEL_ICON[level]} ", style=getattr(pal, LEVEL_ROLE[level]))
+        line.append(text, style=getattr(pal, LEVEL_ROLE[level]) if level != 'info' else pal.ink_muted)
+        blocks.append(line)
+    return Group(*blocks)
+
+
+def _pct_style(pct, warn=80.0, bad=95.0):
+    """The color says how close you are to the wall; the number says it anyway."""
+    pal = _p()
+    if pct is None:
+        return pal.ink_muted
+    if pct >= bad:
+        return pal.critical
+    if pct >= warn:
+        return pal.warning
+    return pal.ink
+
+
+def _gauge(label: str, used, total, pct, unit: str, width: int = 14,
+           warn=80.0, bad=95.0, note: str = "") -> Text:
+    pal = _p()
+    if len(label) > 23:
+        label = label[:22] + "…"
+    out = Text(f"  {label:<24}", style=pal.ink_soft)
+    out.append(meter(used or 0, total or 0, width))
+    if used is not None and total:
+        out.append(f" {used:>9,.0f}/{total:<10,.0f}".replace(',', '.'), style=pal.ink_soft)
+    else:
+        out.append(f" {'?':>20}", style=pal.ink_muted)
+    out.append(f"{unit:<4}", style=pal.ink_muted)
+    if pct is not None:
+        out.append(f"{pct:>6.1f}%", style=f"bold {_pct_style(pct, warn, bad)}")
+    if note:
+        out.append(f"  {note}", style=_pct_style(pct, warn, bad))
+    return out
+
+
+def my_account(prof):
+    """What the cluster knows about you, and that you rarely look at.
+
+    Budget, quotas and expiration don't change minute to minute, but when they
+    run out they block jobs without explaining why: worth keeping them in
+    sight, even if at the bottom of the page.
+    """
+    pal = _p()
+    if prof is None:
+        return Text(t('app.loading'), style=pal.ink_muted)
+    if prof.empty:
+        return Text(t('acct.none'), style=pal.ink_muted)
+
+    blocks = []
+
+    # the alarm bells at the top, if there are any
+    alerts = []
+    for b in prof.budgets:
+        if b.pct is not None and b.pct >= 95:
+            alerts.append(t('acct.budget_spent', project=b.project, pct=f"{b.pct:.1f}"))
+    for q in prof.quotas:
+        if q.pct is not None and q.pct >= 90:
+            alerts.append(t('acct.disk_full', fs=q.filesystem, owner=q.owner,
+                            pct=f"{q.pct:.0f}"))
+    exp = prof.expiration
+    if exp and exp.days_left is not None and exp.days_left <= 30:
+        alerts.append(t('acct.expiring', n=exp.days_left))
+    for text in alerts:
+        line = Text(" \u25b2 ", style=pal.warning)
+        line.append(text, style=f"bold {pal.warning}")
+        blocks.append(line)
+
+    if exp:
+        line = Text(t('acct.expiration'), style=pal.ink_muted)
+        line.append(exp.date.split()[0], style=pal.ink)
+        if exp.days_left is not None:
+            style = pal.critical if exp.days_left <= 14 else (
+                pal.warning if exp.days_left <= 30 else pal.ink_soft)
+            line.append(t('acct.in_days', n=exp.days_left), style=f"bold {style}")
+        blocks.append(line)
+
+    if prof.budgets:
+        blocks.append(Text(""))
+        blocks.append(Text(t('acct.budget_title'), style=f"bold {pal.ink_muted}")
+                      .append(t('acct.budget_sub'), style=pal.ink_muted))
+        for b in sorted(prof.budgets, key=lambda x: -(x.pct or 0)):
+            note = t('acct.exhausted') if (b.pct or 0) >= 99 else ""
+            blocks.append(_gauge(b.project, b.used, b.total, b.pct, "h", note=note))
+
+    if prof.quotas:
+        blocks.append(Text(""))
+        blocks.append(Text(t('acct.quota_title'), style=f"bold {pal.ink_muted}"))
+        for q in sorted(prof.quotas, key=lambda x: -(x.pct or 0)):
+            blocks.append(_gauge(f"{q.filesystem:<7}{q.owner}", q.used_gb, q.quota_gb,
+                                 q.pct, "GB", warn=85.0, bad=95.0))
+
+    if prof.shares:
+        blocks.append(Text(""))
+        line = Text(t('acct.fairshare'), style=f"bold {pal.ink_muted}")
+        for i, sh in enumerate(prof.shares):
+            if i:
+                line.append("   \u00b7   ", style=pal.ink_muted)
+            line.append(f"{sh.account} ", style=pal.ink_soft)
+            factor = sh.factor
+            style = pal.ink
+            if factor is not None:
+                style = pal.critical if factor < 0.25 else (
+                    pal.warning if factor < 0.5 else pal.good)
+            line.append(f"{factor:.2f}" if factor is not None else "?", style=f"bold {style}")
+        blocks.append(line)
+        blocks.append(Text(t('acct.fairshare_hint'), style=pal.ink_muted))
+
+    h = prof.history
+    if h and h.finished:
+        blocks.append(Text(""))
+        line = Text(t('acct.last_days', n=h.days), style=f"bold {pal.ink_muted}")
+        line.append(t('acct.completed', n=h.completed), style=pal.good)
+        if h.failed:
+            rate = h.failure_rate or 0
+            line.append("   \u00b7   ", style=pal.ink_muted)
+            line.append(t('acct.failed', n=h.failed),
+                        style=pal.critical if rate >= 0.2 else pal.warning)
+            line.append(f" ({rate * 100:.0f}%)", style=pal.ink_muted)
+        if h.cancelled:
+            line.append("   \u00b7   ", style=pal.ink_muted)
+            line.append(t('acct.cancelled', n=h.cancelled), style=pal.ink_soft)
+        if h.timeout:
+            line.append("   \u00b7   ", style=pal.ink_muted)
+            line.append(t('acct.timeout', n=h.timeout), style=pal.warning)
+        blocks.append(line)
+
+    if prof.accounts:
+        blocks.append(Text(""))
+        line = Text(t('acct.accounts'), style=f"bold {pal.ink_muted}")
+        line.append("   \u00b7   ".join(prof.accounts), style=pal.ink_soft)
+        blocks.append(line)
+        qos = sorted({q for lst in prof.accounts.values() for q in lst})
+        if qos:
+            line = Text(t('acct.qos'), style=f"bold {pal.ink_muted}")
+            line.append(", ".join(qos), style=pal.ink_muted)
+            blocks.append(line)
+
+    return Group(*blocks)
+
+
+# --------------------------------------------------------------------------
+# "cluster" screen
+# --------------------------------------------------------------------------
+
+def totals_strip(snap: Snapshot):
+    """The three numbers that sum up the cluster, plus what lies behind them."""
+    pal = _p()
+    rows = []
+
+    def line(label, used, total, unit_fn, extra: Text):
+        row = Text()
+        row.append(f"{label:<5}", style=pal.ink_muted)
+        row.append(f"{unit_fn(used):>7} / {unit_fn(total):<8}", style=pal.ink)
+        row.append(meter(used, total, 18))
+        row.append(f" {used / total * 100:>3.0f}%" if total else "   -",
+                   style=f"bold {pal.ink}")
+        row.append("   ")
+        row.append_text(extra)
+        return row
+
+    free_nodes = [n for n in snap.nodes if n.schedulable]
+    gpu_extra = Text()
+    gpu_extra.append(t('cluster.free_on'), style=pal.ink_muted)
+    gpu_extra.append(str(snap.gpus_free), style=f"bold {pal.good}")
+    gpu_extra.append(t('cluster.free_nodes', n=len(free_nodes)), style=pal.ink_muted)
+    rows.append(line(t('col.gpu'), snap.gpus_used, snap.gpus_total,
+                     lambda v: f"{v:.0f}", gpu_extra))
+
+    load = sum(n.cpu_load for n in snap.nodes)
+    cpu_extra = Text()
+    cpu_extra.append(t('cluster.real_load'), style=pal.ink_muted)
+    cpu_extra.append(f"{load:.0f}", style=f"bold {pal.ink}")
+    if snap.cpus_used:
+        cpu_extra.append(t('cluster.of_allocated',
+                           pct=f"{load / snap.cpus_used * 100:.0f}"), style=pal.ink_muted)
+    rows.append(line(t('col.cpu'), snap.cpus_used, snap.cpus_total,
+                     lambda v: f"{v:.0f}", cpu_extra))
+
+    ram_extra = Text()
+    ram_extra.append(t('cluster.unallocated'), style=pal.ink_muted)
+    ram_extra.append(tb(snap.mem_total_mb - snap.mem_used_mb), style=f"bold {pal.good}")
+    rows.append(line(t('col.ram'), snap.mem_used_mb, snap.mem_total_mb, tb, ram_extra))
+
+    models = {n.gpu_model for n in snap.nodes}
+    down = [n for n in snap.nodes if n.status == 'down']
+    drain = [n for n in snap.nodes if n.status == 'drain']
+    tail = Text()
+    tail.append(t('cluster.n_nodes', n=len(snap.nodes)), style=pal.ink)
+    tail.append("  ·  ", style=pal.ink_muted)
+    tail.append(t('cluster.n_models', n=len(models)), style=pal.ink)
+    if down:
+        tail.append("  ·  ", style=pal.ink_muted)
+        tail.append(t('cluster.n_down', n=len(down)), style=f"bold {pal.critical}")
+    if drain:
+        tail.append("  ·  ", style=pal.ink_muted)
+        tail.append(t('cluster.n_drain', n=len(drain)), style=f"bold {pal.warning}")
+    rows.append(tail)
+    return Group(*rows)
+
+
+def node_table(snap: Snapshot, occupants, only_free: bool = False) -> Table:
+    pal = _p()
+    tbl = _table(
+        dict(header=t('col.node'), no_wrap=True),
+        dict(header=t('col.gpu'), no_wrap=True, justify="left"),
+        dict(header=t('col.used'), no_wrap=True, justify="right"),
+        dict(header=t('col.model'), no_wrap=True, style=pal.ink_soft),
+        dict(header=t('col.cpu'), no_wrap=True),
+        dict(header=t('col.ram'), no_wrap=True),
+        dict(header=t('col.status'), no_wrap=True),
+        dict(header=t('col.occupied_by'), ratio=3, no_wrap=True, overflow="ellipsis"),
+    )
+    for node in sorted(snap.nodes, key=an.node_sort_key):
+        if only_free and not node.schedulable:
+            continue
+
+        cpu = Text()
+        cpu.append(meter(node.cpus_alloc, node.cpus_total, 6))
+        cpu.append(f" {node.cpus_alloc:>3}/{node.cpus_total:<4}", style=pal.ink_soft)
+
+        ram = Text()
+        ram.append(meter(node.mem_alloc_mb, node.mem_total_mb, 6))
+        ram.append(f" {gb(node.mem_alloc_mb):>5}/{gb(node.mem_total_mb):<6}", style=pal.ink_soft)
+
+        count = Text(f"{node.gpus_used}/{node.gpus_total}",
+                     style=f"bold {pal.good}" if node.schedulable else pal.ink_soft)
+
+        who = chips(node, occupants) if node.healthy else Text(
+            node.reason or node.base_state.lower(), style=pal.critical)
+
+        tbl.add_row(Text(node.name, style=pal.ink), gpu_slots(node, occupants), count,
+                  node.gpu_model, cpu, ram, status_cell(node), who)
+    return tbl
+
+
+def breakdown(snap: Snapshot, occupants) -> Table:
+    """Who is using the cluster, by GPU model, unix group and account."""
+    pal = _p()
+    tbl = _table(
+        dict(header=t('col.gpu_model'), no_wrap=True),
+        dict(header=t('col.usage'), no_wrap=True),
+        dict(header=t('col.unix_group'), no_wrap=True),
+        # rich wants distinct headers: the trailing space tells them apart
+        dict(header=t('col.usage') + " ", no_wrap=True),
+        dict(header=t('col.account'), no_wrap=True),
+        dict(header=t('col.usage') + "  ", no_wrap=True),
+    )
+    models = an.by_gpu_model(snap)
+    groups = an.gpus_by_group(snap)
+    accounts = an.gpus_by_account(snap)
+
+    def cell(label, used, total=None, color=None):
+        if label is None:
+            return Text("")
+        out = Text(f"{label}", style=color or pal.ink_soft)
+        return out
+
+    def usage(used, total=None):
+        out = Text()
+        if total:
+            out.append(meter(used, total, 6))
+            out.append(f" {used}/{total}", style=pal.ink_soft)
+        else:
+            out.append(f"{used}", style=f"bold {pal.ink}")
+            out.append(" GPU", style=pal.ink_muted)
+        return out
+
+    rows = max(len(models), len(groups), len(accounts))
+    for i in range(rows):
+        m = models[i] if i < len(models) else None
+        g = groups[i] if i < len(groups) else None
+        a = accounts[i] if i < len(accounts) else None
+        tbl.add_row(
+            cell(m[0] if m else None, 0),
+            usage(m[1], m[2]) if m else Text(""),
+            cell(g[0] if g else None, 0),
+            usage(g[1]) if g else Text(""),
+            cell(a[0] if a else None, 0),
+            usage(a[1]) if a else Text(""),
+        )
+    return tbl
+
+
+def specs_table(snap: Snapshot) -> Table:
+    """The fixed specs: what the node *is*, not what it's doing.
+
+    Keeping them apart from usage avoids a twenty-column table where you can't
+    find anything anymore.
+    """
+    pal = _p()
+    tbl = _table(
+        dict(header=t('col.node'), no_wrap=True),
+        dict(header=t('col.gpu'), no_wrap=True),
+        dict(header=t('col.cpu'), justify="right", no_wrap=True),
+        dict(header=t('col.topology'), no_wrap=True, style=pal.ink_muted),
+        dict(header=t('col.ram'), justify="right", no_wrap=True),
+        dict(header=t('col.disk'), justify="right", no_wrap=True),
+        dict(header=t('col.partitions'), no_wrap=True, overflow="ellipsis"),
+        dict(header=t('col.weight'), justify="right", no_wrap=True),
+        dict(header=t('col.uptime'), justify="right", no_wrap=True),
+    )
+    for node in sorted(snap.nodes, key=lambda n: (-n.gpus_total, n.name)):
+        topo = (f"{node.sockets}×{node.cores_per_socket}c×{node.threads_per_core}t"
+                if node.sockets else "-")
+        tbl.add_row(
+            Text(node.name, style=pal.ink),
+            Text(f"{node.gpus_total} × {node.gpu_model}", style=pal.ink_soft),
+            Text(str(node.cpus_total), style=pal.ink_soft),
+            topo,
+            Text(gb(node.mem_total_mb), style=pal.ink_soft),
+            Text(gb(node.tmp_disk_mb) if node.tmp_disk_mb else "-", style=pal.ink_soft),
+            Text(", ".join(node.partitions) or "-", style=pal.ink_muted),
+            Text(str(node.weight), style=pal.ink_muted),
+            Text(an.uptime(node) or "-", style=pal.ink_muted),
+        )
+    return tbl
+
+
+def legend(occupants) -> Text:
+    pal = _p()
+    out = Text(t('node.legend'), style=pal.ink_muted)
+    named = occupants.named()
+    if not named:
+        return Text(t('node.no_gpu_used'), style=pal.ink_muted)
+    for i, (user, color, shape) in enumerate(named):
+        if i:
+            out.append("   ")
+        out.append(shape + " ", style=color)
+        mine = user == occupants.me
+        out.append(user + (t('node.you') if mine else ""),
+                   style=f"bold {pal.ink}" if mine else pal.ink_soft)
+    if occupants.overflow:
+        out.append("   ")
+        out.append(BUSY + " ", style=pal.other)
+        out.append(t('node.others', n=len(occupants.overflow)), style=pal.ink_muted)
+    return out
+
+
+# --------------------------------------------------------------------------
+# "manual" screen
+# --------------------------------------------------------------------------
+
+def manual():
+    """The command cheat sheet: two lines each, description and example.
+
+    Columns don't wrap: this way an entry stays two lines even on a narrow
+    terminal, which is the whole point of the page.
+    """
+    pal = _p()
+    blocks = []
+    for i, (title, items) in enumerate(manual_data.sections()):
+        if i:
+            blocks.append(Text(""))
+        blocks.append(Text(title, style=f"bold {pal.fill(1.0)}"))
+        tbl = Table(box=None, show_header=False, expand=True, pad_edge=False,
+                  padding=(0, 1, 1, 0))
+        tbl.add_column(width=23, no_wrap=True)
+        tbl.add_column(ratio=1, no_wrap=True, overflow="ellipsis")
+        for command, what, example in items:
+            cell = Text(what, style=pal.ink)
+            cell.append("\n$ ", style=pal.ink_muted)
+            cell.append(example, style=pal.fill(0.7))
+            tbl.add_row(Text(command, style=f"bold {pal.ink}"), cell)
+        blocks.append(tbl)
+    return Group(*blocks)
+
+
+# --------------------------------------------------------------------------
+# "queue" screen
+# --------------------------------------------------------------------------
+
+def queue_table(snap: Snapshot, mine_only: bool = False, needle: str = "") -> Table:
+    pal = _p()
+    tbl = _table(
+        dict(header=t('col.id'), style=pal.ink_muted, no_wrap=True),
+        dict(header=t('col.user'), no_wrap=True),
+        dict(header=t('col.group'), no_wrap=True, style=pal.ink_muted),
+        dict(header=t('col.name'), ratio=3, no_wrap=True, overflow="ellipsis"),
+        dict(header=t('col.state'), justify="center", no_wrap=True),
+        dict(header=t('col.gpu'), justify="right", no_wrap=True),
+        dict(header=t('col.ram'), justify="right", no_wrap=True),
+        dict(header=t('col.time'), justify="right", no_wrap=True),
+        dict(header=t('col.where_why'), ratio=4, overflow="ellipsis"),
+    )
+    needle = needle.lower().strip()
+    jobs = sorted(snap.jobs, key=lambda j: (j.pending, -(j.priority or 0), j.jobid))
+    for job in jobs:
+        if mine_only and not job.mine:
+            continue
+        if needle and needle not in f"{job.user} {job.name} {job.jobid} {job.account or ''}".lower():
+            continue
+        if job.running:
+            state = Text(t('job.running_short'), style=f"bold {pal.good}")
+            where = Text(", ".join(sorted(set(job.nodes))) or "-", style=pal.ink_soft)
+        else:
+            state = Text(t('job.pending_short'), style=f"bold {pal.warning}")
+            label, _ = an.explain_reason(job.reason)
+            where = Text(label, style=pal.warning)
+        user = Text(job.user, style=f"bold {pal.ink}" if job.mine else pal.ink_soft)
+        tbl.add_row(job.jobid, user, job.group or "-", job.name, state, str(job.gpus),
+                  gb(job.mem_mb), job.runtime, where)
+    return tbl