apsimo 1.3.0__py3-none-any.whl

apsimo/delivery/rate_limiter.py

@@ -0,0 +1,268 @@
+"""DeliveryRateLimiter — per-person rate limiting for proactive messages.
+
+Rules:
+  - Max 3 proactive messages per day per person
+  - No proactive messages between 22:00–08:00 local time (unless critical)
+  - At least 2 hours between proactive messages to the same person
+  - User can disable proactive messaging entirely (checked externally)
+
+Counts can optionally be persisted to a small SQLite file so restarts don't
+let a crashloop bypass the daily cap. Persistence is opt-in via ``db_path``;
+when ``db_path`` is None the limiter stays purely in-memory (used in tests).
+"""
+
+from __future__ import annotations
+
+from contextlib import closing
+import logging
+import sqlite3
+from collections import defaultdict
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from apsimo.util.quiet_hours import in_quiet_window
+
+logger = logging.getLogger(__name__)
+
+_MAX_PER_DAY = 3
+_COOLDOWN_HOURS = 2
+_QUIET_START_HOUR = 22
+_QUIET_END_HOUR = 8
+
+
+def _resolve_tz():
+    """Owner-local timezone for quiet hours: COLONY_TIMEZONE, else system, else UTC."""
+    import os
+    name = os.environ.get("COLONY_TIMEZONE", "").strip()
+    if name:
+        try:
+            from zoneinfo import ZoneInfo
+            return ZoneInfo(name)
+        except Exception:
+            logger.warning("rate_limiter: invalid COLONY_TIMEZONE %r, using system tz", name)
+    try:
+        local = datetime.now().astimezone().tzinfo
+        if local is not None:
+            return local
+    except Exception:
+        pass
+    return timezone.utc
+# Deliveries older than this many days are pruned at startup; nothing in the
+# rate-limit logic needs more than ~48h of history.
+_HISTORY_RETENTION_DAYS = 3
+
+
+class DeliveryRateLimiter:
+    """Per-person rate limiter for proactive message delivery.
+
+    Tracks delivery timestamps in memory for fast ``can_deliver`` checks, and
+    (optionally) mirrors them to a SQLite log so counts survive restarts.
+    """
+
+    def __init__(
+        self,
+        max_per_day: int = _MAX_PER_DAY,
+        cooldown_hours: int = _COOLDOWN_HOURS,
+        quiet_start_hour: int = _QUIET_START_HOUR,
+        quiet_end_hour: int = _QUIET_END_HOUR,
+        metrics: Optional[Any] = None,
+        db_path: Optional[Path] = None,
+        cap_provider: Optional[Any] = None,
+    ) -> None:
+        self._max_per_day = max_per_day
+        # Adaptive cap (Amendment 1.6): an optional callable(base:int)->int
+        # (the trust engine) that EARNS the daily cap upward with a proven
+        # delivery track record. Bounded by the provider; base is the floor
+        # semantics owners already know. Failure falls back to base.
+        self._cap_provider = cap_provider
+        self._cooldown = timedelta(hours=cooldown_hours)
+        self._quiet_start = quiet_start_hour
+        self._quiet_end = quiet_end_hour
+        self._metrics = metrics
+        # Quiet hours + the daily bucket are evaluated in the OWNER's local
+        # timezone (22:00-08:00 must mean their night, not a UTC window).
+        self._tz = _resolve_tz()
+
+        # person_id → list of delivery timestamps (UTC) today
+        self._daily_counts: Dict[str, List[datetime]] = defaultdict(list)
+        # person_id → last delivery timestamp (UTC)
+        self._last_delivery: Dict[str, Optional[datetime]] = defaultdict(lambda: None)
+        self._today = datetime.now(self._tz).date()
+
+        # Frustration back-off: person_id → probability (updated by autonomy loop)
+        self._frustration_cache: Dict[str, float] = {}
+
+        # Optional persistence. Failing to init the DB must not take the
+        # limiter offline — fall back to pure in-memory with a warning.
+        self._db_path: Optional[Path] = Path(db_path) if db_path else None
+        if self._db_path is not None:
+            try:
+                self._init_db()
+                self._reload_from_db()
+            except Exception as exc:
+                logger.warning(
+                    "rate_limiter: persistence disabled — %s: %s",
+                    type(exc).__name__, exc,
+                )
+                self._db_path = None
+
+    def can_deliver(self, person_id: str, urgency: float = 0.5) -> tuple[bool, str]:
+        """Check if a proactive message can be delivered to person_id.
+
+        Args:
+            person_id: Recipient identifier
+            urgency: Message urgency (0-1). Messages with urgency >= 0.9 bypass quiet hours.
+
+        Returns:
+            (allowed: bool, reason: str)
+        """
+        self._reset_if_new_day()
+
+        # Quiet hours check (bypassed for critical messages)
+        if urgency < 0.9 and self._in_quiet_hours():
+            return False, "quiet_hours"
+
+        # Frustration back-off (bypassed for critical messages)
+        if urgency < 0.9:
+            frust = self._frustration_cache.get(person_id, 0.0)
+            if frust > 0.5:
+                if self._metrics is not None:
+                    try:
+                        self._metrics.record_sentiment_suppression()
+                    except Exception:
+                        pass
+                return False, f"person_frustrated (p={frust:.0%})"
+
+        # Daily limit (adaptive when a trust cap provider is wired)
+        effective_max = self._max_per_day
+        if self._cap_provider is not None:
+            try:
+                effective_max = max(1, int(self._cap_provider(self._max_per_day)))
+            except Exception:
+                effective_max = self._max_per_day
+        count = len(self._daily_counts[person_id])
+        if count >= effective_max:
+            return False, f"daily_limit_reached ({count}/{effective_max})"
+
+        # Cooldown
+        last = self._last_delivery[person_id]
+        if last is not None:
+            elapsed = datetime.now(timezone.utc) - last
+            if elapsed < self._cooldown:
+                remaining = int((self._cooldown - elapsed).total_seconds()) // 60
+                return False, f"cooldown_active ({remaining}m remaining)"
+
+        return True, "ok"
+
+    def record_delivery(self, person_id: str) -> None:
+        """Mark that a proactive message was successfully delivered."""
+        self._reset_if_new_day()
+        now = datetime.now(timezone.utc)
+        self._daily_counts[person_id].append(now)
+        self._last_delivery[person_id] = now
+        if self._db_path is not None:
+            try:
+                with closing(sqlite3.connect(self._db_path)) as conn, conn:
+                    conn.execute(
+                        "INSERT INTO delivery_log (person_id, delivered_at) VALUES (?, ?)",
+                        (person_id, now.isoformat()),
+                    )
+            except Exception as exc:
+                logger.warning(
+                    "rate_limiter: failed to persist delivery for %s: %s",
+                    person_id, exc,
+                )
+        logger.debug(
+            "Delivery recorded for %s (count today: %d)",
+            person_id,
+            len(self._daily_counts[person_id]),
+        )
+
+    def update_frustration(self, person_id: str, probability: float) -> None:
+        """Update cached frustration probability for a person.
+
+        Called by the autonomy loop after running the state estimator.
+        Values above 0.5 will suppress non-critical deliveries.
+        """
+        self._frustration_cache[person_id] = probability
+
+    def daily_count(self, person_id: str) -> int:
+        """Return number of proactive deliveries today for a person."""
+        self._reset_if_new_day()
+        return len(self._daily_counts[person_id])
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def _reset_if_new_day(self) -> None:
+        """Reset daily counters when the UTC date rolls over."""
+        today = datetime.now(self._tz).date()
+        if today != self._today:
+            self._daily_counts.clear()
+            self._today = today
+
+    def _in_quiet_hours(self) -> bool:
+        """Return True if current time is within quiet hours (owner-local tz)."""
+        now = datetime.now(self._tz)
+        return in_quiet_window(
+            now.hour * 60 + now.minute,
+            self._quiet_start * 60,
+            self._quiet_end * 60,
+        )
+
+    # ------------------------------------------------------------------
+    # Persistence
+    # ------------------------------------------------------------------
+
+    def _init_db(self) -> None:
+        """Create the delivery-log table on first use and prune stale rows."""
+        assert self._db_path is not None
+        self._db_path.parent.mkdir(parents=True, exist_ok=True)
+        with closing(sqlite3.connect(self._db_path)) as conn, conn:
+            conn.execute(
+                "CREATE TABLE IF NOT EXISTS delivery_log ("
+                "  person_id TEXT NOT NULL,"
+                "  delivered_at TEXT NOT NULL"
+                ")"
+            )
+            conn.execute(
+                "CREATE INDEX IF NOT EXISTS idx_delivery_person_date "
+                "ON delivery_log(person_id, delivered_at)"
+            )
+            cutoff = (
+                datetime.now(timezone.utc) - timedelta(days=_HISTORY_RETENTION_DAYS)
+            ).isoformat()
+            conn.execute(
+                "DELETE FROM delivery_log WHERE delivered_at < ?", (cutoff,),
+            )
+
+    def _reload_from_db(self) -> None:
+        """Reload today's counts and the most-recent delivery per person."""
+        assert self._db_path is not None
+        # "Today" is the OWNER-LOCAL date (matching _reset_if_new_day), so
+        # its start is local midnight converted to UTC — the log stores UTC
+        # timestamps. Combining the local date with UTC midnight shifted the
+        # reload window by the UTC offset, over- or under-counting restarts.
+        today_start = datetime.combine(
+            self._today, datetime.min.time(), tzinfo=self._tz
+        ).astimezone(timezone.utc).isoformat()
+        with closing(sqlite3.connect(self._db_path)) as conn, conn:
+            # Today's deliveries → daily count
+            cur = conn.execute(
+                "SELECT person_id, delivered_at FROM delivery_log "
+                "WHERE delivered_at >= ? ORDER BY delivered_at",
+                (today_start,),
+            )
+            for person_id, ts_str in cur:
+                self._daily_counts[person_id].append(datetime.fromisoformat(ts_str))
+
+            # Most recent delivery per person → cooldown state (spans day boundary)
+            cur = conn.execute(
+                "SELECT person_id, MAX(delivered_at) FROM delivery_log "
+                "GROUP BY person_id"
+            )
+            for person_id, ts_str in cur:
+                if ts_str:
+                    self._last_delivery[person_id] = datetime.fromisoformat(ts_str)

