trap-cli 0.0.1__py3-none-any.whl

trap/cost/calculator.py

@@ -0,0 +1,41 @@
+"""Cost calculation for LLM token usage.
+
+Isolated so this logic can be moved server-side without touching the proxy infrastructure.
+The only public symbol is :func:`calculate_call_cost`.
+"""
+
+from __future__ import annotations
+
+from tokencost import TOKEN_COSTS as _TOKEN_COSTS  # type: ignore[import-untyped]
+from tokencost import calculate_cost_by_tokens as _calc_cost  # type: ignore[import-untyped]
+from tokencost import register_model_pattern as _register_pattern  # type: ignore[import-untyped]
+
+
+def _register_anthropic_version_patterns() -> None:
+    # Anthropic now returns version-based names (e.g. "claude-sonnet-4-6") but tokencost only
+    # has date-based entries (e.g. "claude-sonnet-4-20250514"). Register wildcard patterns so
+    # calculate_cost_by_tokens can resolve them via _normalize_model_for_pricing.
+    for pattern, canonical in [
+        ("claude-sonnet-4-*", "claude-sonnet-4-20250514"),
+        ("claude-opus-4-*", "claude-opus-4-20250514"),
+    ]:
+        entry = _TOKEN_COSTS.get(canonical)
+        if entry:  # pragma: no branch - both canonicals ship in tokencost
+            _register_pattern(
+                pattern,
+                float(entry["input_cost_per_token"]) * 1000,
+                float(entry["output_cost_per_token"]) * 1000,
+            )
+
+
+_register_anthropic_version_patterns()
+
+
+def calculate_call_cost(prompt_tokens: int, completion_tokens: int, model: str) -> float:
+    """Return the USD cost for one API call. Returns 0.0 if the model is not in the pricing table."""
+    try:
+        return float(
+            _calc_cost(prompt_tokens, model, "input") + _calc_cost(completion_tokens, model, "output")
+        )
+    except KeyError:
+        return 0.0

