@andespindola/crow-skills 0.11.1 → 0.12.0

package/README.md

@@ -2,7 +2,7 @@
 
 Skills com escopo explícito, conhecimento especializado preservado e fluxos comuns reutilizáveis.
 
-**Versão 0.11.1** ([mudanças](CHANGELOG.md)): o Codex deixa de mostrar em dobro as skills que o Uniflow já projeta em `~/.codex/skills`. A 0.11.0 trouxe `crow-skills setup --yes`, que configura de uma vez todos os CLIs de agente da máquina, e `crow-skills upgrade --yes`, que atualiza tudo numa só passada; os hooks que o crow-skills grava já saem habilitados (no Codex, aprovados pelo próprio `codex app-server`, só os do crow-skills; `--no-trust` desliga) e `status`/`doctor` mostram se cada CLI vai rodá-los; a ajuda ficou curta e organizada por tarefa. A 0.10.1 passou a tratar swap e CPU como eixos de pressão no controle de recursos (swap quase cheio e carga alta reduzem agentes, jobs e workers; nenhuma recomendação cresce com a pressão), mostrou a CPU% dos CLIs de agente, trouxe `crow-skills resources --exec-prefix` para rodar jobs pesados em prioridade baixa e as regras da crow-behaviour sob pressão (reduzir já, um job pesado por vez, não repetir verificação, validação ampla no CI); os hooks do Codex vão para o `config.toml` quando o `hooks.json` é symlink. A 0.10.0 trouxe o crow-broadcast, que compartilha, de forma passiva, o que cada sessão e cada CLI (Claude Code, Codex, Gemini CLI, Antigravity, Devin, inclusive dentro do Uniflow) está fazendo nesta máquina: repositório, clone, branch, execução crow em andamento e arquivos em edição; o prompt recebe um resumo só quando outra sessão viva está no mesmo repositório, editar um arquivo que outra sessão tocou ou trocar de branch num clone em uso gera aviso (ou bloqueio, se configurado), e `crow-skills broadcast claim` reserva áreas; a crow-behaviour consulta isso antes de planejar e reserva as áreas que delega ([crow-broadcast](docs/broadcast.md)). A 0.9.0 trouxe o controle de memória da máquina: `crow-skills resources` mede memória, pressão e os CLIs de agente em execução e recomenda quantos agentes, jobs pesados e workers rodar em paralelo; a crow-behaviour consulta essa recomendação antes de cada fan-out (sob `warn` reduz, sob `critical` segue sequencial), limita workers de builds e testes, reutiliza um dev server por projeto e encerra o que abriu, e 15 especialistas que sobem processos pesados ganharam a regra correspondente; o hook de prompt e as status lines só avisam quando a máquina está sob pressão. A 0.8.0 trouxe `crow-skills mode on|off`, que liga e desliga a crow-behaviour em todas as sessões e CLIs (Claude Code, Codex, Gemini CLI, Antigravity, Devin) a partir do próximo prompt, com `/crow on|off` dentro da sessão e o indicador `▸▸ crow on` na status line; a crow-behaviour mostra o progresso como a lista de agentes do host (`● main`, `○ dono  atividade`); `crow-skills events` publica um barramento de eventos dos hooks para terminais; `crow-skills autoupdate on` atualiza o CLI e as skills gerenciadas todo dia e no login. A 0.7.1 trouxe as correções da revalidação no Codex às skills especialistas; a 0.7.0 tornou o Uniflow agente de instalação (`--agents uniflow`); a 0.6.1 passou a mostrar o progresso da crow-behaviour na própria conversa; a 0.6.0 trouxe as regras de entrega das 32 skills especialistas, a partir da [validação no Codex](docs/evaluations/2026-10-26-codex.md).
+**Versão 0.12.0** ([mudanças](CHANGELOG.md)): a crow-behaviour passa a encerrar a árvore inteira de todo processo que a execução inicia (com timeout, registro no ledger e verificação no fim) e `crow-skills resources --orphans` encontra e, com `--kill`, encerra só o que ficou órfão de ferramentas de agente. A 0.11.1 fez o Codex deixar de mostrar em dobro as skills que o Uniflow já projeta em `~/.codex/skills`. A 0.11.0 trouxe `crow-skills setup --yes`, que configura de uma vez todos os CLIs de agente da máquina, e `crow-skills upgrade --yes`, que atualiza tudo numa só passada; os hooks que o crow-skills grava já saem habilitados (no Codex, aprovados pelo próprio `codex app-server`, só os do crow-skills; `--no-trust` desliga) e `status`/`doctor` mostram se cada CLI vai rodá-los; a ajuda ficou curta e organizada por tarefa. A 0.10.1 passou a tratar swap e CPU como eixos de pressão no controle de recursos (swap quase cheio e carga alta reduzem agentes, jobs e workers; nenhuma recomendação cresce com a pressão), mostrou a CPU% dos CLIs de agente, trouxe `crow-skills resources --exec-prefix` para rodar jobs pesados em prioridade baixa e as regras da crow-behaviour sob pressão (reduzir já, um job pesado por vez, não repetir verificação, validação ampla no CI); os hooks do Codex vão para o `config.toml` quando o `hooks.json` é symlink. A 0.10.0 trouxe o crow-broadcast, que compartilha, de forma passiva, o que cada sessão e cada CLI (Claude Code, Codex, Gemini CLI, Antigravity, Devin, inclusive dentro do Uniflow) está fazendo nesta máquina: repositório, clone, branch, execução crow em andamento e arquivos em edição; o prompt recebe um resumo só quando outra sessão viva está no mesmo repositório, editar um arquivo que outra sessão tocou ou trocar de branch num clone em uso gera aviso (ou bloqueio, se configurado), e `crow-skills broadcast claim` reserva áreas; a crow-behaviour consulta isso antes de planejar e reserva as áreas que delega ([crow-broadcast](docs/broadcast.md)). A 0.9.0 trouxe o controle de memória da máquina: `crow-skills resources` mede memória, pressão e os CLIs de agente em execução e recomenda quantos agentes, jobs pesados e workers rodar em paralelo; a crow-behaviour consulta essa recomendação antes de cada fan-out (sob `warn` reduz, sob `critical` segue sequencial), limita workers de builds e testes, reutiliza um dev server por projeto e encerra o que abriu, e 15 especialistas que sobem processos pesados ganharam a regra correspondente; o hook de prompt e as status lines só avisam quando a máquina está sob pressão. A 0.8.0 trouxe `crow-skills mode on|off`, que liga e desliga a crow-behaviour em todas as sessões e CLIs (Claude Code, Codex, Gemini CLI, Antigravity, Devin) a partir do próximo prompt, com `/crow on|off` dentro da sessão e o indicador `▸▸ crow on` na status line; a crow-behaviour mostra o progresso como a lista de agentes do host (`● main`, `○ dono  atividade`); `crow-skills events` publica um barramento de eventos dos hooks para terminais; `crow-skills autoupdate on` atualiza o CLI e as skills gerenciadas todo dia e no login. A 0.7.1 trouxe as correções da revalidação no Codex às skills especialistas; a 0.7.0 tornou o Uniflow agente de instalação (`--agents uniflow`); a 0.6.1 passou a mostrar o progresso da crow-behaviour na própria conversa; a 0.6.0 trouxe as regras de entrega das 32 skills especialistas, a partir da [validação no Codex](docs/evaluations/2026-10-26-codex.md).
 
 **Reconstrução em andamento.** A primeira versão com 32 contratos genéricos não atende à preservação de capacidades solicitada. Não use esse número nem o mapeamento por categoria como prova de substituição das originais. A revisão passa a abranger cada definição e seus recursos, modos e dependências, sem número fixo de skills ou limite artificial de linhas. Veja [critérios e progresso](docs/reconstruction.md).
 
