From d9b9db208f4992a59726edfe445153987e4b97a1 Mon Sep 17 00:00:00 2001
From: youssef-intuned <youssef@intunedhq.com>
Date: Sun, 21 Jun 2026 16:29:06 +0300
Subject: [PATCH] add app insights + telemetry to extension different
 components

---
 .gitignore                                    |   3 +
 README.md                                     |  23 ++
 entrypoints/background.ts                     |  18 ++
 entrypoints/content.ts                        |  15 +
 .../popup/components/TelemetryToggle.tsx      |  46 ++++
 .../popup/components/WorkspaceSwitcher.tsx    |   2 +
 entrypoints/popup/main.tsx                    |  42 ++-
 entrypoints/popup/ui.module.css               |  25 ++
 lib/agent/agentLoopController.ts              |  24 ++
 lib/auth/request.ts                           |  57 +++-
 lib/background/context.ts                     |   3 +
 lib/background/handlers/auth.ts               |  23 +-
 lib/background/handlers/index.ts              |   6 +
 lib/background/handlers/telemetry.ts          |  44 +++
 lib/background/registerHandlers.ts            |  39 ++-
 lib/config.ts                                 |  73 +++++
 lib/messaging/index.ts                        |   2 +
 lib/messaging/protocol.ts                     |  39 +++
 lib/telemetry/api.ts                          |  35 +++
 lib/telemetry/client.ts                       | 259 ++++++++++++++++++
 lib/telemetry/connectionString.ts             |  45 +++
 lib/telemetry/forwardingSink.ts               |  62 +++++
 lib/telemetry/globalErrors.ts                 |  28 ++
 lib/telemetry/index.ts                        |   1 +
 lib/telemetry/scrub.ts                        | 111 ++++++++
 lib/telemetry/types.ts                        |  61 +++++
 package.json                                  |   3 +
 tests/unit/agent/agentLoopController.test.ts  |  17 +-
 tests/unit/auth/request.test.ts               |  90 ++++++
 tests/unit/background/harness.ts              |  43 ++-
 .../unit/background/registerHandlers.test.ts  | 134 +++++++++
 tests/unit/background/telemetry.test.ts       |  47 ++++
 tests/unit/config.test.ts                     |  61 +++++
 tests/unit/telemetry/client.test.ts           | 240 ++++++++++++++++
 tests/unit/telemetry/connectionString.test.ts |  35 +++
 tests/unit/telemetry/forwardingSink.test.ts   |  52 ++++
 tests/unit/telemetry/scrub.test.ts            | 102 +++++++
 wxt.config.ts                                 |  14 +-
 yarn.lock                                     |  37 +++
 39 files changed, 1930 insertions(+), 31 deletions(-)
 create mode 100644 entrypoints/popup/components/TelemetryToggle.tsx
 create mode 100644 lib/background/handlers/telemetry.ts
 create mode 100644 lib/telemetry/api.ts
 create mode 100644 lib/telemetry/client.ts
 create mode 100644 lib/telemetry/connectionString.ts
 create mode 100644 lib/telemetry/forwardingSink.ts
 create mode 100644 lib/telemetry/globalErrors.ts
 create mode 100644 lib/telemetry/index.ts
 create mode 100644 lib/telemetry/scrub.ts
 create mode 100644 lib/telemetry/types.ts
 create mode 100644 tests/unit/background/registerHandlers.test.ts
 create mode 100644 tests/unit/background/telemetry.test.ts
 create mode 100644 tests/unit/config.test.ts
 create mode 100644 tests/unit/telemetry/client.test.ts
 create mode 100644 tests/unit/telemetry/connectionString.test.ts
 create mode 100644 tests/unit/telemetry/forwardingSink.test.ts
 create mode 100644 tests/unit/telemetry/scrub.test.ts

diff --git a/.gitignore b/.gitignore
index 38d3fe8..42d8f30 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,3 +6,6 @@ playwright-report/
 test-results/
 *.log
 .DS_Store
+.env
+.env.local
+.env.*.local
diff --git a/README.md b/README.md
index 414a8d8..a6a4d3a 100644
--- a/README.md
+++ b/README.md
@@ -74,6 +74,29 @@ After the first `yarn dev`, load the unpacked extension from `.output/chrome-mv3
 - **Browser** — Vitest browser-mode tests that run selector generation against a real DOM and prove each candidate resolves to exactly the expected element set. This is the correctness oracle. Both layers run under `yarn test`.
 - **E2E** — Playwright against the packaged MV3 extension with a real page, pointer flow, popup, content script, and background worker. Run with `yarn e2e`.
 
+## Telemetry
+
+The extension reports anonymous diagnostics to Azure Application Insights so we can
+spot errors and usage issues in the wild. It is **anonymous** (a random per-install
+id — never your email, workspace name, browsed-page URLs, or selector strings) and can
+be turned off from the workspace menu in the popup ("Share anonymous usage data").
+
+What's collected: exceptions/unhandled rejections, command events with timing,
+agent-loop outcomes, and Intuned API request host, path, status, and latency — never
+the query string (it carries your workspace id). See [lib/telemetry/](./lib/telemetry).
+
+The background service worker is the single egress; content and popup forward items
+to it over the message protocol. Because an MV3 worker has no DOM and is short-lived,
+the SDK pipeline is built from `@microsoft/applicationinsights-core-js` +
+`-channel-js` directly (fetch transport, in-memory buffer) — not the Web SDK.
+
+The Azure connection string is hard-coded in [lib/config.ts](./lib/config.ts)
+(`HARDCODED_CONNECTION_STRING`); the write-only ingestion key is safe to embed in the
+published bundle. Because it is always present, dev builds report too — while developing,
+either use the in-popup opt-out or point telemetry at a throwaway resource by setting the
+`config.appInsightsConnectionString` key in `browser.storage.local` (an empty value falls
+back to the hard-coded string; clearing it restores the default).
+
 ## Project layout
 
 ```
diff --git a/entrypoints/background.ts b/entrypoints/background.ts
index f109ef1..e5c7be3 100644
--- a/entrypoints/background.ts
+++ b/entrypoints/background.ts
@@ -13,21 +13,39 @@ import {
 } from "@/lib/background/contextMenu";
 import { createBackgroundMessagingClient } from "@/lib/messaging";
 import { SelectorState } from "@/lib/state";
+import { BackgroundTelemetryClient } from "@/lib/telemetry/client";
+import { setTelemetrySink } from "@/lib/telemetry/api";
+import { reportGlobalErrors } from "@/lib/telemetry/globalErrors";
 
 export default defineBackground(() => {
   const state = new SelectorState();
   const messaging = createBackgroundMessagingClient();
+
+  // Single App Insights egress for the whole extension. Registered as the api.ts
+  // sink so background-originated trackEvent/trackException (registerHandlers,
+  // fetchIntunedApi, …) route here; content/popup forward over messaging. init()
+  // is async — calls before it resolves are safe no-ops.
+  const telemetry = new BackgroundTelemetryClient();
+  setTelemetrySink(telemetry);
+  void telemetry.init();
+
   const agentLoopController = new AgentLoopController({
     state,
     backgroundMessagingClient: messaging,
+    telemetry,
   });
 
   const context: BackgroundContext = {
     state,
     agentLoopController,
     backgroundMessagingClient: messaging,
+    telemetry,
   };
 
+  // Global safety net. This runs at the top of every worker cold start, so any
+  // otherwise-unobserved error/rejection in the worker is captured.
+  reportGlobalErrors(self);
+
   void state.hydrate();
 
   registerBackgroundHandlers(backgroundHandlers, context);
diff --git a/entrypoints/content.ts b/entrypoints/content.ts
index 29b8be4..5a04579 100644
--- a/entrypoints/content.ts
+++ b/entrypoints/content.ts
@@ -6,11 +6,24 @@ import {
   type ContentContext,
 } from "@/lib/content";
 import { createContentMessagingClient } from "@/lib/messaging";
+import { setTelemetrySink } from "@/lib/telemetry/api";
+import { createForwardingSink } from "@/lib/telemetry/forwardingSink";
+import { reportGlobalErrors } from "@/lib/telemetry/globalErrors";
+
+// A content script shares the page's `window`, so its error listeners also fire
+// for host-page errors. Gate on the extension origin so we only report our own.
+const EXTENSION_ORIGIN = /(?:chrome|moz)-extension:\/\//;
+function isExtensionError(error: unknown, filename?: string): boolean {
+  if (filename && EXTENSION_ORIGIN.test(filename)) return true;
+  return error instanceof Error && !!error.stack && EXTENSION_ORIGIN.test(error.stack);
+}
 
 export default defineContentScript({
   matches: ["<all_urls>"],
   runAt: "document_idle",
   main: () => {
+    setTelemetrySink(createForwardingSink("selector-extension-content"));
+
     const contextMenu = new ContextMenuTracker();
     contextMenu.addContextMenuListener();
     const picker = new PickerSession(contextMenu);
@@ -18,5 +31,7 @@ export default defineContentScript({
     const context: ContentContext = { picker, contentMessagingClient };
 
     registerContentHandlers(contentHandlers, context);
+
+    reportGlobalErrors(window, isExtensionError);
   },
 });
diff --git a/entrypoints/popup/components/TelemetryToggle.tsx b/entrypoints/popup/components/TelemetryToggle.tsx
new file mode 100644
index 0000000..950cbdb
--- /dev/null
+++ b/entrypoints/popup/components/TelemetryToggle.tsx
@@ -0,0 +1,46 @@
+import { useEffect, useState } from "react";
+import { getTelemetryEnabled, setTelemetryEnabled } from "@/lib/config";
+import styles from "../ui.module.css";
+
+/**
+ * Opt-out control for anonymous telemetry. Reads/writes the shared config flag
+ * (browser.storage.local); the background client picks up the change live via a
+ * storage.onChanged listener. Renders nothing until the current value loads.
+ */
+export function TelemetryToggle() {
+  const [enabled, setEnabled] = useState<boolean | null>(null);
+
+  useEffect(() => {
+    let active = true;
+    void getTelemetryEnabled().then((value) => {
+      if (active) setEnabled(value);
+    });
+    return () => {
+      active = false;
+    };
+  }, []);
+
+  if (enabled === null) return null;
+
+  const onChange = (event: React.ChangeEvent<HTMLInputElement>) => {
+    const next = event.target.checked;
+    setEnabled(next);
+    void setTelemetryEnabled(next);
+  };
+
+  return (
+    <label
+      className={styles.menuToggle}
+      role="menuitemcheckbox"
+      aria-checked={enabled}
+    >
+      <input
+        id="telemetry-toggle"
+        type="checkbox"
+        checked={enabled}
+        onChange={onChange}
+      />
+      <span>Share anonymous usage data</span>
+    </label>
+  );
+}
diff --git a/entrypoints/popup/components/WorkspaceSwitcher.tsx b/entrypoints/popup/components/WorkspaceSwitcher.tsx
index 0243546..0012163 100644
--- a/entrypoints/popup/components/WorkspaceSwitcher.tsx
+++ b/entrypoints/popup/components/WorkspaceSwitcher.tsx
@@ -5,6 +5,7 @@ import { ChevronDown, SignOutIcon } from "../icons";
 import { useClickOutside } from "../hooks/useClickOutside";
 import { useCachedAvatar } from "../hooks/useCachedAvatar";
 import { displayName, initials } from "../utils";
+import { TelemetryToggle } from "./TelemetryToggle";
 
 export function WorkspaceSwitcher({
   identity,
@@ -48,6 +49,7 @@ export function WorkspaceSwitcher({
           <div className={styles.menuIdentity}>
             <span className={styles.menuName}>{name}</span>
           </div>
+          <TelemetryToggle />
           <button
             id="sign-out"
             type="button"
diff --git a/entrypoints/popup/main.tsx b/entrypoints/popup/main.tsx
index cbfe405..80db611 100644
--- a/entrypoints/popup/main.tsx
+++ b/entrypoints/popup/main.tsx
@@ -1,7 +1,47 @@
+import { Component, type ReactNode } from "react";
 import { createRoot } from "react-dom/client";
 import { App } from "./App";
 import "./ui.module.css";
+import { setTelemetrySink, trackException } from "@/lib/telemetry/api";
+import { createForwardingSink } from "@/lib/telemetry/forwardingSink";
+import { reportGlobalErrors } from "@/lib/telemetry/globalErrors";
+
+// The popup is its own extension window — its error events are all ours (no host
+// page), so no filtering is needed. Forward telemetry to the background egress.
+setTelemetrySink(createForwardingSink("selector-extension-popup"));
+reportGlobalErrors(window);
+
+/** Reports render-time crashes to telemetry and shows a minimal fallback. */
+class TelemetryErrorBoundary extends Component<
+  { children: ReactNode },
+  { hasError: boolean }
+> {
+  state = { hasError: false };
+
+  static getDerivedStateFromError(): { hasError: boolean } {
+    return { hasError: true };
+  }
+
+  componentDidCatch(error: unknown): void {
+    trackException({ error, properties: { source: "errorBoundary" } });
+  }
+
+  render(): ReactNode {
+    if (this.state.hasError) {
+      return (
+        <div style={{ padding: 16, fontSize: 13 }}>
+          Something went wrong. Please reopen the popup.
+        </div>
+      );
+    }
+    return this.props.children;
+  }
+}
 
 const container = document.getElementById("root");
 if (!container) throw new Error("Missing #root in popup");
-createRoot(container).render(<App />);
+createRoot(container).render(
+  <TelemetryErrorBoundary>
+    <App />
+  </TelemetryErrorBoundary>
+);
diff --git a/entrypoints/popup/ui.module.css b/entrypoints/popup/ui.module.css
index bc29564..5b71a02 100644
--- a/entrypoints/popup/ui.module.css
+++ b/entrypoints/popup/ui.module.css
@@ -250,6 +250,31 @@ button {
   color: var(--danger);
 }
 
+.menuToggle {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  width: 100%;
+  padding: 7px 8px;
+  margin-bottom: 4px;
+  font-size: 12.5px;
+  font-weight: 600;
+  text-align: left;
+  color: var(--fg);
+  border-bottom: 1px solid var(--border);
+  cursor: pointer;
+}
+
+.menuToggle input {
+  flex: none;
+  margin: 0;
+  cursor: pointer;
+}
+
+.menuToggle span {
+  flex: 1;
+}
+
 /* ── usage bar ──────────────────────────────────────────────────────────── */
 
 .usage {
diff --git a/lib/agent/agentLoopController.ts b/lib/agent/agentLoopController.ts
index 98124f2..54f4df0 100644
--- a/lib/agent/agentLoopController.ts
+++ b/lib/agent/agentLoopController.ts
@@ -7,6 +7,7 @@ import {
 } from "@/lib/messaging";
 import { appendSelectorHistory } from "@/lib/state";
 import { generalizeArrayXpath } from "@/lib/content/dom/arrayXpath";
+import type { BackgroundTelemetry } from "@/lib/telemetry";
 import type {
   BrowserResultRecord,
   FinalSelectorResult,
@@ -21,6 +22,7 @@ import type {
 export interface AgentLoopDeps {
   state: SelectorState;
   backgroundMessagingClient: BackgroundMessagingClient;
+  telemetry: BackgroundTelemetry;
 }
 
 const MAX_BACKEND_STEPS = 20;
@@ -66,11 +68,17 @@ export class AgentLoopController {
 
     this.status = "running";
     let steps = 0;
+    const startedAt = Date.now();
     try {
       while (true) {
         if (signal.aborted) return;
 
         if (steps >= MAX_BACKEND_STEPS) {
+          this.deps.telemetry.trackEvent({
+            name: "agentLoop.maxStepsExceeded",
+            measurements: { steps },
+            operationId: sessionId,
+          });
           await this.settle(sessionId, {
             status: "error",
             note: `Exceeded max backend steps (${MAX_BACKEND_STEPS}).`,
@@ -148,12 +156,28 @@ export class AgentLoopController {
         return;
       }
       console.error("[selector-extension] AgentLoop error", error);
+      this.deps.telemetry.trackException({
+        error,
+        operationId: sessionId,
+        properties: { context: "agentLoop" },
+      });
       await this.settle(sessionId, {
         status: "error",
         note: error instanceof Error ? error.message : "Unknown loop error",
       });
     } finally {
       this.abortController = null;
+      this.deps.telemetry.trackEvent({
+        name: "agentLoop.completed",
+        properties: {
+          outcome: signal.aborted
+            ? "aborted"
+            : this.deps.state.get()?.status ?? "unknown",
+          mode: this.deps.state.get()?.mode ?? "unknown",
+        },
+        measurements: { durationMs: Date.now() - startedAt, steps },
+        operationId: sessionId,
+      });
     }
   }
 
diff --git a/lib/auth/request.ts b/lib/auth/request.ts
index 8d44bb6..c495076 100644
--- a/lib/auth/request.ts
+++ b/lib/auth/request.ts
@@ -1,4 +1,8 @@
 import { getApiHeaders, getApiQueryParams } from "./manager";
+// Import the api surface directly (not the barrel) so this background-only
+// module never pulls in the messaging-backed forwarding sink.
+import { trackEvent, trackException } from "@/lib/telemetry/api";
+import { scrubUrlToHost } from "@/lib/telemetry/scrub";
 
 /**
  * Fetch an Intuned backend REST endpoint with the active auth method applied:
@@ -23,13 +27,48 @@ export async function fetchIntunedApi(
     target.searchParams.set(key, value);
   }
 
-  return fetch(target.toString(), {
-    ...init,
-    headers: {
-      "Content-Type": "application/json",
-      ...init.headers,
-      ...authHeaders,
-    },
-    credentials: authHeaders ? "omit" : "include",
-  });
+  // Telemetry dimensions: host + pathname only — never the query string (it
+  // carries the api-key workspace id) or the request body.
+  const host = scrubUrlToHost(target.toString());
+  const pathname = target.pathname;
+  const method = (init.method ?? "GET").toUpperCase();
+  const startedAt = Date.now();
+
+  try {
+    const res = await fetch(target.toString(), {
+      ...init,
+      headers: {
+        "Content-Type": "application/json",
+        ...init.headers,
+        ...authHeaders,
+      },
+      credentials: authHeaders ? "omit" : "include",
+    });
+    trackEvent({
+      name: "api.request",
+      properties: {
+        host,
+        pathname,
+        method,
+        ok: String(res.ok),
+        statusCode: String(res.status),
+      },
+      measurements: { durationMs: Date.now() - startedAt },
+    });
+    return res;
+  } catch (error) {
+    // Network-level failure (DNS, offline) — the response never arrived. Skip
+    // user-initiated cancels (agent-loop abort), which aren't real failures.
+    const aborted =
+      init.signal?.aborted ||
+      (error instanceof DOMException && error.name === "AbortError");
+    if (!aborted) {
+      trackException({
+        error,
+        properties: { host, pathname, method, context: "api.request" },
+        measurements: { durationMs: Date.now() - startedAt },
+      });
+    }
+    throw error;
+  }
 }
diff --git a/lib/background/context.ts b/lib/background/context.ts
index 231b5d1..0c678e4 100644
--- a/lib/background/context.ts
+++ b/lib/background/context.ts
@@ -2,6 +2,7 @@ import type { ExtensionMessage } from "@webext-core/messaging";
 import type { AgentLoopController } from "@/lib/agent";
 import type { BackgroundMessagingClient } from "@/lib/messaging";
 import type { SelectorState } from "@/lib/state";
+import type { BackgroundTelemetry } from "@/lib/telemetry";
 
 export type MessageSender = ExtensionMessage["sender"];
 
@@ -10,6 +11,8 @@ export interface BackgroundContext {
   state: SelectorState;
   agentLoopController: AgentLoopController;
   backgroundMessagingClient: BackgroundMessagingClient;
+  /** Single App Insights egress; content/popup forward items here. */
+  telemetry: BackgroundTelemetry;
 }
 
 /**
diff --git a/lib/background/handlers/auth.ts b/lib/background/handlers/auth.ts
index 528283c..c2023ed 100644
--- a/lib/background/handlers/auth.ts
+++ b/lib/background/handlers/auth.ts
@@ -13,14 +13,31 @@ export const handleInitializeAuth: BackgroundHandler<
 
 export const handleSignIn: BackgroundHandler<
   BackgroundMessageType.SignIn
-> = async () => {
+> = async (_data, ctx) => {
+  ctx.telemetry.trackEvent({
+    name: "auth.signIn",
+    properties: { authMethod: "session" },
+  });
   void useBrowserSession();
 };
 
 export const handleSignOut: BackgroundHandler<
   BackgroundMessageType.SignOut
-> = async () => signOut();
+> = async (_data, ctx) => {
+  ctx.telemetry.trackEvent({ name: "auth.signOut" });
+  return signOut();
+};
 
 export const handleSetApiKey: BackgroundHandler<
   BackgroundMessageType.SetApiKey
-> = async ({ apiKey, workspaceId }) => configureApiKey(apiKey, workspaceId);
+> = async ({ apiKey, workspaceId }, ctx) => {
+  const result = await configureApiKey(apiKey, workspaceId);
+  ctx.telemetry.trackEvent({
+    name: "auth.setApiKey",
+    properties: {
+      authMethod: "api-key",
+      status: result.authenticated ? "ok" : "failed",
+    },
+  });
+  return result;
+};
diff --git a/lib/background/handlers/index.ts b/lib/background/handlers/index.ts
index 3c242c1..cdd03ef 100644
--- a/lib/background/handlers/index.ts
+++ b/lib/background/handlers/index.ts
@@ -17,6 +17,10 @@ import { handleStartPickerSessionForTab } from "./startPickerSessionForTab";
 import { handleGetSessionState } from "./getSessionState";
 import { handleHighlightSelector } from "./highlightSelector";
 import { handleSubmitSelectorFeedback } from "./submitSelectorFeedback";
+import {
+  handleTrackTelemetryEvent,
+  handleTrackTelemetryException,
+} from "./telemetry";
 
 export const backgroundHandlers: BackgroundHandlers = {
   [BackgroundMessageType.BootstrapPopup]: handleBootstrapPopup,
@@ -33,4 +37,6 @@ export const backgroundHandlers: BackgroundHandlers = {
   [BackgroundMessageType.SubmitSelectorFeedback]: handleSubmitSelectorFeedback,
   [BackgroundMessageType.StartPickerSessionForTab]: handleStartPickerSessionForTab,
   [BackgroundMessageType.GetSessionState]: handleGetSessionState,
+  [BackgroundMessageType.TrackTelemetryEvent]: handleTrackTelemetryEvent,
+  [BackgroundMessageType.TrackTelemetryException]: handleTrackTelemetryException,
 };
diff --git a/lib/background/handlers/telemetry.ts b/lib/background/handlers/telemetry.ts
new file mode 100644
index 0000000..9f04241
--- /dev/null
+++ b/lib/background/handlers/telemetry.ts
@@ -0,0 +1,44 @@
+/**
+ * Background handlers for telemetry forwarded from content/popup. The background
+ * is the single App Insights egress; these reconstruct the item (an Error from
+ * the flattened `{name, message, stack}`) and hand it to the role-aware client.
+ *
+ * NOTE: these handlers are intentionally NOT wrapped by the command-event
+ * instrumentation in registerHandlers — that would emit telemetry about
+ * telemetry. See `TELEMETRY_MESSAGE_TYPES` there.
+ */
+
+import { BackgroundMessageType } from "@/lib/messaging";
+import type { BackgroundHandler } from "@/lib/background";
+
+export const handleTrackTelemetryEvent: BackgroundHandler<
+  BackgroundMessageType.TrackTelemetryEvent
+> = (data, ctx) => {
+  ctx.telemetry.trackEvent(
+    {
+      name: data.name,
+      properties: data.properties,
+      measurements: data.measurements,
+      operationId: data.operationId,
+    },
+    data.role
+  );
+};
+
+export const handleTrackTelemetryException: BackgroundHandler<
+  BackgroundMessageType.TrackTelemetryException
+> = (data, ctx) => {
+  const error = new Error(data.message);
+  error.name = data.name;
+  if (data.stack) error.stack = data.stack;
+  ctx.telemetry.trackException(
+    {
+      error,
+      severity: data.severity,
+      properties: data.properties,
+      measurements: data.measurements,
+      operationId: data.operationId,
+    },
+    data.role
+  );
+};
diff --git a/lib/background/registerHandlers.ts b/lib/background/registerHandlers.ts
index d862a9c..2311aba 100644
--- a/lib/background/registerHandlers.ts
+++ b/lib/background/registerHandlers.ts
@@ -33,6 +33,15 @@ export type BackgroundHandlers = {
   [K in BackgroundMessageType]: BackgroundHandler<K>;
 };
 
+/**
+ * Telemetry-forwarding messages are excluded from command instrumentation —
+ * tracking them would emit telemetry about telemetry (and recurse on failure).
+ */
+const TELEMETRY_MESSAGE_TYPES: ReadonlySet<BackgroundMessageType> = new Set([
+  BackgroundMessageType.TrackTelemetryEvent,
+  BackgroundMessageType.TrackTelemetryException,
+]);
+
 export function registerBackgroundHandlers(
   handlers: BackgroundHandlers,
   ctx: BackgroundContext
@@ -45,10 +54,32 @@ export function registerBackgroundHandlers(
   for (const key of Object.values(BackgroundMessageType)) {
     register(key, async (message) => {
       await ctx.state.ready;
-      return handlers[key](message.data as never, {
-        ...ctx,
-        sender: message.sender,
-      });
+      const handlerCtx = { ...ctx, sender: message.sender };
+      const data = message.data as never;
+
+      if (TELEMETRY_MESSAGE_TYPES.has(key)) {
+        return handlers[key](data, handlerCtx);
+      }
+
+      // One choke point instruments every command: duration + success event,
+      // or an exception (then re-thrown so behavior is unchanged).
+      const startedAt = Date.now();
+      try {
+        const result = await handlers[key](data, handlerCtx);
+        ctx.telemetry.trackEvent({
+          name: `command.${key}`,
+          measurements: { durationMs: Date.now() - startedAt },
+          operationId: ctx.state.get()?.sessionId,
+        });
+        return result;
+      } catch (error) {
+        ctx.telemetry.trackException({
+          error,
+          properties: { command: key },
+          operationId: ctx.state.get()?.sessionId,
+        });
+        throw error;
+      }
     });
   }
 }
diff --git a/lib/config.ts b/lib/config.ts
index 3ade46f..28e6ac3 100644
--- a/lib/config.ts
+++ b/lib/config.ts
@@ -2,6 +2,79 @@ const DEFAULT_API_BASE = "https://app.intuned.io";
 export const GRAPHQL_API = "https://metricsshop.hasura.app/v1/graphql";
 const API_BASE_OVERRIDE_KEY = "config.apiBase";
 
+/* ───────────────────────── telemetry (App Insights) ─────────────────────── */
+
+/** Storage keys for telemetry config. Mirrors the `config.apiBase` override pattern. */
+export const TELEMETRY_ENABLED_KEY = "config.telemetryEnabled";
+const TELEMETRY_CONNECTION_STRING_OVERRIDE_KEY =
+  "config.appInsightsConnectionString";
+const TELEMETRY_INSTALL_ID_KEY = "telemetry.installId";
+
+/**
+ * Hard-coded App Insights connection string (temporary). Currently points at the
+ * shared web resource (cloud role `selector-extension-*` distinguishes it); swap
+ * for a dedicated `selector-extension` resource later. The write-only ingestion
+ * key is safe to ship in the bundle.
+ *
+ * NOTE: the IngestionEndpoint region here is coupled to `appInsightsHost` in
+ * wxt.config.ts (host_permissions). If you change the region, update that entry
+ * in lockstep or the worker's POST will be blocked.
+ */
+const HARDCODED_CONNECTION_STRING =
+  "InstrumentationKey=b042659b-fcc8-403f-ba01-0207fdbb6506;IngestionEndpoint=https://westus2-2.in.applicationinsights.azure.com/;LiveEndpoint=https://westus2.livediagnostics.monitor.azure.com/";
+
+/**
+ * Resolve the App Insights connection string: a `browser.storage.local` override
+ * (set for dev/e2e to point at a throwaway resource) wins over the hard-coded
+ * value. Returns `null` only if both are empty, which disables telemetry.
+ */
+export async function getTelemetryConnectionString(): Promise<string | null> {
+  const out = await browser.storage.local.get(
+    TELEMETRY_CONNECTION_STRING_OVERRIDE_KEY
+  );
+  const override = out[TELEMETRY_CONNECTION_STRING_OVERRIDE_KEY];
+  if (typeof override === "string" && override) return override;
+  return HARDCODED_CONNECTION_STRING || null;
+}
+
+export async function setTelemetryConnectionStringOverride(
+  connectionString: string | null
+): Promise<void> {
+  if (connectionString) {
+    await browser.storage.local.set({
+      [TELEMETRY_CONNECTION_STRING_OVERRIDE_KEY]: connectionString,
+    });
+  } else {
+    await browser.storage.local.remove(
+      TELEMETRY_CONNECTION_STRING_OVERRIDE_KEY
+    );
+  }
+}
+
+/** Whether the user has opted into telemetry. Defaults to enabled. */
+export async function getTelemetryEnabled(): Promise<boolean> {
+  const out = await browser.storage.local.get(TELEMETRY_ENABLED_KEY);
+  return out[TELEMETRY_ENABLED_KEY] !== false;
+}
+
+export async function setTelemetryEnabled(enabled: boolean): Promise<void> {
+  await browser.storage.local.set({ [TELEMETRY_ENABLED_KEY]: enabled });
+}
+
+/**
+ * A stable, anonymous per-install id used as `ai.user.id` so sessions and errors
+ * can be correlated across the worker's lifetimes without any PII. Generated once
+ * and persisted; never derived from the signed-in identity.
+ */
+export async function getInstallId(): Promise<string> {
+  const out = await browser.storage.local.get(TELEMETRY_INSTALL_ID_KEY);
+  const existing = out[TELEMETRY_INSTALL_ID_KEY];
+  if (typeof existing === "string" && existing) return existing;
+  const id = crypto.randomUUID();
+  await browser.storage.local.set({ [TELEMETRY_INSTALL_ID_KEY]: id });
+  return id;
+}
+
 export async function getApiBase(): Promise<string> {
   const out = await browser.storage.local.get(API_BASE_OVERRIDE_KEY);
   const value = out[API_BASE_OVERRIDE_KEY];
diff --git a/lib/messaging/index.ts b/lib/messaging/index.ts
index fcc522c..43162c2 100644
--- a/lib/messaging/index.ts
+++ b/lib/messaging/index.ts
@@ -28,6 +28,8 @@ export {
   type SubmitSelectorFeedbackResult,
   type SubmitTargetSelectionRequest,
   type TestSelectorsRequest,
+  type TrackTelemetryEventRequest,
+  type TrackTelemetryExceptionRequest,
 } from "./protocol";
 export {
   createBackgroundMessagingClient,
diff --git a/lib/messaging/protocol.ts b/lib/messaging/protocol.ts
index 55ebe07..ecb8154 100644
--- a/lib/messaging/protocol.ts
+++ b/lib/messaging/protocol.ts
@@ -13,6 +13,11 @@ import type {
 } from "@/lib/state";
 import type { AuthState } from "@/lib/auth";
 import type { SelectorCreationUsage } from "@/lib/graphql/usage";
+import type {
+  ForwardableRole,
+  TelemetrySeverity,
+  TrackEventInput,
+} from "@/lib/telemetry/types";
 
 /* ──────────────────────────── enums ──────────────────────────────────── */
 
@@ -45,6 +50,11 @@ export enum BackgroundMessageType {
   // programmatic surface (CLI bridge over CDP, see lib/background/bridge.ts)
   StartPickerSessionForTab = "bg:startPickerSessionForTab",
   GetSessionState = "bg:getSessionState",
+
+  // telemetry: content/popup forward items to the background, the single
+  // App Insights egress (see lib/telemetry). Fire-and-forget.
+  TrackTelemetryEvent = "bg:trackTelemetryEvent",
+  TrackTelemetryException = "bg:trackTelemetryException",
 }
 
 // messages addressed to content scripts (from background)
@@ -132,6 +142,28 @@ export interface StartPickerSessionForTabResponse {
   page: PageContext;
 }
 
+/** A telemetry event forwarded from content/popup to the background egress. */
+export type TrackTelemetryEventRequest = TrackEventInput & {
+  role: ForwardableRole;
+};
+
+/**
+ * A telemetry exception forwarded from content/popup. The Error is flattened to
+ * `{name, message, stack}` because Errors don't survive structuredClone; the
+ * background rebuilds it before sending to App Insights. (This is why it can't
+ * just extend TrackExceptionInput, whose `error` is a live value.)
+ */
+export interface TrackTelemetryExceptionRequest {
+  role: ForwardableRole;
+  name: string;
+  message: string;
+  stack?: string;
+  severity?: TelemetrySeverity;
+  properties?: Record<string, string>;
+  measurements?: Record<string, number>;
+  operationId?: string;
+}
+
 export type BackgroundProtocolMap = {
   [BackgroundMessageType.BootstrapPopup]: () => BootstrapPopupResponse;
 
@@ -175,6 +207,13 @@ export type BackgroundProtocolMap = {
     data: StartPickerSessionForTabRequest
   ) => StartPickerSessionForTabResponse;
   [BackgroundMessageType.GetSessionState]: () => SelectorCreateState | null;
+
+  [BackgroundMessageType.TrackTelemetryEvent]: (
+    data: TrackTelemetryEventRequest
+  ) => void;
+  [BackgroundMessageType.TrackTelemetryException]: (
+    data: TrackTelemetryExceptionRequest
+  ) => void;
 };
 
 /* ───────────────────── content protocol map ──────────────────────────── */
diff --git a/lib/telemetry/api.ts b/lib/telemetry/api.ts
new file mode 100644
index 0000000..0182c9c
--- /dev/null
+++ b/lib/telemetry/api.ts
@@ -0,0 +1,35 @@
+/**
+ * The public telemetry surface, imported uniformly by every context. It
+ * delegates to a registered sink: the background registers the direct App
+ * Insights client (see ./client.ts); content and popup register a forwarding
+ * sink (see ./forwardingSink.ts) during their entrypoint setup. Until a sink is
+ * registered — and in tests — every call is a safe no-op.
+ *
+ * Both functions are fire-and-forget and swallow errors: telemetry must never
+ * throw into application logic.
+ */
+
+import type { TelemetrySink, TrackEventInput, TrackExceptionInput } from "./types";
+
+let sink: TelemetrySink | null = null;
+
+/** Register the active sink for this context. Call once during entry setup. */
+export function setTelemetrySink(next: TelemetrySink | null): void {
+  sink = next;
+}
+
+export function trackEvent(input: TrackEventInput): void {
+  try {
+    sink?.trackEvent(input);
+  } catch {
+    // ignore
+  }
+}
+
+export function trackException(input: TrackExceptionInput): void {
+  try {
+    sink?.trackException(input);
+  } catch {
+    // ignore
+  }
+}
diff --git a/lib/telemetry/client.ts b/lib/telemetry/client.ts
new file mode 100644
index 0000000..ddccd8c
--- /dev/null
+++ b/lib/telemetry/client.ts
@@ -0,0 +1,259 @@
+/**
+ * Background-only App Insights client. Builds the SDK pipeline from the core +
+ * channel directly — deliberately NOT the `ApplicationInsights` umbrella class
+ * or `loadAppInsights()`, which wire up DOM auto-collectors (page views, ajax,
+ * history) that reach for `window`/`document` and crash in an MV3 service
+ * worker. With no extensions array there is no DOM auto-collection; we hand the
+ * core only the `Sender`, configured for the worker (fetch transport, in-memory
+ * buffer, no beacon).
+ *
+ * This is the single telemetry egress: content and popup forward their items
+ * here via messaging (see ./forwardingSink.ts and the background handlers).
+ */
+
+import {
+  AppInsightsCore,
+  type IConfiguration,
+  type ITelemetryItem,
+} from "@microsoft/applicationinsights-core-js";
+import { Sender } from "@microsoft/applicationinsights-channel-js";
+import {
+  Event as AiEvent,
+  Exception as AiException,
+  TelemetryItemCreator,
+} from "@microsoft/applicationinsights-common";
+import {
+  getInstallId,
+  getTelemetryConnectionString,
+  getTelemetryEnabled,
+  TELEMETRY_ENABLED_KEY,
+} from "@/lib/config";
+import { parseConnectionString } from "./connectionString";
+import {
+  normalizeError,
+  sanitizeMeasurements,
+  sanitizeProperties,
+  type NormalizedError,
+} from "./scrub";
+import type {
+  BackgroundTelemetry,
+  TelemetryRole,
+  TelemetrySeverity,
+  TrackEventInput,
+  TrackExceptionInput,
+} from "./types";
+
+const BACKGROUND_ROLE: TelemetryRole = "selector-extension-background";
+
+// App Insights SeverityLevel: Warning=2, Error=3, Critical=4.
+const SEVERITY: Record<TelemetrySeverity, number> = {
+  warning: 2,
+  error: 3,
+  critical: 4,
+};
+
+/**
+ * App Insights types `ITelemetryItem.tags` as the awkward `Tags & Tags[]`.
+ * Treat it as a plain string map (which is how the SDK's own initializers use
+ * it — see `envelope.tags["ai.cloud.role"] = ...`).
+ */
+function tagsOf(item: ITelemetryItem): Record<string, string | undefined> {
+  if (!item.tags) {
+    item.tags = {} as ITelemetryItem["tags"];
+  }
+  return item.tags as unknown as Record<string, string | undefined>;
+}
+
+/** Rebuild an Error from a normalized shape so the SDK can parse its stack. */
+function toError(normalized: NormalizedError): Error {
+  const err = new Error(normalized.message);
+  err.name = normalized.name;
+  if (normalized.stack) err.stack = normalized.stack;
+  return err;
+}
+
+let cachedVersion: string | undefined;
+/** Extension version from the manifest (`ai.application.ver`), cached. */
+function appVersion(): string {
+  if (cachedVersion === undefined) {
+    try {
+      cachedVersion = browser.runtime.getManifest().version;
+    } catch {
+      cachedVersion = "unknown";
+    }
+  }
+  return cachedVersion;
+}
+
+export class BackgroundTelemetryClient implements BackgroundTelemetry {
+  private core: AppInsightsCore | null = null;
+  private enabled = true;
+  private installId = "";
+
+  /**
+   * Resolve config and stand up the core + sender. A no-op (leaves `core` null)
+   * when no connection string is configured. The connection string is currently
+   * always present (a hard-coded value in lib/config), so in practice this only
+   * no-ops when the value is unparseable or a storage override clears it. Never
+   * throws — an init failure is logged and leaves telemetry disabled. Safe to
+   * call once at worker startup.
+   */
+  async init(): Promise<void> {
+    try {
+      const connectionString = await getTelemetryConnectionString();
+      if (!connectionString) {
+        console.debug(
+          "[selector-extension] telemetry disabled: no connection string"
+        );
+        return;
+      }
+
+      // The bare core (unlike the umbrella ApplicationInsights class) does not
+      // parse a connection string — it needs an explicit key + endpoint.
+      const parsed = parseConnectionString(connectionString);
+      if (!parsed) {
+        console.debug(
+          "[selector-extension] telemetry disabled: unparseable connection string"
+        );
+        return;
+      }
+
+      this.enabled = await getTelemetryEnabled();
+      this.installId = await getInstallId();
+
+      const sender = new Sender();
+      const core = new AppInsightsCore();
+      const config: IConfiguration = {
+        instrumentationKey: parsed.instrumentationKey,
+        endpointUrl: parsed.trackUrl,
+        disableInstrumentationKeyValidation: true,
+        extensionConfig: {
+          [sender.identifier]: {
+            endpointUrl: parsed.trackUrl,
+            // Service-worker constraints: no XMLHttpRequest, no sessionStorage,
+            // and sendBeacon is unavailable — force the fetch sender + in-memory
+            // buffer, and keep the batch window short so items flush before the
+            // worker is suspended (~30s idle).
+            disableXhr: true,
+            enableSessionStorageBuffer: false,
+            isBeaconApiDisabled: true,
+            maxBatchInterval: 5000,
+          },
+        },
+      };
+      core.initialize(config, [sender]);
+
+      const ver = appVersion();
+      const installId = this.installId;
+      core.addTelemetryInitializer((item: ITelemetryItem) => {
+        const tags = tagsOf(item);
+        // Per-item role (set by stamp() for forwarded content/popup items) wins;
+        // otherwise default to background.
+        tags["ai.cloud.role"] = tags["ai.cloud.role"] ?? BACKGROUND_ROLE;
+        tags["ai.application.ver"] = ver;
+        tags["ai.user.id"] = installId;
+        return true;
+      });
+
+      this.core = core;
+
+      // Respect the opt-out toggle live, without a restart.
+      browser.storage.onChanged.addListener((changes, area) => {
+        if (area === "local" && changes[TELEMETRY_ENABLED_KEY]) {
+          this.enabled = changes[TELEMETRY_ENABLED_KEY].newValue !== false;
+        }
+      });
+    } catch (error) {
+      // Telemetry must never throw into app logic — a broken init just leaves
+      // `core` null (disabled). Log a breadcrumb so the blackout is diagnosable
+      // rather than completely silent.
+      console.debug("[selector-extension] telemetry init failed", error);
+    }
+  }
+
+  trackEvent(input: TrackEventInput, role: TelemetryRole = BACKGROUND_ROLE): void {
+    this.safe(() => {
+      if (!this.ready()) return;
+      const props = sanitizeProperties(input.properties);
+      const event = new AiEvent(
+        this.core!.logger,
+        input.name,
+        props,
+        sanitizeMeasurements(input.measurements)
+      );
+      const item = TelemetryItemCreator.create(
+        event,
+        AiEvent.dataType,
+        AiEvent.envelopeType,
+        this.core!.logger,
+        props
+      );
+      this.stamp(item, role, input.operationId);
+      this.core!.track(item);
+    });
+  }
+
+  trackException(
+    input: TrackExceptionInput,
+    role: TelemetryRole = BACKGROUND_ROLE
+  ): void {
+    this.safe(() => {
+      if (!this.ready()) return;
+      const props = sanitizeProperties(input.properties);
+      const error = toError(normalizeError(input.error));
+      const exception = new AiException(
+        this.core!.logger,
+        error,
+        props,
+        sanitizeMeasurements(input.measurements),
+        SEVERITY[input.severity ?? "error"]
+      );
+      const item = TelemetryItemCreator.create(
+        exception,
+        AiException.dataType,
+        AiException.envelopeType,
+        this.core!.logger,
+        props
+      );
+      this.stamp(item, role, input.operationId);
+      this.core!.track(item);
+    });
+    // Exceptions are low-volume and the most-losable under SW suspend — flush now.
+    void this.flush();
+  }
+
+  /** Force a send. Called internally after exceptions; also used by tests. */
+  async flush(): Promise<void> {
+    try {
+      this.core?.flush(true);
+    } catch {
+      // never let a flush failure surface into app logic
+    }
+  }
+
+  private ready(): boolean {
+    return this.core != null && this.enabled;
+  }
+
+  private stamp(
+    item: ITelemetryItem,
+    role: TelemetryRole,
+    operationId?: string
+  ): void {
+    const tags = tagsOf(item);
+    tags["ai.cloud.role"] = role;
+    if (operationId) tags["ai.operation.id"] = operationId;
+  }
+
+  private safe(fn: () => void): void {
+    try {
+      fn();
+    } catch (error) {
+      try {
+        console.debug("[selector-extension] telemetry track failed", error);
+      } catch {
+        // ignore — telemetry must never throw into app logic
+      }
+    }
+  }
+}
diff --git a/lib/telemetry/connectionString.ts b/lib/telemetry/connectionString.ts
new file mode 100644
index 0000000..85b5637
--- /dev/null
+++ b/lib/telemetry/connectionString.ts
@@ -0,0 +1,45 @@
+/**
+ * Parse an App Insights connection string into the fields the bare
+ * `AppInsightsCore` needs. The umbrella `ApplicationInsights` class parses the
+ * connection string for you, but the core does not — it requires an explicit
+ * instrumentation key and endpoint. The format is a simple `k=v;k=v` string:
+ *
+ *   InstrumentationKey=<guid>;IngestionEndpoint=https://<region>.in.applicationinsights.azure.com/;...
+ */
+
+export interface ParsedConnectionString {
+  instrumentationKey: string;
+  /** Ingestion origin without a trailing slash, e.g. https://westus2-2.in.applicationinsights.azure.com */
+  ingestionEndpoint: string;
+  /** Full track URL the Sender should POST to. */
+  trackUrl: string;
+}
+
+const DEFAULT_INGESTION_ENDPOINT = "https://dc.services.visualstudio.com";
+
+export function parseConnectionString(
+  connectionString: string
+): ParsedConnectionString | null {
+  const map: Record<string, string> = {};
+  for (const part of connectionString.split(";")) {
+    const trimmed = part.trim();
+    if (!trimmed) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq === -1) continue;
+    const key = trimmed.slice(0, eq).trim().toLowerCase();
+    map[key] = trimmed.slice(eq + 1).trim();
+  }
+
+  const instrumentationKey = map["instrumentationkey"];
+  if (!instrumentationKey) return null;
+
+  const ingestionEndpoint = (
+    map["ingestionendpoint"] || DEFAULT_INGESTION_ENDPOINT
+  ).replace(/\/+$/, "");
+
+  return {
+    instrumentationKey,
+    ingestionEndpoint,
+    trackUrl: `${ingestionEndpoint}/v2/track`,
+  };
+}
diff --git a/lib/telemetry/forwardingSink.ts b/lib/telemetry/forwardingSink.ts
new file mode 100644
index 0000000..e6b7add
--- /dev/null
+++ b/lib/telemetry/forwardingSink.ts
@@ -0,0 +1,62 @@
+/**
+ * Telemetry sink for the content script and popup. Neither context sends to App
+ * Insights directly — the background is the single egress. This sink serializes
+ * each item and forwards it over the existing background message protocol.
+ *
+ * Errors don't survive structuredClone (the messaging transport drops the
+ * prototype/stack), so exceptions are normalized to a plain `{name, message,
+ * stack}` shape before sending; the background rebuilds them.
+ */
+
+import { BackgroundMessageType, backgroundProtocol } from "@/lib/messaging";
+import { normalizeError } from "./scrub";
+import type {
+  ForwardableRole,
+  TelemetrySink,
+  TrackEventInput,
+  TrackExceptionInput,
+} from "./types";
+
+/** Build a forwarding sink that tags every item with its originating role. */
+export function createForwardingSink(role: ForwardableRole): TelemetrySink {
+  const send = (
+    type:
+      | BackgroundMessageType.TrackTelemetryEvent
+      | BackgroundMessageType.TrackTelemetryException,
+    data: unknown
+  ): void => {
+    try {
+      void backgroundProtocol.sendMessage(type, data as never).catch(() => {
+        // background may be mid-restart; dropping a telemetry item is fine
+      });
+    } catch {
+      // ignore — telemetry must never throw into app logic
+    }
+  };
+
+  return {
+    trackEvent(input: TrackEventInput): void {
+      send(BackgroundMessageType.TrackTelemetryEvent, {
+        role,
+        name: input.name,
+        properties: input.properties,
+        measurements: input.measurements,
+        operationId: input.operationId,
+      });
+    },
+
+    trackException(input: TrackExceptionInput): void {
+      const normalized = normalizeError(input.error);
+      send(BackgroundMessageType.TrackTelemetryException, {
+        role,
+        name: normalized.name,
+        message: normalized.message,
+        stack: normalized.stack,
+        severity: input.severity,
+        properties: input.properties,
+        measurements: input.measurements,
+        operationId: input.operationId,
+      });
+    },
+  };
+}
diff --git a/lib/telemetry/globalErrors.ts b/lib/telemetry/globalErrors.ts
new file mode 100644
index 0000000..542aeed
--- /dev/null
+++ b/lib/telemetry/globalErrors.ts
@@ -0,0 +1,28 @@
+/**
+ * Wires a context's global `error` / `unhandledrejection` events to telemetry as
+ * `source: "global"` exceptions. Used by all three entrypoints (background uses
+ * `self`, content/popup use `window`); the content script passes an `isReportable`
+ * filter so it ignores host-page errors that share its `window`.
+ */
+
+import { trackException } from "./api";
+
+/** Attach global error + unhandled-rejection reporting to a window/worker scope. */
+export function reportGlobalErrors(
+  target: EventTarget,
+  isReportable?: (error: unknown, filename?: string) => boolean
+): void {
+  target.addEventListener("error", (event) => {
+    const e = event as ErrorEvent;
+    if (isReportable && !isReportable(e.error, e.filename)) return;
+    trackException({
+      error: e.error ?? e.message,
+      properties: { source: "global" },
+    });
+  });
+  target.addEventListener("unhandledrejection", (event) => {
+    const e = event as PromiseRejectionEvent;
+    if (isReportable && !isReportable(e.reason)) return;
+    trackException({ error: e.reason, properties: { source: "global" } });
+  });
+}
diff --git a/lib/telemetry/index.ts b/lib/telemetry/index.ts
new file mode 100644
index 0000000..37b08ae
--- /dev/null
+++ b/lib/telemetry/index.ts
@@ -0,0 +1 @@
+export type { BackgroundTelemetry } from "./types";
diff --git a/lib/telemetry/scrub.ts b/lib/telemetry/scrub.ts
new file mode 100644
index 0000000..d149605
--- /dev/null
+++ b/lib/telemetry/scrub.ts
@@ -0,0 +1,111 @@
+/**
+ * Privacy scrubbing for telemetry. The guiding rule: send shapes and counts,
+ * never content. No page URLs/titles, selector strings, element HTML, or any
+ * signed-in identity. Everything here is defensive — call sites already avoid
+ * PII, but this is the last line before an item reaches App Insights.
+ */
+
+/** A normalized, transport-safe error (Errors don't survive structuredClone). */
+export interface NormalizedError {
+  name: string;
+  message: string;
+  stack?: string;
+}
+
+// chrome-extension://<32-char id>/ and moz-extension://<uuid>/ → stable token so
+// stacks group cleanly and never leak the per-install extension origin.
+const EXTENSION_URL = /(?:chrome|moz)-extension:\/\/[^/\s)]+\//gi;
+
+/** Collapse extension-origin prefixes in arbitrary text (messages, stacks). */
+export function collapseExtensionUrls(text: string): string {
+  return text.replace(EXTENSION_URL, "extension://");
+}
+
+/** Reduce a URL to its host only — drops path, query, and hash. */
+export function scrubUrlToHost(raw: string): string {
+  try {
+    return new URL(raw).host;
+  } catch {
+    return "invalid-url";
+  }
+}
+
+/** Normalize any thrown value into a transport-safe, scrubbed shape. */
+export function normalizeError(error: unknown): NormalizedError {
+  if (error instanceof Error) {
+    return {
+      name: error.name || "Error",
+      message: collapseExtensionUrls(error.message || ""),
+      stack: error.stack ? collapseExtensionUrls(error.stack) : undefined,
+    };
+  }
+  if (typeof error === "string") {
+    return { name: "Error", message: collapseExtensionUrls(error) };
+  }
+  let message = "Unknown error";
+  try {
+    message = collapseExtensionUrls(JSON.stringify(error) ?? message);
+  } catch {
+    // non-serializable — keep the default
+  }
+  return { name: "NonError", message };
+}
+
+/**
+ * Allow-list of property keys that may be sent. Anything else is dropped before
+ * it reaches App Insights — adding a new dimension is a conscious privacy
+ * decision. Keep this in sync with the instrumentation hook points.
+ */
+export const ALLOWED_PROPERTY_KEYS: ReadonlySet<string> = new Set([
+  "command", // background message type name
+  "outcome", // agent-loop result status
+  "mode", // selector mode (single/list)
+  "status", // generic status string (e.g. auth result "ok"/"failed")
+  "statusCode", // HTTP status
+  "host", // API host
+  "pathname", // API pathname (no query)
+  "ok", // HTTP ok boolean (stringified)
+  "method", // HTTP method
+  "authMethod", // api-key | session
+  "source", // where an event originated (e.g. "global", "errorBoundary")
+  "context", // free-form short context label
+]);
+
+const MAX_PROPERTY_LENGTH = 8192;
+
+/**
+ * Coerce values to strings, collapse extension URLs, cap length, and drop any
+ * key not in the allow-list. Returns `undefined` when nothing survives so the
+ * SDK omits an empty properties bag.
+ */
+export function sanitizeProperties(
+  properties: Record<string, string> | undefined
+): Record<string, string> | undefined {
+  if (!properties) return undefined;
+  const out: Record<string, string> = {};
+  let kept = 0;
+  for (const [key, value] of Object.entries(properties)) {
+    if (!ALLOWED_PROPERTY_KEYS.has(key)) continue;
+    if (value == null) continue;
+    const str = collapseExtensionUrls(String(value)).slice(0, MAX_PROPERTY_LENGTH);
+    out[key] = str;
+    kept++;
+  }
+  return kept > 0 ? out : undefined;
+}
+
+/** Keep only finite numeric measurements. */
+export function sanitizeMeasurements(
+  measurements: Record<string, number> | undefined
+): Record<string, number> | undefined {
+  if (!measurements) return undefined;
+  const out: Record<string, number> = {};
+  let kept = 0;
+  for (const [key, value] of Object.entries(measurements)) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+      out[key] = value;
+      kept++;
+    }
+  }
+  return kept > 0 ? out : undefined;
+}
diff --git a/lib/telemetry/types.ts b/lib/telemetry/types.ts
new file mode 100644
index 0000000..8c76636
--- /dev/null
+++ b/lib/telemetry/types.ts
@@ -0,0 +1,61 @@
+/**
+ * Public telemetry types shared across all three extension contexts. The same
+ * `trackEvent` / `trackException` surface (see ./api.ts) is used everywhere; the
+ * background sends directly to App Insights while content and popup forward to
+ * the background (see ./forwardingSink.ts).
+ */
+
+/** App Insights `ai.cloud.role` — distinguishes which context emitted an item. */
+export type TelemetryRole =
+  | "selector-extension-background"
+  | "selector-extension-content"
+  | "selector-extension-popup";
+
+/**
+ * The roles that forward over the message protocol to the background egress.
+ * Background never forwards to itself, so it's excluded — this keeps the wire
+ * DTOs from ever claiming the background role.
+ */
+export type ForwardableRole = Exclude<TelemetryRole, "selector-extension-background">;
+
+/** Maps to App Insights `SeverityLevel` (Warning=2, Error=3, Critical=4). */
+export type TelemetrySeverity = "warning" | "error" | "critical";
+
+export interface TrackEventInput {
+  /** Event name, e.g. `command.StartAgent` or `agentLoop.completed`. */
+  name: string;
+  /** String dimensions. Run through the property allow-list before sending. */
+  properties?: Record<string, string>;
+  /** Numeric metrics (latency, counts). */
+  measurements?: Record<string, number>;
+  /** Correlation id (e.g. sessionId) → `ai.operation.id`. */
+  operationId?: string;
+}
+
+export interface TrackExceptionInput {
+  error: unknown;
+  /** Defaults to `error`. */
+  severity?: TelemetrySeverity;
+  properties?: Record<string, string>;
+  measurements?: Record<string, number>;
+  operationId?: string;
+}
+
+/**
+ * The sink the public API delegates to. The background registers a direct App
+ * Insights client; content/popup register a forwarding sink. Fire-and-forget.
+ */
+export interface TelemetrySink {
+  trackEvent(input: TrackEventInput): void;
+  trackException(input: TrackExceptionInput): void;
+}
+
+/**
+ * The role-aware sink the background holds on BackgroundContext. Background calls
+ * default the role to background; the forwarding handlers pass the content/popup
+ * role through. Implemented by BackgroundTelemetryClient.
+ */
+export interface BackgroundTelemetry {
+  trackEvent(input: TrackEventInput, role?: TelemetryRole): void;
+  trackException(input: TrackExceptionInput, role?: TelemetryRole): void;
+}
diff --git a/package.json b/package.json
index 9d9daa0..d85f590 100644
--- a/package.json
+++ b/package.json
@@ -40,6 +40,9 @@
   },
   "dependencies": {
     "@apollo/client": "^4.1.0",
+    "@microsoft/applicationinsights-channel-js": "2.8.9",
+    "@microsoft/applicationinsights-common": "2.8.9",
+    "@microsoft/applicationinsights-core-js": "2.8.9",
     "@webext-core/messaging": "^3.0.2",
     "graphql": "^16.12.0",
     "lucide-react": "0.539.0",
diff --git a/tests/unit/agent/agentLoopController.test.ts b/tests/unit/agent/agentLoopController.test.ts
index 2f45658..f4e8f2a 100644
--- a/tests/unit/agent/agentLoopController.test.ts
+++ b/tests/unit/agent/agentLoopController.test.ts
@@ -11,7 +11,9 @@ import type {
 } from "../../../lib/state";
 import {
   createFakeMessagingClient,
+  createFakeTelemetry,
   type FakeMessagingClient,
+  type FakeTelemetry,
   makeInflightSession,
   silenceConsole,
 } from "../background/harness";
@@ -145,6 +147,7 @@ function testSelectorsTurn(
 interface LoopFixture {
   state: SelectorState;
   messaging: FakeMessagingClient;
+  telemetry: FakeTelemetry;
   controller: AgentLoopController;
   sessionId: string;
   tabId: number;
@@ -157,13 +160,16 @@ function setupLoop(opts: { withTab?: boolean } = {}): LoopFixture {
   if (opts.withTab !== false) state.setMeta({ tabId: 42 });
 
   const messaging = createFakeMessagingClient();
+  const telemetry = createFakeTelemetry();
   const controller = new AgentLoopController({
     state,
     backgroundMessagingClient: messaging,
+    telemetry,
   });
   return {
     state,
     messaging,
+    telemetry,
     controller,
     sessionId: session.sessionId,
     tabId: 42,
@@ -188,7 +194,8 @@ describe("AgentLoopController", () => {
 
   describe("happy path", () => {
     it("done in one turn → settle dispatches DeactivatePicker + SelectorGenerationSettled, status returns to idle", async () => {
-      const { state, messaging, controller, sessionId, tabId } = setupLoop();
+      const { state, messaging, telemetry, controller, sessionId, tabId } =
+        setupLoop();
       scriptFetch([doneOk(state.get()!)]);
       messaging.whenContent(ContentMessageType.HighlightSelector, () => ({
         matchCount: 1,
@@ -198,6 +205,14 @@ describe("AgentLoopController", () => {
 
       // State reflects the final response.
       expect(state.get()?.status).toBe("done");
+
+      // Telemetry: a completion event with the outcome + step count.
+      const completed = telemetry.events.find(
+        (e) => e.input.name === "agentLoop.completed"
+      );
+      expect(completed).toBeDefined();
+      expect(completed?.input.properties?.outcome).toBe("done");
+      expect(completed?.input.measurements?.steps).toBe(1);
       expect(state.get()?.finalResult).toEqual({
         status: "ok",
         bestSelector: { type: "css", value: "#picked" },
diff --git a/tests/unit/auth/request.test.ts b/tests/unit/auth/request.test.ts
index a1a310c..6f80ae8 100644
--- a/tests/unit/auth/request.test.ts
+++ b/tests/unit/auth/request.test.ts
@@ -19,6 +19,19 @@ vi.mock("@/lib/auth/manager", () => ({
   getApiQueryParams: getApiQueryParamsMock,
 }));
 
+// Telemetry is fire-and-forget; mock the public surface to capture the events
+// `fetchIntunedApi` emits without standing up a real sink. (scrub.ts stays real
+// so we exercise the actual host/path scrubbing.)
+const { trackEventMock, trackExceptionMock } = vi.hoisted(() => ({
+  trackEventMock: vi.fn(),
+  trackExceptionMock: vi.fn(),
+}));
+
+vi.mock("@/lib/telemetry/api", () => ({
+  trackEvent: trackEventMock,
+  trackException: trackExceptionMock,
+}));
+
 const URL_BASE = "https://app.intuned.io/api/selectors/create";
 
 function stubFetch(): ReturnType<typeof vi.fn> {
@@ -31,6 +44,8 @@ describe("fetchIntunedApi", () => {
   beforeEach(() => {
     getApiHeadersMock.mockReset().mockResolvedValue(undefined);
     getApiQueryParamsMock.mockReset().mockResolvedValue(undefined);
+    trackEventMock.mockReset();
+    trackExceptionMock.mockReset();
   });
   afterEach(() => {
     vi.unstubAllGlobals();
@@ -93,4 +108,79 @@ describe("fetchIntunedApi", () => {
     await expect(fetchIntunedApi(URL_BASE)).rejects.toThrow("Not signed in");
     expect(fetchMock).not.toHaveBeenCalled();
   });
+
+  it("emits an api.request event with host + path only, never the query string", async () => {
+    getApiHeadersMock.mockResolvedValue({ "x-api-key": "in1_key" });
+    getApiQueryParamsMock.mockResolvedValue({ workspaceId: "ws-secret" });
+    stubFetch();
+
+    await fetchIntunedApi(URL_BASE);
+
+    expect(trackEventMock).toHaveBeenCalledTimes(1);
+    const input = trackEventMock.mock.calls[0][0];
+    expect(input.name).toBe("api.request");
+    expect(input.properties).toMatchObject({
+      host: "app.intuned.io",
+      pathname: "/api/selectors/create",
+      method: "GET",
+      ok: "true",
+      statusCode: "200",
+    });
+    // The workspace id rides in the query string; it must never be reported.
+    expect(JSON.stringify(input)).not.toContain("ws-secret");
+    expect(typeof input.measurements.durationMs).toBe("number");
+    expect(trackExceptionMock).not.toHaveBeenCalled();
+  });
+
+  it("reports a network failure as an exception (not a success event) and rethrows", async () => {
+    const failure = new TypeError("Failed to fetch");
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => {
+        throw failure;
+      })
+    );
+
+    await expect(fetchIntunedApi(URL_BASE)).rejects.toThrow("Failed to fetch");
+
+    expect(trackEventMock).not.toHaveBeenCalled();
+    expect(trackExceptionMock).toHaveBeenCalledTimes(1);
+    const input = trackExceptionMock.mock.calls[0][0];
+    expect(input.error).toBe(failure);
+    expect(input.properties).toMatchObject({
+      host: "app.intuned.io",
+      pathname: "/api/selectors/create",
+      context: "api.request",
+    });
+  });
+
+  it("skips exception telemetry for a user-initiated abort (pre-aborted signal)", async () => {
+    const controller = new AbortController();
+    controller.abort();
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => {
+        throw new DOMException("Aborted", "AbortError");
+      })
+    );
+
+    await expect(
+      fetchIntunedApi(URL_BASE, { signal: controller.signal })
+    ).rejects.toThrow();
+
+    expect(trackExceptionMock).not.toHaveBeenCalled();
+  });
+
+  it("skips exception telemetry when fetch throws an AbortError without a signal", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => {
+        throw new DOMException("Aborted", "AbortError");
+      })
+    );
+
+    await expect(fetchIntunedApi(URL_BASE)).rejects.toThrow();
+
+    expect(trackExceptionMock).not.toHaveBeenCalled();
+  });
 });
diff --git a/tests/unit/background/harness.ts b/tests/unit/background/harness.ts
index eeda29c..d6ec937 100644
--- a/tests/unit/background/harness.ts
+++ b/tests/unit/background/harness.ts
@@ -15,6 +15,12 @@ import type {
 import { SelectorState } from "../../../lib/state";
 import type { PageContext, SelectorCreateState } from "../../../lib/state";
 import type { GetDataType, GetReturnType } from "@webext-core/messaging";
+import type {
+  BackgroundTelemetry,
+  TelemetryRole,
+  TrackEventInput,
+  TrackExceptionInput,
+} from "../../../lib/telemetry/types";
 
 // harness for testing background handlers in isolation, with fakes for the messaging client and agent loop controller, and some state fixtures.
 
@@ -87,6 +93,37 @@ export function createFakeMessagingClient(): FakeMessagingClient {
   };
 }
 
+// ─── telemetry fake ──────────────────────────────────────────────────────────
+
+export interface RecordedEvent {
+  input: TrackEventInput;
+  role?: TelemetryRole;
+}
+export interface RecordedException {
+  input: TrackExceptionInput;
+  role?: TelemetryRole;
+}
+
+export interface FakeTelemetry extends BackgroundTelemetry {
+  events: RecordedEvent[];
+  exceptions: RecordedException[];
+}
+
+export function createFakeTelemetry(): FakeTelemetry {
+  const events: RecordedEvent[] = [];
+  const exceptions: RecordedException[] = [];
+  return {
+    events,
+    exceptions,
+    trackEvent(input, role) {
+      events.push({ input, role });
+    },
+    trackException(input, role) {
+      exceptions.push({ input, role });
+    },
+  };
+}
+
 // ─── agent-loop fake (for handler tests; the real one has its own tests) ─────
 
 export interface FakeAgentLoopController extends AgentLoopController {
@@ -120,12 +157,14 @@ export interface HarnessOptions {
   messaging?: FakeMessagingClient;
   agentLoop?: AgentLoopController;
   sender?: MessageSender;
+  telemetry?: FakeTelemetry;
 }
 
 export interface Harness {
   state: SelectorState;
   messaging: FakeMessagingClient;
   agentLoop: FakeAgentLoopController;
+  telemetry: FakeTelemetry;
   context: BackgroundHandlerContext;
 }
 
@@ -134,16 +173,18 @@ export function createHarness(opts: HarnessOptions = {}): Harness {
   const messaging = opts.messaging ?? createFakeMessagingClient();
   const agentLoop = (opts.agentLoop ??
     createFakeAgentLoopController()) as FakeAgentLoopController;
+  const telemetry = opts.telemetry ?? createFakeTelemetry();
   const baseContext: BackgroundContext = {
     state,
     agentLoopController: agentLoop,
     backgroundMessagingClient: messaging,
+    telemetry,
   };
   const context: BackgroundHandlerContext = {
     ...baseContext,
     sender: opts.sender as MessageSender,
   };
-  return { state, messaging, agentLoop, context };
+  return { state, messaging, agentLoop, telemetry, context };
 }
 
 // ─── state fixtures ──────────────────────────────────────────────────────────
diff --git a/tests/unit/background/registerHandlers.test.ts b/tests/unit/background/registerHandlers.test.ts
new file mode 100644
index 0000000..5a6ecee
--- /dev/null
+++ b/tests/unit/background/registerHandlers.test.ts
@@ -0,0 +1,134 @@
+import { fakeBrowser } from "@webext-core/fake-browser";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  registerBackgroundHandlers,
+  type BackgroundHandlers,
+} from "../../../lib/background/registerHandlers";
+import {
+  BackgroundMessageType,
+  backgroundProtocol,
+} from "../../../lib/messaging";
+import { createHarness } from "./harness";
+
+/**
+ * The command-instrumentation choke point in `registerBackgroundHandlers`: every
+ * command handler is wrapped to emit a `command.*` event on success or an
+ * exception (re-thrown) on failure, while telemetry-forwarding messages are
+ * deliberately excluded to avoid telemetry-about-telemetry. We register through
+ * a stubbed `backgroundProtocol.onMessage` to capture each wrapped callback, then
+ * invoke it directly.
+ */
+
+type Registered = Map<
+  BackgroundMessageType,
+  (message: { data: unknown; sender: unknown }) => unknown
+>;
+
+function captureRegistrations(): Registered {
+  const registered: Registered = new Map();
+  vi.spyOn(backgroundProtocol, "onMessage").mockImplementation(((
+    type: BackgroundMessageType,
+    cb: (m: { data: unknown; sender: unknown }) => unknown
+  ) => {
+    registered.set(type, cb);
+    return () => {};
+  }) as never);
+  return registered;
+}
+
+function makeHandlers(
+  overrides: Partial<Record<BackgroundMessageType, () => unknown>>
+): BackgroundHandlers {
+  const handlers = {} as Record<BackgroundMessageType, () => unknown>;
+  for (const key of Object.values(BackgroundMessageType)) {
+    handlers[key] = overrides[key] ?? (async () => undefined);
+  }
+  return handlers as BackgroundHandlers;
+}
+
+describe("registerBackgroundHandlers (command instrumentation)", () => {
+  beforeEach(() => fakeBrowser.reset());
+  afterEach(() => vi.restoreAllMocks());
+
+  it("emits a command.* event with duration on success and returns the result", async () => {
+    const h = createHarness();
+    await h.state.hydrate(); // the wrapper awaits ctx.state.ready
+    const registered = captureRegistrations();
+    registerBackgroundHandlers(
+      makeHandlers({
+        [BackgroundMessageType.GetSessionState]: async () => "result",
+      }),
+      h.context
+    );
+
+    const cb = registered.get(BackgroundMessageType.GetSessionState)!;
+    const result = await cb({ data: undefined, sender: undefined });
+
+    expect(result).toBe("result");
+    const event = h.telemetry.events.find(
+      (e) => e.input.name === `command.${BackgroundMessageType.GetSessionState}`
+    );
+    expect(event).toBeDefined();
+    expect(typeof event?.input.measurements?.durationMs).toBe("number");
+    expect(h.telemetry.exceptions).toHaveLength(0);
+  });
+
+  it("records an exception (command property) and re-throws on handler failure", async () => {
+    const h = createHarness();
+    await h.state.hydrate(); // the wrapper awaits ctx.state.ready
+    const registered = captureRegistrations();
+    const boom = new Error("handler boom");
+    registerBackgroundHandlers(
+      makeHandlers({
+        [BackgroundMessageType.SignOut]: async () => {
+          throw boom;
+        },
+      }),
+      h.context
+    );
+
+    const cb = registered.get(BackgroundMessageType.SignOut)!;
+    await expect(cb({ data: undefined, sender: undefined })).rejects.toThrow(
+      "handler boom"
+    );
+
+    const ex = h.telemetry.exceptions.find(
+      (e) => e.input.properties?.command === BackgroundMessageType.SignOut
+    );
+    expect(ex).toBeDefined();
+    expect(ex?.input.error).toBe(boom);
+    // A failed command must NOT also emit a success event.
+    expect(
+      h.telemetry.events.some(
+        (e) => e.input.name === `command.${BackgroundMessageType.SignOut}`
+      )
+    ).toBe(false);
+  });
+
+  it("does not instrument telemetry-forwarding messages (no telemetry about telemetry)", async () => {
+    const h = createHarness();
+    await h.state.hydrate(); // the wrapper awaits ctx.state.ready
+    const registered = captureRegistrations();
+    let handlerCalled = false;
+    registerBackgroundHandlers(
+      makeHandlers({
+        [BackgroundMessageType.TrackTelemetryEvent]: async () => {
+          handlerCalled = true;
+        },
+      }),
+      h.context
+    );
+
+    const cb = registered.get(BackgroundMessageType.TrackTelemetryEvent)!;
+    await cb({
+      data: { role: "selector-extension-content", name: "x" },
+      sender: undefined,
+    });
+
+    expect(handlerCalled).toBe(true);
+    // No `command.*` event for the forwarding message itself.
+    expect(
+      h.telemetry.events.some((e) => e.input.name.startsWith("command."))
+    ).toBe(false);
+  });
+});
diff --git a/tests/unit/background/telemetry.test.ts b/tests/unit/background/telemetry.test.ts
new file mode 100644
index 0000000..b1b3408
--- /dev/null
+++ b/tests/unit/background/telemetry.test.ts
@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+import {
+  handleTrackTelemetryEvent,
+  handleTrackTelemetryException,
+} from "../../../lib/background/handlers/telemetry";
+import { createHarness } from "./harness";
+
+describe("telemetry forwarding handlers", () => {
+  it("forwards an event to the client carrying the originating role", () => {
+    const h = createHarness();
+
+    handleTrackTelemetryEvent(
+      {
+        role: "selector-extension-content",
+        name: "command.test",
+        measurements: { durationMs: 3 },
+      },
+      h.context
+    );
+
+    expect(h.telemetry.events).toHaveLength(1);
+    expect(h.telemetry.events[0].role).toBe("selector-extension-content");
+    expect(h.telemetry.events[0].input.name).toBe("command.test");
+    expect(h.telemetry.events[0].input.measurements?.durationMs).toBe(3);
+  });
+
+  it("rebuilds an Error from the flattened shape before forwarding", () => {
+    const h = createHarness();
+
+    handleTrackTelemetryException(
+      {
+        role: "selector-extension-popup",
+        name: "TypeError",
+        message: "boom",
+        stack: "TypeError: boom\n at x",
+      },
+      h.context
+    );
+
+    expect(h.telemetry.exceptions).toHaveLength(1);
+    const { input, role } = h.telemetry.exceptions[0];
+    expect(role).toBe("selector-extension-popup");
+    expect(input.error).toBeInstanceOf(Error);
+    expect((input.error as Error).name).toBe("TypeError");
+    expect((input.error as Error).message).toBe("boom");
+  });
+});
diff --git a/tests/unit/config.test.ts b/tests/unit/config.test.ts
new file mode 100644
index 0000000..725e633
--- /dev/null
+++ b/tests/unit/config.test.ts
@@ -0,0 +1,61 @@
+import { fakeBrowser } from "@webext-core/fake-browser";
+import { beforeEach, describe, expect, it } from "vitest";
+import {
+  getInstallId,
+  getTelemetryConnectionString,
+  getTelemetryEnabled,
+  setTelemetryConnectionStringOverride,
+  setTelemetryEnabled,
+} from "../../lib/config";
+
+const OVERRIDE = "InstrumentationKey=override;IngestionEndpoint=https://x/";
+
+describe("telemetry config", () => {
+  beforeEach(() => fakeBrowser.reset());
+
+  describe("getInstallId", () => {
+    it("generates once and returns the same id on subsequent calls", async () => {
+      const first = await getInstallId();
+      expect(first).toMatch(/^[0-9a-f-]{36}$/);
+
+      const second = await getInstallId();
+      expect(second).toBe(first);
+    });
+  });
+
+  describe("getTelemetryEnabled", () => {
+    it("defaults to enabled when unset", async () => {
+      expect(await getTelemetryEnabled()).toBe(true);
+    });
+
+    it("is disabled only when explicitly set to false", async () => {
+      await setTelemetryEnabled(false);
+      expect(await getTelemetryEnabled()).toBe(false);
+
+      await setTelemetryEnabled(true);
+      expect(await getTelemetryEnabled()).toBe(true);
+    });
+  });
+
+  describe("getTelemetryConnectionString", () => {
+    it("falls back to the hard-coded string when no override is set", async () => {
+      const cs = await getTelemetryConnectionString();
+      expect(cs).toContain("InstrumentationKey=");
+      expect(cs).not.toContain("override");
+    });
+
+    it("prefers a storage override over the hard-coded string", async () => {
+      await setTelemetryConnectionStringOverride(OVERRIDE);
+      expect(await getTelemetryConnectionString()).toBe(OVERRIDE);
+    });
+
+    it("clears the override on null and falls back to the hard-coded string", async () => {
+      await setTelemetryConnectionStringOverride(OVERRIDE);
+      await setTelemetryConnectionStringOverride(null);
+
+      const cs = await getTelemetryConnectionString();
+      expect(cs).not.toContain("override");
+      expect(cs).toContain("InstrumentationKey=");
+    });
+  });
+});
diff --git a/tests/unit/telemetry/client.test.ts b/tests/unit/telemetry/client.test.ts
new file mode 100644
index 0000000..8bd78d2
--- /dev/null
+++ b/tests/unit/telemetry/client.test.ts
@@ -0,0 +1,240 @@
+import { fakeBrowser } from "@webext-core/fake-browser";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { AppInsightsCore } from "@microsoft/applicationinsights-core-js";
+import { BackgroundTelemetryClient } from "../../../lib/telemetry/client";
+import {
+  setTelemetryConnectionStringOverride,
+  setTelemetryEnabled,
+} from "../../../lib/config";
+import * as config from "../../../lib/config";
+
+const IKEY = "00000000-0000-0000-0000-000000000001";
+const ENDPOINT = "https://test.in.applicationinsights.azure.com";
+const CONNECTION_STRING = `InstrumentationKey=${IKEY};IngestionEndpoint=${ENDPOINT}/`;
+
+type FetchCall = { url: string; body: string };
+
+// The AI channel's fetch sender calls `fetch(new Request(url, {body}))`, so the
+// first arg is a Request. Read both shapes, and only record the call once the
+// body is read so `calls` is ready to assert on as soon as it has the entry.
+function stubFetch(): { calls: FetchCall[]; mock: ReturnType<typeof vi.fn> } {
+  const calls: FetchCall[] = [];
+  const mock = vi.fn(async (input: unknown, init: RequestInit = {}) => {
+    let url: string;
+    let body: string;
+    if (input instanceof Request) {
+      url = input.url;
+      body = await input.clone().text();
+    } else {
+      url = String(input);
+      body = typeof init.body === "string" ? init.body : "";
+    }
+    calls.push({ url, body });
+    return new Response(
+      JSON.stringify({ itemsReceived: 1, itemsAccepted: 1, errors: [] }),
+      { status: 200 }
+    );
+  });
+  vi.stubGlobal("fetch", mock);
+  return { calls, mock };
+}
+
+async function waitForCalls(
+  calls: FetchCall[],
+  n = 1,
+  timeoutMs = 2000
+): Promise<void> {
+  const start = Date.now();
+  while (calls.length < n) {
+    if (Date.now() - start > timeoutMs) {
+      throw new Error(`fetch recorded ${calls.length}/${n} within ${timeoutMs}ms`);
+    }
+    await new Promise((r) => setTimeout(r, 5));
+  }
+}
+
+/** Parse the App Insights ingestion payload (JSON array or newline-delimited). */
+function parseEnvelopes(body: string): any[] {
+  const trimmed = body.trim();
+  if (!trimmed) return [];
+  try {
+    const parsed = JSON.parse(trimmed);
+    return Array.isArray(parsed) ? parsed : [parsed];
+  } catch {
+    return trimmed
+      .split("\n")
+      .filter(Boolean)
+      .map((line) => JSON.parse(line));
+  }
+}
+
+function allEnvelopes(calls: FetchCall[]): any[] {
+  return calls.flatMap((c) => parseEnvelopes(c.body));
+}
+
+describe("BackgroundTelemetryClient", () => {
+  beforeEach(() => {
+    fakeBrowser.reset();
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    vi.spyOn(console, "debug").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it("sends an exception envelope with the right iKey, role, and shape", async () => {
+    const { calls } = stubFetch();
+    await setTelemetryConnectionStringOverride(CONNECTION_STRING);
+
+    const client = new BackgroundTelemetryClient();
+    await client.init();
+    client.trackException({
+      error: new Error("boom"),
+      severity: "error",
+      operationId: "sess-1",
+    });
+
+    await waitForCalls(calls, 1);
+
+    expect(calls[0].url).toContain(ENDPOINT);
+    expect(calls[0].url).toContain("/v2/track");
+
+    const exception = allEnvelopes(calls).find(
+      (e) => e.data?.baseType === "ExceptionData"
+    );
+    expect(exception).toBeDefined();
+    expect(exception.iKey).toBe(IKEY);
+    expect(exception.name).toContain("Exception");
+    expect(exception.tags["ai.cloud.role"]).toBe("selector-extension-background");
+    expect(exception.tags["ai.operation.id"]).toBe("sess-1");
+    expect(exception.data.baseData.exceptions[0].message).toBe("boom");
+  });
+
+  it("sends an event envelope with name and measurements", async () => {
+    const { calls } = stubFetch();
+    await setTelemetryConnectionStringOverride(CONNECTION_STRING);
+
+    const client = new BackgroundTelemetryClient();
+    await client.init();
+    client.trackEvent({
+      name: "command.test",
+      measurements: { durationMs: 5 },
+    });
+    await client.flush();
+
+    await waitForCalls(calls, 1);
+
+    const event = allEnvelopes(calls).find(
+      (e) => e.data?.baseType === "EventData"
+    );
+    expect(event).toBeDefined();
+    expect(event.iKey).toBe(IKEY);
+    expect(event.data.baseData.name).toBe("command.test");
+    expect(event.data.baseData.measurements.durationMs).toBe(5);
+  });
+
+  it("stamps the forwarded role for content/popup items", async () => {
+    const { calls } = stubFetch();
+    await setTelemetryConnectionStringOverride(CONNECTION_STRING);
+
+    const client = new BackgroundTelemetryClient();
+    await client.init();
+    client.trackException(
+      { error: new Error("from popup") },
+      "selector-extension-popup"
+    );
+
+    await waitForCalls(calls, 1);
+    const exception = allEnvelopes(calls).find(
+      (e) => e.data?.baseType === "ExceptionData"
+    );
+    expect(exception.tags["ai.cloud.role"]).toBe("selector-extension-popup");
+  });
+
+  it("is a no-op when no connection string is configured", async () => {
+    const { mock } = stubFetch();
+    vi.spyOn(config, "getTelemetryConnectionString").mockResolvedValue(null);
+
+    const client = new BackgroundTelemetryClient();
+    await client.init();
+    client.trackException({ error: new Error("nope") });
+    client.trackEvent({ name: "command.test" });
+    await client.flush();
+
+    await new Promise((r) => setTimeout(r, 50));
+    expect(mock).not.toHaveBeenCalled();
+  });
+
+  it("is a no-op when telemetry is disabled", async () => {
+    const { mock } = stubFetch();
+    await setTelemetryConnectionStringOverride(CONNECTION_STRING);
+    await setTelemetryEnabled(false);
+
+    const client = new BackgroundTelemetryClient();
+    await client.init();
+    client.trackException({ error: new Error("nope") });
+    await client.flush();
+
+    await new Promise((r) => setTimeout(r, 50));
+    expect(mock).not.toHaveBeenCalled();
+  });
+
+  it("never throws when the SDK's track fails (safe wrapper)", async () => {
+    stubFetch();
+    await setTelemetryConnectionStringOverride(CONNECTION_STRING);
+    const client = new BackgroundTelemetryClient();
+    await client.init();
+
+    // Force the underlying core to throw on track; safe() must swallow it so
+    // application logic never sees a telemetry failure.
+    const trackSpy = vi
+      .spyOn(AppInsightsCore.prototype, "track")
+      .mockImplementation(() => {
+        throw new Error("sdk exploded");
+      });
+
+    expect(() => client.trackEvent({ name: "command.test" })).not.toThrow();
+    expect(() =>
+      client.trackException({ error: new Error("boom") })
+    ).not.toThrow();
+
+    trackSpy.mockRestore();
+  });
+
+  it("stops sending after the user opts out live (storage.onChanged)", async () => {
+    const { mock } = stubFetch();
+    await setTelemetryConnectionStringOverride(CONNECTION_STRING);
+    const client = new BackgroundTelemetryClient();
+    await client.init();
+
+    // Opt out after init — the client's storage.onChanged listener flips enabled.
+    await setTelemetryEnabled(false);
+
+    client.trackEvent({ name: "command.test" });
+    await client.flush();
+    await new Promise((r) => setTimeout(r, 50));
+
+    expect(mock).not.toHaveBeenCalled();
+  });
+
+  it("resumes sending after opt-out then opt-in", async () => {
+    const { calls } = stubFetch();
+    await setTelemetryConnectionStringOverride(CONNECTION_STRING);
+    const client = new BackgroundTelemetryClient();
+    await client.init();
+
+    await setTelemetryEnabled(false);
+    await setTelemetryEnabled(true);
+
+    client.trackEvent({ name: "command.test" });
+    await client.flush();
+    await waitForCalls(calls, 1);
+
+    expect(
+      allEnvelopes(calls).some((e) => e.data?.baseData?.name === "command.test")
+    ).toBe(true);
+  });
+});
diff --git a/tests/unit/telemetry/connectionString.test.ts b/tests/unit/telemetry/connectionString.test.ts
new file mode 100644
index 0000000..4d1394c
--- /dev/null
+++ b/tests/unit/telemetry/connectionString.test.ts
@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import { parseConnectionString } from "../../../lib/telemetry/connectionString";
+
+describe("parseConnectionString", () => {
+  it("parses key + endpoint and builds the track url", () => {
+    const parsed = parseConnectionString(
+      "InstrumentationKey=abc-123;IngestionEndpoint=https://westus2-2.in.applicationinsights.azure.com/;LiveEndpoint=https://x/"
+    );
+    expect(parsed).toEqual({
+      instrumentationKey: "abc-123",
+      ingestionEndpoint: "https://westus2-2.in.applicationinsights.azure.com",
+      trackUrl: "https://westus2-2.in.applicationinsights.azure.com/v2/track",
+    });
+  });
+
+  it("is order-independent and trims a trailing slash", () => {
+    const parsed = parseConnectionString(
+      "IngestionEndpoint=https://r.example.com;InstrumentationKey=k1"
+    );
+    expect(parsed?.instrumentationKey).toBe("k1");
+    expect(parsed?.trackUrl).toBe("https://r.example.com/v2/track");
+  });
+
+  it("falls back to the default ingestion endpoint when omitted", () => {
+    const parsed = parseConnectionString("InstrumentationKey=k2");
+    expect(parsed?.ingestionEndpoint).toBe(
+      "https://dc.services.visualstudio.com"
+    );
+  });
+
+  it("returns null without an instrumentation key", () => {
+    expect(parseConnectionString("IngestionEndpoint=https://x/")).toBeNull();
+    expect(parseConnectionString("")).toBeNull();
+  });
+});
diff --git a/tests/unit/telemetry/forwardingSink.test.ts b/tests/unit/telemetry/forwardingSink.test.ts
new file mode 100644
index 0000000..eb4346d
--- /dev/null
+++ b/tests/unit/telemetry/forwardingSink.test.ts
@@ -0,0 +1,52 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { backgroundProtocol, BackgroundMessageType } from "../../../lib/messaging";
+import { createForwardingSink } from "../../../lib/telemetry/forwardingSink";
+
+describe("createForwardingSink", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("forwards an event to the background with the originating role", () => {
+    const send = vi
+      .spyOn(backgroundProtocol, "sendMessage")
+      .mockResolvedValue(undefined as never);
+
+    const sink = createForwardingSink("selector-extension-content");
+    sink.trackEvent({ name: "command.test", properties: { mode: "single" } });
+
+    expect(send).toHaveBeenCalledWith(
+      BackgroundMessageType.TrackTelemetryEvent,
+      expect.objectContaining({
+        role: "selector-extension-content",
+        name: "command.test",
+        properties: { mode: "single" },
+      })
+    );
+  });
+
+  it("normalizes the Error to a transport-safe shape before forwarding", () => {
+    const send = vi
+      .spyOn(backgroundProtocol, "sendMessage")
+      .mockResolvedValue(undefined as never);
+
+    const sink = createForwardingSink("selector-extension-popup");
+    sink.trackException({ error: new TypeError("boom") });
+
+    const [type, data] = send.mock.calls[0];
+    expect(type).toBe(BackgroundMessageType.TrackTelemetryException);
+    expect(data).toMatchObject({
+      role: "selector-extension-popup",
+      name: "TypeError",
+      message: "boom",
+    });
+  });
+
+  it("swallows background send failures", () => {
+    vi.spyOn(backgroundProtocol, "sendMessage").mockRejectedValue(
+      new Error("bg down") as never
+    );
+    const sink = createForwardingSink("selector-extension-content");
+    expect(() => sink.trackEvent({ name: "x" })).not.toThrow();
+  });
+});
diff --git a/tests/unit/telemetry/scrub.test.ts b/tests/unit/telemetry/scrub.test.ts
new file mode 100644
index 0000000..c11df3a
--- /dev/null
+++ b/tests/unit/telemetry/scrub.test.ts
@@ -0,0 +1,102 @@
+import { describe, expect, it } from "vitest";
+import {
+  collapseExtensionUrls,
+  normalizeError,
+  sanitizeMeasurements,
+  sanitizeProperties,
+  scrubUrlToHost,
+} from "../../../lib/telemetry/scrub";
+
+describe("scrubUrlToHost", () => {
+  it("reduces a URL to host only, dropping path/query/hash", () => {
+    expect(
+      scrubUrlToHost("https://app.intuned.io/api/selectors/create?wid=secret#x")
+    ).toBe("app.intuned.io");
+  });
+
+  it("returns a placeholder for non-URLs", () => {
+    expect(scrubUrlToHost("not a url")).toBe("invalid-url");
+  });
+});
+
+describe("collapseExtensionUrls", () => {
+  it("collapses chrome- and moz-extension origins to a stable token", () => {
+    const stack =
+      "at f (chrome-extension://abcdefghabcdefghabcdefghabcdefgh/content.js:1:2)\n" +
+      "at g (moz-extension://1234-5678/background.js:3:4)";
+    const out = collapseExtensionUrls(stack);
+    expect(out).not.toContain("abcdefghabcdefghabcdefghabcdefgh");
+    expect(out).toContain("extension://content.js:1:2");
+    expect(out).toContain("extension://background.js:3:4");
+  });
+});
+
+describe("normalizeError", () => {
+  it("normalizes an Error and collapses extension urls in the stack", () => {
+    const err = new TypeError("boom");
+    err.stack = "TypeError: boom\n at chrome-extension://aaaa/bg.js:1:1";
+    const out = normalizeError(err);
+    expect(out.name).toBe("TypeError");
+    expect(out.message).toBe("boom");
+    expect(out.stack).toContain("extension://bg.js");
+    expect(out.stack).not.toContain("chrome-extension://aaaa");
+  });
+
+  it("handles thrown strings and non-error values", () => {
+    expect(normalizeError("oops").message).toBe("oops");
+    expect(normalizeError({ a: 1 }).name).toBe("NonError");
+  });
+});
+
+describe("sanitizeProperties", () => {
+  it("drops keys not in the allow-list and keeps allowed ones", () => {
+    const out = sanitizeProperties({
+      command: "bg:startAgent",
+      email: "user@example.com", // not allow-listed -> dropped
+      mode: "single",
+    });
+    expect(out).toEqual({ command: "bg:startAgent", mode: "single" });
+    expect(out).not.toHaveProperty("email");
+  });
+
+  it("collapses extension urls inside property values", () => {
+    const out = sanitizeProperties({
+      context: "failed at chrome-extension://aaaabbbbccccddddeeeeffffgggghhhh/x.js",
+    });
+    expect(out?.context).toContain("extension://x.js");
+    expect(out?.context).not.toContain("aaaabbbbccccddddeeeeffffgggghhhh");
+  });
+
+  it("caps over-long values at 8192 chars", () => {
+    const out = sanitizeProperties({ host: "x".repeat(9000) });
+    expect(out?.host).toHaveLength(8192);
+  });
+
+  it("drops allow-listed keys whose value is null/undefined", () => {
+    const out = sanitizeProperties({
+      host: "app.intuned.io",
+      pathname: null as unknown as string,
+      method: undefined as unknown as string,
+    });
+    expect(out).toEqual({ host: "app.intuned.io" });
+  });
+
+  it("coerces non-string allowed values to strings", () => {
+    const out = sanitizeProperties({ ok: true as unknown as string });
+    expect(out?.ok).toBe("true");
+  });
+
+  it("returns undefined when nothing survives", () => {
+    expect(sanitizeProperties({ email: "a@b.c" })).toBeUndefined();
+    expect(sanitizeProperties(undefined)).toBeUndefined();
+  });
+});
+
+describe("sanitizeMeasurements", () => {
+  it("keeps finite numbers and drops the rest", () => {
+    expect(
+      sanitizeMeasurements({ durationMs: 12, bad: NaN, inf: Infinity })
+    ).toEqual({ durationMs: 12 });
+    expect(sanitizeMeasurements(undefined)).toBeUndefined();
+  });
+});
diff --git a/wxt.config.ts b/wxt.config.ts
index a398668..318c3cf 100644
--- a/wxt.config.ts
+++ b/wxt.config.ts
@@ -1,15 +1,6 @@
 import { defineConfig } from "wxt";
 
-// Pins the Chrome extension ID to `kagnpahelafjcmmbbcinolcjldclchnc` for
-// unpacked/--load-extension installs, so external tooling can find the
-// background worker by URL prefix. Chrome derives the ID from a hash of this
-// RSA public key, so the value must be the key itself — it cannot be a
-// friendly name. Keep in sync with SELECTOR_EXTENSION_ID in
-// apps/intuned-cli/src/lib/browser/extensionTransport/constants.ts.
-// Public key only; the private key (needed solely for .crx packing) lives
-// in 1Password ("selector-extension signing key").
-const intunedSelectorKey =
-  "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAqlaqz8lsLEWGz3ETXFvNS82pmHsnDu/FZ7M+17Owi+Vt/QUkEv8REeQkOm4PiHqZHmyHsPXjAdADCJBWdXFAWWh9hIBxCxcczN/kkrvIY6GSFausVrG5thvmRhU4l74FbLBwX0qfHJ9UXfkmxDbjVL+lDQACZfmgpJpuHTw/P8QYR9lHc9CVpi5bYrwTozKwN4qNhGQCuMA148bKNXIa7ldt7pQ8xHdwziD9Q4ZIFOESjdFkHn/VlFR/7gtd2ZddTBOmIGw5r+no6u+FDQ61FXQ47yyyYP2DBSU+wTgho62C1AGQd5VE3f+2YYvxET62Bv5JqZV6M/sJgZ6g6hrFAwIDAQAB";
+const appInsightsHost = "https://westus2-2.in.applicationinsights.azure.com/*";
 
 // Chrome MV3 + Firefox MV3.
 export default defineConfig({
@@ -38,6 +29,7 @@ export default defineConfig({
       host_permissions: [
         "https://app.intuned.io/*",
         "https://metricsshop.hasura.app/v1/graphql",
+        appInsightsHost,
       ],
     };
 
@@ -54,8 +46,6 @@ export default defineConfig({
           id: "selector@intunedhq.com",
         },
       };
-    } else {
-      manifest.key = intunedSelectorKey;
     }
 
     return manifest;
diff --git a/yarn.lock b/yarn.lock
index 13bb666..cd7d982 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -841,6 +841,43 @@
   dependencies:
     "@types/mdx" "^2.0.0"
 
+"@microsoft/applicationinsights-channel-js@2.8.9":
+  version "2.8.9"
+  resolved "https://registry.yarnpkg.com/@microsoft/applicationinsights-channel-js/-/applicationinsights-channel-js-2.8.9.tgz#840656f3c716de8b3eb0a98c122aa1b92bb8ebfb"
+  integrity sha512-fMBsAEB7pWtPn43y72q9Xy5E5y55r6gMuDQqRRccccVoQDPXyS57VCj5IdATblctru0C6A8XpL2vRyNmEsu0Vg==
+  dependencies:
+    "@microsoft/applicationinsights-common" "2.8.9"
+    "@microsoft/applicationinsights-core-js" "2.8.9"
+    "@microsoft/applicationinsights-shims" "2.0.2"
+    "@microsoft/dynamicproto-js" "^1.1.7"
+
+"@microsoft/applicationinsights-common@2.8.9":
+  version "2.8.9"
+  resolved "https://registry.yarnpkg.com/@microsoft/applicationinsights-common/-/applicationinsights-common-2.8.9.tgz#a75e4a3143a7fd797687830c0ddd2069fd900827"
+  integrity sha512-mObn1moElyxZaGIRF/IU3cOaeKMgxghXnYEoHNUCA2e+rNwBIgxjyKkblFIpmGuHf4X7Oz3o3yBWpaC6AoMpig==
+  dependencies:
+    "@microsoft/applicationinsights-core-js" "2.8.9"
+    "@microsoft/applicationinsights-shims" "2.0.2"
+    "@microsoft/dynamicproto-js" "^1.1.7"
+
+"@microsoft/applicationinsights-core-js@2.8.9":
+  version "2.8.9"
+  resolved "https://registry.yarnpkg.com/@microsoft/applicationinsights-core-js/-/applicationinsights-core-js-2.8.9.tgz#0e5d207acfae6986a6fc97249eeb6117e523bf1b"
+  integrity sha512-HRuIuZ6aOWezcg/G5VyFDDWGL8hDNe/ljPP01J7ImH2kRPEgbtcfPSUMjkamGMefgdq81GZsSoC/NNGTP4pp2w==
+  dependencies:
+    "@microsoft/applicationinsights-shims" "2.0.2"
+    "@microsoft/dynamicproto-js" "^1.1.7"
+
+"@microsoft/applicationinsights-shims@2.0.2":
+  version "2.0.2"
+  resolved "https://registry.yarnpkg.com/@microsoft/applicationinsights-shims/-/applicationinsights-shims-2.0.2.tgz#92b36a09375e2d9cb2b4203383b05772be837085"
+  integrity sha512-PoHEgsnmcqruLNHZ/amACqdJ6YYQpED0KSRe6J7gIJTtpZC1FfFU9b1fmDKDKtFoUSrPzEh1qzO3kmRZP0betg==
+
+"@microsoft/dynamicproto-js@^1.1.7":
+  version "1.1.11"
+  resolved "https://registry.yarnpkg.com/@microsoft/dynamicproto-js/-/dynamicproto-js-1.1.11.tgz#c737e1a50db9453354729ddaeb2c3b16927ed92e"
+  integrity sha512-gNw9z9LbqLV+WadZ6/MMrWwO3e0LuoUH1wve/1iPsBNbgqeVCiB0EZFNNj2lysxS2gkqoF9hmyVaG3MoM1BkxA==
+
 "@mswjs/interceptors@^0.41.3":
   version "0.41.9"
   resolved "https://registry.yarnpkg.com/@mswjs/interceptors/-/interceptors-0.41.9.tgz#9d90bbd60d1ddc30dbcbb827a9bb2e470493530d"