arkaos 4.45.0 → 4.46.0

package/core/governance/evidence_checks.py

@@ -97,6 +97,19 @@ _SECURITY_PATTERNS: tuple[tuple[str, re.Pattern[str]], ...] = (
     ("curl-pipe-shell", re.compile(r"curl[^|\n]*\|\s*(?:ba|z)?sh\b")),
 )
 
+# Sanctioned per-line suppression: `arka:sec-ok(<pattern-id>): <reason>`.
+# A line that DEFINES a dangerous pattern — a deny rule, an egress
+# scanner signature — necessarily contains the pattern it names, and a
+# sweep with no escape valve forces either scanner evasion (splitting
+# the literal) or a permanently red gate. The valve is deliberately
+# narrow: the id must name the exact matched pattern and the reason
+# must be non-empty. The reason is a formality for the record; the
+# CONTROL is visibility — every suppression is carried in the
+# structured `suppressions` / `suppressed_count` fields of the
+# CheckResult (immune to summary truncation), and the string summary
+# ends with a `(+N more suppressed)` marker when the listing is capped.
+_SEC_OK_RE = re.compile(r"arka:sec-ok\(([a-z0-9-]+)\):\s*(\S.+)")
+
 
 @dataclass
 class CheckResult:
@@ -109,6 +122,11 @@ class CheckResult:
     exit_code: int | None
     summary: str
     details_path: str | None = None
+    # security-grep only: the FULL suppression record, structured so it
+    # bypasses summary truncation entirely. Empty for other checks and
+    # for pre-existing corpus records.
+    suppressions: list[str] = field(default_factory=list)
+    suppressed_count: int = 0
 
 
 @dataclass