trap/cost/providers.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import enum
+import json
+import os
+from dataclasses import dataclass
+
+# -- Provider registry --------------------------------------------------------
+
+
+class _ProtocolStyle(enum.StrEnum):
+    ANTHROPIC_COMPATIBLE = "anthropic-compatible"
+    OPENAI_COMPATIBLE = "openai-compatible"
+
+    def parse(self, content_type: str, body: bytes) -> tuple[int, int, str | None]:
+        """Extract (prompt_tokens, completion_tokens, model) from an API response."""
+        is_streaming = "text/event-stream" in content_type
+        match (self, is_streaming):
+            case (_ProtocolStyle.ANTHROPIC_COMPATIBLE, True):
+                return self._parse_anthropic_style_sse(body.decode("utf-8", errors="replace"))
+            case (_ProtocolStyle.ANTHROPIC_COMPATIBLE, False):
+                return self._parse_json(body, "input_tokens", "output_tokens")
+            case (_ProtocolStyle.OPENAI_COMPATIBLE, True):
+                return self._parse_openai_style_sse(body.decode("utf-8", errors="replace"))
+            case (_ProtocolStyle.OPENAI_COMPATIBLE, False):
+                return self._parse_json(body, "prompt_tokens", "completion_tokens")
+            case _:  # pragma: no cover - exhaustive over the two styles above
+                raise ValueError(f"Unsupported protocol style: {self!r}")
+
+    @staticmethod
+    def _parse_json(body: bytes, prompt_key: str, completion_key: str) -> tuple[int, int, str | None]:
+        try:
+            data = json.loads(body)
+        except (json.JSONDecodeError, ValueError):
+            return 0, 0, None
+        usage = data.get("usage", {})
+        return usage.get(prompt_key, 0), usage.get(completion_key, 0), data.get("model")
+
+    @staticmethod
+    def _parse_anthropic_style_sse(text: str) -> tuple[int, int, str | None]:
+        prompt_tokens = 0
+        completion_tokens = 0
+        model = None
+        for line in text.splitlines():
+            if not line.startswith("data: "):
+                continue
+            try:
+                event = json.loads(line[6:])
+            except (json.JSONDecodeError, ValueError):
+                continue
+            if event.get("type") == "message_start":
+                msg = event.get("message", {})
+                usage = msg.get("usage", {})
+                prompt_tokens += usage.get("input_tokens", 0)
+                model = model or msg.get("model")
+            elif event.get("type") == "message_delta":
+                completion_tokens += event.get("usage", {}).get("output_tokens", 0)
+        return prompt_tokens, completion_tokens, model
+
+    @staticmethod
+    def _parse_openai_style_sse(text: str) -> tuple[int, int, str | None]:
+        for line in text.splitlines():
+            if not line.startswith("data: ") or "[DONE]" in line:
+                continue
+            try:
+                chunk = json.loads(line[6:])
+            except (json.JSONDecodeError, ValueError):
+                continue
+            usage = chunk.get("usage")
+            if usage:
+                return usage.get("prompt_tokens", 0), usage.get("completion_tokens", 0), chunk.get("model")
+        return 0, 0, None
+
+
+@dataclass(frozen=True)
+class _ProviderConfig:
+    key_env: str  # env var name for the API key
+    base_env: str  # env var name for the base URL override
+    upstream: str  # default upstream base URL
+    style: _ProtocolStyle  # request/response format used by this provider
+    always_intercept: bool = False  # True for OAuth-based tools that set no API key env var
+
+    def resolve_upstream(self) -> str:
+        """Return the effective upstream URL, honouring any user-set env override."""
+        return os.environ.get(self.base_env) or self.upstream
+
+
+# Central registry of supported LLM providers.
+#
+# To add a new provider: add an entry to _CONFIGS. Set always_intercept=True for
+# OAuth-based tools (Claude Code, Codex CLI, …) that set no API key env var but
+# still respect the base URL override.
+_CONFIGS: dict[str, _ProviderConfig] = {
+    "anthropic": _ProviderConfig(
+        "ANTHROPIC_API_KEY",
+        "ANTHROPIC_BASE_URL",
+        "https://api.anthropic.com",
+        style=_ProtocolStyle.ANTHROPIC_COMPATIBLE,
+        always_intercept=True,
+    ),
+    "openai": _ProviderConfig(
+        "OPENAI_API_KEY",
+        "OPENAI_BASE_URL",
+        "https://api.openai.com/v1",
+        style=_ProtocolStyle.OPENAI_COMPATIBLE,
+        always_intercept=True,
+    ),
+    "mistral": _ProviderConfig(
+        "MISTRAL_API_KEY",
+        "MISTRAL_BASE_URL",
+        "https://api.mistral.ai",
+        style=_ProtocolStyle.OPENAI_COMPATIBLE,
+    ),
+}
+
+
+def active_provider_configs() -> dict[str, _ProviderConfig]:
+    """Providers active in this environment: those with their API key env var set,
+    plus the always-intercept ones (OAuth tools that honour the base URL override)."""
+    return {
+        name: cfg for name, cfg in _CONFIGS.items() if os.environ.get(cfg.key_env) or cfg.always_intercept
+    }

trap/cost/proxy.py

