@arbiterforge/ca-pi 0.8.1 → 0.10.2

package/plugins/ca-pi/hooks/_updatelib.py

@@ -5,15 +5,17 @@
 # auto-update by default (only official Anthropic marketplaces get that). This
 # module backs a lightweight notifier so a stale install is surfaced instead of
 # running forever unnoticed: it reads the installed plugin.json version, reads
-# a small user-global cache of the latest published GitHub release, and — when
-# the cache says a newer version exists — hands back a single notice line. Both
+# a small user-global cache keyed by independently versioned release target,
+# and — when that target's cache says a newer version exists — hands back a
+# single host-native notice line. Both
 # SessionStart and the statusline render from that SAME cache; neither makes a
 # network call on its own hot path (issue #194's constraint).
 #
 # The only network call this module makes (fetch_latest_tag) is invoked from
 # the OFF-hot-path detached refresh (see hooks/update-refresh.py, spawned by
 # session-start.py). refresh_if_stale() gates that call to at most once per
-# day via the cached `checked_at`, and is fail-silent end to end: any network
+# day per target via the cached `checked_at`, and is fail-silent end to end:
+# any network
 # error, timeout, non-200, or unparseable body degrades to "keep the last-known
 # latest" — never a traceback, never a crash of the host hook.
 #
@@ -34,18 +36,24 @@
 #   parse_version(s) -> tuple|None           numeric-tuple parse; None if malformed/absent
 #   version_gt(a, b) -> bool                 True iff semver a > b (numeric-tuple compare)
 #   update_available(installed, latest) -> bool   True iff latest > installed
-#   notice_line(installed, latest) -> str|None    the SessionStart/statusline notice text
-#   read_state(path=None) -> dict            {latest, checked_at} cache, or {} on any failure
+#   update_descriptor(host=None) -> dict|None validated host update descriptor
+#   target_state(state, host=None) -> dict    one target's cache row, or {}
+#   notice_line(installed, latest, host=None) -> str|None host-native notice text
+#   read_state(path=None) -> dict            target-keyed cache, or {} on any failure
 #   write_state(state, path=None) -> None    atomic cache write; best-effort, never raises
 #   is_stale(checked_at, now, interval=ONE_DAY) -> bool   True iff a refresh is due
-#   fetch_latest_tag(url=UPDATE_API_URL, timeout=3.0, opener=None) -> str|None   HTTPS GET, fail-silent
-#   refresh_if_stale(now=None, fetcher=None, path=None) -> dict   best-effort cache refresh
+#   select_latest_tag(releases, tag_prefix) -> str|None target-series selection
+#   fetch_latest_tag(tag_prefix=None, url=..., timeout=3.0,
+#                    opener=None, host=None) -> str|None
+#   refresh_if_stale(now=None, fetcher=None, path=None, host=None) -> dict
 
 import json
+import math
 import os
 import re
 import sys
 import time
+import urllib.parse
 import urllib.request
 
 # Reuse the ONE atomic-write helper defined in _hooklib.py (same rationale as
@@ -54,16 +62,23 @@ import urllib.request
 _HOOKS_DIR = os.path.dirname(os.path.abspath(__file__))
 if _HOOKS_DIR not in sys.path:
     sys.path.insert(0, _HOOKS_DIR)
-from _hooklib import get_host, write_text_atomic  # noqa: E402 — sys.path mount above
+from _hooklib import (  # noqa: E402 — sys.path mount above
+    acquire_lock,
+    get_host,
+    release_lock,
+    write_text_atomic,
+)
 # hostapi is not imported directly here (#257): plugin_root()/installed_version()
 # resolve the Host via _hooklib.get_host() (the DI seam every entry script's
 # run(host) primes via set_host()), never a fresh hostapi.load_host().
 
 ONE_DAY = 24 * 60 * 60
 
-# The repo's own GitHub Releases API — unauthenticated GET, HTTPS only (ADR-0003).
-# The release tag equals plugin.json's version (an established repo invariant).
-UPDATE_API_URL = "https://api.github.com/repos/arbiterForge/codeArbiter/releases/latest"
+# The repo's GitHub Releases collection — unauthenticated GET, HTTPS only
+# (ADR-0003). A collection is required because each host publishes an
+# independent tag series; /releases/latest can represent only one of them.
+UPDATE_API_URL = "https://api.github.com/repos/arbiterForge/codeArbiter/releases?per_page=100"
+MAX_RELEASE_PAGES = 10
 
 _VERSION_STRIP_RE = re.compile(r"^[vV]")
 
@@ -147,21 +162,58 @@ def update_available(installed, latest):
     return version_gt(latest, installed)
 
 
-def notice_line(installed, latest):
+def update_descriptor(host=None):
+    """Validated update descriptor for `host` (or the active host), else None.
+    A partially defined or multi-line descriptor disables the notifier rather
+    than falling back to another host's release series or command."""
+    host = host or get_host()
+    target = getattr(host, "update_target", None)
+    prefix = getattr(host, "update_tag_prefix", None)
+    command = getattr(host, "update_command", None)
+    if not all(isinstance(value, str) and value.strip()
+               for value in (target, prefix, command)):
+        return None
+    if not re.fullmatch(r"[a-z][a-z0-9-]*", target.strip()):
+        return None
+    if "\n" in command or "\r" in command:
+        return None
+    return {
+        "target": target.strip(),
+        "tag_prefix": prefix.strip(),
+        "command": command.strip(),
+    }
+
+
+def target_state(state, host=None):
+    """The active host target's `{latest, checked_at}` row, or {}.
+    Legacy unkeyed cache data is deliberately not attributed to any host: its
+    `latest` may belong to an unrelated release series (the RA-02 defect)."""
+    descriptor = update_descriptor(host)
+    if descriptor is None or not isinstance(state, dict) or state.get("schema") != 1:
+        return {}
+    targets = state.get("targets")
+    if not isinstance(targets, dict):
+        return {}
+    row = targets.get(descriptor["target"])
+    return row if isinstance(row, dict) else {}
+
+
+def notice_line(installed, latest, host=None):
     """The single-line SessionStart/statusline notice, or None when no update is due
-    (AC-1/AC-2): `codeArbiter: update available X -> Y (run /plugin marketplace update
-    codearbiter)`. Never multi-line; never emitted for equal, lesser, missing, or
-    malformed `latest`."""
-    if not update_available(installed, latest):
+    (AC-1/AC-2): `codeArbiter: update available X -> Y (run <host command>)`.
+    Never multi-line; never emitted for equal, lesser, missing, or malformed
+    `latest`."""
+    descriptor = update_descriptor(host)
+    if descriptor is None or not update_available(installed, latest):
         return None
     return (f"codeArbiter: update available {installed} -> {latest} "
-            f"(run /plugin marketplace update codearbiter)")
+            f"(run {descriptor['command']})")
 
 
 def read_state(path=None):
-    """The cached `{latest, checked_at}` state, or {} on ANY failure (missing file,
-    corrupt JSON, non-dict content) — a corrupt cache degrades to 'no notice', never
-    a crash of the host hook."""
+    """The target-keyed cache state, or {} on ANY failure (missing file, corrupt
+    JSON, non-dict content) — a corrupt cache degrades to 'no notice', never a
+    crash of the host hook."""
     path = path or state_path()
     try:
         with open(path, encoding="utf-8") as f:
@@ -190,7 +242,10 @@ def is_stale(checked_at, now, interval=ONE_DAY):
     if checked_at is None:
         return True
     try:
-        return (now - float(checked_at)) >= interval
+        checked_at = float(checked_at)
+        if not math.isfinite(checked_at):
+            return True
+        return (now - checked_at) >= interval
     except (TypeError, ValueError):
         return True
 
@@ -220,8 +275,34 @@ def _build_opener():
     return urllib.request.build_opener(_HTTPSOnlyRedirectHandler())
 
 
-def fetch_latest_tag(url=UPDATE_API_URL, timeout=3.0, opener=None):
-    """GET the GitHub Releases API and return `tag_name`, or None on ANY problem
+def select_latest_tag(releases, tag_prefix):
+    """Highest stable numeric version in `releases` for exact `tag_prefix`.
+    Drafts, prereleases, malformed rows, and every sibling series are ignored."""
+    if not isinstance(releases, list) or not isinstance(tag_prefix, str) or not tag_prefix:
+        return None
+    selected = None
+    selected_tuple = None
+    for release in releases:
+        if not isinstance(release, dict) or release.get("draft") or release.get("prerelease"):
+            continue
+        tag = release.get("tag_name")
+        if not isinstance(tag, str) or not tag.startswith(tag_prefix):
+            continue
+        version = tag[len(tag_prefix):]
+        if not re.fullmatch(r"\d+(?:\.\d+)*", version):
+            continue
+        parsed = parse_version(version)
+        if parsed is not None and (selected_tuple is None or parsed > selected_tuple):
+            selected = version
+            selected_tuple = parsed
+    return selected
+
+
+def fetch_latest_tag(tag_prefix=None, url=UPDATE_API_URL, timeout=3.0,
+                     opener=None, host=None):
+    """GET bounded pages of the GitHub Releases API and return the active
+    series' highest stable numeric version, or
+    None on ANY problem
     (AC-5): non-https url, network error, timeout, non-200, an unparseable/absent
     body, or a redirect to a non-https target. HTTPS-only per ADR-0003 — a
     non-https INITIAL url is refused before any connection is attempted, and a
@@ -229,50 +310,149 @@ def fetch_latest_tag(url=UPDATE_API_URL, timeout=3.0, opener=None):
     since urllib's default opener would otherwise follow an https->http
     downgrade transparently). `opener` is injectable (tests); production builds
     the hardened opener via `_build_opener()`."""
