@andespindola/crow-skills 0.11.0 → 0.12.0

package/crow_skills/guide.py

@@ -187,17 +187,39 @@ def managed_skills(agent, home, store):
     target = destinations(agent, home)[0]
     rows = store.status([target], ())
     store_ok = store_managed(home, store) if any(r["status"] == "uniflow_link" for r in rows) else set()
-    return sorted(r["name"] for r in rows if r["status"] in ("installed", "modified")
-                  or (r["status"] == "uniflow_link" and r["name"] in store_ok))
+    names = {r["name"] for r in rows if r["status"] in ("installed", "modified")
+             or (r["status"] == "uniflow_link" and r["name"] in store_ok)}
+    from .projection import projected
+    return sorted(names | projected(agent, home, store))  # codex: Uniflow's links in ~/.codex/skills
 
 
-def store_managed(home, store):
-    """Names whose Uniflow store copy is a crow-skills install (a record, files installed or edited).
-    A link to a store entry the user wrote by hand is not a crow-skills install for the CLI."""
+def store_statuses(home, store):
+    """{name: status} of the Uniflow store (crow-skills view); {} when it cannot be read."""
     try:
-        return {r["name"] for r in store.status(destinations("uniflow", home), ()) if r["status"] in ("installed", "modified")}
+        return {r["name"]: r["status"] for r in store.status(destinations("uniflow", home), ()) if r["name"]}
     except (CrowError, OSError):
-        return set()
+        return {}
+
+
+def store_managed(home, store):
+    """Names whose Uniflow store copy is an intact crow-skills install. A link to a store entry the user wrote
+    by hand, or to a managed entry that was edited or lost files (a CLI may fail to load it), does not count
+    as an install for the CLI."""
+    return {n for n, s in store_statuses(home, store).items() if s == "installed"}
+
+
+def store_broken(home, store):
+    """Managed store entries that were edited or lost files (status modified/missing)."""
+    return {n for n, s in store_statuses(home, store).items() if s in ("modified", "missing")}
+
+
+BROKEN_REASON = ("a entrada do store do Uniflow foi editada ou perdeu arquivos; o CLI pode não carregá-la, então não conta "
+                 "como instalada")
+
+
+def broken_fix(name):
+    return ("revise o store e, para restaurá-lo com backup: crow-skills update " + name +
+            " --agents uniflow --global --overwrite-modified --yes")
 
 
 def present_skills(agent, home, store, catalog):

package/crow_skills/hook.py

@@ -27,6 +27,12 @@ live sessions in the same repository, only when there are any; ``--check``
 live session on the same file or clone without writing anything.
 
   crow_hook.py hook --host HOST --event PreToolUse --check [--home DIR]
