Discard queued telemetry events when the user opts out

Dropping the singleton on opt-out left the outgoing instance's batch
timer armed, so events captured before the toggle would still reach the
network afterwards. Opting out speaks to activity already generated, not
only to activity still to come.

Author: TheGreatAxios

docs/TELEMETRY.md

@@ -46,6 +46,12 @@ Any of the following disables telemetry entirely:
 - `CORBITS_TELEMETRY` set to any falsy value: `0`, `false`, `off`, `no`, or empty
 - `DO_NOT_TRACK=1` (the standard [Console Do Not Track](https://consoledonottrack.com/) convention)
 
+Turning telemetry off also discards whatever is still queued and unsent.
+Events captured earlier in the session but not yet transmitted are thrown
+away at the moment you opt out, not sent on the way out — opting out covers
+the activity you have already generated, not just the activity still to
+come.
+
 Re-enable from the same Telemetry tab or by removing the env var / settings
 override. While an env kill is active the Telemetry tab cannot re-enable —
 the env override always wins, and the attempt is refused rather than

src/telemetry/index.ts

@@ -146,6 +146,12 @@ export type Telemetry = {
   // exit. Callers use this to bound exit against dropped fire-and-forget
   // requests without ever making capture() itself blocking.
   flush(): Promise<void>;
+  // Throws away everything queued and disarms the batch timer, so nothing
+  // captured before this call can ever reach the network. Opting out uses
+  // this: a user who says stop mid-session is saying they do not want the
+  // activity they have already generated sent, which makes discarding the
+  // queue the honest reading of that intent and flushing it a betrayal.
+  discard(): void;
 };
 
 // Fire-and-forget PostHog batch client. Never throws, never blocks the
@@ -260,5 +266,12 @@ export function createTelemetry(options: CreateTelemetryOptions): Telemetry {
     ]);
   }
 
-  return { enabled, capture, flush };
+  // A request already on the wire cannot be unsent, but nothing still held
+  // in memory follows it.
+  function discard(): void {
+    cancelTimer();
+    queue.length = 0;
+  }
+
+  return { enabled, capture, flush, discard };
 }

src/telemetry/singleton.ts

@@ -5,7 +5,12 @@ import type { Telemetry } from "./index.js";
 // than threading it through every intermediate call site. Defaults to a
 // disabled no-op so any code path that runs before index.ts sets it (or in
 // tests) never throws.
-let instance: Telemetry = { enabled: false, capture: () => {}, flush: async () => {} };
+let instance: Telemetry = {
+  enabled: false,
+  capture: () => {},
+  flush: async () => {},
+  discard: () => {},
+};
 
 export function setTelemetry(telemetry: Telemetry): void {
   instance = telemetry;

src/telemetry/toggle.ts

@@ -57,10 +57,14 @@ export function createTelemetryToggleHandler(
       return;
     }
     if (!enabled) {
-      // Opt-out must be immediate and absolute: swap the in-memory singleton
-      // synchronously, before any await, so no capture in flight during the
-      // persistence step below can land on a still-enabled instance, and so
-      // an unhandled rejection from disk I/O can never leave telemetry on.
+      // Opt-out must be immediate and absolute: discard whatever the outgoing
+      // instance has queued (dropping the singleton alone would leave its
+      // batch timer armed to send it anyway), then swap the in-memory
+      // singleton synchronously, before any await, so no capture in flight
+      // during the persistence step below can land on a still-enabled
+      // instance, and so an unhandled rejection from disk I/O can never
+      // leave telemetry on.
+      deps.getTelemetry().discard();
       deps.setTelemetry(
         deps.createTelemetry({ settings: { providers: {}, telemetry: { enabled: false } } }),
       );

tests/unit/telemetry-toggle.test.ts

@@ -56,6 +56,43 @@ test("capture called immediately after toggle-off makes zero fetch calls", () =>
   expect(fetchCalls()).toBe(0);
 });
 
+// Opting out is a statement about activity already generated, not only about
+// activity to come: events captured before the toggle must never be sent
+// afterwards. Dropping the singleton is not enough on its own — the outgoing
+// instance's batch timer would still fire and post its queue — so this test
+// guards the explicit discard. If a future change makes opt-out flush what it
+// was holding, this fails, and that is the point.
+test("opting out discards events captured before the toggle instead of sending them", async () => {
+  let sends = 0;
+  const fetchFn = (() => {
+    sends++;
+    return Promise.resolve(new Response("1", { status: 200 }));
+  }) as unknown as typeof fetch;
+  const { deps, getInstance } = fakeDeps({
+    createTelemetry: (opts) =>
+      createTelemetry({
+        ...opts,
+        env: opts.env ?? {},
+        apiKey: opts.apiKey ?? "test-key",
+        fetchFn,
+        // Short enough that an undiscarded queue would reach the network well
+        // inside this test's wait, rather than passing by outrunning a timer.
+        batch: { intervalMs: 20 },
+      }),
+  });
+  const handler = createTelemetryToggleHandler("/fake/path", deps);
+
+  handler(true);
+  await new Promise((resolve) => setTimeout(resolve, 10));
+  getInstance().capture("cli_start");
+  expect(sends).toBe(0);
+
+  handler(false);
+  await new Promise((resolve) => setTimeout(resolve, 150));
+  expect(getInstance().enabled).toBe(false);
+  expect(sends).toBe(0);
+});
+
 test("save rejection leaves the singleton disabled with no unhandled rejection", async () => {
   const { deps, getInstance } = fakeDeps({
     saveGlobalSettings: async () => {
@@ -90,7 +127,12 @@ test("load failure skips persistence entirely and stays disabled in memory", asy
 test("toggle on while env-killed writes nothing and swaps no instance", async () => {
   let ensureCalled = false;
   let saveCalled = false;
-  const initial: Telemetry = { enabled: false, capture: () => {}, flush: async () => {} };
+  const initial: Telemetry = {
+    enabled: false,
+    capture: () => {},
+    flush: async () => {},
+    discard: () => {},
+  };
   let setInstance: Telemetry | undefined;
   const { deps } = fakeDeps({
     getTelemetry: () => initial,