@@ -509,26 +527,48 @@ def _check_coverage(
     return _skip("coverage", "no coverage.xml or junit.xml on disk")
 
 
-def _grep_lines(path: Path, lines: list[str]) -> list[str]:
-    hits = []
-    for lineno_or_text in lines:
-        for name, pattern in _SECURITY_PATTERNS:
-            if pattern.search(lineno_or_text):
-                hits.append(f"{path} [{name}]: {lineno_or_text.strip()[:120]}")
-    return hits
+def _line_matches(line: str) -> tuple[list[str], list[str]]:
+    """(flagged, suppressed) pattern names for one line.
+
+    A pattern is suppressed only when the line carries an
+    ``arka:sec-ok(<id>): <reason>`` annotation whose id names EXACTLY
+    that pattern and whose reason is non-empty. A wrong id, a bare
+    annotation, or an empty reason suppresses nothing.
+    """
+    ok = _SEC_OK_RE.search(line)
+    allowed = ok.group(1) if ok else None
+    flagged: list[str] = []
+    suppressed: list[str] = []
+    for name, pattern in _SECURITY_PATTERNS:
+        if pattern.search(line):
+            (suppressed if name == allowed else flagged).append(name)
+    return flagged, suppressed
+
+
+def _grep_lines(
+    path: Path, lines: list[tuple[int, str]]
+) -> tuple[list[str], list[str]]:
+    hits, suppressed = [], []
+    for lineno, text in lines:
+        flagged, quiet = _line_matches(text)
+        hits.extend(
+            f"{path}:{lineno} [{n}]: {text.strip()[:120]}" for n in flagged
+        )
+        suppressed.extend(f"{path}:{lineno} [{n}]" for n in quiet)
+    return hits, suppressed
 
 
-def _grep_file(path: Path) -> list[str]:
+def _grep_file(path: Path) -> tuple[list[str], list[str]]:
     try:
         text = path.read_text(encoding="utf-8", errors="ignore")
     except OSError:
-        return []
-    hits = []
+        return [], []
+    hits, suppressed = [], []
     for lineno, line in enumerate(text.splitlines(), start=1):
-        for name, pattern in _SECURITY_PATTERNS:
-            if pattern.search(line):
-                hits.append(f"{path}:{lineno} [{name}]")
-    return hits
+        flagged, quiet = _line_matches(line)
+        hits.extend(f"{path}:{lineno} [{n}]" for n in flagged)
+        suppressed.extend(f"{path}:{lineno} [{n}]" for n in quiet)
+    return hits, suppressed
 
 
 def _diff_base(project_dir: Path) -> str | None:
@@ -543,11 +583,18 @@ def _diff_base(project_dir: Path) -> str | None:
     return None
 
 
-def _added_lines(project_dir: Path, base: str, name: str) -> list[str] | None:
-    """Lines ADDED by this change (committed + working tree) vs base.
+_HUNK_HEADER_RE = re.compile(r"^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@")
+
+
+def _added_lines(
+    project_dir: Path, base: str, name: str
+) -> list[tuple[int, str]] | None:
+    """(line number, text) pairs ADDED by this change vs base.
 
-    Returns None when git cannot answer — callers fall back to the
-    whole-file scan rather than silently passing.
+    Line numbers come from the ``+`` side of the ``-U0`` hunk headers,
+    so findings carry a location in both scan modes. Returns None when
+    git cannot answer — callers fall back to the whole-file scan
+    rather than silently passing.
     """
     proc = subprocess.run(
         ["git", "diff", "-U0", base, "--", name],
@@ -555,11 +602,16 @@ def _added_lines(project_dir: Path, base: str, name: str) -> list[str] | None:
     )
     if proc.returncode != 0:
         return None
-    return [
-        line[1:]
-        for line in proc.stdout.splitlines()
-        if line.startswith("+") and not line.startswith("+++")
-    ]
+    added: list[tuple[int, str]] = []
+    lineno = 0
+    for line in proc.stdout.splitlines():
+        header = _HUNK_HEADER_RE.match(line)
+        if header:
+            lineno = int(header.group(1))
+        elif line.startswith("+") and not line.startswith("+++"):
+            added.append((lineno, line[1:]))
+            lineno += 1
+    return added
 
 
 def _check_security_grep(
@@ -578,29 +630,56 @@ def _check_security_grep(
     if not changed:
         return _skip("security-grep", "no changed files provided")
     base = _diff_base(project_dir)
-    hits: list[str] = []
+    hits, suppressed = [], []
     mode = "added-lines" if base else "whole-file"
     for name in changed:
-        path = Path(name)
-        if not path.is_absolute():
-            path = project_dir / name
-        if not path.is_file():
+        path = _resolve_changed_file(project_dir, name)
+        if path is None:
             continue
         added = _added_lines(project_dir, base, name) if base else None
-        if added is None:
-            hits.extend(_grep_file(path))
-        else:
-            hits.extend(_grep_lines(path, added))
+        found, quiet = (
+            _grep_file(path) if added is None else _grep_lines(path, added)
+        )
+        hits.extend(found)
+        suppressed.extend(quiet)
+    return CheckResult(
+        check="security-grep", ran=True, passed=not hits,
+        command=f"security-grep ({mode}) over {len(changed)} changed file(s)",
+        exit_code=None, summary=_tail(_grep_summary(hits, suppressed)),
+        suppressions=list(suppressed), suppressed_count=len(suppressed),
+    )
+
+
+def _resolve_changed_file(project_dir: Path, name: str) -> Path | None:
+    path = Path(name)
+    if not path.is_absolute():
+        path = project_dir / name
+    return path if path.is_file() else None
+
+
+def _grep_summary(hits: list[str], suppressed: list[str]) -> str:
+    """String form of the sweep outcome, capped but never quietly.
+
+    Both listings cap at ``_MAX_GREP_HITS`` with an explicit ``+N
+    more`` marker. The suppression record rides at the END of the
+    string because ``_tail`` keeps the tail — and the authoritative
+    record is the structured ``suppressions`` field, not this string.
+    """
     summary = (
         "no security patterns matched"
         if not hits
         else "; ".join(hits[:_MAX_GREP_HITS])
     )
-    return CheckResult(
-        check="security-grep", ran=True, passed=not hits,
-        command=f"security-grep ({mode}) over {len(changed)} changed file(s)",
-        exit_code=None, summary=_tail(summary),
-    )
+    if len(hits) > _MAX_GREP_HITS:
+        summary += f" (+{len(hits) - _MAX_GREP_HITS} more hits)"
+    if suppressed:
+        summary += (
+            f"; suppressed with arka:sec-ok justification: "
+            f"{'; '.join(suppressed[:_MAX_GREP_HITS])}"
+        )
+        if len(suppressed) > _MAX_GREP_HITS:
+            summary += f" (+{len(suppressed) - _MAX_GREP_HITS} more suppressed)"
+    return summary
 
 
 def _check_spellcheck(

package/core/harness/__init__.py

@@ -0,0 +1,22 @@
+"""Harness ownership foundation (workstream C, PR-C1).
+
+The harness — the Claude Code configuration that decides what actually
+executes on the operator's machine — has had no owner: the installer
+re-writes the surface only when the operator runs install or update
+(``installer/update.js``), nothing detects or repairs drift between
+those runs, ``harness_scanner`` grades it but nothing closes the loop,
+and the executed desired state lives only inside installer JavaScript.
+This package is the read-only foundation the ``ClaudeConfigManager``
+(C2) builds on:
+
+- ``paths``      — canonical locations, resolved at call time
+- ``json_store`` — tolerant reads, atomic writes, ``merge_unique``
+- ``manifest``   — Pydantic schema for ``~/.arkaos/ownership.json``
+- ``spec``       — desired state keyed by runtime (parity-pinned to the
+  installer sources by ``test_harness_spec.py``)
+- ``drift``      — spec-vs-disk comparison, never raises
+
+Nothing in this package mutates the operator's machine. The only writer
+(``json_store.write_json_atomic``) is a primitive exercised by tests and
+reserved for C2's assert/restore paths.
+"""

package/core/harness/drift.py

@@ -0,0 +1,317 @@
+"""Spec-vs-disk drift detection for the Claude Code harness (PR-C1).
+
+``scan()`` reads the operator's ``settings.json`` and reports where it
+diverges from ``core.harness.spec``. Read-only by contract — the same
+rule ``harness_scanner`` holds: a scan never mutates what it measures,
+prints nothing, exits nothing, and NEVER raises on hostile input (a
+truncated or binary settings file is a finding, not a traceback).
+
+Drift vocabulary, aligned with the ownership policies:
+
+- ``missing``  — an ArkaOS-managed entry is absent: an owned entry
+  (own / own-subset), a seed surface that was never seeded, or the
+  settings file itself.
+- ``diverged`` — an ArkaOS-owned entry is present but altered.
+- ``adopted``  — a ``seed`` surface the operator changed; the operator
+  won, drift REPORTS it and C2's assert, once it ships, must never
+  revert it.
+- ``unreadable`` — the settings file could not be used, or the scan
+  itself could not run (unknown runtime, internal failure).
+
+Operator additions — extra hook entries, extra deny rules, unknown
+settings keys — are NOT drift. Under own-subset the operator's material
+is legitimate content, and flagging it would teach the operator to
+ignore the report (the harness_scanner noise lesson).
+"""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass, field
+from enum import StrEnum
+from pathlib import Path
+from typing import Any
+
+from core.harness import json_store, paths
+from core.harness.spec import HookRegistration, RuntimeSpec, spec_for
+
+
+class DriftStatus(StrEnum):
+    """Kind of divergence between spec and disk."""
+
+    MISSING = "missing"
+    DIVERGED = "diverged"
+    ADOPTED = "adopted"
+    UNREADABLE = "unreadable"
+
+
+@dataclass(frozen=True)
+class DriftFinding:
+    """One divergence, with enough detail to act on."""
+
+    surface: str
+    status: DriftStatus
+    where: str
+    detail: str
+
+    def to_dict(self) -> dict:
+        return {
+            "surface": self.surface,
+            "status": self.status.value,
+            "where": self.where,
+            "detail": self.detail,
+        }
+
+
+@dataclass
+class DriftReport:
+    """Result of one drift scan against one settings file."""
+
+    settings_path: Path
+    runtime: str
+    findings: list[DriftFinding] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        """True when nothing ArkaOS-owned is missing, diverged or unreadable.
+
+        ``adopted`` findings do not fail the report — the operator
+        winning a seed surface is recorded state, not a defect.
+        """
+        return not [
+            f
+            for f in self.findings
+            if f.status is not DriftStatus.ADOPTED
+        ]
+
+    def to_dict(self) -> dict:
+        return {
+            "settings_path": str(self.settings_path),
+            "runtime": self.runtime,
+            "ok": self.ok,
+            "findings": [f.to_dict() for f in self.findings],
+        }
+
+
+def scan(
+    home: Path | None = None,
+    runtime: str = "claude-code",
+    platform: str | None = None,
+    hooks_root: str | None = None,
+) -> DriftReport:
+    """Compare the harness on disk to the runtime spec. Never raises.
+
+    ``platform`` defaults to ``sys.platform`` (``win32`` skips
+    posix-only registrations); ``hooks_root`` overrides the ArkaOS root
+    used to evaluate ``conditional`` registrations.
+    """
+    settings_path = paths.claude_settings_path(home)
+    report = DriftReport(settings_path=settings_path, runtime=runtime)
+    spec = _spec_or_finding(report, runtime)
+    if spec is None:
+        return report
+    try:
+        _scan_into(report, spec, platform, hooks_root)
+    except Exception as exc:  # never-raises boundary
+        report.findings.append(
+            DriftFinding(
+                "settings", DriftStatus.UNREADABLE, str(settings_path),
+                f"scan aborted: {type(exc).__name__}: {exc}",
+            )
+        )
+    return report
+
+
+def _spec_or_finding(report: DriftReport, runtime: str) -> RuntimeSpec | None:
+    """Resolve the runtime spec, or record why the scan cannot run.
+
+    An unknown runtime is a caller problem, not a settings problem —
+    naming the settings file would send the operator to debug the
+    wrong thing.
+    """
+    try:
+        return spec_for(runtime)
+    except ValueError as exc:
+        report.findings.append(
+            DriftFinding("runtime", DriftStatus.UNREADABLE, runtime, str(exc))
+        )
+        return None
+
+
+# Operator-facing phrasing per load error; the installer remediation is
+# only true for the missing case — re-running it does not repair a
+# corrupted or oversized file.
+_LOAD_ERROR_DETAIL = {
+    "missing": "settings file missing; run the installer to seed it",
+    "invalid-json": "settings file is not valid JSON",
+    "not-an-object": "settings file is not a JSON object",
+    "unreadable": "settings file could not be read",
+    "oversized": "settings file exceeds the 2 MiB read ceiling",
+}
+
+
+def _scan_into(
+    report: DriftReport,
+    spec: RuntimeSpec,
+    platform: str | None,
+    hooks_root: str | None,
+) -> None:
+    loaded = json_store.load_json(report.settings_path)
+    if not loaded.ok:
+        status = (
+            DriftStatus.MISSING
+            if loaded.error == "missing"
+            else DriftStatus.UNREADABLE
+        )
+        detail = _LOAD_ERROR_DETAIL.get(
+            loaded.error or "", f"settings file unusable: {loaded.error}"
+        )
+        report.findings.append(
+            DriftFinding("settings", status, str(report.settings_path), detail)
+        )
+        return
+    settings = loaded.data or {}
+    _check_hooks(report, spec, settings, platform, hooks_root)
+    _check_hard_deny(report, spec, settings)
+    _check_status_line(report, settings)
+    _check_worktree(report, settings)
+
+
+def _check_hooks(
+    report: DriftReport,
+    spec: RuntimeSpec,
+    settings: dict[str, Any],
+    platform: str | None,
+    hooks_root: str | None,
+) -> None:
+    hooks = settings.get("hooks")
+    hooks = hooks if isinstance(hooks, dict) else {}
+    is_windows = (platform or sys.platform) == "win32"
+    for reg in spec.hook_registrations:
+        if reg.posix_only and is_windows:
+            continue
+        if reg.conditional and not _script_deployed(reg, hooks_root):
+            continue
+        _check_registration(report, reg, hooks.get(reg.event))
+
+
+def _check_registration(
+    report: DriftReport, reg: HookRegistration, entries: Any
+) -> None:
+    where = f"hooks.{reg.event}" + (
+        f"[matcher={reg.matcher}]" if reg.matcher else ""
+    )
+    entry = _find_entry(reg, entries)
+    if entry is None:
+        report.findings.append(
+            DriftFinding(
+                "settings:hooks", DriftStatus.MISSING, where,
+                f"no {reg.script} entry registered for this event",
+            )
+        )
+        return
+    timeout = entry.get("timeout")
+    if timeout != reg.timeout:
+        report.findings.append(
+            DriftFinding(
+                "settings:hooks", DriftStatus.DIVERGED, where,
+                f"timeout is {timeout!r}, spec says {reg.timeout}",
+            )
+        )
+
+
+def _find_entry(reg: HookRegistration, entries: Any) -> dict | None:
+    """The ArkaOS inner hook entry for ``reg``, or None."""
+    if not isinstance(entries, list):
+        return None
+    wanted = {f"{reg.script}.sh", f"{reg.script}.ps1", f"{reg.script}.cjs"}
+    for group in entries:
+        if not isinstance(group, dict):
+            continue
+        if (group.get("matcher") or None) != reg.matcher:
+            continue
+        for inner in group.get("hooks") or []:
+            if not isinstance(inner, dict):
+                continue
+            command = str(inner.get("command", ""))
+            if command and Path(command).name in wanted:
+                return inner
+    return None
+
+
+def _script_deployed(reg: HookRegistration, hooks_root: str | None) -> bool:
+    try:
+        hooks = paths.hooks_dir(hooks_root)
+        return any(
+            (hooks / f"{reg.script}{ext}").is_file()
+            for ext in (".sh", ".ps1", ".cjs")
+        )
+    except OSError:
+        return False
+
+
+def _check_hard_deny(
+    report: DriftReport, spec: RuntimeSpec, settings: dict[str, Any]
+) -> None:
+    auto_mode = settings.get("autoMode")
+    auto_mode = auto_mode if isinstance(auto_mode, dict) else {}
+    rules = auto_mode.get("hard_deny")
+    rules = rules if isinstance(rules, list) else []
+    present = {r for r in rules if isinstance(r, str)}
+    absent = [r for r in spec.hard_deny_rules if r not in present]
+    if not absent:
+        return
+    examples = ", ".join(absent[:3])
+    report.findings.append(
+        DriftFinding(
+            "settings:autoMode.hard_deny", DriftStatus.MISSING,
+            "autoMode.hard_deny",
+            f"{len(absent)} of {len(spec.hard_deny_rules)} curated deny "
+            f"rules absent (e.g. {examples})",
+        )
+    )
+
+
+def _check_status_line(report: DriftReport, settings: dict[str, Any]) -> None:
+    status_line = settings.get("statusLine")
+    if status_line is None:
+        report.findings.append(
+            DriftFinding(
+                "settings:statusLine", DriftStatus.MISSING, "statusLine",
+                "status line not seeded",
+            )
+        )
+    elif not _is_arkaos_statusline(status_line):
+        report.findings.append(
+            DriftFinding(
+                "settings:statusLine", DriftStatus.ADOPTED, "statusLine",
+                "operator-configured status line; seed policy adopts it",
+            )
+        )
+
+
+def _check_worktree(report: DriftReport, settings: dict[str, Any]) -> None:
+    worktree = settings.get("worktree")
+    if worktree is None:
+        report.findings.append(
+            DriftFinding(
+                "settings:worktree", DriftStatus.MISSING, "worktree",
+                "worktree.baseRef default not seeded",
+            )
+        )
+    elif not (
+        isinstance(worktree, dict) and worktree.get("baseRef") == "head"
+    ):
+        report.findings.append(
+            DriftFinding(
+                "settings:worktree", DriftStatus.ADOPTED, "worktree",
+                "operator-configured worktree; seed policy adopts it",
+            )
+        )
+
+
+def _is_arkaos_statusline(status_line: Any) -> bool:
+    if not isinstance(status_line, dict):
+        return False
+    command = str(status_line.get("command", ""))
+    return Path(command.strip('"')).name in ("statusline.sh", "statusline.ps1")

package/core/harness/json_store.py

@@ -0,0 +1,119 @@
+"""Tolerant JSON reads, atomic writes, and order-preserving merges.
+
+The harness surfaces this package reads (``settings.json``,
+``ownership.json``, ``hard-deny.json``) are operator-owned files that
+can be truncated, binary, or hand-edited into invalid JSON at any time.
+A loader that raises on that input takes the whole caller down with it —
+the ``harness_scanner`` contract applies here too: hostile input is a
+reported condition, never a traceback.
+
+The writer is the C2 primitive: same-directory tmp file + ``os.replace``
+so a crash mid-write leaves the previous content intact, and the target
+file's permission bits survive the replacement.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import tempfile
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+# Same ceiling as core.governance.harness_scanner: a settings file
+# larger than this is itself a finding, not something to slurp.
+MAX_JSON_BYTES = 2 * 1024 * 1024
+
+
+@dataclass(frozen=True)
+class LoadResult:
+    """Outcome of a tolerant JSON load.
+
+    ``data`` is the parsed top-level object on success, ``None``
+    otherwise; ``error`` names the failure (``missing``, ``oversized``,
+    ``unreadable``, ``invalid-json``, ``not-an-object``) or is ``None``.
+    """
+
+    data: dict[str, Any] | None
+    error: str | None
+
+    @property
+    def ok(self) -> bool:
+        return self.error is None
+
+
+def load_json(path: Path) -> LoadResult:
+    """Read ``path`` as a JSON object without ever raising."""
+    try:
+        if not path.is_file():
+            return LoadResult(None, "missing")
+        if path.stat().st_size > MAX_JSON_BYTES:
+            return LoadResult(None, "oversized")
+        raw = path.read_text(encoding="utf-8", errors="strict")
+    except (OSError, UnicodeDecodeError):
+        return LoadResult(None, "unreadable")
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError:
+        return LoadResult(None, "invalid-json")
+    if not isinstance(data, dict):
+        return LoadResult(None, "not-an-object")
+    return LoadResult(data, None)
+
+
+def write_json_atomic(path: Path, data: dict[str, Any]) -> None:
+    """Write ``data`` to ``path`` via same-dir tmp + ``os.replace``.
+
+    Raises on failure (callers decide policy); guarantees the target is
+    either the previous content or the complete new content, never a
+    partial write. Existing permission bits on ``path`` are preserved.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    previous_mode = _current_mode(path)
+    payload = json.dumps(data, indent=2, ensure_ascii=False) + "\n"
+    fd, tmp_name = tempfile.mkstemp(
+        prefix=f".{path.name}.", suffix=".tmp", dir=path.parent
+    )
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(payload)
+            handle.flush()
+            os.fsync(handle.fileno())
+        if previous_mode is not None:
+            os.chmod(tmp_name, previous_mode)
+        os.replace(tmp_name, path)
+    except BaseException:
+        _unlink_quiet(tmp_name)
+        raise
+
+
+def merge_unique(*sequences: Iterable[str]) -> list[str]:
+    """Order-preserving union; the FIRST occurrence of a value wins.
+
+    Callers encode precedence by argument order — putting the
+    operator's entries first keeps them ahead of shipped defaults, the
+    same contract as ``mergeUnique`` in ``installer/hard-deny.js``.
+    """
+    seen: set[str] = set()
+    merged: list[str] = []
+    for sequence in sequences:
+        for value in sequence:
+            if value not in seen:
+                seen.add(value)
+                merged.append(value)
+    return merged
+
+
+def _current_mode(path: Path) -> int | None:
+    try:
+        return path.stat().st_mode & 0o7777
+    except OSError:
+        return None
+
+
+def _unlink_quiet(name: str) -> None:
+    with contextlib.suppress(OSError):
+        os.unlink(name)