+
+On Stop and SessionEnd the hook also records the live descendants of the
+session's CLI (pid, start time, executable plus package/script name; never
+arguments) in the crow-broadcast state, and at most every 10 minutes refreshes
+the orphan count (crow-skills resources --orphans) that the memory line cites
+under pressure: one ps call on those events, none on prompts.
 """
 from datetime import datetime, timezone
 import hashlib
@@ -236,11 +242,48 @@ def resource_hint(home):
     if module is None:
         return None
     try:
-        return module.hint(module.probe(home, processes=False, use_cache=True))
+        text = module.hint(module.probe(home, processes=False, use_cache=True))
+        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
     except Exception:  # noqa: BLE001
         return None
 
 
+STOP_EVENTS = ("Stop", "AfterAgent", "PostInvocation", "SessionEnd")
+ORPHAN_REFRESH = 600  # seconds: a Stop event rescans orphans at most this often (it already has the table)
+
+
+def record_processes(home, host, event, ppid=None):
+    """Stop/SessionEnd: record the CLI's live descendants in crow-broadcast state (pid, start,
+    redacted command), so a later orphan check can attribute leftovers to a dead session; and
+    refresh the orphan count the pressure hint reads. One ps call; never raises."""
+    module, probe = broadcast_module(), resources_module()
+    if module is None or probe is None or not hasattr(probe, "read_table") or not hasattr(module, "record_processes"):
+        return None
+    try:
+        cfg = module.config(home)
+        if not cfg["enabled"]:
+            return None
+        rows = probe.read_table()
+        if not rows:
+            return None
+        now = time.time()
+        cli = probe.hook_cli_pid(rows, os.getppid() if ppid is None else ppid)
+        row = next((r for r in rows if r["pid"] == cli), None)
+        if row is None or cli <= 1:
+            return None
+        key = session_key(host, event.get("session"), event.get("cwd"))
+        module.record_processes(home, key, host, cli, probe.start_of(row, now),
+                                probe.session_descendants(rows, cli, now=now), now)
+        if probe.read_orphan_cache(home, max_age=ORPHAN_REFRESH) is None:
+            doc = probe.orphan_scan(home, rows=rows, context=module.process_context(home, cfg, now, event.get("cwd")), now=now)
+            probe.write_orphan_cache(home, doc)
+        return cli
+    except Exception:  # noqa: BLE001 - housekeeping never breaks the event
+        return None
+
+
 # --- event bus ----------------------------------------------------------------------------
 
 def append_event(home, event):
@@ -373,9 +416,12 @@ def update_session(home, event, extra=None, fallback_cwd=None, presence=None):
         if extra:
             snap.update(extra)
         if presence:
-            module, touched, ppid = presence
+            module, touched, ppid = presence[:3]
             try:
-                module.fold(snap, event, touched, ppid=ppid)
+                if len(presence) > 3:  # (…, cli pid resolved from the process table on Stop/SessionEnd)
+                    module.fold(snap, event, touched, ppid=ppid, cli_pid=presence[3])
+                else:
+                    module.fold(snap, event, touched, ppid=ppid)
             except Exception:  # noqa: BLE001 - presence is best effort
                 pass
         write_json(path, snap)
@@ -696,6 +742,15 @@ def handle(host, raw, payload, home, env=None, check=False):
         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:
+        cli = record_processes(home, host, event)
+        if cli and snap is not None:
+            bmod = broadcast_module()
+            if bmod is not None:
+                try:  # the resolved CLI pid becomes the presence pid (a hook's sh -c parent is transient)
+                    update_session(home, dict(stamped, event="other"), presence=(bmod, [], None, cli))
+                except Exception:  # noqa: BLE001
+                    pass
     if module is not None and host in SYNC_TOOL_HOSTS:
         if raw in TOOL_START_EVENTS and (touched or tree or checked):
             return broadcast_check(host, raw, home, module, snap, checked or touched, tree)
@@ -848,6 +903,8 @@ def run_main(args):
             if module is not None:
                 try:
                     module.prune_claims(home)
+                    if hasattr(module, "prune_processes"):
+                        module.prune_processes(home)
                 except Exception:  # noqa: BLE001 - pruning is housekeeping; the output already went out
                     pass
     except Exception:  # noqa: BLE001 - a hook must never break the agent

package/crow_skills/machine.py

@@ -173,6 +173,7 @@ def classify(store, target, names, agent, replace, overwrite, store_names=()):
     pending = set(store_names) if projected else set()
     store_ok = guide.store_managed(store.home, store) if projected else set()
     disabled = store_disabled(store.home, store) if projected else set()
+    broken = guide.store_broken(store.home, store) if projected else set()
     for name in names:
         row = rows.get(name) or {"status": "absent"}
         status = row["status"]
@@ -181,6 +182,9 @@ def classify(store, target, names, agent, replace, overwrite, store_names=()):
         elif status == "uniflow_link" and name in disabled:
             kept.append({"name": name, "status": "uniflow_link_disabled", "reason": DISABLED_REASON,
                          "fix": "reabilite a skill no Uniflow; o crow-skills mantém a desabilitação"})
+        elif status == "uniflow_link" and name in broken:
+            kept.append({"name": name, "status": "uniflow_link_modified", "reason": guide.BROKEN_REASON,
+                         "fix": guide.broken_fix(name)})
         elif status == "uniflow_link":
             kept.append({"name": name, "status": "uniflow_link_unmanaged",
                          "reason": "link do Uniflow para um pacote do store que o crow-skills não gerencia; não conta como instalada",
@@ -240,6 +244,8 @@ def configure_agent(args, home, store, agent, names, dry_run, store_names=()):
     try:
         install, entry["kept"], entry["via_uniflow"], waiting = classify(store, target, names, agent, replace, overwrite,
                                                                 store_names if agent != "uniflow" else ())
+        if agent == "codex":
+            install = codex_projection_step(args, home, store, entry, names, install, waiting, store_names, dry_run)
         if waiting:
             entry["via_uniflow_pending"] = waiting
         if not install:
@@ -272,6 +278,60 @@ def configure_agent(args, home, store, agent, names, dry_run, store_names=()):
     return entry
 
 
+DUPLICATE = "removida: duplicava a projeção do Uniflow"
+
+
+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."""
+    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",
+                                  "fix": guide.broken_fix(name)})
+    projected = projection.projected("codex", home, store)
+    if not projected:
+        return install
+    selected = set(names)
+    # Names on their way into the store reach Codex by the same projection on its next start.
+    pending = (set(store_names) - projected - {"crow-behaviour"}) & set(install)
+    pending = {n for n in pending if n not in entry["unchanged"]}
+    native = {r["name"]: r["status"] for r in store.status([destinations("codex", home)[0]], sorted(pending)) if r["name"]}
+    pending = {n for n in pending if native.get(n, "absent") == "absent"}
+    entry["via_uniflow"] = sorted(set(entry["via_uniflow"]) | (projected & selected) | pending)
+    waiting.extend(sorted(pending))
+    dupes = projection.duplicates(home, store)
+    overwrite = bool(getattr(args, "overwrite_modified", False))
+    remove = [n for n in dupes["remove"] + (dupes["modified"] if overwrite else []) if n in selected]
+    entry["kept"] = [k for k in entry["kept"] if k["name"] not in projected]
+    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",
+                                  "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",
+                                  "fix": "se nenhum outro host precisa dela: crow-skills uninstall " + name +
+                                         " --agents codex,shared --global --yes"})
+    if remove:
+        cli = _cli()
+        argv = ["uninstall", *remove, "--agents", "codex", "--global", "--json", "--home", str(home),
+                "--dry-run" if dry_run else "--yes"]
+        if overwrite:
+            argv.append("--overwrite-modified")
+        argv.append("--no-integrations")  # hooks/trust follow in the install/refresh step, with the run's --no-trust
+        data = cli.run(cli.parser().parse_args(argv))
+        entry["removed"] = [{"name": c["name"], "reason": DUPLICATE} for c in data["changes"] if c["action"] != "unchanged"]
+        entry["removal_transaction"] = data.get("transaction")
+    return [n for n in install if n not in projected and n not in pending]
+
+
 def machine_steps(args, home, store, dry_run):
     steps = {}
     # Crow mode: written as on only when the user never chose (no mode file).
