@andespindola/crow-skills 0.11.1 → 0.12.0

package/crow_skills/resources.py

@@ -31,6 +31,10 @@ JSON raw reading (optionally with an "agents" object); the cache is then bypasse
 
 The probe never changes a host limit. Thresholds come from DEFAULTS, merged
 with ~/.config/crow-skills/resources.json when it exists.
+
+Orphan processes (crow-orphans/1, ``crow-skills resources --orphans``) read a
+fuller table (``ps -o pid=,ppid=,pgid=,uid=,rss=,etime=,stat=,args=``) only
+when asked, or from the Stop/SessionEnd hooks; see the section below.
 """
 from datetime import datetime, timezone
 import json
@@ -119,35 +123,41 @@ def now_iso():
 
 # --- configuration -----------------------------------------------------------------------
 
-def load_config(home):
-    """Effective thresholds and the problems found in the user's file (never raises)."""
+def config_file(home):
+    """(dict or None, errors) from the user's resources.json; 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)
+            return None, ["resources.json não é um arquivo regular; padrões usados."]
+        if not path.is_file():
+            return None, []
+        if path.stat().st_size > MAX_CONFIG:
+            return None, ["resources.json maior que 64 KiB; padrões usados."]
+        data = json.loads(path.read_text(encoding="utf-8"))
     except (OSError, ValueError, UnicodeDecodeError):
-        errors.append("resources.json ilegível ou JSON inválido; padrões usados.")
+        return None, ["resources.json ilegível ou JSON inválido; padrões usados."]
+    if not isinstance(data, dict):
+        return None, ["resources.json não é um objeto JSON; padrões usados."]
+    return data, []
+
+
+def load_config(home):
+    """Effective thresholds and the problems found in the user's file (never raises)."""
+    path = config_path(home)
+    effective = dict(DEFAULTS)
+    data, errors = config_file(home)
+    loaded = data is not None
+    for key, value in (data or {}).items():
+        if key in ("$schema", "schema", "comment", "orphans"):  # orphans: orphan_config()
+            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)
     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.")
@@ -794,6 +804,847 @@ def probe(home, processes=True, use_cache=False, platform=None):
     return build(reading, cfg, meta, agents, cached, age)
 
 
