@andespindola/crow-skills 0.15.0 → 0.16.0

package/crow_skills/__init__.py

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

package/crow_skills/agents.py

@@ -37,12 +37,25 @@ def codex_home(home):
 
 
 def codex_skills_dir(home):
-    return codex_home(home) / "skills"
+    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(os.path.abspath(Path(home) / LEGACY_SHARED))
+    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):
@@ -86,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
@@ -109,13 +122,101 @@ def destinations(names, home, project=None, custom=None):
             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/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:

package/crow_skills/cli.py

@@ -18,7 +18,8 @@ from . import projection
 from . import resources
 from . import machine
 from . import ui
-from .agents import AGENTS, destinations, inventory, legacy_shared_dir
+from .agents import (AGENTS, destinations, inventory, legacy_shared_dir,
+                      refuse_implausible_destination, refuse_store_as_cli_dir)
 from .source import CrowError, Source, valid_name
 from .storage import Store, checked
 
@@ -261,7 +262,11 @@ def scope(args, home, interactive=False, read=False):
             agents = ",".join(AGENTS)
         elif interactive:
             agents = prompt("Agentes separados por vírgula (" + ",".join(AGENTS) + "):")
-    return destinations(agents, home, project, custom)
+    targets = destinations(agents, home, project, custom)
+    if not read:
+        refuse_store_as_cli_dir(targets, home)
+        refuse_implausible_destination(targets, home)
+    return targets
 
 
 def authorize(args, interactive, summary):
@@ -357,6 +362,22 @@ def guide_sync(args, home, store, command, targets, plan, source):
             report["skipped"].append({"agent": agent, "reason": "crow-behaviour ausente; guia mantido. Confira crow-skills guide status."})
         elif not record and command != "uninstall":
             report["skipped"].append({"agent": agent, "reason": "crow-behaviour não ficará instalada para " + agent + "; guia não aplicado."})
+    # Um guia que não pode ser gravado não derruba a instalação das skills. Desde que o guia também
+    # resolve o caminho físico, o caso que sobra aqui é a área PROTEGIDA (prompt compartilhado,
+    # config do Uniflow), que `guide.protect()` recusa com protected_path: aquele agente entra em
+    # "skipped", com o motivo, e o resto segue.
+    for agent in list(actions):
+        mechanism = guide.MECHANISMS.get(agent)
+        if not mechanism:
+            continue
+        try:
+            guide.protect(Path(home) / mechanism["path"], home)
+        except CrowError as exc:
+            actions.pop(agent, None)
+            report["skipped"].append({"agent": agent, "code": exc.code,
+                                      "reason": str(exc) + " O guia não foi aplicado; as skills seguem. "
+                                                "Grave o guia você mesmo no caminho físico, ou use --no-guide "
+                                                "para não voltar a tentar."})
     if not actions:
         return report, None
     if source is None and "install" in actions.values():
@@ -573,7 +594,9 @@ def broadcast_view(args, home, owner=None):
     cwd = os.path.abspath(getattr(args, "cwd", None) or os.getcwd())
     owner = owner if owner is not None else broadcast_owner(args, home, cwd)
     me_key = owner["key"] if owner else None
-    view = broadcast.overview(home, me_key, cwd=cwd)
+    # Aqui a identidade forte é de graça: este caminho já é um comando do usuário, não o hook.
+    # Um único ps para a máquina distingue "pid vivo" de "número reciclado" e derruba zumbi.
+    view = broadcast.overview(home, me_key, cwd=cwd, table=broadcast.process_table())
     if view["me"] is not None and view["me"].get("cwd") is None:
         view["me"]["cwd"] = cwd
     view["owner"] = owner

package/crow_skills/guide.py

@@ -119,8 +119,16 @@ def shielded(path, home):
 
 
 def protect(path, home):
-    """Refuse symlinked components, shared prompts and anything inside their targets."""
-    path = checked(path)
+    """Refuse shared prompts and anything inside their targets, on the PHYSICAL path.
+
+    Resolve first (0.16.0, decisão do dono): o arquivo de guia e as integrações de um CLI cujo
+    diretório vive em dotfiles ficavam de fora, e o CLI terminava instalado sem guia, sem hooks e
+    sem /crow — a skill ficava lá sem o agente carregá-la por iniciativa própria. `checked()`
+    continua recusando escrever ATRAVÉS de symlink, agora sobre o caminho real, e `shielded()`
+    passa a comparar o destino real, o que torna a proteção de prompt compartilhado mais precisa.
+    """
+    from .agents import physical
+    path = checked(physical(path))
     if shielded(path, home):
         raise CrowError("protected_path", "Arquivo de prompt compartilhado (ou alvo dele) não é gravado: " + str(path))
     return path

