@andespindola/crow-skills 0.10.0 → 0.10.1

package/crow_skills/resources.py

@@ -8,15 +8,23 @@ memory pressure without the CLI package. The CLI uses the same functions for
 
 What is read, and nothing else:
 - macOS: one ``sysctl`` call (hw.memsize, hw.ncpu, vm.swapusage,
-  kern.memorystatus_vm_pressure_level, kern.memorystatus_level); ``vm_stat``
-  only when the kernel does not report the available level.
-- Linux: /proc/meminfo (MemAvailable, swap), /proc/pressure/memory (PSI) when
-  present, and the cgroup v2 memory limit when the process runs under one.
-- Agent processes (full probe only): pid, parent pid, RSS and the executable
-  name, from ``ps -axo pid=,ppid=,rss=,comm=`` (macOS) or /proc/<pid>/stat
-  (Linux). Names are matched against a fixed list and only the agent kind,
-  counts and RSS are reported: no command line, argument or process name is
-  ever printed or stored.
+  kern.memorystatus_vm_pressure_level, kern.memorystatus_level,
+  vm.compressor_bytes_used); ``vm_stat`` only when the kernel does not report
+  the available level.
+- Linux: /proc/meminfo (MemAvailable, swap), /proc/pressure/memory and
+  /proc/pressure/cpu (PSI) when present, and the cgroup v2 memory and CPU limits
+  (with their pressure files) when the process runs under one.
+- Load average (``os.getloadavg``) on both.
+- Agent processes (full probe only): pid, parent pid, RSS, CPU% and the
+  executable name, from ``ps -axo pid=,ppid=,rss=,%cpu=,comm=`` (macOS) or
+  /proc/<pid>/stat (Linux). Names are matched against a fixed list and only the
+  agent kind, counts, RSS and CPU% are reported: no command line, argument or
+  process name is ever printed or stored.
+
+Three axes, each with its own level (normal, warn, critical): memory (available
+percent, OS level, PSI), swap (folded into the memory level) and CPU (load per
+CPU over 1 and 5 minutes, CPU PSI on Linux). Every recommendation is monotonic:
+more pressure on any axis never raises a number (tests walk a grid of inputs).
 
 Tests (and only tests) pin the reading with CROW_RESOURCES_FIXTURE, the path of a
 JSON raw reading (optionally with an "agents" object); the cache is then bypassed.
@@ -30,6 +38,8 @@ import math
 import os
 from pathlib import Path
 import re
+import shlex
+import shutil
 import subprocess
 import sys
 import time
@@ -62,7 +72,19 @@ DEFAULTS = {
     "criticalAvailablePercent": 7,  # available/total below this -> critical
     "psiWarnSomeAvg10": 10.0,      # Linux PSI "some avg10" (%) at or above this -> warn
     "psiCriticalFullAvg10": 10.0,  # Linux PSI "full avg10" (%) at or above this -> critical
-    "loadPerCpuReduce": 1.5,       # 1-min load / cpus above this halves heavy jobs and workers
+    # Swap (folded into the memory level). macOS grows its swap files on demand, so a high share
+    # of the swap total alone is routine (72% captured on a calm 18 GB machine); the warning also
+    # needs swap in use worth a quarter of the RAM. Critical: swap nearly full while available
+    # memory is also low, the state that ends in thrashing (macOS) or the OOM killer (Linux).
+    "swapWarnUsedPercent": 75,     # swap used/total at or above this...
+    "swapWarnRamPercent": 25,      # ...and swap used/RAM at or above this -> warn
+    "swapCriticalUsedPercent": 90,  # swap used/total at or above this...
+    "swapCriticalAvailablePercent": 25,  # ...and available/total below this -> critical
+    # CPU: load average per CPU (runnable threads per core; above 1 work queues).
+    "loadPerCpuReduce": 1.5,       # 1- or 5-min load / cpus above this -> cpu warn (halves agents, jobs, workers)
+    "loadPerCpuCritical": 3.0,     # 1-min load / cpus at or above this, sustained (5-min above warn) -> cpu critical
+    "psiCpuWarnSomeAvg10": 20.0,   # Linux CPU PSI "some avg10" (%) at or above this -> cpu warn
+    "psiCpuCriticalSomeAvg10": 50.0,  # ... at or above this -> cpu critical
     "cacheSeconds": 5,             # hooks and status lines reuse a probe this recent
 }
 LIMITS = {  # key -> (minimum, maximum)
@@ -71,7 +93,13 @@ LIMITS = {  # key -> (minimum, maximum)
     "warnAvailablePercent": (0, 100), "criticalAvailablePercent": (0, 100),
     "psiWarnSomeAvg10": (0, 100), "psiCriticalFullAvg10": (0, 100),
     "loadPerCpuReduce": (0.1, 1000), "cacheSeconds": (0, 300),
+    "swapWarnUsedPercent": (0, 100), "swapWarnRamPercent": (0, 1000), "swapCriticalUsedPercent": (0, 100),
+    "swapCriticalAvailablePercent": (0, 100), "loadPerCpuCritical": (0.1, 1000),
+    "psiCpuWarnSomeAvg10": (0, 100), "psiCpuCriticalSomeAvg10": (0, 100),
 }
+# (warn key, critical key, critical must be <= warn): an inverted pair falls back to both defaults.
+PAIRS = (("warnAvailablePercent", "criticalAvailablePercent", True), ("swapWarnUsedPercent", "swapCriticalUsedPercent", False),
+         ("loadPerCpuReduce", "loadPerCpuCritical", False), ("psiCpuWarnSomeAvg10", "psiCpuCriticalSomeAvg10", False))
 INTEGER_KEYS = ("reservedMb", "perAgentMb", "perHeavyJobMb", "perWorkerMb", "maxParallelAgents", "maxParallelHeavyJobs")
 MAX_CONFIG = 64 * 1024
 MB = 1024 * 1024
@@ -120,10 +148,10 @@ def load_config(home):
                         effective[key] = int(value) if key in INTEGER_KEYS else float(value)
     except (OSError, ValueError, UnicodeDecodeError):
         errors.append("resources.json ilegível ou JSON inválido; padrões usados.")
-    if effective["criticalAvailablePercent"] > effective["warnAvailablePercent"]:
-        errors.append("criticalAvailablePercent maior que warnAvailablePercent; os dois padrões foram restaurados.")
-        effective["criticalAvailablePercent"] = DEFAULTS["criticalAvailablePercent"]
-        effective["warnAvailablePercent"] = DEFAULTS["warnAvailablePercent"]
+    for warn_key, critical_key, below in PAIRS:
+        if (effective[critical_key] > effective[warn_key]) if below else (effective[critical_key] < effective[warn_key]):
+            errors.append(critical_key + (" maior que " if below else " menor que ") + warn_key + "; os dois padrões foram restaurados.")
+            effective[critical_key], effective[warn_key] = DEFAULTS[critical_key], DEFAULTS[warn_key]
     return effective, {"path": str(path), "loaded": loaded, "errors": errors}
 
 
@@ -190,6 +218,10 @@ def macos_reading(sysctl_text, vm_stat_text=None):
     reading["swapTotalMb"], reading["swapUsedMb"] = parse_swapusage(values.get("vm.swapusage", ""))
     # kern.memorystatus_vm_pressure_level: 1 normal, 2 warning, 4 critical (the level memory_pressure shows).
     reading["osLevel"] = {"1": "normal", "2": "warn", "4": "critical"}.get(values.get("kern.memorystatus_vm_pressure_level"))
+    try:
+        reading["compressedMb"] = int(values["vm.compressor_bytes_used"]) / MB  # memory held by the compressor (report only)
+    except (KeyError, ValueError):
+        pass
     try:
         reading["cpus"] = int(values["hw.ncpu"])
     except (KeyError, ValueError):
@@ -240,9 +272,10 @@ def parse_cpu_max(text):
     return max(1, -(-quota // period)) if quota > 0 and period > 0 else None
 
 
-def linux_reading(meminfo_text, psi_text=None, cgroup=None):
+def linux_reading(meminfo_text, psi_text=None, cgroup=None, cpu_psi_text=None):
     """cgroup: optional dict with the raw cgroup v2 files of the tightest limit:
-    max, current, stat (memory.stat), pressure (memory.pressure) and cpuMax (cpu.max)."""
+    max, current, stat (memory.stat), pressure (memory.pressure), cpuMax (cpu.max) and
+    cpuPressure (cpu.pressure of the level that sets cpu.max). cpu_psi_text: /proc/pressure/cpu."""
     info = parse_meminfo(meminfo_text)
     if "MemTotal" not in info:
         return None
@@ -273,30 +306,48 @@ def linux_reading(meminfo_text, psi_text=None, cgroup=None):
     cpus = parse_cpu_max(cgroup.get("cpuMax"))
     if cpus:
         reading["cpuQuota"] = cpus
+    cpu_psi = parse_psi(cgroup.get("cpuPressure") or cpu_psi_text) if (cgroup.get("cpuPressure") or cpu_psi_text) else None
+    if cpu_psi and "someAvg10" in cpu_psi:
+        reading["cpuPsi"] = {"someAvg10": cpu_psi["someAvg10"]}  # "full" is not meaningful for CPU system-wide
     return reading
 
 
-def parse_ps(text):
-    """``ps -axo pid=,ppid=,rss=,comm=`` -> [(pid, ppid, rss_kb, basename)]."""
+def _percent(text):
+    try:
+        value = float(text.replace(",", "."))
+    except ValueError:
+        return None
+    return value if math.isfinite(value) and value >= 0 else None
+
+
+def parse_ps(text, cpu=False):
+    """``ps -axo pid=,ppid=,rss=,comm=`` -> [(pid, ppid, rss_kb, basename, None)]; with cpu,
+    ``ps -axo pid=,ppid=,rss=,%cpu=,comm=`` -> [(pid, ppid, rss_kb, basename, cpu_percent)]."""
     rows = []
     for line in (text or "").splitlines():
-        parts = line.split(None, 3)
-        if len(parts) < 4 or not (parts[0].isdigit() and parts[1].isdigit() and parts[2].isdigit()):
+        parts = line.split(None, 4 if cpu else 3)
+        if len(parts) < (5 if cpu else 4) or not (parts[0].isdigit() and parts[1].isdigit() and parts[2].isdigit()):
+            continue
+        percent = _percent(parts[3]) if cpu else None
+        if cpu and percent is None:
             continue
-        rows.append((int(parts[0]), int(parts[1]), int(parts[2]), os.path.basename(parts[3].strip())))
+        rows.append((int(parts[0]), int(parts[1]), int(parts[2]), os.path.basename(parts[-1].strip()), percent))
     return rows
 
 
 def agent_trees(rows):
     """Agent CLI process trees: roots are agent processes with no agent ancestor; each tree's
-    RSS includes every descendant (node workers, MCP servers, shells). Only kinds, counts and
-    MB are returned."""
-    parent = {pid: ppid for pid, ppid, _, _ in rows}
-    rss = {pid: kb for pid, _, kb, _ in rows}
-    kind = {pid: AGENT_NAMES.get(name.lower()) for pid, _, _, name in rows}
+    RSS and CPU% include every descendant (node workers, MCP servers, shells). Only kinds,
+    counts, MB and CPU% are returned. Rows: (pid, ppid, rss_kb, name[, cpu_percent or None])."""
+    rows = [tuple(r) + (None,) * (5 - len(r)) for r in rows]
+    parent = {r[0]: r[1] for r in rows}
+    rss = {r[0]: r[2] for r in rows}
+    cpu = {r[0]: r[4] for r in rows}
+    has_cpu = any(r[4] is not None for r in rows)
+    kind = {r[0]: AGENT_NAMES.get(r[3].lower()) for r in rows}
     children = {}
-    for pid, ppid, _, _ in rows:
-        children.setdefault(ppid, []).append(pid)
+    for r in rows:
+        children.setdefault(r[1], []).append(r[0])
 
     def has_agent_ancestor(pid):
         seen, current = set(), parent.get(pid)
@@ -307,23 +358,31 @@ def agent_trees(rows):
             current = parent.get(current)
         return False
 
-    by_kind, total = {}, 0
-    for pid, _, _, _ in rows:
+    by_kind, total, total_cpu = {}, 0, 0.0
+    for r in rows:
+        pid = r[0]
         if not kind.get(pid) or has_agent_ancestor(pid):
             continue
-        stack, seen, tree_kb = [pid], set(), 0
+        stack, seen, tree_kb, tree_cpu = [pid], set(), 0, 0.0
         while stack:
             current = stack.pop()
             if current in seen:
                 continue
             seen.add(current)
             tree_kb += rss.get(current, 0)
+            tree_cpu += cpu.get(current) or 0.0
             stack.extend(children.get(current, []))
-        entry = by_kind.setdefault(kind[pid], {"count": 0, "rssMb": 0})
+        entry = by_kind.setdefault(kind[pid], dict({"count": 0, "rssMb": 0}, **({"cpuPercent": 0.0} if has_cpu else {})))
         entry["count"] += 1
         entry["rssMb"] += round(tree_kb / 1024)
+        if has_cpu:
+            entry["cpuPercent"] = round(entry["cpuPercent"] + tree_cpu, 1)
         total += tree_kb
-    return {"count": sum(e["count"] for e in by_kind.values()), "rssMb": round(total / 1024), "byKind": by_kind}
+        total_cpu += tree_cpu
+    result = {"count": sum(e["count"] for e in by_kind.values()), "rssMb": round(total / 1024), "byKind": by_kind}
+    if has_cpu:
+        result["cpuPercent"] = round(total_cpu, 1)  # % of one CPU, summed (ps convention): 250 = 2.5 CPUs busy
+    return result
 
 
 # --- readers (side effects: one subprocess or a few /proc reads) ----------------------------
@@ -368,6 +427,7 @@ def cgroup_files():
         cpus = parse_cpu_max(cpu_text)
         if cpus and (best_cpu is None or cpus < best_cpu):
             best_cpu, result["cpuMax"] = cpus, cpu_text
+            result["cpuPressure"] = _read(directory / "cpu.pressure", 512)
         if directory == root:
             break
     return result
@@ -378,11 +438,12 @@ def read_machine(platform=None):
     platform = platform or sys.platform
     reading = None
     if platform == "darwin":
-        text = _run(["sysctl", "hw.memsize", "hw.ncpu", "vm.swapusage", "kern.memorystatus_vm_pressure_level", "kern.memorystatus_level"])
+        text = _run(["sysctl", "hw.memsize", "hw.ncpu", "vm.swapusage", "kern.memorystatus_vm_pressure_level", "kern.memorystatus_level",
+                     "vm.compressor_bytes_used"])
         values = parse_sysctl(text)
         reading = macos_reading(text, _run(["vm_stat"]) if "kern.memorystatus_level" not in values else None)
     elif platform.startswith("linux"):
-        reading = linux_reading(_read("/proc/meminfo"), _read("/proc/pressure/memory"), cgroup_files())
+        reading = linux_reading(_read("/proc/meminfo"), _read("/proc/pressure/memory"), cgroup_files(), _read("/proc/pressure/cpu", 512))
     if reading is None:
         reading = {"platform": platform if platform in ("darwin",) or platform.startswith("linux") else "other",
                    "source": "unavailable", "totalMb": None, "availableMb": None, "swapTotalMb": None, "swapUsedMb": None,
@@ -393,7 +454,10 @@ def read_machine(platform=None):
         except (AttributeError, OSError):
             reading["cpus"] = os.cpu_count() or 1
     if reading.get("cpuQuota"):
-        reading["cpus"] = min(reading["cpus"], reading.pop("cpuQuota"))
+        quota = reading.pop("cpuQuota")
+        if quota < reading["cpus"]:
+            reading["loadCpus"] = os.cpu_count() or reading["cpus"]  # load average is host-wide
+            reading["cpus"] = quota
     try:
         reading["load"] = [round(x, 2) for x in os.getloadavg()]
     except (AttributeError, OSError):
@@ -407,7 +471,9 @@ def read_processes(platform=None):
         rows, page_kb = [], (os.sysconf("SC_PAGE_SIZE") // 1024 if hasattr(os, "sysconf") else 4)
         try:
             pids = [p for p in os.listdir("/proc") if p.isdigit()]
-        except OSError:
+            ticks = os.sysconf("SC_CLK_TCK")
+            uptime = float((_read("/proc/uptime", 128) or "").split()[0])
+        except (OSError, ValueError, IndexError, AttributeError):
             return None
         for pid in pids:
             stat = _read("/proc/" + pid + "/stat", 4096)
@@ -417,13 +483,18 @@ def read_processes(platform=None):
             name = stat[stat.find("(") + 1:stat.rfind(")")]
             fields = stat[stat.rfind(")") + 2:].split()
             try:
-                rows.append((int(pid), int(fields[1]), int(statm.split()[1]) * page_kb, name))
-            except (IndexError, ValueError):
+                # CPU%: time used over the process lifetime (what Linux ps reports as %cpu).
+                elapsed = uptime - int(fields[19]) / ticks
+                busy = (int(fields[11]) + int(fields[12])) / ticks
+                rows.append((int(pid), int(fields[1]), int(statm.split()[1]) * page_kb, name,
+                             round(100.0 * busy / elapsed, 1) if elapsed > 0 else 0.0))
+            except (IndexError, ValueError, ZeroDivisionError):
                 continue
         return agent_trees(rows)
     if platform == "darwin" or "bsd" in platform:
-        text = _run(["ps", "-axo", "pid=,ppid=,rss=,comm="], timeout=3.0)
-        return agent_trees(parse_ps(text)) if text else None
+        # %cpu: macOS ps reports a decaying average over roughly the last minute.
+        text = _run(["ps", "-axo", "pid=,ppid=,rss=,%cpu=,comm="], timeout=3.0)
+        return agent_trees(parse_ps(text, cpu=True)) if text else None
     return None
 
 
@@ -435,12 +506,31 @@ def worst(*levels):
     return max(known, key=order.get) if known else None
 
 
+def swap_level(reading, cfg, available_percent):
+    """Swap axis: {'level', 'usedPercent', 'ramPercent'}, or None without swap."""
+    total, used, ram = reading.get("swapTotalMb"), reading.get("swapUsedMb"), reading.get("totalMb")
+    if not total or used is None or not ram:
+        return None
+    used_percent, ram_percent = 100.0 * used / total, 100.0 * used / ram
+    # Critical also needs swap worth swapWarnRamPercent of the RAM: a small swap full on a machine
+    # with plenty of RAM (common on Linux servers) is not the thrashing state.
+    if used_percent >= cfg["swapCriticalUsedPercent"] and ram_percent >= cfg["swapWarnRamPercent"] \
+            and available_percent is not None and available_percent < cfg["swapCriticalAvailablePercent"]:
+        level = "critical"
+    elif used_percent >= cfg["swapWarnUsedPercent"] and ram_percent >= cfg["swapWarnRamPercent"]:
+        level = "warn"
+    else:
+        level = "normal"
+    return {"level": level, "usedPercent": round(used_percent, 1), "ramPercent": round(ram_percent, 1)}
+
+
 def assess(reading, cfg):
-    """Pressure level for a raw reading: the worst of the OS level, PSI and available percent."""
+    """Memory pressure for a raw reading: the worst of the OS level, PSI, available percent and
+    swap. ``ram`` is the same without swap (the status line shows swap on its own)."""
     total, available = reading.get("totalMb"), reading.get("availableMb")
     reasons = []
     if not total or available is None:
-        return {"level": "unknown", "os": reading.get("osLevel"), "psi": reading.get("psi"),
+        return {"level": "unknown", "ram": "unknown", "os": reading.get("osLevel"), "psi": reading.get("psi"), "swap": None,
                 "reasons": ["memória não medida nesta plataforma; recomendação conservadora"]}
     percent = 100.0 * available / total
     by_percent = "critical" if percent < cfg["criticalAvailablePercent"] else "warn" if percent < cfg["warnAvailablePercent"] else "normal"
@@ -460,65 +550,136 @@ def assess(reading, cfg):
             psi_level = "normal"
     if reading.get("osLevel") in ("warn", "critical"):
         reasons.append("pressão do sistema " + reading["osLevel"])
-    return {"level": worst(by_percent, psi_level, reading.get("osLevel")), "os": reading.get("osLevel"), "psi": psi,
-            "availablePercent": round(percent, 1), "reasons": reasons}
-
-
-def recommend(reading, pressure, cfg):
-    """maxParallelAgents, maxParallelHeavyJobs, maxWorkersPerJob and mode for this reading."""
+    ram = worst(by_percent, psi_level, reading.get("osLevel"))
+    swap = swap_level(reading, cfg, percent)
+    if swap and swap["level"] != "normal":
+        reasons.append("swap " + str(round(swap["usedPercent"])) + "% em uso (" + str(round(swap["ramPercent"])) + "% da RAM)")
+    return {"level": worst(ram, swap["level"] if swap else None), "ram": ram, "os": reading.get("osLevel"), "psi": psi,
+            "swap": swap, "availablePercent": round(percent, 1), "reasons": reasons}
+
+
+def assess_cpu(reading, cfg):
+    """CPU pressure: load average per CPU (1 and 5 min) and, on Linux, CPU PSI."""
+    # The load average counts the whole host: inside a container with a CPU quota it is divided
+    # by the host CPUs (loadCpus); the quota's own contention shows in the cgroup cpu.pressure.
+    cpus = max(1, int(reading.get("loadCpus") or reading.get("cpus") or 1))
+    load, psi = reading.get("load"), reading.get("cpuPsi")
+    per1 = per5 = None
+    level, reasons = "normal", []
+    if load:
+        per1, per5 = load[0] / cpus, load[1] / cpus
+        if per1 >= cfg["loadPerCpuCritical"] and per5 > cfg["loadPerCpuReduce"]:
+            level = "critical"
+        elif per1 > cfg["loadPerCpuReduce"] or per5 > cfg["loadPerCpuReduce"]:
+            level = "warn"
+        if level != "normal":
+            reasons.append("carga " + str(load[0]) + "/" + str(load[1]) + " em " + str(cpus) + " CPUs (" + ("%.1f" % per1) + "×/" +
+                           ("%.1f" % per5) + "× por CPU em 1/5 min)")
+    if psi and psi.get("someAvg10") is not None:
+        by_psi = "critical" if psi["someAvg10"] >= cfg["psiCpuCriticalSomeAvg10"] else \
+            "warn" if psi["someAvg10"] >= cfg["psiCpuWarnSomeAvg10"] else "normal"
+        if by_psi != "normal":
+            reasons.append("PSI cpu some avg10 " + str(psi["someAvg10"]))
+        level = worst(level, by_psi)
+    if not load and not psi:
+        return {"level": "unknown", "loadPerCpu1": None, "loadPerCpu5": None, "psi": None, "reasons": []}
+    return {"level": level, "loadPerCpu1": round(per1, 2) if per1 is not None else None,
+            "loadPerCpu5": round(per5, 2) if per5 is not None else None, "psi": psi, "reasons": reasons}
+
+
+def recommend(reading, pressure, cfg, cpu_pressure=None):
+    """maxParallelAgents, maxParallelHeavyJobs, maxWorkersPerJob and mode for this reading.
+
+    Monotonic by construction: every number starts from a base that does not depend on load,
+    and pressure only divides it (warn on memory/swap or CPU halves once; memory critical: 1 agent,
+    no new heavy job; CPU critical: 1 agent, 1 job, 1 worker)."""
     cpus = max(1, int(reading.get("cpus") or 1))
     level = pressure["level"]
+    cpu_level = (cpu_pressure or assess_cpu(reading, cfg))["level"]
     reasons = []
-    if level == "unknown":
-        agents, heavy = min(2, cfg["maxParallelAgents"]), 1
-        workers = max(1, cpus // 2)
-        return {"mode": "reduced" if agents > 1 else "sequential", "maxParallelAgents": agents, "maxParallelHeavyJobs": heavy,
-                "maxWorkersPerJob": workers, "budgetMb": None, "reasons": ["sem medição: assuma reduced"]}
-    reserve = min(cfg["reservedMb"], reading["totalMb"] * cfg["reservedPercent"] / 100.0)
-    budget = max(0.0, reading["availableMb"] - reserve)
+    # Reference job count: the CPU-shaped cap, independent of memory and load. Workers per job
+    # come from it, so fewer jobs under pressure never mean more workers each.
+    ref = max(1, min(cpus // 4, cfg["maxParallelHeavyJobs"]))
     if level == "critical":
+        budget = max(0.0, reading["availableMb"] - min(cfg["reservedMb"], reading["totalMb"] * cfg["reservedPercent"] / 100.0))
         return {"mode": "sequential", "maxParallelAgents": 1, "maxParallelHeavyJobs": 0, "maxWorkersPerJob": 1,
                 "budgetMb": round(budget), "reasons": ["pressão crítica: sequencial, sem novos jobs pesados"] + pressure["reasons"]}
-    memory_agents = int(budget // cfg["perAgentMb"])
-    agents = max(1, min(memory_agents, cfg["maxParallelAgents"]))
-    memory_heavy = int(budget // cfg["perHeavyJobMb"])
-    heavy = max(1, min(memory_heavy, max(1, cpus // 4), cfg["maxParallelHeavyJobs"]))
-    if memory_agents < cfg["maxParallelAgents"]:
-        reasons.append("memória: " + str(round(budget)) + " MB livres além da reserva, " + str(cfg["perAgentMb"]) + " MB por agente")
-    if memory_heavy < 1:
-        reasons.append("memória abaixo de um job pesado (" + str(cfg["perHeavyJobMb"]) + " MB): no máximo um, sem nada pesado em paralelo")
-    if level == "warn":
-        agents, heavy = max(1, agents // 2), max(1, heavy // 2)
-        reasons += ["pressão warn: paralelismo pela metade"] + pressure["reasons"]
-    load = reading.get("load")
-    load_high = bool(load) and load[0] / cpus > cfg["loadPerCpuReduce"]
-    if load_high:
-        heavy = max(1, heavy // 2)
-        reasons.append("carga " + str(load[0]) + " em " + str(cpus) + " CPUs")
-    workers = min(max(1, cpus // heavy), max(1, int((budget / heavy) // cfg["perWorkerMb"])))
-    if level == "warn" or load_high:
-        workers = max(1, workers // 2)
+    if level == "unknown":
+        # Never above what a measured calm machine gets (cpus // ref), halved: unknown is conservative.
+        agents, heavy, workers, budget = min(2, cfg["maxParallelAgents"]), 1, max(1, (cpus // ref) // 2), None
+        reasons.append("sem medição: assuma reduced")
+    else:
+        reserve = min(cfg["reservedMb"], reading["totalMb"] * cfg["reservedPercent"] / 100.0)
+        budget = max(0.0, reading["availableMb"] - reserve)
+        memory_agents = int(budget // cfg["perAgentMb"])
+        agents = max(1, min(memory_agents, cfg["maxParallelAgents"]))
+        memory_heavy = int(budget // cfg["perHeavyJobMb"])
+        heavy = max(1, min(memory_heavy, ref))
+        workers = max(1, min(cpus // ref, int((budget / ref) // cfg["perWorkerMb"])))
+        if memory_agents < cfg["maxParallelAgents"]:
+            reasons.append("memória: " + str(round(budget)) + " MB livres além da reserva, " + str(cfg["perAgentMb"]) + " MB por agente")
+        if memory_heavy < 1:
+            reasons.append("memória abaixo de um job pesado (" + str(cfg["perHeavyJobMb"]) + " MB): no máximo um, sem nada pesado em paralelo")
+        if level == "warn":
+            reasons += ["pressão de memória warn: paralelismo pela metade"] + pressure["reasons"]
+    cpu_reasons = (cpu_pressure or {}).get("reasons") or []
+    if cpu_level == "warn":
+        reasons += ["pressão de CPU warn: agentes, jobs e workers pela metade"] + cpu_reasons
+    if level == "warn" or cpu_level == "warn":  # once, whichever axes are in warn
+        agents, heavy, workers = max(1, agents // 2), max(1, heavy // 2), max(1, workers // 2)
+    if cpu_level == "critical":
+        agents, heavy, workers = 1, 1, 1
+        reasons += ["pressão de CPU crítica: um agente, um job pesado e um worker por vez"] + cpu_reasons
     # Sizing by free memory at normal pressure is already in the numbers; "reduced" means the
-    # machine is struggling (pressure or load), "sequential" that there is room for one agent only.
-    mode = "sequential" if agents <= 1 else "reduced" if level == "warn" or load_high else "parallel"
+    # machine is struggling (memory, swap or CPU), "sequential" that there is room for one agent only.
+    struggling = level in ("warn", "unknown") or cpu_level in ("warn", "critical")
+    mode = "sequential" if agents <= 1 else "reduced" if struggling else "parallel"
     return {"mode": mode, "maxParallelAgents": agents, "maxParallelHeavyJobs": heavy, "maxWorkersPerJob": workers,
-            "budgetMb": round(budget), "reasons": reasons}
+            "budgetMb": round(budget) if budget is not None else None, "reasons": reasons}
+
+
+def low_priority(platform=None, which=None):
+    """The command prefix that runs a heavy job at low priority on this OS: (argv, text).
+
+    macOS: QoS clamp "utility" (taskpolicy -c utility) plus nice 10; ``taskpolicy -b`` is the
+    stronger option for jobs that can wait (efficiency cores and throttled I/O on Apple silicon).
+    Linux: nice 10 plus the lowest best-effort I/O class (ionice -c 2 -n 7) when ionice exists.
+    Windows: ``start "" /low /b /wait`` inside cmd. It changes only the job it prefixes, never a
+    host limit, and is empty when no known tool exists."""
+    platform = platform or sys.platform
+    which = which or shutil.which
+    if platform.startswith("win"):
+        argv = ["cmd", "/c", "start", '""', "/low", "/b", "/wait"]
+        return argv, 'cmd /c start "" /low /b /wait'
+    argv = []
+    if platform == "darwin" and which("taskpolicy"):
+        argv += ["taskpolicy", "-c", "utility"]
+    if which("nice"):
+        argv += ["nice", "-n", "10"]
+    if platform.startswith("linux") and which("ionice"):
+        argv += ["ionice", "-c", "2", "-n", "7"]
+    return argv, shlex.join(argv)
 
 
 def build(reading, cfg, meta, agents=None, cached=False, age=0):
     pressure = assess(reading, cfg)
+    cpu_pressure = assess_cpu(reading, cfg)
     total, available = reading.get("totalMb"), reading.get("availableMb")
     memory = {"totalMb": round(total) if total else None, "availableMb": round(available) if available is not None else None,
               "usedPercent": round(100.0 * (1 - available / total), 1) if total and available is not None else None,
               "swapTotalMb": round(reading["swapTotalMb"]) if reading.get("swapTotalMb") is not None else None,
               "swapUsedMb": round(reading["swapUsedMb"]) if reading.get("swapUsedMb") is not None else None,
               "cgroupLimitMb": round(reading["cgroupLimitMb"]) if reading.get("cgroupLimitMb") else None}
+    if reading.get("compressedMb") is not None:
+        memory["compressedMb"] = round(reading["compressedMb"])
     load = reading.get("load")
+    argv, prefix = low_priority(reading.get("platform") if reading.get("platform") in ("darwin", "linux") else None)
     return {"schema": SCHEMA, "generatedAt": now_iso(), "platform": reading.get("platform"), "source": reading.get("source"),
             "cached": cached, "ageSeconds": int(age), "memory": memory, "pressure": pressure,
-            "cpu": {"count": reading.get("cpus"), "load1": load[0] if load else None, "load5": load[1] if load else None,
-                    "load15": load[2] if load else None},
-            "agents": agents, "recommendation": recommend(reading, pressure, cfg), "thresholds": cfg, "config": meta}
+            "cpu": dict({"count": reading.get("cpus"), "load1": load[0] if load else None, "load5": load[1] if load else None,
+                         "load15": load[2] if load else None}, **cpu_pressure),
+            "agents": agents, "recommendation": recommend(reading, pressure, cfg, cpu_pressure),
+            "lowPriorityPrefix": prefix, "lowPriorityArgv": argv, "thresholds": cfg, "config": meta}
 
 
 # --- cache ----------------------------------------------------------------------------------
@@ -556,12 +717,14 @@ def valid_reading(reading):
         return False  # availableMb may be unmeasured (None) while totalMb is known: assess() reports unknown
     if not number(reading.get("cpus"), allow_none=False) or reading.get("osLevel") not in (None, "normal", "warn", "critical"):
         return False
-    load, psi = reading.get("load"), reading.get("psi")
+    load = reading.get("load")
     if load is not None and not (isinstance(load, list) and len(load) == 3 and all(number(x, False) for x in load)):
         return False
-    if psi is not None and not (isinstance(psi, dict) and all(number(v, False) for v in psi.values())):
-        return False
-    return True
+    for key in ("psi", "cpuPsi"):
+        psi = reading.get(key)
+        if psi is not None and not (isinstance(psi, dict) and all(number(v, False) for v in psi.values())):
+            return False
+    return number(reading.get("compressedMb")) and number(reading.get("loadCpus"))
 
 
 def write_cache(home, reading):
@@ -633,76 +796,137 @@ def probe(home, processes=True, use_cache=False, platform=None):
 
 # --- presentation ---------------------------------------------------------------------------
 
+def cpu_level(data):
+    return (data.get("cpu") or {}).get("level") or "normal"
+
+
 def alert(data):
-    """True when the machine needs attention: pressure warn/critical or a non-parallel recommendation."""
-    return data["pressure"]["level"] in ("warn", "critical") or data["recommendation"]["mode"] != "parallel"
+    """True when the machine needs attention: memory, swap or CPU pressure warn/critical, or a
+    non-parallel recommendation."""
+    return data["pressure"]["level"] in ("warn", "critical") or cpu_level(data) in ("warn", "critical") \
+        or data["recommendation"]["mode"] != "parallel"
 
 
 def gb(mb):
     return "?" if mb is None else ("%.1f" % (mb / 1024)).replace(".", ",")
 
 
+def times_cpu(value):
+    return ("%.1f" % value).replace(".", ",") + "×"
+
+
+# Under pressure the hint also carries the conduct rules (crow-behaviour references/resources.md),
+# so a session without the skill loaded still reduces load the same way.
+CONDUCT = (" Reduza a concorrência já, inclusive a planejada; um job pesado por vez, sem iniciar outro enquanto um roda "
+           "(deixe terminar o que está perto do fim), em prioridade baixa ({prefix}); não repita suíte/build já verificado "
+           "nesta revisão; validação ampla no CI do repositório quando houver, lendo o resultado antes de declarar verificado.")
+
+
 def hint(data):
     """One line for a prompt hook's additionalContext, or None when there is nothing to say."""
     if not alert(data):
         return None
-    rec, memory = data["recommendation"], data["memory"]
-    level = data["pressure"]["level"]
+    rec, memory, pressure = data["recommendation"], data["memory"], data["pressure"]
+    level = pressure["level"]
     if level == "unknown":
         head = "[crow-skills] memória: não medida nesta plataforma."
     else:
         head = ("[crow-skills] memória: pressão " + level + ", " + gb(memory["availableMb"]) + " GB livres de " +
-                gb(memory["totalMb"]) + " GB.")
+                gb(memory["totalMb"]) + " GB")
+        swap = pressure.get("swap")
+        if swap and swap["level"] != "normal":
+            head += "; swap " + str(int(round(swap["usedPercent"]))) + "% em uso (" + swap["level"] + ")"
+        head += "."
+    cpu = data.get("cpu") or {}
+    if cpu_level(data) in ("warn", "critical"):
+        head += " CPU: pressão " + cpu["level"] + (", carga " + times_cpu(cpu["loadPerCpu1"]) + " por CPU"
+                                                   if cpu.get("loadPerCpu1") is not None else "") + "."
     if rec["mode"] == "sequential" and rec["maxParallelHeavyJobs"] == 0:
         body = " Recomendação sequential: um agente por vez, não inicie builds/testes/dev servers novos e encerre os que esta sessão abriu e não usa."
     else:
         body = (" Recomendação " + rec["mode"] + ": até " + str(rec["maxParallelAgents"]) + " agente(s) e " +
                 str(rec["maxParallelHeavyJobs"]) + " job(s) pesado(s) em paralelo, " + str(rec["maxWorkersPerJob"]) + " worker(s) por job.")
-    return head + body + " Detalhe: crow-skills resources --json."
+    prefix = data.get("lowPriorityPrefix")
+    conduct = CONDUCT.format(prefix=("`" + prefix + "`") if prefix else "crow-skills resources --exec-prefix")
+    return head + body + conduct + " Detalhe: crow-skills resources --json."
 
 
 def segment(data, unicode=True):
-    """Compact status line/tmux segment, empty when the machine is fine (e.g. 'mem ▲ 85% ×2')."""
+    """Compact status line/tmux segment, empty when the machine is fine (e.g. 'mem ▲ 85% ×2',
+    'cpu ▲ 1.9× swap ▲ 92% ×3'): one part per axis under pressure, then the agents."""
     if not alert(data):
         return ""
-    used = data["memory"]["usedPercent"]
-    level = data["pressure"]["level"]
-    # The arrow is for real pressure only; "sequential" at normal pressure shows just the numbers.
-    arrow = {"warn": "▲" if unicode else "^", "critical": "▲▲" if unicode else "^^"}.get(level)
+    pressure = data["pressure"]
+    arrows = {"warn": "▲" if unicode else "^", "critical": "▲▲" if unicode else "^^"}
     times = "×" if unicode else "x"
-    text = "mem " + (arrow + " " if arrow else "") + (str(int(round(used))) + "%" if used is not None else "?")
-    return text + " " + times + str(data["recommendation"]["maxParallelAgents"])
+    parts = []
+    swap = pressure.get("swap") or {}
+    cpu = data.get("cpu") or {}
+    swap_on = swap.get("level") in arrows
+    cpu_on = cpu_level(data) in arrows
+    ram = pressure.get("ram", pressure["level"])
+    # Memory shows when it is the axis under pressure, or when nothing else explains the alert
+    # ("sequential" at normal pressure shows just the numbers, without an arrow).
+    if ram in arrows or not (swap_on or cpu_on):
+        used = data["memory"]["usedPercent"]
+        parts.append("mem " + (arrows[ram] + " " if ram in arrows else "") + (str(int(round(used))) + "%" if used is not None else "?"))
+    if cpu_on:
+        parts.append("cpu " + arrows[cpu["level"]] + (" " + ("%.1f" % cpu["loadPerCpu1"]) + times if cpu.get("loadPerCpu1") is not None else ""))
+    if swap_on:
+        parts.append("swap " + arrows[swap["level"]] + " " + str(int(round(swap["usedPercent"]))) + "%")
+    return " ".join(parts) + " " + times + str(data["recommendation"]["maxParallelAgents"])
 
 
 def render(data):
     memory, pressure, rec, cpu = data["memory"], data["pressure"], data["recommendation"], data["cpu"]
+    swap = pressure.get("swap")
     lines = ["memória: " + gb(memory["availableMb"]) + " GB livres de " + gb(memory["totalMb"]) + " GB" +
              (" (" + str(int(round(memory["usedPercent"]))) + "% em uso)" if memory["usedPercent"] is not None else "") +
-             (" · swap " + gb(memory["swapUsedMb"]) + "/" + gb(memory["swapTotalMb"]) + " GB" if memory["swapTotalMb"] else "") +
+             (" · swap " + gb(memory["swapUsedMb"]) + "/" + gb(memory["swapTotalMb"]) + " GB" +
+              (" (" + str(int(round(swap["usedPercent"]))) + "%)" if swap else "") if memory["swapTotalMb"] else "") +
+             (" · comprimida " + gb(memory["compressedMb"]) + " GB" if memory.get("compressedMb") else "") +
              (" · limite cgroup " + gb(memory["cgroupLimitMb"]) + " GB" if memory["cgroupLimitMb"] else ""),
              "pressão: " + pressure["level"] + (" (" + "; ".join(pressure["reasons"]) + ")" if pressure["reasons"] else ""),
              "cpu: " + str(cpu["count"]) + (" · carga " + str(cpu["load1"]) + " " + str(cpu["load5"]) + " " + str(cpu["load15"])
-                                            if cpu["load1"] is not None else "")]
+                                            if cpu["load1"] is not None else "") +
+             (" (" + times_cpu(cpu["loadPerCpu1"]) + " por CPU)" if cpu.get("loadPerCpu1") is not None else "") +
+             (" · PSI some " + str(cpu["psi"]["someAvg10"]) if cpu.get("psi") else "") +
+             " · pressão " + cpu_level(data)]
     agents = data.get("agents")
     if agents is not None:
-        kinds = ", ".join(k + " " + str(v["count"]) + " (" + gb(v["rssMb"]) + " GB)" for k, v in sorted(agents["byKind"].items()))
-        lines.append("agentes: " + str(agents["count"]) + " CLI(s), " + gb(agents["rssMb"]) + " GB RSS" + (" · " + kinds if kinds else ""))
+        def cpu_text(entry):
+            return (", " + ("%.0f" % entry["cpuPercent"]) + "% CPU") if entry.get("cpuPercent") is not None else ""
+        kinds = ", ".join(k + " " + str(v["count"]) + " (" + gb(v["rssMb"]) + " GB" + cpu_text(v) + ")" for k, v in sorted(agents["byKind"].items()))
+        lines.append("agentes: " + str(agents["count"]) + " CLI(s), " + gb(agents["rssMb"]) + " GB RSS" + cpu_text(agents) +
+                     (" · " + kinds if kinds else ""))
     lines.append("recomendação: " + rec["mode"] + " · até " + str(rec["maxParallelAgents"]) + " agente(s), " +
                  str(rec["maxParallelHeavyJobs"]) + " job(s) pesado(s), " + str(rec["maxWorkersPerJob"]) + " worker(s) por job")
     for reason in rec["reasons"]:
         lines.append("  - " + reason)
+    if data.get("lowPriorityPrefix"):
+        lines.append("prioridade baixa: " + data["lowPriorityPrefix"] + " <comando>")
     for error in data["config"]["errors"]:
         lines.append("config: " + error)
     return "\n".join(lines)
 
 
+def exec_prefix_data(platform=None):
+    argv, prefix = low_priority(platform)
+    return {"platform": platform or sys.platform, "lowPriorityPrefix": prefix, "lowPriorityArgv": argv, "text": prefix}
+
+
 def main(argv=None):
     import argparse
     p = argparse.ArgumentParser(prog="crow_resources", description="Memória, pressão e paralelismo recomendado.")
     p.add_argument("--home")
     p.add_argument("--json", action="store_true")
     p.add_argument("--no-processes", action="store_true")
+    p.add_argument("--exec-prefix", action="store_true")
     args = p.parse_args(argv)
+    if args.exec_prefix:
+        data = exec_prefix_data()
+        print(json.dumps(data, ensure_ascii=False) if args.json else data["text"])
+        return 0
     home = Path(args.home).expanduser() if args.home else Path.home()
     data = probe(home, processes=not args.no_processes)
     print(json.dumps(data, ensure_ascii=False) if args.json else render(data))