+# --- orphan processes (crow-orphans/1) ------------------------------------------------------
+#
+# A process left behind by agent tooling: a test runner, a stdio MCP server wrapper (npm exec /
+# npx), a browser driver or a build that outlived the session that started it. Agent CLIs start
+# each MCP server in its own process group, so killing the child's group leaks grandchildren,
+# which the kernel reparents to init/launchd (ppid 1). Detection therefore follows the process
+# TREE (a root and every descendant, whatever their groups), and a kill snapshots that tree
+# before the first signal: once the parent dies the ppid links that find the grandchildren are
+# gone.
+#
+# Orphan root: a process of this user, older than the threshold, that is either reparented to
+# init/launchd (ppid 1) or was recorded by the hooks as a descendant of a session that is now dead
+# (same pid, same start time and same redacted command: a reused pid never matches), AND whose
+# command matches an agent-tooling signature (or is a shell/env/timeout wrapper of a descendant
+# that does). Never: pid 1, this process and its ancestors, processes of other users, processes
+# of live sessions (crow-broadcast presence), allowlisted ones (anywhere in the tree), or, on
+# Linux, processes of a systemd service. Command lines are read only to match signatures and to
+# recheck identity before a signal; they are never printed or stored: the output carries the
+# executable and the package/script name, with anything token-like masked.
+
+ORPHAN_SCHEMA = "crow-orphans/1"
+ORPHAN_CACHE_SCHEMA = "crow-orphans-cache/1"
+ORPHAN_DEFAULTS = {"olderThanMinutes": 30, "graceSeconds": 5}
+ORPHAN_LIMITS = {"olderThanMinutes": (0, 30 * 24 * 60), "graceSeconds": (0.1, 120)}
+ORPHAN_CACHE_SECONDS = 30 * 60  # the prompt hint trusts an orphan scan this recent
+START_TOLERANCE = 3  # seconds between two estimates of a process start time (etime has 1 s resolution)
+# Records written by a hook and read by a later scan: two clocks, ps latency and possible clock steps.
+# A mismatch only ever means "not an orphan" for a process, and "alive" for a session's CLI.
+RECORD_TOLERANCE = 10
+CLI_REUSE_SECONDS = 60  # a recorded CLI pid alive with a start this close is the same, live CLI
+PS_COLUMNS = "pid=,ppid=,pgid=,uid=,rss=,etime=,stat=,args="
+# Name -> regex searched (case-insensitive) in the full command line. Config can add, replace or
+# disable (null) any of them.
+SIGNATURES = {
+    "npm-exec": r"(^|/)(npm|pnpm|yarn|bun)(\.cmd)?\s+(exec|x|dlx)(\s|$)|(^|/)(npx|pnpx|bunx|uvx)(\s|$)|npx-cli\.js",
+    "mcp-server": r"mcp[-_]?server|server[-_][a-z0-9_-]*mcp|[@/_-]mcp([-_/\s@]|$)",
+    "node-test": r"(^|/)(node|nodejs|bun|deno|tsx|ts-node)\s(.*[\s/._-])?(test|tests|spec|specs)([/._-]|\s|$)|(^|/)node\s(.*\s)?--test(\s|$)",
+    "test-runner": r"(^|/)(jest|vitest|mocha|ava|karma|cypress|pytest|py\.test|tox|nox)(\s|$)|\s-m\s+(pytest|unittest)(\s|$)"
+                   r"|(^|/)go\s+test(\s|$)|(^|/)playwright\s+test(\s|$)",
+    "browser-driver": r"(^|/)(chromedriver|geckodriver|msedgedriver)(\s|$)|ms-playwright|chrome-headless-shell|puppeteer"
+                      r"|(^|/)chrom(e|ium)[^/\s]*\s(.*\s)?--headless",
+    "rust-build": r"(^|/)(cargo|rustc)(\s|$)",
+    "dev-server": r"(^|/)(vite|nodemon|webpack-dev-server|parcel)(\s|$)|(^|/)(next|nuxt|astro|webpack)\s+(dev|serve|start)(\s|$)"
+                  r"|next-server|(^|/)tsc\s(.*\s)?(-w|--watch)(\s|$)|(^|/)esbuild\s(.*\s)?--watch",
+}
+# A root with this executable is an orphan only through a descendant that matches a signature.
+WRAPPERS = ("sh", "bash", "zsh", "dash", "ksh", "fish", "env", "timeout", "gtimeout", "nohup", "time", "xargs")
+# Generic long-running daemons people start by hand (VPN, keep-awake, agents, local services):
+# protected even when they match a signature or sit in a matching tree. Personal additions go
+# to resources.json ("orphans": {"allowlist": [...]}), never here.
+ALLOWLIST = ("wg-quick", "wireguard-go", "openvpn", "tailscaled", "caffeinate", "ssh-agent", "gpg-agent", "ollama",
+             "colima", "limactl", "dockerd", "containerd", "syncthing", "postgres", "redis-server", "mongod", "mysqld")
+SHELLS = ("sh", "bash", "zsh", "dash", "ksh", "fish")
+NPM_LIKE = ("npm", "pnpm", "yarn", "bun")
+PACKAGE_RUNNERS = ("npx", "pnpx", "bunx", "uvx", "pipx")
+INTERPRETER = re.compile(r"(node|nodejs|bun|deno|tsx|ts-node|python[0-9.]*|ruby|perl|php)", re.IGNORECASE)
+SUBCOMMANDS = ("test", "run", "build", "check", "dev", "serve", "start", "watch", "exec", "x", "dlx", "bench", "clippy", "install")
+TOKENISH = re.compile(r"(?i)token|secret|passw|apikey|api[_-]key|bearer|credential|authorization|private[_-]?key"
+                      r"|(gh[pousr]_|github_pat_|glpat-|xox[abprs]-|AKIA[A-Z0-9]|AIza)|^sk-"
+                      r"|^(?=.*[0-9])(?=.*[A-Za-z])[A-Za-z0-9+/_=.-]{32,}$|^(?=.*[0-9])[0-9a-fA-F]{20,}$")
+SAFE_WORD = re.compile(r"[^A-Za-z0-9@._/:+=-]")
+# What a shown word may look like: a path/script/module name, or an npm-style package spec
+# (@scope/name@version). URLs, user:password@host, NAME=value and anything else are masked.
+SHOWN_WORD = re.compile(r"(@[A-Za-z0-9._-]+/)?[A-Za-z0-9._/+-]+(@[A-Za-z0-9._^~+-]+)?")
+RUN_SCRIPT = re.compile(r"[A-Za-z0-9._-]{1,30}(:[A-Za-z0-9._-]{1,30}){0,3}")  # npm run test:unit (only there)
+ASSIGNMENT = re.compile(r"[A-Za-z_][A-Za-z0-9_]*=")
+# Options whose next word is a value, not the package/script (uvx --from git+https://..., node -r x).
+VALUE_OPTIONS = ("--from", "--spec", "-p", "--with", "--registry", "--cache", "--prefix", "-r", "--require", "--import",
+                 "--loader", "--experimental-loader", "-w", "--workspace", "--userconfig", "-C", "--cwd", "--dir", "--python")
+INLINE_OPTIONS = ("-c", "--call", "-e", "--eval")  # everything after them is inline code or a command line: never shown
+ENV_VALUE_OPTIONS = ("-u", "--unset", "-C", "--chdir", "-S", "--split-string")  # env's own options with a value
+# What an interpreter's script looks like: a path, or a file with a script extension. Other operands
+# (option values such as 127.0.0.1:9229 or lib) are never shown as the script.
+SCRIPT_LIKE = re.compile(r"\S*/\S*|[^/\s]+\.(m?[jt]sx?|c[jt]s|py|rb|pl|php|sh|bash|zsh|lua)", re.IGNORECASE)
+
+
+def parse_etime(text):
+    """ps etime ([[dd-]hh:]mm:ss) -> seconds, or None."""
+    match = re.fullmatch(r"\s*(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)\s*", text or "")
+    if not match:
+        return None
+    days, hours, minutes, seconds = (int(x) if x else 0 for x in match.groups())
+    return ((days * 24 + hours) * 60 + minutes) * 60 + seconds
+
+
+def parse_table(text):
+    """``ps -o pid=,ppid=,pgid=,uid=,rss=,etime=,stat=,args=`` (macOS or procps) -> rows:
+    {pid, ppid, pgid, uid, rssKb, age (s), stat, command}. The command stays in memory only."""
+    rows = []
+    for line in (text or "").splitlines():
+        parts = line.split(None, 7)
+        if len(parts) < 7 or not all(p.isdigit() for p in parts[:5]):
+            continue
+        age = parse_etime(parts[5])
+        if age is None:
+            continue
+        rows.append({"pid": int(parts[0]), "ppid": int(parts[1]), "pgid": int(parts[2]), "uid": int(parts[3]),
+                     "rssKb": int(parts[4]), "age": age, "stat": parts[6], "command": parts[7].strip() if len(parts) > 7 else ""})
+    return rows
+
+
+def ps_argv(platform=None):
+    platform = platform or sys.platform
+    if platform.startswith("linux"):
+        return ["ps", "-e", "-ww", "-o", PS_COLUMNS]
+    # BSD/macOS: never -e there (it prints the environment).
+    return ["ps", "-axww", "-o", PS_COLUMNS]
+
+
+def table_is_fixture():
+    return bool(os.environ.get("CROW_PS_FIXTURE"))
+
+
+def signals_allowed():
+    """A kill only ever runs against the real process table (never a test fixture)."""
+    return not table_is_fixture()
+
+
+def orphan_note(config_file_path):
+    """Shown with every non-empty listing: a hand-started daemon may match a signature."""
+    return ("Atenção: uma árvore listada pode ser um daemon que o usuário iniciou à mão (fora do launchd/systemd), não uma "
+            "sobra de agente; nada é encerrado sem --kill. Para excluí-la, adicione o pacote ou script à allowlist em " +
+            str(config_file_path) + ', por exemplo {"orphans": {"allowlist": ["@scope/meu-servidor-mcp", "re:meu-daemon\\\\.js"]}}.')
+
+
+def read_table(platform=None):
+    """Rows of every process (one ps call), or None when ps is unavailable. Tests (and only
+    tests) pin the table with CROW_PS_FIXTURE, the path of a ps output in the same format."""
+    fixture = os.environ.get("CROW_PS_FIXTURE")
+    if fixture:
+        try:
+            return parse_table(Path(fixture).read_text(encoding="utf-8"))
+        except OSError:
+            return None
+    platform = platform or sys.platform
+    if not (platform == "darwin" or platform.startswith("linux") or "bsd" in platform):
+        return None
+    text = _run(ps_argv(platform), timeout=5.0)
+    return parse_table(text) if text else None
+
+
+def zombie(row):
+    return row["stat"][:1] in ("Z", "X")
+
+
+def start_of(row, now):
+    return now - row["age"]
+
+
+def _basename(word):
+    return os.path.basename(word.rstrip("/")) or word
+
+
+def _mask(word, limit=60, shape=SHOWN_WORD):
+    raw = word.strip("'\"")
+    word = SAFE_WORD.sub("", raw)
+    if not word:
+        return ""
+    if word != raw or "://" in word or "=" in word or not shape.fullmatch(word) or TOKENISH.search(word):
+        return "***"
+    return word[:limit]
+
+
+def _script(words):
+    """First operand that looks like a script (skipping option values)."""
+    skip = False
+    for word in words:
+        if skip:
+            skip = False
+            continue
+        if word in INLINE_OPTIONS:
+            return None
+        if word in VALUE_OPTIONS:
+            skip = True
+            continue
+        if word == "--" or word.startswith("-"):
+            continue
+        if SCRIPT_LIKE.fullmatch(word.strip("'\"")):
+            return word
+    return None
+
+
+def _operand(words):
+    """First non-option word (``--package=X`` and ``--package X`` give X; values of VALUE_OPTIONS are skipped)."""
+    skip = False
+    for index, word in enumerate(words):
+        if skip:
+            skip = False
+            continue
+        if word.startswith("--package="):
+            return word.split("=", 1)[1]
+        if word == "--package" and index + 1 < len(words):
+            return words[index + 1]
+        if word in INLINE_OPTIONS:
+            return None
+        if word in VALUE_OPTIONS:
+            skip = True
+            continue
+        if word == "--" or word.startswith("-"):
+            continue
+        return word
+    return None
+
+
+def redact(command):
+    """Executable + package/script name only, anything token-like masked: what may be shown."""
+    words = (command or "").split()
+    while words and ASSIGNMENT.match(words[0].strip("'\"")):
+        words = words[1:]  # NAME=value prefixes are never shown
+    if not words:
+        return "?"
+    exe = _mask(_basename(words[0]), 40) or "?"
+    rest = words[1:]
+    parts = [exe]
+    if exe in SHELLS and "-c" in rest:
+        inner = " ".join(rest[rest.index("-c") + 1:]).strip("'\"")
+        inner = re.sub(r"^\s*exec\s+", "", inner)
+        return (exe + " -c " + redact(inner))[:80]
+    if exe == "env":
+        while rest and (rest[0].startswith("-") or ASSIGNMENT.match(rest[0])):
+            rest = rest[2:] if rest[0] in ENV_VALUE_OPTIONS else rest[1:]
+        return ("env " + redact(" ".join(rest)))[:80] if rest else "env"
+    if exe in NPM_LIKE and rest and rest[0] in SUBCOMMANDS:
+        parts.append(rest[0])
+        package = _operand(rest[1:])
+        if package and rest[0] in ("exec", "x", "dlx"):
+            parts.append(_mask(package))
+        elif package and rest[0] in ("run", "run-script"):
+            parts.append(_mask(package, shape=RUN_SCRIPT))
+    elif exe in SHELLS:
+        script = _script(rest)
+        if script:
+            parts.append(_mask(_basename(script)))
+    elif exe in PACKAGE_RUNNERS:
+        package = _operand(rest)
+        if package:
+            parts.append(_mask(package))
+    elif INTERPRETER.fullmatch(exe):
+        if "-c" in rest or "-e" in rest or "--eval" in rest:
+            parts.append("-c" if "-c" in rest else "-e")  # inline code is never shown
+        elif "-m" in rest and rest.index("-m") + 1 < len(rest):
+            parts += ["-m", _mask(rest[rest.index("-m") + 1])]
+        else:
+            script = _script(rest)
+            if script:
+                name = _mask(_basename(script))
+                parts.append(name)
+                if name in ("npx-cli.js", "npm-cli.js"):
+                    package = _operand(rest[rest.index(script) + 1:])
+                    if package:
+                        parts.append(_mask(package))
+    else:
+        operand = _operand(rest)
+        if operand in SUBCOMMANDS:
+            parts.append(operand)
+    return " ".join(p for p in parts if p)[:80]
+
+
+def _allowed(command, allow):
+    words = (command or "").split()
+    names = {_basename(w.strip("'\"")) for w in words}
+    for entry in allow:
+        if isinstance(entry, re.Pattern):
+            if entry.search(command or ""):
+                return True
+        elif entry in names or any(w == entry or w.startswith(entry + "@") for w in words):
+            return True
+    return False
+
+
+def orphan_config(home):
+    """Effective orphan settings ("orphans" in resources.json) and the problems found (never raises)."""
+    data, errors = config_file(home)
+    signatures, wrappers, allow = dict(SIGNATURES), list(WRAPPERS), list(ALLOWLIST)
+    cfg = dict(ORPHAN_DEFAULTS)
+    section = (data or {}).get("orphans")
+    if section is not None and not isinstance(section, dict):
+        errors.append("orphans deve ser um objeto; padrões usados.")
+        section = None
+    for key, value in (section or {}).items():
+        if key in ORPHAN_LIMITS:
+            low, high = ORPHAN_LIMITS[key]
+            if isinstance(value, bool) or not isinstance(value, (int, float)) or not low <= value <= high:
+                errors.append("orphans." + key + " inválido (esperado número entre " + str(low) + " e " + str(high) + "); padrão mantido.")
+            else:
+                cfg[key] = float(value)
+        elif key == "allowlist" and isinstance(value, list) and len(value) <= 200:
+            for item in value:
+                if isinstance(item, str) and 0 < len(item) <= 200:
+                    allow.append(item)
+                else:
+                    errors.append("orphans.allowlist: item inválido ignorado.")
+        elif key == "wrappers" and isinstance(value, list) and len(value) <= 50:
+            for item in value:
+                if isinstance(item, str) and re.fullmatch(r"[A-Za-z0-9._+-]{1,40}", item):
+                    wrappers.append(item)
+                else:
+                    errors.append("orphans.wrappers: item inválido ignorado.")
+        elif key == "signatures" and isinstance(value, dict) and len(value) <= 100:
+            for name, pattern in value.items():
+                if pattern is None:
+                    signatures.pop(name, None)
+                elif isinstance(pattern, str) and 0 < len(pattern) <= 500 and re.fullmatch(r"[A-Za-z0-9._-]{1,40}", str(name)):
+                    signatures[name] = pattern
+                else:
+                    errors.append("orphans.signatures." + str(name)[:40] + " inválida; ignorada.")
+        elif key not in ("comment",):
+            errors.append("orphans." + str(key)[:40] + ": chave desconhecida ou valor inválido; ignorada.")
+    compiled = []
+    for name, pattern in signatures.items():
+        try:
+            compiled.append((name, re.compile(pattern, re.IGNORECASE)))
+        except re.error:
+            errors.append("orphans.signatures." + name[:40] + ": regex inválida; ignorada.")
+    matchers = []
+    for item in allow:
+        if item.startswith("re:"):
+            try:
+                matchers.append(re.compile(item[3:], re.IGNORECASE))
+            except re.error:
+                errors.append("orphans.allowlist: regex inválida ignorada.")
+        else:
+            matchers.append(item)
+    cfg.update(signatures=compiled, wrappers=tuple(wrappers), allowlist=matchers,
+               public={"olderThanMinutes": cfg["olderThanMinutes"], "graceSeconds": cfg["graceSeconds"],
+                       "signatures": sorted(signatures), "wrappers": list(wrappers), "allowlist": list(allow)})
+    return cfg, {"path": str(config_path(home)), "errors": errors}
+
+
+def signature(command, cfg):
+    for name, pattern in cfg["signatures"]:
+        if pattern.search(command or ""):
+            return name
+    return None
+
+
+def children_of(rows):
+    kids = {}
+    for row in rows:
+        kids.setdefault(row["ppid"], []).append(row["pid"])
+    return kids
+
+
+def tree_pids(root, kids):
+    """root and every descendant (parents before children)."""
+    order, seen = [root], {root}
+    for pid in order:
+        for child in kids.get(pid, ()):
+            if child not in seen:
+                seen.add(child)
+                order.append(child)
+    return order
+
+
+def ancestry(pid, rows):
+    """pid and its ancestors present in rows (stops at pid 1 or a loop)."""
+    parent = {r["pid"]: r["ppid"] for r in rows}
+    chain, current = [], pid
+    while current and current not in chain:
+        chain.append(current)
+        if current <= 1:
+            break
+        current = parent.get(current)
+    return chain
+
+
+def systemd_service(pid):
+    """Linux: True when the process belongs to a systemd service (its own lifecycle manager), and
+    also when its cgroup cannot be read (fail closed: an unknown process is never an orphan)."""
+    text = _read("/proc/" + str(int(pid)) + "/cgroup", 4096) if sys.platform.startswith("linux") else None
+    if not text:
+        return True
+    for line in text.splitlines():
+        if line.startswith("0::") and line.rstrip().endswith(".service"):
+            return True
+    return False
+
+
+def parse_launchctl(text):
+    """``launchctl list`` (PID, status, label per line) -> pids of running launchd jobs."""
+    pids = set()
+    for line in (text or "").splitlines():
+        first = line.split("\t", 1)[0].strip()
+        if first.isdigit() and int(first) > 1:
+            pids.add(int(first))
+    return pids
+
+
+class ServiceChecker:
+    """pid -> True when a service manager owns the process: a launchd job of this user (macOS,
+    one ``launchctl list`` call, made only when there is a candidate) or a systemd service
+    (Linux). A daemon the user runs through launchd/systemd has ppid 1 by design and is never
+    an orphan, whatever its command line. Fails closed: when the manager cannot be asked (error,
+    timeout under pressure, unreadable cgroup) every candidate counts as managed and
+    ``unverified`` says why, so a scan never claims a clean machine it could not check."""
+
+    def __init__(self, platform=None, runner=None):
+        self.platform = platform or sys.platform
+        self.runner = runner
+        self.unverified = None
+        self._pids = False
+
+    def __call__(self, pid):
+        if self.platform.startswith("linux"):
+            text = _read("/proc/" + str(int(pid)) + "/cgroup", 4096)
+            if not text:
+                self.unverified = "cgroup do systemd ilegível"
+                return True
+            return any(line.startswith("0::") and line.rstrip().endswith(".service") for line in text.splitlines())
+        if self.platform != "darwin":
+            return False
+        if self._pids is False:
+            self._pids = parse_launchctl((self.runner or _run)(["launchctl", "list"], timeout=3.0)) or None
+            if self._pids is None:
+                self.unverified = "launchctl indisponível"
+        return self._pids is None or pid in self._pids
+
+
+def service_checker(platform=None, runner=None):
+    return ServiceChecker(platform, runner)
+
+
+# Agent CLIs are sessions, never tooling leftovers: a tree that holds one (a headless `claude -p`,
+# `codex exec` started with nohup) is never an orphan, whatever its arguments match.
+AGENT_PATHS = re.compile(r"@anthropic-ai/claude-code|@openai/codex|@google/gemini-cli|/claude-code/|/codex-cli/", re.IGNORECASE)
+
+
+def agent_cli(command):
+    words = (command or "").split()
+    while words and ASSIGNMENT.match(words[0]):
+        words = words[1:]
+    if not words:
+        return False
+    exe = _basename(words[0]).lower()
+    if exe in AGENT_NAMES or AGENT_PATHS.search(command or ""):
+        return True
+    if INTERPRETER.fullmatch(exe):
+        script = _script(words[1:])
+        if script and re.sub(r"\.(m?js|cjs)$", "", _basename(script).lower()) in AGENT_NAMES:
+            return True
+    return False
+
+
+def find_orphans(rows, cfg, uid, now=None, older_than=None, protected=(), records=(), self_pids=(), managed=None):
+    """Orphan trees in a process table (pure apart from ``managed``, a pid -> bool callback).
+
+    protected: pids of live sessions (their descendants are protected too). records: processes
+    the hooks attributed to dead sessions, [{pid, start, display, session}]. Returns trees sorted
+    by RSS, each with private ``_entries`` (full commands, for a kill) that callers never print."""
+    now = time.time() if now is None else now
+    older_than = cfg["olderThanMinutes"] * 60 if older_than is None else older_than
+    alive = [r for r in rows if not zombie(r)]
+    by_pid = {r["pid"]: r for r in alive}
+    kids = children_of(alive)
+    shielded = set()
+    for pid in protected:
+        if pid in by_pid:
+            shielded.update(tree_pids(pid, kids))
+    self_pids = set(self_pids)
+    attributed = {}
+    for record in records:
+        row = by_pid.get(record.get("pid"))
+        if row and redact(row["command"]) == record.get("display") and isinstance(record.get("start"), (int, float)) \
+                and abs(start_of(row, now) - record["start"]) <= RECORD_TOLERANCE:
+            attributed[row["pid"]] = record
+    candidates = {}
+    for row in alive:
+        pid = row["pid"]
+        if pid <= 1 or row["uid"] != uid or pid in self_pids or pid in shielded:
+            continue
+        if pid in attributed:
+            cli = attributed[pid].get("cliPid")
+            if cli and cli in ancestry(pid, alive)[1:]:
+                continue  # still under the recorded CLI: that session is not dead
+            reason = "dead-session"
+        else:
+            parent = by_pid.get(row["ppid"])
+            subreaper = parent is not None and parent["uid"] == uid and \
+                _basename((parent["command"].split() or ["?"])[0]) == "systemd"  # systemd --user adopts orphans
+            reason = "reparented" if row["ppid"] == 1 or subreaper else None
+        if reason:
+            candidates[pid] = reason
+    trees = []
+    for pid, reason in candidates.items():
+        root = by_pid[pid]
+        if root["age"] < older_than:
+            continue
+        members = [by_pid[p] for p in tree_pids(pid, kids) if p in by_pid]
+        if any(m["uid"] != uid or m["pid"] in self_pids or m["pid"] in shielded or _allowed(m["command"], cfg["allowlist"])
+               or agent_cli(m["command"]) for m in members):
+            continue
+        name = signature(root["command"], cfg)
+        if name is None:
+            below = next((signature(m["command"], cfg) for m in members[1:] if signature(m["command"], cfg)), None)
+            exe = _basename((root["command"].split() or ["?"])[0])
+            if below and (reason == "dead-session" or exe in cfg["wrappers"]):
+                name = below
+        if name is None:
+            continue
+        if managed is not None and managed(pid):
+            continue
+        depth = {pid: 0}
+        processes, entries = [], []
+        for m in members:
+            if m["pid"] != pid:
+                depth[m["pid"]] = depth.get(m["ppid"], 0) + 1
+            processes.append({"pid": m["pid"], "ppid": m["ppid"], "pgid": m["pgid"], "depth": depth[m["pid"]],
+                              "ageSeconds": m["age"], "rssMb": round(m["rssKb"] / 1024, 1), "command": redact(m["command"])})
+            entries.append({"pid": m["pid"], "pgid": m["pgid"], "uid": m["uid"], "command": m["command"],
+                            "start": start_of(m, now)})
+        tree = {"root": pid, "reason": reason, "signature": name, "ageSeconds": root["age"],
+                "rssMb": round(sum(m["rssKb"] for m in members) / 1024, 1),
+                "groups": len({m["pgid"] for m in members}), "processes": processes, "_entries": entries}
+        if reason == "dead-session":
+            tree["session"] = str(attributed[pid].get("session") or "")[:20]
+        trees.append(tree)
+    inside = {p["pid"] for t in trees for p in t["processes"][1:]}
+    trees = [t for t in trees if t["root"] not in inside]  # a qualifying root inside another orphan tree
+    return sorted(trees, key=lambda t: (-t["rssMb"], t["root"]))
+
+
+def public_orphans(doc):
+    """The document without private keys (full commands)."""
+    if isinstance(doc, dict):
+        return {k: public_orphans(v) for k, v in doc.items() if not str(k).startswith("_")}
+    if isinstance(doc, list):
+        return [public_orphans(v) for v in doc]
+    return doc
+
+
+def orphan_scan(home, rows=None, context=None, older_than=None, now=None, uid=None, managed=None, self_pid=None):
+    """crow-orphans/1 for this machine. context: {"livePids", "liveKeys", "records",
+    "ledgerProcesses"} from crow-broadcast (process_context), None without it (then only
+    reparented roots count). Protected (with their trees): CLIs of live sessions, the processes
+    recorded for live sessions, and processes registered as running by live crow-behaviour runs."""
+    cfg, meta = orphan_config(home)
+    now = time.time() if now is None else now
+    rows = read_table() if rows is None else rows
+    doc = {"schema": ORPHAN_SCHEMA, "generatedAt": now_iso(), "available": rows is not None,
+           "olderThanSeconds": int(cfg["olderThanMinutes"] * 60 if older_than is None else older_than),
+           "trees": [], "count": 0, "processes": 0, "rssMb": 0.0, "settings": cfg["public"], "config": meta}
+    if rows is None:
+        return doc
+    uid = os.getuid() if uid is None and hasattr(os, "getuid") else uid
+    context = context or {}
+    by_pid = {r["pid"]: r for r in rows}
+    records = []
+    protected = set(context.get("livePids") or ())
+    for record in context.get("records") or []:
+        cli = by_pid.get(record.get("cliPid"))
+        cli_alive = cli is not None and not zombie(cli) and (not isinstance(record.get("cliStart"), (int, float))
+                                                             or abs(start_of(cli, now) - record["cliStart"]) <= CLI_REUSE_SECONDS)
+        if record.get("key") in (context.get("liveKeys") or ()) or cli_alive:
+            if cli is not None:
+                protected.add(cli["pid"])  # the recorded CLI (not the hook's shell) shields its whole tree
+            for item in record.get("processes") or []:  # and so do its recorded processes, even reparented
+                row = by_pid.get(item.get("pid")) if isinstance(item, dict) else None
+                if row and isinstance(item.get("start"), (int, float)) and abs(start_of(row, now) - item["start"]) <= RECORD_TOLERANCE:
+                    protected.add(row["pid"])
+            continue  # the session is alive: its processes are not orphans
+        for item in record.get("processes") or []:
+            if isinstance(item, dict):
+                records.append(dict(item, session=record.get("key"), cliPid=record.get("cliPid")))
+    for item in context.get("ledgerProcesses") or []:  # registered by a running crow-behaviour run
+        row = by_pid.get(item.get("pid")) if isinstance(item, dict) else None
+        if not row or not isinstance(item.get("start"), (int, float)) or abs(start_of(row, now) - item["start"]) > RECORD_TOLERANCE:
+            continue
+        if isinstance(item.get("cliPid"), int):
+            # Protected exactly while the agent CLI that registered it lives (same pid, same start).
+            cli = by_pid.get(item["cliPid"])
+            if cli is None or zombie(cli) or (isinstance(item.get("cliStart"), (int, float))
+                                              and abs(start_of(cli, now) - item["cliStart"]) > CLI_REUSE_SECONDS):
+                continue
+        elif not item.get("fresh", True):
+            continue  # CLI unknown: only while the ledger is fresh or its session is live
+        protected.add(row["pid"])
+    fixture = table_is_fixture()  # tests: fixture pids are not this machine's (no ancestry, no launchctl)
+    self_pids = [] if fixture and self_pid is None else ancestry(os.getpid() if self_pid is None else self_pid, rows)
+    if managed is None:
+        managed = (lambda pid: False) if fixture else service_checker()
+    trees = find_orphans(rows, cfg, uid, now, doc["olderThanSeconds"], protected, records, self_pids, managed)
+    doc.update(trees=trees, count=len(trees), processes=sum(len(t["processes"]) for t in trees),
+               rssMb=round(sum(t["rssMb"] for t in trees), 1), verified=not getattr(managed, "unverified", None))
+    if not doc["verified"]:
+        doc["unverifiedReason"] = managed.unverified
+    if trees:
+        doc["note"] = orphan_note(meta["path"])
+    return doc
+
+
+def kill_trees(entries, grace=5.0, rows_reader=None, kill=None, sleep=time.sleep, clock=time.monotonic,
+               interval=0.2, uid=None, self_pid=None):
+    """Stop process trees from a snapshot taken before the first signal.
+
+    entries: [{pid, pgid, uid, command, start}] (find_orphans ``_entries`` or a ledger snapshot).
+    TERM every process (and each group it leads when every member of that group is in the
+    snapshot), re-snapshot every ``interval`` during ``grace`` to catch new children, recheck
+    each pid's command and start time before any later signal (a reused pid is never signalled),
+    KILL what is still alive after the grace, and verify. Returns [{pid, command, result}] with
+    result terminated, killed, gone (already dead), reused (pid now another process), refused
+    (pid 1, this process or an ancestor, another user), denied or survived."""
+    if kill is None:
+        if table_is_fixture():
+            raise RuntimeError("CROW_PS_FIXTURE: a fixture table is never signalled")
+        kill = os.kill
+    rows_reader = rows_reader or read_table
+    uid = (os.getuid() if hasattr(os, "getuid") else 0) if uid is None else uid
+    self_pid = os.getpid() if self_pid is None else self_pid
+    rows = rows_reader()
+    if rows is None:
+        return [{"pid": e["pid"], "command": redact(e.get("command")), "result": "unverified"} for e in entries]
+    mine = set(ancestry(self_pid, rows)) | {self_pid}
+    forbidden_groups = {r["pgid"] for r in rows if r["pid"] in mine}
+    try:
+        forbidden_groups.add(os.getpgrp())
+    except OSError:
+        pass
+    tracked, results, signalled = {}, {}, {}
+    for entry in entries:
+        pid = entry.get("pid")
+        if not isinstance(pid, int) or pid <= 1 or pid in mine or entry.get("uid", uid) != uid:
+            results[pid] = "refused"
+        else:
+            tracked[pid] = entry
+
+    def identity(pid, by_pid, now):
+        row, entry = by_pid.get(pid), tracked[pid]
+        if row is None or zombie(row):
+            return "dead"
+        if row["command"] != entry["command"] or row["uid"] != uid or abs(start_of(row, now) - entry["start"]) > START_TOLERANCE:
+            return "other"
+        return "same"
+
+    def send(pids, sig, rows):
+        groups = {}
+        for row in rows:
+            groups.setdefault(row["pgid"], set()).add(row["pid"])
+        for pid in pids:
+            entry = tracked[pid]
+            owned = {p for p in tracked if results.get(p) not in ("reused", "refused", "denied")}
+            if entry.get("pgid") == pid and pid not in forbidden_groups and groups.get(pid, set()) <= owned:
+                try:
+                    kill(-pid, sig)
+                    for member in groups[pid]:  # reached by the group signal: may be gone before its own
+                        signalled[member] = sig
+                except OSError:
+                    pass
+            try:
+                kill(pid, sig)
+                signalled[pid] = sig
+            except ProcessLookupError:
+                signalled.setdefault(pid, sig)  # alive at the last snapshot: it ended during this stop
+            except PermissionError:
+                results[pid] = "denied"
+
+    def settle(rows, now):
+        by_pid = {r["pid"]: r for r in rows}
+        alive = []
+        for pid in list(tracked):
+            if pid in results:
+                continue
+            state = identity(pid, by_pid, now)
+            if state == "same":
+                alive.append(pid)
+            elif pid not in signalled:
+                results[pid] = "gone" if state == "dead" else "reused"
+            else:
+                results[pid] = "killed" if signalled[pid] == signal_kill else "terminated"
+        return alive
+
+    import signal as _signal
+    signal_kill = getattr(_signal, "SIGKILL", 9)
+    now = time.time()
+    alive = settle(rows, now)
+    send(alive, _signal.SIGTERM, rows)
+    deadline = clock() + max(0.0, grace)
+    while alive and clock() < deadline:
+        sleep(interval)
+        rows, now = rows_reader(), time.time()
+        if rows is None:
+            break
+        alive = settle(rows, now)
+        fresh = []
+        for row in rows:  # children started during the grace (a TERM handler, a respawning wrapper)
+            if row["ppid"] in alive and row["pid"] not in tracked and row["uid"] == uid and row["pid"] not in mine and not zombie(row):
+                tracked[row["pid"]] = {"pid": row["pid"], "pgid": row["pgid"], "uid": row["uid"], "command": row["command"],
+                                       "start": start_of(row, now)}
+                fresh.append(row["pid"])
+        if fresh:
+            send(fresh, _signal.SIGTERM, rows)
+            alive += fresh
+    rows, now = rows_reader(), time.time()
+    if rows is not None:
+        alive = settle(rows, now)
+        send(alive, signal_kill, rows)
+        for _ in range(20):
+            if not alive:
+                break
+            sleep(min(interval, 0.1))
+            rows, now = rows_reader(), time.time()
+            if rows is None:
+                break
+            alive = settle(rows, now)
+    for pid in tracked:
+        results.setdefault(pid, "survived" if rows is not None else "unverified")
+    commands = {e.get("pid"): e.get("command") for e in entries}
+    commands.update({pid: e["command"] for pid, e in tracked.items()})
+    return [{"pid": pid, "command": redact(commands.get(pid)), "result": result} for pid, result in results.items()]
+
+
+def session_descendants(rows, cli_pid, self_pid=None, now=None):
+    """What the hooks record for a session: descendants of the agent CLI (never the hook's own
+    chain), as {pid, ppid, pgid, start, display}. Commands are redacted before they leave."""
+    now = time.time() if now is None else now
+    self_pid = os.getpid() if self_pid is None else self_pid
+    alive = [r for r in rows if not zombie(r)]
+    by_pid = {r["pid"]: r for r in alive}
+    hook_chain = set(ancestry(self_pid, alive))
+    out = []
+    for pid in tree_pids(cli_pid, children_of(alive))[1:]:
+        if pid in hook_chain:
+            continue
+        row = by_pid[pid]
+        out.append({"pid": pid, "ppid": row["ppid"], "pgid": row["pgid"], "start": round(start_of(row, now)),
+                    "display": redact(row["command"])})
+    return out[:200]
+
+
+def hook_cli_pid(rows, ppid):
+    """The agent CLI behind a hook: its parent, or the grandparent when the parent is a shell."""
+    by_pid = {r["pid"]: r for r in rows}
+    row = by_pid.get(ppid)
+    if row and _basename((row["command"].split() or ["?"])[0]).lstrip("-") in SHELLS and row["ppid"] > 1:
+        return row["ppid"]
+    return ppid
+
+
+def orphan_cache_path(home):
+    return Path(home) / ".local" / "state" / "crow-skills" / "orphans-cache.json"
+
+
+def write_orphan_cache(home, doc):
+    """Counts only (no pid, no command): what the prompt hint needs. Failure means no cache."""
+    base = Path(os.path.realpath(home))
+    path = orphan_cache_path(base)
+    try:
+        for part in (base / ".local", base / ".local" / "state", path.parent):
+            if part.is_symlink():
+                return
+        path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+        temp = path.parent / ("." + 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": ORPHAN_CACHE_SCHEMA, "at": time.time(), "count": int(doc.get("count") or 0),
+                           "processes": int(doc.get("processes") or 0), "rssMb": float(doc.get("rssMb") or 0)}, handle)
+            os.replace(temp, path)
+        finally:
+            if os.path.lexists(temp):
+                os.unlink(temp)
+    except OSError:
+        pass
+
+
+def read_orphan_cache(home, max_age=ORPHAN_CACHE_SECONDS, now=None):
+    path = orphan_cache_path(home)
+    try:
+        if path.is_symlink() or not path.is_file() or path.stat().st_size > 4096:
+            return None
+        data = json.loads(path.read_text(encoding="utf-8"))
+        age = (now or time.time()) - float(data.get("at") or 0)
+    except (OSError, ValueError, TypeError, AttributeError):
+        return None
+    if not isinstance(data, dict) or data.get("schema") != ORPHAN_CACHE_SCHEMA or not 0 <= age <= max_age:
+        return None
+    if not all(isinstance(data.get(k), (int, float)) and not isinstance(data.get(k), bool) for k in ("count", "processes", "rssMb")):
+        return None
+    return data
+
+
+def orphan_hint(home):
+    """Suffix for the pressure hint from the last orphan scan (a file read, never a ps call)."""
+    cache = read_orphan_cache(home)
+    if not cache or cache["count"] <= 0:
+        return ""
+    return (" Órfãos de ferramentas de agente: " + str(int(cache["count"])) + " árvore(s), " + str(int(cache["processes"])) +
+            " processo(s), " + gb(cache["rssMb"]) + " GB; revise com `crow-skills resources --orphans` e limpe só o que for "
+            "órfão (nunca processos do usuário ou de sessões vivas).")
+
+
+def duration_text(seconds):
+    seconds = int(seconds or 0)
+    if seconds >= 86400:
+        return str(seconds // 86400) + "d" + (str(seconds % 86400 // 3600) + "h" if seconds % 86400 >= 3600 else "")
+    if seconds >= 3600:
+        return str(seconds // 3600) + "h" + ("%02d" % (seconds % 3600 // 60))
+    return str(seconds // 60) + "min"
+
+
+def parse_duration(text):
+    """'30m', '2h', '1d', '45s' or plain seconds -> seconds (ValueError otherwise)."""
+    match = re.fullmatch(r"\s*(\d+(?:\.\d+)?)\s*([smhd]?)\s*", str(text or ""), re.IGNORECASE)
+    if not match:
+        raise ValueError("duração inválida: use 30m, 2h, 1d ou segundos")
+    return int(float(match.group(1)) * {"": 1, "s": 1, "m": 60, "h": 3600, "d": 86400}[match.group(2).lower()])
+
+
+REASONS = {"reparented": "pai morto (reparentado ao init/launchd)", "dead-session": "sessão de agente encerrada"}
+
+
+def render_orphans(doc):
+    if not doc.get("available"):
+        return "órfãos: tabela de processos indisponível nesta plataforma."
+    if not doc["trees"] and doc.get("verified") is False:
+        lines = ["órfãos: não verificado: " + str(doc.get("unverifiedReason")) + "; processos reparentados não puderam ser "
+                 "separados de serviços do usuário e não foram listados (isso não quer dizer que não há órfãos)."]
+    elif not doc["trees"]:
+        lines = ["órfãos: nenhum processo órfão de ferramentas de agente com mais de " + duration_text(doc["olderThanSeconds"]) + "."]
+    else:
+        lines = ["órfãos de ferramentas de agente: " + str(doc["count"]) + " árvore(s), " + str(doc["processes"]) +
+                 " processo(s), " + gb(doc["rssMb"]) + " GB RSS (mais de " + duration_text(doc["olderThanSeconds"]) + ")"]
+        for tree in doc["trees"]:
+            lines.append("- " + tree["signature"] + " · " + REASONS.get(tree["reason"], tree["reason"]) + " · " +
+                         duration_text(tree["ageSeconds"]) + " · " + str(round(tree["rssMb"])) + " MB · " +
+                         str(len(tree["processes"])) + " processo(s) em " + str(tree["groups"]) + " grupo(s)")
+            for proc in tree["processes"]:
+                lines.append("    " + "  " * proc["depth"] + ("└ " if proc["depth"] else "") + str(proc["pid"]) + "  " +
+                             proc["command"] + "  (" + duration_text(proc["ageSeconds"]) + ", " + str(round(proc["rssMb"])) + " MB)")
+    if doc.get("note") and not doc.get("killed"):
+        lines.append(doc["note"])
+    for item in doc.get("killed") or []:
+        lines.append("  " + str(item["pid"]) + " " + item["command"] + ": " + item["result"])
+    if doc.get("remaining") is not None:
+        lines.append("restantes após o encerramento: " + str(doc["remaining"]) + " árvore(s)")
+    if doc.get("dryRun"):
+        lines.append("dry-run: nada foi sinalizado; --kill --yes encerra as árvores listadas.")
+    for error in doc["config"]["errors"]:
+        lines.append("config: " + error)
+    return "\n".join(lines)
+
+
 # --- presentation ---------------------------------------------------------------------------
 
 def cpu_level(data):