@arbiterforge/ca-pi 0.10.13 → 0.14.6

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.6"
     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:

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

@@ -381,6 +381,16 @@ def marker_name_for(rel_path):
     (non-empty) rel_path can ever produce, since a real segment always
     contributes a non-empty stem.
 
+    Every segment is case-folded (`.lower()`) before encoding (#624), matching
+    `_canon`/`lookup_policy`'s own case-insensitive registry comparison: a
+    marker name computed for a differently-cased Write/Edit target must equal
+    the one minted under the registry's canonical casing, or a legitimate
+    authoring write is wrongly blocked despite a fresh, correctly-minted
+    marker. This widens what two paths can collide into one marker (a
+    same-name directory differing only by case now shares a marker with its
+    canonical sibling) - the same accepted "widens admission, never narrows
+    protection" tradeoff `lookup_policy`'s own case fold already makes.
+
     Residual (accepted): the escaping above closes hyphen/segment-boundary
     ambiguity but is not a fully bijective encoding against adversarially
     crafted underscore runs (e.g. a directory literally named "a_" holding
@@ -388,7 +398,7 @@ def marker_name_for(rel_path):
     small, curated, human-authored set (spec B1/B2), not attacker-chosen
     directory names, so this is judged out of proportion to close fully
     here."""
-    parts = [p for p in norm_path(rel_path).split("/") if p not in ("", ".", "..")]
+    parts = [p for p in norm_path(rel_path).lower().split("/") if p not in ("", ".", "..")]
     if not parts:
         return "-authoring"
     if parts[0] == ".codearbiter" and len(parts) > 1:

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

@@ -1084,3 +1084,123 @@ def compute_injection(root, session_id, rel, runner=None):
         return ""
     except Exception:  # noqa: BLE001
         return ""
+
+# Typed artifact pilot bridge. Keep legacy matching unchanged; never cache HTML
+# authority by mtime. Importing this module performs no subprocess or file I/O.
+_artifact_legacy_build_index = build_index
+_artifact_legacy_spec_pointers = spec_pointers
+
+
+def build_index(root):
+    result = _artifact_legacy_build_index(root)
+    if not isinstance(result, dict):
+        return result
+    result = dict(result)
+    try:
+        from _artifactlib import ArtifactClient, helper_installation, has_html
+        if not has_html(root):
+            return result
+        # Preserve full engine identities in the advisory snapshot. Pointer
+        # matching uses only spec/path/globs, while dedup below hashes the same
+        # entries including revision/model/normative identity. Do not reread the
+        # artifact after this validated index stream.
+        extra = []
+        client = ArtifactClient(root, helper_installation(__file__))
+        for entry in client.index("spec"):
+            authority = entry["authority"]
+            if authority["authority_verified"] and entry.get("governs"):
+                extra.append({
+                    "spec": entry["artifact_id"],
+                    "path": entry["path"],
+                    "globs": entry["governs"],
+                    "artifact_html": True,
+                    "revision": entry.get("revision"),
+                    "model_sha256": entry.get("model_sha256"),
+                    "normative_sha256": entry.get("normative_sha256"),
+                })
+    except Exception as error:
+        # Advisory read injection remains fail-open. This warning is NOT an
+        # approved-spec pointer and MUST NOT authorize a planning/execution gate.
+        code = getattr(error, "code", "CAPABILITY_MISSING")
+        code = str(code)[:80]
+        capability_codes = {
+            "CAPABILITY_MISSING", "INVALID_INSTALLATION", "PACKAGE_INTEGRITY",
+            "UNSUPPORTED_PLATFORM", "UNSUPPORTED_VERSION", "UNVERIFIED_PLATFORM",
+            "INVALID_RESPONSE", "RESPONSE_TOO_LARGE", "SUBPROCESS_FAILED", "TIMEOUT",
+        }
+        extra = [{
+            "artifact_diagnostic": code,
+            "artifact_diagnostic_kind": (
+                "capability" if code in capability_codes else "invalid-artifact"
+            ),
+            "artifact_html": True,
+        }]
+    result["spec"] = [item for item in result.get("spec", [])
+                      if not isinstance(item, dict) or not item.get("artifact_html")] + extra
+    return result
+
+
+def spec_pointers(rel, index):
+    if not isinstance(index, list):
+        return _artifact_legacy_spec_pointers(rel, index)
+    warnings = [item for item in index if isinstance(item, dict) and item.get("artifact_diagnostic")]
+    normal = [item for item in index if not isinstance(item, dict) or not item.get("artifact_diagnostic")]
+    result = _artifact_legacy_spec_pointers(rel, normal)
+    if warnings:
+        warning = warnings[0]
+        code = warning["artifact_diagnostic"]
+        if warning.get("artifact_diagnostic_kind") == "capability":
+            text = (
+                "HTML artifact capability unavailable (" + code + "). Repair or reinstall "
+                "the pinned artifact payload. Source inspection and unrelated legacy Markdown "
+                "may continue; HTML planning/execution must stop until resolved."
+            )
+        else:
+            text = (
+                "HTML specification is invalid or unreadable (" + code + "). Inspect the "
+                "engine diagnostic and repair-preview before any repair. Source inspection may "
+                "continue; HTML planning/execution must stop until resolved."
+            )
+        result.append({"tier": "artifact-diagnostic", "text": text})
+    return result
+
+_artifact_legacy_compute_injection = compute_injection
+
+
+def compute_injection(root, session_id, rel, runner=None):
+    # Bind the injected pointers and dedup epoch to ONE validated HTML snapshot.
+    # A second artifact read here permits B(epoch) -> A(content) and records A
+    # under B's marker, suppressing a later stable B read. HTML therefore builds
+    # once before dedup; the same entries drive both context and epoch. This is
+    # advisory identity only, never approval or execution authority.
+    if not isinstance(rel, str) or rel.replace("\\", "/").split("/", 1)[0] == ".codearbiter":
+        return _artifact_legacy_compute_injection(root, session_id, rel, runner)
+    try:
+        from _artifactlib import has_html
+        if not has_html(root):
+            return _artifact_legacy_compute_injection(root, session_id, rel, runner)
+        index = build_index(root)
+        if not isinstance(index, dict):
+            return ""
+        artifact_entries = [
+            item for item in index.get("spec", [])
+            if isinstance(item, dict) and item.get("artifact_html") is True
+        ]
+        epoch = hashlib.sha256(
+            json.dumps(
+                artifact_entries, sort_keys=True, separators=(",", ":")
+            ).encode()
+        ).hexdigest()
+        epoch_session = str(session_id) + "|html:" + epoch
+        if already_injected(root, epoch_session, rel):
+            return ""
+        pointers = governing_docs(rel, index, runner)
+        if not pointers:
+            return ""
+        context = assemble_context(pointers, budget=150)
+        if context:
+            record_injection(root, epoch_session, rel)
+            return context
+        return ""
+    except Exception:  # noqa: BLE001 - advisory injection always fails open
+        return ""