@andespindola/crow-skills 0.14.0 → 0.15.0

package/crow_skills/__init__.py

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

package/crow_skills/agents.py

@@ -4,18 +4,47 @@ import os
 import shutil
 from .source import CrowError
 
+# Every destination is the CLI's OWN skills directory. There is no shared folder: the
+# ~/.agents/skills store that codex used until 0.14.0 made crow-skills act on a directory
+# instead of on an agent, which showed up as a phantom "codex,shared" agent and let Codex
+# list the same skill twice (its own dir plus the shared one). LEGACY_SHARED stays named
+# only so an install made there can be found and migrated away.
+LEGACY_SHARED = ".agents/skills"
 AGENTS = {
-    "codex": (".agents/skills", ".agents/skills", "codex"),
+    "codex": (".codex/skills", ".codex/skills", "codex"),
     "claude": (".claude/skills", ".claude/skills", "claude"),
     "gemini": (".gemini/skills", ".gemini/skills", "gemini"),
     "devin": (".config/devin/skills", ".devin/skills", "devin"),
-    "shared": (".agents/skills", ".agents/skills", None),
     # Uniflow keeps one store and links it into each CLI's user skills dir; it has
     # no project scope. The store sits beside config.json (see uniflow_store).
     "uniflow": (".config/uniflow/skills", None, "uniflow"),
 }
 
 
+def codex_home(home):
+    """$CODEX_HOME for the real profile (as Codex resolves it); an isolated --home uses <home>/.codex.
+
+    A RELATIVE $CODEX_HOME is ignored: os.path.abspath would resolve it against this process's cwd,
+    which is not Codex's, so the destination would depend on where the command was run and could
+    land inside the user's repository. Only an absolute (or ~-anchored) value is honoured."""
+    home = Path(home)
+    raw = os.environ.get("CODEX_HOME") if real_home(home) else None
+    if raw:
+        expanded = Path(raw).expanduser()
+        if expanded.is_absolute():
+            return Path(os.path.abspath(expanded))
+    return Path(os.path.abspath(home / ".codex"))
+
+
+def codex_skills_dir(home):
+    return 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))
+
+
 def real_home(home):
     """Environment overrides describe the real profile; an isolated --home ignores them."""
     return home == Path.home().resolve()
@@ -74,6 +103,10 @@ def destinations(names, home, project=None, custom=None):
         # Respect explicit XDG config, but isolate it when --home selects another profile.
         if name == "devin" and not project and real_home(home) and os.getenv("XDG_CONFIG_HOME"):
             path = Path(os.environ["XDG_CONFIG_HOME"]).expanduser() / "devin/skills"
+        # Codex resolves its own home through $CODEX_HOME; the destination must follow it, or an
+        # install would write beside a profile Codex never reads.
+        if name == "codex" and not project:
+            path = codex_skills_dir(home)
         if name == "uniflow":
             path = uniflow_store(home)
         key = str(path.absolute())

package/crow_skills/autoupdate.py

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

package/crow_skills/cli.py

@@ -18,7 +18,7 @@ from . import projection
 from . import resources
 from . import machine
 from . import ui
-from .agents import AGENTS, destinations, inventory
+from .agents import AGENTS, destinations, inventory, legacy_shared_dir
 from .source import CrowError, Source, valid_name
 from .storage import Store, checked
 
@@ -166,6 +166,12 @@ def parser():
                            help="Não aplicar/remover as integrações de interface (status line, tmux) em --global")
         if name != "uninstall":
             child.add_argument("--no-trust", action="store_true", help=TRUST_HELP)
+        if name == "uninstall":
+            # Interno: a migração da pasta compartilhada roda como um uninstall logo depois de um
+            # install, e precisa ficar atrelada a ele para que um rollback do install desfaça os dois.
+            child.add_argument("--linked-to", dest="linked_to", metavar="TXID", default=argparse.SUPPRESS,
+                               help=argparse.SUPPRESS)  # SUPPRESS: ausente não cria atributo, então
+            # uma invocação existente continua parseando com exatamente o mesmo conjunto de atributos.
     child = command_parser(sub, "guide", [common])
     child.add_argument("action", choices=("install", "status", "uninstall"))
     child.add_argument("--replace", action="store_true", help="Autorizar backup e substituição de conteúdo não gerenciado no caminho do guia")
@@ -367,9 +373,9 @@ def guide_sync(args, home, store, command, targets, plan, source):
     return report, gplan
 
 
-def apply_chain(store, plan, gplan, home):
+def apply_chain(store, plan, gplan, home, linked=None):
     """Skills first, then the guide; a failed guide rolls the skills back."""
-    txid = store.apply(plan)
+    txid = store.apply(plan, linked=linked)
     if gplan is None:
         return txid, None
     try:
@@ -716,24 +722,31 @@ def resync_integrations(home, store):
         pass  # Reported by status/doctor; never turns a completed rollback into a failure.
 
 
+def linked_transactions(store, txid):
+    """Committed transactions that COMPLETE the given one and must be undone before it: the guide,
+    and the uninstall that migrated the legacy shared folder after an install."""
+    return [t["id"] for t in store.transactions()
+            if t.get("linked") == txid and t["phase"] == "committed"]
+
+
 def linked_guides(store, txid):
     """Committed guide transactions that completed the given skills transaction."""
     return [t["id"] for t in store.transactions() if t.get("kind") == "guide" and t.get("linked") == txid and t["phase"] == "committed"]
 
 
 # What a native copy means once Uniflow links its store into each CLI's user skills dir.
-# Uniflow links codex into ~/.codex/skills, not into ~/.agents/skills (this CLI's codex root).
+# Every CLI, codex included since 0.15.0, has its skills installed in its OWN dir, the same one
+# Uniflow links into, so a native copy of a name always just wins there (no second directory).
 NATIVE_EFFECT = {
     "claude": "skipped", "gemini": "skipped", "devin": "skipped",
-    "codex": "both",
+    "codex": "skipped",
 }
 
 
 def uniflow_notice(home, store, targets, plan):
     """Installing into the Uniflow store while native crow-* copies remain. Uniflow does
     not link a name a CLI already has in the same dir, so that copy (possibly another
-    revision) wins there; codex reads ~/.agents/skills and Uniflow's ~/.codex/skills
-    link, so it sees both. Report it and the explicit command; never remove anything."""
+    revision) wins there. Report it and the explicit command; never remove anything."""
     if not any("uniflow" in t["agents"] for t in targets):
         return None
     names = sorted({c["name"] for c in plan["changes"] if "uniflow" in c["agents"]})
@@ -765,8 +778,9 @@ def uniflow_notice(home, store, targets, plan):
                 for names_, agents_ in groups.items()]
     return {"native_duplicates": list(native.values()), "uninspected": uninspected,
             "note": "effect=skipped: o Uniflow não cria o link de um nome que o agente já tem nativo, e essa cópia vale no lugar do "
-                    "store. effect=both: o Uniflow liga o store em ~/.codex/skills e o Codex também lê ~/.agents/skills, então vê as "
-                    "duas cópias. Nada foi removido. Remover a cópia nativa de crow-behaviour remove também o guia daquele agente.",
+                    "store. Desde a 0.15.0 nenhum destino produz effect=both: todo CLI instala no diretório dele, o mesmo em que o "
+                    "Uniflow projeta o store, então não há uma segunda raiz em que o mesmo nome apareça de novo. Nada foi removido. "
+                    "Remover a cópia nativa de crow-behaviour remove também o guia daquele agente.",
             "suggested_commands": commands, "suggested_command": " && ".join(commands) if commands else None}
 
 
@@ -803,7 +817,7 @@ def codex_projection_split(home, store, targets, names):
     """The user-scope codex target and which of the names Codex already sees via Uniflow (install skips them)."""
     target = next((t for t in targets if projection.native_target("codex", t, home)), None)
     if target is None or set(target["agents"]) - {"codex"}:
-        return None  # --agents shared: other hosts read that dir without Uniflow's codex projection
+        return None  # a dir shared with another agent is not Codex's own projected dir
     projected = projection.projected("codex", home, store)
     if not projected:
         return None
@@ -946,16 +960,30 @@ def run(args):
                   "mode": hook.read_mode(home), "activation_verified": False,
                   "reload_hint": "Peça ao host para recarregar/listar skills; reinicie a sessão se necessário."}
         if any(projection.native_target("codex", t, home) for t in targets):
-            rows += projection.status_rows(home, store, rows)
+            rows[:] = projection.status_rows(home, store, rows)  # enriquece no lugar; += contaria duas vezes
             dupes = projection.duplicates(home, store)
             names_ = dupes["remove"] + dupes["modified"] + dupes["shared"]
             if names_:
                 # A warning, not unhealthy: both copies are intact and work; Codex just lists them twice.
-                result["warnings"] = [{"code": "codex_duplicates", "skills": names_,
-                                       "message": "O Codex vê " + str(len(names_)) + " skill(s) duas vezes (cópia em ~/.agents/skills "
-                                                  "e link do Uniflow em " + str(projection.codex_skills_dir(home)) + ").",
-                                       "fix": "crow-skills setup --agents codex --yes"
-                                              + (" --overwrite-modified" if dupes["modified"] else "")}]
+                result.setdefault("warnings", []).append({"code": "codex_duplicates", "skills": names_,
+                                       "message": "O Codex vê " + str(len(names_)) + " skill(s) duas vezes: cópia antiga na pasta "
+                                                  "compartilhada " + str(legacy_shared_dir(home)) + " e a instalação em "
+                                                  + str(projection.codex_skills_dir(home)) + ". O crow-skills não usa mais a pasta "
+                                                  "compartilhada; remover as cópias de lá encerra a duplicação.",
+                                       "fix": "crow-skills uninstall " + ",".join(names_) + " --dest "
+                                              + str(legacy_shared_dir(home)) + " --yes"
+                                              + (" --overwrite-modified" if dupes["modified"] else "")})
+            leftovers = [n for n in projection.legacy_leftovers(home, store) if n not in names_]
+            if leftovers:
+                # Sem Uniflow nada disso duplica uma projeção, então o aviso acima nunca apareceria
+                # e uma instalação feita pela 0.14.0 ficaria invisível aqui, ainda carregada pelo Codex.
+                result.setdefault("warnings", []).append(
+                    {"code": "codex_legacy_shared", "skills": leftovers,
+                     "message": "O crow-skills ainda tem " + str(len(leftovers)) + " skill(s) instalada(s) na pasta "
+                                "compartilhada antiga " + str(legacy_shared_dir(home)) + ", que esta versão não usa mais; o "
+                                "Codex continua carregando de lá.",
+                     "fix": "crow-skills setup --agents codex --yes  (instala no diretório do Codex e migra), ou "
+                            "crow-skills uninstall " + ",".join(leftovers) + " --dest " + str(legacy_shared_dir(home)) + " --yes"})
         result["groups"] = group_coverage(rows)
         try:
             result["autoupdate"] = autoupdate.status(store, home) if global_view else None
@@ -983,7 +1011,7 @@ def run(args):
         # on recover, an interrupted guide also undoes the skills it completed.
         follow = []
         if args.command == "rollback":
-            before_ids = [g for txid in ids for g in linked_guides(store, txid)]
+            before_ids = [g for txid in ids for g in linked_transactions(store, txid)]
             ids, transactions = before_ids + ids, [store.journal(t) for t in before_ids] + transactions
         else:
             follow = [t["linked"] for t in transactions if t.get("linked")
@@ -1064,15 +1092,19 @@ def run(args):
         summary["codex_projection"] = {
             "via_uniflow": sorted(codex_view["skip"]), "duplicates": codex_view["duplicates"],
             "note": "O Codex já vê estas skills pelo link do Uniflow em " + str(projection.codex_skills_dir(home)) +
-                    "; nenhuma cópia nativa é criada para o codex. Cópias nativas que duplicam a projeção não são removidas "
-                    "por install; remova-as com o comando sugerido ou rode crow-skills setup --yes.",
-            "suggested_command": ("crow-skills uninstall " + " ".join(codex_view["duplicates"]) + " --agents codex --global")
-            if codex_view["duplicates"] else None}
+                    "; nenhuma cópia é criada para o codex. As cópias que ficaram na pasta compartilhada antiga "
+                    + str(legacy_shared_dir(home)) + " duplicam a projeção e não são removidas por install; remova-as com o "
+                    "comando sugerido ou rode crow-skills setup --yes.",
+            # --dest, nunca --agents codex: esses nomes, no diretório do Codex, são links do Uniflow, e
+            # o uninstall ali recusaria com unsafe_destination.
+            "suggested_command": ("crow-skills uninstall " + " ".join(codex_view["duplicates"]) + " --dest "
+                                  + str(legacy_shared_dir(home)) + " --yes") if codex_view["duplicates"] else None}
     if plan["items"] or (gplan and gplan["items"]) or ui.get("changes"):
         authorize(args, interactive, summary)
     txid = None
     if not getattr(args, "dry_run", False):
-        txid, guides["transaction"] = apply_chain(store, plan, gplan, home)
+        txid, guides["transaction"] = apply_chain(store, plan, gplan, home,
+                                                  linked=getattr(args, "linked_to", None))
         if not ui.get("disabled"):
             # Best effort after the skills/guide transactions; a refusal is reported, never undoes them.
             try:

package/crow_skills/guide.py

@@ -52,7 +52,6 @@ MECHANISMS = {
               "load": "use a ferramenta de skills do Devin ou digite /devin:nome"},
 }
 UNVERIFIED = {
-    "shared": "shared é um diretório de skills, não um CLI; não há onde gravar instruções.",
     "uniflow": "o Uniflow infere o uso de crow-behaviour por padrão e já projeta o store nos agentes; não há guia a gravar.",
 }
 # Shared prompt files (often symlinks into ~/.config/uniflow) and their targets.

package/crow_skills/hook.py

@@ -239,13 +239,20 @@ def broadcast_module():
     return _BROADCAST or None
 
 
-def resource_hint(home):
-    """The one-line memory hint, or None (no pressure, no probe, or any failure)."""
+def resource_hint(home, write_through=True):
+    """The one-line memory hint, or None (no pressure, no probe, or any failure).
+
+    write_through=False for `--probe`: the reading is still taken, but a cache miss must not write
+    resources-cache.json, or "exercise the hook without writing anything" would be false."""
     module = resources_module()
     if module is None:
         return None
     try:
-        text = module.hint(module.probe(home, processes=False, use_cache=True))
+        try:
+            reading = module.probe(home, processes=False, use_cache=True, write_through=write_through)
+        except TypeError:  # crow_resources.py copy older than this hook
+            reading = module.probe(home, processes=False, use_cache=True)
+        text = module.hint(reading)
         if text and hasattr(module, "orphan_hint"):
             text += module.orphan_hint(home)  # last orphan scan, a file read: no ps call per prompt
         return text
@@ -705,7 +712,7 @@ def check_only(host, raw, payload, home):
     return broadcast_check(host, raw, home, module, me, touched, tree)
 
 
-def handle(host, raw, payload, home, env=None, check=False):
+def handle(host, raw, payload, home, env=None, check=False, probe=False):
     """Process one hook call; returns the JSON to print (or None). Never raises to the caller."""
     env = os.environ if env is None else env
     if host not in HOSTS or not isinstance(payload, dict) or foreign(host, payload, env, home):
@@ -714,7 +721,7 @@ def handle(host, raw, payload, home, env=None, check=False):
         return check_only(host, raw, payload, home)
     event = normalise(host, raw, payload)
     current = read_mode(home)
-    if raw in PROMPT_EVENTS:
+    if raw in PROMPT_EVENTS and not probe:
         text = prompt_text(payload)
         match = COMMAND.match(text) if text and len(text) < 64 else None
         if match and host in ("codex", "devin", "agy"):
@@ -756,8 +763,17 @@ def handle(host, raw, payload, home, env=None, check=False):
                 module = None
         except Exception:  # noqa: BLE001 - the broadcast never breaks the event
             module, presence = None, None
-    stamped, snap = record(home, dict(event, mode=current["mode"]), snapshot=True, fallback_cwd=process_cwd(), presence=presence)
-    if raw in STOP_EVENTS:
+    if probe:
+        # Everything a real event would compute, nothing it would write: no event appended, no session
+        # snapshot, no presence. Validating that a CLI's hook is wired must never invent a live session.
+        stamped = dict(event, mode=current["mode"])
+        snap = {"key": session_key(host, event.get("session"), event.get("cwd")), "host": host,
+                "session": event.get("session"), "cwd": event.get("cwd") or process_cwd(),
+                "state": "working", "presence": {}}
+    else:
+        stamped, snap = record(home, dict(event, mode=current["mode"]), snapshot=True, fallback_cwd=process_cwd(),
+                              presence=presence)
+    if raw in STOP_EVENTS and not probe:
         cli = record_processes(home, host, event)
         if cli and snap is not None:
             bmod = broadcast_module()
@@ -786,12 +802,12 @@ def handle(host, raw, payload, home, env=None, check=False):
     stamp = current["mode"] + "@" + str(current["updatedAt"])
     if host in ("codex", "gemini", "devin") and (raw == "SessionStart" or (seen and seen != stamp)):
         system = indicator(current["mode"])  # visible line only at start or when the mode changed
-    if snap is not None and seen != stamp:
+    if snap is not None and seen != stamp and not probe:
         update_session(home, dict(stamped, event="other"), {"modeSeen": stamp, "mode": current["mode"]})
     if raw == "SessionStart":
         return output_for(host, raw, system=system) if system else None
     context = context_line(current["mode"])
-    memory = resource_hint(home)
+    memory = resource_hint(home, write_through=not probe)
     if memory:
         context += "\n" + memory
     if module is not None and snap is not None:
@@ -854,8 +870,8 @@ def fast_hook_args(argv):
         if name in ("--host", "--event", "--home") and i + 1 < len(argv):
             values[name[2:]] = argv[i + 1]
             i += 2
-        elif name == "--check":
-            flags.add("check")
+        elif name in ("--check", "--probe"):
+            flags.add(name[2:])
             i += 1
         else:
             return None
@@ -863,7 +879,7 @@ def fast_hook_args(argv):
         return None
     import types
     return types.SimpleNamespace(command="hook", host=values["host"], event=values["event"], home=values.get("home"),
-                                 check="check" in flags)
+                                 check="check" in flags, probe="probe" in flags)
 
 
 def main(argv=None):
@@ -882,6 +898,8 @@ def parse_args(argv):
     hook.add_argument("--event", required=True)
     hook.add_argument("--home")
     hook.add_argument("--check", action="store_true")
+    # Exercise the hook without side effects: validating a CLI's wiring must not register a session.
+    hook.add_argument("--probe", action="store_true")
     mode = sub.add_parser("mode")
     mode.add_argument("action", nargs="?", default="status", choices=("on", "off", "status", "toggle"))
     mode.add_argument("--home")
@@ -908,11 +926,11 @@ def run_main(args):
     try:
         raw = sys.stdin.buffer.read(MAX_STDIN + 1) if not sys.stdin.isatty() else b""
         payload = json.loads(raw.decode("utf-8")) if raw.strip() and len(raw) <= MAX_STDIN else {}
-        result = handle(args.host, args.event, payload, home, check=args.check)
+        result = handle(args.host, args.event, payload, home, check=args.check, probe=getattr(args, "probe", False))
         if result:
             sys.stdout.write(json.dumps(result, ensure_ascii=False) + "\n")
             sys.stdout.flush()
-        if args.event == "SessionStart" and not args.check:
+        if args.event == "SessionStart" and not args.check and not getattr(args, "probe", False):
             prune_sessions(home)
             module = broadcast_module()
             if module is not None:

package/crow_skills/machine.py

@@ -30,7 +30,7 @@ from . import hook
 from . import integrations
 from . import resources
 from . import ui
-from .agents import destinations, uniflow_config_dir
+from .agents import destinations, legacy_shared_dir, uniflow_config_dir
 from .source import CrowError, Source
 from .storage import Store
 
@@ -251,6 +251,9 @@ def configure_agent(args, home, store, agent, names, dry_run, store_names=()):
         if not install:
             entry.update(refresh_extras(agent, home, dry_run, not getattr(args, "no_trust", False), getattr(args, "source", None),
                                         getattr(args, "ref", None), replace, overwrite))
+            if agent == "codex":
+                # Nada a instalar: o que vale como substituto é o que já está lá (unchanged).
+                migrate_legacy(args, home, store, entry, dry_run, planned=entry["unchanged"])
             return entry
         argv = ["install", *install, "--agents", agent, "--global", "--json", "--home", str(home),
                 "--dry-run" if dry_run else "--yes"]
@@ -275,22 +278,139 @@ def configure_agent(args, home, store, agent, names, dry_run, store_names=()):
     entry["transaction"] = data.get("transaction")
     if data.get("uniflow"):
         entry["uniflow"] = data["uniflow"]
+    if agent == "codex":
+        # Depois da instalação no diretório do Codex, nunca antes: a cópia legada só sai quando
+        # existe uma instalação no lugar novo. Num dry run o disco não foi tocado, então o que este
+        # run instalaria conta como substituto — senão o preview mentiria sobre o apply.
+        migrate_legacy(args, home, store, entry, dry_run,
+                       planned=(entry["changed"] + entry["unchanged"]) if dry_run else ())
     return entry
 
 
 DUPLICATE = "removida: duplicava a projeção do Uniflow"
 
 
+def migrate_legacy(args, home, store, entry, dry_run, planned=()):
+    """legacy_shared_step, but a failure there never costs the agent its result.
+
+    planned: names this run installs (or already has) in the CLI's own dir. In a dry run nothing is
+    written there, so without this the preview would judge every name as "has no replacement" and
+    predict the opposite of what the apply does."""
+    try:
+        legacy_shared_step(args, home, store, entry, dry_run, planned=planned)
+    except (CrowError, OSError, ValueError, KeyError, TypeError) as exc:
+        entry["legacy_shared"] = {"state": "warn", "note": "migração da pasta compartilhada antiga não concluída: " + str(exc),
+                                  "fix": "crow-skills doctor"}
+
+
+def legacy_shared_step(args, home, store, entry, dry_run, planned=()):
+    """Remove what crow-skills left in the legacy shared folder (~/.agents/skills), where codex
+    installed until 0.14.0, now that codex installs in its own dir.
+
+    duplicates() only sees names Uniflow projects, so a copy of a NON-projected skill (the
+    coordinator itself, typically) would otherwise stay there for ever and keep being listed by
+    Codex beside the real install. Only crow-skills-managed, intact copies go, through the normal
+    uninstall (backup, transaction, rollback); an edited copy, or one also recorded for another
+    agent of that dir, is kept and reported. Nothing that crow-skills did not install is touched.
+
+    A copy is removed ONLY when that name really works in Codex's own dir — an intact install of
+    ours, or a healthy Uniflow link. Otherwise the legacy copy is the only working skill Codex has
+    (a broken store entry leaves the link occupying the name in the new dir), and removing it would
+    take the skill away instead of migrating it.
+    """
+    legacy = legacy_shared_dir(home)
+    # Mesmo diretório (inclusive via symlink): não há nada para migrar e avisar seria ruído.
+    if os.path.realpath(legacy) == os.path.realpath(entry["target"]):
+        return
+    if legacy.is_symlink():
+        # Não seguimos symlink para apagar nada, mas quem tem a pasta nos dotfiles precisa saber
+        # que a migração não aconteceu, em vez de supor que aconteceu.
+        entry["legacy_shared"] = {"state": "warn", "action": "skip", "path": str(legacy),
+                                  "note": "a pasta compartilhada antiga é um symlink; nada foi tocado e a migração não "
+                                          "aconteceu. Mova o conteúdo você mesmo ou aponte --dest para o caminho físico."}
+        return
+    if not legacy.is_dir():
+        return
+    target = {"path": str(legacy), "agents": ["codex"]}
+    try:
+        records = store.state(target["path"])["installed"]
+        rows = {r["name"]: r for r in store.status([target], sorted(records)) if r["name"]}
+    except (CrowError, OSError) as exc:
+        entry["legacy_shared"] = {"state": "warn", "note": str(exc), "path": str(legacy)}
+        return
+    # What actually works in Codex's own dir right now: our intact install, or a healthy projection.
+    from . import projection
+    try:
+        own = {r["name"]: r["status"] for r in store.status([destinations("codex", home)[0]], sorted(records)) if r["name"]}
+    except (CrowError, OSError):
+        own = {}
+    try:
+        healthy = {k for k, kind in projection.links(home, store).items() if kind == "managed"}
+    except (CrowError, OSError):
+        healthy = set()
+    # One reason per name: a more specific one already recorded for this name (a broken projection,
+    # an unsafe target) explains it better than anything this step would add.
+    already = {k["name"] for k in entry.get("kept") or []}
+    remove, kept, deferred = [], [], []
+    for name in sorted(records):
+        row = rows.get(name)
+        if not row or row["status"] not in ("installed", "modified", "missing"):
+            continue  # unmanaged, absent or unreadable: not ours to remove
+        if name in already:
+            deferred.append(name)  # já explicado por uma razão mais específica deste mesmo nome
+            continue
+        if own.get(name) != "installed" and name not in healthy and name not in set(planned or ()):
+            kept.append({"name": name, "status": "legacy_shared_without_replacement",
+                         "reason": "a cópia na pasta compartilhada antiga é a única que funciona: no diretório do Codex "
+                                   "este nome não tem instalação íntegra nem projeção saudável do Uniflow",
+                         "fix": "conserte a instalação no diretório do Codex (por exemplo crow-skills setup --agents codex "
+                                "--yes, ou corrija a entrada do store do Uniflow) e rode de novo"})
+            continue
+        others = set(records.get(name, {}).get("agents") or ["codex"]) - {"codex"}
+        if others:
+            kept.append({"name": name, "status": "legacy_shared_of_another_agent",
+                         "reason": "também registrada para " + ",".join(sorted(others)) + " naquele diretório",
+                         "fix": "crow-skills uninstall " + name + " --dest " + str(legacy) + " --yes"})
+        elif row["status"] == "installed":
+            remove.append(name)
+        else:
+            kept.append({"name": name, "status": "legacy_shared_modified",
+                         "reason": "cópia editada na pasta compartilhada antiga",
+                         "fix": "crow-skills uninstall " + name + " --dest " + str(legacy) + " --overwrite-modified --yes"})
+    entry["kept"] += kept
+    if not remove:
+        # Nunca silencioso: se ainda há cópias nossas lá, o resumo diz que a pasta foi olhada e por
+        # que nada saiu — senão não há como auditar uma migração que não aconteceu.
+        if kept or deferred:
+            entry["legacy_shared"] = {"state": "warn", "action": "keep", "path": str(legacy),
+                                      "kept": [k["name"] for k in kept] + deferred}
+        return
+    argv = ["uninstall", *remove, "--dest", str(legacy), "--json", "--home", str(home),
+            "--dry-run" if dry_run else "--yes", "--no-integrations"]
+    if entry.get("transaction"):
+        # Atrelada à transação do install: um rollback dele restaura primeiro estas cópias, em vez
+        # de tirar a instalação nova e deixar o usuário sem nenhuma.
+        argv += ["--linked-to", entry["transaction"]]
+    data = _cli().run(_cli().parser().parse_args(argv))
+    entry["legacy_shared"] = {"state": "ok", "action": "plan" if dry_run else "remove", "path": str(legacy),
+                              "removed": [c["name"] for c in data["changes"] if c["action"] != "unchanged"],
+                              "transaction": data.get("transaction"),
+                              "note": "o crow-skills não usa mais a pasta compartilhada; as cópias de lá foram removidas "
+                                      "(com backup) agora que o codex instala no diretório dele"}
+
+
 def codex_projection_step(args, home, store, entry, names, install, waiting, store_names, dry_run):
-    """Codex sees ~/.codex/skills (Uniflow's links to its store) and ~/.agents/skills (our copies) and lists a
-    same-name skill twice. A name Codex sees via a managed projection gets no native copy, and an intact
-    managed native copy of it is removed through uninstall (backup, transaction, rollback). Returns the
-    names still to install natively."""
+    """Codex sees its own dir (where crow-skills installs and Uniflow links its store) and also the legacy
+    shared ~/.agents/skills, so a copy left there by a version before 0.15.0 is still listed twice. A name
+    Codex sees via a managed projection gets no copy of its own, and an intact managed legacy copy of it is
+    removed through uninstall against that legacy dir (backup, transaction, rollback). Returns the names
+    still to install."""
     from . import projection
     for name, kind in sorted(projection.links(home, store).items()):
         if kind == "modified" and name in names:
             entry["kept"].append({"name": name, "status": "uniflow_link_modified",
-                                  "reason": guide.BROKEN_REASON + "; a cópia nativa em ~/.agents/skills continua valendo",
+                                  "reason": guide.BROKEN_REASON + "; o link do Uniflow ocupa este nome no diretório do "
+                                            "Codex, então conserte a entrada do store",
                                   "fix": guide.broken_fix(name)})
     projected = projection.projected("codex", home, store)
     if not projected:
@@ -310,18 +430,20 @@ def codex_projection_step(args, home, store, entry, names, install, waiting, sto
     for name in dupes["modified"]:
         if name in selected and not overwrite:
             entry["kept"].append({"name": name, "status": "duplicate_modified",
-                                  "reason": "cópia nativa editada que duplica a projeção do Uniflow no Codex",
+                                  "reason": "cópia editada na pasta compartilhada antiga, que duplica a projeção do Uniflow no Codex",
                                   "fix": "revise e, para remover com backup: crow-skills setup --agents codex --overwrite-modified --yes"})
     for name in dupes["shared"]:
         if name in selected:
             entry["kept"].append({"name": name, "status": "duplicate_shared",
-                                  "reason": "cópia nativa também registrada para shared (diretório lido por outros hosts); "
-                                            "mantida, e o Codex a vê duas vezes",
+                                  "reason": "cópia na pasta compartilhada antiga também registrada para outro agente que lê "
+                                            "aquele diretório; mantida, e o Codex a vê duas vezes",
                                   "fix": "se nenhum outro host precisa dela: crow-skills uninstall " + name +
-                                         " --agents codex,shared --global --yes"})
+                                         " --dest " + str(legacy_shared_dir(home)) + " --yes"})
     if remove:
         cli = _cli()
-        argv = ["uninstall", *remove, "--agents", "codex", "--global", "--json", "--home", str(home),
+        # The duplicates live in the legacy shared folder, never in Codex's own dir: --dest targets it
+        # explicitly, since no agent name points there any more.
+        argv = ["uninstall", *remove, "--dest", str(legacy_shared_dir(home)), "--json", "--home", str(home),
                 "--dry-run" if dry_run else "--yes"]
         if overwrite:
             argv.append("--overwrite-modified")
@@ -473,6 +595,16 @@ def summarize(detected, entries, store, home, probe, dry_run, trust=True):
             parts.append(str(len(entry["removed"])) + (" a remover" if dry_run else " removidas") + " (duplicavam o Uniflow)")
         if kept:
             parts.append(str(len(kept)) + " mantidas")
+        legacy = entry.get("legacy_shared") or {}
+        if legacy.get("removed"):
+            # Apagar diretórios do usuário nunca é silencioso: aparece na linha do agente e na nota,
+            # com o caminho, para quem só lê a saída humana saber o que saiu.
+            parts.append(str(len(legacy["removed"])) + (" a tirar" if dry_run else " tiradas") + " da pasta compartilhada antiga")
+            item["notes"].append(("a remover de " if dry_run else "removidas de ") + legacy.get("path", "?") + ": " +
+                                 ", ".join(legacy["removed"]))
+        elif legacy.get("state") == "warn":
+            item["notes"].append("pasta compartilhada antiga " + legacy.get("path", "?") + ": " +
+                                 (legacy.get("note") or ("mantidas " + ", ".join(legacy.get("kept") or []))))
         item["skills"] = ", ".join(parts) or "—"
         guides = entry.get("guides") or {}
         guide_change = next((c for c in guides.get("changes", []) if c.get("agent") == cli["agent"]), None)

package/crow_skills/projection.py

@@ -1,37 +1,31 @@
 """Uniflow's projection of its store into Codex's own skills dir ($CODEX_HOME/skills, default ~/.codex/skills).
 
-Codex scans both $CODEX_HOME/skills and ~/.agents/skills (where crow-skills installs for codex), follows
-symlinks and lists a same-name skill twice when the two entries resolve to different directories. Uniflow
-links ~/.codex/skills/crow-x -> <store>/crow-x, so a native copy in ~/.agents/skills duplicates it.
+Since 0.15.0 crow-skills installs for codex in that same directory, like it does for every other CLI, so a
+managed copy and a projected link can no longer carry the same name in two places. Codex still scans
+~/.agents/skills as well, so a copy left there by an older version is still listed twice: those legacy copies
+are what duplicates() reports, and removing them is the migration away from the shared folder.
 
 A link counts as the codex install of a skill ("via uniflow") only when it resolves to <store>/<name> and
 that store entry is crow-skills-managed (guide.store_managed); a store entry Uniflow disabled is reported as
 disabled; a link to anything else is ignored. A link ~/.codex/skills/crow-x -> ~/.agents/skills/crow-x is an
-alias Codex deduplicates by canonical path: harmless, never touched.
+alias Codex deduplicates by canonical path: never altered nor removed. Note that the LINK being untouched
+does not make the command succeed — that name now lives in the codex destination, and a symlinked entry
+there cannot be managed, so install/setup report it (status "unsafe") and exit 1 until the user resolves it.
 """
 import os
 from pathlib import Path
 
-from .agents import destinations, real_home, uniflow_store
+from .agents import codex_home, codex_skills_dir, destinations, legacy_shared_dir, real_home, uniflow_store
 from .source import CrowError
 
 
-def codex_home(home):
-    """$CODEX_HOME for the real profile (as Codex resolves it); an isolated --home uses <home>/.codex."""
-    home = Path(home)
-    if real_home(home) and os.environ.get("CODEX_HOME"):
-        return Path(os.path.abspath(Path(os.environ["CODEX_HOME"]).expanduser()))
-    return Path(os.path.abspath(home / ".codex"))
-
-
-def codex_skills_dir(home):
-    return codex_home(home) / "skills"
-
-
 def links(home, store):
     """{name: "managed" | "disabled" | "modified" | "unmanaged" | "alias" | "other"} for crow-* symlinks in Codex's own
     skills dir: to an intact managed / Uniflow-disabled / edited-or-incomplete managed / hand-written store entry, to our
-    own copy, or elsewhere. Only "managed" counts as the codex install and allows removing a native duplicate."""
+    legacy shared copy, or elsewhere. Only "managed" counts as the codex install and allows removing a legacy
+    duplicate. "alias" is a link into the legacy ~/.agents/skills: Codex deduplicates it by canonical path, and
+    crow-skills never alters it — but it occupies the name in the destination, so that name is reported
+    unmanageable rather than installed."""
     directory = codex_skills_dir(home)
     try:
         if directory.is_symlink() or not directory.is_dir():
@@ -42,14 +36,16 @@ def links(home, store):
     if not entries:
         return {}
     store_dir = uniflow_store(home)
-    native = Path(destinations("codex", home)[0]["path"])
+    # The alias case is a link into the LEGACY shared folder, never into Codex's own dir (where the link
+    # itself lives): comparing against the destination would now test a link against itself.
+    legacy = legacy_shared_dir(home)
     from .guide import store_statuses
     statuses = store_statuses(home, store)  # only an intact ("installed") store entry is a working codex install
     result = {}
     for link in entries:
         name = link.name
         resolved = os.path.realpath(link)
-        if resolved == os.path.realpath(native / name):
+        if resolved == os.path.realpath(legacy / name):
             result[name] = "alias"
         elif (resolved == os.path.realpath(store_dir / name) and (store_dir / name).is_dir()
               and not (store_dir / name).is_symlink()):
@@ -62,7 +58,13 @@ def links(home, store):
 
 
 def status_rows(home, store, rows):
-    """Rows for `status`/`doctor`: Codex's view through Uniflow's links, as a destination of its own."""
+    """Rows for `status`/`doctor`: Codex's view through Uniflow's links, classified.
+
+    Codex's own dir IS the codex destination since 0.15.0, so `store.status()` already lists these
+    links (as a bare `uniflow_link`). These rows ENRICH the existing one for each name — managed,
+    disabled, edited or unmanaged, each with its reason — and are only appended when the base scan
+    did not report the name. Appending unconditionally would count every projected skill twice.
+    """
     directory = str(codex_skills_dir(home))
     extra = []
     for name, kind in sorted(links(home, store).items()):
@@ -84,7 +86,22 @@ def status_rows(home, store, rows):
                           "activation_verified": False, "projection": "uniflow_link_unmanaged",
                           "note": "Link do Uniflow para um pacote do store que o crow-skills não gerencia; não conta como instalada. "
                                   "Revise o store e, para gerenciá-lo com backup: crow-skills setup --agents uniflow --replace --yes"})