@@ -42,7 +42,7 @@ Exemplos:
 O pacote de cada skill é somente sua pasta em `skills/`. O [CLI crow-skills](docs/cli.md) instala cópias completas e versionadas em agentes/escopos explícitos, com preview, saída JSON, detecção de conflitos e recuperação. Requer Python 3.10+; Git para fontes em clone, Node 18+ para o launcher npm; mutações em macOS/Linux. A distribuição npm privada `@andespindola/crow-skills` inclui um snapshot completo das skills, sem clone ou hooks que as instalem automaticamente. No [Uniflow](docs/cli.md#uniflow), `--agents uniflow --global` grava as skills no store dele (`~/.config/uniflow/skills`), sem tocar no resto da configuração. Em `--global`, instalar a crow-behaviour também grava o guia aditivo do agente (claude, codex, gemini, devin) para usar as skills; `--no-guide` desliga. As integrações de interface (status lines do Claude Code, do Codex e do Antigravity, hooks do modo crow em cada CLI, comando `/crow`, segmento tmux) seguem o mesmo fluxo, preservando a configuração existente; `--no-integrations` desliga. O [barramento de eventos](docs/events.md) e a atualização automática (`crow-skills autoupdate on`) estão no [CLI](docs/cli.md).
 
 ```sh
-npm install -g @andespindola/crow-skills@0.11.1
+npm install -g @andespindola/crow-skills@0.12.0
 crow-skills mode
 crow-skills progress
 ./bin/crow-skills list

package/crow_skills/__init__.py

@@ -1,3 +1,3 @@
 """Portable, local-first installer for the crow-skills catalogue."""
 
-__version__ = "0.11.1"
+__version__ = "0.12.0"

package/crow_skills/broadcast.py

@@ -26,6 +26,10 @@ Text written by other agents (ledger titles, unit titles, claim notes) is data:
 control and format characters are removed, length is capped, quotes are
 neutralised and the block says it is not an instruction.
 
+Session processes (crow-procs/1): on Stop and SessionEnd the hook records the
+live descendants of the session's CLI (pid, start, redacted command) so an
+orphan check can attribute leftovers to a dead session.
+
 Single machine only: state lives under ~/.local/state/crow-skills; nothing is
 sent anywhere. Config: ~/.config/crow-skills/broadcast.json (edited by the user).
 """
@@ -457,10 +461,18 @@ def pid_alive(pid):
         return None  # exists but not ours, or unknown: fall back to the heartbeat
 
 
-def fold(snap, event, touched=(), now=None, ppid=None):
-    """Update the session snapshot's presence object (in place) for one event."""
+def fold(snap, event, touched=(), now=None, ppid=None, cli_pid=None):
+    """Update the session snapshot's presence object (in place) for one event.
+
+    cli_pid: the agent CLI resolved from a process table (Stop/SessionEnd); once known and alive it
+    is the presence pid, so a hook started through a transient ``sh -c`` does not replace it."""
     now = now or time.time()
     presence = snap.get("presence") if isinstance(snap.get("presence"), dict) else {}
+    if cli_pid:
+        presence["cliPid"] = cli_pid
+    known = presence.get("cliPid")
+    if known and pid_alive(known) is not False:
+        ppid = known
     presence["schema"] = PRESENCE_SCHEMA
     cwd = snap.get("cwd")
     repo = presence.get("repo") if isinstance(presence.get("repo"), dict) else None
@@ -764,6 +776,234 @@ def prune_claims(home, now=None):
             write_json(path, {"schema": CLAIMS_SCHEMA, "claims": kept})
 
 
+# --- session processes (crow-procs/1) ---------------------------------------------------------
+#
+# On Stop and SessionEnd the hook records the live descendants of the session's CLI (pid, start
+# time and a redacted command: executable plus package/script name, never arguments), so a later
+# orphan check can attribute a leftover process to a session that is now dead even when it was
+# not reparented to init/launchd (a subreaper such as tmux or systemd --user adopted it).
+
+PROCS_SCHEMA = "crow-procs/1"
+PROCS_TTL = 14 * 24 * 3600
+MAX_PROCS = 200
+KEY = re.compile(r"[0-9a-f]{20}")
+
+
+def procs_dir(home):
+    return state_dir(home) / "procs"
+
+
+def _proc_entry(item):
+    if not isinstance(item, dict):
+        return None
+    pid, start, display = item.get("pid"), item.get("start"), item.get("display")
+    if not isinstance(pid, int) or isinstance(pid, bool) or pid <= 1 or not isinstance(start, (int, float)) \
+            or isinstance(start, bool) or not isinstance(display, str):
+        return None
+    entry = {"pid": pid, "start": int(start), "display": clean(display, 80)}
+    for field in ("ppid", "pgid"):
+        if isinstance(item.get(field), int) and not isinstance(item.get(field), bool):
+            entry[field] = item[field]
+    return entry
+
+
+def record_processes(home, key, host, cli_pid, cli_start, processes, now=None):
+    """Write the session's descendants (only when the set changed); returns True when written."""
+    if not isinstance(key, str) or not KEY.fullmatch(key) or not isinstance(cli_pid, int) or cli_pid <= 1:
+        return False
+    now = now or time.time()
+    entries = [e for e in (_proc_entry(p) for p in processes or []) if e][:MAX_PROCS]
+    path = procs_dir(home) / (key + ".json")
+    old = read_json(path, 256 * 1024)
+    same = isinstance(old, dict) and old.get("cliPid") == cli_pid and \
+        sorted((p.get("pid"), p.get("start")) for p in old.get("processes") or [] if isinstance(p, dict)) == \
+        sorted((e["pid"], e["start"]) for e in entries)
+    if same:
+        return False
+    write_json(path, {"schema": PROCS_SCHEMA, "key": key, "host": clean(host, 20), "cliPid": cli_pid,
+                      "cliStart": int(cli_start) if isinstance(cli_start, (int, float)) else None,
+                      "recordedAt": now_iso(now), "processes": entries})
+    return True
+
+
+def process_records(home, now=None):
+    """Recorded descendants of every session (validated), newest files only (PROCS_TTL)."""
+    now = now or time.time()
+    directory = procs_dir(home)
+    result = []
+    try:
+        if directory.is_symlink() or not directory.is_dir():
+            return result
+        entries = list(os.scandir(directory))
+    except OSError:
+        return result
+    for entry in entries:
+        if not entry.name.endswith(".json") or not KEY.fullmatch(entry.name[:-5]):
+            continue
+        try:
+            if now - entry.stat(follow_symlinks=False).st_mtime > PROCS_TTL:
+                continue
+        except OSError:
+            continue
+        data = read_json(entry.path, 256 * 1024)
+        if not isinstance(data, dict) or data.get("schema") != PROCS_SCHEMA or data.get("key") != entry.name[:-5]:
+            continue
+        cli = data.get("cliPid")
+        if not isinstance(cli, int) or isinstance(cli, bool):
+            continue
+        result.append({"key": data["key"], "host": data.get("host"), "cliPid": cli,
+                       "cliStart": data.get("cliStart") if isinstance(data.get("cliStart"), (int, float)) else None,
+                       "processes": [e for e in (_proc_entry(p) for p in data.get("processes") or []) if e]})
+    return result
+
+
+LEDGER_FRESH = 2 * 3600  # a running ledger touched this recently is live (crow-skills progress uses the same window)
+MAX_LEDGER_BYTES = 1024 * 1024
+
+
+REGISTRATION_SCHEMA = "crow-registration/1"
+REGISTRATION_TTL = 14 * 24 * 3600
+
+
+def registrations_dir(home):
+    """Where crow_ledger.py ``proc add`` writes a cwd-independent pointer to each registration, so
+    an orphan check from any directory or repository sees every live run's processes."""
+    return Path(home) / ".local" / "state" / "crow-skills" / "registrations"
+
+
+def _number(value):
+    return isinstance(value, (int, float)) and not isinstance(value, bool)
+
+
+def _ledger_entry(item, cli_pid=None, cli_start=None, fresh=True):
+    """A protectable registration: {pid, start, cliPid?, cliStart?, fresh}, or None."""
+    if not isinstance(item, dict) or item.get("status", "running") not in ("running", "survived") \
+            or not isinstance(item.get("pid"), int) or isinstance(item.get("pid"), bool) or not _number(item.get("start")):
+        return None
+    entry = {"pid": item["pid"], "start": item["start"], "fresh": fresh}
+    cli, cli_at = item.get("cliPid", cli_pid), item.get("cliStart", cli_start)
+    if isinstance(cli, int) and not isinstance(cli, bool) and cli > 1:
+        entry["cliPid"] = cli
+        if _number(cli_at):
+            entry["cliStart"] = cli_at
+    return entry
+
+
+def ledger_processes(home, cwds=(), live_keys=(), now=None, env=None):
+    """Processes registered as running (``crow_ledger.py proc add``) by running crow-behaviour
+    runs: [{pid, start, cliPid?, cliStart?, fresh}]. Sources: the registration pointers under the
+    user state directory (any repository), $CROW_LEDGER, <dir>/.crow/runs from each given
+    directory up to the root, and ~/.crow/runs. The caller protects an entry while its agent CLI
+    (cliPid, same start) is alive; without a known CLI, while ``fresh`` (the ledger was updated
+    within LEDGER_FRESH or its host session is live). Stale or corrupt files are ignored."""
+    now = now or time.time()
+    env = os.environ if env is None else env
+    files, dirs = [], []
+    if env.get("CROW_LEDGER"):
+        files.append(Path(env["CROW_LEDGER"]).expanduser())
+    try:
+        directory = registrations_dir(home)
+        if not directory.is_symlink() and directory.is_dir():
+            for item in os.scandir(directory):
+                if item.name.endswith(".json"):
+                    data = read_json(item.path, 64 * 1024)
+                    if isinstance(data, dict) and data.get("schema") == REGISTRATION_SCHEMA and isinstance(data.get("ledger"), str):
+                        files.append(Path(data["ledger"]))
+    except OSError:
+        pass
+    for cwd in cwds:
+        if not cwd:
+            continue
+        current = Path(cwd)
+        for directory in (current, *current.parents):
+            dirs.append(directory / ".crow" / "runs")
+    dirs.append(Path(home) / ".crow" / "runs")
+    seen = set()
+    for directory in dirs:
+        if str(directory) in seen:
+            continue
+        seen.add(str(directory))
+        try:
+            if directory.is_symlink() or not directory.is_dir():
+                continue
+            files += [Path(e.path) for e in os.scandir(directory) if e.name.endswith(".json")]
+        except OSError:
+            continue
+    result, read, keys = [], set(), set()
+    for path in files:
+        if str(path) in read:
+            continue
+        read.add(str(path))
+        try:
+            mtime = path.stat().st_mtime
+        except OSError:
+            continue
+        data = read_json(path, MAX_LEDGER_BYTES)
+        if not isinstance(data, dict) or data.get("schema") != "crow-run/1" or data.get("status") != "running":
+            continue
+        session = data.get("session") if isinstance(data.get("session"), dict) else {}
+        key = session_key(session.get("host"), session.get("id"), None) if session.get("id") else None
+        fresh = now - mtime <= LEDGER_FRESH or key in live_keys
+        for item in data.get("processes") or []:
+            entry = _ledger_entry(item, fresh=fresh)
+            if entry and (entry["pid"], entry["start"]) not in keys:
+                keys.add((entry["pid"], entry["start"]))
+                result.append(entry)
+    return result  # a pointer whose ledger is gone, unreadable or finished protects nothing
+
+
+def prune_registrations(home, now=None):
+    """Drop pointers whose ledger is gone or finished, or older than REGISTRATION_TTL; quiet on failure."""
+    now = now or time.time()
+    directory = registrations_dir(home)
+    try:
+        if directory.is_symlink() or not directory.is_dir():
+            return
+        for item in os.scandir(directory):
+            if not item.name.endswith(".json"):
+                continue
+            data = read_json(item.path, 64 * 1024)
+            ledger = read_json(data["ledger"], MAX_LEDGER_BYTES) if isinstance(data, dict) and isinstance(data.get("ledger"), str) else None
+            if not isinstance(ledger, dict) or ledger.get("status") != "running" or \
+                    now - item.stat(follow_symlinks=False).st_mtime > REGISTRATION_TTL:
+                os.unlink(item.path)
+    except OSError:
+        pass
+
+
+def process_context(home, cfg=None, now=None, cwd=None):
+    """What an orphan check needs from crow-broadcast: live session keys, the CLI pids of live
+    sessions (their trees are protected), the processes recorded per session, and the processes
+    live crow-behaviour runs registered (also protected)."""
+    sessions = live_sessions(home, cfg, now)
+    pids = set()
+    for snap in sessions:
+        presence = presence_of(snap)
+        for field in ("pid", "cliPid"):
+            pid = presence.get(field)
+            if isinstance(pid, int) and not isinstance(pid, bool) and pid > 1:
+                pids.add(pid)
+    keys = {s["key"] for s in sessions}
+    cwds = [cwd or os.getcwd()] + [s.get("cwd") for s in sessions if isinstance(s.get("cwd"), str)]
+    return {"liveKeys": keys, "livePids": pids, "records": process_records(home, now),
+            "ledgerProcesses": ledger_processes(home, cwds, keys, now)}
+
+
+def prune_processes(home, now=None):
+    """Drop records older than PROCS_TTL and stale registration pointers (called on SessionStart)."""
+    now = now or time.time()
+    prune_registrations(home, now)
+    directory = procs_dir(home)
+    try:
+        if directory.is_symlink() or not directory.is_dir():
+            return
+        for entry in os.scandir(directory):
+            if entry.name.endswith(".json") and now - entry.stat(follow_symlinks=False).st_mtime > PROCS_TTL:
+                os.unlink(entry.path)
+    except OSError:
+        pass
+
+
 def git_branch(root):
     dot = Path(root) / ".git"
     try:

package/crow_skills/cli.py

@@ -71,8 +71,9 @@ COMMANDS = {
                ["crow-skills events", "crow-skills events tail --limit 20", "crow-skills events tail --follow"]),
     "broadcast": ("Sessões vivas dos CLIs, arquivos em edição, conflitos e reservas.",
                   ["crow-skills broadcast", "crow-skills broadcast claim src/api --ttl 30m", "crow-skills broadcast release --all"]),
-    "resources": ("Memória, pressão, agentes em execução e paralelismo recomendado (somente leitura).",
-                  ["crow-skills resources", "crow-skills resources --exec-prefix"]),
+    "resources": ("Memória, pressão, agentes em execução, paralelismo recomendado e processos órfãos de ferramentas de agente.",
+                  ["crow-skills resources", "crow-skills resources --exec-prefix", "crow-skills resources --orphans",
+                   "crow-skills resources --orphans --kill --dry-run", "crow-skills resources --orphans --kill --yes"]),
     "autoupdate": ("Agenda a atualização diária e no login (o mesmo fluxo de upgrade) ou roda agora.",
                    ["crow-skills autoupdate on --yes", "crow-skills autoupdate status", "crow-skills autoupdate run --yes"]),
     "rollback": ("Desfaz uma transação concluída (skills e o guia ligado a ela).", ["crow-skills rollback --transaction <id> --yes"]),
@@ -199,6 +200,11 @@ def parser():
     child.add_argument("--no-processes", action="store_true", help="Não varrer os processos dos CLIs de agente (mais rápido)")
     child.add_argument("--exec-prefix", action="store_true",
                        help="Só imprimir o prefixo que roda um job pesado em prioridade baixa neste sistema (taskpolicy/nice/ionice/start /low)")
+    child.add_argument("--orphans", action="store_true",
+                       help="Listar processos órfãos de ferramentas de agente (árvore, idade, RSS); somente leitura sem --kill")
+    child.add_argument("--kill", action="store_true",
+                       help="Com --orphans: encerrar as árvores órfãs (TERM, carência, KILL só se preciso); exige --yes ou confirmação")
+    child.add_argument("--older-than", help="Com --orphans: idade mínima da raiz (ex.: 30m, 2h, 1d; padrão 30m ou o do resources.json)")
     child = command_parser(sub, "autoupdate", [common])
     child.add_argument("action", choices=("on", "off", "status", "run"))
     child.add_argument("--git-pull", action="store_true", help="on: também atualizar um checkout git limpo em main/master (git pull --ff-only)")
@@ -572,6 +578,52 @@ def public(view):
     return {k: v for k, v in view.items() if not k.startswith("_")}
 
 
+def orphans_command(args, home, interactive):
+    """resources --orphans [--kill]: read-only listing; a kill needs --yes or a TTY confirmation."""
+    if not args.orphans:
+        raise CrowError("usage", "--kill e --older-than só valem com --orphans.")
+    older = None
+    if args.older_than is not None:
+        try:
+            older = resources.parse_duration(args.older_than)
+        except ValueError as exc:
+            raise CrowError("usage", str(exc)) from None
+    try:
+        context = broadcast.process_context(home)
+    except (OSError, ValueError, TypeError, KeyError):
+        context = None  # without crow-broadcast state only reparented roots count; live CLIs still protect their trees
+    doc = resources.orphan_scan(home, context=context, older_than=older)
+    if older is None and doc["available"]:
+        resources.write_orphan_cache(home, doc)
+    dry = getattr(args, "dry_run", False)
+    if args.kill and doc["trees"]:
+        entries = [e for tree in doc["trees"] for e in tree["_entries"]]
+        if dry:
+            doc["dryRun"] = True
+            doc["wouldKill"] = [{"pid": p["pid"], "command": p["command"]} for tree in doc["trees"] for p in tree["processes"]]
+        else:
+            if not getattr(args, "yes", False):
+                if not interactive:
+                    raise CrowError("confirmation_required", "Use --dry-run para ver o que seria encerrado ou --yes para encerrar as árvores órfãs.")
+                print(resources.render_orphans(resources.public_orphans(doc)), file=sys.stderr)
+                if prompt("Encerrar estas árvores de processos? [s/N]").lower() not in ("s", "sim", "y", "yes"):
+                    raise CrowError("cancelled", "Operação cancelada; nenhum processo sinalizado.")
+            if not resources.signals_allowed():
+                raise CrowError("usage", "CROW_PS_FIXTURE definido: uma tabela de teste nunca é sinalizada.")
+            doc["killed"] = resources.kill_trees(entries, grace=doc["settings"]["graceSeconds"])
+            doc["survivors"] = sum(1 for item in doc["killed"] if item["result"] == "survived")
+            after = resources.orphan_scan(home, context=context, older_than=older)  # verification, and a fresh count
+            doc["remaining"] = after["count"]
+            if older is None and after["available"]:
+                resources.write_orphan_cache(home, after)
+    elif args.kill and dry:
+        doc["dryRun"] = True
+        doc["wouldKill"] = []
+    data = resources.public_orphans(doc)
+    data["text"] = resources.render_orphans(data)
+    return data
+
+
 def broadcast_command(args, home):
     action = args.action
     cwd = os.path.abspath(getattr(args, "cwd", None) or os.getcwd())
@@ -871,6 +923,8 @@ def run(args):
     if args.command == "resources":
         if args.exec_prefix:
             return resources.exec_prefix_data()
+        if args.orphans or args.kill or args.older_than is not None:
+            return orphans_command(args, home, interactive)
         data = resources.probe(home, processes=not args.no_processes)
         data["text"] = resources.render(data)
         return data

package/crow_skills/hook.py

@@ -27,6 +27,12 @@ live sessions in the same repository, only when there are any; ``--check``
 live session on the same file or clone without writing anything.
 
   crow_hook.py hook --host HOST --event PreToolUse --check [--home DIR]
+
+On Stop and SessionEnd the hook also records the live descendants of the
+session's CLI (pid, start time, executable plus package/script name; never
+arguments) in the crow-broadcast state, and at most every 10 minutes refreshes
+the orphan count (crow-skills resources --orphans) that the memory line cites
+under pressure: one ps call on those events, none on prompts.
 """
 from datetime import datetime, timezone
 import hashlib
@@ -236,11 +242,48 @@ def resource_hint(home):
     if module is None:
         return None
     try:
-        return module.hint(module.probe(home, processes=False, use_cache=True))
+        text = module.hint(module.probe(home, processes=False, use_cache=True))
+        if text and hasattr(module, "orphan_hint"):
+            text += module.orphan_hint(home)  # last orphan scan, a file read: no ps call per prompt
+        return text
     except Exception:  # noqa: BLE001
         return None
 
 
+STOP_EVENTS = ("Stop", "AfterAgent", "PostInvocation", "SessionEnd")
+ORPHAN_REFRESH = 600  # seconds: a Stop event rescans orphans at most this often (it already has the table)
+
+
+def record_processes(home, host, event, ppid=None):
+    """Stop/SessionEnd: record the CLI's live descendants in crow-broadcast state (pid, start,
+    redacted command), so a later orphan check can attribute leftovers to a dead session; and
+    refresh the orphan count the pressure hint reads. One ps call; never raises."""
+    module, probe = broadcast_module(), resources_module()
+    if module is None or probe is None or not hasattr(probe, "read_table") or not hasattr(module, "record_processes"):
+        return None
+    try:
+        cfg = module.config(home)
+        if not cfg["enabled"]:
+            return None
+        rows = probe.read_table()
+        if not rows:
+            return None
+        now = time.time()
+        cli = probe.hook_cli_pid(rows, os.getppid() if ppid is None else ppid)
+        row = next((r for r in rows if r["pid"] == cli), None)
+        if row is None or cli <= 1:
+            return None
+        key = session_key(host, event.get("session"), event.get("cwd"))
+        module.record_processes(home, key, host, cli, probe.start_of(row, now),
+                                probe.session_descendants(rows, cli, now=now), now)
+        if probe.read_orphan_cache(home, max_age=ORPHAN_REFRESH) is None:
+            doc = probe.orphan_scan(home, rows=rows, context=module.process_context(home, cfg, now, event.get("cwd")), now=now)
+            probe.write_orphan_cache(home, doc)
+        return cli
+    except Exception:  # noqa: BLE001 - housekeeping never breaks the event
+        return None
+
+
 # --- event bus ----------------------------------------------------------------------------
 
 def append_event(home, event):
@@ -373,9 +416,12 @@ def update_session(home, event, extra=None, fallback_cwd=None, presence=None):
         if extra:
             snap.update(extra)
         if presence:
-            module, touched, ppid = presence
+            module, touched, ppid = presence[:3]
             try:
-                module.fold(snap, event, touched, ppid=ppid)
+                if len(presence) > 3:  # (…, cli pid resolved from the process table on Stop/SessionEnd)
+                    module.fold(snap, event, touched, ppid=ppid, cli_pid=presence[3])
+                else:
+                    module.fold(snap, event, touched, ppid=ppid)
             except Exception:  # noqa: BLE001 - presence is best effort
                 pass
         write_json(path, snap)
@@ -696,6 +742,15 @@ def handle(host, raw, payload, home, env=None, check=False):
         except Exception:  # noqa: BLE001 - the broadcast never breaks the event
             module, presence = None, None
     stamped, snap = record(home, dict(event, mode=current["mode"]), snapshot=True, fallback_cwd=process_cwd(), presence=presence)
+    if raw in STOP_EVENTS:
+        cli = record_processes(home, host, event)
+        if cli and snap is not None:
+            bmod = broadcast_module()
+            if bmod is not None:
+                try:  # the resolved CLI pid becomes the presence pid (a hook's sh -c parent is transient)
+                    update_session(home, dict(stamped, event="other"), presence=(bmod, [], None, cli))
+                except Exception:  # noqa: BLE001
+                    pass
     if module is not None and host in SYNC_TOOL_HOSTS:
         if raw in TOOL_START_EVENTS and (touched or tree or checked):
             return broadcast_check(host, raw, home, module, snap, checked or touched, tree)
@@ -848,6 +903,8 @@ def run_main(args):
             if module is not None:
                 try:
                     module.prune_claims(home)
+                    if hasattr(module, "prune_processes"):
+                        module.prune_processes(home)
                 except Exception:  # noqa: BLE001 - pruning is housekeeping; the output already went out
                     pass
     except Exception:  # noqa: BLE001 - a hook must never break the agent