@maudecode/talaria-web 0.0.0

package/sidecar/talaria_sidecar/methods/usage.py

@@ -0,0 +1,59 @@
+"""``usage.*``: provider account usage through ``agent.account_usage``."""
+
+from __future__ import annotations
+
+import dataclasses
+import logging
+from typing import Any
+
+from ..errors import InvalidParams, RpcError
+from ..home import profile_home_param, scoped_home
+from ..rpc import CallContext
+
+log = logging.getLogger("talaria_sidecar.usage")
+
+
+def _plain(value: Any) -> Any:
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        return {k: _plain(v) for k, v in dataclasses.asdict(value).items()}
+    if isinstance(value, dict):
+        return {str(k): _plain(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple, set)):
+        return [_plain(v) for v in value]
+    if isinstance(value, (str, int, float, bool)) or value is None:
+        return value
+    if hasattr(value, "__dict__"):
+        return {k: _plain(v) for k, v in vars(value).items() if not k.startswith("_")}
+    return str(value)
+
+
+def account(provider: str, *, base_url: str | None, api_key: str | None) -> dict | None:
+    try:
+        from agent.account_usage import fetch_account_usage
+    except Exception as exc:  # noqa: BLE001
+        raise RpcError(f"account usage unavailable: {exc}", condition="usage_unavailable") from exc
+    try:
+        snapshot = fetch_account_usage(provider, base_url=base_url, api_key=api_key)
+    except Exception as exc:  # noqa: BLE001
+        log.debug("fetch_account_usage(%r) failed", provider, exc_info=True)
+        return {"provider": provider, "available": False, "unavailable_reason": f"{type(exc).__name__}: {exc}", "windows": [], "details": []}
+    if snapshot is None:
+        return None
+    row = _plain(snapshot)
+    if not isinstance(row, dict):
+        return None
+    row.setdefault("provider", provider)
+    row["windows"] = [w for w in (row.get("windows") or []) if isinstance(w, dict)]
+    row["details"] = list(row.get("details") or [])
+    row["available"] = bool(row.get("available"))
+    return row
+
+
+def register(registry) -> None:
+    @registry.method("usage.account")
+    def account_(ctx: CallContext, params: dict) -> dict:
+        provider = str(params.get("provider") or "").strip()
+        if not provider:
+            raise InvalidParams("provider is required")
+        with scoped_home(profile_home_param(params)):
+            return {"snapshot": account(provider, base_url=params.get("base_url"), api_key=params.get("api_key"))}

package/sidecar/talaria_sidecar/methods/worktree.py

@@ -0,0 +1,71 @@
+"""``worktree.*``: Hermes Agent git worktree creation (``hermes_cli.worktree_ops._setup_worktree``)."""
+
+from __future__ import annotations
+
+import io
+import logging
+import subprocess
+from contextlib import redirect_stderr, redirect_stdout
+from pathlib import Path
+
+from ..errors import InvalidParams, RpcError
+from ..home import profile_home_param, scoped_home
+from ..rpc import CallContext
+
+log = logging.getLogger("talaria_sidecar.worktree")
+
+
+def _setup_worktree_fn():
+    try:
+        from hermes_cli.worktree_ops import _setup_worktree
+
+        return _setup_worktree
+    except Exception:  # noqa: BLE001 - older Agents keep the helper in cli.py
+        pass
+    try:
+        import importlib.util
+
+        import hermes_cli
+
+        spec = importlib.util.spec_from_file_location("hermes_cli_worktree", str(Path(hermes_cli.__file__).resolve().parent.parent / "cli.py"))
+        if spec is None or spec.loader is None:
+            raise RuntimeError("cli.py not found")
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+        return module._setup_worktree
+    except Exception as exc:  # noqa: BLE001
+        raise RpcError("Hermes Agent worktree helper is unavailable", condition="worktree_unavailable") from exc
+
+
+def create(repo_root: str) -> dict:
+    root = Path(repo_root).expanduser()
+    if not root.is_dir():
+        raise RpcError("Workspace path does not exist or is not a directory", condition="not_a_repo")
+    probe = subprocess.run(["git", "rev-parse", "--show-toplevel"], cwd=str(root), text=True, capture_output=True, timeout=5, check=False)
+    if probe.returncode != 0 or not probe.stdout.strip():
+        raise RpcError("Workspace is not inside a git repository", condition="not_a_repo")
+    setup = _setup_worktree_fn()
+    output = io.StringIO()
+    with redirect_stdout(output), redirect_stderr(output):
+        info = setup(str(Path(probe.stdout.strip()).resolve()))
+    emitted = output.getvalue().strip()
+    if emitted:
+        log.debug("Hermes Agent worktree helper output: %s", emitted)
+    if not info or not info.get("path") or not info.get("branch"):
+        raise RpcError("Hermes Agent failed to create a git worktree", condition="worktree_failed")
+    return {
+        "path": str(Path(info["path"]).expanduser().resolve()),
+        "branch": str(info["branch"]),
+        "repo_root": str(Path(info.get("repo_root") or probe.stdout.strip()).expanduser().resolve()),
+        "base": str(info["base"]) if info.get("base") else None,
+    }
+
+
+def register(registry) -> None:
+    @registry.method("worktree.create")
+    def create_(ctx: CallContext, params: dict) -> dict:
+        repo_root = params.get("repo_root")
+        if not isinstance(repo_root, str) or not repo_root.strip():
+            raise InvalidParams("repo_root is required")
+        with scoped_home(profile_home_param(params)):
+            return create(repo_root)