-    return extra
+    return merge_rows(rows, extra, directory)
+
+
+def merge_rows(rows, extra, directory):
+    """Each enriched row replaces the base row of the same name in the same directory; the rest is
+    appended. Returns the merged list (the caller keeps its own list object)."""
+    merged, used = [], set()
+    for row in rows:
+        richer = next((e for e in extra if e["name"] == row.get("name") and row.get("target") == directory), None)
+        if richer is None:
+            merged.append(row)
+            continue
+        used.add(richer["name"])
+        merged.append(dict(row, **{k: v for k, v in richer.items() if k != "revision" or row.get("revision") is None}))
+    merged += [e for e in extra if e["name"] not in used]
+    return merged
 
 
 def projected(agent, home, store):
@@ -99,17 +116,42 @@ def native_target(agent, target, home):
     return agent == "codex" and os.path.abspath(target["path"]) == os.path.abspath(destinations("codex", home)[0]["path"])
 
 
+def legacy_leftovers(home, store):
+    """Names crow-skills still has installed in the legacy shared folder, INDEPENDENT of Uniflow.
+
+    duplicates() answers "what duplicates a projection", so on a machine without Uniflow it is
+    always empty — and an install made by 0.14.0 (which put codex's copies in that folder) would be
+    invisible to status/doctor while Codex kept loading it. This is the signal for that."""
+    legacy = legacy_shared_dir(home)
+    if not legacy.is_dir() or legacy.is_symlink():
+        return []
+    target = {"path": str(legacy), "agents": ["codex"]}
+    try:
+        records = store.state(target["path"])["installed"]
+        if not records:
+            return []
+        rows = {r["name"]: r for r in store.status([target], sorted(records)) if r["name"]}
+    except (CrowError, OSError):
+        return []
+    return sorted(n for n, r in rows.items() if r["status"] in ("installed", "modified", "missing"))
+
+
 def duplicates(home, store):
-    """Native copies in ~/.agents/skills that duplicate a managed projection, by what can be done with them.
+    """Copies left in the legacy shared folder (~/.agents/skills) that Codex lists a second time.
 
-    Returns {"remove": [...], "modified": [...], "shared": [...]}: "remove" are crow-skills-managed and intact;
-    "modified" were edited locally (kept unless --overwrite-modified); "shared" are also recorded for another
-    agent of that dir (shared), which may rely on them."""
+    Codex scans its own dir and ~/.agents/skills; until 0.15.0 crow-skills installed for codex in the
+    latter. A copy still there duplicates what Uniflow projects into Codex's own dir, so it is the thing
+    to migrate away. Returns {"remove": [...], "modified": [...], "shared": [...]}: "remove" are
+    crow-skills-managed and intact; "modified" were edited locally (kept unless --overwrite-modified);
+    "shared" are also recorded for another agent of that dir, which may rely on them."""
     names = projected("codex", home, store)
     result = {"remove": [], "modified": [], "shared": []}
     if not names:
         return result
-    target = destinations("codex", home)[0]
+    legacy = legacy_shared_dir(home)
+    if not legacy.is_dir() or legacy.is_symlink():
+        return result
+    target = {"path": str(legacy), "agents": ["codex"]}
     try:
         rows = {r["name"]: r for r in store.status([target], sorted(names)) if r["name"]}
         records = store.state(target["path"])["installed"]

