Skip to content

an open-source alternative to the dots, bots and muses of the world, run an office of claude code/codex like agents on your laptop, sandboxes or anywhere, uses your existing subscriptions

feat(telemetry): update_applied, so we can see whether auto-update works

Chaitanya Girief548aafe275
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2aa1c901..6118890d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,18 @@ All notable changes to this project are documented here. The format is based on
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [Unreleased]
+
+### Added
+
+- **`update_applied` telemetry.** The app now reports, once, on the first start after its own
+ version changes: `update_applied { from_version, to_version }`. Auto-update health was the one
+ thing we had no way to see — a release is delivered in place, and the only evidence we had was
+ installs that happened to show events on two versions. `from_version` is `unknown` for an
+ install that predates the event, so the first release carrying it is measurable rather than
+ silent for a cycle. Both values are version strings; nothing new about you is collected, the
+ same opt-outs apply, and [`TELEMETRY.md`](TELEMETRY.md) lists it like every other event.
+
## [0.4.4] — 2026-08-18
**Windows agents can finally talk to each other** — and the first run stops silently failing.
diff --git a/TELEMETRY.md b/TELEMETRY.md
index ebcbd489..0512004e 100644
--- a/TELEMETRY.md
+++ b/TELEMETRY.md
@@ -24,6 +24,7 @@ The events:
| --- | --- | --- |
| `first_run` | — | Once, the first time the app ever starts |
| `app_launched` | — | Each app start |
+| `update_applied` | `from_version`, `to_version` — version strings, or `unknown` for an install older than this event | Once, on the first start after the app's version changes |
| `agent_spawned` | `provider` (CLI engine name, e.g. `claude`, `codex`) | An agent terminal is spawned |
| `feature_used` | `feature` — one of `slack_trigger`, `webhook_trigger`, `hire_install`, `voice_dictation` | At most once per feature per app session |
| `session_ended` | `duration_bucket` — one of `<5m`, `5-30m`, `30m-2h`, `2-8h`, `8h+` | On quit (coarse bucket, never raw duration) |
@@ -43,6 +44,10 @@ identifiers, or API keys. Nothing free-form — the property allowlist in
- The only identifier is a **random UUID** minted on first run and stored in
the app's user-data directory (`telemetry-install-id`). It is not derived
from your machine, and deleting the app's data deletes it.
+- The only other thing stored for telemetry is the app version this install
+ last ran (`telemetry-last-version`, beside the install id) — it exists so
+ `update_applied` can name the version you came from, and it is deleted with
+ the app's data in the same way.
- IP-based geolocation is used only to derive a country for aggregate stats;
PostHog does not retain the IP on the event.
diff --git a/src/main/analytics.ts b/src/main/analytics.ts
index 6a49aa39..80ac9a47 100644
--- a/src/main/analytics.ts
+++ b/src/main/analytics.ts
@@ -49,6 +49,12 @@ const EVENTS: Record<string, ReadonlySet<string>> = {
first_run: new Set<string>(),
/** Every app start. The DAU/retention backbone. */
app_launched: new Set<string>(),
+ /** Once per version change, on the first run after the version moved. Both
+ * values are version strings of the same shape as the `app_version` every
+ * event already carries; `from_version` is `unknown` for an install that
+ * predates version stamping (i.e. anything upgrading INTO the first release
+ * that ships this event). */
+ update_applied: new Set<string>(['from_version', 'to_version']),
/** An agent PTY spawned. `provider` is the CLI engine name only. */
agent_spawned: new Set<string>(['provider']),
/** Coarse feature adoption; `feature` is a fixed enum (see FEATURES), fired
@@ -79,11 +85,19 @@ function dntSet(): boolean {
return v !== undefined && v !== '' && v !== '0';
}
-class Analytics {
+/** Exported for the unit test only — index.ts uses the `analytics` singleton
+ * below. Constructing a fresh one is the only way to exercise the once-per-
+ * install paths (first_run, update_applied) more than once in a process. */
+export class Analytics {
private client: PostHog | null = null;
private distinctId = '';
private enabled = false;
private firstRun = false;
+ /** False when the state dir was unwritable and loadOrMintInstallId fell back
+ * to an ephemeral id. Such an install cannot be recognised across boots, so
+ * it must never report a version transition — it would report one on EVERY
+ * boot and inflate the exact number update_applied exists to produce. */
+ private idPersisted = false;
private startedAt = 0;
private sessionEnded = false;
/** Session-scoped dedup for feature_used. */
@@ -119,7 +133,22 @@ class Analytics {
this.client = null;
return;
}
+ // Version-change detection. Read BEFORE the stamp is refreshed, and stamp
+ // BEFORE sending: at-most-once beats at-least-once here, because a
+ // duplicated update_applied would corrupt the very count it exists to
+ // produce, while a lost one costs a single install out of thousands. The
+ // stamp is refreshed for opted-out users too — we record locally and let
+ // track() decide whether anything leaves the machine, so opting back in
+ // never back-fills a transition that happened while we were dark.
+ let transition: VersionTransition | null = null;
+ if (this.idPersisted) {
+ const previous = readVersionStamp(opts.stateDir);
+ transition = updateTransition(previous, opts.appVersion, this.firstRun);
+ if (previous !== opts.appVersion) writeVersionStamp(opts.stateDir, opts.appVersion);
+ }
+
if (this.firstRun) this.track('first_run');
+ if (transition) this.track('update_applied', transition);
this.track('app_launched');
}
@@ -174,12 +203,16 @@ class Analytics {
try {
if (existsSync(file)) {
const id = readFileSync(file, 'utf8').trim();
- if (id) return id;
+ if (id) {
+ this.idPersisted = true;
+ return id;
+ }
}
const id = randomUUID();
mkdirSync(stateDir, { recursive: true });
writeFileSync(file, id + '\n', 'utf8');
this.firstRun = true;
+ this.idPersisted = true;
return id;
} catch (e) {
// Unwritable state dir: use an ephemeral id for this session rather than
@@ -190,6 +223,72 @@ class Analytics {
}
}
+/** The version this install last ran, kept beside the install id in userData.
+ * Deleting the app's data dir clears it exactly like the install id. */
+const VERSION_STAMP_FILE = 'telemetry-last-version';
+
+/** Semver-shaped and nothing else. The stamp is an ordinary file in userData
+ * that a user can edit, so it is re-validated on the way out — that keeps
+ * `from_version` provably closed-form and honours TELEMETRY.md's "nothing
+ * free-form" promise even against a hand-edited state dir. */
+const VERSION_RE = /^[0-9]{1,6}\.[0-9]{1,6}\.[0-9]{1,6}(?:-[0-9A-Za-z.]{1,32})?$/;
+
+/** A type alias, NOT an interface: `track()` takes `Record<string, string>` and
+ * TypeScript only gives object *type aliases* an implicit index signature. */
+export type VersionTransition = {
+ from_version: string;
+ to_version: string;
+};
+
+/** The single place that decides whether a boot is a version change.
+ *
+ * - `firstRun` (the install id was just minted) → a brand-new install, never
+ * an update. This is what keeps update_applied and first_run disjoint.
+ * - no stamp on an install that already had an id → the install predates
+ * version stamping, so it arrived here from SOME earlier version:
+ * `from_version: 'unknown'`. This is what makes the very first release
+ * carrying the event measurable, instead of silent for one whole cycle.
+ * - stamp !== current → a version change (a downgrade reports honestly, with
+ * from > to).
+ * - stamp === current → an ordinary relaunch. Nothing.
+ *
+ * Pure and exported so the decision can be unit-tested without PostHog. */
+export function updateTransition(
+ previous: string | null,
+ current: string,
+ firstRun: boolean
+): VersionTransition | null {
+ if (firstRun) return null;
+ if (!VERSION_RE.test(current)) return null; // can't name where we landed
+ if (previous === current) return null;
+ return {
+ from_version: previous && VERSION_RE.test(previous) ? previous : 'unknown',
+ to_version: current
+ };
+}
+
+/** Raw stamp, or null when absent/unreadable. Never throws. */
+export function readVersionStamp(stateDir: string): string | null {
+ try {
+ const file = join(stateDir, VERSION_STAMP_FILE);
+ if (!existsSync(file)) return null;
+ return readFileSync(file, 'utf8').trim() || null;
+ } catch {
+ return null;
+ }
+}
+
+/** Best-effort. A failed stamp just means the transition may be reported again
+ * next boot; it must never take the app down. */
+export function writeVersionStamp(stateDir: string, version: string): void {
+ try {
+ mkdirSync(stateDir, { recursive: true });
+ writeFileSync(join(stateDir, VERSION_STAMP_FILE), version + '\n', 'utf8');
+ } catch (e) {
+ console.error('[analytics] version stamp persist failed:', e);
+ }
+}
+
/** Coarse, non-identifying session-length label. */
function durationBucket(ms: number): string {
const m = ms / 60_000;
diff --git a/test/update-applied.test.cjs b/test/update-applied.test.cjs
new file mode 100644
index 00000000..3a02ec11
--- /dev/null
+++ b/test/update-applied.test.cjs
@@ -0,0 +1,249 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const loadTs = require('./load-ts.cjs');
+
+// analytics.ts reads __POSTHOG_KEY__ (an electron-vite `define`, absent here)
+// and constructs a real PostHog client. Both are stubbed BEFORE the module is
+// loaded so the class can be driven end to end without a network or a key.
+globalThis.__POSTHOG_KEY__ = 'test-key';
+globalThis.__POSTHOG_HOST__ = 'https://example.invalid';
+delete process.env.DO_NOT_TRACK;
+
+const captured = [];
+class FakePostHog {
+ capture(payload) { captured.push(payload); }
+ async shutdown() {}
+}
+const posthogPath = require.resolve('posthog-node');
+require.cache[posthogPath] = {
+ id: posthogPath, filename: posthogPath, loaded: true, exports: { PostHog: FakePostHog }
+};
+
+const { updateTransition, readVersionStamp, writeVersionStamp, Analytics } =
+ loadTs('src/main/analytics.ts');
+
+function stateDir() {
+ return fs.mkdtempSync(path.join(os.tmpdir(), 'md-update-applied-'));
+}
+
+// ── the decision ────────────────────────────────────────────────────────────
+
+test('a brand-new install is never an update', () => {
+ // first_run and update_applied must stay disjoint, or every new install
+ // double-counts as an upgrade and the auto-update rate is fiction.
+ assert.equal(updateTransition(null, '0.4.5', true), null);
+ assert.equal(updateTransition('0.4.4', '0.4.5', true), null);
+});
+
+test('an ordinary relaunch reports nothing', () => {
+ assert.equal(updateTransition('0.4.5', '0.4.5', false), null);
+});
+
+test('a version change reports both ends', () => {
+ assert.deepEqual(updateTransition('0.4.4', '0.4.5', false), {
+ from_version: '0.4.4',
+ to_version: '0.4.5'
+ });
+});
+
+test('an install that predates stamping reports from unknown', () => {
+ // This is the case that makes the FIRST release carrying the event
+ // measurable: the id file exists (so the app ran before) but no stamp does.
+ assert.deepEqual(updateTransition(null, '0.4.5', false), {
+ from_version: 'unknown',
+ to_version: '0.4.5'
+ });
+});
+
+test('a downgrade is reported honestly, from > to', () => {
+ assert.deepEqual(updateTransition('0.4.6', '0.4.5', false), {
+ from_version: '0.4.6',
+ to_version: '0.4.5'
+ });
+});
+
+test('prerelease versions are a legal shape on both ends', () => {
+ assert.deepEqual(updateTransition('0.4.5-beta.1', '0.4.5', false), {
+ from_version: '0.4.5-beta.1',
+ to_version: '0.4.5'
+ });
+});
+
+// ── the anonymity guarantee ─────────────────────────────────────────────────
+
+test('a hand-edited stamp cannot smuggle a free-form value out', () => {
+ // The stamp is an ordinary file in userData. TELEMETRY.md promises nothing
+ // free-form is ever sent, so anything not semver-shaped degrades to unknown
+ // rather than riding along as a property value.
+ for (const junk of ['/Users/someone/secret-repo', 'not a version', '', '0.4', 'x'.repeat(300)]) {
+ const out = updateTransition(junk, '0.4.5', false);
+ assert.deepEqual(out, { from_version: 'unknown', to_version: '0.4.5' }, `junk: ${junk}`);
+ }
+});
+
+test('an unnameable current version reports nothing at all', () => {
+ // If we cannot say where we landed there is no event worth sending.
+ assert.equal(updateTransition('0.4.4', 'main', false), null);
+ assert.equal(updateTransition('0.4.4', '', false), null);
+});
+
+// ── the stamp on disk ───────────────────────────────────────────────────────
+
+test('a missing stamp reads as null, not as a throw', () => {
+ assert.equal(readVersionStamp(stateDir()), null);
+ assert.equal(readVersionStamp('/nope/does/not/exist'), null);
+});
+
+test('a stamp round-trips and the trailing newline is not part of it', () => {
+ const dir = stateDir();
+ writeVersionStamp(dir, '0.4.5');
+ assert.equal(readVersionStamp(dir), '0.4.5');
+ assert.equal(fs.readFileSync(path.join(dir, 'telemetry-last-version'), 'utf8'), '0.4.5\n');
+});
+
+test('an empty stamp file reads as null', () => {
+ const dir = stateDir();
+ fs.writeFileSync(path.join(dir, 'telemetry-last-version'), '\n');
+ assert.equal(readVersionStamp(dir), null);
+});
+
+test('the stamp lives beside the install id and dies with the data dir', () => {
+ const dir = stateDir();
+ writeVersionStamp(dir, '0.4.5');
+ fs.rmSync(dir, { recursive: true, force: true });
+ assert.equal(readVersionStamp(dir), null);
+});
+
+// ── the sequence a real install walks through ───────────────────────────────
+
+test('upgrade sequence: fires once per version change, never on a relaunch', () => {
+ const dir = stateDir();
+ const fired = [];
+ // firstRun is true only on the boot that mints the id.
+ const boot = (version, firstRun = false) => {
+ const previous = readVersionStamp(dir);
+ const t = updateTransition(previous, version, firstRun);
+ if (previous !== version) writeVersionStamp(dir, version);
+ if (t) fired.push(`${t.from_version}->${t.to_version}`);
+ };
+
+ boot('0.4.4', true); // fresh install
+ boot('0.4.4'); // relaunch
+ boot('0.4.5'); // auto-update lands
+ boot('0.4.5'); // relaunch
+ boot('0.4.5'); // relaunch
+ boot('0.4.6'); // next update
+
+ assert.deepEqual(fired, ['0.4.4->0.4.5', '0.4.5->0.4.6']);
+});
+
+test('the 0.4.4 to 0.4.5 fleet: an existing install with no stamp fires exactly once', () => {
+ const dir = stateDir(); // has an install id, no stamp — the real world
+ const fired = [];
+ const boot = (version) => {
+ const previous = readVersionStamp(dir);
+ const t = updateTransition(previous, version, false);
+ if (previous !== version) writeVersionStamp(dir, version);
+ if (t) fired.push(`${t.from_version}->${t.to_version}`);
+ };
+
+ boot('0.4.5');
+ boot('0.4.5');
+ boot('0.4.5');
+
+ assert.deepEqual(fired, ['unknown->0.4.5']);
+});
+
+
+// ── end to end, through the real class ──────────────────────────────────────
+
+/** One app boot against a persistent stateDir. Returns the events it sent. */
+function bootApp(dir, appVersion, { enabled = true } = {}) {
+ const before = captured.length;
+ new Analytics().init({ stateDir: dir, appVersion, enabled });
+ return captured.slice(before).map((c) => ({ event: c.event, props: c.properties }));
+}
+
+test('e2e: a fresh install sends first_run and app_launched, never update_applied', () => {
+ const names = bootApp(stateDir(), '0.4.5').map((e) => e.event);
+ assert.deepEqual(names, ['first_run', 'app_launched']);
+});
+
+test('e2e: an existing 0.4.4 install starting 0.4.5 reports the upgrade once', () => {
+ const dir = stateDir();
+ bootApp(dir, '0.4.4'); // the install exists and is stamped
+ const second = bootApp(dir, '0.4.5'); // the update lands
+ assert.deepEqual(second.map((e) => e.event), ['update_applied', 'app_launched']);
+ const props = second[0].props;
+ assert.equal(props.from_version, '0.4.4');
+ assert.equal(props.to_version, '0.4.5');
+ assert.equal(props.app_version, '0.4.5'); // common props still stamped
+ assert.equal(props.$process_person_profile, false); // still an anonymous event
+
+ const third = bootApp(dir, '0.4.5'); // relaunch: nothing extra
+ assert.deepEqual(third.map((e) => e.event), ['app_launched']);
+});
+
+test('e2e: a live 0.4.4 install with no stamp reports unknown, exactly once', () => {
+ // The real 0.4.4 -> 0.4.5 fleet: telemetry-install-id exists, no stamp does.
+ const dir = stateDir();
+ fs.writeFileSync(path.join(dir, 'telemetry-install-id'), 'a-uuid-from-0.4.4\n');
+
+ const first = bootApp(dir, '0.4.5');
+ assert.deepEqual(first.map((e) => e.event), ['update_applied', 'app_launched']);
+ assert.equal(first[0].props.from_version, 'unknown');
+
+ assert.deepEqual(bootApp(dir, '0.4.5').map((e) => e.event), ['app_launched']);
+});
+
+test('e2e: an opted-out install sends nothing and is not back-filled on opting in', () => {
+ const dir = stateDir();
+ fs.writeFileSync(path.join(dir, 'telemetry-install-id'), 'a-uuid\n');
+
+ assert.deepEqual(bootApp(dir, '0.4.5', { enabled: false }), []);
+ // The stamp still advanced locally, so opting back in later does NOT replay a
+ // transition that happened while we were dark.
+ assert.equal(readVersionStamp(dir), '0.4.5');
+ assert.deepEqual(bootApp(dir, '0.4.5').map((e) => e.event), ['app_launched']);
+});
+
+test('e2e: DO_NOT_TRACK sends nothing and writes no stamp at all', () => {
+ const dir = stateDir();
+ process.env.DO_NOT_TRACK = '1';
+ try {
+ assert.deepEqual(bootApp(dir, '0.4.5'), []);
+ assert.equal(readVersionStamp(dir), null);
+ assert.equal(fs.existsSync(path.join(dir, 'telemetry-install-id')), false);
+ } finally {
+ delete process.env.DO_NOT_TRACK;
+ }
+});
+
+test('e2e: an unwritable state dir reports no transition, on any boot', () => {
+ // The ephemeral-id fallback cannot recognise the install across boots, so a
+ // version transition here would fire on EVERY launch. It must fire on none.
+ const dir = path.join(os.tmpdir(), 'md-update-applied-file-not-a-dir');
+ fs.writeFileSync(dir, 'x'); // mkdirSync/writeFileSync will throw
+ try {
+ for (let i = 0; i < 3; i++) {
+ assert.deepEqual(bootApp(dir, '0.4.5').map((e) => e.event), ['app_launched']);
+ }
+ } finally {
+ fs.rmSync(dir, { force: true });
+ }
+});
+
+test('e2e: the allowlist still drops a property nobody declared', () => {
+ const a = new Analytics();
+ a.init({ stateDir: stateDir(), appVersion: '0.4.5', enabled: true });
+ const before = captured.length;
+ a.track('update_applied', { from_version: '0.4.4', to_version: '0.4.5', repo_path: '/Users/me/secret' });
+ const props = captured[before].properties;
+ assert.equal(props.from_version, '0.4.4');
+ assert.equal('repo_path' in props, false);
+});