Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

feat(hogli): stamp session, command kind, and rerun on telemetry events (#122357)

Georges-Antoine Assi3576d5bc3d47
diff --git a/tools/hogli-commands/README.md b/tools/hogli-commands/README.md
index 644382759af6..75f9f7dcb2fe 100644
--- a/tools/hogli-commands/README.md
+++ b/tools/hogli-commands/README.md
@@ -50,7 +50,7 @@ That's it. No side-effect imports, no central registration list to maintain.
`config.boot_modules` in `hogli.yaml` lists modules imported once at startup. They register hooks via `hogli.hooks`:
- `hogli_commands.prechecks` — declares the `migrations` precheck (used by `dev:start`).
-- `hogli_commands.telemetry_props` — adds PostHog environment props (`environment`, `actor`, `agent`, `is_agent`, `git_hook`, `in_flox`, `is_worktree`, `is_posthog_dev`, `process_manager`, `has_devenv_config`, `repo_sha`, `repo_commit_date`) to every `command_started` / `command_completed` event.
+- `hogli_commands.telemetry_props` — adds PostHog environment props (`environment`, `actor`, `agent`, `is_agent`, `git_hook`, `in_flox`, `is_worktree`, `is_posthog_dev`, `process_manager`, `has_devenv_config`, `repo_sha`, `repo_commit_date`, `git_branch`, `pr_number`, `command_kind`, `session_id`, `session_id_source`, `is_rerun`) to every `command_started` / `command_completed` event.
- `hogli_commands.hint_hook` — shows a contextual hint after successful commands.
Add a new boot module by creating a file that calls one of the `register_*` helpers from `hogli.hooks` at import time, then list it under `config.boot_modules:`. Keep these modules import-light: the precheck handler in `prechecks.py` is the canonical example of deferring its heavy import until the handler actually fires.
diff --git a/tools/hogli-commands/hogli_commands/telemetry_props.py b/tools/hogli-commands/hogli_commands/telemetry_props.py
index 05816ea02e24..5fa8c9e4bfc0 100644
--- a/tools/hogli-commands/hogli_commands/telemetry_props.py
+++ b/tools/hogli-commands/hogli_commands/telemetry_props.py
@@ -11,10 +11,18 @@ from __future__ import annotations
import os
import re
import sys
+import json
import time
+import fcntl
+import socket
+import hashlib
+import secrets
import functools
+import contextlib
import subprocess
import configparser
+from collections.abc import Iterator, Sequence
+from dataclasses import dataclass
from pathlib import Path
from typing import Any, Literal
@@ -22,6 +30,8 @@ from hogli.hooks import register_telemetry_properties
from hogli.manifest import REPO_ROOT
from hogli.telemetry import _load_config, _save_config, is_ci
+from hogli_commands.test_runner import runs_on_playwright
+
_POSTHOG_DEV_CACHE_TTL_SECONDS = 30 * 86400 # 30 days
@@ -54,6 +64,46 @@ _STANDARD_AGENT_ENV_VARS = ("AI_AGENT", "AGENT")
_ACTOR_ENV_VAR = "HOGLI_ACTOR"
+# Ordered like _AGENT_ENV_MARKERS: posthog-code runs claude or codex inside its task run,
+# so the task run id must win over the session id of the inner harness.
+_AGENT_SESSION_ENV_VARS = (
+ "HOGLI_SESSION_ID",
+ "POSTHOG_TASK_RUN_ID",
+ "CLAUDE_CODE_SESSION_ID",
+ "CODEX_THREAD_ID",
+)
+
+_PR_NUMBER_ENV_VARS = ("HOGLI_PR_NUMBER", "GITHUB_PR_NUMBER", "BUILDKITE_PULL_REQUEST")
+_GITHUB_PULL_REF = re.compile(r"^refs/pull/(\d+)/")
+
+_TELEMETRY_STATE_PATH = Path.home() / ".hogli" / "telemetry_state.json"
+_STATE_LOCK_ATTEMPTS = 5
+_STATE_LOCK_RETRY_SECONDS = 0.002
+_RERUN_WINDOW_SECONDS = 30 * 60
+_MAX_RECORDED_RUNS = 200
+# The terminal session cache is keyed by the session leader pid. After this idle age the
+# pid can belong to a new terminal, so the id is derived again from the leader start time.
+_TERMINAL_SESSION_TTL_SECONDS = 12 * 3600
+_MAX_CACHED_TERMINAL_SESSIONS = 50
+
+CommandKind = Literal[
+ "verify-lint",
+ "verify-typecheck",
+ "verify-test",
+ "verify-preflight",
+ "verify-e2e",
+ "build",
+ "run-stack",
+ "devbox",
+ "other",
+]
+
+_RUN_STACK_COMMANDS = frozenset(
+ {"start", "up", "wait", "stop", "down", "dev:up", "services:ready", "db:migrate", "migrations:run"}
+)
+_LINT_COMMANDS = frozenset({"tool:ruff", "migrations:check"})
+_NOT_TESTS = frozenset({"test:quarantine"})
+
def _declared(var: str) -> str:
"""Self-declared label from *var*, normalized so a sloppy export ('Sandbox ')
@@ -221,6 +271,225 @@ def _is_posthog_dev() -> bool:
return is_member
+def classify_command(command: str | None, argv: Sequence[str] = ()) -> CommandKind:
+ """Bucket a hogli command by the kind of work it does, so verification loops can be counted.
+
+ *argv* holds the arguments after the command name. ``hogli test`` dispatches on its
+ paths, so a path the test runner hands to Playwright makes it an e2e run.
+ """
+ if not command:
+ return "other"
+ segments = command.split(":")
+ prefix = segments[0]
+ leaf = segments[-1]
+ if command == "ci:preflight":
+ return "verify-preflight"
+ if command == "test:e2e" or (
+ command == "test" and any(runs_on_playwright(arg) for arg in argv if not arg.startswith("-"))
+ ):
+ return "verify-e2e"
+ if "typecheck" in leaf or "mypy" in leaf:
+ return "verify-typecheck"
+ if command not in _NOT_TESTS and (prefix == "test" or leaf == "test"):
+ return "verify-test"
+ if prefix in {"lint", "format"} or "lint" in segments or command in _LINT_COMMANDS:
+ return "verify-lint"
+ if prefix == "build" or leaf == "build":
+ return "build"
+ if prefix == "devbox":
+ return "devbox"
+ if command in _RUN_STACK_COMMANDS or prefix in {"start", "docker", "check"}:
+ return "run-stack"
+ return "other"
+
+
+@dataclass(frozen=True)
+class RecordedRun:
+ session_id: str
+ kind: str
+ at: float
+
+
+def is_rerun(runs: Sequence[RecordedRun], session_id: str, kind: str, now: float) -> bool:
+ """Whether *kind* already ran in *session_id* within the rerun window before *now*."""
+ return any(
+ run.session_id == session_id and run.kind == kind and 0 <= now - run.at <= _RERUN_WINDOW_SECONDS for run in runs
+ )
+
+
+def _recent_runs(runs: Sequence[RecordedRun], now: float) -> list[RecordedRun]:
+ recent = [run for run in runs if 0 <= now - run.at <= _RERUN_WINDOW_SECONDS]
+ return recent[-_MAX_RECORDED_RUNS:]
+
+
+def _state_lock() -> Iterator[None]:
+ """Serialize the state read-modify-write across hogli processes.
+
+ Gives up after a few milliseconds and runs unlocked, because a lost rerun record
+ costs less than a delayed command.
+ """
+ handle = None
+ try:
+ _TELEMETRY_STATE_PATH.parent.mkdir(parents=True, exist_ok=True)
+ handle = _TELEMETRY_STATE_PATH.with_name(f"{_TELEMETRY_STATE_PATH.name}.lock").open("a")
+ for attempt in range(_STATE_LOCK_ATTEMPTS):
+ try:
+ fcntl.flock(handle, fcntl.LOCK_EX | fcntl.LOCK_NB)
+ break
+ except BlockingIOError:
+ if attempt < _STATE_LOCK_ATTEMPTS - 1:
+ time.sleep(_STATE_LOCK_RETRY_SECONDS)
+ except Exception:
+ pass
+ try:
+ yield
+ finally:
+ if handle is not None:
+ handle.close()
+
+
+def _load_state() -> dict[str, Any]:
+ try:
+ state = json.loads(_TELEMETRY_STATE_PATH.read_text())
+ return state if isinstance(state, dict) else {}
+ except Exception:
+ return {}
+
+
+def _save_state(state: dict[str, Any]) -> None:
+ """Write through a rename so a concurrent hogli process never reads a partial file."""
+ try:
+ _TELEMETRY_STATE_PATH.parent.mkdir(parents=True, exist_ok=True)
+ tmp = _TELEMETRY_STATE_PATH.with_name(f"{_TELEMETRY_STATE_PATH.name}.{os.getpid()}.tmp")
+ tmp.write_text(json.dumps(state))
+ tmp.replace(_TELEMETRY_STATE_PATH)
+ except Exception:
+ pass
+
+
+def _parse_runs(raw: Any) -> list[RecordedRun]:
+ runs: list[RecordedRun] = []
+ for entry in raw if isinstance(raw, list) else []:
+ try:
+ session_id, kind, at = entry
+ runs.append(RecordedRun(session_id=str(session_id), kind=str(kind), at=float(at)))
+ except Exception:
+ continue
+ return runs
+
+
+def _proc_start_time(pid: int) -> str | None:
+ """Start time of *pid* from ``/proc``, which tells apart two terminals that got the same pid."""
+ try:
+ stat = Path(f"/proc/{pid}/stat").read_text()
+ # Field 2 is the command name and can contain spaces, so split after its closing paren.
+ return stat.rsplit(")", 1)[1].split()[19]
+ except Exception:
+ return None
+
+
+def _ps_start_time(pid: int) -> str | None:
+ try:
+ result = subprocess.run(["ps", "-o", "lstart=", "-p", str(pid)], capture_output=True, text=True, timeout=1)
+ started = result.stdout.strip()
+ return started if result.returncode == 0 and started else None
+ except Exception:
+ return None
+
+
+def _terminal_session_id(state: dict[str, Any], now: float) -> str | None:
+ """Stable id for the terminal session, shared by every hogli call made in it.
+
+ The session leader (the login shell, or the harness that spawned the shell) outlives
+ each hogli process. Where ``/proc`` gives the leader start time cheaply, every call
+ checks it, so a recycled leader pid gets a new id. Elsewhere the cache in *state*
+ keeps the ``ps`` call off most invocations.
+ """
+ try:
+ leader = os.getsid(0)
+ except Exception:
+ return None
+ started = _proc_start_time(leader)
+ cache = state.get("terminal_sessions")
+ cache = cache if isinstance(cache, dict) else {}
+ cached = cache.get(str(leader))
+ if (
+ started is None
+ and isinstance(cached, dict)
+ and now - float(cached.get("seen", 0)) < _TERMINAL_SESSION_TTL_SECONDS
+ ):
+ session_id = str(cached.get("id"))
+ else:
+ started = started or _ps_start_time(leader)
+ if started is None:
+ return None
+ digest = hashlib.sha256(f"{socket.gethostname()}|{leader}|{started}".encode()).hexdigest()
+ session_id = f"term-{digest[:16]}"
+ cache[str(leader)] = {"id": session_id, "seen": now}
+ newest = sorted(cache.items(), key=lambda item: float(item[1].get("seen", 0)), reverse=True)
+ state["terminal_sessions"] = dict(newest[:_MAX_CACHED_TERMINAL_SESSIONS])
+ return session_id
+
+
+def _agent_session_id(state: dict[str, Any]) -> str | None:
+ for var in _AGENT_SESSION_ENV_VARS:
+ value = os.environ.get(var, "").strip()
+ if value:
+ salt = state.get("session_salt")
+ if not isinstance(salt, str) or not salt:
+ salt = secrets.token_hex(16)
+ state["session_salt"] = salt
+ digest = hashlib.sha256(f"{salt}|{value}".encode()).hexdigest()
+ return f"agent-{digest[:16]}"
+ return None
+
+
+def _session_properties(command: str | None) -> dict[str, Any]:
+ """Session, command kind, and rerun flag for this invocation.
+
+ Cached per process, so command_started, command_completed and ci_preflight_run
+ report the same values and the run is recorded once. A second record would make
+ the invocation count as its own rerun.
+ """
+ kind = classify_command(command, sys.argv[2:])
+ props: dict[str, Any] = {"command_kind": kind, "session_id": None, "session_id_source": None, "is_rerun": None}
+ try:
+ now = time.time()
+ with _state_lock():
+ state = _load_state()
+ session_id = _agent_session_id(state)
+ source = "agent" if session_id else None
+ if session_id is None:
+ session_id = _terminal_session_id(state, now)
+ source = "terminal"
+ if session_id is None:
+ return props
+ runs = _parse_runs(state.get("runs"))
+ props.update(
+ session_id=session_id, session_id_source=source, is_rerun=is_rerun(runs, session_id, kind, now)
+ )
+ recorded = _recent_runs([*runs, RecordedRun(session_id=session_id, kind=kind, at=now)], now)
+ state["runs"] = [[run.session_id, run.kind, run.at] for run in recorded]
+ _save_state(state)
+ except Exception:
+ pass
+ return props
+
+
+def _pr_number() -> int | None:
+ """PR number from the environment only, because a ``gh`` call on every command is too slow."""
+ match = _GITHUB_PULL_REF.match(os.environ.get("GITHUB_REF", ""))
+ if match:
+ return int(match.group(1))
+ for var in _PR_NUMBER_ENV_VARS:
+ value = os.environ.get(var, "").strip()
+ if value.isdigit():
+ return int(value)
+ return None
+
+
def _posthog_telemetry_properties(command: str | None = None) -> dict[str, Any]:
# Agent-driven traffic (e.g. skills running metabase:query) otherwise
# swamps human usage stats.
@@ -237,6 +506,8 @@ def _posthog_telemetry_properties(command: str | None = None) -> dict[str, Any]:
"is_posthog_dev": _is_posthog_dev(),
"process_manager": _infer_process_manager(command),
"git_branch": _git_branch(),
+ "pr_number": _pr_number(),
+ **_session_properties(command),
**_repo_commit_properties(),
}
diff --git a/tools/hogli-commands/hogli_commands/test_runner.py b/tools/hogli-commands/hogli_commands/test_runner.py
index 248447104afb..217e673e0141 100644
--- a/tools/hogli-commands/hogli_commands/test_runner.py
+++ b/tools/hogli-commands/hogli_commands/test_runner.py
@@ -565,6 +565,14 @@ def _detect_directory(dir_path: str) -> TestRunConfig:
)
+def runs_on_playwright(file_path: str) -> bool:
+ """Whether `hogli test <file_path>` hands the path to Playwright, resolved from the current directory."""
+ try:
+ return detect_test_type(_resolve_to_repo_relative(file_path)).test_type == "playwright"
+ except click.UsageError:
+ return False
+
+
def detect_test_type(file_path: str) -> TestRunConfig:
"""Detect the test type from a file or directory path and return run configuration.
diff --git a/tools/hogli-commands/hogli_commands/tests/test_commands.py b/tools/hogli-commands/hogli_commands/tests/test_commands.py
index 2bdaebf791c2..845c65c068a9 100644
--- a/tools/hogli-commands/hogli_commands/tests/test_commands.py
+++ b/tools/hogli-commands/hogli_commands/tests/test_commands.py
@@ -4,14 +4,17 @@ from __future__ import annotations
import json
import time
+import fcntl
import pytest
from unittest.mock import patch
+from hogli.manifest import REPO_ROOT
from hogli_commands.telemetry_props import (
_AGENT_ENV_MARKERS,
_DEVBOX_ENV_MARKERS,
_STANDARD_AGENT_ENV_VARS,
+ RecordedRun,
_detect_actor,
_detect_agent,
_detect_environment,
@@ -19,6 +22,9 @@ from hogli_commands.telemetry_props import (
_is_posthog_dev,
_repo_commit,
_repo_commit_properties,
+ _session_properties,
+ classify_command,
+ is_rerun,
)
@@ -201,3 +207,122 @@ class TestIsPosthogDev:
assert _is_posthog_dev() is True
mock_email.assert_called_once()
assert json.loads(_config_dir.read_text())["is_posthog_org_member"] is True
+
+
+class TestClassifyCommand:
+ @pytest.mark.parametrize(
+ ("command", "argv", "expected"),
+ [
+ ("ci:preflight", [], "verify-preflight"),
+ ("test:e2e", [], "verify-e2e"),
+ ("test", ["playwright/e2e/insights.spec.ts"], "verify-e2e"),
+ ("test", ["posthog/api/test/test_team.py"], "verify-test"),
+ ("test", ["posthog/api/test/test_playwright_setup.py"], "verify-test"),
+ ("test:python", [], "verify-test"),
+ ("desktop:test", [], "verify-test"),
+ ("test:quarantine", [], "other"),
+ ("desktop:typecheck", [], "verify-typecheck"),
+ ("lint", [], "verify-lint"),
+ ("lint:workflows", [], "verify-lint"),
+ ("format:python", [], "verify-lint"),
+ ("product:lint", [], "verify-lint"),
+ ("product:lint:owners", [], "verify-lint"),
+ ("desktop:lint:fix", [], "verify-lint"),
+ ("tool:ruff", [], "verify-lint"),
+ ("build:openapi", [], "build"),
+ ("phrocs:build", [], "build"),
+ ("start", [], "run-stack"),
+ ("start:backend", [], "run-stack"),
+ ("up", ["-d"], "run-stack"),
+ ("docker:services:up", [], "run-stack"),
+ ("devbox:start", [], "devbox"),
+ ("metabase:query", [], "other"),
+ (None, [], "other"),
+ ],
+ )
+ def test_classification(self, command, argv, expected) -> None:
+ assert classify_command(command, argv) == expected
+
+ def test_a_spec_named_from_inside_the_playwright_directory_is_e2e(self, monkeypatch) -> None:
+ monkeypatch.chdir(REPO_ROOT / "playwright")
+ assert classify_command("test", ["e2e/insights.spec.ts"]) == "verify-e2e"
+
+
+class TestIsRerun:
+ NOW = 1_000_000.0
+
+ @pytest.mark.parametrize(
+ ("runs", "expected"),
+ [
+ ([], False),
+ ([RecordedRun(session_id="s1", kind="verify-test", at=NOW - 60)], True),
+ ([RecordedRun(session_id="s1", kind="verify-test", at=NOW - 30 * 60)], True),
+ ([RecordedRun(session_id="s1", kind="verify-test", at=NOW - 30 * 60 - 1)], False),
+ ([RecordedRun(session_id="s2", kind="verify-test", at=NOW - 60)], False),
+ ([RecordedRun(session_id="s1", kind="verify-lint", at=NOW - 60)], False),
+ ([RecordedRun(session_id="s1", kind="verify-test", at=NOW + 60)], False),
+ ],
+ ids=[
+ "first_run",
+ "same_session_same_kind",
+ "window_edge_inclusive",
+ "outside_window",
+ "other_session",
+ "other_kind",
+ "clock_skew_future_entry",
+ ],
+ )
+ def test_decision(self, runs, expected) -> None:
+ assert is_rerun(runs, "s1", "verify-test", self.NOW) is expected
+
+
+class TestSessionProperties:
+ @pytest.fixture(autouse=True)
+ def _isolated_state(self, monkeypatch, tmp_path):
+ monkeypatch.setattr("hogli_commands.telemetry_props._TELEMETRY_STATE_PATH", tmp_path / "state.json")
+ monkeypatch.setenv("CLAUDE_CODE_SESSION_ID", "sess-1")
+ for var in ("HOGLI_SESSION_ID", "POSTHOG_TASK_RUN_ID"):
+ monkeypatch.delenv(var, raising=False)
+ monkeypatch.setattr("sys.argv", ["hogli", "lint"])
+ _session_properties.cache_clear()
+ yield
+ _session_properties.cache_clear()
+
+ def test_next_process_in_session_is_a_rerun_but_repeated_hook_calls_are_not(self) -> None:
+ assert _session_properties("lint")["is_rerun"] is False
+ assert _session_properties("lint")["is_rerun"] is False
+ _session_properties.cache_clear()
+ rerun = _session_properties("lint")
+ assert rerun == {
+ "command_kind": "verify-lint",
+ "session_id": rerun["session_id"],
+ "session_id_source": "agent",
+ "is_rerun": True,
+ }
+ assert rerun["session_id"].startswith("agent-")
+ assert "sess-1" not in rerun["session_id"]
+
+ def test_corrupt_state_file_does_not_raise(self, tmp_path) -> None:
+ (tmp_path / "state.json").write_text('{"runs": [["only-two", 1], "junk"], "terminal_sessions": 3}')
+ assert _session_properties("lint")["is_rerun"] is False
+
+ def test_held_state_lock_does_not_block_the_command(self, tmp_path) -> None:
+ with (tmp_path / "state.json.lock").open("a") as holder:
+ fcntl.flock(holder, fcntl.LOCK_EX)
+ assert _session_properties("lint")["is_rerun"] is False
+ fcntl.flock(holder, fcntl.LOCK_UN)
+ _session_properties.cache_clear()
+ assert _session_properties("lint")["is_rerun"] is True
+
+ def test_recycled_leader_pid_gets_a_new_terminal_id(self, monkeypatch) -> None:
+ for var in ("CLAUDE_CODE_SESSION_ID", "CODEX_THREAD_ID"):
+ monkeypatch.delenv(var, raising=False)
+ monkeypatch.setattr("os.getsid", lambda _pid: 4242)
+ monkeypatch.setattr("hogli_commands.telemetry_props._proc_start_time", lambda _pid: "1000")
+ first = _session_properties("lint")["session_id"]
+ _session_properties.cache_clear()
+ monkeypatch.setattr("hogli_commands.telemetry_props._proc_start_time", lambda _pid: "2000")
+ second = _session_properties("lint")
+ assert first is not None and first.startswith("term-")
+ assert second["session_id"] != first
+ assert second["is_rerun"] is False