package/crow_skills/resources.py

@@ -785,9 +785,10 @@ def fixture_reading():
     return data
 
 
-def probe(home, processes=True, use_cache=False, platform=None):
+def probe(home, processes=True, use_cache=False, platform=None, write_through=True):
     """The crow-resources/1 document. use_cache: reuse a reading younger than cacheSeconds
-    (hooks, status lines, snapshot); processes: also scan agent CLI process trees."""
+    (hooks, status lines, snapshot); processes: also scan agent CLI process trees;
+    write_through: refresh the cache file on a miss (false for a side-effect-free probe)."""
     cfg, meta = load_config(home)
     reading, age, cached = None, 0, False
     data = fixture_reading()
@@ -799,7 +800,8 @@ def probe(home, processes=True, use_cache=False, platform=None):
         cached = reading is not None
     if reading is None:
         reading = read_machine(platform)
-        write_cache(home, reading)
+        if write_through:
+            write_cache(home, reading)
     agents = read_processes(platform) if processes else None
     return build(reading, cfg, meta, agents, cached, age)
 

package/crow_skills/storage.py

@@ -177,6 +177,8 @@ class Store:
         try:
             if data["id"] != txid or data["phase"] not in ("prepared", "restoring", "committed", "rolled_back"):
                 raise ValueError("phase")
+            if "linked" in data and not re.fullmatch(r"[a-f0-9]{32}", data["linked"] or ""):
+                raise ValueError("linked")
             targets = data["before"]
             if not isinstance(targets, dict) or set(targets) != set(data["after"]):
                 raise ValueError("targets")
@@ -344,7 +346,11 @@ class Store:
                     }
         return {"before": before, "after": after, "items": items, "packages": packages, "changes": output}
 
-    def apply(self, plan):
+    def apply(self, plan, linked=None):
+        """linked: a committed transaction this one completes, so a rollback of that one undoes this
+        one first. Used by the migration out of the legacy shared folder, which runs as its own
+        uninstall right after an install: without the link, rolling back the install alone would
+        remove the new copies while the legacy ones stayed removed, leaving the user with none."""
         if not plan["items"]:
             return None
         with self.lock():
@@ -359,6 +365,8 @@ class Store:
             txid = uuid.uuid4().hex
             data = {k: plan[k] for k in ("before", "after", "items")}
             data.update(id=txid, phase="prepared", created_at=datetime.now(timezone.utc).isoformat())
+            if linked:
+                data["linked"] = linked
             journal = self.root / "transactions" / (txid + ".json")
             try:
                 for target in plan["before"]:

package/crow_skills/ui.py

@@ -160,7 +160,7 @@ FIXES = {
     "unmanaged_conflict": "revise o conteúdo; para substituir com backup, acrescente --replace",
     "unmanaged_link": "acrescente --replace para trocar só o link por uma cópia gerenciada",
     "guide_requires_skill": "crow-skills setup --yes",
-    "unknown_agent": "use --agents com: claude, codex, gemini, devin, shared, uniflow",
+    "unknown_agent": "use --agents com: claude, codex, gemini, devin, uniflow (um diretório fora desses: --dest)",
     "unknown_group": "crow-skills groups  (lista os grupos; todas = catálogo inteiro)",
     "source_mismatch": "use install com --source para trocar de origem",
     "unsupported_platform": "agende crow-skills upgrade --yes por conta própria (ex.: cron)",

package/docs/cli.md

@@ -18,7 +18,7 @@ crow-skills init --yes                            # alias
 | CLI | Binário | Configuração | Agente do instalador |
 |---|---|---|---|
 | Claude Code | `claude` | `~/.claude` | claude |
-| Codex CLI | `codex` | `~/.codex` | codex (`~/.agents/skills`) |
+| Codex CLI | `codex` | `~/.codex` | codex (`$CODEX_HOME/skills`, padrão `~/.codex/skills`) |
 | Gemini CLI | `gemini` | `~/.gemini/settings.json` | gemini |
 | Antigravity | `agy` | `~/.gemini/antigravity-cli` | gemini (mesmo diretório de skills; hooks e status line próprios) |
 | Devin CLI | `devin` | `~/.config/devin` (ou XDG) | devin |
@@ -183,14 +183,13 @@ Erros retornam `ok:false` e `error.code/message`. Saídas reais incluem alteraç
 
 | Adaptador | Usuário | Projeto |
 |---|---|---|
-| codex | `~/.agents/skills` | `.agents/skills` |
+| codex | `$CODEX_HOME/skills` (padrão `~/.codex/skills`) | `.codex/skills` |
 | claude | `~/.claude/skills` | `.claude/skills` |
 | gemini | `~/.gemini/skills` | `.gemini/skills` |
 | devin | `~/.config/devin/skills` (ou XDG_CONFIG_HOME) | `.devin/skills` |
-| shared | `~/.agents/skills` | `.agents/skills` |
 | uniflow | store do Uniflow: `~/.config/uniflow/skills` (veja [Uniflow](#uniflow)) | não existe; recusado com `unsupported_scope` |
 
-Codex/shared são deduplicados quando apontam para o mesmo diretório. O diretório compartilhado também pode ser lido por outros hosts; não é isolamento entre agentes. `.codex/skills` é uma localização legada encontrada em ambientes existentes; o adaptador usa a localização moderna documentada. Para um destino legado específico, use `--dest` explicitamente.
+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.
 
 `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.
 
@@ -214,18 +213,31 @@ O Uniflow guarda as skills num store próprio e cria, ao subir cada CLI, links d
 - Só `--global`: o Uniflow não tem store de projeto (`--project` falha com `unsupported_scope`).
 - Sem guia: o Uniflow infere o uso da crow-behaviour por conta própria, então `guide` recusa `uniflow` (`unsupported_guide`) e `install` informa isso em `guides.skipped`. Integrações de interface também não se aplicam.
 - Detecção: `agents` marca `detected` quando `uniflow` está no PATH (`executable_found`) ou o diretório de configuração existe (`config_found`).
-- 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`). No codex é pior: o crow-skills instala em `~/.agents/skills`, o Uniflow liga o store em `~/.codex/skills` e o Codex lê os dois, vendo duas skills de mesmo nome (`effect: both`). `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.
+- 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`.
 
+#### 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.
+
+Sem isso, validar um hook rodando-o de verdade registra uma sessão com o `session_id` usado no teste. Essa sessão falsa conta como viva para TODOS os outros agentes da máquina pela janela de `stale_minutes` (30 min por padrão): entra na contagem do bloco, na relevância por repositório e nos avisos de "não troque de branch neste clone". Uma validação dos cinco CLIs chega a inventar dez ou mais sessões `working`.
+
 #### Codex e a projeção do Uniflow
 
-O Codex lê duas raízes de skills do usuário: `$CODEX_HOME/skills` (padrão `~/.codex/skills`, onde o Uniflow liga o store) e `~/.agents/skills` (onde o crow-skills instala para o codex). Ele segue symlinks e lista duas vezes uma skill de mesmo nome quando as duas entradas apontam para diretórios diferentes. Por isso:
+O Codex lê duas raízes de skills do usuário: `$CODEX_HOME/skills` (padrão `~/.codex/skills`, onde o crow-skills instala e o Uniflow liga o store) e a legada `~/.agents/skills`, onde o crow-skills instalava para o codex até a 0.14.0. Ele segue symlinks e lista duas vezes uma skill de mesmo nome quando as duas entradas apontam para diretórios diferentes — hoje isso só acontece com uma cópia deixada na pasta legada. Instalar no diretório do próprio Codex é seguro ao lado do Uniflow: ele não sobrescreve um nome que já existe ali (registra `skipped`) e só apaga um diretório que tenha o marcador `.uniflow-store.json`, que apenas ele escreve. Por isso:
 
 - Um link `~/.codex/skills/crow-x` → `<store>/crow-x`, com a entrada do store gerenciada pelo crow-skills, conta como a instalação do codex (`via uniflow`). Entrada desabilitada no Uniflow aparece como `disabled`; entrada escrita à mão, como não gerenciada (com o mesmo motivo e correção do resto do Uniflow). `CODEX_HOME` vale para o perfil real; `--home` isolado usa `<home>/.codex`.
-- `setup` e `upgrade` não criam cópia nativa em `~/.agents/skills` para esses nomes e removem, pelo `uninstall` normal (backup, transação, `rollback`), as cópias nativas gerenciadas e intactas que duplicam a projeção (`removida: duplicava a projeção do Uniflow`). Uma cópia editada fica, com aviso e a dica `--overwrite-modified`. Uma cópia também registrada para `shared` (`--agents codex,shared`: o diretório é lido por outros hosts) fica, porque outro host pode depender dela; o motivo e o comando aparecem no resumo.
-- `install --agents codex` não cria cópia nativa de um nome projetado (`codex_projection.via_uniflow` no resumo) e nunca remove nada: as duplicatas existentes aparecem em `codex_projection.duplicates`, com `suggested_command`. Com `--agents codex,shared` instala como antes.
+- `setup` e `upgrade` não criam cópia própria para esses nomes e removem, pelo `uninstall` normal contra a pasta legada (`--dest ~/.agents/skills`, com backup, transação e `rollback`), as cópias gerenciadas e intactas que ficaram lá duplicando a projeção (`removida: duplicava a projeção do Uniflow`). Uma cópia editada fica, com aviso e a dica `--overwrite-modified`. Uma cópia também registrada para outro agente daquele diretório fica, porque outro host pode depender dela; o motivo e o comando (`uninstall ... --dest ~/.agents/skills`) aparecem no resumo.
+- `install --agents codex` não cria cópia de um nome projetado (`codex_projection.via_uniflow` no resumo) e nunca remove nada: as cópias legadas aparecem em `codex_projection.duplicates`, com `suggested_command`. `--agents shared` não existe mais e é recusado com `unknown_agent`; para gravar num diretório específico, use `--dest`.
 - 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.
-- Um link `~/.codex/skills/crow-x` → `~/.agents/skills/crow-x` é só um apelido (o Codex o deduplica pelo caminho canônico): nunca é alterado nem removido.
+- 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.
+- **`$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>`).
+- **Rollback encadeado.** A migração roda como um `uninstall` próprio logo depois do install e fica atrelada a ele (campo `linked` no journal da transação). Um `rollback` da transação do install desfaz PRIMEIRO a migração, restaurando as cópias legadas, e só então remove a instalação nova: o estado final é o anterior ao comando. Sem esse encadeamento, desfazer só o install deixaria as duas pastas vazias.
+- Um link `~/.codex/skills/crow-x` → `~/.agents/skills/crow-x` (apontando para a pasta legada) é só um apelido (o Codex o deduplica pelo caminho canônico): nunca é alterado nem removido.
 - `status`/`doctor` mostram `~/.codex/skills` como um destino do codex (`N skills (N via uniflow)`). Duplicatas geram o aviso `codex_duplicates` (`warnings`) com o comando que resolve; o doctor continua `healthy:true`, porque as duas cópias estão íntegras e funcionam (o Codex só as lista duas vezes).
 
 
@@ -246,7 +258,7 @@ crow-skills guide uninstall --agents codex --global --yes
 
 Aplicação automática (padrão em `install`, `update` e `uninstall` com `--global`, desligada por `--no-guide`):
 
-- O guia é planejado junto com as skills, a partir do conjunto de skills que o agente terá depois do comando, e conferido antes de gravar qualquer coisa. Install/update que deixam a crow-behaviour instalada aplicam o guia ou o regeneram; mudança de outra skill gerenciada regenera um guia já instalado (também quando a mudança chega pelo diretório compartilhado `~/.agents/skills`, que é o do codex). Uninstall da crow-behaviour remove o guia, devolvendo o arquivo que `--replace` havia deslocado; uninstall de outra skill regenera o guia instalado e nunca cria um novo.
+- O guia é planejado junto com as skills, a partir do conjunto de skills que o agente terá depois do comando, e conferido antes de gravar qualquer coisa. Install/update que deixam a crow-behaviour instalada aplicam o guia ou o regeneram; mudança de outra skill gerenciada regenera um guia já instalado (também quando a mudança chega pelo diretório do codex). Uninstall da crow-behaviour remove o guia, devolvendo o arquivo que `--replace` havia deslocado; uninstall de outra skill regenera o guia instalado e nunca cria um novo.
 - Recusa do guia (arquivo não gerenciado sem `--replace`, guia editado/ausente sem `--overwrite-modified`, chave `developer_instructions` alheia, symlink, hard link, prompt compartilhado ou Uniflow) falha o comando inteiro, com código do guia e sugestão de `--replace`, `--overwrite-modified` ou `--no-guide`, sem gravar skills nem guia. Em install/update, `--replace` e `--overwrite-modified` valem para skills e guia.
 - `shared`, `uniflow`, `--project` e `--dest` não têm mecanismo: o comando segue e informa em `guides.skipped`. Sem Python 3.11+ (tomllib), o guia do codex também é pulado e informado.
 - `--dry-run` inclui `guides.changes` e `guides.preview` (conteúdo que seria gravado). A saída JSON traz `guides` com `changes`, `skipped`, `revision` e `transaction`.
@@ -527,6 +539,6 @@ Cada execução:
 
 1. Atualiza o próprio crow-skills conforme a instalação: Homebrew (`brew upgrade andersonflima/tap/crow-skills`), npm global (`npm install -g @andespindola/crow-skills@latest`). Checkout Git só com `autoupdate on --git-pull`, e só se estiver limpo em `main`/`master` (`git pull --ff-only`); caso contrário, é pulado com o motivo. Saída de brew/npm/git não é guardada nem impressa, só código de saída e versões.
 2. Se a versão mudou, a versão nova (o launcher) faz o passo seguinte, para usar o snapshot novo como fonte.
-3. Para cada agente com skills gerenciadas (claude, codex/`~/.agents/skills`, gemini, devin, uniflow), roda o equivalente a `update <skills> --agents <agente> --global --yes`: regenera guia, integrações e hooks; a [identidade do pacote](#origem-e-versões) evita `source_mismatch` depois do upgrade. Skills editadas localmente (`modified`), ausentes ou instaladas de outra origem (`other_origin`, por exemplo de um clone Git) ficam como estão e aparecem em `kept`; nada é sobrescrito. Uma reaplicação dos hooks troca as entradas do crow-skills no lugar, sem mudar a posição das suas. Uma recusa num agente (por exemplo, guia editado) aparece em `error` e não interrompe os outros.
+3. Para cada agente com skills gerenciadas (claude, codex/`$CODEX_HOME/skills`, gemini, devin, uniflow), roda o equivalente a `update <skills> --agents <agente> --global --yes`: regenera guia, integrações e hooks; a [identidade do pacote](#origem-e-versões) evita `source_mismatch` depois do upgrade. Skills editadas localmente (`modified`), ausentes ou instaladas de outra origem (`other_origin`, por exemplo de um clone Git) ficam como estão e aparecem em `kept`; nada é sobrescrito. Uma reaplicação dos hooks troca as entradas do crow-skills no lugar, sem mudar a posição das suas. Uma recusa num agente (por exemplo, guia editado) aparece em `error` e não interrompe os outros.
 
 O resultado fica em `~/.local/state/crow-skills/autoupdate/state.json` (`lastRun` e as últimas 20 execuções), aparece em `autoupdate status`, em `status`/`doctor` (doctor `healthy:false` se a última execução falhou ou o agendador foi alterado/removido) e em `events snapshot`. Duas execuções simultâneas são recusadas (`busy`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andespindola/crow-skills",
-  "version": "0.14.0",
+  "version": "0.15.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": "f246c05e18f6f675c3819d7a9f59e592f8b5da30e46c811f5d9a145aa004eea2"
+      "sha256": "26eaa6dfbdfbc6e83983270615e53556227560f236d3064f8fb596bbfceebf0c"
     },
     "crow_skills/__main__.py": {
       "executable": false,
@@ -28,12 +28,12 @@
     "crow_skills/agents.py": {
       "executable": false,
       "kind": "file",
-      "sha256": "b14c37d2f1becfe38c74411fc413608b375c05bd6961a0757e3ec085ec2e1f66"
+      "sha256": "0f8a284d5ce6dfc8c55a81be861c56c1884156937ecbce3a8800aef4ade76496"
     },
     "crow_skills/autoupdate.py": {
       "executable": false,
       "kind": "file",
-      "sha256": "bbe3c38f93d8f6e70c0ec428e3d383d7248c61c07c774420c4c47e27c7e9def5"
+      "sha256": "8de4a6f3f7ce773dafb4c4f9b217d399becbd98b0b0638a80e27e13450e3a0f6"
     },
     "crow_skills/broadcast.py": {
       "executable": false,
@@ -43,7 +43,7 @@
     "crow_skills/cli.py": {
       "executable": false,
       "kind": "file",
-      "sha256": "f38bfcede958343266e1a6f3ac061e4321c04a4e264e5b96a91d93bb357b28a4"
+      "sha256": "5a1146f2d6c14554384bc13f0e2f83b3e5ce4b2743dd8a3fee70db3c2f5db9b1"
     },
     "crow_skills/events.py": {
       "executable": false,
@@ -58,12 +58,12 @@
     "crow_skills/guide.py": {
       "executable": false,
       "kind": "file",
-      "sha256": "0d6fd0a026954f8d9b72bafcad204f1929f3b96f89f84e0bea1c0c5deda91cdc"
+      "sha256": "aa8c16b293a72d6aabd99246a3666e40beaa81d5c1b77e6389341eca463e6a7f"
     },
     "crow_skills/hook.py": {
       "executable": false,
       "kind": "file",
-      "sha256": "526f7a7acf7c9e433d7c986c94aaa39d1603813107387601f27859a473ce6f52"
+      "sha256": "3a2b3df94cbd655f88f087a60640c016a5669c06657e97236c841ae19c3a3257"
     },
     "crow_skills/integrations.py": {
       "executable": false,
@@ -73,7 +73,7 @@
     "crow_skills/machine.py": {
       "executable": false,
       "kind": "file",
-      "sha256": "f48bb54b7816ce0fc62e68694dd970f699d355e60db2fb2eab651291294c7012"
+      "sha256": "8b7187afae9ad85369fdc8a918e19b32bab9d95776246cda6670a963dff19df3"
     },
     "crow_skills/npm_entry.py": {
       "executable": false,
@@ -88,12 +88,12 @@
     "crow_skills/projection.py": {
       "executable": false,
       "kind": "file",
-      "sha256": "0f6a7c788e58cc54752bbf293f107a2a8e731cacefa2dcd95d3f4998f2866d4a"
+      "sha256": "927cabbdde134c5c504abf6e762026295e6a7a38e8bee1f45a608d21b716be4a"
     },
     "crow_skills/resources.py": {
       "executable": false,
       "kind": "file",
-      "sha256": "871e3834c342ee52e98a0999c679a8f329d7bc6d71d3008b21d08c806d39a7c3"
+      "sha256": "8cb3fe3a24ebd1d84d2c8b135f4c10b76928b3b94d5aa921c847855edb6213a6"
     },
     "crow_skills/source.py": {
       "executable": false,
@@ -103,7 +103,7 @@
     "crow_skills/storage.py": {
       "executable": false,
       "kind": "file",
-      "sha256": "e3a7a41bcb3aa52530bbc1770165308b61a42017a8d8962fdb6a271ce2b5188f"
+      "sha256": "92b7b76ed75e84901dc2a67df3bb6998558200041bc42c8597e708829541a5b1"
     },
     "crow_skills/trust.py": {
       "executable": false,
@@ -113,7 +113,7 @@
     "crow_skills/ui.py": {
       "executable": false,
       "kind": "file",
-      "sha256": "72f0ce4f47d5d3225ee30fe116b2b359bef3c426f5366d51782fa66eeedcc094"
+      "sha256": "24b5cb9aea11603db79c6c10628952263c265251f737cc3621db6872f8c15a91"
     },
     "docs/cli-security.md": {
       "executable": false,
@@ -123,12 +123,12 @@
     "docs/cli.md": {
       "executable": false,
       "kind": "file",
-      "sha256": "88d12559d02a8266f832e25ff66f9494c7c68822d5a5a1101f65d289089a4d3c"
+      "sha256": "9dd1b9cc567e01356ead3d667b3ea559534d44930dffaa9dff7808e3476f25a3"
     },
     "package.json": {
       "executable": false,
       "kind": "file",
-      "sha256": "62aad546f7a29256d2769ffb7741dd3911c048efa9147d70305b14aea0ad32a5"
+      "sha256": "f89633c7d12d50ab189edd74ed7c347d299001db6b9a0397f7a98693abaef936"
     },
     "skills/crow-accessibility/SKILL.md": {
       "executable": false,
@@ -716,7 +716,7 @@
       "sha256": "e37132ef8b060548191fbf14a5a18a9dd3acd84ea9a35e802174455b9e374d3d"
     }
   },
-  "revision": "7f30848161287f341f72a4302f4ea685a2dab610",
+  "revision": "4297812328b55870f4b4e7a9bb3e4e7d4f82e358",
   "schema_version": 1,
-  "version": "0.14.0"
+  "version": "0.15.0"
 }