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.via, read from the log 0.4.4 already writes
Chaitanya Giri64d9942b1d96
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 6118890d..94912236 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -15,6 +15,10 @@ All notable changes to this project are documented here. The format is based oninstall that predates the event, so the first release carrying it is measurable rather thansilent for a cycle. Both values are version strings; nothing new about you is collected, thesame opt-outs apply, and [`TELEMETRY.md`](TELEMETRY.md) lists it like every other event.+ A `via` property says whether the app's own updater installed it (`auto`), something else moved+ the version (`manual`), or there was no update log to read (`unknown`) — read from the update+ log the app already keeps, so it works for installs updating from a version released before+ this one.## [0.4.4] — 2026-08-18diff --git a/TELEMETRY.md b/TELEMETRY.mdindex 0512004e..d2beb9ae 100644--- a/TELEMETRY.md+++ b/TELEMETRY.md@@ -24,7 +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 |+| `update_applied` | `from_version`, `to_version` — version strings, or `unknown` for an install older than this event; `via` — one of `auto` (the app's own updater installed it), `manual`, `unknown` | 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) |@@ -48,6 +48,11 @@ identifiers, or API keys. Nothing free-form — the property allowlist inlast ran (`telemetry-last-version`, beside the install id) — it exists so`update_applied` can name the version you came from, and it is deleted withthe app's data in the same way.+- To set `via`, the app reads its own update log (`updater.log`, kept in the+ same user-data directory) to see whether the version it is now running is the+ one its updater downloaded and you asked it to restart into. Only that+ one-word result leaves the machine — no line, path or message from that log+ is ever sent.- 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 80ac9a47..cfd3f2b3 100644--- a/src/main/analytics.ts+++ b/src/main/analytics.ts@@ -31,7 +31,7 @@* Deliberately free of any `electron` import (paths/version are injected via* init) so it can be smoke-tested as a plain Node module, like telemetry.ts.*/-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';+import { closeSync, existsSync, fstatSync, mkdirSync, openSync, readFileSync, readSync, writeFileSync } from 'node:fs';import { join } from 'node:path';import { randomUUID } from 'node:crypto';import { PostHog } from 'posthog-node';@@ -53,8 +53,9 @@ const EVENTS: Record<string, ReadonlySet<string>> = {* 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']),+ * that ships this event). `via` is a fixed three-value enum saying whether+ * OUR updater moved the version or something else did. */+ update_applied: new Set<string>(['from_version', 'to_version', 'via']),/** 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@@ -137,9 +138,12 @@ export class Analytics {// 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.+ // stamp is refreshed for a user who opted out IN THE APP — we record+ // locally and let track() decide whether anything leaves the machine, so+ // turning it back on never back-fills a transition from the dark period.+ // It is NOT refreshed under DO_NOT_TRACK or without a build key, because+ // init() returns above before anything here runs: those installs write no+ // file at all, and a DNT user who later unsets it reports 'unknown' once.let transition: VersionTransition | null = null;if (this.idPersisted) {const previous = readVersionStamp(opts.stateDir);@@ -148,7 +152,10 @@ export class Analytics {}if (this.firstRun) this.track('first_run');- if (transition) this.track('update_applied', transition);+ if (transition) {+ const via = updateVia(readUpdaterLogTail(opts.stateDir), transition.to_version);+ this.track('update_applied', { ...transition, via });+ }this.track('app_launched');}@@ -289,6 +296,94 @@ export function writeVersionStamp(stateDir: string, version: string): void {}}+/** ── Was it OUR updater, or did the user reinstall by hand? ──────────────────+ *+ * `update_applied` on its own says the version moved; it cannot say what moved+ * it, because an auto-update and a manual re-download both keep userData, keep+ * the install id, and advance the version. The obvious fix is a marker written+ * by the OLD process when the user clicks restart-to-install — but the old+ * process is a build already in the wild, so a marker added now would be+ * useless for exactly the release we need to watch and would only start+ * telling the truth one cycle later.+ *+ * It turns out we do not need a new marker: `updater.ts` has appended one to+ * `updater.log` since v0.3.7, and both lines below are byte-identical in the+ * shipped v0.4.3 and v0.4.4 builds. An auto-update leaves this ordered pair:+ *+ * update downloaded: <version> — waiting for the user to restart+ * quitAndInstall requested by the user+ *+ * Matching on the version is what makes it trustworthy: a leftover pair from a+ * PREVIOUS upgrade names that older version, so it cannot be mistaken for this+ * one. The log is read only to derive the closed enum below — no line, path or+ * message from it is ever sent, and updater.ts is not modified to support this+ * (`test/update-applied.test.cjs` asserts the two literals still match, so a+ * future reword fails the suite instead of silently degrading the metric).+ */+const LOG_FILE = 'updater.log';+const LOG_DOWNLOADED = 'update downloaded: ';+const LOG_QUIT_REQUESTED = 'quitAndInstall requested by the user';+const LOG_QUIT_FAILED = 'quitAndInstall failed:';+/** The log grows by a line or two per update, never on a routine check, so this+ * is years of history — but it is a user-writable file, so the read is bounded+ * rather than trusting. */+const LOG_TAIL_BYTES = 128 * 1024;++/** `auto` our updater installed it, `manual` something else moved the version,+ * `unknown` there is no log to read (and therefore no evidence either way). */+export type UpdateVia = 'auto' | 'manual' | 'unknown';++/** Pure: the whole decision, given the log text and where we landed. */+export function updateVia(logText: string | null, toVersion: string): UpdateVia {+ if (logText === null) return 'unknown';+ const lines = logText.split('\n');+ // The lookahead excludes every character a version can CONTINUE with, so+ // `0.4.5` matches neither `0.4.55` nor the prerelease `0.4.5-beta.1` — both+ // are different builds, and a download of one is no evidence about the other.+ const downloaded = new RegExp(+ `${LOG_DOWNLOADED}${toVersion.replace(/[.*+?^${}()|[\]\\-]/g, '\\$&')}(?![0-9.\\-])`+ );++ // The LAST download of THIS version — anything earlier belongs to a previous+ // upgrade and would name a different version anyway.+ let i = -1;+ for (let n = 0; n < lines.length; n++) if (downloaded.test(lines[n])) i = n;+ if (i < 0) return 'manual';++ // A restart request that came AFTER that download. The log is append-only, so+ // file order is time order.+ let j = -1;+ for (let n = i + 1; n < lines.length; n++) if (lines[n].includes(LOG_QUIT_REQUESTED)) j = n;+ if (j < 0) return 'manual';++ // updater.ts logs the failure from the catch immediately after the request, so+ // an attempt that threw is the very next line — the app never quit, and+ // whatever moved the version afterwards was not us.+ if (lines[j + 1]?.includes(LOG_QUIT_FAILED)) return 'manual';+ return 'auto';+}++/** Last LOG_TAIL_BYTES of updater.log, or null when there is none to read.+ * Never throws — a missing log is an answer ('unknown'), not a failure. */+export function readUpdaterLogTail(stateDir: string): string | null {+ let fd: number | null = null;+ try {+ const file = join(stateDir, LOG_FILE);+ if (!existsSync(file)) return null;+ fd = openSync(file, 'r');+ const size = fstatSync(fd).size;+ if (size === 0) return null;+ const length = Math.min(size, LOG_TAIL_BYTES);+ const buf = Buffer.allocUnsafe(length);+ readSync(fd, buf, 0, length, size - length);+ return buf.toString('utf8');+ } catch {+ return null;+ } finally {+ if (fd !== null) { try { closeSync(fd); } catch { /* nothing left to do */ } }+ }+}+/** 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.cjsindex 3a02ec11..719694c2 100644--- a/test/update-applied.test.cjs+++ b/test/update-applied.test.cjs@@ -24,7 +24,7 @@ require.cache[posthogPath] = {id: posthogPath, filename: posthogPath, loaded: true, exports: { PostHog: FakePostHog }};-const { updateTransition, readVersionStamp, writeVersionStamp, Analytics } =+const { updateTransition, readVersionStamp, writeVersionStamp, updateVia, readUpdaterLogTail, Analytics } =loadTs('src/main/analytics.ts');function stateDir() {@@ -247,3 +247,146 @@ test('e2e: the allowlist still drops a property nobody declared', () => {assert.equal(props.from_version, '0.4.4');assert.equal('repo_path' in props, false);});+++// ── via: was it OUR updater, or a manual reinstall? ─────────────────────────++/** Lines exactly as updater.ts appends them. */+const L = {+ ready: (v) => `[2026-08-20T10:00:00.000Z] native updater ready (current v${v})`,+ downloaded: (v) => `[2026-08-21T10:00:00.000Z] update downloaded: ${v} — waiting for the user to restart`,+ requested: '[2026-08-21T10:05:00.000Z] quitAndInstall requested by the user',+ failed: '[2026-08-21T10:05:00.001Z] quitAndInstall failed: ENOENT',+ downloadErr: '[2026-08-21T09:00:00.000Z] download failed: socket hang up'+};+const log = (...lines) => lines.join('\n') + '\n';++test('via: the ordered pair from our own updater reads as auto', () => {+ assert.equal(updateVia(log(L.ready('0.4.4'), L.downloaded('0.4.5'), L.requested), '0.4.5'), 'auto');+});++test('via: downloaded but never restarted is manual, not auto', () => {+ // The update sat there and the user installed 0.4.5 some other way.+ assert.equal(updateVia(log(L.ready('0.4.4'), L.downloaded('0.4.5')), '0.4.5'), 'manual');+});++test('via: a leftover pair from the PREVIOUS upgrade cannot be mistaken for this one', () => {+ // This is the whole reason the match is version-aware. Without it, anyone who+ // ever used restart-to-install would read as auto forever.+ assert.equal(+ updateVia(log(L.downloaded('0.4.4'), L.requested, L.ready('0.4.4')), '0.4.5'),+ 'manual'+ );+});++test('via: an attempt that threw is manual — the app never quit', () => {+ assert.equal(+ updateVia(log(L.downloaded('0.4.5'), L.requested, L.failed), '0.4.5'),+ 'manual'+ );+});++test('via: a failed attempt followed by a successful one is auto', () => {+ assert.equal(+ updateVia(log(L.downloaded('0.4.5'), L.requested, L.failed, L.requested), '0.4.5'),+ 'auto'+ );+});++test('via: the request must come AFTER the download, not before', () => {+ assert.equal(updateVia(log(L.requested, L.downloaded('0.4.5')), '0.4.5'), 'manual');+});++test('via: no log at all is unknown, never a guess in either direction', () => {+ assert.equal(updateVia(null, '0.4.5'), 'unknown');+ assert.equal(readUpdaterLogTail(stateDir()), null);+ assert.equal(readUpdaterLogTail('/nope/does/not/exist'), null);+});++test('via: an empty log is unknown, a non-empty log with no pair is manual', () => {+ const dir = stateDir();+ fs.writeFileSync(path.join(dir, 'updater.log'), '');+ assert.equal(readUpdaterLogTail(dir), null);+ assert.equal(updateVia(log(L.ready('0.4.4'), L.downloadErr), '0.4.5'), 'manual');+});++test('via: a version prefix does not match a longer version', () => {+ assert.equal(updateVia(log(L.downloaded('0.4.55'), L.requested), '0.4.5'), 'manual');+ assert.equal(updateVia(log(L.downloaded('0.4.5-beta.1'), L.requested), '0.4.5'), 'manual');+ // and the mirror: a stable download is no evidence for a prerelease target+ assert.equal(updateVia(log(L.downloaded('0.4.5'), L.requested), '0.4.5-beta.1'), 'manual');+ assert.equal(updateVia(log(L.downloaded('0.4.5-beta.1'), L.requested), '0.4.5-beta.1'), 'auto');+});++test('via: the log read is bounded and still finds a recent pair', () => {+ const dir = stateDir();+ const filler = Array.from({ length: 20000 }, (_, n) => `[2026-01-01T00:00:00.000Z] noise ${n}`).join('\n');+ fs.writeFileSync(+ path.join(dir, 'updater.log'),+ `${L.downloaded('0.4.4')}\n${filler}\n${L.downloaded('0.4.5')}\n${L.requested}\n`+ );+ const tail = readUpdaterLogTail(dir);+ assert.ok(tail.length <= 128 * 1024);+ assert.ok(tail.length < fs.statSync(path.join(dir, 'updater.log')).size); // actually truncated+ assert.equal(updateVia(tail, '0.4.5'), 'auto');+});++// ── the literals this depends on must stay in updater.ts ────────────────────++test('updater.ts still emits the exact lines via reads', () => {+ // via parses updater.log rather than adding a marker, which is what lets the+ // 0.4.4 -> 0.4.5 hop be measured at all. The cost of that choice is this+ // coupling, so it fails here rather than silently degrading the metric.+ const src = fs.readFileSync(path.join(__dirname, '..', 'src/main/updater.ts'), 'utf8');+ assert.ok(+ src.includes('logLine(`update downloaded: ${info.version}'),+ 'updater.ts no longer logs "update downloaded: <version>" — update analytics.ts LOG_DOWNLOADED'+ );+ assert.ok(+ src.includes("logLine('quitAndInstall requested by the user')"),+ 'updater.ts no longer logs the restart request — update analytics.ts LOG_QUIT_REQUESTED'+ );+ assert.ok(+ src.includes('logLine(`quitAndInstall failed:'),+ 'updater.ts no longer logs the failed attempt — update analytics.ts LOG_QUIT_FAILED'+ );+});++// ── via, end to end ─────────────────────────────────────────────────────────++test('e2e: a real 0.4.4 install that auto-updated reports via auto', () => {+ const dir = stateDir();+ fs.writeFileSync(path.join(dir, 'telemetry-install-id'), 'a-uuid-from-0.4.4\n');+ fs.writeFileSync(path.join(dir, 'updater.log'), log(L.downloaded('0.4.5'), L.requested));++ const sent = bootApp(dir, '0.4.5');+ assert.deepEqual(sent.map((e) => e.event), ['update_applied', 'app_launched']);+ assert.equal(sent[0].props.from_version, 'unknown');+ assert.equal(sent[0].props.via, 'auto');+});++test('e2e: the same install reinstalled by hand reports via manual', () => {+ const dir = stateDir();+ fs.writeFileSync(path.join(dir, 'telemetry-install-id'), 'a-uuid-from-0.4.4\n');+ fs.writeFileSync(path.join(dir, 'updater.log'), log(L.ready('0.4.4')));++ assert.equal(bootApp(dir, '0.4.5')[0].props.via, 'manual');+});++test('e2e: an install with no updater.log reports via unknown', () => {+ const dir = stateDir();+ fs.writeFileSync(path.join(dir, 'telemetry-install-id'), 'a-uuid-from-0.4.4\n');+ assert.equal(bootApp(dir, '0.4.5')[0].props.via, 'unknown');+});++test('e2e: via is only ever one of the three enum values', () => {+ const dir = stateDir();+ fs.writeFileSync(path.join(dir, 'telemetry-install-id'), 'a-uuid\n');+ fs.writeFileSync(path.join(dir, 'updater.log'), log(L.downloaded('0.4.5'), L.requested));+ const props = bootApp(dir, '0.4.5')[0].props;+ assert.ok(['auto', 'manual', 'unknown'].includes(props.via));+ // and nothing from the log itself rode along+ assert.deepEqual(Object.keys(props).sort(), [+ '$process_person_profile', 'app_version', 'arch', 'from_version', 'os', 'to_version', 'via'+ ]);+});