package/crow_skills/storage.py

@@ -19,6 +19,18 @@ from .agents import uniflow_store
 from .source import CrowError, MAX_FILE, MAX_PACKAGE, MAX_FILES, SHA, digest, file_entry, safe_relative, same_source, source_identity, valid_name
 
 
+def resolved(path):
+    """checked() sobre o caminho FÍSICO: usado onde o alvo vem GRAVADO numa transação.
+
+    Um alvo registrado antes de o diretório virar dotfiles continua apontando para o caminho antigo.
+    Exigir ali um caminho livre de symlink quebrava rollback e recover e chegava a TRAVAR o perfil
+    (recover recusava, rollback dizia fase incompatível, e todo install passava a exigir recovery).
+    Resolver primeiro mantém a garantia: o que é escrito continua passando por checked().
+    """
+    from .agents import physical
+    return checked(physical(path))
+
+
 def checked(path):
     path = Path(os.path.abspath(Path(path).expanduser()))
     for part in reversed((path, *path.parents)):
@@ -132,6 +144,22 @@ def validate_entries(entries):
             raise CrowError("invalid_state", "Hash/tipo de arquivo inválido no estado.")
 
 
+def retargeted(state, target):
+    """O manifesto gravado precisa declarar o caminho de HOJE (resolvido), não o de quando a
+    transação rodou: `validate_state` exige essa igualdade, e sem isto um rollback restaurava um
+    estado que o próprio leitor recusava depois com invalid_state."""
+    if not isinstance(state, dict):
+        return state
+    return dict(state, target=str(resolved(target)))
+
+
+def same_manifest(a, b):
+    """Dois manifestos descrevem o mesmo conteúdo, ignorando a string do caminho do alvo."""
+    if a is None or b is None:
+        return a == b
+    return {k: v for k, v in a.items() if k != "target"} == {k: v for k, v in b.items() if k != "target"}
+
+
 def validate_state(data, target):
     try:
         if (data["schema_version"] != 1 or data["target"] != str(target) or
@@ -153,12 +181,50 @@ class Store:
         self.root = self.home / ".local/state/crow-skills"
 
     def state_path(self, target):
-        key = hashlib.sha256(str(checked(target)).encode()).hexdigest()
+        key = hashlib.sha256(str(resolved(target)).encode()).hexdigest()
         return self.root / "targets" / key / "state.json"
 
+    def aliased_state_path(self, target):
+        """Estado gravado sob um APELIDO do mesmo destino (antes da resolução de symlink, 0.16.0).
+
+        A chave é o sha do caminho; um estado escrito quando ~/.claude ainda era diretório comum
+        está sob outra chave e ficaria invisível depois que o usuário move tudo para dotfiles —
+        `uninstall` responderia not_managed e a cópia instalada viraria órfã. Varre os destinos
+        conhecidos (poucos) e devolve o que resolve para o MESMO caminho físico."""
+        from .agents import physical
+        directory = self.root / "targets"
+        try:
+            if directory.is_symlink() or not directory.is_dir():
+                return None
+            entries = list(os.scandir(directory))
+        except OSError:
+            return None
+        wanted = physical(target)
+        found = []
+        for entry in entries:
+            candidate = Path(entry.path) / "state.json"
+            try:
+                data = read_json(candidate)
+            except (CrowError, OSError, ValueError):
+                continue
+            recorded = data.get("target") if isinstance(data, dict) else None
+            if isinstance(recorded, str) and recorded != str(target) and physical(recorded) == wanted:
+                found.append(candidate)
+        # Mais de um apelido para o MESMO caminho físico é ambíguo: escolher o primeiro do scandir
+        # (ordem arbitrária de hash) podia reportar uma skill gerenciada como `unmanaged` e, com
+        # --replace, sobrescrevê-la como se fosse lixo alheio — exatamente o dano que o apelido
+        # existe para evitar. Sem resposta única, nenhuma resposta.
+        return found[0] if len(found) == 1 else None
+
     def state(self, target):
-        target = checked(target)
+        target = resolved(target)
         path = checked(self.state_path(target))
+        if not path.exists():
+            alias = self.aliased_state_path(target)
+            if alias is not None:
+                data = read_json(alias)
+                # Reescreve o alvo para o caminho físico; a próxima mutação grava sob a chave nova.
+                return validate_state(dict(data, target=str(target)), target)
         if not path.exists():
             return {"schema_version": 1, "target": str(target), "installed": {}}
         return validate_state(read_json(path), target)
@@ -183,7 +249,11 @@ class Store:
             if not isinstance(targets, dict) or set(targets) != set(data["after"]):
                 raise ValueError("targets")
             for target, before in targets.items():
-                if str(checked(target)) != target:
+                # Absoluto e normalizado, mas NÃO exigimos que continue livre de symlink: o destino
+                # pode ter virado dotfiles depois desta transação, e toda ESCRITA ainda passa por
+                # checked(). Exigir aqui derrubava status, doctor, install, uninstall e recover de
+                # TODOS os agentes por causa de um journal antigo.
+                if target != os.path.abspath(target):
                     raise ValueError("path")
                 validate_state(before, target)
                 validate_state(data["after"][target], target)
@@ -223,7 +293,7 @@ class Store:
 
     def work(self, target, txid):
         from .guide import shielded
-        target = checked(target)
+        target = resolved(target)
         key = hashlib.sha256(str(target).encode()).hexdigest()[:20]
         # Beside the discovery dir, unless that parent is protected (the Uniflow
         # config): then staging/backups stay in the private state root instead.
@@ -234,7 +304,7 @@ class Store:
         """Backups of a transaction, wherever the version that made it put them: older
         transactions kept them beside the target even where that is now protected."""
         primary = self.work(target, txid)
-        target = checked(target)
+        target = resolved(target)
         key = hashlib.sha256(str(target).encode()).hexdigest()[:20]
         for candidate in (primary, target.parent / ".crow-skills" / key / txid, self.root / "work" / key / txid):
             if os.path.lexists(candidate):
@@ -397,7 +467,7 @@ class Store:
                     if item["new"] is not None:
                         os.replace(work / "new" / item["name"], dest)
                 for target, state in data["after"].items():
-                    atomic_json(self.state_path(target), state)
+                    atomic_json(self.state_path(target), retargeted(state, target))
                 data["phase"] = "committed"
                 atomic_json(journal, data)
             except (Exception, KeyboardInterrupt):
@@ -423,10 +493,14 @@ class Store:
         operations = []
         for target, before in data["before"].items():
             current = self.state(target)
-            if current != before and current != data["after"][target]:
+            # O campo "target" dentro do manifesto guarda o caminho de QUANDO a transação rodou; se
+            # o diretório virou dotfiles depois, ele difere do caminho resolvido de hoje e as duas
+            # estruturas nunca batem, recusando um rollback perfeitamente válido. A comparação é
+            # sobre o CONTEÚDO (as skills instaladas), não sobre a string do caminho.
+            if not same_manifest(current, before) and not same_manifest(current, data["after"][target]):
                 raise CrowError("recovery_conflict", "Manifesto mudou após a transação; recuperação recusada.")
         for item in reversed(data["items"]):
-            dest = checked(Path(item["target"])) / item["name"]
+            dest = resolved(Path(item["target"])) / item["name"]
             old = self.existing_work(item["target"], data["id"]) / "old" / item["name"]
             if item.get("link") is not None:
                 if same_link(old, item["link"]):
@@ -462,7 +536,7 @@ class Store:
             if backup is not None:
                 os.replace(backup, dest)
         for target, state in data["before"].items():
-            atomic_json(self.state_path(target), state)
+            atomic_json(self.state_path(target), retargeted(state, target))
         data["phase"] = "rolled_back"
         atomic_json(self.root / "transactions" / (data["id"] + ".json"), data)
 
@@ -479,7 +553,10 @@ class Store:
                 return rollback(self, data, self.home, recovery)
             if not recovery:
                 for target, state in data["after"].items():
-                    if self.state(target) != state:
+                    # same_manifest, e não ==: o campo "target" do manifesto guarda o caminho de
+                    # quando a transação rodou, e um diretório que virou dotfiles depois faria toda
+                    # comparação falhar, recusando um rollback válido por diferença de string.
+                    if not same_manifest(self.state(target), state):
                         raise CrowError("rollback_conflict", "Há mudanças posteriores; rollback antigo recusado.")
             self._restore(data)
 

package/docs/cli.md

@@ -191,6 +191,18 @@ Erros retornam `ok:false` e `error.code/message`. Saídas reais incluem alteraç
 
 Cada adaptador grava no diretório PRÓPRIO do seu CLI: o crow-skills atua em cada CLI diretamente e não mantém pasta compartilhada de skills. Até a 0.14.0 o codex era a exceção, instalando em `~/.agents/skills`, o que fazia o crow-skills agir sobre um diretório em vez de sobre um agente: aparecia um agente `shared` que não é CLI nenhum, e o Codex, que varre as duas raízes, listava a mesma skill duas vezes. O adaptador `shared` foi removido e `~/.agents/skills` virou apenas legado: nada é instalado lá, e o que ficou de versões anteriores é apontado como duplicata para você remover (veja [Codex e a projeção do Uniflow](#codex-e-a-projeção-do-uniflow)). Para gravar num diretório fora dos adaptadores, use `--dest` explicitamente.
 
+#### Diretório de skills em symlink (dotfiles)
+
+Desde a 0.16.0 o destino de cada adaptador é resolvido para o caminho FÍSICO (`agents.physical`, via `os.path.realpath`): `~/.codex -> /dotfiles/codex` instala em `/dotfiles/codex/skills`, e o symlink é preservado. Vale para os cinco CLIs e também para `--dest`. Antes isso era recusado com `unsafe_destination` em todos eles.
+
+O controle de segurança não foi enfraquecido, foi deslocado: `storage.checked()` continua recusando escrever ATRAVÉS de um symlink, e agora valida o destino real, o que é mais preciso. As proteções por LOCALIZAÇÃO continuam valendo depois da resolução: um diretório de skills que resolve para dentro de `~/.config/uniflow` é recusado com `protected_path`, sem tocar a config.
+
+Duas consequências que vale conhecer:
+
+- **O arquivo de prompt do agente não é resolvido.** `CLAUDE.md`, `AGENTS.md` e `rules/crow-skills.md` seguem recusados quando o caminho passa por symlink, porque gravar ali reescreveria um arquivo dentro do seu repositório de dotfiles. Isso não derruba mais o comando: o agente aparece em `guides.skipped` com `code: "unsafe_destination"` e as skills são instaladas. Para ter o guia nesse caso, grave-o você mesmo no caminho físico ou use `--no-guide` para não voltar a tentar.
+- **Apontar o diretório de um CLI exatamente para o store do Uniflow é RECUSADO numa mutação** (`protected_path`, com a dica de usar `--agents uniflow`). Gravar no store vale para todos os CLIs que o Uniflow projeta, não só para o selecionado, e a resolução tornou esse caminho alcançável a partir da seleção de um CLI. A checagem roda só na mutação: `destinations()` é usado por `status`, `doctor` e pelos avisos do uniflow para inspecionar o destino de outro agente, e recusar ali derrubaria leitura.
+- **As integrações (status line, hooks, comando) também passam por `protect()`**, então num diretório de agente em symlink elas são recusadas junto com o guia e aparecem em `integrations.skipped`. Um diretório `.crow-skills` de transações/backup aparece dentro do caminho físico (o repositório de dotfiles) e não é podado depois do commit.
+
 `agents` só verifica PATH e caminhos, sem iniciar agente/LLM. `status`/`doctor` conferem arquivos e estado de instalação, não provam carregamento, ativação, independência dos workers ou execução correta da skill. Gemini oferece `/skills reload`; para outros hosts, confira sua lista/reload ou reinicie a sessão conforme a versão. Nenhum system prompt base é alterado; o guia abaixo e os hooks do modo crow, aplicados por padrão em `--global` e desligáveis com `--no-guide` e `--no-integrations`, são aditivos: só informam ao agente o modo escolhido pelo usuário.
 
 ### Uniflow
@@ -232,7 +244,7 @@ O Codex lê duas raízes de skills do usuário: `$CODEX_HOME/skills` (padrão `~
 - A crow-behaviour continua nativa onde o Uniflow não a projeta, e o guia, as integrações e os hooks do Codex seguem funcionando; quando ela é projetada, o guia conta a projeção.
 - Migração da pasta compartilhada antiga: em `setup`, `upgrade` e no autoupdate, depois de instalar no diretório do Codex, o crow-skills remove de `~/.agents/skills` as skills que ELE instalou lá e que estão íntegras, pelo `uninstall` normal (`--dest ~/.agents/skills`, com backup, transação e `rollback`); o resumo do agente traz isso em `legacy_shared`. Isso cobre também uma skill que o Uniflow não projeta (a própria crow-behaviour, tipicamente), que não apareceria como duplicata e ficaria lá para sempre. Uma cópia editada, ou também registrada para outro agente daquele diretório, é mantida e reportada em `kept` com o comando. Nada que não tenha sido instalado pelo crow-skills é tocado, e uma falha na migração nunca derruba o resultado do agente (vira `legacy_shared.state: warn`).
 - A cópia legada só sai quando aquele nome REALMENTE funciona no diretório do Codex — instalação íntegra nossa, ou link saudável do Uniflow. Se a entrada do store do Uniflow está quebrada, o link ocupa o nome sem funcionar e a cópia legada é a única skill que o Codex tem: nesse caso ela é mantida e reportada (`legacy_shared_without_replacement`), porque removê-la tiraria a skill em vez de migrá-la. O mesmo vale quando o nome no diretório do Codex é um apelido apontando para a própria cópia legada: remover o alvo deixaria um link pendurado. Cada nome recebe UMA razão em `kept`: uma razão mais específica já registrada para ele (projeção quebrada, destino inseguro) prevalece.
-- **Mudanças de comportamento do destino do codex (0.15.0).** Com o destino no diretório próprio do Codex, duas situações que antes não afetavam o codex passam a afetá-lo, exatamente como já valia para claude, gemini e devin: (a) se `~/.codex` (ou o `$CODEX_HOME`) for um symlink, o comando é recusado com `unsafe_destination` — o crow-skills não escreve através de symlink, e a saída pede um caminho físico ou `--dest`; (b) se houver um link de qualquer tipo ocupando o nome no diretório (inclusive o apelido para a pasta legada), aquele nome não pode ser gerenciado: ele é reportado com status `unsafe` e o comando sai com 1, sem alterar o link. Não é uma regra nova do codex, é a mesma regra dos outros CLIs passando a valer para ele.
+- **Mudanças de comportamento do destino do codex (0.15.0).** Com o destino no diretório próprio do Codex, uma situação que antes não afetava o codex passa a afetá-lo, exatamente como já valia para claude, gemini e devin: (a) a partir da 0.16.0 um `~/.codex`/`$CODEX_HOME` em symlink é RESOLVIDO para o caminho físico (veja a seção de dotfiles acima); na 0.15.0 ele era recusado com `unsafe_destination`; (b) se houver um link de qualquer tipo ocupando o nome no diretório (inclusive o apelido para a pasta legada), aquele nome não pode ser gerenciado: ele é reportado com status `unsafe` e o comando sai com 1, sem alterar o link. Não é uma regra nova do codex, é a mesma regra dos outros CLIs passando a valer para ele.
 - **`$CODEX_HOME` relativo é ignorado.** Um valor relativo seria resolvido contra o diretório de trabalho DESTE processo, que não é o do Codex, então o destino dependeria de onde o comando foi rodado e poderia cair dentro de um repositório seu. Só valor absoluto (ou com `~`) é honrado; caso contrário vale `<home>/.codex`.
 - **Fallback perdido quando a entrada do store do Uniflow está quebrada.** Até a 0.14.0 o codex tinha duas raízes, então uma entrada quebrada no store ainda deixava uma cópia funcional na pasta compartilhada. Agora o link do Uniflow ocupa o nome no diretório do Codex: a entrada quebrada é reportada (`uniflow_link_modified`, com o comando que conserta o store) e a skill fica sem versão funcional até você consertar. A cópia legada, se existir, NÃO é removida nesse caso — é justamente o que o guarda de substituição protege.
 - **Aviso `codex_legacy_shared` em `status`/`doctor`.** Numa máquina sem Uniflow nada do que ficou na pasta compartilhada duplica uma projeção, então o aviso de duplicatas não apareceria e uma instalação feita pela 0.14.0 ficaria invisível, ainda carregada pelo Codex. Esse aviso novo lista essas skills, com o caminho e o comando (`setup --agents codex --yes`, que migra, ou `uninstall … --dest <pasta legada>`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andespindola/crow-skills",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Versioned, complementary agent skills with a protected multi-agent installer",
   "license": "UNLICENSED",
   "repository": {

package/release.json

@@ -18,7 +18,7 @@
     "crow_skills/__init__.py": {
       "executable": false,
       "kind": "file",
-      "sha256": "26eaa6dfbdfbc6e83983270615e53556227560f236d3064f8fb596bbfceebf0c"
+      "sha256": "6a988b314e5b6bb3f2db799d74aec9717c6c3dfa59b4b1ebdeb1e3697fad498b"
     },
     "crow_skills/__main__.py": {
       "executable": false,
@@ -28,7 +28,7 @@
     "crow_skills/agents.py": {
       "executable": false,
       "kind": "file",
-      "sha256": "0f8a284d5ce6dfc8c55a81be861c56c1884156937ecbce3a8800aef4ade76496"
+      "sha256": "1c2f61e6729c88f0ddc218fba0c5159869e5226d4f7bc0fd2181dd688d4272fe"
     },
     "crow_skills/autoupdate.py": {
       "executable": false,
@@ -38,12 +38,12 @@
     "crow_skills/broadcast.py": {
       "executable": false,
       "kind": "file",
-      "sha256": "33ba77b7fad64b8cb068d7cdac697505fbe061d60522ef0fabb9b121255cee2d"
+      "sha256": "3d25bd5fa2bdbe7e6ec78ce9c44a3b96f13d48b2ceea076c792ffbecd5bbbf1f"
     },
     "crow_skills/cli.py": {
       "executable": false,
       "kind": "file",
-      "sha256": "5a1146f2d6c14554384bc13f0e2f83b3e5ce4b2743dd8a3fee70db3c2f5db9b1"
+      "sha256": "3182cabd5cf63e780e37f0ae0ef5b2b1090d91debaf90d54765dc80a08e6f864"
     },
     "crow_skills/events.py": {
       "executable": false,
@@ -58,7 +58,7 @@
     "crow_skills/guide.py": {
       "executable": false,
       "kind": "file",
-      "sha256": "aa8c16b293a72d6aabd99246a3666e40beaa81d5c1b77e6389341eca463e6a7f"
+      "sha256": "ab75772bc70758b3c3b16339dcf0ec572af358dd0378f7fc3844dbf039590563"
     },
     "crow_skills/hook.py": {
       "executable": false,
@@ -103,7 +103,7 @@
     "crow_skills/storage.py": {
       "executable": false,
       "kind": "file",
-      "sha256": "92b7b76ed75e84901dc2a67df3bb6998558200041bc42c8597e708829541a5b1"
+      "sha256": "7cbc25b39ada200e516079b81a77770e641b267cd5e5868686eb0d87a6604ea8"
     },
     "crow_skills/trust.py": {
       "executable": false,
@@ -123,12 +123,12 @@
     "docs/cli.md": {
       "executable": false,
       "kind": "file",
-      "sha256": "9dd1b9cc567e01356ead3d667b3ea559534d44930dffaa9dff7808e3476f25a3"
+      "sha256": "0f425d8d694e1103cd9e56b8b6f6332756bcb8415ca04ec55e0db2f201481807"
     },
     "package.json": {
       "executable": false,
       "kind": "file",
-      "sha256": "f89633c7d12d50ab189edd74ed7c347d299001db6b9a0397f7a98693abaef936"
+      "sha256": "64613f54bedd2d62023be224e30de2dd87bbc0ac7664ed0c49ee8e20a6454ade"
     },
     "skills/crow-accessibility/SKILL.md": {
       "executable": false,
@@ -716,7 +716,7 @@
       "sha256": "e37132ef8b060548191fbf14a5a18a9dd3acd84ea9a35e802174455b9e374d3d"
     }
   },
-  "revision": "4297812328b55870f4b4e7a9bb3e4e7d4f82e358",
+  "revision": "23cca75e8117dd6110db7e2565b0ce0b740b8efb",
   "schema_version": 1,
-  "version": "0.15.0"
+  "version": "0.16.0"
 }