-    if not isinstance(url, str) or not url.lower().startswith("https://"):
+    if tag_prefix is None:
+        descriptor = update_descriptor(host)
+        tag_prefix = descriptor.get("tag_prefix") if descriptor else None
+    if (not isinstance(tag_prefix, str) or not tag_prefix
+            or not isinstance(url, str) or not url.lower().startswith("https://")):
         return None
     try:
-        req = urllib.request.Request(url, headers={
-            "User-Agent": "codeArbiter-update-check",
-            "Accept": "application/vnd.github+json",
-        })
         op = opener or _build_opener()
-        with op.open(req, timeout=timeout) as resp:
-            status = getattr(resp, "status", None) or getattr(resp, "code", None)
-            if status != 200:
+        parsed_url = urllib.parse.urlsplit(url)
+        query = dict(urllib.parse.parse_qsl(parsed_url.query, keep_blank_values=True))
+        try:
+            page_size = int(query.get("per_page", "100"))
+        except (TypeError, ValueError):
+            page_size = 100
+        if page_size < 1:
+            page_size = 100
+
+        releases = []
+        for page in range(1, MAX_RELEASE_PAGES + 1):
+            page_query = dict(query)
+            page_query["page"] = str(page)
+            page_url = urllib.parse.urlunsplit(parsed_url._replace(
+                query=urllib.parse.urlencode(page_query)))
+            req = urllib.request.Request(page_url, headers={
+                "User-Agent": "codeArbiter-update-check",
+                "Accept": "application/vnd.github+json",
+            })
+            with op.open(req, timeout=timeout) as resp:
+                status = getattr(resp, "status", None) or getattr(resp, "code", None)
+                if status != 200:
+                    return None
+                body = resp.read()
+            page_data = json.loads(body.decode("utf-8", "replace"))
+            if not isinstance(page_data, list):
                 return None
-            body = resp.read()
-        data = json.loads(body.decode("utf-8", "replace"))
-        tag = data.get("tag_name") if isinstance(data, dict) else None
-        return tag.strip() if isinstance(tag, str) and tag.strip() else None
+            releases.extend(page_data)
+            if len(page_data) < page_size:
+                break
+        else:
+            # Every bounded page was full, so more releases may exist. Do not
+            # cache a result whose series enumeration is known to be incomplete.
+            return None
+        return select_latest_tag(releases, tag_prefix)
     except Exception:  # noqa: BLE001 — AC-5: fail-silent on any network/parse error
         return None
 
 
