fix(plugins): count installs once, and re-resolve the email when the key changes

code.install counted upgrades and repeat sessions. Session start records install
whenever is_first_run() is true, and that only checked whether
telemetry-identity.json exists. Recording install does not create that file —
only the first successful flush does. So install fired for every 0.2.x user on
their first 0.3.x session (0.2.x never wrote the file, and the data directory
survives the upgrade), again for any session starting before that first flush
finished, and — this is the part that makes it unbounded rather than a race —
on every single session, forever, for anyone whose flush never succeeds. An
offline or firewalled user reported a new install every time they opened an
editor, which is exactly the population hardest to see in the data.

A dedicated install-state.json is now claimed with O_CREAT|O_EXCL at the moment
install is recorded, so two sessions starting together cannot both win, and the
marker is not coupled to identity. Deliberately not the identity file: writing
that from a recording process would race the sender, which writes it during
resolve_distinct_id, and overloading it is what caused this.

Upgrade detection keys on the data directory already having content. A fresh
install has an empty one; anything else predates this session. That is a firmer
predicate than looking for 0.2.x's venv/ and requirements.txt, which is a guess
about files another part of the plugin may or may not have written and only ever
works for this one upgrade. The version is stored in the marker so later changes
record code.upgrade with a real from_version.

A cached email outlived an API key change. resolve_distinct_id kept the first
email it resolved and never looked again, so switching to a key from another
account kept attributing events to the previous one. It now stores a fingerprint
of the key the email came from and re-resolves when the current key differs, and
falls back to the anonymous id when no key is configured rather than continuing
to attribute to an account it cannot verify.

The dangerous part is the alias. resolve_distinct_id's second return value
becomes a PostHog $identify with $anon_distinct_id, and aliasing one account
email to another merges two real person profiles irreversibly. The re-resolve
path returns no alias; aliasing runs anonymous to email only, and never
email to email.

One existing test asserted that is_first_run flips when the identity file is
written, which is the defect itself. Rewritten, along with coverage for atomic
claiming, upgrade detection and version changes.

Claude-Session: https://claude.ai/code/session_01C7tEmH86HAr7GoAAKCEHZb

integrations/agent-plugin-core/python/hook_runner.py

@@ -305,8 +305,19 @@ def run(
             return 0
 
         if args.action == "session-start":
-            if telemetry.is_first_run():
+            # Claims the marker atomically and says which event to record, so a
+            # second session starting alongside this one cannot record it too.
+            first_event = telemetry.claim_install()
+            if first_event == "install":
                 telemetry.record("install")
+            elif first_event == "upgrade":
+                # First run after a build that never wrote the marker; the
+                # predecessor version was never recorded anywhere.
+                telemetry.record("upgrade", from_version="pre-0.3")
+            else:
+                previous = telemetry.claim_version_change()
+                if previous:
+                    telemetry.record("upgrade", from_version=previous)
             recovered = recover_pending_handoffs()
             record_session_start(store, hook_input)
             if recovered:

integrations/agent-plugin-core/python/telemetry.py

@@ -206,9 +206,92 @@ def anonymous_id(identity: dict[str, str] | None = None) -> str:
     return created
 
 
+def _install_state_path() -> Path:
+    return memory_core.data_dir() / "install-state.json"
+
+
 def is_first_run() -> bool:
-    """Whether this machine has never recorded a plugin event before."""
-    return not _identity_path().exists()
+    """Whether install has never been recorded on this machine.
+
+    Deliberately NOT the identity file. That file is only written by a
+    successful flush, so an offline or firewalled user recorded code.install on
+    every single session, forever — and every 0.2.x user recorded one on their
+    first 0.3.x session because 0.2.x never wrote it at all.
+    """
+    return not _install_state_path().exists()
+
+
+def claim_install() -> str | None:
+    """Claim the one install/upgrade record for this machine, atomically.
+
+    Returns the event to record ("install" or "upgrade"), or None if another
+    session already claimed it. O_CREAT|O_EXCL so two sessions starting together
+    cannot both win.
+    """
+    path = _install_state_path()
+    # A fresh install has an empty data directory. Anything already there —
+    # a 0.2.x venv, an evidence db, a spool — means this is an upgrade. Read
+    # before the marker is created, since creating it would itself be content.
+    upgrading = _data_dir_has_content()
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        handle = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+    except FileExistsError:
+        return None
+    except OSError:
+        return None
+    try:
+        with os.fdopen(handle, "w", encoding="utf-8") as stream:
+            json.dump(
+                {
+                    "plugin_version": memory_core.PLUGIN_VERSION,
+                    "installed_at": memory_core.utc_now(),
+                    "upgraded": upgrading,
+                },
+                stream,
+            )
+    except OSError:
+        pass
+    return "upgrade" if upgrading else "install"
+
+
+def _data_dir_has_content() -> bool:
+    """Whether anything predates this session in the plugin data directory."""
+    try:
+        for entry in memory_core.data_dir().iterdir():
+            if entry.name != "install-state.json":
+                return True
+    except OSError:
+        pass
+    return False
+
+
+def claim_version_change() -> str | None:
+    """Return the previously recorded version if it differs, updating the marker.
+
+    Only meaningful once the marker exists — the first transition into 0.3.x has
+    no recorded predecessor and reports "pre-0.3" instead. Claiming by rewriting
+    the marker means the next session sees no change and records nothing.
+    """
+    path = _install_state_path()
+    try:
+        state = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(state, dict):
+        return None
+    previous = str(state.get("plugin_version") or "")
+    if not previous or previous == memory_core.PLUGIN_VERSION:
+        return None
+    state["plugin_version"] = memory_core.PLUGIN_VERSION
+    state["upgraded_at"] = memory_core.utc_now()
+    try:
+        temporary = path.with_suffix(f".{os.getpid()}.tmp")
+        temporary.write_text(json.dumps(state), encoding="utf-8")
+        temporary.replace(path)
+    except OSError:
+        return None
+    return previous
 
 
 def record(
@@ -468,21 +551,39 @@ def _post(payload: dict[str, Any], url: str) -> bool:
 
 
 def resolve_distinct_id() -> tuple[str, str]:
-    """Return the PostHog distinct id and the anonymous id it replaced, if any."""
+    """Return the PostHog distinct id and the anonymous id it replaced, if any.
+
+    The second value becomes a PostHog $identify alias. It is ONLY ever an
+    anonymous id: aliasing one account email to another merges two real person
+    profiles and cannot be undone, so a key that now belongs to a different
+    account re-resolves with no alias.
+    """
     identity = _read_identity()
-    email = identity.get("email", "")
-    if email:
-        return email, ""
     key = memory_core.api_key()
+    fingerprint = _digest(key) if key else ""
+    email = identity.get("email", "")
+
+    if email and identity.get("key_fingerprint", "") == fingerprint and fingerprint:
+        return email, ""
+
     if not key:
-        return anonymous_id(identity), ""
-    email = _resolve_email(key)
-    if not email:
-        return anonymous_id(identity), ""
-    previous = identity.get("anonymous_id", "")
-    identity["email"] = email
+        # No key to verify the account with; do not keep attributing to it.
+        if email:
+            identity.pop("email", None)
+            identity.pop("key_fingerprint", None)
             _write_identity(identity)
-    return email, previous
+        return anonymous_id(identity), ""
+
+    resolved = _resolve_email(key)
+    if not resolved:
+        return (email, "") if email else (anonymous_id(identity), "")
+
+    # Alias only when going anonymous -> email for the first time.
+    previous = "" if email else identity.get("anonymous_id", "")
+    identity["email"] = resolved
+    identity["key_fingerprint"] = fingerprint
+    _write_identity(identity)
+    return resolved, previous
 
 
 def flush() -> int:

integrations/antigravity-plugin/core/hook_runner.py

@@ -305,8 +305,19 @@ def run(
             return 0
 
         if args.action == "session-start":
-            if telemetry.is_first_run():
+            # Claims the marker atomically and says which event to record, so a
+            # second session starting alongside this one cannot record it too.
+            first_event = telemetry.claim_install()
+            if first_event == "install":
                 telemetry.record("install")
+            elif first_event == "upgrade":
+                # First run after a build that never wrote the marker; the
+                # predecessor version was never recorded anywhere.
+                telemetry.record("upgrade", from_version="pre-0.3")
+            else:
+                previous = telemetry.claim_version_change()
+                if previous:
+                    telemetry.record("upgrade", from_version=previous)
             recovered = recover_pending_handoffs()
             record_session_start(store, hook_input)
             if recovered:

integrations/antigravity-plugin/core/telemetry.py

@@ -206,9 +206,92 @@ def anonymous_id(identity: dict[str, str] | None = None) -> str:
     return created
 
 
+def _install_state_path() -> Path:
+    return memory_core.data_dir() / "install-state.json"
+
+
 def is_first_run() -> bool:
-    """Whether this machine has never recorded a plugin event before."""
-    return not _identity_path().exists()
+    """Whether install has never been recorded on this machine.
+
+    Deliberately NOT the identity file. That file is only written by a
+    successful flush, so an offline or firewalled user recorded code.install on
+    every single session, forever — and every 0.2.x user recorded one on their
+    first 0.3.x session because 0.2.x never wrote it at all.
+    """
+    return not _install_state_path().exists()
+
+
+def claim_install() -> str | None:
+    """Claim the one install/upgrade record for this machine, atomically.
+
+    Returns the event to record ("install" or "upgrade"), or None if another
+    session already claimed it. O_CREAT|O_EXCL so two sessions starting together
+    cannot both win.
+    """
+    path = _install_state_path()
+    # A fresh install has an empty data directory. Anything already there —
+    # a 0.2.x venv, an evidence db, a spool — means this is an upgrade. Read
+    # before the marker is created, since creating it would itself be content.
+    upgrading = _data_dir_has_content()
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        handle = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+    except FileExistsError:
+        return None
+    except OSError:
+        return None
+    try:
+        with os.fdopen(handle, "w", encoding="utf-8") as stream:
+            json.dump(
+                {
+                    "plugin_version": memory_core.PLUGIN_VERSION,
+                    "installed_at": memory_core.utc_now(),
+                    "upgraded": upgrading,
+                },
+                stream,
+            )
+    except OSError:
+        pass
+    return "upgrade" if upgrading else "install"
+
+
+def _data_dir_has_content() -> bool:
+    """Whether anything predates this session in the plugin data directory."""
+    try:
+        for entry in memory_core.data_dir().iterdir():
+            if entry.name != "install-state.json":
+                return True
+    except OSError:
+        pass
+    return False
+
+
+def claim_version_change() -> str | None:
+    """Return the previously recorded version if it differs, updating the marker.
+
+    Only meaningful once the marker exists — the first transition into 0.3.x has
+    no recorded predecessor and reports "pre-0.3" instead. Claiming by rewriting
+    the marker means the next session sees no change and records nothing.
+    """
+    path = _install_state_path()
+    try:
+        state = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(state, dict):
+        return None
+    previous = str(state.get("plugin_version") or "")
+    if not previous or previous == memory_core.PLUGIN_VERSION:
+        return None
+    state["plugin_version"] = memory_core.PLUGIN_VERSION
+    state["upgraded_at"] = memory_core.utc_now()
+    try:
+        temporary = path.with_suffix(f".{os.getpid()}.tmp")
+        temporary.write_text(json.dumps(state), encoding="utf-8")
+        temporary.replace(path)
+    except OSError:
+        return None
+    return previous
 
 
 def record(
@@ -468,21 +551,39 @@ def _post(payload: dict[str, Any], url: str) -> bool:
 
 
 def resolve_distinct_id() -> tuple[str, str]:
-    """Return the PostHog distinct id and the anonymous id it replaced, if any."""
+    """Return the PostHog distinct id and the anonymous id it replaced, if any.
+
+    The second value becomes a PostHog $identify alias. It is ONLY ever an
+    anonymous id: aliasing one account email to another merges two real person
+    profiles and cannot be undone, so a key that now belongs to a different
+    account re-resolves with no alias.
+    """
     identity = _read_identity()
-    email = identity.get("email", "")
-    if email:
-        return email, ""
     key = memory_core.api_key()
+    fingerprint = _digest(key) if key else ""
+    email = identity.get("email", "")
+
+    if email and identity.get("key_fingerprint", "") == fingerprint and fingerprint:
+        return email, ""
+
     if not key:
-        return anonymous_id(identity), ""
-    email = _resolve_email(key)
-    if not email:
-        return anonymous_id(identity), ""
-    previous = identity.get("anonymous_id", "")
-    identity["email"] = email
+        # No key to verify the account with; do not keep attributing to it.
+        if email:
+            identity.pop("email", None)
+            identity.pop("key_fingerprint", None)
             _write_identity(identity)
-    return email, previous
+        return anonymous_id(identity), ""
+
+    resolved = _resolve_email(key)
+    if not resolved:
+        return (email, "") if email else (anonymous_id(identity), "")
+
+    # Alias only when going anonymous -> email for the first time.
+    previous = "" if email else identity.get("anonymous_id", "")
+    identity["email"] = resolved
+    identity["key_fingerprint"] = fingerprint
+    _write_identity(identity)
+    return resolved, previous
 
 
 def flush() -> int:

integrations/claude-code-plugin/core/hook_runner.py

@@ -305,8 +305,19 @@ def run(
             return 0
 
         if args.action == "session-start":
-            if telemetry.is_first_run():
+            # Claims the marker atomically and says which event to record, so a
+            # second session starting alongside this one cannot record it too.
+            first_event = telemetry.claim_install()
+            if first_event == "install":
                 telemetry.record("install")
+            elif first_event == "upgrade":
+                # First run after a build that never wrote the marker; the
+                # predecessor version was never recorded anywhere.
+                telemetry.record("upgrade", from_version="pre-0.3")
+            else:
+                previous = telemetry.claim_version_change()
+                if previous:
+                    telemetry.record("upgrade", from_version=previous)
             recovered = recover_pending_handoffs()
             record_session_start(store, hook_input)
             if recovered:

integrations/claude-code-plugin/core/telemetry.py

@@ -206,9 +206,92 @@ def anonymous_id(identity: dict[str, str] | None = None) -> str:
     return created
 
 
+def _install_state_path() -> Path:
+    return memory_core.data_dir() / "install-state.json"
+
+
 def is_first_run() -> bool:
-    """Whether this machine has never recorded a plugin event before."""
-    return not _identity_path().exists()
+    """Whether install has never been recorded on this machine.
+
+    Deliberately NOT the identity file. That file is only written by a
+    successful flush, so an offline or firewalled user recorded code.install on
+    every single session, forever — and every 0.2.x user recorded one on their
+    first 0.3.x session because 0.2.x never wrote it at all.
+    """
+    return not _install_state_path().exists()
+
+
+def claim_install() -> str | None:
+    """Claim the one install/upgrade record for this machine, atomically.
+
+    Returns the event to record ("install" or "upgrade"), or None if another
+    session already claimed it. O_CREAT|O_EXCL so two sessions starting together
+    cannot both win.
+    """
+    path = _install_state_path()
+    # A fresh install has an empty data directory. Anything already there —
+    # a 0.2.x venv, an evidence db, a spool — means this is an upgrade. Read
+    # before the marker is created, since creating it would itself be content.
+    upgrading = _data_dir_has_content()
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        handle = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+    except FileExistsError:
+        return None
+    except OSError:
+        return None
+    try:
+        with os.fdopen(handle, "w", encoding="utf-8") as stream:
+            json.dump(
+                {
+                    "plugin_version": memory_core.PLUGIN_VERSION,
+                    "installed_at": memory_core.utc_now(),
+                    "upgraded": upgrading,
+                },
+                stream,
+            )
+    except OSError:
+        pass
+    return "upgrade" if upgrading else "install"
+
+
+def _data_dir_has_content() -> bool:
+    """Whether anything predates this session in the plugin data directory."""
+    try:
+        for entry in memory_core.data_dir().iterdir():
+            if entry.name != "install-state.json":
+                return True
+    except OSError:
+        pass
+    return False
+
+
+def claim_version_change() -> str | None:
+    """Return the previously recorded version if it differs, updating the marker.
+
+    Only meaningful once the marker exists — the first transition into 0.3.x has
+    no recorded predecessor and reports "pre-0.3" instead. Claiming by rewriting
+    the marker means the next session sees no change and records nothing.
+    """
+    path = _install_state_path()
+    try:
+        state = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(state, dict):
+        return None
+    previous = str(state.get("plugin_version") or "")
+    if not previous or previous == memory_core.PLUGIN_VERSION:
+        return None
+    state["plugin_version"] = memory_core.PLUGIN_VERSION
+    state["upgraded_at"] = memory_core.utc_now()
+    try:
+        temporary = path.with_suffix(f".{os.getpid()}.tmp")
+        temporary.write_text(json.dumps(state), encoding="utf-8")
+        temporary.replace(path)
+    except OSError:
+        return None
+    return previous
 
 
 def record(
@@ -468,21 +551,39 @@ def _post(payload: dict[str, Any], url: str) -> bool:
 
 
 def resolve_distinct_id() -> tuple[str, str]:
-    """Return the PostHog distinct id and the anonymous id it replaced, if any."""
+    """Return the PostHog distinct id and the anonymous id it replaced, if any.
+
+    The second value becomes a PostHog $identify alias. It is ONLY ever an
+    anonymous id: aliasing one account email to another merges two real person
+    profiles and cannot be undone, so a key that now belongs to a different
+    account re-resolves with no alias.
+    """
     identity = _read_identity()
-    email = identity.get("email", "")
-    if email:
-        return email, ""
     key = memory_core.api_key()
+    fingerprint = _digest(key) if key else ""
+    email = identity.get("email", "")
+
+    if email and identity.get("key_fingerprint", "") == fingerprint and fingerprint:
+        return email, ""
+
     if not key:
-        return anonymous_id(identity), ""
-    email = _resolve_email(key)
-    if not email:
-        return anonymous_id(identity), ""
-    previous = identity.get("anonymous_id", "")
-    identity["email"] = email
+        # No key to verify the account with; do not keep attributing to it.
+        if email:
+            identity.pop("email", None)
+            identity.pop("key_fingerprint", None)
             _write_identity(identity)
-    return email, previous
+        return anonymous_id(identity), ""
+
+    resolved = _resolve_email(key)
+    if not resolved:
+        return (email, "") if email else (anonymous_id(identity), "")
+
+    # Alias only when going anonymous -> email for the first time.
+    previous = "" if email else identity.get("anonymous_id", "")
+    identity["email"] = resolved
+    identity["key_fingerprint"] = fingerprint
+    _write_identity(identity)
+    return resolved, previous
 
 
 def flush() -> int:

integrations/claude-code-plugin/tests/test_telemetry.py

@@ -265,12 +265,47 @@ def test_an_unresolvable_key_falls_back_to_the_anonymous_id(isolated_env, monkey
     assert telemetry.resolve_distinct_id()[0].startswith("code-anon-")
 
 
-def test_is_first_run_flips_after_the_first_identity_write(isolated_env):
+def test_first_run_is_not_flipped_by_writing_the_identity_file(isolated_env):
+    """The identity file is written by a successful flush, not by recording.
+
+    Keying first-run off it meant an offline user recorded code.install on every
+    session forever, and every 0.2.x user recorded one on their first 0.3.x run.
+    """
     assert telemetry.is_first_run()
     telemetry.anonymous_id()
+    assert telemetry.is_first_run()
+
+
+def test_claiming_install_ends_first_run(isolated_env):
+    assert telemetry.claim_install() == "install"
     assert not telemetry.is_first_run()
 
 
+def test_install_can_only_be_claimed_once(isolated_env):
+    """Two sessions starting together must not both record an install."""
+    assert telemetry.claim_install() == "install"
+    assert telemetry.claim_install() is None
+
+
+def test_a_populated_data_dir_reads_as_an_upgrade(isolated_env):
+    """A fresh install has an empty data directory; anything else predates it."""
+    data_dir = memory_core.data_dir()
+    data_dir.mkdir(parents=True, exist_ok=True)
+    (data_dir / "requirements.txt").write_text("mem0ai\n", encoding="utf-8")
+    assert telemetry.claim_install() == "upgrade"
+
+
+def test_a_version_change_is_claimed_once(isolated_env):
+    telemetry.claim_install()
+    state_path = memory_core.data_dir() / "install-state.json"
+    state = json.loads(state_path.read_text())
+    state["plugin_version"] = "0.0.1-old"
+    state_path.write_text(json.dumps(state), encoding="utf-8")
+
+    assert telemetry.claim_version_change() == "0.0.1-old"
+    assert telemetry.claim_version_change() is None
+
+
 def test_spawn_flush_does_nothing_without_a_spool(isolated_env):
     with patch.object(telemetry.subprocess, "Popen") as popen:
         assert telemetry.spawn_flush() is False

integrations/codex-plugin/core/hook_runner.py

@@ -305,8 +305,19 @@ def run(
             return 0
 
         if args.action == "session-start":
-            if telemetry.is_first_run():
+            # Claims the marker atomically and says which event to record, so a
+            # second session starting alongside this one cannot record it too.
+            first_event = telemetry.claim_install()
+            if first_event == "install":
                 telemetry.record("install")
+            elif first_event == "upgrade":
+                # First run after a build that never wrote the marker; the
+                # predecessor version was never recorded anywhere.
+                telemetry.record("upgrade", from_version="pre-0.3")
+            else:
+                previous = telemetry.claim_version_change()
+                if previous:
+                    telemetry.record("upgrade", from_version=previous)
             recovered = recover_pending_handoffs()
             record_session_start(store, hook_input)
             if recovered:

integrations/codex-plugin/core/telemetry.py

@@ -206,9 +206,92 @@ def anonymous_id(identity: dict[str, str] | None = None) -> str:
     return created
 
 
+def _install_state_path() -> Path:
+    return memory_core.data_dir() / "install-state.json"
+
+
 def is_first_run() -> bool:
-    """Whether this machine has never recorded a plugin event before."""
-    return not _identity_path().exists()
+    """Whether install has never been recorded on this machine.
+
+    Deliberately NOT the identity file. That file is only written by a
+    successful flush, so an offline or firewalled user recorded code.install on
+    every single session, forever — and every 0.2.x user recorded one on their
+    first 0.3.x session because 0.2.x never wrote it at all.
+    """
+    return not _install_state_path().exists()
+
+
+def claim_install() -> str | None:
+    """Claim the one install/upgrade record for this machine, atomically.
+
+    Returns the event to record ("install" or "upgrade"), or None if another
+    session already claimed it. O_CREAT|O_EXCL so two sessions starting together
+    cannot both win.
+    """
+    path = _install_state_path()
+    # A fresh install has an empty data directory. Anything already there —
+    # a 0.2.x venv, an evidence db, a spool — means this is an upgrade. Read
+    # before the marker is created, since creating it would itself be content.
+    upgrading = _data_dir_has_content()
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        handle = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+    except FileExistsError:
+        return None
+    except OSError:
+        return None
+    try:
+        with os.fdopen(handle, "w", encoding="utf-8") as stream:
+            json.dump(
+                {
+                    "plugin_version": memory_core.PLUGIN_VERSION,
+                    "installed_at": memory_core.utc_now(),
+                    "upgraded": upgrading,
+                },
+                stream,
+            )
+    except OSError:
+        pass
+    return "upgrade" if upgrading else "install"
+
+
+def _data_dir_has_content() -> bool:
+    """Whether anything predates this session in the plugin data directory."""
+    try:
+        for entry in memory_core.data_dir().iterdir():
+            if entry.name != "install-state.json":
+                return True
+    except OSError:
+        pass
+    return False
+
+
+def claim_version_change() -> str | None:
+    """Return the previously recorded version if it differs, updating the marker.
+
+    Only meaningful once the marker exists — the first transition into 0.3.x has
+    no recorded predecessor and reports "pre-0.3" instead. Claiming by rewriting
+    the marker means the next session sees no change and records nothing.
+    """
+    path = _install_state_path()
+    try:
+        state = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(state, dict):
+        return None
+    previous = str(state.get("plugin_version") or "")
+    if not previous or previous == memory_core.PLUGIN_VERSION:
+        return None
+    state["plugin_version"] = memory_core.PLUGIN_VERSION
+    state["upgraded_at"] = memory_core.utc_now()
+    try:
+        temporary = path.with_suffix(f".{os.getpid()}.tmp")
+        temporary.write_text(json.dumps(state), encoding="utf-8")
+        temporary.replace(path)
+    except OSError:
+        return None
+    return previous
 
 
 def record(
@@ -468,21 +551,39 @@ def _post(payload: dict[str, Any], url: str) -> bool:
 
 
 def resolve_distinct_id() -> tuple[str, str]:
-    """Return the PostHog distinct id and the anonymous id it replaced, if any."""
+    """Return the PostHog distinct id and the anonymous id it replaced, if any.
+
+    The second value becomes a PostHog $identify alias. It is ONLY ever an
+    anonymous id: aliasing one account email to another merges two real person
+    profiles and cannot be undone, so a key that now belongs to a different
+    account re-resolves with no alias.
+    """
     identity = _read_identity()
-    email = identity.get("email", "")
-    if email:
-        return email, ""
     key = memory_core.api_key()
+    fingerprint = _digest(key) if key else ""
+    email = identity.get("email", "")
+
+    if email and identity.get("key_fingerprint", "") == fingerprint and fingerprint:
+        return email, ""
+
     if not key:
-        return anonymous_id(identity), ""
-    email = _resolve_email(key)
-    if not email:
-        return anonymous_id(identity), ""
-    previous = identity.get("anonymous_id", "")
-    identity["email"] = email
+        # No key to verify the account with; do not keep attributing to it.
+        if email:
+            identity.pop("email", None)
+            identity.pop("key_fingerprint", None)
             _write_identity(identity)
-    return email, previous
+        return anonymous_id(identity), ""
+
+    resolved = _resolve_email(key)
+    if not resolved:
+        return (email, "") if email else (anonymous_id(identity), "")
+
+    # Alias only when going anonymous -> email for the first time.
+    previous = "" if email else identity.get("anonymous_id", "")
+    identity["email"] = resolved
+    identity["key_fingerprint"] = fingerprint
+    _write_identity(identity)
+    return resolved, previous
 
 
 def flush() -> int:

integrations/cursor-plugin/core/hook_runner.py

@@ -305,8 +305,19 @@ def run(
             return 0
 
         if args.action == "session-start":
-            if telemetry.is_first_run():
+            # Claims the marker atomically and says which event to record, so a
+            # second session starting alongside this one cannot record it too.
+            first_event = telemetry.claim_install()
+            if first_event == "install":
                 telemetry.record("install")
+            elif first_event == "upgrade":
+                # First run after a build that never wrote the marker; the
+                # predecessor version was never recorded anywhere.
+                telemetry.record("upgrade", from_version="pre-0.3")
+            else:
+                previous = telemetry.claim_version_change()
+                if previous:
+                    telemetry.record("upgrade", from_version=previous)
             recovered = recover_pending_handoffs()
             record_session_start(store, hook_input)
             if recovered:

integrations/cursor-plugin/core/telemetry.py

@@ -206,9 +206,92 @@ def anonymous_id(identity: dict[str, str] | None = None) -> str:
     return created
 
 
+def _install_state_path() -> Path:
+    return memory_core.data_dir() / "install-state.json"
+
+
 def is_first_run() -> bool:
-    """Whether this machine has never recorded a plugin event before."""
-    return not _identity_path().exists()
+    """Whether install has never been recorded on this machine.
+
+    Deliberately NOT the identity file. That file is only written by a
+    successful flush, so an offline or firewalled user recorded code.install on
+    every single session, forever — and every 0.2.x user recorded one on their
+    first 0.3.x session because 0.2.x never wrote it at all.
+    """
+    return not _install_state_path().exists()
+
+
+def claim_install() -> str | None:
+    """Claim the one install/upgrade record for this machine, atomically.
+
+    Returns the event to record ("install" or "upgrade"), or None if another
+    session already claimed it. O_CREAT|O_EXCL so two sessions starting together
+    cannot both win.
+    """
+    path = _install_state_path()
+    # A fresh install has an empty data directory. Anything already there —
+    # a 0.2.x venv, an evidence db, a spool — means this is an upgrade. Read
+    # before the marker is created, since creating it would itself be content.
+    upgrading = _data_dir_has_content()
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        handle = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+    except FileExistsError:
+        return None
+    except OSError:
+        return None
+    try:
+        with os.fdopen(handle, "w", encoding="utf-8") as stream:
+            json.dump(
+                {
+                    "plugin_version": memory_core.PLUGIN_VERSION,
+                    "installed_at": memory_core.utc_now(),
+                    "upgraded": upgrading,
+                },
+                stream,
+            )
+    except OSError:
+        pass
+    return "upgrade" if upgrading else "install"
+
+
+def _data_dir_has_content() -> bool:
+    """Whether anything predates this session in the plugin data directory."""
+    try:
+        for entry in memory_core.data_dir().iterdir():
+            if entry.name != "install-state.json":
+                return True
+    except OSError:
+        pass
+    return False
+
+
+def claim_version_change() -> str | None:
+    """Return the previously recorded version if it differs, updating the marker.
+
+    Only meaningful once the marker exists — the first transition into 0.3.x has
+    no recorded predecessor and reports "pre-0.3" instead. Claiming by rewriting
+    the marker means the next session sees no change and records nothing.
+    """
+    path = _install_state_path()
+    try:
+        state = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(state, dict):
+        return None
+    previous = str(state.get("plugin_version") or "")
+    if not previous or previous == memory_core.PLUGIN_VERSION:
+        return None
+    state["plugin_version"] = memory_core.PLUGIN_VERSION
+    state["upgraded_at"] = memory_core.utc_now()
+    try:
+        temporary = path.with_suffix(f".{os.getpid()}.tmp")
+        temporary.write_text(json.dumps(state), encoding="utf-8")
+        temporary.replace(path)
+    except OSError:
+        return None
+    return previous
 
 
 def record(
@@ -468,21 +551,39 @@ def _post(payload: dict[str, Any], url: str) -> bool:
 
 
 def resolve_distinct_id() -> tuple[str, str]:
-    """Return the PostHog distinct id and the anonymous id it replaced, if any."""
+    """Return the PostHog distinct id and the anonymous id it replaced, if any.
+
+    The second value becomes a PostHog $identify alias. It is ONLY ever an
+    anonymous id: aliasing one account email to another merges two real person
+    profiles and cannot be undone, so a key that now belongs to a different
+    account re-resolves with no alias.
+    """
     identity = _read_identity()
-    email = identity.get("email", "")
-    if email:
-        return email, ""
     key = memory_core.api_key()
+    fingerprint = _digest(key) if key else ""
+    email = identity.get("email", "")
+
+    if email and identity.get("key_fingerprint", "") == fingerprint and fingerprint:
+        return email, ""
+
     if not key:
-        return anonymous_id(identity), ""
-    email = _resolve_email(key)
-    if not email:
-        return anonymous_id(identity), ""
-    previous = identity.get("anonymous_id", "")
-    identity["email"] = email
+        # No key to verify the account with; do not keep attributing to it.
+        if email:
+            identity.pop("email", None)
+            identity.pop("key_fingerprint", None)
             _write_identity(identity)
-    return email, previous
+        return anonymous_id(identity), ""
+
+    resolved = _resolve_email(key)
+    if not resolved:
+        return (email, "") if email else (anonymous_id(identity), "")
+
+    # Alias only when going anonymous -> email for the first time.
+    previous = "" if email else identity.get("anonymous_id", "")
+    identity["email"] = resolved
+    identity["key_fingerprint"] = fingerprint
+    _write_identity(identity)
+    return resolved, previous
 
 
 def flush() -> int:

integrations/kimi-plugin/core/hook_runner.py

@@ -305,8 +305,19 @@ def run(
             return 0
 
         if args.action == "session-start":
-            if telemetry.is_first_run():
+            # Claims the marker atomically and says which event to record, so a
+            # second session starting alongside this one cannot record it too.
+            first_event = telemetry.claim_install()
+            if first_event == "install":
                 telemetry.record("install")
+            elif first_event == "upgrade":
+                # First run after a build that never wrote the marker; the
+                # predecessor version was never recorded anywhere.
+                telemetry.record("upgrade", from_version="pre-0.3")
+            else:
+                previous = telemetry.claim_version_change()
+                if previous:
+                    telemetry.record("upgrade", from_version=previous)
             recovered = recover_pending_handoffs()
             record_session_start(store, hook_input)
             if recovered:

integrations/kimi-plugin/core/telemetry.py

@@ -206,9 +206,92 @@ def anonymous_id(identity: dict[str, str] | None = None) -> str:
     return created
 
 
+def _install_state_path() -> Path:
+    return memory_core.data_dir() / "install-state.json"
+
+
 def is_first_run() -> bool:
-    """Whether this machine has never recorded a plugin event before."""
-    return not _identity_path().exists()
+    """Whether install has never been recorded on this machine.
+
+    Deliberately NOT the identity file. That file is only written by a
+    successful flush, so an offline or firewalled user recorded code.install on
+    every single session, forever — and every 0.2.x user recorded one on their
+    first 0.3.x session because 0.2.x never wrote it at all.
+    """
+    return not _install_state_path().exists()
+
+
+def claim_install() -> str | None:
+    """Claim the one install/upgrade record for this machine, atomically.
+
+    Returns the event to record ("install" or "upgrade"), or None if another
+    session already claimed it. O_CREAT|O_EXCL so two sessions starting together
+    cannot both win.
+    """
+    path = _install_state_path()
+    # A fresh install has an empty data directory. Anything already there —
+    # a 0.2.x venv, an evidence db, a spool — means this is an upgrade. Read
+    # before the marker is created, since creating it would itself be content.
+    upgrading = _data_dir_has_content()
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        handle = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+    except FileExistsError:
+        return None
+    except OSError:
+        return None
+    try:
+        with os.fdopen(handle, "w", encoding="utf-8") as stream:
+            json.dump(
+                {
+                    "plugin_version": memory_core.PLUGIN_VERSION,
+                    "installed_at": memory_core.utc_now(),
+                    "upgraded": upgrading,
+                },
+                stream,
+            )
+    except OSError:
+        pass
+    return "upgrade" if upgrading else "install"
+
+
+def _data_dir_has_content() -> bool:
+    """Whether anything predates this session in the plugin data directory."""
+    try:
+        for entry in memory_core.data_dir().iterdir():
+            if entry.name != "install-state.json":
+                return True
+    except OSError:
+        pass
+    return False
+
+
+def claim_version_change() -> str | None:
+    """Return the previously recorded version if it differs, updating the marker.
+
+    Only meaningful once the marker exists — the first transition into 0.3.x has
+    no recorded predecessor and reports "pre-0.3" instead. Claiming by rewriting
+    the marker means the next session sees no change and records nothing.
+    """
+    path = _install_state_path()
+    try:
+        state = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(state, dict):
+        return None
+    previous = str(state.get("plugin_version") or "")
+    if not previous or previous == memory_core.PLUGIN_VERSION:
+        return None
+    state["plugin_version"] = memory_core.PLUGIN_VERSION
+    state["upgraded_at"] = memory_core.utc_now()
+    try:
+        temporary = path.with_suffix(f".{os.getpid()}.tmp")
+        temporary.write_text(json.dumps(state), encoding="utf-8")
+        temporary.replace(path)
+    except OSError:
+        return None
+    return previous
 
 
 def record(
@@ -468,21 +551,39 @@ def _post(payload: dict[str, Any], url: str) -> bool:
 
 
 def resolve_distinct_id() -> tuple[str, str]:
-    """Return the PostHog distinct id and the anonymous id it replaced, if any."""
+    """Return the PostHog distinct id and the anonymous id it replaced, if any.
+
+    The second value becomes a PostHog $identify alias. It is ONLY ever an
+    anonymous id: aliasing one account email to another merges two real person
+    profiles and cannot be undone, so a key that now belongs to a different
+    account re-resolves with no alias.
+    """
     identity = _read_identity()
-    email = identity.get("email", "")
-    if email:
-        return email, ""
     key = memory_core.api_key()
+    fingerprint = _digest(key) if key else ""
+    email = identity.get("email", "")
+
+    if email and identity.get("key_fingerprint", "") == fingerprint and fingerprint:
+        return email, ""
+
     if not key:
-        return anonymous_id(identity), ""
-    email = _resolve_email(key)
-    if not email:
-        return anonymous_id(identity), ""
-    previous = identity.get("anonymous_id", "")
-    identity["email"] = email
+        # No key to verify the account with; do not keep attributing to it.
+        if email:
+            identity.pop("email", None)
+            identity.pop("key_fingerprint", None)
             _write_identity(identity)
-    return email, previous
+        return anonymous_id(identity), ""
+
+    resolved = _resolve_email(key)
+    if not resolved:
+        return (email, "") if email else (anonymous_id(identity), "")
+
+    # Alias only when going anonymous -> email for the first time.
+    previous = "" if email else identity.get("anonymous_id", "")
+    identity["email"] = resolved
+    identity["key_fingerprint"] = fingerprint
+    _write_identity(identity)
+    return resolved, previous
 
 
 def flush() -> int:

integrations/mem0-agent-plugin/core/telemetry.py

@@ -206,9 +206,92 @@ def anonymous_id(identity: dict[str, str] | None = None) -> str:
     return created
 
 
+def _install_state_path() -> Path:
+    return memory_core.data_dir() / "install-state.json"
+
+
 def is_first_run() -> bool:
-    """Whether this machine has never recorded a plugin event before."""
-    return not _identity_path().exists()
+    """Whether install has never been recorded on this machine.
+
+    Deliberately NOT the identity file. That file is only written by a
+    successful flush, so an offline or firewalled user recorded code.install on
+    every single session, forever — and every 0.2.x user recorded one on their
+    first 0.3.x session because 0.2.x never wrote it at all.
+    """
+    return not _install_state_path().exists()
+
+
+def claim_install() -> str | None:
+    """Claim the one install/upgrade record for this machine, atomically.
+
+    Returns the event to record ("install" or "upgrade"), or None if another
+    session already claimed it. O_CREAT|O_EXCL so two sessions starting together
+    cannot both win.
+    """
+    path = _install_state_path()
+    # A fresh install has an empty data directory. Anything already there —
+    # a 0.2.x venv, an evidence db, a spool — means this is an upgrade. Read
+    # before the marker is created, since creating it would itself be content.
+    upgrading = _data_dir_has_content()
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        handle = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+    except FileExistsError:
+        return None
+    except OSError:
+        return None
+    try:
+        with os.fdopen(handle, "w", encoding="utf-8") as stream:
+            json.dump(
+                {
+                    "plugin_version": memory_core.PLUGIN_VERSION,
+                    "installed_at": memory_core.utc_now(),
+                    "upgraded": upgrading,
+                },
+                stream,
+            )
+    except OSError:
+        pass
+    return "upgrade" if upgrading else "install"
+
+
+def _data_dir_has_content() -> bool:
+    """Whether anything predates this session in the plugin data directory."""
+    try:
+        for entry in memory_core.data_dir().iterdir():
+            if entry.name != "install-state.json":
+                return True
+    except OSError:
+        pass
+    return False
+
+
+def claim_version_change() -> str | None:
+    """Return the previously recorded version if it differs, updating the marker.
+
+    Only meaningful once the marker exists — the first transition into 0.3.x has
+    no recorded predecessor and reports "pre-0.3" instead. Claiming by rewriting
+    the marker means the next session sees no change and records nothing.
+    """
+    path = _install_state_path()
+    try:
+        state = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(state, dict):
+        return None
+    previous = str(state.get("plugin_version") or "")
+    if not previous or previous == memory_core.PLUGIN_VERSION:
+        return None
+    state["plugin_version"] = memory_core.PLUGIN_VERSION
+    state["upgraded_at"] = memory_core.utc_now()
+    try:
+        temporary = path.with_suffix(f".{os.getpid()}.tmp")
+        temporary.write_text(json.dumps(state), encoding="utf-8")
+        temporary.replace(path)
+    except OSError:
+        return None
+    return previous
 
 
 def record(
@@ -468,21 +551,39 @@ def _post(payload: dict[str, Any], url: str) -> bool:
 
 
 def resolve_distinct_id() -> tuple[str, str]:
-    """Return the PostHog distinct id and the anonymous id it replaced, if any."""
+    """Return the PostHog distinct id and the anonymous id it replaced, if any.
+
+    The second value becomes a PostHog $identify alias. It is ONLY ever an
+    anonymous id: aliasing one account email to another merges two real person
+    profiles and cannot be undone, so a key that now belongs to a different
+    account re-resolves with no alias.
+    """
     identity = _read_identity()
-    email = identity.get("email", "")
-    if email:
-        return email, ""
     key = memory_core.api_key()
+    fingerprint = _digest(key) if key else ""
+    email = identity.get("email", "")
+
+    if email and identity.get("key_fingerprint", "") == fingerprint and fingerprint:
+        return email, ""
+
     if not key:
-        return anonymous_id(identity), ""
-    email = _resolve_email(key)
-    if not email:
-        return anonymous_id(identity), ""
-    previous = identity.get("anonymous_id", "")
-    identity["email"] = email
+        # No key to verify the account with; do not keep attributing to it.
+        if email:
+            identity.pop("email", None)
+            identity.pop("key_fingerprint", None)
             _write_identity(identity)
-    return email, previous
+        return anonymous_id(identity), ""
+
+    resolved = _resolve_email(key)
+    if not resolved:
+        return (email, "") if email else (anonymous_id(identity), "")
+
+    # Alias only when going anonymous -> email for the first time.
+    previous = "" if email else identity.get("anonymous_id", "")
+    identity["email"] = resolved
+    identity["key_fingerprint"] = fingerprint
+    _write_identity(identity)
+    return resolved, previous
 
 
 def flush() -> int: