Stamp PostHog app version on every telemetry event

docs/TELEMETRY.md

@@ -33,7 +33,9 @@ there is nothing to compact — an event that also fires on no-ops makes its own
 duration and turn-count averages meaningless.
 
 Common properties attached to every event: a random installation UUID
-(`distinct_id`), `session_id`, `service_version`, `os_type`, `os_arch`, and a
+(`distinct_id`), `session_id`, `$app_version` (PostHog's standard Version
+property, the running package version), `service_version` (same value, kept
+for existing custom-property dashboards), `os_type`, `os_arch`, and a
 `schema_version` for forward compatibility.
 
 Approximate country-level location is derived server-side by PostHog from the

src/telemetry/index.ts

@@ -91,8 +91,8 @@ export function getSessionId(): string {
 
 // Per-event property allowlist. Anything not listed here is stripped before
 // the payload leaves the process. Together with the fixed common properties
-// capture() appends (service_version, os_type, os_arch, schema_version,
-// session_id), this bounds everything telemetry can ever contain.
+// capture() appends ($app_version, service_version, os_type, os_arch,
+// schema_version, session_id), this bounds everything telemetry can ever contain.
 const EVENT_PROPERTY_ALLOWLIST: Record<TelemetryEvent, readonly string[]> = {
   cli_start: [],
   session_end: ["status", "turn_count", "duration_ms", "session_mode", "exit_reason"],
@@ -353,6 +353,10 @@ export function createTelemetry(options: CreateTelemetryOptions): Telemetry {
       timestamp: new Date().toISOString(),
       properties: {
         ...allowedProperties(event, properties),
+        // PostHog's built-in Version breakdown reads $app_version; without it
+        // every event buckets as "Other". service_version is the same value
+        // kept for dashboards that already filter on the custom property.
+        $app_version: pkg.version,
         service_version: pkg.version,
         os_type: process.platform,
         os_arch: process.arch,

tests/unit/telemetry.test.ts

@@ -259,6 +259,9 @@ test("capture payload shape includes distinct_id and common props, with no clien
   expect(body.properties.$geoip_disable).toBeUndefined();
   expect(body.properties.schema_version).toBe(1);
   expect(typeof body.properties.service_version).toBe("string");
+  expect(body.properties.$app_version).toBe(body.properties.service_version);
+  expect(typeof body.properties.$app_version).toBe("string");
+  expect(String(body.properties.$app_version).length).toBeGreaterThan(0);
   expect(body.properties.os_type).toBe(process.platform);
   expect(body.properties.os_arch).toBe(process.arch);
 });