-def refresh_if_stale(now=None, fetcher=None, path=None):
+def refresh_if_stale(now=None, fetcher=None, path=None, host=None):
     """Best-effort, once-daily, fail-silent cache refresh (AC-3/AC-4/AC-5).
 
-    Reads the cache; if `checked_at` is still fresh (is_stale() False), returns it
-    UNCHANGED and calls the fetcher NOT AT ALL (AC-4 — at most one fetch per day).
-    Otherwise calls `fetcher()` (default fetch_latest_tag): on success the new
+    Reads the cache under the write lock; if `checked_at` is still fresh
+    (is_stale() False), returns it UNCHANGED and calls the fetcher NOT AT ALL.
+    Otherwise it reserves that target's daily refresh before releasing the lock,
+    so a concurrent same-target process observes a fresh row and also makes no
+    call (AC-4 — at most one fetch per day). It then calls `fetcher()` (default
+    fetch_latest_tag): on success the new
     `latest` is cached; on ANY exception or a None/falsy return, the PRIOR `latest`
     is preserved (fail-silent — a network hiccup never blanks a known-good notice)
     and `checked_at` still advances, so a persistently-unreachable network is not
     retried every single session that day. Never raises (AC-3)."""
     now = time.time() if now is None else now
     path = path or state_path()
-    state = read_state(path)
-    checked_at = state.get("checked_at") if isinstance(state, dict) else None
-    if not is_stale(checked_at, now):
-        return state
-    fetch = fetcher or fetch_latest_tag
+    descriptor = update_descriptor(host)
+    if descriptor is None:
+        return read_state(path)
+
+    # Reserve this target's refresh under the cache lock before any network
+    # work. Without the re-read and reservation here, concurrent detached
+    # SessionStart refreshes can all observe the same stale row and each issue
+    # a bounded release-page fetch before the later merge lock serializes them.
+    try:
+        reservation_at = float(now)
+    except (TypeError, ValueError):
+        return read_state(path)
+    if not math.isfinite(reservation_at):
+        return read_state(path)
+
+    lock = acquire_lock(path)
+    if lock is None:
+        return read_state(path)
+    try:
+        current = read_state(path)
+        current_row = target_state(current, host=host)
+        if not is_stale(current_row.get("checked_at"), reservation_at):
+            return current
+        prior_targets = current.get("targets") if isinstance(current, dict) else None
+        targets = dict(prior_targets) if isinstance(prior_targets, dict) else {}
+        targets[descriptor["target"]] = {
+            "latest": current_row.get("latest"),
+            "checked_at": reservation_at,
+        }
+        reserved_state = {"schema": 1, "targets": targets}
+        write_state(reserved_state, path)
+        confirmed_row = target_state(read_state(path), host=host)
+        if confirmed_row.get("checked_at") != reservation_at:
+            # A failed reservation cannot safely authorize network egress. The
+            # notifier remains fail-silent and will retry on a later session.
+            return read_state(path)
+    finally:
+        release_lock(lock)
+
+    fetch = fetcher or (lambda: fetch_latest_tag(
+        tag_prefix=descriptor["tag_prefix"], host=host))
     try:
         latest = fetch()
     except Exception:  # noqa: BLE001 — AC-3/AC-5: never propagate a fetch failure
         latest = None
