@arbiterforge/ca-pi 0.10.13 → 0.14.7

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

@@ -92,7 +92,8 @@
 #                                         restating the literal.
 #   marker_fresh(path, minutes) -> bool   True iff marker file exists and is recent
 #   write_text_atomic(path, text) -> None  crash-safe write (temp + os.replace)
-#   acquire_lock(path) -> handle|None     OS-owned cross-process file lock (#271 C-2);
+#   acquire_lock(path, wait_seconds=None) -> handle|None
+#                                         OS-owned cross-process file lock (#271 C-2);
 #                                         non-blocking + bounded LOCK_WAIT retry spin,
 #                                         fail-soft None on contention/timeout/OSError
 #   release_lock(handle) -> None          release + close; None handle is a no-op
@@ -222,6 +223,7 @@ from _sensitivelib import (  # noqa: F401
 # POSIX flock and Windows byte-range locks are process-scoped, so sibling
 # threads can otherwise burn the shared wait budget contending with each other.
 _GATE_EVENTS_PROCESS_LOCK = threading.Lock()
+GATE_EVENT_LOCK_WAIT_SECONDS = 5.0
 _WINDOWS_LOCK_TIMEOUT_SECONDS = 5.0
 _WINDOWS_LOCK_RETRY_SECONDS = 0.01
 _WINDOWS_CRT_EDEADLK = 36
@@ -345,7 +347,7 @@ def write_text_atomic(path, text, newline=None):
         raise
 
 
-def acquire_lock(path):
+def acquire_lock(path, wait_seconds=None):
     """Acquire an OS-owned cross-process file lock keyed on `path`; process
     death releases it automatically (#271 C-2 — hoisted from the
     statusline-ledger-only `_ledgerlib._acquire_lock`, now shared with
@@ -355,7 +357,8 @@ def acquire_lock(path):
     with one byte so the OS byte-range lock has a byte to lock (an empty file
     has no range to range-lock). Non-blocking (`msvcrt.locking(..., LK_NBLCK,
     1)` on Windows, `fcntl.flock(..., LOCK_EX | LOCK_NB)` elsewhere) with a
-    bounded `LOCK_WAIT`-second retry spin; any `OSError` opening the lock file,
+    bounded `LOCK_WAIT`-second retry spin (or an explicit non-negative
+    `wait_seconds` budget); any `OSError` opening the lock file,
     or exhausting the deadline still contended, is FAIL-SOFT: returns `None`
     rather than raising or blocking indefinitely. Callers decide what
     "fail-soft" means for them — `_ledgerlib.ledger_update`/`persist_sess_start`
@@ -373,7 +376,8 @@ def acquire_lock(path):
             handle.flush()
     except OSError:
         return None
-    deadline = time.monotonic() + LOCK_WAIT
+    wait_seconds = LOCK_WAIT if wait_seconds is None else max(0.0, wait_seconds)
+    deadline = time.monotonic() + wait_seconds
     while True:
         try:
             handle.seek(0)
@@ -493,9 +497,22 @@ def marker_fresh(path, minutes):
 def _log_gate_event(kind, tag, msg):
     """Best-effort durable append of one gate decision to
     .codearbiter/gate-events.log (observability-001, issue #186) — the durable
-    sink block()/remind()/warn() funnel every BLOCK/REMIND/WARN through, so a
-    decision is no longer visible ONLY in the ephemeral per-turn stderr
-    transcript.
+    sink block() funnels every BLOCK through, so a decision is no longer
+    visible ONLY in the ephemeral per-turn stderr transcript.
+
+    remind()/warn() do NOT call this (2026-09-17 scope-down): measured on a
+    live repo, REMIND/WARN accounted for 76% of the file's lines and 60% were
+    one repeated boilerplate reminder carrying no information past its first
+    occurrence, while the file's git-tracked + H-05 append-only status gave
+    that noise the full cost of a protected audit artifact — two branches
+    that both merely touched it, independently, produced a real merge
+    conflict; _releaselib.py's clean-tree probe carries its own comment about
+    working around a mid-window REMIND/WARN append poisoning a release gate.
+    BLOCK is the one kind with real forensic value (evidence for diagnosing a
+    hook that misfired); REMIND/WARN remain full-strength on stderr, just not
+    persisted. Not ADR-governed — issue #186 shipped this as an implementation
+    detail of `_hooklib`, not an architectural decision, so scoping it back
+    down is the same kind of call.
 
     One line per event: `[ISO-8601Z] KIND [tag] host=<host> hook=<script> | msg`.
     `tag` may be None (warn() carries no tag) — the bracket is simply omitted
@@ -538,7 +555,10 @@ def _log_gate_event(kind, tag, msg):
         try:
             _GATE_EVENTS_PROCESS_LOCK.acquire()
             process_lock_acquired = True
-            audit_lock = acquire_lock(audit_lock_key(root, log_path))
+            audit_lock = acquire_lock(
+                audit_lock_key(root, log_path),
+                wait_seconds=GATE_EVENT_LOCK_WAIT_SECONDS,
+            )
         except Exception:
             if process_lock_acquired:
                 _GATE_EVENTS_PROCESS_LOCK.release()
@@ -551,7 +571,10 @@ def _log_gate_event(kind, tag, msg):
         os_lock_acquired = False
         try:
             fd = os.open(log_path, flags, 0o600)
-            if os.name == "nt":
+            # The trusted sidecar already serializes current writers. Keep the
+            # legacy descriptor lock for compatibility once the log has data,
+            # but Windows cannot reliably lock byte zero of a new empty file.
+            if os.name == "nt" and os.fstat(fd).st_size:
                 import msvcrt
                 os.lseek(fd, 0, os.SEEK_SET)
                 lock_mode = getattr(msvcrt, "LK_NBLCK", msvcrt.LK_LOCK)
@@ -596,14 +619,15 @@ def block(tag, msg):
 
 
 def remind(tag, msg):
-    """Non-blocking nudge to stderr."""
-    _log_gate_event("REMIND", tag, msg)
+    """Non-blocking nudge to stderr. Deliberately NOT persisted to
+    gate-events.log (see _log_gate_event's 2026-09-17 scope-down note)."""
     print(f"REMINDER [{tag}]: {msg}", file=sys.stderr)
 
 
 def warn(msg):
-    """Loud degradation/diagnostic breadcrumb — never silent."""
-    _log_gate_event("WARN", None, msg)
+    """Loud degradation/diagnostic breadcrumb — never silent. Deliberately
+    NOT persisted to gate-events.log (see _log_gate_event's 2026-09-17
+    scope-down note)."""
     print(f"codeArbiter hook: {msg}", file=sys.stderr)
 
 

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

@@ -11,7 +11,7 @@ import hostapi  # noqa: E402
 class PiHost(hostapi.Host):
     name = "pi"
     adapter_name = "@arbiterforge/ca-pi"
-    adapter_version = "0.10.13"
+    adapter_version = "0.14.7"
     update_target = "ca-pi"
     update_tag_prefix = "ca-pi-v"
     update_command = "pi update npm:@arbiterforge/ca-pi"

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

@@ -168,6 +168,8 @@ def uncovered_intent(spec_text, issue_body=None):
     docstring for what it cannot catch."""
     if not isinstance(spec_text, str):
         spec_text = ""
+    if spec_text.lstrip().lower().startswith(("<!doctype html", "<html")):
+        return ["[HTML-REQUIRES-VALIDATION] Use the path-based artifact validator; HTML is not empty Markdown."]
     criteria_tokens = set()
     for criterion in _criteria_texts(spec_text):
         criteria_tokens.update(_tokens(criterion))
@@ -232,6 +234,35 @@ def main(argv):
             sys.stderr.write(f"_intentlib.py: cannot read {issue_body_path}: {exc}\n")
             return 2
 
+    if positional[0].lower().endswith(".html"):
+        try:
+            from _artifactlib import resolve_spec_file, helper_installation
+            client, entry = resolve_spec_file(positional[0], helper_installation(__file__))
+            result = client.call("validate", {"artifact_id": entry["artifact_id"], "gate": "ready"}, permit_invalid=True)
+            findings = ["[INVALID-HTML-SPEC] " + item["code"] + ": " + item["message"]
+                        for item in result.get("diagnostics", [])]
+            # Explicit source->criterion mappings replace fuzzy scope matching.
+            # The legacy issue-checkbox heuristic is retained ONLY for external
+            # issue text until issue-source records receive their own schema.
+            if issue_body:
+                criteria_tokens = set()
+                for record in client.outline(entry["artifact_id"]):
+                    if record["kind"] == "criteria" and not record["retired"]:
+                        data = client.call("read", {"artifact_id": entry["artifact_id"], "symbol": record["id"], "mode": "exact"})
+                        criteria_tokens.update(_tokens(data["record"].get("statement", "")))
+                for box in _checkboxes(issue_body):
+                    if not _cited(box, criteria_tokens):
+                        findings.append("[UNCOVERED-CHECKBOX] " + box)
+            fresh = client.call("identity", {"artifact_id": entry["artifact_id"]})
+            if fresh["model_sha256"] != result["model_sha256"]:
+                raise RuntimeError("HTML spec changed during intent verification; retry a fresh read")
+            for finding in findings:
+                print(finding)
+            return 1 if findings or not result["valid"] else 0
+        except Exception as error:
+            sys.stderr.write("_intentlib.py: HTML validation failed: " + str(error)[:512] + "\n")
+            return 2
+
     findings = uncovered_intent(spec_text, issue_body)
     for finding in findings:
         print(finding)

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

@@ -70,6 +70,30 @@ def _request_path(root, slug, kind):
     return os.path.join(root, ".codearbiter", KINDS[kind], f"{slug}.md")
 
 
+def _require_legacy_pair(root, slug):
+    """Refuse Pi's Markdown-only plan surface unless one exact legacy pair owns the slug."""
+    _request_path(root, slug, "spec")
+    root_info = os.lstat(root)
+    if not _directory(root_info):
+        raise PlanFileError("root")
+    state_path, _ = _exact_absolute_child(root, ".codearbiter")
+    for kind in KINDS:
+        parent_path, _ = _exact_absolute_child(state_path, KINDS[kind])
+        html_leaf = f"{slug}.html"
+        if _aliases(parent_path, html_leaf):
+            raise PlanFileError("html_authority")
+        markdown_leaf = f"{slug}.md"
+        aliases = _aliases(parent_path, markdown_leaf)
+        if not aliases:
+            raise PlanFileError("legacy_pair_required")
+        if aliases != [markdown_leaf]:
+            raise PlanFileError("path_alias")
+        path = os.path.join(parent_path, markdown_leaf)
+        info = os.lstat(path)
+        if not _regular_single(info) or os.path.realpath(path) != os.path.abspath(path):
+            raise PlanFileError("path_type")
+
+
 def _windows_handle_identity(handle):
     from ctypes import wintypes
 
@@ -580,7 +604,8 @@ def _committed_result(path, data, content, fault=None, initial_diagnostic=None):
     return result
 
 
-def plan_file_operation(root, request, *, lock_root=None, fault=None):
+def plan_file_operation(root, request, *, lock_root=None, fault=None,
+                        require_legacy_pair=False):
     """Run a bounded CAS. The lock serializes cooperating codeArbiter Pi writers only."""
     try:
         if not isinstance(request, dict) or set(request) - {"slug", "kind", "action", "expectedHash", "content"}:
@@ -593,7 +618,13 @@ def plan_file_operation(root, request, *, lock_root=None, fault=None):
         if action not in ("read", "replace"):
             raise PlanFileError("request")
         target = _request_path(root, request.get("slug"), request.get("kind"))
+        if require_legacy_pair is not False:
+            if require_legacy_pair is not True:
+                raise PlanFileError("request")
+            _require_legacy_pair(root, request["slug"])
         with _lock_for(target, lock_root), _held_path(root, request["slug"], request["kind"], fault) as path:
+            if require_legacy_pair:
+                _require_legacy_pair(root, request["slug"])
             chosen = _read_target(path, fault)
             if action == "read":
                 if chosen is None:
@@ -625,6 +656,8 @@ def plan_file_operation(root, request, *, lock_root=None, fault=None):
                 for phase in ("before_publish", "publish"):
                     if fault:
                         fault(phase, path)
+                    if require_legacy_pair:
+                        _require_legacy_pair(root, request["slug"])
                     try:
                         latest = _read_target(path)
                     except Exception: