🤖 fix: non-React flows now respect PostHog experiment assignments

Previously, getSendOptionsFromStorage() (used by resume/creation flows) always
passed the localStorage default to the backend, which treated any non-undefined
value as an explicit user override for userOverridable experiments.

Fix: isExperimentEnabled() now returns undefined for userOverridable experiments
when user hasn't explicitly set a localStorage value. The backend already handles
undefined correctly by falling through to PostHog assignment.

Also addresses code review feedback:
- Move telemetryService property declaration to top of ExperimentsService class
- Add comment explaining the "undefined" string check in hasLocalOverride
- Add docstring for getRemoteExperimentEnabled and move near other helpers
- Document MUX_ENABLE_TELEMETRY_IN_DEV env var in Makefile

Change-Id: I15e5360f7461cd62ad347fbb2e32b0e8dc4b873d
Signed-off-by: Thomas Kosiewski <[email protected]>

Author: ThomasK33

Makefile

@@ -23,6 +23,12 @@
 #   AVOID CONDITIONAL BRANCHES (if/else) IN BUILD TARGETS AT ALL COSTS.
 #   Branches reduce reproducibility - builds should fail fast with clear errors
 #   if dependencies are missing, not silently fall back to different behavior.
+#
+# Telemetry in Development:
+#   Telemetry is disabled by default in dev mode (MUX_DISABLE_TELEMETRY=1).
+#   To enable it (e.g., for testing PostHog experiments), set:
+#     MUX_ENABLE_TELEMETRY_IN_DEV=1 make dev
+#   This single env var is sufficient - no need to also set MUX_DISABLE_TELEMETRY=0.
 
 # Use PATH-resolved bash for portability across different systems.
 # - Windows: /usr/bin/bash doesn't exist in Chocolatey's make environment or GitHub Actions

src/browser/contexts/ExperimentsContext.tsx

@@ -63,24 +63,28 @@ function hasLocalOverride(experimentId: ExperimentId): boolean {
   const key = getExperimentKey(experimentId);
   try {
     const stored = window.localStorage.getItem(key);
+    // Check for literal "undefined" string defensively - this can occur if
+    // JSON.stringify(undefined) is accidentally stored (it returns "undefined")
     return stored !== null && stored !== "undefined";
   } catch {
     return false;
   }
 }
 
 /**
- * Set experiment state to localStorage and dispatch sync event.
+ * Convert PostHog experiment variant to boolean enabled state.
+ * For experiments with control/test variants, "test" means enabled.
  */
-
 function getRemoteExperimentEnabled(value: string | boolean): boolean {
   if (typeof value === "boolean") {
     return value;
   }
-
-  // For now, our PostHog experiment uses control/test variants.
   return value === "test";
 }
+
+/**
+ * Set experiment state to localStorage and dispatch sync event.
+ */
 function setExperimentState(experimentId: ExperimentId, enabled: boolean): void {
   const key = getExperimentKey(experimentId);
 

src/browser/hooks/useExperiments.ts

@@ -16,10 +16,32 @@ export {
  *
  * For reactive updates in React components, use useExperimentValue instead.
  *
+ * IMPORTANT: For user-overridable experiments, returns `undefined` when no explicit
+ * localStorage override exists. This signals to the backend to use the PostHog
+ * assignment instead of treating the default value as a user choice.
+ *
  * @param experimentId - The experiment to check
- * @returns Whether the experiment is enabled
+ * @returns Whether the experiment is enabled, or undefined if backend should decide
  */
-export function isExperimentEnabled(experimentId: ExperimentId): boolean {
+export function isExperimentEnabled(experimentId: ExperimentId): boolean | undefined {
   const experiment = EXPERIMENTS[experimentId];
-  return readPersistedState<boolean>(getExperimentKey(experimentId), experiment.enabledByDefault);
+  const key = getExperimentKey(experimentId);
+
+  // For user-overridable experiments: only return a value if user explicitly set one.
+  // This allows the backend to use PostHog assignment when there's no override.
+  if (experiment.userOverridable) {
+    const raw = window.localStorage.getItem(key);
+    // Check for null (never set) or literal "undefined" (defensive - see hasLocalOverride)
+    if (raw === null || raw === "undefined") {
+      return undefined; // Let backend use PostHog
+    }
+    try {
+      return JSON.parse(raw) as boolean;
+    } catch {
+      return undefined;
+    }
+  }
+
+  // Non-overridable: always use default (these are local-only experiments)
+  return readPersistedState<boolean>(key, experiment.enabledByDefault);
 }

src/node/services/experimentsService.ts

@@ -40,6 +40,7 @@ function isRecord(value: unknown): value is Record<string, unknown> {
  * - Avoid calling PostHog when telemetry is disabled
  */
 export class ExperimentsService {
+  private readonly telemetryService: TelemetryService;
   private readonly muxHome: string;
   private readonly cacheFilePath: string;
   private readonly cacheTtlMs: number;
@@ -60,8 +61,6 @@ export class ExperimentsService {
     this.cacheTtlMs = options.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
   }
 
-  private readonly telemetryService: TelemetryService;
-
   async initialize(): Promise<void> {
     if (this.cacheLoaded) {
       return;