package/sidecar/talaria_sidecar/rpc.py

@@ -0,0 +1,218 @@
+"""Newline-delimited JSON-RPC 2.0 over stdio with streamed frames and cancellation.
+
+One line per message. Requests dispatch on a worker thread each, at most
+``max_calls`` at a time; beyond that a request is answered immediately with a
+``sidecar_busy`` error instead of growing the thread count. A method may emit
+``stream`` frames tagged with its request id before it returns its result.
+``rpc.cancel`` sets the request's cancel event; the method decides how to stop
+and still returns (a result with ``status: "cancelled"`` or a CANCELLED error).
+Cancellation never takes a slot, so it always reaches the call it targets.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import sys
+import threading
+import traceback
+from typing import Any, Callable
+
+from .errors import (
+    APPLICATION_ERROR,
+    INTERNAL_ERROR,
+    INVALID_PARAMS,
+    INVALID_REQUEST,
+    METHOD_NOT_FOUND,
+    PARSE_ERROR,
+    Cancelled,
+    RpcError,
+)
+
+log = logging.getLogger("talaria_sidecar.rpc")
+
+Handler = Callable[["CallContext", dict], Any]
+
+DEFAULT_MAX_CALLS = 64
+
+
+class CallContext:
+    """Per-request handle: stream emission and cooperative cancellation."""
+
+    def __init__(self, server: "RpcServer", request_id: Any, method: str):
+        self.server = server
+        self.id = request_id
+        self.method = method
+        self.cancel_event = threading.Event()
+        self._seq = 0
+        self._seq_lock = threading.Lock()
+
+    @property
+    def cancelled(self) -> bool:
+        return self.cancel_event.is_set()
+
+    def check_cancelled(self) -> None:
+        if self.cancel_event.is_set():
+            raise Cancelled()
+
+    def emit(self, event: str, data: Any = None) -> None:
+        """Send one stream frame for this request."""
+        with self._seq_lock:
+            self._seq += 1
+            seq = self._seq
+        self.server.notify("stream", {"id": self.id, "seq": seq, "event": event, "data": data if data is not None else {}})
+
+
+class RpcServer:
+    def __init__(self, methods: dict[str, Handler], *, stdin=None, stdout=None, max_calls: int = DEFAULT_MAX_CALLS):
+        self.methods = dict(methods)
+        self._slots = threading.BoundedSemaphore(max(1, int(max_calls)))
+        self.methods.setdefault("rpc.cancel", self._cancel)
+        self.methods.setdefault("rpc.methods", lambda ctx, params: {"methods": sorted(self.methods)})
+        self._in = stdin or sys.stdin.buffer
+        self._out = stdout or sys.stdout.buffer
+        self._write_lock = threading.Lock()
+        self._active: dict[Any, CallContext] = {}
+        self._active_lock = threading.Lock()
+        self._closed = threading.Event()
+        self.exit_code = 0
+
+    # ── output ────────────────────────────────────────────────────────────
+    def _write(self, message: dict) -> None:
+        try:
+            # Strict JSON: a NaN/Infinity anywhere would be an unparsable line the client silently drops (a hung call).
+            line = json.dumps(message, separators=(",", ":"), ensure_ascii=False, allow_nan=False) + "\n"
+        except ValueError as exc:
+            if "id" in message and "result" in message:
+                self._error(message["id"], INTERNAL_ERROR, f"result is not JSON-serialisable: {exc}")
+                return
+            log.error("dropping unserialisable %s message: %s", message.get("method"), exc)
+            return
+        data = line.encode("utf-8")
+        with self._write_lock:
+            try:
+                self._out.write(data)
+                self._out.flush()
+            except (BrokenPipeError, OSError, ValueError):
+                self._closed.set()
+
+    def notify(self, method: str, params: dict) -> None:
+        self._write({"jsonrpc": "2.0", "method": method, "params": params})
+
+    def _result(self, request_id: Any, result: Any) -> None:
+        self._write({"jsonrpc": "2.0", "id": request_id, "result": result})
+
+    def _error(self, request_id: Any, code: int, message: str, data: dict | None = None) -> None:
+        error: dict[str, Any] = {"code": code, "message": message}
+        if data:
+            error["data"] = data
+        self._write({"jsonrpc": "2.0", "id": request_id, "error": error})
+
+    # ── built-ins ─────────────────────────────────────────────────────────
+    def _cancel(self, ctx: CallContext, params: dict) -> dict:
+        target = params.get("id") if isinstance(params, dict) else None
+        with self._active_lock:
+            active = self._active.get(target)
+        if active is None:
+            return {"cancelled": False, "reason": "not_active"}
+        active.cancel_event.set()
+        return {"cancelled": True}
+
+    def request_shutdown(self, exit_code: int = 0) -> None:
+        self.exit_code = exit_code
+        self._closed.set()
+
+    # ── dispatch ──────────────────────────────────────────────────────────
+    def _register(self, request: dict) -> CallContext | None:
+        """Make the call cancellable before the reader accepts the next message (an immediate ``rpc.cancel`` must find it)."""
+        request_id = request.get("id")
+        method = request.get("method")
+        if request_id is None or not isinstance(method, str):
+            return None
+        ctx = CallContext(self, request_id, method)
+        with self._active_lock:
+            self._active[request_id] = ctx
+        return ctx
+
+    def _dispatch(self, request: dict, ctx: CallContext | None = None) -> None:
+        request_id = request.get("id")
+        method = request.get("method")
+        params = request.get("params")
+        if params is None:
+            params = {}
+        if not isinstance(method, str) or not isinstance(params, dict):
+            if request_id is not None:
+                with self._active_lock:
+                    self._active.pop(request_id, None)
+                self._error(request_id, INVALID_REQUEST, "method must be a string and params an object")
+            return
+        handler = self.methods.get(method)
+        if handler is None:
+            if request_id is not None:
+                with self._active_lock:
+                    self._active.pop(request_id, None)
+                self._error(request_id, METHOD_NOT_FOUND, f"unknown method {method}")
+            return
+        if ctx is None:
+            ctx = CallContext(self, request_id, method)
+            if request_id is not None:
+                with self._active_lock:
+                    self._active[request_id] = ctx
+        try:
+            result = handler(ctx, params)
+            if request_id is not None:
+                self._result(request_id, result if result is not None else {})
+        except RpcError as exc:
+            if request_id is not None:
+                error = exc.to_json()
+                self._error(request_id, error["code"], error["message"], error.get("data"))
+        except TypeError as exc:
+            # Wrong keyword arguments reaching a wrapped Agent function.
+            log.debug("invalid params for %s", method, exc_info=True)
+            if request_id is not None:
+                self._error(request_id, INVALID_PARAMS, str(exc))
+        except Exception as exc:  # noqa: BLE001 - every unexpected failure becomes a typed error
+            log.error("method %s failed: %s\n%s", method, exc, traceback.format_exc())
+            if request_id is not None:
+                self._error(request_id, INTERNAL_ERROR, f"{type(exc).__name__}: {exc}")
+        finally:
+            if request_id is not None:
+                with self._active_lock:
+                    self._active.pop(request_id, None)
+
+    def serve_forever(self) -> int:
+        """Read requests until stdin closes or shutdown is requested."""
+        while not self._closed.is_set():
+            try:
+                raw = self._in.readline()
+            except (OSError, ValueError):
+                break
+            if not raw:
+                break
+            raw = raw.strip()
+            if not raw:
+                continue
+            try:
+                request = json.loads(raw)
+            except ValueError:
+                self._error(None, PARSE_ERROR, "invalid JSON")
+                continue
+            if not isinstance(request, dict) or request.get("jsonrpc") != "2.0":
+                self._error(request.get("id") if isinstance(request, dict) else None, INVALID_REQUEST, "expected a JSON-RPC 2.0 request object")
+                continue
+            if request.get("method") == "rpc.cancel":
+                # Cancellation must not queue behind the call it targets.
+                self._dispatch(request)
+                continue
+            if not self._slots.acquire(blocking=False):
+                self._error(request.get("id"), APPLICATION_ERROR, "sidecar is at its concurrent call limit", {"condition": "sidecar_busy"})
+                continue
+            ctx = self._register(request)
+            threading.Thread(target=self._dispatch_slot, args=(request, ctx), name=f"rpc-{request.get('method')}", daemon=True).start()
+        return self.exit_code
+
+    def _dispatch_slot(self, request: dict, ctx: CallContext | None) -> None:
+        try:
+            self._dispatch(request, ctx)
+        finally:
+            self._slots.release()

package/sidecar/talaria_sidecar/runtime.py

@@ -0,0 +1,330 @@
+"""Agent import, pin verification, and the runtime drift guard.
+
+Ported from api/agent_runtime.py. The sidecar owns the Agent pin
+(``sidecar/agent_dependency.json``): it compares the loaded checkout revision
+with the pin at handshake and refuses further chat calls once the checkout
+changes underneath the running interpreter.
+"""
+
+from __future__ import annotations
+
+import errno
+import importlib
+import json
+import math
+import os
+import stat
+import subprocess
+import sys
+import threading
+import time
+from pathlib import Path
+
+from . import SIDECAR_RPC_VERSION
+from .errors import RpcError
+
+PIN_PATH = Path(__file__).resolve().parent.parent / "agent_dependency.json"
+_RESTART_REQUIRED_MESSAGE = (
+    "Hermes Agent was updated while Talaria Web was running. "
+    "Talaria Web cannot verify that the Agent update completed safely. "
+    "Check the Agent update outcome and environment first. "
+    "Restart Talaria Web manually before retrying this action."
+)
+_AGENT_UPDATE_MARKER = ".hermes-update-in-progress"
+_AGENT_RECOVERY_MARKERS = (".update-incomplete", ".lazy-refresh-incomplete")
+_AGENT_UPDATE_MAX_AGE_SECONDS = 20 * 60
+_AGENT_UPDATE_MARKER_MAX_BYTES = 64 * 1024
+_O_NOFOLLOW = getattr(os, "O_NOFOLLOW", 0)
+_O_NONBLOCK = getattr(os, "O_NONBLOCK", 0)
+_MARKER_SAFE_OPEN_AVAILABLE = bool(_O_NOFOLLOW) and bool(_O_NONBLOCK)
+
+
+class AgentRuntimeStale(RpcError):
+    def __init__(self, update_state: str | None):
+        data = {"retryable": True, "restart_scheduled": False}
+        if update_state is not None:
+            data["agent_update_state"] = update_state
+        super().__init__(_RESTART_REQUIRED_MESSAGE, condition="agent_runtime_stale", data=data)
+
+
+class AgentIncompatible(RpcError):
+    def __init__(self, message: str, **data):
+        super().__init__(message, condition="agent_incompatible", data=data)
+
+
+def read_pin(path: Path = PIN_PATH) -> dict:
+    pin = json.loads(path.read_text(encoding="utf-8"))
+    talaria = pin["x-talaria"]
+    return {"version": talaria["version"], "source_revision": talaria["sourceRevision"], "image": pin["services"]["hermes-agent"]["image"]}
+
+
+def _git(agent_dir: Path, *args: str) -> str | None:
+    try:
+        result = subprocess.run(["git", "-C", str(agent_dir), *args], check=False, capture_output=True, text=True, timeout=2)
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    if result.returncode != 0:
+        return None
+    return result.stdout.strip() or None
+
+
+def read_agent_revision(agent_dir: Path | None, module_path: Path | None) -> str | None:
+    """Return the checkout HEAD that supplied ``run_agent``, or None if untracked."""
+    if agent_dir is None or module_path is None:
+        return None
+    worktree = _git(agent_dir, "rev-parse", "--show-toplevel")
+    if not worktree:
+        return None
+    try:
+        relative = module_path.relative_to(Path(worktree).resolve()).as_posix()
+    except ValueError:
+        return None
+    if _git(Path(worktree), "--literal-pathspecs", "ls-files", "--error-unmatch", "--", relative) is None:
+        return None
+    return _git(Path(worktree), "rev-parse", "--verify", "HEAD")
+
+
+def _head_stamp(agent_dir: Path | None) -> tuple | None:
+    """Identity of the checkout's HEAD without spawning git: stats of ``.git/HEAD`` and of the ref it names."""
+    if agent_dir is None:
+        return None
+    git_dir = agent_dir / ".git"
+    try:
+        if git_dir.is_file():  # worktree: ``gitdir: <path>``
+            target = git_dir.read_text(encoding="utf-8").strip()
+            git_dir = Path(target[len("gitdir:"):].strip()) if target.startswith("gitdir:") else git_dir
+        head = git_dir / "HEAD"
+        st = head.stat()
+        parts: list = [st.st_mtime_ns, st.st_size, st.st_ino]
+        content = head.read_text(encoding="utf-8").strip()
+        if content.startswith("ref:"):
+            ref = git_dir / content[len("ref:"):].strip()
+            try:
+                rst = ref.stat()
+                parts.extend([rst.st_mtime_ns, rst.st_size, rst.st_ino])
+            except OSError:
+                parts.append("packed")
+                try:
+                    pst = (git_dir / "packed-refs").stat()
+                    parts.extend([pst.st_mtime_ns, pst.st_size])
+                except OSError:
+                    parts.append(None)
+        return tuple(parts)
+    except OSError:
+        return None
+
+
+def _pid_is_alive(pid: int) -> bool | None:
+    if pid <= 0:
+        return False
+    if pid.bit_length() > 32:
+        return None
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    except (OverflowError, ValueError):
+        return None
+    except OSError as exc:
+        if exc.errno == errno.ESRCH:
+            return False
+        if exc.errno == errno.EPERM:
+            return True
+        return None
+    return True
+
+
+def _read_live_agent_update(marker: Path) -> str:
+    """Classify the Agent update marker: absent, active, stale, or unknown."""
+    if not _MARKER_SAFE_OPEN_AVAILABLE:
+        try:
+            marker.lstat()
+        except FileNotFoundError:
+            return "absent"
+        except (OSError, ValueError, TypeError):
+            return "unknown"
+        return "unknown"
+    try:
+        fd = os.open(marker, os.O_RDONLY | _O_NONBLOCK | _O_NOFOLLOW)
+    except FileNotFoundError:
+        try:
+            marker.lstat()
+        except FileNotFoundError:
+            return "absent"
+        except OSError:
+            return "unknown"
+        return "unknown"
+    except (OSError, ValueError, TypeError):
+        return "unknown"
+    try:
+        try:
+            st = os.fstat(fd)
+        except OSError:
+            return "unknown"
+        if not stat.S_ISREG(st.st_mode) or st.st_size > _AGENT_UPDATE_MARKER_MAX_BYTES:
+            return "unknown"
+        try:
+            data = os.read(fd, _AGENT_UPDATE_MARKER_MAX_BYTES + 1)
+        except (OSError, BlockingIOError):
+            return "unknown"
+    finally:
+        try:
+            os.close(fd)
+        except OSError:
+            pass
+    if len(data) > _AGENT_UPDATE_MARKER_MAX_BYTES:
+        return "unknown"
+    try:
+        lines = data.decode("utf-8").splitlines()
+        pid = int(lines[0].strip())
+        started_at = float(lines[1].strip())
+    except (IndexError, TypeError, ValueError, UnicodeError):
+        return "unknown"
+    if pid <= 0 or not math.isfinite(started_at):
+        return "unknown"
+    age = time.time() - started_at
+    if age < 0:
+        return "unknown"
+    if age > _AGENT_UPDATE_MAX_AGE_SECONDS:
+        return "stale"
+    alive = _pid_is_alive(pid)
+    if alive is None:
+        return "unknown"
+    return "active" if alive else "stale"
+
+
+def _marker_presence(marker: Path) -> str:
+    try:
+        marker.lstat()
+    except FileNotFoundError:
+        return "absent"
+    except OSError:
+        return "unknown"
+    return "present"
+
+
+class AgentRuntime:
+    """Loads the Agent once and guards against a changed checkout."""
+
+    def __init__(self, hermes_home: Path, agent_dir: Path | None = None):
+        self.hermes_home = Path(hermes_home)
+        self._stale_lock = threading.Lock()
+        self._stale = False
+        self._stale_stamp: tuple | None = None
+        self.agent_dir = Path(agent_dir).resolve() if agent_dir else None
+        self.pin = read_pin()
+        self.loaded = False
+        self.module_path: Path | None = None
+        self.revision: str | None = None
+        self.import_error: str | None = None
+        self._lock = threading.Lock()
+
+    # ── loading ───────────────────────────────────────────────────────────
+    def load(self) -> None:
+        with self._lock:
+            if self.loaded:
+                return
+            try:
+                module = importlib.import_module("run_agent")
+                getattr(module, "AIAgent")
+            except Exception as exc:  # noqa: BLE001 - reported as a handshake condition
+                self.import_error = f"{type(exc).__name__}: {exc}"
+                raise AgentIncompatible(f"Hermes Agent could not be imported: {self.import_error}", import_error=self.import_error)
+            module_file = getattr(module, "__file__", None)
+            self.module_path = Path(module_file).resolve() if module_file else None
+            if self.agent_dir is None and self.module_path is not None:
+                self.agent_dir = self.module_path.parent
+            self.revision = read_agent_revision(self.agent_dir, self.module_path)
+            self.loaded = True
+
+    @property
+    def agent_version(self) -> str | None:
+        try:
+            return getattr(importlib.import_module("hermes_cli"), "__version__", None)
+        except Exception:  # noqa: BLE001
+            return None
+
+    # ── guards ────────────────────────────────────────────────────────────
+    def _install_roots(self) -> tuple[Path, ...]:
+        roots: list[Path] = []
+        if self.agent_dir is not None:
+            roots.append(self.agent_dir)
+        python = Path(sys.executable)
+        if python.parent.name.lower() in {"bin", "scripts"} and python.parent.parent.name.lower() in {"venv", ".venv"}:
+            candidate = python.parent.parent.parent
+            if all(os.path.normcase(str(candidate)) != os.path.normcase(str(root)) for root in roots):
+                roots.append(candidate)
+        return tuple(roots)
+
+    def update_transaction_state(self) -> str:
+        live = _read_live_agent_update(self.hermes_home / _AGENT_UPDATE_MARKER)
+        if live == "unknown":
+            return "unknown"
+        recovery = False
+        for root in self._install_roots():
+            for name in _AGENT_RECOVERY_MARKERS:
+                presence = _marker_presence(root / name)
+                if presence == "unknown":
+                    return "unknown"
+                recovery = recovery or presence == "present"
+        if recovery:
+            return "incomplete"
+        return "unverified" if live == "absent" else live
+
+    def is_stale(self) -> bool:
+        """True when the checkout revision no longer matches the loaded module.
+
+        The revision read spawns git, so it is memoised on the checkout's HEAD stamp (``.git/HEAD`` plus the ref it
+        points at, both plain stat calls) across the worker pool, and a read that fails (timeout under load) is retried
+        once before it counts as a change.
+        """
+        if not self.loaded or self.revision is None:
+            return False
+        with self._stale_lock:
+            stamp = _head_stamp(self.agent_dir)
+            if stamp is not None and stamp == self._stale_stamp:
+                return self._stale
+            fresh = None
+            for _ in range(2):
+                try:
+                    fresh = read_agent_revision(self.agent_dir, self.module_path)
+                except Exception:  # noqa: BLE001 - unreadable fails closed like a change
+                    fresh = None
+                if fresh is not None:
+                    break
+            self._stale = fresh != self.revision
+            self._stale_stamp = stamp if fresh is not None else None
+            return self._stale
+
+    def ensure_current(self) -> None:
+        """Raise ``agent_runtime_stale`` when the checkout changed since import."""
+        if self.is_stale():
+            raise AgentRuntimeStale(self.update_transaction_state())
+
+    # ── handshake ─────────────────────────────────────────────────────────
+    def describe(self) -> dict:
+        # A checkout answers by revision; an untracked install (pip, image, no .git) must match the pinned version
+        # instead of passing unchecked, and an unknown version fails closed.
+        if not self.loaded:
+            compatible = False
+        elif self.revision is not None:
+            compatible = self.revision == self.pin["source_revision"]
+        else:
+            compatible = self.agent_version is not None and self.agent_version == self.pin["version"]
+        return {
+            "rpc_version": SIDECAR_RPC_VERSION,
+            "python": sys.executable,
+            "python_version": ".".join(str(part) for part in sys.version_info[:3]),
+            "agent_dir": str(self.agent_dir) if self.agent_dir else None,
+            "agent_revision": self.revision,
+            "agent_version": self.agent_version if self.loaded else None,
+            "pinned_revision": self.pin["source_revision"],
+            "pinned_version": self.pin["version"],
+            "pinned_image": self.pin["image"],
+            "compatible": compatible,
+            "stale": self.is_stale(),
+            "update_state": self.update_transaction_state(),
+            "import_error": self.import_error,
+        }