@@ -409,6 +469,8 @@ def summarize(detected, entries, store, home, probe, dry_run, trust=True):
             parts.append(str(unchanged) + " já em dia")
         if entry.get("via_uniflow"):
             parts.append(str(len(entry["via_uniflow"])) + " via uniflow")
+        if entry.get("removed"):
+            parts.append(str(len(entry["removed"])) + (" a remover" if dry_run else " removidas") + " (duplicavam o Uniflow)")
         if kept:
             parts.append(str(len(kept)) + " mantidas")
         item["skills"] = ", ".join(parts) or "—"
@@ -466,7 +528,7 @@ def summarize(detected, entries, store, home, probe, dry_run, trust=True):
         elif kept or state in ("warn", "absent"):
             item["state"] = "warn"
         else:
-            item["state"] = "plan" if dry_run and (entry["changed"] or real_changes(entry.get("integrations"))) else "ok"
+            item["state"] = "plan" if dry_run and (entry["changed"] or entry.get("removed") or real_changes(entry.get("integrations"))) else "ok"
         summary.append(item)
     return summary
 
@@ -497,7 +559,7 @@ def setup(args, home, store, interactive):
     entries, steps = build(True)
     result = {"version": __version__, "revision": source.revision, "skills": names, "detected": detected, "agents": agents,
               "absent": [r["id"] for r in detected if not r["detected"]], "trust": not getattr(args, "no_trust", False)}
