@andespindola/crow-skills 0.11.0 → 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.0** ([mudanças](CHANGELOG.md)): `crow-skills setup --yes` configura de uma vez todos os CLIs de agente da máquina e `crow-skills upgrade --yes` 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.0
+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.0"
+__version__ = "0.12.0"

package/crow_skills/autoupdate.py

@@ -305,6 +305,60 @@ def preview_self(install, git_pull):
     return {"kind": "unknown", "result": "skipped", "reason": "instalação não reconhecida (brew, npm ou checkout git)"}
 
 
+def broken_projections(agent, home, store, rows):
+    """Uniflow links of this CLI whose store entry was edited or lost files: the CLI may not load them, so
+    upgrade reports them as needing the user (same as setup), with the command that restores the store."""
+    from .guide import broken_fix, store_broken
+    names = set()
+    if any(r["status"] == "uniflow_link" for r in rows):
+        bad = store_broken(home, store)
+        names |= {r["name"] for r in rows if r["status"] == "uniflow_link" and r["name"] in bad}
+    if agent == "codex":
+        from . import projection
+        names |= {n for n, kind in projection.links(home, store).items() if kind == "modified"}
+    return [{"name": n, "status": "uniflow_link_modified", "fix": broken_fix(n)} for n in sorted(names)]
+
+
+def reinstall_behaviour(home, entry, dry_run, trust):
+    """Codex without a working crow-behaviour (its projection is broken, no native copy): install it natively,
+    as setup does, so the guide and hooks keep a coordinator to point to."""
+    from .cli import parser, run as cli_run
+    argv = ["install", "crow-behaviour", "--agents", "codex", "--global", "--json", "--home", str(home),
+            "--dry-run" if dry_run else "--yes"]
+    if not trust:
+        argv.append("--no-trust")
+    data = cli_run(parser().parse_args(argv))
+    if any(c["name"] == "crow-behaviour" and c["action"] != "unchanged" for c in data["changes"]):
+        entry["updated"].append("crow-behaviour")
+        entry["transaction"] = data.get("transaction")
+
+
+def codex_duplicates(home, store, entry, names, dry_run):
+    """Codex sees Uniflow's links in ~/.codex/skills: those names are not updated natively, and intact managed
+    native copies of them are removed through uninstall (backup, transaction). Returns the names to update."""
+    from . import projection
+    from .cli import parser, run as cli_run
+    seen = projection.projected("codex", home, store)
+    if not seen:
+        return names
+    dupes = projection.duplicates(home, store)
+    entry["via_uniflow"] = sorted(set(entry["via_uniflow"]) | seen)
+    entry["kept"] = [k for k in entry["kept"] if k["name"] not in seen]
+    entry["kept"] += [{"name": n, "status": "duplicate_modified"} for n in dupes["modified"]]
+    entry["kept"] += [{"name": n, "status": "duplicate_shared"} for n in dupes["shared"]]
+    if dupes["remove"]:
+        argv = ["uninstall", *dupes["remove"], "--agents", "codex", "--global", "--json", "--home", str(home),
+                "--dry-run" if dry_run else "--yes", "--no-integrations"]
+        try:
+            data = cli_run(parser().parse_args(argv))
+            entry["removed"] = [{"name": c["name"], "reason": "removida: duplicava a projeção do Uniflow"}
+                                for c in data["changes"] if c["action"] != "unchanged"]
+            entry["removal_transaction"] = data.get("transaction")
+        except CrowError as exc:
+            entry["error"] = {"code": exc.code, "message": str(exc)}
+    return [n for n in names if n not in seen]
+
+
 def skills_update(home, trust=True, dry_run=False):
     """update --global for every agent with managed installs; modified skills are kept and reported.
 
@@ -334,17 +388,23 @@ def skills_update(home, trust=True, dry_run=False):
         from .guide import store_managed
         store_ok = store_managed(home, store) if any(r["status"] == "uniflow_link" for r in rows) else set()
         projected = sorted(r["name"] for r in rows if r["status"] == "uniflow_link" and r["name"] in store_ok)
+        if agent == "codex":
+            from . import projection
+            projected = sorted(set(projected) | projection.projected("codex", home, store))  # ~/.codex/skills links
+        broken = broken_projections(agent, home, store, rows)
         rows = [r for r in rows if r["name"] and r["revision"]]
         if not rows:
-            if projected:
+            if projected or broken:
                 # Every crow skill here comes from Uniflow's store (updated as agent uniflow): only the guide,
                 # integrations and hooks of this CLI are refreshed.
                 from . import machine
-                entry = {"agent": agent, "target": target["path"], "updated": [], "unchanged": 0, "kept": [], "error": None,
+                entry = {"agent": agent, "target": target["path"], "updated": [], "unchanged": 0, "kept": list(broken), "error": None,
                          "via_uniflow": projected}
                 if dry_run:
                     entry["dry_run"] = True
                 try:
+                    if agent == "codex" and "crow-behaviour" in [k["name"] for k in broken]:
+                        reinstall_behaviour(home, entry, dry_run, trust)
                     extras = machine.refresh_extras(agent, home, dry_run, trust)
                     entry["guides"] = (extras.get("guides") or {}).get("transaction")
                 except CrowError as exc:
@@ -362,10 +422,23 @@ def skills_update(home, trust=True, dry_run=False):
                 kept.append({"name": r["name"], "status": "other_origin"})  # update --source or install switches it
             else:
                 names.append(r["name"])
-        entry = {"agent": agent, "target": target["path"], "updated": [], "unchanged": 0, "kept": kept, "error": None,
-                 "via_uniflow": projected}
+        entry = {"agent": agent, "target": target["path"], "updated": [], "unchanged": 0, "kept": kept + list(broken),
+                 "error": None, "via_uniflow": projected}
         if dry_run:
             entry["dry_run"] = True
+        if agent == "codex":
+            names = codex_duplicates(home, store, entry, names, dry_run)
+            if "crow-behaviour" in [k["name"] for k in broken] and "crow-behaviour" not in [r["name"] for r in rows]:
+                try:
+                    reinstall_behaviour(home, entry, dry_run, trust)
+                except CrowError as exc:
+                    entry["error"] = {"code": exc.code, "message": str(exc)}
+            if not names and not entry.get("error"):
+                from . import machine
+                try:
+                    machine.refresh_extras(agent, home, dry_run, trust)
+                except CrowError as exc:
+                    entry["error"] = {"code": exc.code, "message": str(exc)}
         if names:
             try:
                 argv = ["update", *names, "--agents", agent, "--global", "--dry-run" if dry_run else "--yes", "--json",

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

@@ -14,6 +14,7 @@ from . import guide
 from . import hook
 from . import integrations
 from . import progress
+from . import projection
 from . import resources
 from . import machine
 from . import ui
@@ -70,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"]),
@@ -198,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)")
@@ -332,6 +339,7 @@ def guide_sync(args, home, store, command, targets, plan, source):
         if agent not in selected and not (record and path in touched):
             continue
         added, removed = touched.get(path, (set(), set()))
+        removed = removed - projection.projected(agent, home, store)  # still provided by Uniflow's projection
         after = sorted((set(guide.managed_skills(agent, home, store)) | added) - removed)
         if mech["kind"] == "toml" and guide.tomllib is None:
             report["skipped"].append({"agent": agent, "reason": "Python 3.11+ (tomllib) é necessário para editar config.toml; guia não alterado."})
@@ -387,6 +395,7 @@ def behaviour_agents(home, store, plan=None):
         path = os.path.abspath(destinations(agent, home)[0]["path"])
         added, removed = touched.get(path, (set(), set()))
         try:
+            removed = removed - projection.projected(agent, home, store)
             managed = set(guide.managed_skills(agent, home, store))
         except CrowError:
             # An unreadable skills root (e.g. a dotfiles symlink) holds nothing this CLI manages;
@@ -569,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())
@@ -744,14 +799,43 @@ def pick(source):
     return names, ",".join(chosen_groups) or None
 
 
+def codex_projection_split(home, store, targets, names):
+    """The user-scope codex target and which of the names Codex already sees via Uniflow (install skips them)."""
+    target = next((t for t in targets if projection.native_target("codex", t, home)), None)
+    if target is None or set(target["agents"]) - {"codex"}:
+        return None  # --agents shared: other hosts read that dir without Uniflow's codex projection
+    projected = projection.projected("codex", home, store)
+    if not projected:
+        return None
+    dupes = projection.duplicates(home, store)
+    return {"target": target, "skip": set(names) & projected,
+            "duplicates": sorted(set(dupes["remove"]) | set(dupes["modified"]))}
+
+
+def merge_plans(plans):
+    merged = {"before": {}, "after": {}, "items": [], "packages": {}, "changes": []}
+    for plan in plans:
+        merged["before"].update(plan["before"])
+        merged["after"].update(plan["after"])
+        merged["items"] += plan["items"]
+        merged["packages"].update(plan["packages"])
+        merged["changes"] += plan["changes"]
+    return merged
+
+
 def unmanaged_projections(store, home, rows):
     """A Uniflow link to a store entry crow-skills does not manage is not an install (same rule as setup)."""
     if not any(r["status"] == "uniflow_link" for r in rows):
         return rows
     managed = guide.store_managed(home, store)
     disabled = machine.store_disabled(home, store)
+    broken = guide.store_broken(home, store)
     for row in rows:
-        if row["status"] == "uniflow_link" and row["name"] in disabled:
+        if row["status"] == "uniflow_link" and row["name"] in broken:
+            # The store entry this link resolves to was edited or lost files: not a working install.
+            row.update(status="modified", projection="uniflow_link_modified",
+                       note=guide.BROKEN_REASON[0].upper() + guide.BROKEN_REASON[1:] + ". Para corrigir: " + guide.broken_fix(row["name"]))
+        elif row["status"] == "uniflow_link" and row["name"] in disabled:
             # Managed by crow-skills but disabled by Uniflow: reported as such, never as unmanaged (no --replace).
             row.update(status="disabled", projection="uniflow_link_disabled",
                        note="Desabilitada no Uniflow (SKILL.md.disabled no store); reabilite no Uniflow para usar.")
@@ -839,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
@@ -859,6 +945,17 @@ def run(args):
         result = {"installations": rows, "guides": guides, "integrations": ui, "pending_transactions": pending,
                   "mode": hook.read_mode(home), "activation_verified": False,
                   "reload_hint": "Peça ao host para recarregar/listar skills; reinicie a sessão se necessário."}
+        if any(projection.native_target("codex", t, home) for t in targets):
+            rows += projection.status_rows(home, store, rows)
+            dupes = projection.duplicates(home, store)
+            names_ = dupes["remove"] + dupes["modified"] + dupes["shared"]
+            if names_:
+                # A warning, not unhealthy: both copies are intact and work; Codex just lists them twice.
+                result["warnings"] = [{"code": "codex_duplicates", "skills": names_,
+                                       "message": "O Codex vê " + str(len(names_)) + " skill(s) duas vezes (cópia em ~/.agents/skills "
+                                                  "e link do Uniflow em " + str(projection.codex_skills_dir(home)) + ").",
+                                       "fix": "crow-skills setup --agents codex --yes"
+                                              + (" --overwrite-modified" if dupes["modified"] else "")}]
         result["groups"] = group_coverage(rows)
         try:
             result["autoupdate"] = autoupdate.status(store, home) if global_view else None
@@ -942,7 +1039,17 @@ def run(args):
         for name in list(names):
             source.require(name)
             names.extend(n for n in source.catalog[name]["next"] if n not in names)
-    plan = store.plan(args.command, names, targets, source, getattr(args, "replace", False), args.overwrite_modified)
+    codex_view = None
+    if args.command == "install" and not (getattr(args, "project", None) or getattr(args, "dest", None)):
+        codex_view = codex_projection_split(home, store, targets, names)
+    if codex_view and codex_view["skip"]:
+        # Codex already sees these through Uniflow's links in ~/.codex/skills: no native copy for codex.
+        plans = [store.plan(args.command, [n for n in names if n not in codex_view["skip"]] if t is codex_view["target"] else names,
+                            [t], source, getattr(args, "replace", False), args.overwrite_modified)
+                 for t in targets if t is not codex_view["target"] or set(names) - codex_view["skip"]]
+        plan = merge_plans(plans)
+    else:
+        plan = store.plan(args.command, names, targets, source, getattr(args, "replace", False), args.overwrite_modified)
     guides, gplan = guide_sync(args, home, store, args.command, targets, plan, source)
     ui = integrations_preview(args, home, store, plan)
     summary = {"changes": plan["changes"], "revision": source.revision if source else None,
@@ -953,6 +1060,14 @@ def run(args):
     notice = uniflow_notice(home, store, targets, plan) if args.command != "uninstall" else None
     if notice is not None:
         summary["uniflow"] = notice
+    if codex_view and (codex_view["skip"] or codex_view["duplicates"]):
+        summary["codex_projection"] = {
+            "via_uniflow": sorted(codex_view["skip"]), "duplicates": codex_view["duplicates"],
+            "note": "O Codex já vê estas skills pelo link do Uniflow em " + str(projection.codex_skills_dir(home)) +
+                    "; nenhuma cópia nativa é criada para o codex. Cópias nativas que duplicam a projeção não são removidas "
+                    "por install; remova-as com o comando sugerido ou rode crow-skills setup --yes.",
+            "suggested_command": ("crow-skills uninstall " + " ".join(codex_view["duplicates"]) + " --agents codex --global")
+            if codex_view["duplicates"] else None}
     if plan["items"] or (gplan and gplan["items"]) or ui.get("changes"):
         authorize(args, interactive, summary)
     txid = None
@@ -1023,6 +1138,8 @@ def render_status(data, doctor=False, stream=None):
                                     ("fail" if h["state"] in machine.BAD_HOOKS else "warn"), stream),
                             h["integration"], ui.word(h["state"]),
                             ui.clean(h.get("fix") or "")] for h in hooks], stream=stream)
+    for warning in data.get("warnings") or []:
+        lines += ["", ui.mark("warn", stream) + " " + ui.clean(warning["message"]) + "\n  Para corrigir: " + warning["fix"]]
     if data.get("pending_transactions"):
         lines += ["", ui.mark("fail", stream) + " Transação pendente: crow-skills recover --yes"]
     if doctor: