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
HTML agent-harnessagent-orchestrationagentsai-agentsautonomous-agentsclaude-codecodexcoding-agentsdesktop-appdeveloper-toolselectrongemini-cliharnessharness-engineeringlocal-firstmemorymulti-agentopencodeorchestrationtypescript
feat(telemetry): update_applied, so we can see whether auto-update works
Chaitanya Girief548aafe275
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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.mdindex 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 inthe app's user-data directory (`telemetry-install-id`). It is not derivedfrom 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.tsindex 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.cjsnew file mode 100644index 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);+});