-    pending = any(e["changed"] or real_changes(e.get("integrations")) or real_changes(e.get("guides"))
+    pending = any(e["changed"] or e.get("removed") or real_changes(e.get("integrations")) or real_changes(e.get("guides"))
                   for e in entries) or any(s["state"] == "plan" for s in steps.values())
     if dry_run or not agents:
         summary = summarize(detected, entries, store, home, False, True)
@@ -564,11 +626,21 @@ def upgrade_summary(skills, dry_run):
         agent = s["agent"]
         item = {"agent": agent, "label": AGENT_LABELS.get(agent, agent), "changed": s.get("updated") or [],
                 "unchanged": s.get("unchanged", 0), "kept": s.get("kept") or [], "via_uniflow": len(s.get("via_uniflow") or []),
+                "removed": [r["name"] for r in s.get("removed") or []],
                 "needs_user": []}
         for k in item["kept"]:
             if k["status"] in ("modified", "missing"):
                 item["needs_user"].append(k["name"] + " editada localmente; para substituir com backup: crow-skills update " +
                                           k["name"] + " --agents " + agent + " --global --overwrite-modified --yes")
+            elif k["status"] == "duplicate_modified":
+                item["needs_user"].append(k["name"] + " (cópia nativa editada) duplica a projeção do Uniflow no Codex; para remover "
+                                          "com backup: crow-skills setup --agents codex --overwrite-modified --yes")
+            elif k["status"] == "uniflow_link_modified":
+                item["needs_user"].append(k["name"] + ": a entrada do store do Uniflow foi editada ou perdeu arquivos; para "
+                                          "restaurá-la com backup: " + k.get("fix", "crow-skills update " + k["name"] +
+                                          " --agents uniflow --global --overwrite-modified --yes").split(": ", 1)[-1])
+            elif k["status"] == "duplicate_shared":
+                item["needs_user"].append(k["name"] + " duplica a projeção do Uniflow no Codex, mas também é de shared; mantida")
             elif k["status"] == "other_origin":
                 item["needs_user"].append(k["name"] + " instalada de outra origem; para trocar: crow-skills install " +
                                           k["name"] + " --agents " + agent + " --global --yes")
@@ -576,7 +648,7 @@ def upgrade_summary(skills, dry_run):
                 item["needs_user"].append(k["name"] + ": " + k["status"])
         if s.get("error"):
             item["needs_user"].insert(0, s["error"]["message"])
-        item["state"] = "fail" if s.get("error") else ("warn" if item["needs_user"] else ("plan" if dry_run and item["changed"] else "ok"))
+        item["state"] = "fail" if s.get("error") else ("warn" if item["needs_user"] else ("plan" if dry_run and (item["changed"] or item["removed"]) else "ok"))
         rows.append(item)
     return rows
 
@@ -698,8 +770,11 @@ def render_upgrade(data, stream=None):
     rows = []
     for item in data.get("summary", []):
         changed = ", ".join(item["changed"]) if len(item["changed"]) <= 3 else str(len(item["changed"])) + " skills"
+        removed = ((" · " if changed else "") + str(len(item["removed"])) + (" a remover" if dry else " removidas") +
+                   " (duplicavam o Uniflow)") if item.get("removed") else ""
         rows.append([ui.mark(STATE_MARK[item["state"]], stream), item["label"],
-                     (("a atualizar: " if dry else "atualizadas: ") + changed) if changed else "sem mudanças",
+                     ((("a atualizar: " if dry else "atualizadas: ") + changed) if changed else ("" if removed else "sem mudanças"))
+                     + removed,
                      str(item["unchanged"]), str(item.get("via_uniflow", 0)), str(len(item["kept"]))])
     if rows:
         lines.append("")

package/crow_skills/projection.py

@@ -0,0 +1,128 @@
+"""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.
+
+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.
+"""
+import os
+from pathlib import Path
+
+from .agents import destinations, 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."""
+    directory = codex_skills_dir(home)
+    try:
+        if directory.is_symlink() or not directory.is_dir():
+            return {}
+        entries = [p for p in directory.iterdir() if p.name.startswith("crow-") and p.is_symlink()]
+    except OSError:
+        return {}
+    if not entries:
+        return {}
+    store_dir = uniflow_store(home)
+    native = Path(destinations("codex", home)[0]["path"])
+    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):
+            result[name] = "alias"
+        elif (resolved == os.path.realpath(store_dir / name) and (store_dir / name).is_dir()
+              and not (store_dir / name).is_symlink()):
+            state = statuses.get(name)
+            result[name] = {"installed": "managed", "disabled": "disabled", "modified": "modified",
+                            "missing": "modified"}.get(state, "unmanaged")
+        else:
+            result[name] = "other"
+    return result
+
+
+def status_rows(home, store, rows):
+    """Rows for `status`/`doctor`: Codex's view through Uniflow's links, as a destination of its own."""
+    directory = str(codex_skills_dir(home))
+    extra = []
+    for name, kind in sorted(links(home, store).items()):
+        if kind == "managed":
+            extra.append({"name": name, "target": directory, "agents": ["codex"], "status": "uniflow_link", "revision": None,
+                          "activation_verified": False, "projection": "codex_home",
+                          "note": "Link do Uniflow em " + directory + " para o store; é a instalação do codex (via uniflow)."})
+        elif kind == "disabled":
+            extra.append({"name": name, "target": directory, "agents": ["codex"], "status": "disabled", "revision": None,
+                          "activation_verified": False, "projection": "uniflow_link_disabled",
+                          "note": "Desabilitada no Uniflow (SKILL.md.disabled no store); reabilite no Uniflow para usar."})
+        elif kind == "modified":
+            from .guide import BROKEN_REASON, broken_fix
+            extra.append({"name": name, "target": directory, "agents": ["codex"], "status": "modified", "revision": None,
+                          "activation_verified": False, "projection": "uniflow_link_modified",
+                          "note": BROKEN_REASON[0].upper() + BROKEN_REASON[1:] + ". Para corrigir: " + broken_fix(name)})
+        elif kind == "unmanaged":
+            extra.append({"name": name, "target": directory, "agents": ["codex"], "status": "unmanaged", "revision": None,
+                          "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
+
+
+def projected(agent, home, store):
+    """Names Codex already sees through a managed Uniflow projection (empty for other agents)."""
+    if agent != "codex":
+        return set()
+    return {n for n, kind in links(home, store).items() if kind == "managed"}
+
+
+def native_target(agent, target, home):
+    """target is the user-scope codex install dir (not --project/--dest)."""
+    return agent == "codex" and os.path.abspath(target["path"]) == os.path.abspath(destinations("codex", home)[0]["path"])
+
+
+def duplicates(home, store):
+    """Native copies in ~/.agents/skills that duplicate a managed projection, by what can be done with them.
+
+    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."""
+    names = projected("codex", home, store)
+    result = {"remove": [], "modified": [], "shared": []}
+    if not names:
+        return result
+    target = destinations("codex", home)[0]
+    try:
+        rows = {r["name"]: r for r in store.status([target], sorted(names)) if r["name"]}
+        records = store.state(target["path"])["installed"]
+    except (CrowError, OSError):
+        return result
+    for name in sorted(names):
+        row = rows.get(name)
+        if not row or row["status"] not in ("installed", "modified", "missing"):
+            continue  # absent, unmanaged or unreadable: nothing of ours to remove
+        if set(records.get(name, {}).get("agents") or ["codex"]) - {"codex"}:
+            result["shared"].append(name)
+        elif row["status"] == "installed":
+            result["remove"].append(name)
+        else:
+            result["modified"].append(name)
+    return result