@@ -0,0 +1,186 @@
+from __future__ import annotations
+
+import http.server
+import socketserver
+import threading
+from functools import cached_property
+from typing import TYPE_CHECKING
+
+import httpx
+
+from trap.cost.calculator import calculate_call_cost as _calc_cost
+from trap.cost.providers import active_provider_configs
+from trap.models.cost import CaseCost, ModelCost
+
+if TYPE_CHECKING:
+    from trap.cost.providers import _ProviderConfig
+
+# Three-class structure imposed by the socketserver framework:
+#
+#   CostProxy  →(creates one per active provider)→  _ProxyServer
+#                                                        │  .proxy = cost_proxy   (back-ref for bookkeeping)
+#                                                        └─→(framework)→  _ProxyHandler
+#                                                                             │  .server = proxy_server
+#
+# Each _ProxyServer is bound to its own port and knows its provider, protocol
+# style, and upstream URL — no per-request provider detection needed.
+# _ProxyHandler is ephemeral (one per request); _ProxyServer and CostProxy
+# live for the duration of a case run.
+
+
+class CostProxy:
+    """HTTP reverse proxy that intercepts LLM API calls to track token usage and cost per case."""
+
+    def __init__(self) -> None:
+        self._cost_buckets: dict[tuple[str, str | None], ModelCost] = {}
+        self._lock = threading.Lock()
+        # Servers are created here to bind ports immediately; threads start in start().
+        self._servers: dict[str, _ProxyServer] = {
+            name: _ProxyServer(self, name, cfg) for name, cfg in active_provider_configs().items()
+        }
+
+    @cached_property
+    def env_overrides(self) -> dict[str, str]:
+        """Env vars pointing each provider SDK at its proxy port."""
+        return {
+            server.base_env: f"http://127.0.0.1:{server.server_address[1]}"
+            for server in self._servers.values()
+        }
+
+    def start(self) -> None:
+        """Start serving threads for all provider proxy servers."""
+        for server in self._servers.values():
+            threading.Thread(target=server.serve_forever, daemon=True).start()
+
+    def stop(self) -> CaseCost:
+        """Shut down all proxy servers and return accumulated cost data."""
+        for server in self._servers.values():
+            server.shutdown()
+        with self._lock:
+            self._servers.clear()
+            return CaseCost(by_model=list(self._cost_buckets.values()))
+
+    def _accumulate(
+        self, provider: str, prompt_tokens: int, completion_tokens: int, model: str | None
+    ) -> None:
+        if not (prompt_tokens or completion_tokens):
+            return
+        call_cost = _calc_cost(prompt_tokens, completion_tokens, model) if model else 0.0
+        with self._lock:
+            key = (provider, model)
+            entry = self._cost_buckets.get(key)
+            if entry is None:
+                self._cost_buckets[key] = ModelCost(
+                    provider=provider,
+                    model=model,
+                    prompt_tokens=prompt_tokens,
+                    completion_tokens=completion_tokens,
+                    cost_usd=call_cost,
+                    calls=1,
+                )
+            else:
+                entry.prompt_tokens += prompt_tokens
+                entry.completion_tokens += completion_tokens
+                entry.cost_usd += call_cost
+                entry.calls += 1
+
+
+class _ProxyServer(socketserver.ThreadingMixIn, socketserver.TCPServer):
+    allow_reuse_address = True
+    daemon_threads = True
+    block_on_close = False
+
+    def __init__(self, proxy: CostProxy, provider: str, cfg: _ProviderConfig) -> None:
+        self.proxy = proxy
+        self.provider = provider
+        self.base_env = cfg.base_env
+        self.style = cfg.style
+        # Capture upstream before env_overrides() redirects base_env to the proxy itself.
+        self.upstream = cfg.resolve_upstream()
+        super().__init__(("127.0.0.1", 0), _ProxyHandler)
+
+
+class _ProxyHandler(http.server.BaseHTTPRequestHandler):
+    server: _ProxyServer  # type: ignore[assignment]
+
+    _STRIP_REQUEST_HEADERS = frozenset(
+        {
+            "host",
+            "content-length",
+            "accept-encoding",
+            "connection",
+            "keep-alive",
+            "proxy-authenticate",
+            "proxy-authorization",
+            "te",
+            "trailers",
+            "transfer-encoding",
+            "upgrade",
+        }
+    )
+    _STRIP_RESPONSE_HEADERS = frozenset(
+        {
+            "content-length",
+            "content-encoding",
+            "transfer-encoding",
+            "connection",
+            "keep-alive",
+            "proxy-authenticate",
+            "proxy-authorization",
+            "te",
+            "trailers",
+            "upgrade",
+        }
+    )
+
+    def do_POST(self) -> None:
+        self._forward()
+
+    def do_GET(self) -> None:
+        self._forward()
+
+    def _forward(self) -> None:
+        proxy = self.server.proxy
+        body = self._read_body()
+        status_code, content_type, chunks = self._relay_to_upstream(self.server.upstream, body)
+        if 0 < status_code < 400:
+            prompt_tokens, completion_tokens, model = self.server.style.parse(content_type, b"".join(chunks))
+            proxy._accumulate(self.server.provider, prompt_tokens, completion_tokens, model)
+
+    def _read_body(self) -> bytes:
+        n = int(self.headers.get("Content-Length", 0))
+        return self.rfile.read(n) if n else b""
+
+    def _relay_to_upstream(self, upstream: str, body: bytes) -> tuple[int, str, list[bytes]]:
+        target_url = upstream.rstrip("/") + self.path
+        forward_headers = {
+            k: v for k, v in self.headers.items() if k.lower() not in self._STRIP_REQUEST_HEADERS
+        }
+        status_code = 0
+        content_type = ""
+        chunks: list[bytes] = []
+        try:
+            with httpx.Client(timeout=300.0) as client:
+                with client.stream(self.command, target_url, content=body, headers=forward_headers) as resp:
+                    status_code = resp.status_code
+                    content_type = resp.headers.get("content-type", "")
+                    self.send_response(status_code)
+                    for h_name, h_val in resp.headers.multi_items():
+                        if h_name.lower() not in self._STRIP_RESPONSE_HEADERS:
+                            self.send_header(h_name, h_val)
+                    self.end_headers()
+                    for chunk in resp.iter_bytes():
+                        try:
+                            self.wfile.write(chunk)
+                            self.wfile.flush()
+                        except (BrokenPipeError, ConnectionResetError):  # pragma: no cover - client hangup
+                            break
+                        chunks.append(chunk)
+        except httpx.HTTPError as exc:
+            if not status_code:  # pragma: no branch - the set-status case needs a mid-stream failure
+                self.send_error(502, str(exc))
+        return status_code, content_type, chunks
+
+    def log_message(self, format: str, *args: object) -> None:
+        # Suppress the default per-request stderr logging from BaseHTTPRequestHandler.
+        pass

trap/display/__init__.py

@@ -0,0 +1,4 @@
+from trap.display.progress import CaseProgress
+from trap.display.submit import render_submit_result
+
+__all__ = ["CaseProgress", "render_submit_result"]

trap/display/progress.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from types import TracebackType
+from typing import Any
+
+from rich.console import Console
+from rich.progress import (
+    BarColumn,
+    MofNCompleteColumn,
+    Progress,
+    SpinnerColumn,
+    TaskProgressColumn,
+    TextColumn,
+    TimeElapsedColumn,
+)
+from rich.table import Column
+
+from trap.models import CaseResult, TraptaskCase
+
+
+class CaseProgress:
+    """Context manager that shows a Rich progress bar while cases run.
+
+    Pass ``console=None`` (the default) for a silent no-op.
+    """
+
+    def __init__(self, cases: tuple[TraptaskCase, ...], *, console: Console | None = None) -> None:
+        self._n = len(cases)
+        # Always build the Progress; disable=True (console=None) makes every call a
+        # no-op — Rich renders nothing rather than falling back to its stdout console.
+        self._progress = Progress(
+            SpinnerColumn(style="dark_orange"),
+            TextColumn("[bold]{task.description}", table_column=Column(width=30, no_wrap=True)),
+            BarColumn(complete_style="dark_orange", finished_style="bright_yellow"),
+            TaskProgressColumn(),
+            MofNCompleteColumn(),
+            TimeElapsedColumn(),
+            console=console,
+            transient=True,
+            disable=console is None,
+        )
+        self._task_id: Any = None
+
+    def __enter__(self) -> CaseProgress:
+        self._progress.start()
+        self._task_id = self._progress.add_task("starting...", total=self._n)
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        self._progress.stop()
+
+    def on_case_start(self, case_id: str) -> None:
+        self._progress.update(self._task_id, description=f"running  [bold]{case_id}[/bold]")
+
+    def on_case_done(self, _: CaseResult) -> None:
+        self._progress.advance(self._task_id)

trap/display/submit.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+
+def render_submit_result(resp_data: dict) -> None:
+    run_obj = resp_data.get("run") or {}
+    passed = run_obj.get("passed")
+    table = Table.grid(padding=(0, 2))
+    table.add_column(style="dim")
+    table.add_column()
+    table.add_row("status", "[green]✓ passed[/green]" if passed else "[red]✗ failed[/red]")
+    table.add_row("run", f"[bold]{run_obj.get('id', '?')}[/bold]")
+    table.add_row("score", f"[cyan]{run_obj.get('total_score')}[/cyan]")
+    if view_url := resp_data.get("view_url"):
+        table.add_row("url", f"[link={view_url}]{view_url}[/link]")
+    console.print(table)

trap/environment/__init__.py

