@andespindola/crow-skills 0.8.0 → 0.9.0

package/crow_skills/resources.py

@@ -0,0 +1,713 @@
+"""Machine resource probe and parallelism recommendation (crow-resources/1).
+
+Self-contained on purpose (standard library only, no package-relative
+imports): the integrations copy this file next to the hook as
+``crow_resources.py``, so the per-prompt hook and the status line can read
+memory pressure without the CLI package. The CLI uses the same functions for
+``crow-skills resources`` and the ``resources`` field of ``events snapshot``.
+
+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.
+
+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.
+
+The probe never changes a host limit. Thresholds come from DEFAULTS, merged
+with ~/.config/crow-skills/resources.json when it exists.
+"""
+from datetime import datetime, timezone
+import json
+import math
+import os
+from pathlib import Path
+import re
+import subprocess
+import sys
+import time
+import uuid
+
+SCHEMA = "crow-resources/1"
+CACHE_SCHEMA = "crow-resources-cache/1"
+LEVELS = ("normal", "warn", "critical")
+MODES = ("parallel", "reduced", "sequential")
+# Executable name (basename, lower case) -> agent kind. Node-based CLIs that keep the
+# process name "node" are not detected: their command line is never read.
+AGENT_NAMES = {"claude": "claude", "codex": "codex", "gemini": "gemini", "agy": "agy", "antigravity": "agy", "devin": "devin"}
+
+# Defaults derived from measurements on a 18 GB / 12-core macOS machine (docs/cli.md,
+# "crow-skills resources"): a Claude Code session with its MCP servers and shells used
+# ~0.95 GB RSS as a process tree; a standalone Codex CLI 60-70 MB; the Codex desktop
+# app-server tree ~2.1 GB. perAgentMb takes the heaviest common CLI session, since a
+# fan-out cannot know which kind of worker the host starts. perHeavyJobMb and
+# perWorkerMb are conservative estimates for a build/test suite/dev server and for one
+# test or compiler worker; they were not measured on this machine.
+DEFAULTS = {
+    "reservedMb": 2048,            # kept free for the OS, the editor and the browser...
+    "reservedPercent": 15,         # ...but never more than this share of the total (small machines)
+    "perAgentMb": 1024,            # one more agent/subagent session
+    "perHeavyJobMb": 1536,         # one build, test suite, dev server, emulator or container
+    "perWorkerMb": 512,            # one worker inside a heavy job (-j, --maxWorkers, pytest -n)
+    "maxParallelAgents": 6,        # hard cap, whatever the memory
+    "maxParallelHeavyJobs": 4,     # hard cap; also limited to cpus // 4
+    "warnAvailablePercent": 15,    # available/total below this -> warn
+    "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
+    "cacheSeconds": 5,             # hooks and status lines reuse a probe this recent
+}
+LIMITS = {  # key -> (minimum, maximum)
+    "reservedMb": (0, 1 << 22), "reservedPercent": (0, 90), "perAgentMb": (1, 1 << 22), "perHeavyJobMb": (1, 1 << 22), "perWorkerMb": (1, 1 << 22),
+    "maxParallelAgents": (1, 256), "maxParallelHeavyJobs": (1, 256),
+    "warnAvailablePercent": (0, 100), "criticalAvailablePercent": (0, 100),
+    "psiWarnSomeAvg10": (0, 100), "psiCriticalFullAvg10": (0, 100),
+    "loadPerCpuReduce": (0.1, 1000), "cacheSeconds": (0, 300),
+}
+INTEGER_KEYS = ("reservedMb", "perAgentMb", "perHeavyJobMb", "perWorkerMb", "maxParallelAgents", "maxParallelHeavyJobs")
+MAX_CONFIG = 64 * 1024
+MB = 1024 * 1024
+
+
+def config_path(home):
+    return Path(home) / ".config" / "crow-skills" / "resources.json"
+
+
+def cache_path(home):
+    return Path(home) / ".local" / "state" / "crow-skills" / "resources-cache.json"
+
+
+def now_iso():
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+# --- configuration -----------------------------------------------------------------------
+
+def load_config(home):
+    """Effective thresholds and the problems found in the user's file (never raises)."""
+    path = config_path(home)
+    effective, errors, loaded = dict(DEFAULTS), [], False
+    try:
+        if path.is_symlink() or (path.exists() and not path.is_file()):
+            errors.append("resources.json não é um arquivo regular; padrões usados.")
+        elif path.is_file():
+            if path.stat().st_size > MAX_CONFIG:
+                errors.append("resources.json maior que 64 KiB; padrões usados.")
+            else:
+                data = json.loads(path.read_text(encoding="utf-8"))
+                if not isinstance(data, dict):
+                    errors.append("resources.json não é um objeto JSON; padrões usados.")
+                else:
+                    loaded = True
+                    for key, value in data.items():
+                        if key in ("$schema", "schema", "comment"):
+                            continue
+                        if key not in DEFAULTS:
+                            errors.append("chave desconhecida ignorada: " + str(key)[:40])
+                            continue
+                        low, high = LIMITS[key]
+                        if isinstance(value, bool) or not isinstance(value, (int, float)) or not low <= value <= high:
+                            errors.append(key + " inválido (esperado número entre " + str(low) + " e " + str(high) + "); padrão mantido.")
+                            continue
+                        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"]
+    return effective, {"path": str(path), "loaded": loaded, "errors": errors}
+
+
+# --- parsing (pure, covered by fixtures) ------------------------------------------------
+
+def _size_mb(text):
+    """'4464.19M' / '6.00G' / '512K' -> MB (float)."""
+    match = re.fullmatch(r"\s*([0-9.]+)\s*([KMGT]?)B?\s*", text or "", re.IGNORECASE)
+    if not match:
+        return None
+    value = float(match.group(1))
+    return value * {"": 1 / MB, "K": 1 / 1024, "M": 1, "G": 1024, "T": 1024 * 1024}[match.group(2).upper()]
+
+
+def parse_sysctl(text):
+    """``sysctl name ...`` output (``name: value`` lines) -> dict of raw strings."""
+    values = {}
+    for line in (text or "").splitlines():
+        name, sep, value = line.partition(":")
+        if sep and re.fullmatch(r"[a-z0-9_.]+", name.strip()):
+            values[name.strip()] = value.strip()
+    return values
+
+
+def parse_swapusage(text):
+    """'total = 6144.00M  used = 4464.19M  free = 1679.81M  (encrypted)' -> (total, used) MB."""
+    found = dict(re.findall(r"(total|used|free)\s*=\s*([0-9.]+[KMGT]?)", text or ""))
+    total, used = _size_mb(found.get("total")), _size_mb(found.get("used"))
+    return total, used
+
+
+def parse_vm_stat(text):
+    """vm_stat output -> available MB (free + inactive + speculative + purgeable), or None."""
+    page = re.search(r"page size of (\d+) bytes", text or "")
+    if not page:
+        return None
+    counts = {}
+    for name, value in re.findall(r"^Pages ([a-z ]+):\s+(\d+)\.", text, re.MULTILINE):
+        counts[name.strip()] = int(value)
+    if "free" not in counts:
+        return None
+    pages = sum(counts.get(k, 0) for k in ("free", "inactive", "speculative", "purgeable"))
+    return pages * int(page.group(1)) / MB
+
+
+def macos_reading(sysctl_text, vm_stat_text=None):
+    """Raw macOS reading from sysctl (and vm_stat when the kernel level is missing)."""
+    values = parse_sysctl(sysctl_text)
+    try:
+        total = int(values["hw.memsize"]) / MB
+    except (KeyError, ValueError):
+        return None
+    reading = {"platform": "darwin", "source": "sysctl", "totalMb": total, "availableMb": None, "swapTotalMb": None,
+               "swapUsedMb": None, "osLevel": None, "psi": None, "cgroupLimitMb": None}
+    try:
+        level = int(values["kern.memorystatus_level"])  # % of memory the kernel counts as available
+        if 0 <= level <= 100:
+            reading["availableMb"] = total * level / 100
+    except (KeyError, ValueError):
+        pass
+    if reading["availableMb"] is None and vm_stat_text:
+        reading["availableMb"] = parse_vm_stat(vm_stat_text)
+        reading["source"] = "sysctl+vm_stat"
+    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["cpus"] = int(values["hw.ncpu"])
+    except (KeyError, ValueError):
+        pass
+    return reading
+
+
+def parse_meminfo(text):
+    values = {}
+    for line in (text or "").splitlines():
+        name, sep, rest = line.partition(":")
+        parts = rest.split()
+        if sep and parts and parts[0].isdigit():
+            values[name.strip()] = int(parts[0]) / 1024  # kB -> MB
+    return values
+
+
+def parse_psi(text):
+    """/proc/pressure/memory -> {'someAvg10': float, 'fullAvg10': float} (missing lines omitted)."""
+    result = {}
+    for line in (text or "").splitlines():
+        kind, _, rest = line.partition(" ")
+        match = re.search(r"avg10=([0-9.]+)", rest)
+        if kind in ("some", "full") and match:
+            result[kind + "Avg10"] = float(match.group(1))
+    return result or None
+
+
+def _cgroup_int(text):
+    value = (text or "").strip()
+    if not value or value == "max":
+        return None
+    try:
+        return int(value)
+    except ValueError:
+        return None
+
+
+def parse_cpu_max(text):
+    """cgroup v2 cpu.max ('200000 100000' or 'max 100000') -> CPUs (ceil), or None."""
+    parts = (text or "").split()
+    if len(parts) != 2 or parts[0] == "max":
+        return None
+    try:
+        quota, period = int(parts[0]), int(parts[1])
+    except ValueError:
+        return None
+    return max(1, -(-quota // period)) if quota > 0 and period > 0 else None
+
+
+def linux_reading(meminfo_text, psi_text=None, cgroup=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)."""
+    info = parse_meminfo(meminfo_text)
+    if "MemTotal" not in info:
+        return None
+    total = info["MemTotal"]
+    available = info.get("MemAvailable")
+    if available is None:  # kernels before 3.14
+        available = info.get("MemFree", 0) + info.get("Buffers", 0) + info.get("Cached", 0)
+    reading = {"platform": "linux", "source": "proc", "totalMb": total, "availableMb": available,
+               "swapTotalMb": info.get("SwapTotal"), "swapUsedMb": None, "osLevel": None,
+               "psi": parse_psi(psi_text) if psi_text else None, "cgroupLimitMb": None}
+    if info.get("SwapTotal") is not None and info.get("SwapFree") is not None:
+        reading["swapUsedMb"] = max(0.0, info["SwapTotal"] - info["SwapFree"])
+    cgroup = cgroup or {}
+    limit = _cgroup_int(cgroup.get("max"))
+    if limit and limit / MB < total:
+        # Inside a container: the cgroup limit is the machine this process really has. Usage is the
+        # working set (memory.current minus inactive_file, as the kubelet counts it): page cache the
+        # kernel can reclaim is not memory in use.
+        used = _cgroup_int(cgroup.get("current")) or 0
+        stat = dict(re.findall(r"^(\w+) (\d+)$", cgroup.get("stat") or "", re.MULTILINE))
+        used = max(0, used - int(stat.get("inactive_file", 0)))
+        reading["cgroupLimitMb"] = limit / MB
+        reading["totalMb"] = limit / MB
+        reading["availableMb"] = max(0.0, min(available, (limit - used) / MB))
+        reading["source"] = "proc+cgroup"
+        if cgroup.get("pressure"):
+            reading["psi"] = parse_psi(cgroup["pressure"]) or reading["psi"]
+    cpus = parse_cpu_max(cgroup.get("cpuMax"))
+    if cpus:
+        reading["cpuQuota"] = cpus
+    return reading
+
+
+def parse_ps(text):
+    """``ps -axo pid=,ppid=,rss=,comm=`` -> [(pid, ppid, rss_kb, basename)]."""
+    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()):
+            continue
+        rows.append((int(parts[0]), int(parts[1]), int(parts[2]), os.path.basename(parts[3].strip())))
+    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}
+    children = {}
+    for pid, ppid, _, _ in rows:
+        children.setdefault(ppid, []).append(pid)
+
+    def has_agent_ancestor(pid):
+        seen, current = set(), parent.get(pid)
+        while current and current not in seen:
+            if kind.get(current):
+                return True
+            seen.add(current)
+            current = parent.get(current)
+        return False
+
+    by_kind, total = {}, 0
+    for pid, _, _, _ in rows:
+        if not kind.get(pid) or has_agent_ancestor(pid):
+            continue
+        stack, seen, tree_kb = [pid], set(), 0
+        while stack:
+            current = stack.pop()
+            if current in seen:
+                continue
+            seen.add(current)
+            tree_kb += rss.get(current, 0)
+            stack.extend(children.get(current, []))
+        entry = by_kind.setdefault(kind[pid], {"count": 0, "rssMb": 0})
+        entry["count"] += 1
+        entry["rssMb"] += round(tree_kb / 1024)
+        total += tree_kb
+    return {"count": sum(e["count"] for e in by_kind.values()), "rssMb": round(total / 1024), "byKind": by_kind}
+
+
+# --- readers (side effects: one subprocess or a few /proc reads) ----------------------------
+
+def _run(argv, timeout=2.0):
+    try:
+        done = subprocess.run(argv, capture_output=True, text=True, timeout=timeout, env={"PATH": "/usr/sbin:/usr/bin:/sbin:/bin", "LC_ALL": "C"})
+        return done.stdout
+    except (OSError, subprocess.SubprocessError, ValueError):
+        return ""
+
+
+def _read(path, limit=256 * 1024):
+    try:
+        with open(path, "r", encoding="utf-8", errors="replace") as handle:
+            return handle.read(limit)
+    except OSError:
+        return None
+
+
+def cgroup_files():
+    """cgroup v2 files of this process: the tightest memory.max walking up to the root (with
+    that level's memory.current and memory.stat), the leaf memory.pressure and the tightest
+    cpu.max. Empty dict outside cgroup v2."""
+    text = _read("/proc/self/cgroup") or ""
+    leaf = next((line[3:].strip() for line in text.splitlines() if line.startswith("0::")), None)
+    if leaf is None:
+        return {}
+    root = Path("/sys/fs/cgroup")
+    path = Path(os.path.normpath(str(root / leaf.lstrip("/"))))
+    if path != root and root not in path.parents:
+        return {}
+    result, best, best_cpu = {}, None, None
+    for directory in (path, *[p for p in path.parents if p == root or root in p.parents]):
+        limit = _cgroup_int(_read(directory / "memory.max", 64))
+        if limit and (best is None or limit < best):
+            best = limit
+            result.update(max=str(limit), current=_read(directory / "memory.current", 64),
+                          stat=_read(directory / "memory.stat", 16 * 1024),
+                          pressure=_read(directory / "memory.pressure", 512))
+        cpu_text = _read(directory / "cpu.max", 64)
+        cpus = parse_cpu_max(cpu_text)
+        if cpus and (best_cpu is None or cpus < best_cpu):
+            best_cpu, result["cpuMax"] = cpus, cpu_text
+        if directory == root:
+            break
+    return result
+
+
+def read_machine(platform=None):
+    """One raw reading of the machine (no processes)."""
+    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"])
+        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())
+    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,
+                   "osLevel": None, "psi": None, "cgroupLimitMb": None}
+    if not reading.get("cpus"):
+        try:
+            reading["cpus"] = len(os.sched_getaffinity(0))  # type: ignore[attr-defined]
+        except (AttributeError, OSError):
+            reading["cpus"] = os.cpu_count() or 1
+    if reading.get("cpuQuota"):
+        reading["cpus"] = min(reading["cpus"], reading.pop("cpuQuota"))
+    try:
+        reading["load"] = [round(x, 2) for x in os.getloadavg()]
+    except (AttributeError, OSError):
+        reading["load"] = None
+    return reading
+
+
+def read_processes(platform=None):
+    platform = platform or sys.platform
+    if platform.startswith("linux"):
+        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:
+            return None
+        for pid in pids:
+            stat = _read("/proc/" + pid + "/stat", 4096)
+            statm = _read("/proc/" + pid + "/statm", 512)
+            if not stat or not statm or ")" not in stat:
+                continue
+            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):
+                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
+    return None
+
+
+# --- assessment ------------------------------------------------------------------------------
+
+def worst(*levels):
+    order = {"normal": 0, "warn": 1, "critical": 2}
+    known = [l for l in levels if l in order]
+    return max(known, key=order.get) if known else None
+
+
+def assess(reading, cfg):
+    """Pressure level for a raw reading: the worst of the OS level, PSI and available percent."""
+    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"),
+                "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"
+    if by_percent != "normal":
+        reasons.append("disponível " + str(round(percent)) + "% < " + str(round(cfg["warnAvailablePercent"] if by_percent == "warn"
+                                                                                     else cfg["criticalAvailablePercent"])) + "%")
+    psi_level = None
+    psi = reading.get("psi")
+    if psi:
+        if psi.get("fullAvg10", 0) >= cfg["psiCriticalFullAvg10"]:
+            psi_level = "critical"
+            reasons.append("PSI full avg10 " + str(psi["fullAvg10"]))
+        elif psi.get("someAvg10", 0) >= cfg["psiWarnSomeAvg10"]:
+            psi_level = "warn"
+            reasons.append("PSI some avg10 " + str(psi["someAvg10"]))
+        else:
+            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."""
+    cpus = max(1, int(reading.get("cpus") or 1))
+    level = pressure["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)
+    if level == "critical":
+        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)
+    # 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"
+    return {"mode": mode, "maxParallelAgents": agents, "maxParallelHeavyJobs": heavy, "maxWorkersPerJob": workers,
+            "budgetMb": round(budget), "reasons": reasons}
+
+
+def build(reading, cfg, meta, agents=None, cached=False, age=0):
+    pressure = assess(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}
+    load = reading.get("load")
+    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}
+
+
+# --- cache ----------------------------------------------------------------------------------
+
+def read_cache(home, max_age, now=None):
+    path = cache_path(home)
+    try:
+        if path.is_symlink() or not path.is_file() or path.stat().st_size > 64 * 1024:
+            return None, 0
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None, 0
+    if not isinstance(data, dict) or data.get("schema") != CACHE_SCHEMA or not isinstance(data.get("reading"), dict):
+        return None, 0
+    try:
+        age = (now or time.time()) - float(data.get("at") or 0)
+        valid = math.isfinite(age) and valid_reading(data["reading"])
+    except (TypeError, ValueError):
+        return None, 0
+    if not valid or age < 0 or age > max_age:
+        return None, 0  # a corrupt or old cache is a miss; the next probe rewrites it
+    return data["reading"], age
+
+
+def valid_reading(reading):
+    """A raw reading has the numeric fields build() uses (None allowed where unmeasured)."""
+    def number(value, allow_none=True):
+        return (value is None and allow_none) or (isinstance(value, (int, float)) and not isinstance(value, bool)
+                                                 and math.isfinite(value) and value >= 0)
+    if not isinstance(reading, dict):
+        return False
+    if not all(number(reading.get(k)) for k in ("totalMb", "availableMb", "swapTotalMb", "swapUsedMb", "cgroupLimitMb")):
+        return False
+    if reading.get("totalMb") == 0 or (reading.get("totalMb") is None and reading.get("availableMb") is not None):
+        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")
+    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
+
+
+def write_cache(home, reading):
+    """Atomic, private, never through a symlink; a failure only means no cache."""
+    # The home itself may be a symlink (/home -> /var/home on Fedora Atomic); only the
+    # directories this CLI creates below it must not be.
+    base = Path(os.path.realpath(home))
+    path = cache_path(base)
+    try:
+        directory = path.parent
+        for part in (base / ".local", base / ".local" / "state", base / ".local" / "state" / "crow-skills"):
+            if part.is_symlink():
+                return
+        directory.mkdir(parents=True, exist_ok=True, mode=0o700)
+        temp = directory / ("." + path.name + "." + uuid.uuid4().hex)
+        fd = os.open(temp, os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0), 0o600)
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as handle:
+                json.dump({"schema": CACHE_SCHEMA, "at": time.time(), "reading": reading}, handle)
+            os.replace(temp, path)
+        finally:
+            if os.path.lexists(temp):
+                os.unlink(temp)
+    except OSError:
+        pass
+
+
+def fixture_reading():
+    """The pinned reading of CROW_RESOURCES_FIXTURE (tests), or None when unset or invalid:
+    a bad fixture falls back to the real machine instead of failing."""
+    fixture = os.environ.get("CROW_RESOURCES_FIXTURE")
+    if not fixture:
+        return None
+    try:
+        path = Path(fixture)
+        if not path.is_file() or path.stat().st_size > 64 * 1024:
+            return None
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    if not isinstance(data, dict):
+        return None
+    agents = data.pop("agents", None)
+    if not valid_reading(data):
+        return None
+    if isinstance(agents, dict):
+        data["agents"] = agents
+    return data
+
+
+def probe(home, processes=True, use_cache=False, platform=None):
+    """The crow-resources/1 document. use_cache: reuse a reading younger than cacheSeconds
+    (hooks, status lines, snapshot); processes: also scan agent CLI process trees."""
+    cfg, meta = load_config(home)
+    reading, age, cached = None, 0, False
+    data = fixture_reading()
+    if data is not None:
+        agents = data.pop("agents", None) if processes else None
+        return build(data, cfg, meta, agents, False, 0)
+    if use_cache:
+        reading, age = read_cache(home, cfg["cacheSeconds"])
+        cached = reading is not None
+    if reading is None:
+        reading = read_machine(platform)
+        write_cache(home, reading)
+    agents = read_processes(platform) if processes else None
+    return build(reading, cfg, meta, agents, cached, age)
+
+
+# --- presentation ---------------------------------------------------------------------------
+
+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"
+
+
+def gb(mb):
+    return "?" if mb is None else ("%.1f" % (mb / 1024)).replace(".", ",")
+
+
+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"]
+    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.")
+    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."
+
+
+def segment(data, unicode=True):
+    """Compact status line/tmux segment, empty when the machine is fine (e.g. 'mem ▲ 85% ×2')."""
+    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)
+    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"])
+
+
+def render(data):
+    memory, pressure, rec, cpu = data["memory"], data["pressure"], data["recommendation"], data["cpu"]
+    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 "") +
+             (" · 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 "")]
+    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 ""))
+    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)
+    for error in data["config"]["errors"]:
+        lines.append("config: " + error)
+    return "\n".join(lines)
+
+
+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")
+    args = p.parse_args(argv)
+    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))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())