-    new_state = {
-        "latest": latest if latest else state.get("latest"),
-        "checked_at": now,
-    }
-    write_state(new_state, path)
-    return new_state
+    lock = acquire_lock(path)
+    if lock is None:
+        return read_state(path)
+    try:
+        # Re-read under the write lock. Another independently versioned host
+        # may have refreshed while this process was waiting on GitHub; merging
+        # the pre-fetch snapshot would silently erase that target's row.
+        current = read_state(path)
+        current_row = target_state(current, host=host)
+        prior_targets = current.get("targets") if isinstance(current, dict) else None
+        targets = dict(prior_targets) if isinstance(prior_targets, dict) else {}
+
+        current_latest = current_row.get("latest")
+        if parse_version(latest) is None:
+            merged_latest = current_latest
+        elif (parse_version(current_latest) is not None
+              and version_gt(current_latest, latest)):
+            merged_latest = current_latest
+        else:
+            merged_latest = latest
+
+        current_checked_at = current_row.get("checked_at")
+        finite_checked_at = []
+        for value in (current_checked_at, now):
+            try:
+                value = float(value)
+            except (TypeError, ValueError):
+                continue
+            if math.isfinite(value):
+                finite_checked_at.append(value)
+        targets[descriptor["target"]] = {
+            "latest": merged_latest,
+            "checked_at": max(finite_checked_at) if finite_checked_at else None,
+        }
+        new_state = {"schema": 1, "targets": targets}
+        write_state(new_state, path)
+        return new_state
+    finally:
+        release_lock(lock)

package/plugins/ca-pi/hooks/doctor.py

@@ -19,7 +19,7 @@ import subprocess
 import sys
 
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-from _gitexec import git_executable  # noqa: E402
+from _gitexec import git_executable, root_bound_git_env  # noqa: E402
 import hostapi  # noqa: E402 — host seam (ADR-0011): plugin-root resolution
 import _entrylib  # noqa: E402 — shared run() dispatch (jscpd dedup)
 import _githooks  # noqa: E402 — #556: git-hook drop-in registry freshness
@@ -173,7 +173,9 @@ def check_payload(root, host=None):
 def check_repo():
     """Returns the resolved repo root (for check_git_hook_freshness below), or
     None when this process isn't inside a git repository at all."""
-    r = _run_cmd([git_executable(), "rev-parse", "--show-toplevel"])
+    r = _run_cmd(
+        [git_executable(), "rev-parse", "--show-toplevel"],
+        env=root_bound_git_env())
     if r.returncode != 0:
         warn("not inside a git repository — repo-level checks skipped")
         return None
@@ -199,7 +201,9 @@ def check_repo():
         else:
             warn(f"no <!--INITIALIZED--> marker — startup will route to "
                  f"{get_host().cmd_ref('decompose')} or {get_host().cmd_ref('create-context')}")
-        email = _run_cmd([git_executable(), "config", "user.email"]).stdout.strip()
+        email = _run_cmd(
+            [git_executable(), "config", "user.email"], cwd=root,
+            env=root_bound_git_env()).stdout.strip()
         if email:
             ok(f"git identity for audit attribution: {email}")
         else:
@@ -209,7 +213,9 @@ def check_repo():
 
 
 def check_git_hook_freshness(root):
-    """#556 (AC-3): the git-level hook backstop (#161) can be running from a
+    """Verify the effective Git backstop, then report registry freshness.
+
+    #556 (AC-3): the git-level hook backstop (#161) can be running from a
     host's plugin cache that nobody has refreshed in a long time — a cache
     that predates a fix THIS checkout already carries (the #279
     sensitive-scan exemption, in the issue that motivated this check) is
@@ -219,14 +225,56 @@ def check_git_hook_freshness(root):
     commit/push time (`_githooks.stale_registered_plugins`), so this can
     never disagree with what actually happens at commit time.
 
-    A no-op (nothing printed) when `root` is None (not inside a git repo —
-    already reported by check_repo) or the drop-in registry doesn't exist
-    yet (nothing installed, or a host that predates ADR-0014)."""
+    A no-op when `root` is None (already reported by check_repo) or the repo is
+    deliberately dormant. For an arbiter-enabled repo, missing effective
+    managed shims or a registry without a live enforcer is a broken backstop,
+    not a healthy empty registry."""
     if root is None:
         return
+    ctx = os.path.join(root, ".codearbiter", "CONTEXT.md")
+    enabled, malformed = frontmatter_enabled(ctx)
+    if not enabled or malformed:
+        return
+    hooks_dir = _githooks.hooks_dir(root)
+    if hooks_dir is None:
+        fail("git-hook backstop: the selected Git binary could not resolve its "
+             "effective hooks directory")
+        return
     dropin_dir = _githooks._dropin_dir(root)
