@tyroneross/build-loop 0.30.3 → 0.35.0

package/scripts/prune_plugin_cache.py

@@ -17,8 +17,11 @@ from __future__ import annotations
 import argparse
 import json
 import os
+import re
 import shutil
+import subprocess
 import sys
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Literal
 
@@ -31,6 +34,16 @@ Host = Literal["codex", "claude"]
 # "Plugin directory does not exist".
 IN_USE_ENV_VARS: tuple[str, ...] = ("CLAUDE_PLUGIN_ROOT", "CODEX_PLUGIN_ROOT")
 
+# Archive layout: pruned version dirs are MOVED, never deleted, so the
+# session-start healer (scripts/hooks/plugin_dir_heal.py) can move them
+# back if a peer session was pinned to that version. The healer scans
+# <plugins>/removed/<tag>/<plugin>/<version>/ (and the shallower
+# <plugins>/removed/<tag>/<version>/ shape) — `find_archived_match()` —
+# so the layout below MUST stay grandparent-of-cache = parent-of-removed.
+ARCHIVE_PREFIX = "buildloop-prune-"
+ARCHIVE_RETENTION = 5
+REMOVED_DIR_NAME = "removed"
+
 HOST_CONFIG: dict[Host, dict[str, str]] = {
     "codex": {
         "manifest": ".codex-plugin/plugin.json",
@@ -91,14 +104,27 @@ def iter_version_dirs(
     return sorted(versions)
 
 
-def detect_in_use_versions(*, plugin_name: str) -> set[str]:
+def detect_in_use_versions(*, plugin_name: str, scan_peers: bool = True) -> set[str]:
     """Cache version dir name(s) a live host session is currently loaded from.
 
-    Read from the host plugin-root env vars. The path is intentionally NOT
-    resolved: an in-use version dir may itself be a symlink (e.g. a local-dev
-    override pointing at a working tree), and we must protect its *cache* name,
-    not the symlink target's name. Only a path whose parent is this plugin's
-    cache dir counts, so an unrelated env value can't over-protect.
+    Reads:
+      1. THIS process's env vars (CLAUDE_PLUGIN_ROOT / CODEX_PLUGIN_ROOT) —
+         original behaviour; always on.
+      2. PEER live host processes' env (when ``scan_peers``, default on) —
+         covers the multi-session case (cross-terminal Claude + Claude, or
+         Claude + Codex) where another session is bound to a different
+         version of the same plugin. The cross-user fix for
+         `bl-plugin-cache-gc-selfheal`.
+
+    The path is intentionally NOT resolved: an in-use version dir may itself
+    be a symlink (e.g. a local-dev override pointing at a working tree), and
+    we must protect its *cache* name, not the symlink target's name. Only a
+    path whose parent is this plugin's cache dir counts, so an unrelated env
+    value can't over-protect.
+
+    Peer scan is best-effort and fail-open: if ``ps -E`` / ``/proc`` are
+    unavailable or return nothing, we fall back to the current-process scan.
+    Never raises.
     """
     names: set[str] = set()
     for var in IN_USE_ENV_VARS:
@@ -108,9 +134,117 @@ def detect_in_use_versions(*, plugin_name: str) -> set[str]:
         p = Path(root)
         if p.parent.name == plugin_name:
             names.add(p.name)
+    if scan_peers:
+        try:
+            names.update(_detect_peer_in_use_versions(plugin_name=plugin_name))
+        except Exception:  # noqa: BLE001 - fail-open on ANY error
+            pass
     return names
 
 
+# Matches IN_USE_ENV_VARS values in a ps -E / /proc/environ blob. Captures
+# the path up to the first whitespace or NUL byte. Env-var values can't
+# legally contain whitespace via shell export, so this is safe and avoids
+# bleeding into an adjacent var.
+_ENV_VAR_PATTERN = re.compile(
+    r"(?:^|[ \t\0])(" + "|".join(re.escape(v) for v in IN_USE_ENV_VARS) + r")=([^\s\0]+)"
+)
+
+
+def _detect_peer_in_use_versions(*, plugin_name: str) -> set[str]:
+    """Scan peer live processes' environment for CLAUDE_PLUGIN_ROOT /
+    CODEX_PLUGIN_ROOT pinned to ``plugin_name``'s cache. Returns the version
+    dir names found.
+
+    Strategy by platform:
+      - Linux:  read /proc/<pid>/environ for every same-uid process.
+      - macOS:  ``ps -E`` (BSD) prints env vars after the command, restricted
+                to the current user.
+
+    Best-effort. Returns ``set()`` on any failure.
+    """
+    names: set[str] = set()
+    # Linux fast-path: /proc is the most reliable read.
+    proc_root = Path("/proc")
+    if proc_root.is_dir():
+        try:
+            my_uid = os.getuid()
+        except AttributeError:
+            my_uid = None
+        try:
+            entries = list(proc_root.iterdir())
+        except OSError:
+            return names
+        for entry in entries:
+            if not entry.name.isdigit():
+                continue
+            if entry.name == str(os.getpid()):
+                continue
+            if my_uid is not None:
+                try:
+                    if entry.stat().st_uid != my_uid:
+                        continue
+                except OSError:
+                    continue
+            environ_path = entry / "environ"
+            try:
+                blob = environ_path.read_bytes()
+            except OSError:
+                continue
+            try:
+                text = blob.decode("utf-8", errors="replace")
+            except Exception:  # noqa: BLE001
+                continue
+            for match in _ENV_VAR_PATTERN.finditer(text):
+                _name = _version_from_root(match.group(2), plugin_name)
+                if _name:
+                    names.add(_name)
+        return names
+
+    # macOS / BSD: `ps -E` shows env after the command. Restrict to current
+    # user (-u $USER); env-only for other users requires root.
+    user = os.environ.get("USER") or ""
+    cmd: list[str]
+    if user:
+        cmd = ["ps", "-E", "-o", "pid=,command=", "-u", user]
+    else:
+        cmd = ["ps", "-E", "-o", "pid=,command=", "-ax"]
+    try:
+        result = subprocess.run(
+            cmd, capture_output=True, text=True, timeout=2, check=False,
+        )
+    except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
+        return names
+    my_pid = str(os.getpid())
+    for line in result.stdout.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        parts = line.split(None, 1)
+        if not parts:
+            continue
+        if parts[0] == my_pid:
+            continue
+        for match in _ENV_VAR_PATTERN.finditer(line):
+            _name = _version_from_root(match.group(2), plugin_name)
+            if _name:
+                names.add(_name)
+    return names
+
+
+def _version_from_root(root_value: str, plugin_name: str) -> str | None:
+    """Extract the version dir name from an env-var value when it points at
+    a cache dir for ``plugin_name``. Same un-resolved match rule as the
+    current-process detector — protect by NAME, not resolved target.
+    """
+    if not root_value:
+        return None
+    p = Path(root_value)
+    if p.parent.name == plugin_name:
+        return p.name
+    return None
+
+
 def installed_pinned_versions(*, plugin_name: str, host: Host) -> set[str]:
     """Cache version dir names the host has pinned for this plugin across ALL
     scopes/projects, read from its installed_plugins.json. These belong to other
@@ -164,11 +298,75 @@ def classify_versions(
     return keep, stale, skipped
 
 
-def remove_cache_entry(path: Path) -> None:
+def archive_root_for(cache_root: Path) -> Path:
+    """Return the `removed/` sibling of cache_root, matching the layout the
+    SessionStart healer scans. cache_root is `<host>/plugins/cache`, so the
+    removed dir is `<host>/plugins/removed` — one level up + sibling.
+    """
+    return cache_root.parent / REMOVED_DIR_NAME
+
+
+def _archive_tag() -> str:
+    # Microsecond precision so multiple prunes inside one second don't collide.
+    return ARCHIVE_PREFIX + datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
+
+
+def _gc_old_archives(archive_root: Path, retention: int) -> None:
+    """Keep only the newest `retention` `buildloop-prune-*` dirs under
+    archive_root; rmtree older ones. Fail-open: any unreadable entry skipped."""
+    if retention < 0 or not archive_root.is_dir():
+        return
+    try:
+        entries = [p for p in archive_root.iterdir()
+                   if p.is_dir() and p.name.startswith(ARCHIVE_PREFIX)]
+    except OSError:
+        return
+    if len(entries) <= retention:
+        return
+    entries.sort(key=lambda p: p.stat().st_mtime, reverse=True)
+    for stale in entries[retention:]:
+        try:
+            shutil.rmtree(stale)
+        except OSError:
+            continue
+
+
+def remove_cache_entry(
+    path: Path,
+    *,
+    plugin_name: str,
+    archive_root: Path,
+    retention: int = ARCHIVE_RETENTION,
+) -> None:
+    """Retire a cache entry safely.
+
+    Symlinks (local-dev / heal symlinks) → `unlink()` only. The link target is
+    a real dir the host may still need; following or archiving it would risk
+    nuking a live install. The link itself is cheap to recreate.
+
+    Real version dirs → MOVED into
+    `archive_root/buildloop-prune-<UTC-ts>/<plugin>/<basename>/` via atomic
+    `os.rename` (same-fs); cross-fs falls back to `copytree(symlinks=True)` +
+    `rmtree`. Hard delete is removed entirely so the SessionStart healer can
+    restore-from-removed when a peer session was pinned to the version.
+
+    After a successful archive, prune old `buildloop-prune-*` dirs under
+    archive_root down to `retention` so `removed/` does not grow unbounded.
+    """
     if path.is_symlink():
         path.unlink()
         return
-    shutil.rmtree(path)
+    tag_dir = archive_root / _archive_tag() / plugin_name
+    dest = tag_dir / path.name
+    tag_dir.mkdir(parents=True, exist_ok=True)
+    try:
+        os.rename(path, dest)
+    except OSError:
+        # Cross-filesystem move (or other rename refusal) — copy then remove.
+        # symlinks=True preserves any inner symlinks verbatim.
+        shutil.copytree(path, dest, symlinks=True)
+        shutil.rmtree(path)
+    _gc_old_archives(archive_root, retention)
 
 
 def prune_host(
@@ -181,6 +379,7 @@ def prune_host(
     keep_version_override: str | None,
     protect: list[str] | None,
     detect_in_use: bool,
+    scan_peers: bool,
     protect_installed: bool,
     apply: bool,
 ) -> tuple[dict[str, Any], int]:
@@ -189,7 +388,9 @@ def prune_host(
     keep_version = keep_version_override or manifest["version"]
     protected_names: set[str] = set(protect or [])
     if detect_in_use:
-        protected_names.update(detect_in_use_versions(plugin_name=plugin_name))
+        protected_names.update(
+            detect_in_use_versions(plugin_name=plugin_name, scan_peers=scan_peers)
+        )
     if protect_installed:
         protected_names.update(installed_pinned_versions(plugin_name=plugin_name, host=host))
     version_dirs = iter_version_dirs(
@@ -207,12 +408,17 @@ def prune_host(
 
     deleted: list[Path] = []
     errors: list[dict[str, str]] = []
+    archive_root = archive_root_for(cache_root)
     if apply:
         for path in stale:
             try:
-                remove_cache_entry(path)
+                remove_cache_entry(
+                    path,
+                    plugin_name=plugin_name,
+                    archive_root=archive_root,
+                )
                 deleted.append(path)
-            except OSError as exc:
+            except (OSError, shutil.Error) as exc:
                 errors.append({"path": str(path), "error": str(exc)})
 
     return {
@@ -251,6 +457,13 @@ def parse_args() -> argparse.Namespace:
         help="Disable auto-protecting the version dir the running host session is "
         "loaded from (read from CLAUDE_PLUGIN_ROOT / CODEX_PLUGIN_ROOT).",
     )
+    p.add_argument(
+        "--no-scan-peers",
+        action="store_true",
+        help="Don't scan PEER live host processes' env for in-use versions. "
+        "Default-on peer scan protects multi-session pins (Claude + Claude, "
+        "Claude + Codex) so a prune in one session doesn't kill another's hooks.",
+    )
     p.add_argument(
         "--protect-installed",
         action="store_true",
@@ -338,6 +551,7 @@ def main() -> int:
                 keep_version_override=args.keep_version,
                 protect=args.protect,
                 detect_in_use=not args.no_detect_in_use,
+                scan_peers=not args.no_scan_peers,
                 protect_installed=args.protect_installed,
                 apply=args.apply,
             )

package/scripts/sync_navgator_lessons.py

@@ -113,6 +113,26 @@ TOOL = "navgator"
 SOURCE = "migration"  # one-way external import per write_decision taxonomy
 SYNC_ERRORS_LOG = ".build-loop/sync_errors.log"
 
+# One-time-per-process guard for the psycopg-missing warning. The Postgres
+# mirror is OPTIONAL (SQLite is the source of truth); a missing psycopg should
+# degrade gracefully, but it had been failing SILENTLY — only a line in
+# .build-loop/sync_errors.log, which recurred 2026-05-05..2026-06-03 unseen.
+# Surface it ONCE on stderr with the actionable install hint, then stay quiet.
+_PSYCOPG_WARNED = False
+
+
+def _warn_psycopg_missing_once() -> None:
+    global _PSYCOPG_WARNED
+    if _PSYCOPG_WARNED:
+        return
+    _PSYCOPG_WARNED = True
+    _log(
+        "psycopg not installed — skipping the optional Postgres mirror "
+        "(SQLite remains the source of truth). Install with "
+        "`uv pip install -e .[db]` to enable the mirror. "
+        "(This notice prints once per run; details in .build-loop/sync_errors.log.)"
+    )
+
 # Make scripts/ importable as a sibling module (mirrors capture_arch_violation.py).
 HERE = Path(__file__).resolve().parent
 if str(HERE) not in sys.path:
@@ -597,6 +617,11 @@ def main(argv: list[str] | None = None) -> int:
             _append_sync_error(workdir, msg)
             errors.append("postgres_unavailable")
             conn = None
+            # A MISSING psycopg module (vs. a reachable-but-down server) is the
+            # silent recurring case. Surface it visibly, once per run, with the
+            # install hint — don't bury it in the log file again.
+            if isinstance(exc, ModuleNotFoundError) or "psycopg" in str(exc).lower():
+                _warn_psycopg_missing_once()
 
         if conn is not None:
             try:

package/scripts/sync_plugin_cache.py

@@ -33,7 +33,7 @@ if str(HERE) not in sys.path:
 import check_cache_sync as cache_sync  # type: ignore  # noqa: E402
 
 
-EXCLUDE_DIRS = {".git", "node_modules", "__pycache__", ".venv", ".build-loop"}
+EXCLUDE_DIRS = {".git", "node_modules", "__pycache__", ".venv", ".build-loop", ".rally"}
 HOOK_NAMES = ("post-commit", "post-merge", "post-checkout", "post-rewrite")
 HOOK_MARKER = "# --- BEGIN build-loop plugin-cache-sync ---"
 HOOK_MARKER_END = "# --- END build-loop plugin-cache-sync ---"
@@ -80,9 +80,15 @@ def safe_extract_tar(tar_bytes: bytes, target: Path) -> None:
 
 def materialize_head(source: Path) -> tempfile.TemporaryDirectory[str]:
     require_git_head(source)
+    top = Path(run_git(source, ["rev-parse", "--show-toplevel"])).resolve()
+    try:
+        rel = source.resolve().relative_to(top)
+    except ValueError as exc:
+        raise SyncError(f"{source} is not under git toplevel {top}") from exc
+    treeish = "HEAD" if str(rel) == "." else f"HEAD:{rel.as_posix()}"
     proc = subprocess.run(
-        ["git", "archive", "--format=tar", "HEAD"],
-        cwd=str(source),
+        ["git", "archive", "--format=tar", treeish],
+        cwd=str(top),
         stdout=subprocess.PIPE,
         stderr=subprocess.PIPE,
         check=False,
@@ -324,33 +330,28 @@ def print_human(results: list[dict[str, Any]], source_mode: str, materialized_so
                 print(f"    [{diff.get('status')}] {diff.get('path')}")
 
 
-def main(argv: list[str] | None = None) -> int:
-    args = parse_args(argv)
-    source = Path(args.source).expanduser().resolve()
-    if not source.is_dir():
-        print(f"error: source is not a directory: {source}", file=sys.stderr)
-        return 2
+def emit_hook_install(installed: dict[str, Any], args: argparse.Namespace) -> None:
+    if args.json:
+        print(json.dumps(installed, indent=2, sort_keys=True))
+    elif not args.quiet:
+        print(f"installed plugin cache sync hooks for {args.host}:")
+        for hook in installed["hooks"]:
+            print(f"  {hook}")
 
-    try:
-        if args.install_git_hooks:
-            installed = install_git_hooks(source, args.host)
-            if args.json:
-                print(json.dumps(installed, indent=2, sort_keys=True))
-            elif not args.quiet:
-                print(f"installed plugin cache sync hooks for {args.host}:")
-                for hook in installed["hooks"]:
-                    print(f"  {hook}")
-            return 0
 
-        tmp: tempfile.TemporaryDirectory[str] | None = None
-        if args.dirty:
-            source_for_sync = source
-            source_mode = "dirty"
-        else:
-            tmp = materialize_head(source)
-            source_for_sync = Path(tmp.name)
-            source_mode = "head"
+def materialize_source_for_sync(
+    source: Path,
+    args: argparse.Namespace,
+) -> tuple[Path, str, tempfile.TemporaryDirectory[str] | None]:
+    if args.dirty:
+        return source, "dirty", None
+    tmp = materialize_head(source)
+    return Path(tmp.name), "head", tmp
 
+
+def build_sync_payload(source: Path, args: argparse.Namespace) -> dict[str, Any]:
+    source_for_sync, source_mode, tmp = materialize_source_for_sync(source, args)
+    try:
         explicit_host = args.host != "all"
         results = [
             sync_one_host(
@@ -362,25 +363,54 @@ def main(argv: list[str] | None = None) -> int:
             )
             for host in host_list(args.host)
         ]
-        payload = {
+        return {
             "ok": all(result.get("ok", True) for result in results),
             "source": str(source),
             "source_mode": source_mode,
             "materialized_source": str(source_for_sync),
             "results": results,
         }
-        if args.json:
-            print(json.dumps(payload, indent=2, sort_keys=True))
-        elif not args.quiet:
-            print_human(results, source_mode, source_for_sync)
+    finally:
         if tmp is not None:
             tmp.cleanup()
+
+
+def emit_sync_payload(payload: dict[str, Any], args: argparse.Namespace) -> None:
+    if args.json:
+        print(json.dumps(payload, indent=2, sort_keys=True))
+    elif not args.quiet:
+        print_human(
+            payload["results"],
+            payload["source_mode"],
+            Path(payload["materialized_source"]),
+        )
+
+
+def emit_sync_error(exc: SyncError, args: argparse.Namespace) -> None:
+    if args.json:
+        print(json.dumps({"ok": False, "error": str(exc)}, indent=2, sort_keys=True))
+    else:
+        print(f"error: {exc}", file=sys.stderr)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    source = Path(args.source).expanduser().resolve()
+    if not source.is_dir():
+        print(f"error: source is not a directory: {source}", file=sys.stderr)
+        return 2
+
+    try:
+        if args.install_git_hooks:
+            installed = install_git_hooks(source, args.host)
+            emit_hook_install(installed, args)
+            return 0
+
+        payload = build_sync_payload(source, args)
+        emit_sync_payload(payload, args)
         return 0 if payload["ok"] else 1
     except SyncError as exc:
-        if args.json:
-            print(json.dumps({"ok": False, "error": str(exc)}, indent=2, sort_keys=True))
-        else:
-            print(f"error: {exc}", file=sys.stderr)
+        emit_sync_error(exc, args)
         return 2
 
 

package/skills/agent-rally-point/SKILL.md

@@ -19,7 +19,7 @@ is mechanical later.
 |---|---|
 | Substrate package | `${CLAUDE_PLUGIN_ROOT}/scripts/rally_point/` |
 | Host-neutral CLI | `${CLAUDE_PLUGIN_ROOT}/scripts/agent_rally.py` |
-| Slash command | `${CLAUDE_PLUGIN_ROOT}/commands/agent-rally-point.md` |
+| Slash command | `${CLAUDE_PLUGIN_ROOT}/commands/rally-point.md` |
 | Hook adapters | `${CLAUDE_PLUGIN_ROOT}/hooks/session-start-rally-point.sh`, `${CLAUDE_PLUGIN_ROOT}/hooks/pre-edit-rally-point.sh` |
 | Build-loop adapters | `${CLAUDE_PLUGIN_ROOT}/scripts/coordination_status.py`, `${CLAUDE_PLUGIN_ROOT}/scripts/coordination_rally.py`, `${CLAUDE_PLUGIN_ROOT}/scripts/coordination_bootstrap.py` |
 | Boundary manifest | `${CLAUDE_PLUGIN_ROOT}/scripts/rally_point/plugin_boundary.json` |

package/skills/agent-rally-watcher/SKILL.md

@@ -20,7 +20,7 @@ entrypoints thin.
 | Watcher package | `${CLAUDE_PLUGIN_ROOT}/scripts/agent_rally_watcher/` |
 | Compatibility CLI | `${CLAUDE_PLUGIN_ROOT}/scripts/coordination_watch.py` |
 | Status dependency | `${CLAUDE_PLUGIN_ROOT}/scripts/coordination_status.py` |
-| Manual command | `${CLAUDE_PLUGIN_ROOT}/commands/agent-rally-point.md` `watch` subcommand |
+| Manual command | `${CLAUDE_PLUGIN_ROOT}/commands/rally-point.md` `watch` subcommand |
 | Boundary manifest | `${CLAUDE_PLUGIN_ROOT}/scripts/rally_point/plugin_boundary.json` |
 
 ## Operating Rules