@andespindola/crow-skills 0.15.0 → 0.16.1

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.1"

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,104 @@ 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:
+            # "custom" é o rótulo interno de --dest: dizer "o destino de custom" confunde quem não
+            # passou agente nenhum. A mensagem nomeia o que o usuário realmente escreveu.
+            quem = "--dest" if others == ["custom"] else ",".join(others)
+            raise CrowError("protected_path", "O destino de " + quem + " resolve para o store do Uniflow ("
+                            + store + "), que vale para todos os CLIs que ele projeta. 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,97 @@ 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")
+        # Um heartbeat FRESCO vence a comparação de start: `cliStart` é gravado como
+        # (agora_do_hook - etime) e a tabela recalcula (agora_do_leitor - etime), então um salto de
+        # relógio (NTP, suspensão do Mac) maior que a tolerância faria os dois divergirem e mataria
+        # uma sessão VIVA. Se ela deu sinal agora, está viva, qualquer que seja a aritmética.
+        if exists and age > CLI_REUSE_SECONDS 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 +831,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 +1372,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
@@ -132,7 +140,9 @@ def protect_skill(path, home):
     config (config.json, prompts, backups) stay protected. The package entry itself may
     be a link Uniflow made; the plan decides about it, never following it."""
     path = Path(os.path.abspath(path))
-    if path.parent == uniflow_store(home) and NAME.fullmatch(path.name):
+    from .agents import physical
+    # Mesmo motivo: o store em dotfiles resolve, e a comparação crua nunca batia.
+    if physical(path.parent) == physical(uniflow_store(home)) and NAME.fullmatch(path.name):
         checked(path.parent)
         return path
     path = checked(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,66 @@ 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 retire_alias(self, target):
+        """Retira o estado gravado sob um APELIDO deste destino, depois de gravar o canônico.
+
+        Sem isto o registro antigo ficava para trás divergente e voltava a mandar se o diretório
+        deixasse de ser link: uma skill removida ressuscitava como `missing`, com a revisão errada,
+        deixando o doctor insalubre e o update em source_mismatch. Renomeia para `.superseded`
+        em vez de apagar, para que nada se perca se o diagnóstico precisar do histórico.
+        """
+        alias = self.aliased_state_path(target)
+        if alias is None:
+            return
+        try:
+            alias.replace(alias.with_suffix(".superseded.json"))
+        except OSError:
+            pass  # nunca derruba a mutação por causa da aposentadoria do apelido
+
     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 +265,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 +309,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 +320,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):
@@ -284,7 +370,13 @@ class Store:
                                         "crow-skills uninstall " + name + " --dest " + str(target) + " --yes e, se for para o "
                                         "Uniflow, reinstale com --agents uniflow --global.") from exc
             # Only the uniflow agent replaces Uniflow's import links; --dest keeps refusing links.
-            store_target = "uniflow" in target_info["agents"] and target == uniflow_store(self.home)
+            # physical() e não resolved(): plan() tem um local chamado `resolved` mais abaixo, que
+            # torna o nome local em toda a função e faria esta linha estourar UnboundLocalError.
+            # O store do Uniflow em dotfiles tem o caminho resolvido, e comparar com o não resolvido
+            # deixava o store inteiro não gerenciável (lacuna anterior à 0.16.0).
+            from .agents import physical as _physical
+            store_target = "uniflow" in target_info["agents"] and \
+                str(target) == _physical(uniflow_store(self.home))
             before[key] = state
             after[key] = json.loads(json.dumps(state))
             selected = list(names) if names else list(state["installed"])
@@ -397,7 +489,8 @@ 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))
+                    self.retire_alias(target)
                 data["phase"] = "committed"
                 atomic_json(journal, data)
             except (Exception, KeyboardInterrupt):
@@ -423,10 +516,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 +559,8 @@ 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))
+            self.retire_alias(target)
         data["phase"] = "rolled_back"
         atomic_json(self.root / "transactions" / (data["id"] + ".json"), data)
 
@@ -479,7 +577,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)
 
@@ -506,7 +607,11 @@ class Store:
                     continue
                 record = state["installed"].get(name)
                 link = target / name
-                store = uniflow_store(self.home)
+                from .agents import physical as _physical  # local `resolved` nesta função sombreia o helper
+                # Path(), não a string crua: `physical()` devolve str, e aqui o valor é comparado
+                # com um Path (`target == store`, que seria SEMPRE falso, matando em silêncio o
+                # ramo de status external_link) e usado como caminho (`store / name`, TypeError).
+                store = Path(_physical(uniflow_store(self.home)))
                 if link.is_symlink() and target == store:
                     resolved = os.path.realpath(link)
                     managed = self.managed_target(resolved, name)

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
@@ -216,6 +228,12 @@ O Uniflow guarda as skills num store próprio e cria, ao subir cada CLI, links d
 - Cópias nativas duplicadas: se claude, gemini ou devin já têm um pacote crow de mesmo nome, o Uniflow não cria o link para ele e a cópia nativa continua valendo ali, possivelmente em outra revisão (`effect: skipped`). O codex se comporta igual desde a 0.15.0, por instalar no diretório dele (`effect: skipped`); antes ele instalava na pasta compartilhada e o Codex via a mesma skill duas vezes. `install`/`update` com `uniflow` listam essas cópias em `uniflow.native_duplicates` (diretórios que não puderam ser lidos, como um `~/.claude` symlink de dotfiles, vão para `uniflow.uninspected` sem derrubar o comando) e sugerem em `uniflow.suggested_command` o `uninstall` explícito; nada é removido sem esse comando. Remover a cópia nativa da crow-behaviour remove também o guia daquele agente, que deixa de valer fora do Uniflow.
 - Links projetados: em `status`/`doctor`, um link do Uniflow para o store num diretório de agente aparece como `uniflow_link`, e não deixa o doctor `healthy:false`.
 
+#### Estado gravado sob um apelido do destino
+
+A chave do estado é o caminho FÍSICO. Um estado escrito quando `~/.claude` ainda era diretório comum fica sob outra chave, e `Store.state()` o encontra varrendo os destinos conhecidos (`aliased_state_path`) para não perder a instalação quando você move tudo para dotfiles. Depois de gravar o estado canônico, a mutação APOSENTA o apelido, renomeando-o para `.superseded.json` em vez de apagar. Sem essa aposentadoria o registro antigo ficava divergente e voltava a mandar caso o diretório deixasse de ser link: uma skill removida ressuscitava como `missing`, com a revisão errada, e o `update` passava a recusar com `source_mismatch`. Dois apelidos para o mesmo caminho físico são ambíguos e nenhum é usado.
+
+Consequência a conhecer, se você DESFIZER o link depois de ter mexido pelo link: o estado canônico ficou sob o caminho físico de então (o dos dotfiles) e o apelido antigo foi aposentado, então o novo local não tem registro e as skills aparecem como `unmanaged`, com o `doctor` saudável. É a resposta honesta — não existe registro para aquele caminho —, e `install --replace` ou `setup` readotam o que está lá. O comportamento anterior era pior: o registro antigo ressuscitava e reportava uma skill já removida como `missing`, com a revisão errada, deixando o `doctor` insalubre e o `update` em `source_mismatch`.
+
 #### Exercitar um hook sem efeito colateral (`--probe`)
 
 `crow_hook.py hook --host <host> --event <evento> --probe` calcula exatamente o que o hook entregaria naquele evento — modo crow, aviso de memória e o bloco do crow-broadcast — e **não grava nada**: nenhum evento no barramento, nenhum snapshot de sessão, nenhuma presença, nenhuma escrita de modo. É o que usar para conferir se o hook de um CLI está cabeado e funcionando.
@@ -232,7 +250,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.1",
   "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": "fb5a2f995f5007c08a1d21d9853763865628ac218330da800ef7b3461282a626"
     },
     "crow_skills/__main__.py": {
       "executable": false,
@@ -28,7 +28,7 @@
     "crow_skills/agents.py": {
       "executable": false,
       "kind": "file",
-      "sha256": "0f8a284d5ce6dfc8c55a81be861c56c1884156937ecbce3a8800aef4ade76496"
+      "sha256": "903750fa57f9aa3cba686bcbd3775881493275b1e5aff86c5e57035d2144c7f1"
     },
     "crow_skills/autoupdate.py": {
       "executable": false,
@@ -38,12 +38,12 @@
     "crow_skills/broadcast.py": {
       "executable": false,
       "kind": "file",
-      "sha256": "33ba77b7fad64b8cb068d7cdac697505fbe061d60522ef0fabb9b121255cee2d"
+      "sha256": "d886806e138953dfe47bd19c8f12b4267f5137e510346081c2e3fb15e4b7a8fb"
     },
     "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": "0b5ca9d1629bcdc88e30f42b14b1189f41e9417b46c16771c339fe3ffc09dece"
     },
     "crow_skills/hook.py": {
       "executable": false,
@@ -103,7 +103,7 @@
     "crow_skills/storage.py": {
       "executable": false,
       "kind": "file",
-      "sha256": "92b7b76ed75e84901dc2a67df3bb6998558200041bc42c8597e708829541a5b1"
+      "sha256": "2e276f27c25256508670afcd1d6da38811819351dee45e42f4098090a00d8832"
     },
     "crow_skills/trust.py": {
       "executable": false,
@@ -123,12 +123,12 @@
     "docs/cli.md": {
       "executable": false,
       "kind": "file",
-      "sha256": "9dd1b9cc567e01356ead3d667b3ea559534d44930dffaa9dff7808e3476f25a3"
+      "sha256": "84bc06ac93083a18d81d202409dfe26202feb20d4d6cab7a46520badd2b13a13"
     },
     "package.json": {
       "executable": false,
       "kind": "file",
-      "sha256": "f89633c7d12d50ab189edd74ed7c347d299001db6b9a0397f7a98693abaef936"
+      "sha256": "774b17857c2e1701e444296d522e1d36d3a1b4915b63bb86d3bc45d405a51f73"
     },
     "skills/crow-accessibility/SKILL.md": {
       "executable": false,
@@ -716,7 +716,7 @@
       "sha256": "e37132ef8b060548191fbf14a5a18a9dd3acd84ea9a35e802174455b9e374d3d"
     }
   },
-  "revision": "4297812328b55870f4b4e7a9bb3e4e7d4f82e358",
+  "revision": "a0d9e9a088c074f4422b2181ac0629631dbea321",
   "schema_version": 1,
-  "version": "0.15.0"
+  "version": "0.16.1"
 }