-    if dropin_dir is None or not os.path.isdir(dropin_dir):
+    if dropin_dir is None:
+        fail("git-hook backstop: Git's shared registry directory could not be resolved")
+        return
+    if not _githooks._hooks_current(hooks_dir, dropin_dir):
+        fail(f"git-hook backstop: Git's effective hooks directory ({hooks_dir}) "
+             "does not contain the current managed pre-commit and pre-push shims")
+        return
+    if os.name != "nt":
+        inoperable = [phase for phase in _githooks.PHASES
+                      if not os.access(os.path.join(hooks_dir, phase), os.X_OK)]
+        if inoperable:
+            fail("git-hook backstop: Git's managed hook is not executable: "
+                 + ", ".join(inoperable))
+            return
+    live = _githooks.live_registered_plugins(dropin_dir)
+    if not live:
+        fail("git-hook backstop: the shared registry has no live enforcer; start "
+             "a session from a durable installed host or reinstall that host")
+        return
+    try:
+        probe = _run_cmd(
+            [git_executable(), "hook", "run", "pre-push"], cwd=root, input="",
+            env=root_bound_git_env())
+    except Exception as exc:  # noqa: BLE001 - diagnostic must fail unhealthy, never crash
+        fail(f"git-hook backstop live-fire could not run: {exc}")
+        return
+    if probe.returncode != 0:
+        detail = (probe.stderr or probe.stdout or "managed pre-push returned nonzero").strip()
+        fail(f"git-hook backstop live-fire failed: {detail[:240]}")
+        return
+    if "ignored because" in (probe.stderr or "").lower():
+        fail(f"git-hook backstop live-fire was ignored by Git: {probe.stderr.strip()[:240]}")
         return
+    ok("git-hook backstop live-fire: selected Git executed the managed pre-push shim")
     stale = _githooks.stale_registered_plugins(dropin_dir)
     if stale:
         names = ", ".join(sorted(stale))

package/plugins/ca-pi/hooks/git-enforce.py

@@ -194,6 +194,12 @@ def _marker_set(root, name):
         return set()
 
 
+def _marker_root(root):
+    """Escalate only gate-marker reads to the main checkout for a linked
+    worktree; all Git and worktree reads remain anchored at ``root`` (#695)."""
+    return hostapi.git_worktree_main_root(root) or root
+
+
 def pre_commit(root):
     cwd = root
     # H-01: no commit onto a protected branch (or a detached HEAD on its tip).
@@ -230,11 +236,12 @@ def pre_commit(root):
         kind = "crypto/TLS" if touches_crypto else "secret"
         tag = "H-09b" if touches_crypto else "H-10b"
         skill = "crypto-compliance" if touches_crypto else "secret-handling"
-        marker = os.path.join(root, ".codearbiter", ".markers", "security-gate-passed")
+        marker_root = _marker_root(root)
+        marker = os.path.join(marker_root, ".codearbiter", ".markers", "security-gate-passed")
         if not marker_fresh(marker, MARKER_FRESHNESS_MINUTES):
             block(tag, f"This commit introduces {kind} changes, but no security-gate pass is "
                        f"recorded (#161 git backstop). Run the {skill} gate, then commit.")
-        approved = _marker_set(root, "security-gate-passed")
+        approved = _marker_set(marker_root, "security-gate-passed")
         uncovered = [ln for ln in sensitive if line_digest(ln) not in approved]
         if uncovered:
             block(tag, f"{len(uncovered)} {kind} line(s) in this commit are not covered by the "
@@ -248,7 +255,7 @@ def pre_commit(root):
                       "failing closed (ORCHESTRATOR §2).")
     migs = sorted(p for p in names if is_migration_path(p, root))
     if migs:
-        approved = _marker_set(root, "migration-gate-passed")
+        approved = _marker_set(_marker_root(root), "migration-gate-passed")
         uncovered = []
         for rel in migs:
             text = read_worktree(cwd, rel)