agentmetry 0.9.9__tar.gz → 0.10.1__tar.gz

{agentmetry-0.9.9 → agentmetry-0.10.1}/.gitignore

@@ -16,6 +16,8 @@ build/
 # Next.js
 apps/dashboard/.next/
 apps/dashboard/out/
+# The same export copied into the package by the release build, for the wheel.
+apps/orchestrator/agentmetry/dashboard_static/
 
 # Environment
 .env

{agentmetry-0.9.9 → agentmetry-0.10.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentmetry
-Version: 0.9.9
+Version: 0.10.1
 Summary: Local-first endpoint sensor for AI coding agents: hash-chained audit trail, MITRE-mapped sequence detection, DLP
 Project-URL: Homepage, https://agentmetry.ai
 Project-URL: Source, https://github.com/blitzcrieg1/agentmetry
@@ -44,19 +44,38 @@ Description-Content-Type: text/markdown
 
 A local-first endpoint sensor for AI coding agents.
 
-Agentmetry hooks the tool lifecycle of Claude Code, Cursor, Codex and Antigravity,
-writes every tool call, approval and denial to a hash-chained JSONL trail on your
-machine, and runs sequence detection over the session. A credential read followed
-by network egress becomes one finding rather than two unremarkable log lines.
+Agentmetry hooks the tool lifecycle of Claude Code, Cursor, Codex, GitHub Copilot,
+Antigravity, Qwen, Kimi, Qoder and CodeBuddy, writes every tool call, approval and
+denial to a hash-chained JSONL trail on your machine, and runs sequence detection
+over the session. A credential read followed by network egress becomes one finding
+rather than two unremarkable log lines. Findings carry MITRE ATT&CK labels, and
+MITRE ATLAS labels where ATLAS says something ATT&CK cannot.
 
-Everything runs locally. There are no cloud calls and no telemetry. Forwarding to
-Elastic ECS, Splunk HEC or a webhook exists and is off unless you configure it.
+Nothing leaves the machine unless you configure it, and there is no telemetry.
+Forwarding to Splunk HEC, Elastic ECS, Google SecOps, Microsoft Sentinel or a
+webhook (canonical JSON or CloudEvents) is off by default.
+
+## Try it with nothing installed
+
+```bash
+uvx agentmetry demo
+```
+
+It replays a session into a temporary directory it deletes: a private-key read,
+then an upload. That raises one critical finding. It then edits the trail and
+shows `agentmetry verify` fail.
+
+## Record a real agent
 
 ```bash
 pip install agentmetry
+agentmetry hooks install
+agentmetry start
 agentmetry doctor
 ```
 
+`agentmetry dashboard` opens the local console with a one-time sign-in link.
+
 ## Check the detection claims yourself
 
 The corpus ships inside the package, so this works from a clean install:
@@ -72,12 +91,19 @@ matters: any tool can fire on an attack, and a feed that cries wolf gets muted.
 ## What it does not do
 
 - **It is not a CASB.** It records the agents you wire in. An unmanaged browser
-  assistant is invisible to it.
-- **It is a recorder, not a sandbox.** The only enforcement path is pre-execution
-  DLP blocking in the hook.
+  assistant, or an IDE with its hooks off, is invisible to it.
+- **It is a recorder, not a sandbox.** By default it records. DLP and tool policy
+  can deny a call in the hook, before it runs, when you set them to block.
 - **The DLP is regex, not ML.** A starting pack you extend in YAML.
+- **macOS is in preview.** CI runs the full suite on Windows, Linux and macOS, but
+  only Windows and Linux are required checks, and no hook has been exercised
+  against a live agent on a Mac.
 - **It is a public alpha.** Integration surfaces may still change.
 
+For a fleet, a managed policy file can lock settings such as the DLP and tool
+policy modes so a developer cannot change them. See
+[docs/managed-policy.md](https://github.com/blitzcrieg1/agentmetry/blob/master/docs/managed-policy.md).
+
 Full documentation, the event schema, and the SIEM integration guides are in the
 repository.
 

agentmetry-0.10.1/README.md

@@ -0,0 +1,71 @@
+# Agentmetry
+
+A local-first endpoint sensor for AI coding agents.
+
+Agentmetry hooks the tool lifecycle of Claude Code, Cursor, Codex, GitHub Copilot,
+Antigravity, Qwen, Kimi, Qoder and CodeBuddy, writes every tool call, approval and
+denial to a hash-chained JSONL trail on your machine, and runs sequence detection
+over the session. A credential read followed by network egress becomes one finding
+rather than two unremarkable log lines. Findings carry MITRE ATT&CK labels, and
+MITRE ATLAS labels where ATLAS says something ATT&CK cannot.
+
+Nothing leaves the machine unless you configure it, and there is no telemetry.
+Forwarding to Splunk HEC, Elastic ECS, Google SecOps, Microsoft Sentinel or a
+webhook (canonical JSON or CloudEvents) is off by default.
+
+## Try it with nothing installed
+
+```bash
+uvx agentmetry demo
+```
+
+It replays a session into a temporary directory it deletes: a private-key read,
+then an upload. That raises one critical finding. It then edits the trail and
+shows `agentmetry verify` fail.
+
+## Record a real agent
+
+```bash
+pip install agentmetry
+agentmetry hooks install
+agentmetry start
+agentmetry doctor
+```
+
+`agentmetry dashboard` opens the local console with a one-time sign-in link.
+
+## Check the detection claims yourself
+
+The corpus ships inside the package, so this works from a clean install:
+
+```bash
+agentmetry benchmark
+```
+
+It replays recorded sessions through the real rule engine and exits non-zero on
+any missed rule or any false positive. The benign half is the number that
+matters: any tool can fire on an attack, and a feed that cries wolf gets muted.
+
+## What it does not do
+
+- **It is not a CASB.** It records the agents you wire in. An unmanaged browser
+  assistant, or an IDE with its hooks off, is invisible to it.
+- **It is a recorder, not a sandbox.** By default it records. DLP and tool policy
+  can deny a call in the hook, before it runs, when you set them to block.
+- **The DLP is regex, not ML.** A starting pack you extend in YAML.
+- **macOS is in preview.** CI runs the full suite on Windows, Linux and macOS, but
+  only Windows and Linux are required checks, and no hook has been exercised
+  against a live agent on a Mac.
+- **It is a public alpha.** Integration surfaces may still change.
+
+For a fleet, a managed policy file can lock settings such as the DLP and tool
+policy modes so a developer cannot change them. See
+[docs/managed-policy.md](https://github.com/blitzcrieg1/agentmetry/blob/master/docs/managed-policy.md).
+
+Full documentation, the event schema, and the SIEM integration guides are in the
+repository.
+
+- Source and issues: https://github.com/blitzcrieg1/agentmetry
+- Website: https://agentmetry.ai
+
+Apache-2.0.

{agentmetry-0.9.9 → agentmetry-0.10.1}/agentmetry/api/main.py

@@ -79,6 +79,22 @@ def _start_forwarders() -> list[asyncio.Task]:
     return tasks
 
 
+def antigravity_watcher_wanted() -> bool:
+    """Whether this recorder should tail the developer's Antigravity transcripts.
+
+    It used to start whenever the script existed, so every recorder did it,
+    including the dashboard demo, whose trail is supposed to hold seeded events
+    only. The watcher reads `~/.gemini/antigravity/brain`, the real one, so a
+    demo shown to someone could carry the presenter's actual agent activity, and
+    a second recorder doubled every Antigravity call. It now runs only where the
+    recorder accepts ingest, and `AGENTMETRY_ANTIGRAVITY_WATCHER=0` turns it off.
+    """
+    if not settings.audit_ingest_enabled:
+        return False
+    flag = os.environ.get("AGENTMETRY_ANTIGRAVITY_WATCHER", "").strip().lower()
+    return flag not in ("0", "false", "no", "off")
+
+
 def start_transcript_watcher(watcher_path: Path) -> subprocess.Popen:
     """Start the Antigravity transcript watcher, tied to this process's life.
 
@@ -111,6 +127,20 @@ def stop_transcript_watcher(process: subprocess.Popen) -> None:
 async def lifespan(app: FastAPI):
     from agentmetry.core.audit.migrate import backfill_db_from_jsonl
 
+    # The ingest-only token, which hooks prefer and the ingest route accepts.
+    # Without it a hook running as another account (Codex's Windows sandbox)
+    # could not authenticate and every event it sent was lost (#302). Owner-
+    # only like the full token; `hooks install` widens it to Codex's sandbox
+    # accounts where they exist. A failure here costs that, never the boot.
+    from agentmetry.core import api_token
+    from agentmetry.core.auth import auth_is_disabled
+
+    if not auth_is_disabled():
+        try:
+            api_token.ensure_ingest_token()
+        except OSError:
+            logger.exception("Could not write the ingest-only token; hooks fall back to the full token")
+
     # Backfill SQLite from the existing JSONL trail. A broken or locked audit DB
     # must degrade the dashboard, never stop the daemon from booting: the
     # recorder's job is to keep recording.
@@ -211,7 +241,7 @@ async def lifespan(app: FastAPI):
     watcher_process = None
     try:
         watcher_path = Path(__file__).resolve().parents[4] / "scripts" / "antigravity_transcript_watcher.py"
-        if watcher_path.exists():
+        if watcher_path.exists() and antigravity_watcher_wanted():
             watcher_process = start_transcript_watcher(watcher_path)
             logger.info("Started Antigravity transcript watcher (PID: %s)", watcher_process.pid)
     except Exception as exc:
@@ -285,28 +315,79 @@ async def websocket_endpoint(
         ws_manager.disconnect(websocket, session_id)
 
 
-_DASHBOARD_DIR = Path(__file__).resolve().parents[3] / "dashboard" / "out"
-
-
-def mount_dashboard(target: FastAPI, directory: Path = _DASHBOARD_DIR) -> bool:
-    """Serve the dashboard's static export when it has been built.
-
-    Single-process mode: `npm run build` in apps/dashboard emits `out/`, which
-    the orchestrator serves at the root. Mounted last so it only catches paths
-    not already claimed by the API or WebSocket. Dev uses the :3000 dev server
-    instead, so this is a no-op when the export is absent.
+#: A source checkout's build, which a developer rebuilds and expects to see.
+_CHECKOUT_DASHBOARD_DIR = Path(__file__).resolve().parents[3] / "dashboard" / "out"
+#: The same export, bundled inside the wheel by the release build. Until 0.10.1
+#: nothing put it there, so `pip install agentmetry`, `agentmetry dashboard`
+#: signed the browser in and landed it on a JSON 404.
+_PACKAGED_DASHBOARD_DIR = Path(__file__).resolve().parents[1] / "dashboard_static"
+
+_DASHBOARD_MISSING_PAGE = """<!DOCTYPE html>
+<html lang="en"><head><meta charset="utf-8"><title>Agentmetry</title>
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<style>body{font:16px/1.6 system-ui,sans-serif;max-width:40rem;margin:4rem auto;padding:0 1rem}
+code{background:#f2f2f2;padding:.1em .3em;border-radius:3px}</style></head>
+<body><h1>Agentmetry is recording.</h1>
+<p>The dashboard is not part of this install. Packages from 0.10.1 include it:
+<code>pip install --upgrade agentmetry</code>, then restart the recorder.</p>
+<p>Recording, detection and the trail do not depend on it. From a shell:
+<code>agentmetry stats</code>, <code>agentmetry replay &lt;session&gt;</code>,
+<code>agentmetry verify --trail</code>.</p></body></html>"""
+
+
+def dashboard_dir() -> Path | None:
+    """Where the dashboard export is: a checkout's build first, then the package's."""
+    for candidate in (_CHECKOUT_DASHBOARD_DIR, _PACKAGED_DASHBOARD_DIR):
+        if (candidate / "index.html").is_file():
+            return candidate
+    return None
+
+
+def mount_dashboard(target: FastAPI, directory: Path | None = None) -> bool:
+    """Serve the dashboard's static export when there is one.
+
+    Single-process mode: the orchestrator serves the export at the root,
+    mounted last so it only catches paths not already claimed by the API or
+    WebSocket. Dev uses the :3000 dev server instead. With no export, the root
+    serves a page saying so, because the sign-in link redirects there and a
+    JSON 404 reads as a broken product.
     """
-    if not directory.is_dir():
+    if directory is None:
+        directory = dashboard_dir()
+    if directory is None or not directory.is_dir():
         logger.info(
-            "Dashboard export not found at %s — run 'npm run build' in "
-            "apps/dashboard for single-process serving",
-            directory,
+            "Dashboard export not found (looked in %s and %s); serving a notice at /",
+            _CHECKOUT_DASHBOARD_DIR,
+            _PACKAGED_DASHBOARD_DIR,
         )
+        from fastapi.responses import HTMLResponse
+
+        @target.get("/", include_in_schema=False, name="dashboard-missing")
+        async def dashboard_missing() -> HTMLResponse:
+            return HTMLResponse(_DASHBOARD_MISSING_PAGE, headers={"Cache-Control": "no-cache"})
+
         return False
 
     from fastapi.staticfiles import StaticFiles
 
-    target.mount("/", StaticFiles(directory=str(directory), html=True), name="dashboard")
+    class DashboardFiles(StaticFiles):
+        """The export, with its HTML pages marked `no-cache`.
+
+        Served with no cache header at all, a browser may reuse a stale page on
+        an ordinary reload, and the page names the old scripts, so an upgraded
+        recorder kept showing the previous dashboard until a hard reload.
+        `no-cache` still lets the browser keep a copy; it only has to ask
+        whether the page changed. The scripts are not touched: their names
+        change with every build.
+        """
+
+        async def get_response(self, path: str, scope):  # type: ignore[override]
+            response = await super().get_response(path, scope)
+            if response.headers.get("content-type", "").startswith("text/html"):
+                response.headers["Cache-Control"] = "no-cache"
+            return response
+
+    target.mount("/", DashboardFiles(directory=str(directory), html=True), name="dashboard")
     logger.info("Serving dashboard from %s", directory)
     return True
 

{agentmetry-0.9.9 → agentmetry-0.10.1}/agentmetry/api/routes/audit.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import asyncio
+import logging
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import Any, Literal
@@ -11,12 +12,13 @@ from fastapi import APIRouter, Depends, HTTPException, Query, Request
 from fastapi.responses import FileResponse
 from pydantic import BaseModel, Field, field_validator
 
-from agentmetry.core.auth import require_api_key
+from agentmetry.core.auth import require_api_key, require_ingest_key
 from agentmetry.core.audit.detection.disposition import STATUSES, get_disposition_store
 from agentmetry.core.audit.ingest import ingest_external_event
 from agentmetry.core.config import settings
 
 router = APIRouter(prefix="/audit", tags=["audit"])
+logger = logging.getLogger(__name__)
 
 _RUN_ACTION_TYPES = frozenset({
     "session_start",
@@ -142,6 +144,8 @@ class ExternalIngestBody(BaseModel):
     # drops what it does not know, silently, which has already cost this file
     # two shipped bugs.
     schema_concealed: dict[str, int] = Field(default_factory=dict)
+    # Model-steering text in a tool description (#188), counts per category.
+    schema_injection: dict[str, int] = Field(default_factory=dict)
     server_version: str = ""
     list_changed: bool | None = None
 
@@ -191,7 +195,24 @@ def _event_source_app(event: dict[str, Any]) -> str:
     return "agentmetry"
 
 
-@router.post("/ingest", dependencies=[Depends(require_api_key)])
+_THROTTLE_WARNED: dict[str, float] = {}
+
+
+def _warn_throttled(source_app: str) -> None:
+    """Log throttling once a minute per source, so a flood does not flood the log too."""
+    import time
+
+    now = time.monotonic()
+    if now - _THROTTLE_WARNED.get(source_app, -60.0) >= 60.0:
+        _THROTTLE_WARNED[source_app] = now
+        # The caller passes a resolved, allowlisted name, so this changes
+        # nothing today. It keeps a future caller that passes client text from
+        # forging log lines, and it is the guard code scanning can see.
+        safe = (source_app or "unknown").replace("\r", "").replace("\n", "")
+        logger.warning("Ingest rate limit reached for source %s; events are spooled for replay", safe)
+
+
+@router.post("/ingest", dependencies=[Depends(require_ingest_key)])
 async def audit_ingest(body: ExternalIngestBody):
     """Accept canonical adapter events from Cursor, Claude, MCP proxy, etc."""
     if not settings.audit_ingest_enabled:
@@ -199,6 +220,26 @@ async def audit_ingest(body: ExternalIngestBody):
     if not settings.audit_export_enabled:
         raise HTTPException(status_code=503, detail="Audit export is disabled")
 
+    # Rate limit per source app and per session (#312). The hook spools a 429
+    # and the recorder's drain replays it with the original timestamps, so a
+    # burst past the cap is late, not lost.
+    from agentmetry.core.audit.external import _resolve_source_app
+    from agentmetry.core.audit.ingest_quota import get_limiter
+
+    # Keyed and logged by the name the trail will record, not the one the
+    # client sent: an unlisted name becomes `unknown`. Keyed on raw text, a
+    # flood inventing a name per event got a fresh bucket each time, and the
+    # warning wrote client text into the log.
+    source = _resolve_source_app(body.source_app)[0]
+    limiter = get_limiter()
+    if not limiter.allow(source, body.session_id or body.correlation_id):
+        _warn_throttled(source)
+        raise HTTPException(
+            status_code=429,
+            detail="Ingest rate limit reached; the hook spools this event and the recorder replays it",
+            headers={"Retry-After": str(limiter.retry_after())},
+        )
+
     payload = body.model_dump(exclude_none=True)
     try:
         canonical = await ingest_external_event(payload)
@@ -495,11 +536,19 @@ async def audit_status():
     Powers the freshness badge and `selftest` — makes silent hook failure visible
     instead of the operator falsely believing they are being audited.
     """
+    from agentmetry.core.audit.ingest_quota import get_limiter
     from agentmetry.core.audit.spool import spool_depth, spool_oldest_age_seconds
     from agentmetry.core.audit.trail_db import get_trail_db
     path = Path(settings.audit_export_path)
     if not settings.audit_export_enabled:
-        return {"enabled": False, "last_event_utc": None, "recent": 0, "by_source": {}, "path": str(path)}
+        return {
+            "enabled": False,
+            "last_event_utc": None,
+            "recent": 0,
+            "by_source": {},
+            "path": str(path),
+            "demo": settings.demo_mode,
+        }
 
     status_data = get_trail_db().status()
     # Pending spool depth belongs in the same payload as freshness. A feed that
@@ -516,6 +565,12 @@ async def audit_status():
         # Per SIEM: the last seq it accepted, and how long it has been failing.
         "forwarding": _forward_status(),
         "spool_oldest_age_seconds": spool_oldest_age_seconds(),
+        # Events refused by the ingest rate limit since the recorder started.
+        # They went to the hook spool, so a non-zero count is late work, and a
+        # growing one is an agent sending far faster than agents do (#312).
+        "ingest_throttled": get_limiter().snapshot(),
+        # A demo server's events are synthetic. The dashboard says so from here.
+        "demo": settings.demo_mode,
     }
 
 

{agentmetry-0.9.9 → agentmetry-0.10.1}/agentmetry/cli/__init__.py

@@ -312,16 +312,41 @@ def cmd_status(args: argparse.Namespace) -> int:
     return 0
 
 
-def cmd_stats(args: argparse.Namespace) -> int:
-    """Audit trail metrics over a window — dogfood weekly counts."""
+def _api_get_json(port: int, path: str, what: str, params: dict | None = None) -> dict | None:
+    """GET an API route with this install's token, or print why not and return None.
+
+    Every route but health has needed the per-install token since 0.9.3, and
+    `stats` and `detections` were still calling without it. The 401 body was
+    read as if it were the answer, so both printed an empty result over a trail
+    with events and a critical detection in it. A refusal is now an error.
+    """
     try:
-        data = httpx.get(
-            f"{_base_url(args.port)}/api/v1/audit/stats",
-            params={"days": args.days},
+        resp = httpx.get(
+            f"{_api_base_url(port)}{path}",
+            params=params,
+            headers=_api_headers(),
             timeout=10.0,
-        ).json()
+        )
     except Exception:
-        print("Not running - start Agentmetry first (stats reads via the API).")
+        print(f"Not running - start Agentmetry first ({what} reads via the API).")
+        return None
+    if resp.status_code in (401, 403):
+        print(
+            f"The recorder refused the request (HTTP {resp.status_code}): this shell has no "
+            "valid API token for it. Run it as the account that started the recorder, or "
+            "set AGENTMETRY_API_KEY."
+        )
+        return None
+    if resp.status_code >= 400:
+        print(f"FAILED: HTTP {resp.status_code} from {path}")
+        return None
+    return resp.json()
+
+
+def cmd_stats(args: argparse.Namespace) -> int:
+    """Audit trail metrics over a window — dogfood weekly counts."""
+    data = _api_get_json(args.port, "/api/v1/audit/stats", "stats", {"days": args.days})
+    if data is None:
         return 1
 
     if not data.get("enabled", True):
@@ -349,13 +374,10 @@ def cmd_stats(args: argparse.Namespace) -> int:
 
 
 def cmd_detections(args: argparse.Namespace) -> int:
-    try:
-        data = httpx.get(
-            f"{_base_url(args.port)}/api/v1/audit/detections/{args.correlation_id}",
-            timeout=10.0,
-        ).json()
-    except Exception:
-        print("Not running - start Agentmetry first (detections reads via the API).")
+    data = _api_get_json(
+        args.port, f"/api/v1/audit/detections/{args.correlation_id}", "detections"
+    )
+    if data is None:
         return 1
     if not data.get("enabled", True):
         print("Audit export is disabled, so no sessions are recorded.")
@@ -595,6 +617,39 @@ _HOOK_INSTALLERS = ("cursor", "claude", "codex", "qwen", "kimi", "qoder", "codeb
 
 
 
+def _cloud_cursor_cache(args: argparse.Namespace) -> int:
+    """Record Cursor cloud-agent tool calls from the desktop app's local cache.
+
+    No vendor key and no network call to Cursor: the calls are read from the
+    state database the Cursor app keeps on this machine, read-only. See
+    `core/audit/cursor_cloud_cache.py` for what that cache does and does not hold.
+    """
+    from agentmetry.core.audit.cursor_cloud_cache import STATE_FILE, default_db_path, import_cache
+    from agentmetry.core.paths import data_dir
+    from agentmetry.hooks.ingest import post_ingest
+
+    db = Path(args.db).expanduser() if args.db else default_db_path()
+    if db is None or not db.is_file():
+        print(f"No Cursor state database at {db}. Is the Cursor desktop app installed here? (--db to point at one)")
+        return 2
+
+    def post(payload: dict) -> bool:
+        # No spool: a call that did not land is simply not marked as recorded,
+        # and the next run picks it up from the cache again.
+        return post_ingest(payload, quiet=True, spool=False)
+
+    result = import_cache(db, post=post, state_path=data_dir() / STATE_FILE, dry_run=args.dry_run)
+    verb = "would record" if args.dry_run else "recorded"
+    count = result.new if args.dry_run else result.posted
+    print(f"cursor-cache: {result.agents} cloud agent conversation(s), {result.calls} finished tool call(s).")
+    print(f"  {verb} {count}, already recorded {result.already_seen}, failed {result.failed}.")
+    if result.skipped:
+        print(f"  skipped: {dict(result.skipped)}")
+    if result.tools:
+        print("  by tool: " + ", ".join(f"{name} {n}" for name, n in result.tools.most_common()))
+    return 1 if result.failed else 0
+
+
 def cmd_cloud(args: argparse.Namespace) -> int:
     """Poll a vendor cloud-agent API once and record what it exposes.
 
@@ -605,6 +660,9 @@ def cmd_cloud(args: argparse.Namespace) -> int:
     """
     import os
 
+    if args.provider == "cursor-cache":
+        return _cloud_cursor_cache(args)
+
     import httpx
 
     from agentmetry.core.audit.cloud_bridge import (
@@ -628,7 +686,14 @@ def cmd_cloud(args: argparse.Namespace) -> int:
         headers = {"Content-Type": "application/json"}
         if key:
             headers["Authorization"] = f"Bearer {key}"
-        resp = httpx.post(f"{url}/api/v1/audit/ingest", json=payload, headers=headers, timeout=15)
+        # A 429 is the ingest rate limit (#312). Unlike a hook, this importer
+        # has no spool, so it waits as told and tries again rather than drop
+        # the event.
+        for _ in range(6):
+            resp = httpx.post(f"{url}/api/v1/audit/ingest", json=payload, headers=headers, timeout=15)
+            if resp.status_code != 429:
+                break
+            time.sleep(min(30.0, float(resp.headers.get("Retry-After", "1") or 1)))
         ok = resp.status_code < 300
         if ok:
             posted += 1
@@ -1139,6 +1204,32 @@ def cmd_mcp(args: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_scan(args: argparse.Namespace) -> int:
+    """Check what an agent is about to depend on: MCP servers, skills, packages.
+
+    Exits 1 when anything is found and 2 when nothing could be read. Unlike
+    `mcp` and `posture`, which a health check runs in the background, this is
+    run on purpose before something is installed, so a finding should stop the
+    script that ran it. See core/scanner/scan.py.
+    """
+    import json as _json
+    from pathlib import Path as _Path
+
+    from agentmetry.core.scanner.scan import run
+
+    report = run(
+        args.target,
+        project=_Path(args.project).resolve() if args.project else _Path.cwd(),
+        known_file=args.known,
+    )
+    if args.json:
+        print(_json.dumps(report.to_json(), indent=2))
+    else:
+        for line in report.lines():
+            print(line)
+    return report.exit_code()
+
+
 def cmd_posture(args: argparse.Namespace) -> int:
     """Report agent settings that take a human or a hook out of the loop.
 
@@ -1591,10 +1682,13 @@ def main(argv: list[str] | None = None) -> int:
     stats = sub.add_parser("stats", help="audit trail metrics for dogfood (events, detections)")
     stats.add_argument("--days", type=int, default=7)
     cloud = sub.add_parser("cloud", help="record what a vendor cloud-agent API exposes (Cursor, Claude)")
-    cloud.add_argument("provider", choices=("cursor", "claude"))
+    cloud.add_argument("provider", choices=("cursor", "claude", "cursor-cache"))
+    cloud.add_argument("--db", default="", help="cursor-cache: Cursor state database (default: the desktop app's)")
+    cloud.add_argument("--dry-run", action="store_true", help="cursor-cache: count what would be recorded, post nothing")
     cloud.add_argument("--url", default="", help="vendor API base override")
     cloud.add_argument("--limit", type=int, default=10, help="max sessions/agents per poll")
     cloud.add_argument("--skip-runs", action="store_true", help="cursor: agents only, skip per-run fetch")
+    cloud.add_argument("--remote", action="store_true", help="claude: the Compliance API's remote sessions instead of local ones (not Claude Code on the web, which that API excludes)")
     detections = sub.add_parser("detections", help="list detections for one session")
     detections.add_argument("correlation_id", help="correlation_id / session id")
     disposition = sub.add_parser("disposition", help="close an audit detection from the shell")
@@ -1698,6 +1792,18 @@ def main(argv: list[str] | None = None) -> int:
     posture.add_argument(
         "--strict", action="store_true", help="exit 1 when any high-severity finding is present",
     )
+    scan = sub.add_parser(
+        "scan",
+        help="check MCP servers, skills or a package name before an agent depends on them",
+    )
+    scan.add_argument(
+        "target", nargs="?", default=None,
+        help="a file or folder (skills, rules, a saved tools/list), npm:NAME or pypi:NAME; "
+        "omit to scan the MCP servers configured on this machine",
+    )
+    scan.add_argument("--project", default=None, help="project root whose MCP config to include (default: cwd)")
+    scan.add_argument("--known", default=None, help="file of extra known package names, one per line (npm:/pypi: or bare)")
+    scan.add_argument("--json", action="store_true", help="print the report as JSON")
     otel = sub.add_parser(
         "otel", help="receive Claude Code's native OpenTelemetry stream (no hooks needed)"
     )
@@ -1810,6 +1916,7 @@ def main(argv: list[str] | None = None) -> int:
         "anchor": cmd_anchor,
         "mcp": cmd_mcp,
         "posture": cmd_posture,
+        "scan": cmd_scan,
         "dashboard": cmd_dashboard,
         "otel": cmd_otel,
         "import-agt": cmd_import_agt,