@@ -0,0 +1,3 @@
+from .detector import EnvironmentDetector
+
+__all__ = ["EnvironmentDetector"]

trap/environment/detector.py

@@ -0,0 +1,81 @@
+# Best-effort detection of the host's runtime environment, recorded in the report
+# so runs are comparable across machines. Each probe is decorated with `@_safe`, so
+# a failing call degrades that field to None and never aborts the run.
+from __future__ import annotations
+
+import functools
+import platform
+from collections.abc import Callable
+
+import cpuinfo
+import psutil
+
+from trap.models.environment import Cpu, Environment
+
+
+class EnvironmentDetector:
+    """Probes the host machine for a fastfetch-like subset of its environment."""
+
+    @staticmethod
+    def _safe[**P, T](probe: Callable[P, T]) -> Callable[P, T | None]:
+        """Decorate a probe so any failure is swallowed to None — one bad field
+        can't sink the whole run."""
+
+        @functools.wraps(probe)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> T | None:
+            try:
+                return probe(*args, **kwargs)
+            except Exception:
+                return None
+
+        return wrapper
+
+    def detect(self) -> Environment:
+        return Environment(
+            os=self._get_os(),
+            kernel=self._get_kernel(),
+            arch=self._get_arch(),
+            cpu=Cpu(
+                model=self._get_cpu_model(),
+                cores_physical=self._get_cpu_cores_physical(),
+                cores_logical=self._get_cpu_cores_logical(),
+            ),
+            memory_total_bytes=self._get_memory_total_bytes(),
+        )
+
+    # -- probes: stdlib `platform` ------------------------------------------
+
+    @_safe
+    def _get_os(self) -> str | None:
+        if platform.system() == "Darwin":
+            ver = platform.mac_ver()[0]
+            return f"macOS {ver}" if ver else "macOS"
+        if platform.system() == "Linux":
+            return platform.freedesktop_os_release().get("PRETTY_NAME") or platform.system()
+        return platform.system() or None
+
+    @_safe
+    def _get_kernel(self) -> str | None:
+        return f"{platform.system()} {platform.release()}".strip() or None
+
+    @_safe
+    def _get_arch(self) -> str | None:
+        return platform.machine() or None
+
+    # -- probes: py-cpuinfo / psutil ----------------------------------------
+
+    @_safe
+    def _get_cpu_model(self) -> str | None:
+        return cpuinfo.get_cpu_info().get("brand_raw") or None
+
+    @_safe
+    def _get_cpu_cores_physical(self) -> int | None:
+        return psutil.cpu_count(logical=False)
+
+    @_safe
+    def _get_cpu_cores_logical(self) -> int | None:
+        return psutil.cpu_count(logical=True)
+
+    @_safe
+    def _get_memory_total_bytes(self) -> int | None:
+        return psutil.virtual_memory().total

trap/git_ops/__init__.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from trap.git_ops.base import GitOpsError
+from trap.git_ops.local import LocalRepo
+from trap.git_ops.remote import RemoteRepo
+from trap.git_ops.url import ParsedGitUrl
+
+__all__ = [
+    "GitOpsError",
+    "LocalRepo",
+    "ParsedGitUrl",
+    "RemoteRepo",
+]

trap/git_ops/base.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+
+# Progress callback used across clone/fetch/update steps; None disables progress output.
+ProgressCallback = Callable[[str], None] | None
+
+
+class GitOpsError(Exception):
+    pass

