chore: fix PostHog analytics identity and desktop metadata (#960)

* chore: report desktop app metadata in web analytics

* chore: fix stale test expectations and watcher flakiness

* chore: unify PostHog user identity tracking

* chore: preserve analytics dedupe state before login

* chore: harden analytics identity retries and coverage

* chore: scope first conversation analytics per user

* chore: avoid backfilling anonymous first-conversation analytics

* chore: defer first-session dedupe until analytics identity exists

* chore: log analytics identity failures and drop dead search helper

* chore: handle legacy analytics state and robust workspace watcher paths

Author: mrcfps

apps/controller/src/services/analytics-service.ts

@@ -19,6 +19,7 @@ type InternalSkillSource = "curated" | "managed" | "custom";
 
 type AnalyticsState = {
   sessionStartSent: boolean;
+  firstConversationDistinctId: string | null;
   sentUserMessageIds: string[];
   sentSkillUseIds: string[];
 };
@@ -65,10 +66,16 @@ type ResolvedSkillInfo = {
   source: string | null;
 };
 
+type AnalyticsDistinctIdResolution =
+  | { status: "ready"; distinctId: string }
+  | { status: "missing" }
+  | { status: "error" };
+
 const DEFAULT_POSTHOG_HOST = "https://us.i.posthog.com";
 
 const EMPTY_ANALYTICS_STATE: AnalyticsState = {
   sessionStartSent: false,
+  firstConversationDistinctId: null,
   sentUserMessageIds: [],
   sentSkillUseIds: [],
 };
@@ -169,11 +176,41 @@ export class AnalyticsService {
       return;
     }
 
+    const analyticsDistinctId = await this.resolveAnalyticsDistinctId();
+    if (analyticsDistinctId.status === "error") {
+      return;
+    }
+
+    const shouldSendAnalytics = analyticsDistinctId.status === "ready";
+    const currentDistinctId =
+      analyticsDistinctId.status === "ready"
+        ? analyticsDistinctId.distinctId
+        : null;
+    let stateChanged = false;
+
     await this.ensureStateLoaded();
-    const profile = await this.configStore.getLocalProfile();
+    if (
+      currentDistinctId &&
+      this.state.sessionStartSent &&
+      this.state.firstConversationDistinctId === null
+    ) {
+      this.state.sessionStartSent = false;
+      stateChanged = true;
+    }
+
+    if (
+      currentDistinctId &&
+      this.state.sessionStartSent &&
+      this.state.firstConversationDistinctId &&
+      this.state.firstConversationDistinctId !== currentDistinctId
+    ) {
+      this.state.sessionStartSent = false;
+      this.state.firstConversationDistinctId = null;
+      stateChanged = true;
+    }
+
     const sessions = await this.sessionsRuntime.listSessions();
     const skillLedger = await this.readSkillLedgerSources();
-    let stateChanged = false;
     let firstSessionCandidate: UserMessageCandidate | null = null;
 
     for (const session of sessions) {
@@ -214,16 +251,18 @@ export class AnalyticsService {
           continue;
         }
 
-        await this.sendAnalyticsEvent(
-          profile.id,
-          "user_message_sent",
-          {
-            channel: userMessage.channel,
-            model_provider: userMessage.providerName,
-            state: userMessage.state,
-          },
-          userMessage.timestampMs,
-        );
+        if (shouldSendAnalytics) {
+          await this.sendAnalyticsEvent(
+            analyticsDistinctId.distinctId,
+            "user_message_sent",
+            {
+              channel: userMessage.channel,
+              model_provider: userMessage.providerName,
+              state: userMessage.state,
+            },
+            userMessage.timestampMs,
+          );
+        }
         this.sentUserMessageIds.add(userMessage.id);
         stateChanged = true;
       }
@@ -236,34 +275,39 @@ export class AnalyticsService {
           continue;
         }
 
-        await this.sendAnalyticsEvent(
-          profile.id,
-          "skill_use",
-          {
-            skill_name: skillUse.skillName,
-            skill_source: skillUse.skillSource,
-            channel: skillUse.channel,
-            model_provider: skillUse.providerName,
-          },
-          skillUse.timestampMs,
-        );
+        if (shouldSendAnalytics) {
+          await this.sendAnalyticsEvent(
+            analyticsDistinctId.distinctId,
+            "skill_use",
+            {
+              skill_name: skillUse.skillName,
+              skill_source: skillUse.skillSource,
+              channel: skillUse.channel,
+              model_provider: skillUse.providerName,
+            },
+            skillUse.timestampMs,
+          );
+        }
         this.sentSkillUseIds.add(skillUse.id);
         stateChanged = true;
       }
     }
 
     if (!this.state.sessionStartSent && firstSessionCandidate?.providerName) {
-      await this.sendAnalyticsEvent(
-        profile.id,
-        "nexu_first_conversation_start",
-        {
-          channel: firstSessionCandidate.channel,
-          model_provider: firstSessionCandidate.providerName,
-        },
-        firstSessionCandidate.timestampMs,
-      );
-      this.state.sessionStartSent = true;
-      stateChanged = true;
+      if (shouldSendAnalytics) {
+        await this.sendAnalyticsEvent(
+          analyticsDistinctId.distinctId,
+          "nexu_first_conversation_start",
+          {
+            channel: firstSessionCandidate.channel,
+            model_provider: firstSessionCandidate.providerName,
+          },
+          firstSessionCandidate.timestampMs,
+        );
+        this.state.firstConversationDistinctId = analyticsDistinctId.distinctId;
+        this.state.sessionStartSent = true;
+        stateChanged = true;
+      }
     }
 
     if (stateChanged) {
@@ -281,6 +325,10 @@ export class AnalyticsService {
       const parsed = JSON.parse(raw) as Partial<AnalyticsState>;
       this.state = {
         sessionStartSent: parsed.sessionStartSent === true,
+        firstConversationDistinctId:
+          typeof parsed.firstConversationDistinctId === "string"
+            ? parsed.firstConversationDistinctId
+            : null,
         sentUserMessageIds: Array.isArray(parsed.sentUserMessageIds)
           ? parsed.sentUserMessageIds.filter(
               (value): value is string => typeof value === "string",
@@ -600,6 +648,29 @@ export class AnalyticsService {
     return `${host.replace(/\/+$/, "")}/i/v0/e/`;
   }
 
+  private async resolveAnalyticsDistinctId(): Promise<AnalyticsDistinctIdResolution> {
+    try {
+      const cloudStatus = await this.configStore.getDesktopCloudStatus();
+      const userId =
+        typeof cloudStatus?.userId === "string"
+          ? cloudStatus.userId.trim()
+          : "";
+      if (!userId || userId === "desktop-local-user") {
+        return { status: "missing" };
+      }
+
+      return { status: "ready", distinctId: userId };
+    } catch (error) {
+      logger.warn(
+        {
+          error: error instanceof Error ? error.message : String(error),
+        },
+        "failed_to_resolve_analytics_distinct_id",
+      );
+      return { status: "error" };
+    }
+  }
+
   private async sendAnalyticsEvent(
     distinctId: string,
     eventType: string,

apps/controller/src/services/skillhub/skill-dir-watcher.ts

@@ -10,7 +10,7 @@ export type SkillDirWatcherLogFn = (
 ) => void;
 
 const defaultLog: SkillDirWatcherLogFn = () => {};
-const workspaceSkillPathPattern = /^agents\/[^/]+\/skills(?:\/|$)/;
+const workspaceSkillPathPattern = /(?:^|\/)agents\/[^/]+\/skills(?:\/|$)/;
 
 export class SkillDirWatcher {
   private readonly skillsDir: string;
@@ -299,7 +299,7 @@ export class SkillDirWatcher {
       return false;
     }
 
-    const normalized = String(fileName).replace(/\\/g, "/");
+    const normalized = this.normalizeWorkspaceWatchPath(String(fileName));
     return workspaceSkillPathPattern.test(normalized);
   }
 
@@ -337,7 +337,7 @@ export class SkillDirWatcher {
   }
 
   private ensureWorkspaceSkillWatcherForPath(relativePath: string): void {
-    const normalized = relativePath.replace(/\\/g, "/");
+    const normalized = this.normalizeWorkspaceWatchPath(relativePath);
     const match = normalized.match(/^agents\/([^/]+)\//);
     if (!match) {
       return;
@@ -351,6 +351,19 @@ export class SkillDirWatcher {
     this.ensureWorkspaceSkillWatcher(botId);
   }
 
+  private normalizeWorkspaceWatchPath(filePath: string): string {
+    const normalized = filePath.replace(/\\/g, "/");
+    const match = workspaceSkillPathPattern.exec(normalized);
+    if (!match || typeof match.index !== "number") {
+      return normalized;
+    }
+
+    const startIndex =
+      normalized[match.index] === "/" ? match.index + 1 : match.index;
+
+    return normalized.slice(startIndex);
+  }
+
   private ensureWorkspaceSkillWatcher(botId: string): void {
     if (!this.openclawStateDir || this.workspaceSkillWatchers.has(botId)) {
       return;