arkaos 4.21.0 → 4.22.0

package/core/governance/stop_lint.py

@@ -0,0 +1,266 @@
+"""Deterministic lint evidence at turn end (warn-only detached worker).
+
+The Stop hook enqueues this module DETACHED (the ``turn_capture``
+pattern) — none of this cost lands on the hook's 5s budget. The worker
+scopes ``core.governance.evidence_checks`` to the files actually
+changed (merge-base diff + working tree untracked), appends one JSONL
+line per run to ``~/.arkaos/telemetry/stop-lint.jsonl`` and coalesces
+repeat runs while the tree fingerprint is unchanged.
+
+WARN mode only: results are telemetry plus an owner-only tmp-state
+file; nothing blocks. Promotion to a blocking surface is gated on
+clean telemetry (the frontend-gate rollout pattern, ADR
+2026-04-17-binding-flow-enforcement).
+
+Config (``~/.arkaos/config.json``):
+    hooks.stopLint           absent/"warn" -> warn | false/"off" -> off
+    hooks.stopLintTypecheck  true adds the typecheck check. Default
+                             false: typecheck has no scoped mode in the
+                             engine (a scoped mypy would silently weaken
+                             the same check the Quality Gate runs), so
+                             the project-wide run is opt-in.
+Env kill-switch: ``ARKA_STOP_LINT=0``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import subprocess
+import sys
+import time
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from core.governance.evidence_checks import (
+    EvidenceReport,
+    _diff_base,
+    run_evidence_checks,
+)
+from core.shared.safe_session_id import safe_session_id
+from core.shared.temp_paths import arkaos_temp_dir
+
+TELEMETRY_PATH: Path = Path.home() / ".arkaos" / "telemetry" / "stop-lint.jsonl"
+CONFIG_PATH: Path = Path.home() / ".arkaos" / "config.json"
+_STATE_SUBDIR = "arkaos-stop-lint"
+_RESULT_SUBDIR = "arkaos-stop-lint-result"
+_GIT_TIMEOUT = 10
+_SUMMARY_CHARS = 200
+
+
+def mode(config_path: Path | None = None) -> str:
+    """Resolve the stop-lint mode: ``"off"`` or ``"warn"`` (default)."""
+    if os.environ.get("ARKA_STOP_LINT", "").strip() == "0":
+        return "off"
+    raw = _hooks_config(config_path).get("stopLint", "warn")
+    if raw is False or (isinstance(raw, str) and raw.lower() == "off"):
+        return "off"
+    return "warn"
+
+
+def _hooks_config(config_path: Path | None) -> dict[str, Any]:
+    path = config_path or CONFIG_PATH
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+    hooks = data.get("hooks") if isinstance(data, dict) else None
+    return hooks if isinstance(hooks, dict) else {}
+
+
+def _typecheck_enabled(config_path: Path | None) -> bool:
+    return bool(_hooks_config(config_path).get("stopLintTypecheck", False))
+
+
+def _git(args: list[str], cwd: Path) -> subprocess.CompletedProcess | None:
+    try:
+        return subprocess.run(
+            ["git", *args], cwd=cwd, capture_output=True, text=True,
+            timeout=_GIT_TIMEOUT,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+
+
+def changed_files(project_dir: Path) -> list[str]:
+    """Repo-relative files changed vs the merge-base, plus untracked."""
+    try:
+        base = _diff_base(project_dir)
+    except (OSError, subprocess.TimeoutExpired):
+        base = None
+    if base is None:
+        return []
+    out: list[str] = []
+    diff = _git(["diff", "--name-only", base], project_dir)
+    if diff is not None and diff.returncode == 0:
+        out.extend(f.strip() for f in diff.stdout.splitlines() if f.strip())
+    status = _git(["status", "--porcelain"], project_dir)
+    if status is not None and status.returncode == 0:
+        out.extend(
+            line[3:].strip()
+            for line in status.stdout.splitlines()
+            if line.startswith("??") and line[3:].strip()
+        )
+    seen: set[str] = set()
+    return [f for f in out if not (f in seen or seen.add(f))]
+
+
+def _fingerprint(project_dir: Path) -> str | None:
+    head = _git(["rev-parse", "HEAD"], project_dir)
+    status = _git(["status", "--porcelain"], project_dir)
+    if head is None or head.returncode != 0 or status is None:
+        return None
+    digest = hashlib.sha1()
+    digest.update(head.stdout.strip().encode("utf-8"))
+    # Porcelain alone only says WHICH files are dirty — editing an
+    # already-dirty file leaves it unchanged. Fold in mtime+size so
+    # content edits re-arm the worker.
+    for line in sorted(status.stdout.splitlines()):
+        digest.update(line.encode("utf-8", "replace"))
+        digest.update(_stat_token(project_dir / line[3:].strip()))
+    return digest.hexdigest()
+
+
+def _stat_token(path: Path) -> bytes:
+    try:
+        st = path.stat()
+    except OSError:
+        return b"|gone"
+    return f"|{st.st_mtime_ns}:{st.st_size}".encode("ascii")
+
+
+def _state_file(project_dir: Path) -> Path:
+    key = hashlib.sha1(
+        str(project_dir.resolve()).encode("utf-8")
+    ).hexdigest()[:16]
+    return arkaos_temp_dir(_STATE_SUBDIR) / f"{key}.json"
+
+
+def _seen_fingerprint(state_file: Path) -> str | None:
+    try:
+        data = json.loads(state_file.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    value = data.get("fingerprint") if isinstance(data, dict) else None
+    return value if isinstance(value, str) else None
+
+
+def _remember_fingerprint(state_file: Path, fingerprint: str) -> None:
+    prev_umask = os.umask(0o077)
+    try:
+        state_file.parent.mkdir(parents=True, exist_ok=True)
+        state_file.write_text(
+            json.dumps({"fingerprint": fingerprint}), encoding="utf-8"
+        )
+    except OSError:
+        pass
+    finally:
+        os.umask(prev_umask)
+
+
+def _check_fields(report: EvidenceReport) -> dict[str, Any]:
+    fields: dict[str, Any] = {}
+    for result in report.results:
+        fields[f"{result.check}_ran"] = result.ran
+        fields[f"{result.check}_passed"] = result.passed
+        fields[f"{result.check}_command"] = result.command
+        fields[f"{result.check}_summary"] = result.summary[:_SUMMARY_CHARS]
+    return fields
+
+
+def _run_checks(
+    project_dir: Path, changed: list[str], config_path: Path | None,
+) -> dict[str, Any]:
+    if not changed:
+        return {
+            "overall": "skipped",
+            "would_block": False,
+            "skip_reason": "no-changed-files",
+        }
+    checks = ["lint"]
+    if _typecheck_enabled(config_path):
+        checks.append("typecheck")
+    report = run_evidence_checks(
+        project_dir, changed_files=changed, checks=checks
+    )
+    fields = _check_fields(report)
+    fields["overall"] = report.overall
+    fields["would_block"] = report.overall == "fail"
+    return fields
+
+
+def _append_telemetry(entry: dict[str, Any], telemetry_path: Path) -> None:
+    try:
+        telemetry_path.parent.mkdir(parents=True, exist_ok=True)
+        with telemetry_path.open("a", encoding="utf-8") as fh:
+            fh.write(json.dumps(entry) + "\n")
+    except OSError:
+        pass
+
+
+def _write_result_state(session_id: str, entry: dict[str, Any]) -> None:
+    sid = safe_session_id(session_id)
+    if not sid:
+        return
+    prev_umask = os.umask(0o077)
+    try:
+        result_dir = arkaos_temp_dir(_RESULT_SUBDIR)
+        result_dir.mkdir(parents=True, exist_ok=True)
+        (result_dir / f"{sid}.json").write_text(
+            json.dumps(entry), encoding="utf-8"
+        )
+    except OSError:
+        pass
+    finally:
+        os.umask(prev_umask)
+
+
+def run(
+    project_dir: Path,
+    session_id: str = "",
+    *,
+    config_path: Path | None = None,
+    telemetry_path: Path | None = None,
+) -> int:
+    """Run the scoped batch once per tree fingerprint; append telemetry."""
+    project_dir = Path(project_dir)
+    if mode(config_path) == "off" or not project_dir.is_dir():
+        return 0
+    fingerprint = _fingerprint(project_dir)
+    state_file = _state_file(project_dir)
+    if fingerprint is not None and fingerprint == _seen_fingerprint(state_file):
+        return 0
+    started = time.monotonic()
+    changed = changed_files(project_dir)
+    entry = _run_checks(project_dir, changed, config_path)
+    entry.update(
+        ts=datetime.now(UTC).isoformat(),
+        session_id=session_id,
+        project_dir=str(project_dir),
+        event="stop-lint",
+        mode="warn",
+        changed_count=len(changed),
+        duration_ms=round((time.monotonic() - started) * 1000),
+    )
+    _append_telemetry(entry, telemetry_path or TELEMETRY_PATH)
+    _write_result_state(session_id, entry)
+    if fingerprint is not None:
+        _remember_fingerprint(state_file, fingerprint)
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    """CLI: ``python -m core.governance.stop_lint <project_dir> [sid]``."""
+    args = list(sys.argv[1:] if argv is None else argv)
+    if not args:
+        return 0
+    try:
+        return run(Path(args[0]), args[1] if len(args) > 1 else "")
+    except Exception:
+        return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/core/governance/stop_lint_telemetry.py

@@ -0,0 +1,132 @@
+"""Stop-lint telemetry summarizer.
+
+Reads the ``"event": "stop-lint"`` entries appended by
+``core.governance.stop_lint`` to ``~/.arkaos/telemetry/stop-lint.jsonl``
+and reports pass/would-block rates. This summary is the evidence that
+gates any promotion of the stop-lint batch beyond WARN (the
+frontend-gate ``would_deny_rate`` rollout pattern).
+
+Mirrors the period vocabulary of ``compliance_telemetry.summarise``
+(today / week / month / all). Empty/missing file = zero rates. Rates
+are computed over *observed* runs only — skipped runs (no changed
+files) are counted separately and excluded from denominators.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+DEFAULT_PATH: Path = Path.home() / ".arkaos" / "telemetry" / "stop-lint.jsonl"
+_VALID_PERIODS: frozenset[str] = frozenset({"today", "week", "month", "all"})
+_EVENT: str = "stop-lint"
+
+
+@dataclass(frozen=True)
+class StopLintSummary:
+    """Stop-lint snapshot over a slice of worker telemetry."""
+
+    period: str
+    runs: int
+    skipped_runs: int
+    lint_pass_rate: float
+    typecheck_pass_rate: float
+    would_block_rate: float
+    corrupt_line_count: int = 0
+
+
+def summarise(period: str, *, path: Path | None = None) -> StopLintSummary:
+    """Return a StopLintSummary for the requested period."""
+    if period not in _VALID_PERIODS:
+        raise ValueError(f"invalid period: {period!r}")
+    src = path or DEFAULT_PATH
+    cutoff = _period_cutoff(period)
+    entries, corrupt = _read_entries(src, cutoff)
+    return _build_summary(period, entries, corrupt)
+
+
+def _period_cutoff(period: str, now: datetime | None = None) -> datetime | None:
+    ref = now or datetime.now(UTC)
+    if period == "today":
+        return ref.replace(hour=0, minute=0, second=0, microsecond=0)
+    if period == "week":
+        return ref - timedelta(days=7)
+    if period == "month":
+        return ref - timedelta(days=30)
+    return None
+
+
+def _read_entries(
+    src: Path, cutoff: datetime | None,
+) -> tuple[list[dict[str, Any]], int]:
+    if not src.exists():
+        return [], 0
+    entries: list[dict[str, Any]] = []
+    corrupt = 0
+    try:
+        with src.open("r", encoding="utf-8", errors="replace") as fh:
+            for line in fh:
+                if not line.strip():
+                    continue
+                try:
+                    entry = json.loads(line)
+                except json.JSONDecodeError:
+                    corrupt += 1
+                    continue
+                if not isinstance(entry, dict):
+                    corrupt += 1
+                    continue
+                if entry.get("event") != _EVENT:
+                    continue
+                if cutoff is not None and not _within_cutoff(entry, cutoff):
+                    continue
+                entries.append(entry)
+    except OSError:
+        return entries, corrupt
+    return entries, corrupt
+
+
+def _within_cutoff(entry: dict[str, Any], cutoff: datetime) -> bool:
+    ts = _parse_ts(entry.get("ts"))
+    return ts is not None and ts >= cutoff
+
+
+def _parse_ts(raw: Any) -> datetime | None:
+    if not isinstance(raw, str) or not raw:
+        return None
+    try:
+        parsed = datetime.fromisoformat(raw.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=UTC)
+    return parsed
+
+
+def _build_summary(
+    period: str,
+    entries: Iterable[dict[str, Any]],
+    corrupt: int,
+) -> StopLintSummary:
+    rows = list(entries)
+    observed = [r for r in rows if r.get("overall") != "skipped"]
+    return StopLintSummary(
+        period=period,
+        runs=len(rows),
+        skipped_runs=len(rows) - len(observed),
+        lint_pass_rate=_true_rate(observed, "lint_passed"),
+        typecheck_pass_rate=_true_rate(observed, "typecheck_passed"),
+        would_block_rate=_true_rate(observed, "would_block"),
+        corrupt_line_count=corrupt,
+    )
+
+
+def _true_rate(rows: list[dict[str, Any]], key: str) -> float:
+    observed = [r for r in rows if isinstance(r.get(key), bool)]
+    if not observed:
+        return 0.0
+    return sum(1 for r in observed if r[key] is True) / len(observed)

package/core/governance/tool_loop_check.py

@@ -0,0 +1,111 @@
+"""Tool-loop detection over the current turn's transcript (warn-only).
+
+The context monitor's missing gap: an agent stuck re-issuing the same
+tool call burns budget without progress, and nothing surfaced it.
+Detection runs at the turn boundary (Stop hook) over the transcript, so
+it sees EVERY call — including the ones the PostToolUse fast-path shim
+short-circuits away from Python, which an in-process ring buffer never
+sees. Two patterns:
+
+  - ``consecutive`` — the same (tool, input) issued N times in a row,
+    the canonical stuck loop;
+  - ``repeated`` — the same (tool, input) issued N times across the
+    turn with other calls between, the churn variant.
+
+Privacy: tool inputs are compared by digest and never stored — the
+verdict carries the tool name and counts only. Reuses the turn-slicing
+helpers of ``phantom_action_check`` (same package, same transcript
+contract).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections import Counter
+from dataclasses import dataclass
+
+from core.governance.phantom_action_check import (
+    _last_real_user_index,
+    _parse_jsonl,
+    _record_content,
+    _record_role,
+)
+
+DEFAULT_THRESHOLD = 4
+
+
+@dataclass(frozen=True)
+class LoopVerdict:
+    """Outcome of the tool-loop scan. Never contains tool inputs."""
+
+    detected: bool = False
+    tool: str = ""
+    repeats: int = 0
+    pattern: str = ""  # "consecutive" | "repeated" | ""
+    total_tool_uses: int = 0
+
+
+def _call_key(block: dict) -> tuple[str, str]:
+    tool = str(block.get("name") or "")
+    try:
+        payload = json.dumps(block.get("input"), sort_keys=True, default=str)
+    except (TypeError, ValueError):
+        payload = "?"
+    digest = hashlib.sha1(payload.encode("utf-8")).hexdigest()[:16]
+    return tool, digest
+
+
+def _turn_tool_calls(raw_transcript: str) -> list[tuple[str, str]]:
+    records = _parse_jsonl(raw_transcript)
+    start = _last_real_user_index(records)
+    if start < 0:
+        return []
+    calls: list[tuple[str, str]] = []
+    for record in records[start + 1:]:
+        if _record_role(record) != "assistant":
+            continue
+        content = _record_content(record)
+        if not isinstance(content, list):
+            continue
+        calls.extend(
+            _call_key(block)
+            for block in content
+            if isinstance(block, dict) and block.get("type") == "tool_use"
+        )
+    return calls
+
+
+def _max_consecutive_run(calls: list[tuple[str, str]]) -> tuple[int, str]:
+    best, best_tool = 0, ""
+    run, prev = 0, None
+    for call in calls:
+        run = run + 1 if call == prev else 1
+        prev = call
+        if run > best:
+            best, best_tool = run, call[0]
+    return best, best_tool
+
+
+def check_tool_loops(
+    raw_transcript: str | None, *, threshold: int = DEFAULT_THRESHOLD,
+) -> LoopVerdict:
+    """Scan the current turn for stuck or churning tool-call loops."""
+    if not raw_transcript or threshold < 2:
+        return LoopVerdict()
+    calls = _turn_tool_calls(raw_transcript)
+    if not calls:
+        return LoopVerdict()
+    run, run_tool = _max_consecutive_run(calls)
+    if run >= threshold:
+        return LoopVerdict(
+            detected=True, tool=run_tool, repeats=run,
+            pattern="consecutive", total_tool_uses=len(calls),
+        )
+    (top_call, top_count), = Counter(calls).most_common(1)
+    if top_count >= threshold:
+        return LoopVerdict(
+            detected=True, tool=top_call[0], repeats=top_count,
+            pattern="repeated", total_tool_uses=len(calls),
+        )
+    return LoopVerdict(total_tool_uses=len(calls))