@andespindola/crow-skills 0.14.0 → 0.16.0

package/crow_skills/__init__.py

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

package/crow_skills/agents.py

@@ -4,18 +4,60 @@ import os
 import shutil
 from .source import CrowError
 
+# Every destination is the CLI's OWN skills directory. There is no shared folder: the
+# ~/.agents/skills store that codex used until 0.14.0 made crow-skills act on a directory
+# instead of on an agent, which showed up as a phantom "codex,shared" agent and let Codex
+# list the same skill twice (its own dir plus the shared one). LEGACY_SHARED stays named
+# only so an install made there can be found and migrated away.
+LEGACY_SHARED = ".agents/skills"
 AGENTS = {
-    "codex": (".agents/skills", ".agents/skills", "codex"),
+    "codex": (".codex/skills", ".codex/skills", "codex"),
     "claude": (".claude/skills", ".claude/skills", "claude"),
     "gemini": (".gemini/skills", ".gemini/skills", "gemini"),
     "devin": (".config/devin/skills", ".devin/skills", "devin"),
-    "shared": (".agents/skills", ".agents/skills", None),
     # Uniflow keeps one store and links it into each CLI's user skills dir; it has
     # no project scope. The store sits beside config.json (see uniflow_store).
     "uniflow": (".config/uniflow/skills", None, "uniflow"),
 }
 
 
+def codex_home(home):
+    """$CODEX_HOME for the real profile (as Codex resolves it); an isolated --home uses <home>/.codex.
+
+    A RELATIVE $CODEX_HOME is ignored: os.path.abspath would resolve it against this process's cwd,
+    which is not Codex's, so the destination would depend on where the command was run and could
+    land inside the user's repository. Only an absolute (or ~-anchored) value is honoured."""
+    home = Path(home)
+    raw = os.environ.get("CODEX_HOME") if real_home(home) else None
+    if raw:
+        expanded = Path(raw).expanduser()
+        if expanded.is_absolute():
+            return Path(os.path.abspath(expanded))
+    return Path(os.path.abspath(home / ".codex"))
+
+
+def codex_skills_dir(home):
+    return Path(physical(codex_home(home) / "skills"))
+
+
+def legacy_shared_dir(home):
+    """Where codex installs landed until 0.14.0; read only, to migrate what is still there."""
+    return Path(physical(Path(home) / LEGACY_SHARED))
+
+
+def physical(path):
+    """The physical path behind a skills directory, following symlinks on the components that exist.
+
+    A CLI directory kept in dotfiles (~/.codex -> /dotfiles/codex) is the normal case, and the CLI
+    itself follows the link. storage.checked() refuses to WRITE through a symlink, which is the
+    control that keeps a write from landing somewhere other than where it reads: resolving here, at
+    destination resolution, honours the dotfiles layout while leaving that control intact, because
+    what reaches checked() is already physical. os.path.realpath resolves the existing components
+    and leaves the rest, so a skills dir that does not exist yet still resolves correctly.
+    """
+    return os.path.realpath(os.path.abspath(Path(path).expanduser()))
+
+
 def real_home(home):
     """Environment overrides describe the real profile; an isolated --home ignores them."""
     return home == Path.home().resolve()
@@ -57,7 +99,7 @@ def destinations(names, home, project=None, custom=None):
     if custom:
         if names:
             raise CrowError("usage", "--dest e --agents não podem ser combinados.")
-        return [{"path": str(Path(custom).expanduser().absolute()), "agents": ["custom"]}]
+        return [{"path": physical(custom), "agents": ["custom"]}]
     if not names:
         raise CrowError("usage", "Selecione --agents; não há instalação implícita em todos os agentes.")
     selected = names.split(",") if isinstance(names, str) else names
@@ -74,15 +116,107 @@ def destinations(names, home, project=None, custom=None):
         # Respect explicit XDG config, but isolate it when --home selects another profile.
         if name == "devin" and not project and real_home(home) and os.getenv("XDG_CONFIG_HOME"):
             path = Path(os.environ["XDG_CONFIG_HOME"]).expanduser() / "devin/skills"