apsimo/delivery/reachout_policy.py

@@ -0,0 +1,206 @@
+"""Reach-out delivery policy: sanitisation, staleness, quiet-hours urgency.
+
+These are the quality/safety guards applied to a user-facing reach-out
+initiative *before* it is handed to the guarded Hermes delivery path. They are
+generic and deployment-agnostic (patterns + env-tunable thresholds, no
+hardcoded identities or messages).
+
+* sanitise  -- strip raw conversation / skill / control markup from the
+               outward-facing text so Hermes composes from clean intent.
+* staleness -- drop reach-outs whose subject is older than a max age; a late
+               autonomous ping about a two-week-stale item is noise.
+* quiet     -- reach-out must respect quiet hours by default; a high
+               stale-age priority must NOT silently bypass the quiet window.
+               Only an explicit urgent signal may exceed the cap.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+# ---------------------------------------------------------------------------
+# Sanitisation
+# ---------------------------------------------------------------------------
+
+# ``<<RCSCTX ...>>`` and any other ``<<...>>`` control block, terminated or not
+# (titles are truncated so the closing ``>>`` is frequently missing).
+_ANGLE_BLOCK = re.compile(r"<<.*?>>", re.DOTALL)
+_ANGLE_UNTERMINATED = re.compile(r"<<[^>]*$", re.DOTALL)
+
+# Bracketed system/skill directives, e.g.
+#   [IMPORTANT: The user has invoked the "colony-operations" skill ...]
+#   [System note: Your previous turn was interrupted ...]
+_BRACKET_DIRECTIVE = re.compile(
+    r"\[\s*(?:IMPORTANT|SYSTEM\s*NOTE|SYSTEM|INTERNAL|CONTEXT|NOTE)\b[^\]]*\]",
+    re.IGNORECASE | re.DOTALL,
+)
+_BRACKET_UNTERMINATED = re.compile(
+    r"\[\s*(?:IMPORTANT|SYSTEM\s*NOTE|SYSTEM|INTERNAL|CONTEXT|NOTE)\b[^\]]*$",
+    re.IGNORECASE | re.DOTALL,
+)
+
+# Non-printable / control characters (keep tab/newline out of outward text too).
+_CONTROL = re.compile(r"[\x00-\x1f\x7f]")
+_WS = re.compile(r"\s+")
+
+_SANITIZE_FIELDS = ("title", "description", "rationale", "suggested_action")
+
+
+def sanitize_text(text: Optional[str]) -> str:
+    """Strip control/conversation/skill markup and collapse whitespace."""
+    if not text:
+        return ""
+    s = str(text)
+    s = _ANGLE_BLOCK.sub(" ", s)
+    s = _ANGLE_UNTERMINATED.sub(" ", s)
+    s = _BRACKET_DIRECTIVE.sub(" ", s)
+    s = _BRACKET_UNTERMINATED.sub(" ", s)
+    s = _CONTROL.sub(" ", s)
+    s = _WS.sub(" ", s).strip()
+    return s
+
+
+def sanitize_payload(payload: dict) -> dict:
+    """Return a copy of the initiative payload with its text fields cleaned."""
+    out = dict(payload)
+    for field in _SANITIZE_FIELDS:
+        value = out.get(field)
+        if isinstance(value, str):
+            out[field] = sanitize_text(value)
+    if not out.get("title"):
+        out["title"] = (out.get("description") or "")[:80] or "(follow-up)"
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Meaningful-content gate (applied at reach-out GENERATION time)
+# ---------------------------------------------------------------------------
+
+# Minimum real alphanumeric substance a reach-out source must retain after
+# sanitisation to be worth generating an initiative from. Low enough to keep
+# legitimately short subjects ("Call Bob"), high enough to drop fragments.
+_MIN_MEANINGFUL_CHARS = 4
+
+# Markers that a source turn is system / skill / non-conversational, i.e. not
+# genuine conversation or a real commitment. These identify origins that
+# sanitisation alone might leave partial residue from.
+_SYSTEM_ORIGIN = re.compile(
+    r"\binvoked\b.{0,60}?\bskill\b"          # "... invoked the <name> skill ..."
+    r"|previous turn was interrupted"
+    r"|\bsystem note\b"
+    r"|\bsystem[- ]?generated\b"
+    r"|conversation (?:was )?(?:interrupted|truncated|reset)"
+    r"|<\s*/?\s*system[\s>]",                 # <system> ... </system> style tags
+    re.IGNORECASE | re.DOTALL,
+)
+
+
+def is_system_origin(text: Optional[str]) -> bool:
+    """True if the raw source text is a system/skill/non-conversational turn."""
+    return bool(text) and bool(_SYSTEM_ORIGIN.search(str(text)))
+
+
+def meaningful_reachout_text(text: Optional[str]) -> str:
+    """Clean reach-out source text, or "" if it is not worth surfacing.
+
+    Returns the sanitised text when the source is genuine, human-meaningful
+    content; returns "" when the source is empty, of system/skill origin, or
+    has no real substance after sanitisation. Use at reach-out GENERATION time
+    so near-empty / system-origin junk never becomes an initiative.
+    """
+    if not text or is_system_origin(text):
+        return ""
+    cleaned = sanitize_text(text)
+    substance = re.sub(r"[^0-9a-z]+", "", cleaned.lower())
+    if len(substance) < _MIN_MEANINGFUL_CHARS:
+        return ""
+    return cleaned
+
+
+# ---------------------------------------------------------------------------
+# Staleness
+# ---------------------------------------------------------------------------
+
+# Structured "how overdue is the subject" signals. Deliberately excludes
+# contact-recency signals (e.g. days_since_contact) which are a *reason* to
+# reach out, not a disqualifier.
+_STALENESS_KEYS = (
+    "days_pending", "days_overdue", "days_stale", "stale_days", "age_days",
+)
+
+
+def _scan_staleness(obj: Any, depth: int = 2) -> float:
+    best = 0.0
+    if isinstance(obj, dict):
+        for key, value in obj.items():
+            if key in _STALENESS_KEYS and isinstance(value, (int, float)):
+                best = max(best, float(value))
+            elif depth > 0 and isinstance(value, (dict, list)):
+                best = max(best, _scan_staleness(value, depth - 1))
+    elif isinstance(obj, list) and depth > 0:
+        for value in obj:
+            best = max(best, _scan_staleness(value, depth - 1))
+    return best
+
+
+def reachout_age_days(payload: dict) -> float:
+    """Effective age of a reach-out: max of structured subject-staleness and
+    the initiative's own age since generation."""
+    age = _scan_staleness(payload.get("context") or {})
+    generated_at = payload.get("generated_at")
+    if generated_at:
+        try:
+            ts = datetime.fromisoformat(str(generated_at).replace("Z", "+00:00"))
+            if ts.tzinfo is None:
+                ts = ts.replace(tzinfo=timezone.utc)
+            init_age = (datetime.now(timezone.utc) - ts).total_seconds() / 86400.0
+            age = max(age, init_age)
+        except Exception:
+            pass
+    return age
+
+
+def max_age_days() -> float:
+    try:
+        return float(os.environ.get("COLONY_REACHOUT_MAX_AGE_DAYS", "7"))
+    except (TypeError, ValueError):
+        return 7.0
+
+
+def is_aged_out(payload: dict) -> bool:
+    """True if this reach-out is too old to be worth surfacing."""
+    return reachout_age_days(payload) > max_age_days()
+
+
+# ---------------------------------------------------------------------------
+# Quiet-hours urgency
+# ---------------------------------------------------------------------------
+
+# The rate limiter bypasses quiet hours at urgency >= 0.9. Reach-out urgency is
+# derived from priority, which for stale items pins to 1.0 -- an artifact, not a
+# genuine "wake them up" signal. Cap it below the bypass threshold by default.
+def _urgency_cap() -> float:
+    try:
+        return float(os.environ.get("COLONY_REACHOUT_URGENCY_CAP", "0.85"))
+    except (TypeError, ValueError):
+        return 0.85
+
+
+def _explicit_urgent(payload: dict) -> bool:
+    if payload.get("urgent") is True or payload.get("bypass_quiet_hours") is True:
+        return True
+    ctx = payload.get("context") or {}
+    if isinstance(ctx, dict):
+        return ctx.get("urgent") is True or ctx.get("bypass_quiet_hours") is True
+    return False
+
+
+def quiet_hours_urgency(payload: dict, raw_urgency: float) -> float:
+    """Urgency to use for the delivery gate. Reach-out respects quiet hours
+    unless an explicit urgent flag is set on the initiative/context."""
+    if _explicit_urgent(payload):
+        return raw_urgency
+    return min(raw_urgency, _urgency_cap())

apsimo/directed/__init__.py

@@ -0,0 +1,22 @@
+"""Directed action: owner directive -> gated, delegated, audited execution.
+
+Option A architecture: Colony never mutates external systems itself. It
+scopes the directive deterministically, gates it (boundaries first, then
+approval), dispatches the contract to an env-configured delegate, audits
+what actually happened against the granted scope, and reports back through
+the guarded reach-out path.
+"""
+
+from apsimo.directed.models import (
+    ScopedTask, ScopedTaskStore, ScopeLimits, READ_OPS, MUTATE_OPS,
+)
+from apsimo.directed.intake import scope_from_directive, resolve_targets
+from apsimo.directed.audit import audit_completion, audit_via_report
+from apsimo.directed.service import DirectedActionService, directed_mode
+
+__all__ = [
+    "ScopedTask", "ScopedTaskStore", "ScopeLimits", "READ_OPS", "MUTATE_OPS",
+    "scope_from_directive", "resolve_targets",
+    "audit_completion", "audit_via_report",
+    "DirectedActionService", "directed_mode",
+]

apsimo/directed/audit.py

@@ -0,0 +1,167 @@
+"""Post-action verification: what actually happened vs the granted scope.
+
+Two evidence sources, best-first:
+  1. Repo inspection (when a read-only local mirror of the target exists):
+     fetch the work branch and diff it against its merge-base -- files touched,
+     commit count, branch name are verified MECHANICALLY.
+  2. The delegate's structured report, cross-checked field by field.
+
+Any out-of-scope observation is a VIOLATION: flagged loudly, recorded on the
+task, and fed to the outcome feedback store by the service.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import logging
+import subprocess
+from typing import Any, Dict, List, Optional
+
+from apsimo.directed.models import ScopedTask, MUTATE_OPS
+
+logger = logging.getLogger(__name__)
+
+
+def _match_globs(path: str, globs: List[str]) -> bool:
+    p = (path or "").lstrip("./")
+    for g in globs or ["**"]:
+        if g in ("**", "*") or fnmatch.fnmatch(p, g) or fnmatch.fnmatch(p, g.rstrip("/") + "/**"):
+            return True
+    return False
+
+
+def _git(mirror_path: str, *args: str, timeout: int = 30) -> str:
+    out = subprocess.run(
+        ["git", "-C", mirror_path, *args],
+        capture_output=True, text=True, timeout=timeout,
+    )
+    if out.returncode != 0:
+        raise RuntimeError(out.stderr.strip()[:200])
+    return out.stdout
+
+
+def audit_via_mirror(task: ScopedTask, mirror_path: str, branch: str,
+                     base: str = "HEAD") -> Dict[str, Any]:
+    """Mechanical audit from a read-only mirror: fetch the branch, diff vs base."""
+    findings: List[str] = []
+    ok = True
+    try:
+        _git(mirror_path, "fetch", "origin", branch, timeout=60)
+        merge_base = _git(mirror_path, "merge-base", base, "FETCH_HEAD").strip()
+        commits = _git(mirror_path, "rev-list", "--count", f"{merge_base}..FETCH_HEAD").strip()
+        n_commits = int(commits or 0)
+        files = [f for f in _git(
+            mirror_path, "diff", "--name-only", merge_base, "FETCH_HEAD",
+        ).splitlines() if f.strip()]
+    except Exception as exc:
+        return {"method": "mirror", "ok": None,
+                "findings": [f"mirror inspection unavailable: {exc}"]}
+
+    if not branch.startswith(task.limits.branch_prefix):
+        ok = False
+        findings.append(f"branch {branch!r} outside required prefix {task.limits.branch_prefix!r}")
+    if n_commits > task.limits.max_commits:
+        ok = False
+        findings.append(f"{n_commits} commits exceeds cap {task.limits.max_commits}")
+    off = [f for f in files if not _match_globs(f, task.limits.path_globs)]
+    if off:
+        ok = False
+        findings.append(f"files outside allowed paths: {off[:10]}")
+    return {"method": "mirror", "ok": ok, "branch": branch,
+            "commits": n_commits, "files_touched": files[:100], "findings": findings}
+
+
+def audit_via_report(task: ScopedTask, report: Dict[str, Any]) -> Dict[str, Any]:
+    """Cross-check the delegate's structured report against the scope."""
+    findings: List[str] = []
+    ok = True
+    report = report or {}
+
+    ops = [str(o).lower() for o in (report.get("operations") or [])]
+    illegal = [o for o in ops if o not in set(task.allowed_ops)]
+    if illegal:
+        ok = False
+        findings.append(f"operations outside scope: {illegal}")
+
+    branch = str(report.get("branch") or "")
+    did_mutate = bool(set(ops) & MUTATE_OPS) or bool(report.get("commits"))
+    if did_mutate and not task.mutating:
+        ok = False
+        findings.append("delegate mutated on a read-only scope")
+    if did_mutate and branch and not branch.startswith(task.limits.branch_prefix):
+        ok = False
+        findings.append(f"branch {branch!r} outside required prefix {task.limits.branch_prefix!r}")
+
+    n_commits = int(report.get("commits") or 0)
+    if n_commits > task.limits.max_commits:
+        ok = False
+        findings.append(f"{n_commits} commits exceeds cap {task.limits.max_commits}")
+
+    if report.get("force_push"):
+        ok = False
+        findings.append("force push reported (never allowed)")
+    if report.get("deletions") and not task.limits.delete_allowed:
+        deld = report.get("deletions")
+        off = [f for f in deld if not _match_globs(str(f), task.limits.path_globs)] if isinstance(deld, list) else [str(deld)]
+        if off:
+            ok = False
+            findings.append(f"deletes outside scope: {off[:10]}")
+
+    files = [str(f) for f in (report.get("files_touched") or [])]
+    off = [f for f in files if not _match_globs(f, task.limits.path_globs)]
+    if off:
+        ok = False
+        findings.append(f"files outside allowed paths: {off[:10]}")
+
+    missing = [k for k in task.reporting if k not in report]
+    if missing:
+        findings.append(f"report missing expected fields: {missing}")
+        if ok:
+            # What was not reported cannot be verified: an empty/partial
+            # report is "unverified" (ok=None), never "clean" (ok=True).
+            ok = None
+
+    return {"method": "report", "ok": ok, "branch": branch, "commits": n_commits,
+            "files_touched": files[:100], "findings": findings}
+
+
+def audit_completion(task: ScopedTask, report: Dict[str, Any],
+                     mirror_path: Optional[str] = None) -> Dict[str, Any]:
+    """Full audit: mirror inspection when reachable, report cross-check always.
+
+    Verdict: 'clean' | 'violation' | 'unverified'. A violation from EITHER
+    source wins (fail loud).
+    """
+    report_audit = audit_via_report(task, report)
+    mirror_audit = None
+    branch = report_audit.get("branch") or ""
+    if mirror_path and branch:
+        mirror_audit = audit_via_mirror(task, mirror_path, branch)
+    elif mirror_path and not branch and task.mutating:
+        # A mirror was available but the mutating delegate reported no
+        # branch, so the mirror inspection silently could not run: the
+        # report side may not verdict "clean" on its own say-so.
+        report_audit["findings"].append(
+            "mirror audit skipped: no branch reported for mutating task")
+        if report_audit.get("ok") is True:
+            report_audit["ok"] = None
+
+    oks = [a["ok"] for a in (report_audit, mirror_audit) if a is not None]
+    if any(o is False for o in oks):
+        verdict = "violation"
+    elif any(o is True for o in oks):
+        verdict = "clean"
+    else:
+        verdict = "unverified"
+
+    result = {
+        "verdict": verdict,
+        "report_audit": report_audit,
+        "mirror_audit": mirror_audit,
+    }
+    if verdict == "violation":
+        all_findings = report_audit.get("findings", []) + (
+            (mirror_audit or {}).get("findings", []) if mirror_audit else [])
+        logger.warning("DIRECTED-ACTION SCOPE VIOLATION on %s: %s",
+                       task.id, "; ".join(all_findings)[:400])
+    return result