trap/git_ops/local.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import git
+
+from trap.git_ops.url import ParsedGitUrl
+from trap.models.provenance import GitProvenance
+
+
+class LocalRepo:
+    """An existing on-disk git checkout — read-only inspection.
+
+    Distinct from `RemoteRepo` (which clones a declared URL into a root): this wraps
+    a `git.Repo` already on disk — whether trap cloned it or the user pointed at
+    a local solution. Both clone-sync validation and report provenance go through
+    here, so the "open repo + read origin/commit/dirty" logic lives in one place.
+    """
+
+    def __init__(self, repo: git.Repo) -> None:
+        self.repo = repo
+
+    @classmethod
+    def open(cls, path: Path, *, search_parent: bool = False) -> LocalRepo | None:
+        """Open the git checkout at `path`, or None if it isn't a git repo."""
+        try:
+            return cls(git.Repo(path, search_parent_directories=search_parent))
+        except (git.InvalidGitRepositoryError, git.NoSuchPathError):
+            return None
+
+    @property
+    def origin_normalised_url(self) -> str | None:
+        """`origin` remote as a canonical https URL, or None if there's no origin."""
+        try:
+            return ParsedGitUrl.from_full_url(self.repo.remotes.origin.url).normalised_url
+        except AttributeError:
+            return None
+
+    def provenance(self) -> GitProvenance:
+        """{repo, commit} for a clean checkout with an origin, else empty.
+
+        Empty for a dirty tree (tracked-file changes), a remote-less repo, or any
+        git error — the run isn't reproducible from remote+commit alone, so we
+        claim nothing. Best-effort: a probe failure degrades to empty rather than
+        aborting an otherwise-complete run. Untracked files (run outputs under
+        .trap/, .venv, …) don't count as dirty.
+        """
+        try:
+            url = self.origin_normalised_url
+            if url is None or not self.repo.head.is_valid() or self.repo.is_dirty():
+                return GitProvenance()
+            return GitProvenance(repo=url, commit=self.repo.head.commit.hexsha)
+        except Exception:
+            return GitProvenance()
+
+    @classmethod
+    def provenance_of(cls, path: Path) -> GitProvenance:
+        """Provenance ({repo, commit}) of the checkout at `path`, empty if not a git repo."""
+        local_repo = cls.open(path, search_parent=True)
+        return local_repo.provenance() if local_repo else GitProvenance()

trap/git_ops/remote.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import git
+
+from trap.git_ops.base import GitOpsError, ProgressCallback
+from trap.git_ops.local import LocalRepo
+from trap.git_ops.rev import RevStrategy
+from trap.git_ops.url import ParsedGitUrl
+
+
+class RemoteRepo:
+    """A parsed git+ URL bound to a local clone directory (`root`).
+
+    `ensure()` clones it (fresh) or reconciles an existing clone. The caller
+    decides where to clone — `root` is the resolved directory, RemoteRepo holds no
+    default or base-dir policy. Takes a `ParsedGitUrl` (callers usually need its
+    `basename` to build `root` anyway, so parse once and pass it in).
+    """
+
+    def __init__(self, parsed: ParsedGitUrl, root: Path) -> None:
+        self.parsed = parsed
+        self.strategy = RevStrategy.for_rev(parsed.rev)
+        self.root = root
+
+    @property
+    def local_dir(self) -> Path:
+        """Clone root, descended into the requested subdirectory if any."""
+        if self.parsed.subdirectory:
+            return self.root / self.parsed.subdirectory
+        return self.root
+
+    def ensure(self, progress_func: ProgressCallback = None) -> bool:
+        """Clone (fresh) or sync (existing) the repo into `root`.
+
+        Returns True when code changed (fresh clone OR branch fast-forwarded) —
+        callers auto-run setup_cmd then.  Read `local_dir` for the resolved path.
+        """
+        return self._sync(progress_func) if self.root.exists() else self._clone(progress_func)
+
+    def _clone(self, progress_func: ProgressCallback) -> bool:
+        """Fresh clone — common scaffolding here; rev-specific clone via the strategy."""
+        if progress_func:
+            progress_func(f"cloning {self.parsed.repo} → {self.root}")
+        try:
+            self.strategy.clone(self.parsed.repo, self.root)
+        except git.GitCommandError as exc:
+            raise GitOpsError(f"git clone failed:\n{exc.stderr.strip()}") from exc
+        return True
+
+    def _sync(self, progress_func: ProgressCallback) -> bool:
+        """Existing clone — validate remote here; rev-specific update via the strategy."""
+        local_repo = LocalRepo.open(self.root)
+        if local_repo is None:
+            raise GitOpsError(f"{self.root} is not a git repository")
+
+        actual = local_repo.origin_normalised_url
+        expected = self.parsed.normalised_url
+        if actual != expected:
+            raise GitOpsError(f"repo mismatch at {self.root}:\n  declared: {expected}\n  found:    {actual}")
+
+        return self.strategy.reconcile(local_repo.repo, self.root, progress_func)