Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

[CHOO-2394] console: record the launch off the boot path (#683)

Christian McDermotta2682e775353
diff --git a/console/apps/switch-console-desktop/src/main/core/settings/controller.telemetry.test.ts b/console/apps/switch-console-desktop/src/main/core/settings/controller.telemetry.test.ts
index 374dfd939..d07614ed1 100644
--- a/console/apps/switch-console-desktop/src/main/core/settings/controller.telemetry.test.ts
+++ b/console/apps/switch-console-desktop/src/main/core/settings/controller.telemetry.test.ts
@@ -8,7 +8,9 @@ import { beforeEach, describe, expect, it, vi } from 'vitest';
const { h } = vi.hoisted(() => ({
h: {
trackEvent: vi.fn(),
+ launchInstallKind: vi.fn(),
get: vi.fn(),
+ getWithMeta: vi.fn(),
update: vi.fn(async () => {}),
reset: vi.fn(async () => {}),
resetField: vi.fn(async () => {}),
@@ -16,13 +18,15 @@ const { h } = vi.hoisted(() => ({
}));
vi.mock('@main/core/telemetry/telemetry-service', () => ({ trackEvent: h.trackEvent }));
-vi.mock('@main/core/telemetry/launch-history', () => ({ currentInstallKind: () => 'new' }));
+vi.mock('@main/core/telemetry/launch-history', () => ({
+ launchInstallKind: h.launchInstallKind,
+}));
vi.mock('./settings-service', () => ({
appSettingsService: {
get: h.get,
update: h.update,
getAll: vi.fn(),
- getWithMeta: vi.fn(),
+ getWithMeta: h.getWithMeta,
reset: h.reset,
resetField: h.resetField,
},
@@ -32,9 +36,13 @@ const { appSettingsController } = await import('./controller');
const NEVER_ASKED = { enabled: false, askedAt: null };
+/** The consent report waits for the launch kind, so it lands after `update` returns. */
+const settled = () => new Promise((resolve) => setTimeout(resolve, 0));
+
beforeEach(() => {
vi.clearAllMocks();
h.get.mockResolvedValue(NEVER_ASKED);
+ h.launchInstallKind.mockResolvedValue('new');
});
describe('changing a setting', () => {
@@ -48,6 +56,21 @@ describe('changing a setting', () => {
});
});
+describe('reading a setting', () => {
+ it('passes the value, its defaults and its overrides through, and reports nothing', async () => {
+ const meta = {
+ value: { defaultLocationsDirectory: '/srv/agents' },
+ defaults: { defaultLocationsDirectory: '' },
+ overrides: { defaultLocationsDirectory: '/srv/agents' },
+ };
+ h.getWithMeta.mockResolvedValue(meta);
+
+ expect(await appSettingsController.getWithMeta('localLocation')).toBe(meta);
+ expect(h.getWithMeta).toHaveBeenCalledWith('localLocation');
+ expect(h.trackEvent).not.toHaveBeenCalled();
+ });
+});
+
describe('putting a setting back to its default', () => {
it('reports a whole group being reset', async () => {
await appSettingsController.reset('localLocation');
@@ -85,6 +108,7 @@ describe('putting a setting back to its default', () => {
describe('agreeing to share usage data', () => {
it('reports an agreement given at the first-run prompt', async () => {
await appSettingsController.update('telemetry', { enabled: true, askedAt: 1 } as never);
+ await settled();
expect(h.trackEvent).toHaveBeenCalledWith('telemetry_consent_changed', {
source: 'first_run',
@@ -96,6 +120,7 @@ describe('agreeing to share usage data', () => {
h.get.mockResolvedValue({ enabled: false, askedAt: 1 });
await appSettingsController.update('telemetry', { enabled: true, askedAt: 1 } as never);
+ await settled();
expect(h.trackEvent).toHaveBeenCalledWith('telemetry_consent_changed', {
source: 'settings',
@@ -108,6 +133,7 @@ describe('agreeing to share usage data', () => {
// every send, so this would be dropped anyway; the point is that we do not
// try to transmit something from someone at the moment they said not to.
await appSettingsController.update('telemetry', { enabled: false, askedAt: 1 } as never);
+ await settled();
const names = h.trackEvent.mock.calls.map(([name]) => name);
expect(names).not.toContain('telemetry_consent_changed');
@@ -117,6 +143,7 @@ describe('agreeing to share usage data', () => {
h.get.mockResolvedValue({ enabled: true, askedAt: 1 });
await appSettingsController.update('telemetry', { enabled: false, askedAt: 1 } as never);
+ await settled();
const names = h.trackEvent.mock.calls.map(([name]) => name);
expect(names).not.toContain('telemetry_consent_changed');
@@ -128,6 +155,7 @@ describe('agreeing to share usage data', () => {
h.get.mockResolvedValue({ enabled: true, askedAt: 1 });
await appSettingsController.update('telemetry', { enabled: true, askedAt: 1 } as never);
+ await settled();
const names = h.trackEvent.mock.calls.map(([name]) => name);
expect(names).not.toContain('telemetry_consent_changed');
@@ -141,7 +169,58 @@ describe('agreeing to share usage data', () => {
});
await appSettingsController.update('telemetry', { enabled: true, askedAt: 1 } as never);
+ await settled();
expect(order).toEqual(['write', 'report']);
});
+
+ it('still saves telemetry when the previous answer cannot be read, and claims no agreement', async () => {
+ // The read is only there to tell a first agreement from a later one. It
+ // failing must never stop someone turning telemetry off.
+ h.get.mockRejectedValue(new Error('database is locked'));
+
+ await appSettingsController.update('telemetry', { enabled: false, askedAt: 1 } as never);
+ await appSettingsController.update('telemetry', { enabled: true, askedAt: 1 } as never);
+ await settled();
+
+ expect(h.update).toHaveBeenCalledTimes(2);
+ const names = h.trackEvent.mock.calls.map(([name]) => name);
+ expect(names).toEqual(['setting_changed', 'setting_changed']);
+ });
+
+ it('waits for the launch kind when the first-run notice is answered before boot records it', async () => {
+ // Boot records the launch without waiting on it, so a slow database can let
+ // someone answer first. Reading too early would send a kind nobody worked
+ // out, on an event an install only ever sends once.
+ let recorded: (kind: 'new') => void = () => {};
+ h.launchInstallKind.mockReturnValue(new Promise((resolve) => (recorded = resolve)));
+
+ await appSettingsController.update('telemetry', { enabled: true, askedAt: 1 } as never);
+ await settled();
+
+ expect(h.update).toHaveBeenCalled();
+ expect(h.trackEvent.mock.calls.map(([name]) => name)).not.toContain(
+ 'telemetry_consent_changed'
+ );
+
+ recorded('new');
+ await settled();
+
+ expect(h.trackEvent).toHaveBeenCalledWith('telemetry_consent_changed', {
+ source: 'first_run',
+ install_kind: 'new',
+ });
+ });
+
+ it('reports the launch kind it is given, unknown included', async () => {
+ h.launchInstallKind.mockResolvedValue('unknown');
+
+ await appSettingsController.update('telemetry', { enabled: true, askedAt: 1 } as never);
+ await settled();
+
+ expect(h.trackEvent).toHaveBeenCalledWith('telemetry_consent_changed', {
+ source: 'first_run',
+ install_kind: 'unknown',
+ });
+ });
});
diff --git a/console/apps/switch-console-desktop/src/main/core/settings/controller.ts b/console/apps/switch-console-desktop/src/main/core/settings/controller.ts
index b84c9fb8e..582ffe8f0 100644
--- a/console/apps/switch-console-desktop/src/main/core/settings/controller.ts
+++ b/console/apps/switch-console-desktop/src/main/core/settings/controller.ts
@@ -1,5 +1,5 @@
import type { TelemetrySettingKey } from '@main/core/telemetry/events';
-import { currentInstallKind } from '@main/core/telemetry/launch-history';
+import { launchInstallKind } from '@main/core/telemetry/launch-history';
import { trackEvent } from '@main/core/telemetry/telemetry-service';
import type { TelemetrySettings } from '@shared/core/app-settings';
import { createRPCController } from '@shared/lib/ipc/rpc';
@@ -17,15 +17,16 @@ import { appSettingsService, type AppSettings, type AppSettingsKey } from './set
*
* Nothing is reported when the answer has not changed, so re-saving an unrelated
* part of the settings does not look like a fresh agreement.
+ *
+ * Waits for this launch's kind, which boot records without waiting, so the
+ * first-run notice can be answered first. Never rejects.
*/
-function reportConsent(previous: TelemetrySettings, next: TelemetrySettings): void {
+async function reportConsent(previous: TelemetrySettings, next: TelemetrySettings): Promise<void> {
if (!next.enabled || next.askedAt === null) return;
if (previous.enabled && previous.askedAt !== null) return;
- trackEvent('telemetry_consent_changed', {
- source: previous.askedAt === null ? 'first_run' : 'settings',
- install_kind: currentInstallKind(),
- });
+ const source = previous.askedAt === null ? 'first_run' : 'settings';
+ trackEvent('telemetry_consent_changed', { source, install_kind: await launchInstallKind() });
}
export const appSettingsController = createRPCController({
@@ -51,7 +52,7 @@ export const appSettingsController = createRPCController({
await appSettingsService.update(key, value);
trackEvent('setting_changed', { setting_key: key as TelemetrySettingKey });
- if (previousTelemetry) reportConsent(previousTelemetry, value as TelemetrySettings);
+ if (previousTelemetry) void reportConsent(previousTelemetry, value as TelemetrySettings);
},
/**
diff --git a/console/apps/switch-console-desktop/src/main/core/telemetry/events.ts b/console/apps/switch-console-desktop/src/main/core/telemetry/events.ts
index 670e52cab..d102ea7e5 100644
--- a/console/apps/switch-console-desktop/src/main/core/telemetry/events.ts
+++ b/console/apps/switch-console-desktop/src/main/core/telemetry/events.ts
@@ -581,8 +581,11 @@ export type TelemetryEventMap = {
*/
telemetry_consent_changed: {
source: 'first_run' | 'settings';
- /** This launch's kind, so a new install agreeing at first run is one filter. */
- install_kind: TelemetryInstallKind;
+ /**
+ * This launch's kind, so a new install agreeing at first run is one filter;
+ * `unknown` when the launch could not be recorded.
+ */
+ install_kind: TelemetryInstallKind | 'unknown';
};
};
diff --git a/console/apps/switch-console-desktop/src/main/core/telemetry/launch-history.test.ts b/console/apps/switch-console-desktop/src/main/core/telemetry/launch-history.test.ts
index bc04e4cde..18bc82631 100644
--- a/console/apps/switch-console-desktop/src/main/core/telemetry/launch-history.test.ts
+++ b/console/apps/switch-console-desktop/src/main/core/telemetry/launch-history.test.ts
@@ -1,9 +1,34 @@
-import { describe, expect, it, vi } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type * as LaunchHistory from './launch-history';
+const h = vi.hoisted(() => ({
+ trackEvent: vi.fn(),
+ warn: vi.fn(),
+ readFails: false,
+ isCanary: false,
+ databaseExisted: true,
+}));
+
+vi.mock('./telemetry-service', () => ({ trackEvent: h.trackEvent }));
+vi.mock('@main/core/app/utils', () => ({ resolveAppVersion: async () => '2.3.0' }));
+vi.mock('@shared/app-identity', () => ({
+ get IS_CANARY() {
+ return h.isCanary;
+ },
+}));
+vi.mock('@main/db/client', () => ({
+ get databaseExistedAtStart() {
+ return h.databaseExisted;
+ },
+}));
+vi.mock('@main/lib/logger', () => ({ log: { warn: h.warn } }));
vi.mock('@main/db/kv', () => ({
KV: class {
private values = new Map<string, unknown>();
async get(key: string) {
+ if (h.readFails) throw new Error('SQLITE_BUSY: database is locked');
return this.values.get(key) ?? null;
}
async set(key: string, value: unknown) {
@@ -54,3 +79,171 @@ describe('canary and stable, which share one database', () => {
expect(await launch('canary', '1.5.0-canary.3')).toBe('updated');
});
});
+
+describe('reporting a launch at boot', () => {
+ // A fresh module per test: the launch record and this launch's kind are
+ // module state, and one test's launch would otherwise be the next one's last.
+ let launches: typeof LaunchHistory;
+
+ beforeEach(async () => {
+ vi.resetModules();
+ h.trackEvent.mockClear();
+ h.warn.mockClear();
+ h.readFails = false;
+ launches = await import('./launch-history');
+ });
+
+ const firstLaunch = async () => ({
+ version: '2.0.0',
+ channel: 'stable' as const,
+ databaseExisted: false,
+ });
+
+ it('sends app_launched with the kind it recorded', async () => {
+ await launches.reportLaunch(firstLaunch);
+ await launches.reportLaunch(firstLaunch);
+
+ expect(h.trackEvent.mock.calls).toEqual([
+ ['app_launched', { install_kind: 'new' }],
+ ['app_launched', { install_kind: 'same' }],
+ ]);
+ });
+
+ it('never rejects when the launch cannot be recorded, so boot is not held up', async () => {
+ // Boot starts this without waiting on it; a rejection would be unhandled,
+ // and an awaited one would stop everything after it, the window included.
+ h.readFails = true;
+
+ await expect(launches.reportLaunch(firstLaunch)).resolves.toBeUndefined();
+
+ expect(h.trackEvent).not.toHaveBeenCalled();
+ expect(h.warn).toHaveBeenCalledWith(
+ expect.stringContaining('could not record this launch'),
+ expect.objectContaining({ error: expect.any(Error) })
+ );
+ });
+
+ it('never rejects when what it reads to record the launch fails', async () => {
+ await expect(
+ launches.reportLaunch(async () => {
+ throw new Error('package.json unreadable');
+ })
+ ).resolves.toBeUndefined();
+
+ expect(h.trackEvent).not.toHaveBeenCalled();
+ });
+});
+
+describe('asking for this launch’s kind', () => {
+ let launches: typeof LaunchHistory;
+
+ beforeEach(async () => {
+ vi.resetModules();
+ h.warn.mockClear();
+ h.readFails = false;
+ launches = await import('./launch-history');
+ });
+
+ it('is the kind boot recorded', async () => {
+ await launches.reportLaunch(async () => ({
+ version: '2.0.0',
+ channel: 'stable',
+ databaseExisted: false,
+ }));
+
+ expect(await launches.launchInstallKind()).toBe('new');
+ });
+
+ it('waits for a recording boot started but has not finished', async () => {
+ // Boot does not wait for the recording, so the first-run notice can be
+ // answered while it is still reading the database.
+ let read: (inputs: {
+ version: string;
+ channel: 'stable';
+ databaseExisted: boolean;
+ }) => void = () => {};
+ void launches.reportLaunch(() => new Promise((resolve) => (read = resolve)));
+
+ const asked = launches.launchInstallKind();
+ read({ version: '2.0.0', channel: 'stable', databaseExisted: true });
+
+ expect(await asked).toBe('updated');
+ });
+
+ it('is unknown, never a guessed kind, when the launch could not be recorded', async () => {
+ h.readFails = true;
+ await launches.reportLaunch(async () => ({
+ version: '2.0.0',
+ channel: 'stable',
+ databaseExisted: false,
+ }));
+
+ expect(await launches.launchInstallKind()).toBe('unknown');
+ });
+
+ it('is unknown, and says so, when nothing recorded this launch', async () => {
+ expect(await launches.launchInstallKind()).toBe('unknown');
+ expect(h.warn).toHaveBeenCalledWith(
+ expect.stringContaining('nothing has recorded this launch')
+ );
+ });
+});
+
+describe('what boot records the launch from', () => {
+ let launches: typeof LaunchHistory;
+
+ beforeEach(() => {
+ vi.resetModules();
+ h.trackEvent.mockClear();
+ h.readFails = false;
+ });
+
+ const load = async ({
+ isCanary,
+ databaseExisted,
+ }: {
+ isCanary: boolean;
+ databaseExisted: boolean;
+ }) => {
+ h.isCanary = isCanary;
+ h.databaseExisted = databaseExisted;
+ launches = await import('./launch-history');
+ };
+
+ it('is the app version, the stable channel, and whether the database was already there', async () => {
+ await load({ isCanary: false, databaseExisted: true });
+
+ expect(await launches.readThisLaunch()).toEqual({
+ version: '2.3.0',
+ channel: 'stable',
+ databaseExisted: true,
+ });
+ });
+
+ it('is the canary channel in a canary build, so the two keep separate records', async () => {
+ await load({ isCanary: true, databaseExisted: false });
+
+ expect(await launches.readThisLaunch()).toEqual({
+ version: '2.3.0',
+ channel: 'canary',
+ databaseExisted: false,
+ });
+ });
+
+ it('reports a fresh install as new', async () => {
+ await load({ isCanary: false, databaseExisted: false });
+
+ await launches.reportLaunch(launches.readThisLaunch);
+
+ expect(h.trackEvent).toHaveBeenCalledWith('app_launched', { install_kind: 'new' });
+ });
+
+ it('is started by boot without being waited on', () => {
+ // Boot has no tests of its own, so this reads it. Waiting on the launch
+ // would put a database read and write in front of the window opening.
+ const boot = readFileSync(join(import.meta.dirname, '..', '..', 'index.ts'), 'utf8');
+
+ expect(boot).toContain('void reportLaunch(readThisLaunch);');
+ expect(boot).not.toMatch(/await\s+reportLaunch\b/);
+ });
+});
diff --git a/console/apps/switch-console-desktop/src/main/core/telemetry/launch-history.ts b/console/apps/switch-console-desktop/src/main/core/telemetry/launch-history.ts
index 97d2b8e20..d8f58130e 100644
--- a/console/apps/switch-console-desktop/src/main/core/telemetry/launch-history.ts
+++ b/console/apps/switch-console-desktop/src/main/core/telemetry/launch-history.ts
@@ -1,6 +1,9 @@
+import { resolveAppVersion } from '@main/core/app/utils';
import { KV } from '@main/db/kv';
import { log } from '@main/lib/logger';
+import { IS_CANARY } from '@shared/app-identity';
import type { TelemetryInstallKind } from './events';
+import { trackEvent } from './telemetry-service';
/**
* Which kind of launch this is, from what the last launch recorded.
@@ -31,7 +34,18 @@ export function installKindFor({
*/
const store = new KV<Record<string, string>>('telemetry-launches');
-let current: TelemetryInstallKind | null = null;
+/**
+ * This launch's recording, once boot has started it. Kept as the promise rather
+ * than its result, because boot does not wait for it and something can ask
+ * before it settles. Settles to null when the launch could not be recorded.
+ */
+let recording: Promise<TelemetryInstallKind | null> | null = null;
+
+type LaunchInputs = {
+ version: string;
+ channel: 'canary' | 'stable';
+ databaseExisted: boolean;
+};
/**
* Record this launch and say which kind it is. Recorded on every launch,
@@ -42,28 +56,50 @@ export async function recordLaunch({
version,
channel,
databaseExisted,
-}: {
- version: string;
- channel: 'canary' | 'stable';
- databaseExisted: boolean;
-}): Promise<TelemetryInstallKind> {
+}: LaunchInputs): Promise<TelemetryInstallKind> {
const key = `lastLaunchedVersion.${channel}`;
const lastVersion = (await store.get(key)) ?? null;
- current = installKindFor({ lastVersion, version, databaseExisted });
+ const kind = installKindFor({ lastVersion, version, databaseExisted });
await store.set(key, version);
- return current;
+ return kind;
+}
+
+/** What recording this launch needs, read when boot starts it. */
+export async function readThisLaunch(): Promise<LaunchInputs> {
+ return {
+ version: await resolveAppVersion(),
+ channel: IS_CANARY ? 'canary' : 'stable',
+ // Imported here, not at the top: the client opens the database on import.
+ databaseExisted: (await import('@main/db/client')).databaseExistedAtStart,
+ };
+}
+
+/**
+ * Record this launch and report it as `app_launched`. Never rejects, so boot
+ * can start it without waiting on it: nothing telemetry does may stop the app
+ * opening. A launch that cannot be recorded is logged and goes unreported,
+ * rather than reported with a kind nobody worked out.
+ */
+export async function reportLaunch(read: () => Promise<LaunchInputs>): Promise<void> {
+ const recorded = (async () => recordLaunch(await read()))();
+ recording = recorded.catch(() => null);
+ try {
+ trackEvent('app_launched', { install_kind: await recorded });
+ } catch (error) {
+ log.warn('telemetry: could not record this launch, so app_launched is not sent', { error });
+ }
}
/**
- * This launch's kind. Boot records it before any window opens, so nothing a
- * person does can ask first; if something does, it is said in the log rather
- * than passed off as a real answer, and reads as `same`, the kind that claims
- * nothing.
+ * This launch's kind, waited for rather than read: boot does not wait for the
+ * recording, so the window can open and the first-run notice be answered before
+ * the database has said. Never rejects. A launch that could not be recorded, or
+ * that nothing started recording, is `unknown` — never a kind nobody worked out.
*/
-export function currentInstallKind(): TelemetryInstallKind {
- if (current === null) {
- log.warn('telemetry: install kind read before this launch was recorded');
- return 'same';
+export async function launchInstallKind(): Promise<TelemetryInstallKind | 'unknown'> {
+ if (recording === null) {
+ log.warn('telemetry: install kind asked for, but nothing has recorded this launch');
+ return 'unknown';
}
- return current;
+ return (await recording) ?? 'unknown';
}
diff --git a/console/apps/switch-console-desktop/src/main/index.ts b/console/apps/switch-console-desktop/src/main/index.ts
index 9aafd68d7..f02947cee 100644
--- a/console/apps/switch-console-desktop/src/main/index.ts
+++ b/console/apps/switch-console-desktop/src/main/index.ts
@@ -4,7 +4,7 @@ import { setTimeout as delay } from 'node:timers/promises';
import { config as dotenvConfig } from 'dotenv';
import { app, BrowserWindow, dialog, ipcMain, powerMonitor } from 'electron';
import dockIcon from '@/assets/images/switch-console/icon-dock.png?asset';
-import { IS_CANARY, PRODUCT_NAME } from '@shared/app-identity';
+import { PRODUCT_NAME } from '@shared/app-identity';
import { registerRPCRouter } from '@shared/lib/ipc/rpc';
import { flushPendingDeeplink, setupDeeplinks } from './app/deeplinks';
import { setupApplicationMenu } from './app/menu';
@@ -15,7 +15,6 @@ import { setAgentStorageMigrationReady } from './core/agents/agent-storage-migra
import { migrateAgentStorage } from './core/agents/migrate-agent-storage';
import { initializeRemoteDiscovery, initializeRemoteWatchers } from './core/agents/remote-watcher';
import { appService } from './core/app/service';
-import { resolveAppVersion } from './core/app/utils';
import { controlService } from './core/control-api/control-service';
import { localDependencyManager } from './core/dependencies/dependency-managers';
import { embeddedControllerService } from './core/embedded-controller/embedded-controllers';
@@ -35,9 +34,9 @@ import { appSettingsService } from './core/settings/settings-service';
import { sshConnectionManager } from './core/ssh/lifecycle/production-ssh-connection-manager';
import { autoSessionWatcher } from './core/switch-rooms/auto-session-watcher';
import { currentInternalFlag } from './core/telemetry/internal-account';
-import { recordLaunch } from './core/telemetry/launch-history';
+import { readThisLaunch, reportLaunch } from './core/telemetry/launch-history';
import { registerTelemetryListeners } from './core/telemetry/telemetry-listeners';
-import { telemetryService, trackEvent } from './core/telemetry/telemetry-service';
+import { telemetryService } from './core/telemetry/telemetry-service';
import { updateService } from './core/updates/update-service';
import { viewStateService } from './core/view-state/view-state-service';
import { reconcileAllWorkspaces } from './core/workspaces/reconcile-workspaces';
@@ -148,14 +147,7 @@ void app.whenReady().then(async () => {
// before it is sent, and never before the database it is read from.
registerTelemetryListeners();
telemetryService.setInternalSource(currentInternalFlag);
- trackEvent('app_launched', {
- install_kind: await recordLaunch({
- version: await resolveAppVersion(),
- channel: IS_CANARY ? 'canary' : 'stable',
- // Imported here, not at the top: the client opens the database on import.
- databaseExisted: (await import('./db/client')).databaseExistedAtStart,
- }),
- });
+ void reportLaunch(readThisLaunch);
// Kept off the boot path: this can open an SSH/SFTP connection per remote
// agent, so awaiting it here delayed the window opening. Session relaunch below
diff --git a/docs/TELEMETRY.md b/docs/TELEMETRY.md
index 1d235b691..6b8409d0f 100644
--- a/docs/TELEMETRY.md
+++ b/docs/TELEMETRY.md
@@ -108,7 +108,7 @@ id, no IP field, no Switch identity.
| `update_checked` | `trigger`: `user` / `startup` / `scheduled` · `result`: `available` / `up_to_date` / `failed` |
| `update_downloaded` | `outcome`: `success` / `failure` |
| `update_install_started` | `outcome`: `success` / `failure` |
-| `telemetry_consent_changed` | `source`: `first_run` / `settings` · `install_kind`: as on `app_launched` |
+| `telemetry_consent_changed` | `source`: `first_run` / `settings` · `install_kind`: as on `app_launched`, or `unknown` if the launch could not be recorded |
| `setting_changed` | `setting_key`, one of exactly 15: `theme`, `notifications`, `terminal`, `defaultAgent`, `sessions`, `location`, `localLocation`, `openIn`, `interface`, `browser`, `browserPreview`, `changesViewMode`, `remote`, `onboarding`, `telemetry`. **The new value is never sent** — we learn that someone changed their theme, not to what. |
| `search_performed` | `status`: `ok` / `recents` / `query-too-short` / `failed` · `result_count`: `0`, `3`, `17`. **The query is never sent.** |