+        # Codex resolves its own home through $CODEX_HOME; the destination must follow it, or an
+        # install would write beside a profile Codex never reads.
+        if name == "codex" and not project:
+            path = codex_skills_dir(home)
         if name == "uniflow":
             path = uniflow_store(home)
-        key = str(path.absolute())
+        key = physical(path)
         result.setdefault(key, {"path": key, "agents": []})
         if name not in result[key]["agents"]:
             result[key]["agents"].append(name)
     return list(result.values())
 
 
+def plausible_skills_dir(path, agents_):
+    """O caminho resolvido parece o diretório de skills DESTE CLI?
+
+    Regra positiva, por decisão do dono. "Termina em skills" sozinho não basta: o arranjo de
+    dotfiles mais comum é `~/.claude/skills -> /dotfiles/claude`, em que o LINK se chama skills e o
+    ALVO se chama como o agente — e recusá-lo quebraria exatamente o caso que a resolução existe
+    para atender. Então o último trecho pode ser "skills" OU o nome de um dos agentes selecionados
+    (ou o nome do diretório de config dele, para o devin). `~/.ssh`, o `.git` de outro repositório
+    e o diretório de transações do crow-skills continuam fora.
+    """
+    # Um trecho sensível no caminho vence o nome: `~/.ssh/skills` passava só por terminar em
+    # "skills" e o instalador criava ali seu diretório de staging, ao lado das chaves. Isto não é
+    # uma lista de negação geral (que o dono recusou): são três áreas que nunca são diretório de
+    # skills de um CLI.
+    parts = {x.lower() for x in Path(path).parts}
+    if parts & {".ssh", ".git", ".gnupg"}:
+        return False
+    base = os.path.basename(path).lower()
+    if base == "skills":
+        return True
+    names = set()
+    for agent in agents_:
+        names.add(agent.lower())
+        user_path = (AGENTS.get(agent) or (None,))[0]
+        if user_path:
+            parts = [x for x in Path(user_path).parts if x not in (".", "")]
+            if len(parts) >= 2:
+                names.add(parts[-2].lstrip(".").lower())  # .config/devin/skills -> devin
+            names.add(parts[0].lstrip(".").lower())        # .claude/skills -> claude
+    return base in names
+
+
+def refuse_implausible_destination(targets, home):
+    """Recusa um destino de CLI que resolve para um lugar que não é diretório de skills.
+
+    Resolver symlink (0.16.0) tirou a garantia implícita de que a seleção de um CLI só escrevia
+    embaixo do diretório daquele CLI: um ~/.claude/skills apontando para ~/.ssh, para o .git de
+    outro repositório ou para o próprio diretório de transações do crow-skills passava a receber
+    pacotes. Regra POSITIVA, por decisão do dono: o caminho resolvido precisa terminar em "skills"
+    (o layout de dotfiles normal, /dotfiles/claude/skills, passa) ou ser o store do Uniflow pelo
+    agente certo. Uma lista de negação seria mais fácil de furar com um caminho não previsto.
+    """
+    store = physical(uniflow_store(home))
+    for target in targets:
+        path = physical(target["path"])
+        agents_ = target.get("agents") or []
+        if "custom" in agents_:
+            continue  # --dest é escolha explícita e consciente do usuário
+        if path == store and agents_ == ["uniflow"]:
+            continue
+        if plausible_skills_dir(path, agents_):
+            continue
+        # Uma área protegida tem razão PRÓPRIA e melhor: dizer "não parece diretório de skills" ali
+        # esconderia o motivo verdadeiro e mandaria o usuário para um --dest que a proteção recusa
+        # de qualquer forma — beco sem saída.
+        from .guide import shielded
+        try:
+            if shielded(Path(path), home):
+                raise CrowError("protected_path", "O destino de " + ",".join(agents_) + " resolve para " + path +
+                                ", que é área protegida (prompt compartilhado ou configuração do Uniflow).")
+        except CrowError:
+            raise
+        except Exception:  # noqa: BLE001 - se não der para avaliar, vale a razão genérica
+            pass
+        raise CrowError("implausible_destination", "O destino de " + ",".join(agents_) + " resolve para " +
+                        path + ", que não parece um diretório de skills deste CLI (esperado um caminho cujo "
+                        "último trecho seja \"skills\" ou o nome do agente). Se é mesmo onde você quer "
+                        "instalar, use --dest explicitamente.")
+
+
+def refuse_store_as_cli_dir(targets, home):
+    """Recusa um destino de CLI que resolve para o store do Uniflow.
+
+    Resolver symlink (0.16.0) tornou isso alcançável pela seleção de um CLI: um
+    ~/.claude/skills -> ~/.config/uniflow/skills gravaria um pacote dentro do store, que vale para
+    TODOS os CLIs que o Uniflow projeta, não só o selecionado. Só vale na MUTAÇÃO: `destinations()`
+    é chamado por vários caminhos de leitura (status, doctor, avisos do uniflow) que inspecionam o
+    destino de outro agente, e levantar lá derrubaria um comando que nem ia gravar naquele lugar.
+    """
+    store = physical(uniflow_store(home))
+    for target in targets:
+        others = [a for a in target.get("agents") or [] if a != "uniflow"]
+        if others and physical(target["path"]) == store:
+            raise CrowError("protected_path", "O destino de " + ",".join(others) + " resolve para o store do "
+                            "Uniflow (" + store + "), que vale para todos os CLIs que ele projeta, não só para "
+                            + ",".join(others) + ". Use --agents uniflow para gravar no store.")
+
+
 def inventory(home):
     rows = []
     for name, (_, project, binary) in AGENTS.items():

package/crow_skills/autoupdate.py

@@ -29,7 +29,7 @@ import subprocess
 import sys
 
 from . import __version__
-from .agents import destinations
+from .agents import destinations, legacy_shared_dir
 from .guide import protect, read_regular, sha, write_atomic
 from .source import CrowError, Source, same_source
 from .storage import atomic_json, checked, private_dir, read_json
@@ -334,8 +334,9 @@ def reinstall_behaviour(home, entry, dry_run, trust):
 
 
 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."""
+    """Codex sees Uniflow's links in its own dir: those names are not updated there, and intact managed copies
+    left in the legacy shared folder are removed through uninstall against THAT folder (backup, transaction).
+    Returns the names to update."""
     from . import projection
     from .cli import parser, run as cli_run
     seen = projection.projected("codex", home, store)
@@ -347,7 +348,8 @@ def codex_duplicates(home, store, entry, names, dry_run):
     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),
+        # --dest na pasta legada: em ~/.codex/skills esses nomes são links do Uniflow e o uninstall recusaria.
+        argv = ["uninstall", *dupes["remove"], "--dest", str(legacy_shared_dir(home)), "--json", "--home", str(home),
                 "--dry-run" if dry_run else "--yes", "--no-integrations"]
         try:
             data = cli_run(parser().parse_args(argv))
@@ -411,6 +413,11 @@ def skills_update(home, trust=True, dry_run=False):
                     entry["error"] = {"code": exc.code, "message": str(exc)}
                 except (OSError, ValueError, KeyError, TypeError):
                     entry["error"] = {"code": "io_error", "message": "Falha de leitura/gravação; nada concluído para este agente."}
+                if agent == "codex" and not entry.get("error"):
+                    # Ramo mais provável de quem vinha da 0.14.0: no diretório do Codex só há links do
+                    # Uniflow, e TODAS as cópias do codex estão na pasta compartilhada. Sem migrar aqui,
+                    # uma máquina que só roda autoupdate nunca sai daquela pasta.
+                    machine.migrate_legacy(None, home, store, entry, dry_run, planned=projected)
                 results.append(entry)
             continue
         records = store.state(target["path"])["installed"]
@@ -455,6 +462,12 @@ def skills_update(home, trust=True, dry_run=False):
                 entry["error"] = {"code": exc.code, "message": str(exc)}
             except (OSError, ValueError, KeyError, TypeError):
                 entry["error"] = {"code": "io_error", "message": "Falha de leitura/gravação; nada concluído para este agente."}
+        if agent == "codex" and not entry.get("error"):
+            # Mesma migração do setup, e pelo mesmo motivo: sem isto, uma máquina que só roda
+            # autoupdate/upgrade mantém a pasta compartilhada antiga para sempre. Depois da
+            # atualização, nunca antes.
+            from . import machine
+            machine.migrate_legacy(None, home, store, entry, dry_run)
         results.append(entry)
     return results
 

package/crow_skills/broadcast.py

@@ -548,30 +548,69 @@ TTY_TIMEOUT = 1.0
 TTY_TRIES = 2
 
 
+def parse_elapsed(text):
+    """Segundos de `ps -o etime=` ([[dd-]hh:]mm:ss), ou None quando não dá para ler."""
+    if not isinstance(text, str) or not text.strip():
+        return None
+    body = text.strip()
+    days = 0
+    if "-" in body:
+        head, _, body = body.partition("-")
+        try:
+            days = int(head)
+        except ValueError:
+            return None
+    pieces = body.split(":")
+    if not 1 <= len(pieces) <= 3:
+        return None
+    try:
+        values = [int(x) for x in pieces]
+    except ValueError:
+        return None
+    while len(values) < 3:
+        values.insert(0, 0)
+    return days * 86400 + values[0] * 3600 + values[1] * 60 + values[2]
+
+
 def tty_lookup(pid, runner=None):
-    """(tty, answered): the controlling terminal of pid as a device path (``/dev/ttys012``,
-    ``/dev/pts/3``) or None, and whether ``ps`` actually answered (False on error, timeout or a
-    non-POSIX system, so the caller may retry later). One ``ps -o tty= -p PID`` limited to
-    TTY_TIMEOUT; never raises."""
+    """(tty, answered, elapsed): the controlling terminal of pid as a device path
+    (``/dev/ttys012``, ``/dev/pts/3``) or None; whether ``ps`` actually answered (False on error,
+    timeout or a non-POSIX system, so the caller may retry later); and how many seconds the process
+    has been running, or None.
+
+    ONE ``ps -o tty=,etime= -p PID`` limited to TTY_TIMEOUT, never raises. The elapsed time rides
+    along in the ps that already happens once per stable pid: recording when the CLI started is
+    what lets a reader tell "this pid is still the same process" from "the number was recycled",
+    and it must cost nothing on the hook's path."""
     if not isinstance(pid, int) or isinstance(pid, bool) or pid <= 1 or os.name != "posix":
-        return None, False
+        return None, False, None
     try:
         if runner is None:
             import subprocess
-            done = subprocess.run(["ps", "-o", "tty=", "-p", str(pid)], stdin=subprocess.DEVNULL, capture_output=True,
-                                  text=True, timeout=TTY_TIMEOUT)
+            done = subprocess.run(["ps", "-o", "tty=,etime=", "-p", str(pid)], stdin=subprocess.DEVNULL,
+                                  capture_output=True, text=True, timeout=TTY_TIMEOUT)
             if done.returncode != 0:
-                return None, done.returncode == 1  # 1: no such process (a definite answer)
+                return None, done.returncode == 1, None  # 1: no such process (a definite answer)
             out = done.stdout
         else:
             out = runner(pid)
     except Exception:  # noqa: BLE001 - a missing tty is never an error
-        return None, False
-    name = (out or "").strip().splitlines()[0].strip() if (out or "").strip() else ""
+        return None, False, None
+    line = (out or "").strip().splitlines()[0].strip() if (out or "").strip() else ""
+    # "ttys012 01:23:45": o tty é a primeira coluna; o resto, quando existe, é o etime. Um runner
+    # de teste que devolva só o tty continua funcionando — o start fica None.
+    # Só separa a segunda coluna quando ela REALMENTE parece um etime; caso contrário a linha
+    # inteira é o nome do tty, como antes. Dividir por espaço sem checar aceitaria "tty s1" como
+    # o tty "tty", afrouxando a validação do nome.
+    parts = line.split()
+    name, elapsed = line, None
+    if len(parts) == 2 and parse_elapsed(parts[1]) is not None:
+        name, elapsed = parts[0], parts[1]
     base = name[len("/dev/"):] if name.startswith("/dev/") else name
+    seconds = parse_elapsed(elapsed)
     if not base or base.strip("?-") == "" or not re.fullmatch(r"[A-Za-z0-9._-][A-Za-z0-9/._-]{0,63}", base) or ".." in base:
-        return None, True
-    return "/dev/" + base, True
+        return None, True, seconds
+    return "/dev/" + base, True, seconds
 
 
 def tty_of(pid, runner=None):
@@ -610,12 +649,17 @@ def fold(snap, event, touched=(), now=None, ppid=None, cli_pid=None, tty_runner=
     stable = isinstance(pid, int) and (pid == presence.get("cliPid") or presence.get("pidStable"))
     if stable and presence.get("ttyPid") != pid:  # one short ps per stable pid (retried if ps did not answer)
         presence.pop("tty", None)
-        tty, answered = tty_lookup(pid, tty_runner)
+        tty, answered, elapsed = tty_lookup(pid, tty_runner)
         tries = presence.get("ttyTries") if isinstance(presence.get("ttyTries"), list) and presence["ttyTries"][:1] == [pid] else [pid, 0]
         tries = [pid, int(tries[1]) + 1 if isinstance(tries[1], int) else 1]
         presence["ttyTries"] = tries
         if answered or tries[1] >= TTY_TRIES:  # a ps that failed or timed out is retried once, never per event
             presence["ttyPid"] = pid
+        if isinstance(elapsed, int):
+            # Identidade do processo, de graça: o MESMO ps do tty traz o tempo decorrido. Guardar o
+            # início permite distinguir "o pid continua vivo" de "o número foi reciclado por outro
+            # processo" sem nenhuma chamada a mais no caminho do hook.
+            presence["cliStart"] = int(now - elapsed)
         if tty:
             presence["tty"] = tty
     if stable:
@@ -673,19 +717,93 @@ def presence_of(snap):
     return value if isinstance(value, dict) else {}
 
 
-def liveness(snap, age, cfg, now=None):
-    """'live' or None: ended sessions and stale ones (no heartbeat, CLI pid not alive) drop out."""
+CLI_REUSE_SECONDS = 60  # mesma tolerância de resources.py: start desta distância é o mesmo CLI
+
+
+def process_identity(table, pid):
+    """(existe, é zumbi, start) de um pid numa tabela já lida, ou (None, None, None) sem tabela.
+
+    A tabela vem de quem JÁ leu os processos (crow-skills broadcast status, doctor, varredura de
+    órfãos). O caminho do hook não passa tabela e por isso não paga nada: lá vale a checagem barata
+    de `pid_alive`. Assim a identidade forte existe onde é de graça, e o contrato do hook
+    ("retorne rápido, nunca bloqueie") fica intacto.
+    """
+    # Tabela VAZIA não é "nenhum processo existe": é `ps` que falhou, deu timeout ou não existe
+    # neste sistema. Tratá-la como resposta apagava todas as sessões vivas de uma vez. Sem
+    # evidência, vale a checagem barata.
+    if not isinstance(table, dict) or not table or not isinstance(pid, int) or isinstance(pid, bool):
+        return None, None, None
+    row = table.get(pid)
+    if row is None:
+        return False, None, None
+    return True, bool(row.get("zombie")), row.get("start")
+
+
+def process_table(runner=None):
+    """{pid: {"start": epoch, "zombie": bool}} num único `ps`, para quem vai avaliar várias sessões.
+
+    Um ps para a máquina inteira, não um por sessão. Quem não precisa de identidade forte (o hook)
+    simplesmente não chama isto."""
+    if os.name != "posix":
+        return {}
+    try:
+        if runner is None:
+            import subprocess
+            done = subprocess.run(["ps", "-Ao", "pid=,etime=,stat="], stdin=subprocess.DEVNULL,
+                                  capture_output=True, text=True, timeout=TTY_TIMEOUT * 3)
+            if done.returncode != 0:
+                return {}
+            out = done.stdout
+        else:
+            out = runner()
+    except Exception:  # noqa: BLE001 - sem tabela, a checagem barata continua valendo
+        return {}
+    moment = time.time()
+    table = {}
+    for line in (out or "").splitlines():
+        parts = line.split()
+        if len(parts) < 3:
+            continue
+        try:
+            pid = int(parts[0])
+        except ValueError:
+            continue
+        seconds = parse_elapsed(parts[1])
+        table[pid] = {"start": int(moment - seconds) if isinstance(seconds, int) else None,
+                      "zombie": parts[2][:1] in ("Z", "X")}
+    return table
+
+
+def liveness(snap, age, cfg, now=None, table=None):
+    """'live' or None: ended sessions, stale ones and ones whose CLI process is gone drop out.
+
+    A session whose pid is STABLE (the resolved CLI, not a transient hook parent) and whose process
+    no longer exists is dead now, not in stale_minutes: a CLI that crashed used to keep claiming
+    `working` for half an hour, inflating the count and making every other session avoid its clone.
+    pid_alive returning None (it could not tell) is not treated as dead, and a session without a
+    stable pid still falls back to the heartbeat window.
+    """
     if snap.get("state") == "ended":
         return None
+    presence = presence_of(snap)
+    if presence.get("pidStable") and pid_alive(presence.get("pid")) is False:
+        return None
+    if presence.get("pidStable"):
+        exists, is_zombie, start = process_identity(table, presence.get("pid"))
+        if exists is False or is_zombie:
+            return None  # o processo sumiu, ou é zumbi: a sessão acabou, sem esperar a janela
+        recorded = presence.get("cliStart")
+        if exists and isinstance(start, (int, float)) and isinstance(recorded, (int, float)) \
+                and abs(start - recorded) > CLI_REUSE_SECONDS:
+            return None  # o número do pid foi reciclado por outro processo; esta sessão morreu
     if age <= cfg["stale_minutes"] * 60:
         return "live"
-    presence = presence_of(snap)
     if presence.get("pidStable") and age <= cfg["pid_alive_hours"] * 3600 and pid_alive(presence.get("pid")):
         return "live"
     return None
 
 
-def live_sessions(home, cfg=None, now=None):
+def live_sessions(home, cfg=None, now=None, table=None):
     """crow-session/1 snapshots of live sessions of this user, newest first, each with ageSeconds and repo."""
     cfg = cfg or config(home)
     now = now or time.time()
@@ -709,7 +827,7 @@ def live_sessions(home, cfg=None, now=None):
         snap = read_json(entry.path)
         if not isinstance(snap, dict) or snap.get("schema") != SESSION_SCHEMA:
             continue
-        if liveness(snap, age, cfg, now) is None:
+        if liveness(snap, age, cfg, now, table=table) is None:
             continue
         snap["ageSeconds"] = max(0, int(age))
         presence = presence_of(snap)
@@ -1250,11 +1368,11 @@ def relations(me, other, now, cfg):
     return rel
 
 
-def overview(home, me_key=None, me=None, cwd=None, now=None, cfg=None):
+def overview(home, me_key=None, me=None, cwd=None, now=None, cfg=None, table=None):
     """crow-broadcast/1: every live session with its relation to me, plus active claims."""
     cfg = cfg or config(home)
     now = now or time.time()
-    live = live_sessions(home, cfg, now)
+    live = live_sessions(home, cfg, now, table=table)
     if me is None:
         me = next((s for s in live if s.get("key") == me_key), None) if me_key else None
     if me is None and cwd: