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.via, read from the log 0.4.4 already writes

Chaitanya Giri64d9942b1d96
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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 on
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.
+ 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-18
diff --git a/TELEMETRY.md b/TELEMETRY.md
index 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 in
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.
+- 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.ts
index 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.cjs
index 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'
+ ]);
+});