@rulemetric/proxy 0.2.2

package/addon/reporter.py

@@ -0,0 +1,778 @@
+"""Non-blocking HTTP reporter for sending events + context snapshots to the
+RuleMetric API, with on-disk spool for durability across API outages and
+proxy restarts.
+
+Three layers, in order:
+
+1. **Inline retry** — `_post_with_retry` does 3 attempts with exponential
+   backoff (0.5s, 1s) and treats 4xx as a permanent failure (no retry,
+   no spool). 5xx and transport errors exhaust retries before falling
+   through to the spool.
+
+2. **Spool** — `~/.config/rulemetric/event-spool.jsonl` is an append-only
+   JSONL queue. Anything that exhausts retries lands here. Append is
+   `O_APPEND`+`fsync` per line so a crash mid-write loses at most that one
+   line. The file is FIFO-evicted at 100 MB to bound disk use.
+
+3. **Drainer** — a single background thread (`_drain_loop`) wakes every
+   30 seconds while the spool is non-empty. It re-POSTs each line through
+   the same retry helper. On persistent 5xx, it sleeps and retries later.
+   On 4xx, it drops the line. Successful drains rewrite the spool with
+   the remaining lines (atomic rename).
+
+**Important caveat about replay ordering:** the spool stores the request
+body verbatim. The receiver auto-assigns `sequence` on insert, so a
+replayed event gets a NEW sequence number — it appears AFTER the gap in
+the timeline rather than filling it. The total event count is correct;
+the relative ordering is not. Documented in
+`docs/plans/2026-05-02-proxy-reporter-durability-prp.md` as accepted
+trade-off for v1.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import shutil
+import tempfile
+import threading
+import time
+from typing import Any
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+from secret_redactor import redact_snapshot
+
+logger = logging.getLogger("rulemetric.reporter")
+
+DEFAULT_TIMEOUT = 5  # seconds (was 2 — too aggressive for cold starts)
+MAX_RETRIES = 2  # 3 total attempts
+RETRY_BACKOFF = 0.5  # seconds — exponential backoff base
+
+SPOOL_MAX_BYTES = 100 * 1024 * 1024  # 100 MB cap before FIFO eviction
+SPOOL_EVICT_FRACTION = 0.10  # evict the oldest 10% when over cap
+DRAIN_INTERVAL_SECONDS = 30  # how often to re-attempt spooled items
+
+# ─── Stats ────────────────────────────────────────────────────────────────
+# Per-kind so operators can distinguish "events flowing fine but snapshots
+# failing" from "everything is broken". Kinds: "event", "snapshot".
+_stats_lock = threading.Lock()
+_STAT_KEYS = (
+    "posted",
+    "failed_permanent",  # 4xx — receiver rejected, replay won't help
+    "spooled",  # exhausted retries, parked on disk
+    "replayed_ok",  # successfully drained from spool
+    "replayed_failed",  # 4xx during drain → dropped
+    "dropped_evicted",  # FIFO-evicted from spool when over cap
+    "dropped_corrupt",  # unparseable JSON line in spool
+    "skipped",  # no session_id at call site
+)
+_stats: dict[str, dict[str, int]] = {
+    "event": {k: 0 for k in _STAT_KEYS},
+    "snapshot": {k: 0 for k in _STAT_KEYS},
+}
+
+# Debounced instruction linking — trigger once per session, not every snapshot
+_linked_sessions: set[str] = set()
+_link_lock = threading.Lock()
+
+# Spool serialization — protects file r/w across drainer + appenders
+_spool_lock = threading.Lock()
+_drain_thread: threading.Thread | None = None
+_drain_started_lock = threading.Lock()
+
+
+def _bump(kind: str, key: str, n: int = 1) -> None:
+    with _stats_lock:
+        _stats[kind][key] += n
+
+
+def get_stats() -> dict[str, dict[str, int]]:
+    """Return a deep copy of the per-kind stats."""
+    with _stats_lock:
+        return {kind: dict(values) for kind, values in _stats.items()}
+
+
+def _get_api_url() -> str:
+    return os.environ.get("RULEMETRIC_API_URL", "http://localhost:3000")
+
+
+def _get_auth_headers() -> dict[str, str]:
+    api_key = os.environ.get("RULEMETRIC_API_KEY", "")
+    token = os.environ.get("RULEMETRIC_ACCESS_TOKEN", "")
+
+    headers: dict[str, str] = {"Content-Type": "application/json"}
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    elif token:
+        headers["Authorization"] = f"Bearer {token}"
+    else:
+        logger.warning(
+            "No auth credentials found — API calls will fail. "
+            "Set RULEMETRIC_API_KEY or RULEMETRIC_ACCESS_TOKEN."
+        )
+    return headers
+
+
+def _config_dir() -> str:
+    """Mirror the CLI / hooks config-dir resolution."""
+    override = os.environ.get("RULEMETRIC_CONFIG_DIR")
+    if override:
+        return override
+    home = os.path.expanduser("~")
+    return os.path.join(home, ".config", "rulemetric")
+
+
+def _spool_path() -> str:
+    return os.path.join(_config_dir(), "event-spool.jsonl")
+
+
+def get_active_org_id() -> str | None:
+    """Resolve the active org for capture attribution.
+
+    Priority: ``RULEMETRIC_ORG_ID`` env var beats the local file. The file
+    lives at ``$RULEMETRIC_CONFIG_DIR/active-org`` and contains JSON
+    written by ``rulemetric org switch``. Missing file, malformed JSON,
+    or any I/O error all collapse to ``None`` — the proxy must never crash
+    on bad org context.
+    """
+    env_org = os.environ.get("RULEMETRIC_ORG_ID")
+    if env_org and env_org.strip():
+        return env_org.strip()
+
+    path = os.path.join(_config_dir(), "active-org")
+    try:
+        with open(path, encoding="utf-8") as f:
+            payload = json.load(f)
+    except (FileNotFoundError, OSError, json.JSONDecodeError):
+        return None
+    except Exception as exc:  # pragma: no cover — defensive
+        logger.debug("Unexpected error reading active-org file %s: %s", path, exc)
+        return None
+
+    if not isinstance(payload, dict):
+        return None
+    org_id = payload.get("orgId")
+    if isinstance(org_id, str) and org_id.strip():
+        return org_id.strip()
+    return None
+
+
+# ─── Shared retry helper ──────────────────────────────────────────────────
+
+
+def _post_with_retry(
+    url: str,
+    data: bytes,
+    headers: dict[str, str],
+    *,
+    log_label: str,
+) -> tuple[bool, str | None, bool]:
+    """POST `data` with up to MAX_RETRIES retries on transport / 5xx errors.
+
+    Returns:
+        (success, last_error_str, is_permanent)
+
+        `is_permanent=True` means a 4xx from the server: the request will
+        never succeed in its current form, so callers SHOULD NOT spool it.
+        `is_permanent=False` covers transport errors and 5xx — caller
+        should spool the payload for later replay.
+    """
+    last_error: str | None = None
+    is_permanent = False
+
+    for attempt in range(1 + MAX_RETRIES):
+        try:
+            req = Request(url, data=data, headers=headers, method="POST")
+            with urlopen(req, timeout=DEFAULT_TIMEOUT) as resp:
+                if resp.status < 300:
+                    return True, None, False
+                # Some receivers may return 3xx — treat as transient.
+                last_error = f"HTTP {resp.status}"
+                logger.warning(
+                    "%s: API returned %d on attempt %d/%d",
+                    log_label, resp.status, attempt + 1, 1 + MAX_RETRIES,
+                )
+        except HTTPError as exc:
+            last_error = f"HTTP {exc.code}: {exc.reason}"
+            if 400 <= exc.code < 500:
+                # 409 from a duplicate replay is "success" — receiver already
+                # has this row. Treat as posted, not failed.
+                if exc.code == 409:
+                    return True, None, False
+                logger.error(
+                    "%s: API rejected request with HTTP %d (%s) — permanent failure",
+                    log_label, exc.code, exc.reason,
+                )
+                is_permanent = True
+                return False, last_error, True
+            logger.warning(
+                "%s: HTTP %d on attempt %d/%d: %s",
+                log_label, exc.code, attempt + 1, 1 + MAX_RETRIES, exc.reason,
+            )
+        except (URLError, OSError, TimeoutError) as exc:
+            last_error = str(exc)
+            logger.warning(
+                "%s: transport error on attempt %d/%d: %s",
+                log_label, attempt + 1, 1 + MAX_RETRIES, exc,
+            )
+
+        if attempt < MAX_RETRIES:
+            time.sleep(RETRY_BACKOFF * (2 ** attempt))
+
+    return False, last_error, is_permanent
+
+
+# ─── Spool ────────────────────────────────────────────────────────────────
+
+
+def _spool_append(kind: str, session_id: str, payload: dict) -> None:
+    """Append one envelope line to the spool. Rotates if over cap.
+
+    Each line: ``{"kind": "...", "session_id": "...", "payload": {...},
+    "queued_at": "ISO-8601"}``. Caller owns the kind/session_id; we add
+    the timestamp for diagnostics.
+    """
+    envelope = {
+        "kind": kind,
+        "session_id": session_id,
+        "payload": payload,
+        "queued_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+    }
+    line = json.dumps(envelope, separators=(",", ":")) + "\n"
+    encoded = line.encode("utf-8")
+
+    path = _spool_path()
+    with _spool_lock:
+        try:
+            os.makedirs(os.path.dirname(path), exist_ok=True)
+            # O_APPEND guarantees atomic append on POSIX even with multiple
+            # writers. We add fsync so a crash mid-write loses at most this
+            # one line, not the lines before it.
+            fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o600)
+            try:
+                os.write(fd, encoded)
+                os.fsync(fd)
+            finally:
+                os.close(fd)
+        except OSError as exc:
+            logger.error(
+                "Failed to append to spool %s: %s. Event lost.", path, exc,
+            )
+            _bump(kind, "dropped_corrupt")
+            return
+
+        _bump(kind, "spooled")
+        _evict_if_over_cap_locked()
+
+
+def _evict_if_over_cap_locked() -> None:
+    """Caller must hold _spool_lock. Evicts oldest ~10% of file if over cap."""
+    path = _spool_path()
+    try:
+        size = os.path.getsize(path)
+    except OSError:
+        return
+    if size <= SPOOL_MAX_BYTES:
+        return
+
+    # Drop enough to land 10% below the cap in a single pass. The old
+    # fixed 10%-of-cap drop meant a far-over-cap file (16 GB once) needed
+    # hundreds of full-file copies to recover — it never did.
+    bytes_to_drop = size - SPOOL_MAX_BYTES + int(
+        SPOOL_MAX_BYTES * SPOOL_EVICT_FRACTION
+    )
+    evicted = 0
+    try:
+        with open(path, "rb") as src:
+            # Skip until we've passed `bytes_to_drop`; align to next newline.
+            src.seek(bytes_to_drop)
+            src.readline()  # consume partial line at boundary
+            tmp_fd, tmp_path = tempfile.mkstemp(
+                dir=os.path.dirname(path), prefix=".spool-", suffix=".tmp",
+            )
+            with os.fdopen(tmp_fd, "wb") as dst:
+                # Count evicted lines up to the boundary by re-reading.
+                src.seek(0)
+                pos = 0
+                for line in src:
+                    pos += len(line)
+                    if pos <= bytes_to_drop:
+                        evicted += 1
+                        # Charge eviction by inspecting the kind in each line
+                        try:
+                            env = json.loads(line)
+                            kind = env.get("kind", "event")
+                        except (json.JSONDecodeError, ValueError):
+                            kind = "event"
+                        _bump(kind, "dropped_evicted")
+                    else:
+                        dst.write(line)
+                # Copy the rest after the eviction boundary
+                for line in src:
+                    dst.write(line)
+            os.replace(tmp_path, path)
+            logger.warning(
+                "Spool over %d bytes — evicted %d oldest entries.",
+                SPOOL_MAX_BYTES, evicted,
+            )
+    except OSError as exc:
+        logger.error("Spool eviction failed: %s", exc)
+
+
+def _replay_envelope(envelope: dict) -> tuple[bool, bool]:
+    """Replay one spool envelope. Returns (success, is_permanent).
+
+    Used by the drainer. On success, the line should be removed from the
+    spool. On `is_permanent`, the line should also be removed (dropped).
+    On transient failure, the line stays — drainer will sleep and retry.
+    """
+    kind = envelope.get("kind", "event")
+    session_id = envelope.get("session_id")
+    payload = envelope.get("payload")
+    if not session_id or not isinstance(payload, dict):
+        # Corrupt / unexpected shape — drop.
+        return False, True
+
+    api_url = _get_api_url()
+    if kind == "event":
+        url = f"{api_url}/api/sessions/{session_id}/events"
+    elif kind == "snapshot":
+        url = f"{api_url}/api/sessions/{session_id}/context-snapshots"
+    else:
+        # Unknown kind — drop.
+        return False, True
+
+    headers = _get_auth_headers()
+    data = json.dumps(payload).encode("utf-8")
+    success, _err, is_permanent = _post_with_retry(
+        url, data, headers, log_label=f"replay {kind}",
+    )
+    return success, is_permanent
+
+
+def _drain_once() -> bool:
+    """Snapshot the spool, replay each line, push leftovers back.
+
+    Returns True if the spool is now empty, False if there's still work
+    (transient failure paused the drain or new work arrived).
+
+    Uses a rename-snapshot to avoid clobbering concurrent appends:
+      1. Lock briefly: rename `event-spool.jsonl` → `event-spool.jsonl.draining`.
+         New appends after this point land in a fresh `event-spool.jsonl`.
+      2. Unlock. Read the snapshot, replay each line.
+      3. Lock briefly: prepend any leftovers (replay-paused lines) onto
+         `event-spool.jsonl`, preserving FIFO order. Delete snapshot.
+    """
+    path = _spool_path()
+    snapshot = path + ".draining"
+
+    with _spool_lock:
+        try:
+            if not os.path.exists(path) or os.path.getsize(path) == 0:
+                return True
+        except OSError:
+            return True
+        # If a previous drain crashed mid-flight, a stale snapshot may
+        # exist. Merge it back so we don't double-process.
+        if os.path.exists(snapshot):
+            logger.warning("Recovering stale drain snapshot %s", snapshot)
+            try:
+                # Stream-append current spool onto the snapshot, then rename
+                # back. Never load either file into memory — a runaway spool
+                # once reached 16 GB and the previous read()-based merge
+                # jetsam-killed the proxy at every boot (2026-06-10).
+                with open(snapshot, "ab") as dst, open(path, "rb") as cur:
+                    shutil.copyfileobj(cur, dst)
+                os.replace(snapshot, path)
+            except OSError as exc:
+                logger.error("Stale snapshot recovery failed: %s", exc)
+                return False
+        _evict_if_over_cap_locked()
+        try:
+            os.rename(path, snapshot)
+        except OSError as exc:
+            logger.error("Spool snapshot rename failed: %s", exc)
+            return True
+
+    # Stream the snapshot line-by-line — never readlines() the whole file
+    # into memory. Once a transient failure pauses the drain, remaining
+    # lines spill to an on-disk leftovers file instead of a Python list.
+    leftovers_path = snapshot + ".leftovers"
+    have_leftovers = False
+    try:
+        with open(snapshot, "rb") as f, open(leftovers_path, "wb") as lf:
+            paused = False
+            for raw in f:
+                if paused:
+                    lf.write(raw)
+                    have_leftovers = True
+                    continue
+                text = raw.decode("utf-8", errors="replace").strip()
+                if not text:
+                    continue
+                try:
+                    envelope = json.loads(text)
+                except (json.JSONDecodeError, ValueError):
+                    _bump("event", "dropped_corrupt")
+                    logger.warning("Skipping corrupt spool line (length=%d)", len(text))
+                    continue
+
+                kind = envelope.get("kind", "event")
+                success, is_permanent = _replay_envelope(envelope)
+                if success:
+                    _bump(kind, "replayed_ok")
+                elif is_permanent:
+                    _bump(kind, "replayed_failed")
+                    logger.error(
+                        "Drain dropped permanently-failed envelope: kind=%s session=%s",
+                        kind, envelope.get("session_id"),
+                    )
+                else:
+                    # Transient failure — keep this line and pause the rest.
+                    paused = True
+                    lf.write(raw)
+                    have_leftovers = True
+    except OSError as exc:
+        logger.error("Spool snapshot read failed: %s", exc)
+        try:
+            os.remove(leftovers_path)
+        except OSError:
+            pass
+        return True
+
+    # Merge leftovers (FIFO) in front of any concurrent appends that arrived
+    # in `path` while we were replaying. Brief lock: read concurrent lines,
+    # write `leftovers + concurrent`, atomic rename.
+    with _spool_lock:
+        try:
+            have_concurrent = (
+                os.path.exists(path) and os.path.getsize(path) > 0
+            )
+            if have_leftovers or have_concurrent:
+                tmp_fd, tmp_path = tempfile.mkstemp(
+                    dir=os.path.dirname(path),
+                    prefix=".spool-", suffix=".tmp",
+                )
+                with os.fdopen(tmp_fd, "wb") as dst:
+                    if have_leftovers:
+                        with open(leftovers_path, "rb") as lf:
+                            shutil.copyfileobj(lf, dst)
+                    if have_concurrent:
+                        with open(path, "rb") as f:
+                            shutil.copyfileobj(f, dst)
+                    dst.flush()
+                    os.fsync(dst.fileno())
+                os.replace(tmp_path, path)
+            else:
+                # Drain complete — nothing pending and nothing arrived during.
+                try:
+                    os.remove(path)
+                except FileNotFoundError:
+                    pass
+            # Snapshot fully consumed.
+            for stale in (snapshot, leftovers_path):
+                try:
+                    os.remove(stale)
+                except FileNotFoundError:
+                    pass
+            # The merge path above is NOT cap-checked by _spool_append, and
+            # an unbounded merge is exactly how the spool once escaped the
+            # 100 MB cap and grew to 16 GB. Enforce the cap here too.
+            _evict_if_over_cap_locked()
+        except OSError as exc:
+            logger.error("Spool rewrite failed: %s", exc)
+            return False
+
+    return not have_leftovers and not have_concurrent
+
+
+def _drain_loop() -> None:
+    """Background loop: drain whenever spool is non-empty."""
+    logger.info("Spool drainer started.")
+    while True:
+        try:
+            done = _drain_once()
+        except Exception as exc:  # pragma: no cover — defensive
+            logger.error("Drain loop iteration crashed: %s", exc)
+            done = False
+        # Sleep a fixed interval whether the spool was empty or paused on
+        # transient failure. Cheap (only one stat() per cycle when empty).
+        time.sleep(DRAIN_INTERVAL_SECONDS if not done else DRAIN_INTERVAL_SECONDS)
+
+
+def start_drainer() -> None:
+    """Spawn the drain thread once. Idempotent.
+
+    Called from `RuleMetricAddon.__init__` so the drainer runs for the
+    proxy's lifetime. Safe to call from tests; subsequent calls are no-ops.
+    """
+    global _drain_thread
+    with _drain_started_lock:
+        if _drain_thread is not None and _drain_thread.is_alive():
+            return
+        _drain_thread = threading.Thread(
+            target=_drain_loop, daemon=True, name="rulemetric-spool-drain",
+        )
+        _drain_thread.start()
+
+
+# ─── Post functions (now spool-aware) ─────────────────────────────────────
+
+
+def _post_event(session_id: str, event: dict) -> None:
+    """Synchronous POST for session events — called from a background thread."""
+    api_url = _get_api_url()
+    url = f"{api_url}/api/sessions/{session_id}/events"
+    headers = _get_auth_headers()
+    data = json.dumps(event).encode("utf-8")
+
+    success, _err, is_permanent = _post_with_retry(
+        url, data, headers, log_label=f"event session={session_id[:8]}",
+    )
+    if success:
+        _bump("event", "posted")
+        return
+    if is_permanent:
+        _bump("event", "failed_permanent")
+        return
+    # Transient failure exhausted retries — spool for later replay.
+    _spool_append("event", session_id, event)
+
+
+def _post_snapshot(session_id: str, snapshot: dict) -> None:
+    """Synchronous POST — called from a background thread."""
+    api_url = _get_api_url()
+    url = f"{api_url}/api/sessions/{session_id}/context-snapshots"
+    headers = _get_auth_headers()
+    data = json.dumps(snapshot).encode("utf-8")
+
+    success, _err, is_permanent = _post_with_retry(
+        url, data, headers, log_label=f"snapshot session={session_id[:8]}",
+    )
+    if success:
+        _bump("snapshot", "posted")
+        # Auto-link instructions on first snapshot per session
+        with _link_lock:
+            if session_id not in _linked_sessions:
+                _linked_sessions.add(session_id)
+                threading.Thread(
+                    target=_trigger_link_instructions,
+                    daemon=True,
+                    name=f"rulemetric-link-{session_id[:8]}",
+                ).start()
+        return
+    if is_permanent:
+        _bump("snapshot", "failed_permanent")
+        return
+    _spool_append("snapshot", session_id, snapshot)
+
+
+def _trigger_link_instructions() -> None:
+    """Call POST /api/sessions/link-instructions to auto-link captured context."""
+    api_url = _get_api_url()
+    url = f"{api_url}/api/sessions/link-instructions"
+    headers = _get_auth_headers()
+
+    try:
+        req = Request(url, data=b"{}", headers=headers, method="POST")
+        with urlopen(req, timeout=10) as resp:
+            if resp.status < 300:
+                body = json.loads(resp.read())
+                linked = body.get("linked", 0)
+                if linked > 0:
+                    logger.info(
+                        "Auto-linked %d instruction(s) to %d session(s)",
+                        linked, body.get("sessionsLinked", 0),
+                    )
+    except (HTTPError, URLError, OSError, TimeoutError) as exc:
+        logger.debug("Auto-link instructions failed (non-critical): %s", exc)
+
+
+# ─── Auto-session creation ────────────────────────────────────────────────
+
+# Provider → tool mapping for auto-created sessions
+_PROVIDER_TO_TOOL: dict[str, str] = {
+    "anthropic": "claude_code",
+    "github_copilot_fim": "vscode_copilot",
+    "github_copilot_chat": "vscode_copilot",
+}
+
+# Cache of auto-created session IDs (tool → session_id)
+_auto_sessions: dict[str, str] = {}
+_auto_session_lock = threading.Lock()
+
+
+def _git_root() -> str | None:
+    """Best-effort git root directory from cwd."""
+    import subprocess
+    try:
+        root = subprocess.check_output(
+            ["git", "rev-parse", "--show-toplevel"],
+            stderr=subprocess.DEVNULL, timeout=3,
+        ).decode().strip()
+        return root if root else None
+    except Exception:
+        return None
+
+
+def _git_info() -> dict[str, Any]:
+    """Best-effort git context from cwd: branch, remote, root commit, worktree."""
+    import subprocess
+    info: dict[str, Any] = {}
+    metadata: dict[str, Any] = {}
+
+    def _run(args: list[str]) -> str:
+        try:
+            return subprocess.check_output(
+                args, stderr=subprocess.DEVNULL, timeout=3,
+            ).decode().strip()
+        except Exception:
+            return ""
+
+    branch = _run(["git", "rev-parse", "--abbrev-ref", "HEAD"])
+    if branch:
+        info["gitBranch"] = branch
+
+    remote = _run(["git", "config", "--get", "remote.origin.url"])
+    if remote:
+        metadata["gitRemote"] = remote
+
+    # Root commit: SHA of the very first commit. Stability anchor for
+    # project identity — survives URL renames. Pick the last line in case
+    # the repo has multiple disconnected histories (rare).
+    root_commit_output = _run(["git", "rev-list", "--max-parents=0", "HEAD"])
+    if root_commit_output:
+        root_commit = root_commit_output.split("\n")[-1].strip()
+        if root_commit:
+            metadata["gitRootCommit"] = root_commit
+
+    # Worktree detection: in a worktree, --git-dir differs from --git-common-dir.
+    git_dir = _run(["git", "rev-parse", "--git-dir"])
+    common_dir = _run(["git", "rev-parse", "--git-common-dir"])
+    if git_dir and common_dir:
+        metadata["isWorktree"] = git_dir != common_dir
+
+    if metadata:
+        info["metadata"] = metadata
+    return info
+
+
+def create_session_for_provider(
+    provider: str, project_path: str | None = None,
+) -> str | None:
+    """Create a session via the API for traffic that has no hook-based session.
+
+    Returns the new session ID, or None on failure. Results are cached so
+    only one session is created per tool per proxy lifetime. Now uses the
+    shared retry helper so cold-start API blips don't lose every event for
+    that tool.
+    """
+    tool = _PROVIDER_TO_TOOL.get(provider)
+    if not tool:
+        return None
+
+    with _auto_session_lock:
+        if tool in _auto_sessions:
+            return _auto_sessions[tool]
+
+    api_url = _get_api_url()
+    url = f"{api_url}/api/sessions"
+    headers = _get_auth_headers()
+    payload: dict[str, Any] = {"tool": tool}
+    raw_path = project_path or os.getcwd()
+    git_root = _git_root()
+    payload["projectPath"] = (
+        git_root if git_root and raw_path.startswith(git_root) else raw_path
+    )
+    payload.update(_git_info())
+    org_id = get_active_org_id()
+    if org_id:
+        payload["orgId"] = org_id
+    data = json.dumps(payload).encode("utf-8")
+
+    # Inline retry, no spool, and EXACTLY ONE POST per attempt: session-create
+    # is not idempotent for auto-created sessions (no externalSessionId), so
+    # spooling or a second confirmation POST would produce duplicate rows.
+    # (A previous version POSTed via _post_with_retry and then POSTed AGAIN
+    # to read the body — every successful auto-create made two sessions.)
+    last_exc: Exception | None = None
+    for attempt in range(1 + MAX_RETRIES):
+        try:
+            req = Request(url, data=data, headers=headers, method="POST")
+            with urlopen(req, timeout=DEFAULT_TIMEOUT) as resp:
+                if resp.status < 300:
+                    body = json.loads(resp.read())
+                    session_id = body.get("id")
+                    if session_id:
+                        with _auto_session_lock:
+                            _auto_sessions[tool] = session_id
+                        logger.info("Auto-created %s session: %s", tool, session_id)
+                        return session_id
+                    return None  # 2xx without id — retrying would duplicate
+                last_exc = RuntimeError(f"HTTP {resp.status}")
+        except HTTPError as exc:
+            if 400 <= exc.code < 500:
+                logger.warning("Auto-create session for %s rejected: HTTP %d", tool, exc.code)
+                return None  # permanent — retrying won't help
+            last_exc = exc
+        except (URLError, OSError, TimeoutError, ValueError) as exc:
+            last_exc = exc
+        if attempt < MAX_RETRIES:
+            time.sleep(RETRY_BACKOFF * (2 ** attempt))
+
+    logger.warning("Failed to auto-create session for %s: %s", tool, last_exc)
+    return None
+
+
+# ─── Public reporting API ─────────────────────────────────────────────────
+
+
+def report_event(session_id: str | None, event: dict) -> None:
+    """Fire-and-forget: POST a session event in a background thread."""
+    if not session_id:
+        _bump("event", "skipped")
+        return
+
+    threading.Thread(
+        target=_post_event,
+        args=(session_id, event),
+        daemon=True,
+        name=f"rulemetric-event-{session_id[:8]}",
+    ).start()
+
+
+def report_snapshot(session_id: str | None, snapshot: dict) -> None:
+    """Fire-and-forget: POST snapshot to API in a background thread.
+
+    Redacts detected secrets from snapshot content before sending.
+    """
+    if not session_id:
+        logger.warning(
+            "No session ID — snapshot dropped (provider=%s, model=%s). "
+            "Ensure session tracking is active.",
+            snapshot.get("provider", "unknown"),
+            snapshot.get("model", "unknown"),
+        )
+        _bump("snapshot", "skipped")
+        return
+
+    try:
+        snapshot, findings = redact_snapshot(snapshot)
+        if findings:
+            logger.info(
+                "Redacted %d secret(s) from snapshot (patterns: %s)",
+                len(findings),
+                ", ".join(f["pattern"] for f in findings[:5]),
+            )
+    except Exception as exc:
+        # Fail-open: redaction failure must not block snapshot reporting
+        logger.warning("Secret redaction failed (continuing without): %s", exc)
+
+    threading.Thread(
+        target=_post_snapshot,
+        args=(session_id, snapshot),
+        daemon=True,
+        name=f"rulemetric-report-{session_id[:8]}",
+    ).start()