Proj/analytics system tool mode

.env.example

@@ -8,4 +8,5 @@ BRV_GIT_REMOTE_BASE_URL=http://localhost:8080
 BRV_LLM_BASE_URL=http://localhost:3002
 BRV_WEB_APP_URL=http://localhost:8080
 BRV_BILLING_BASE_URL=http://localhost:3003
+BRV_ANALYTICS_BASE_URL=http://localhost:3004
 BRV_UI_SOURCE=lib

CLAUDE.md

@@ -168,6 +168,61 @@ npm run dev:ui:package               # Vite dev server resolving shared UI from
 - **HTTP (nock)**: Must verify `.matchHeader('authorization', ...)` + `.matchHeader('x-byterover-session-id', ...)`
 - **ES Modules**: Cannot stub ES exports with sinon; test utils with real filesystem (`tmpdir()`)
 
+### M4.7 — analytics e2e against dev-beta (`test/e2e/analytics/dev-beta.e2e.ts`)
+
+End-to-end smoke for the analytics pipeline (M4.1 -> M4.6). One mocha file that spins up an isolated daemon per scenario under a temp `BRV_DATA_DIR` plus a temp `HOME`, exercises one slice via the real `bin/run.js`, and asserts on JSONL `status` transitions plus scenario-specific runtime state. NOT picked up by `npm test` (glob is `test/**/*.test.ts`; this file is `.e2e.ts`).
+
+**Run modes**:
+
+```bash
+npm run test:e2e:analytics                                # all auto scenarios (transition skipped by default)
+npm run test:e2e:analytics -- --grep "1 happy"            # single scenario
+BRV_E2E_TRANSITION=1 npm run test:e2e:analytics -- --grep transition  # interactive login scenario
+BRV_ANALYTICS_BASE_URL=http://127.0.0.1:3001 npm run test:e2e:analytics  # override backend (e.g. local telemetry)
+```
+
+The npm script chains `npm run build && mocha ...` so `dist/` is always fresh when the test starts.
+
+Scenarios covered (`describe` names):
+
+1. `happy` — opt in, emit 1 event, ship within 35s
+2. `burst` — 25 events via `analytics:track`, 20-event threshold flush
+3. `idle` — 1 event, wait 45s for the interval flush
+4. `transition` — anon -> `brv login` -> authed; interactive, gated on `BRV_E2E_TRANSITION=1`
+5. `down` — backend down via inline drop-proxy on a random port; failed flush + backoff counters move
+6. `disable` — ship 1 baseline, disable, queue more, no further ships
+
+**Prereqs**:
+
+- `npm install` (so `bin/run.js` and `node_modules/.bin` are present). `npm link` is NOT required: the test spawns `node <repo>/bin/run.js` directly so it always exercises THIS checkout.
+- `npm run build` is chained in front of mocha inside the npm script; you only need to run it manually if you invoke `mocha` directly without going through `npm run test:e2e:analytics`.
+- Network access to `dev-beta-iam.byterover.dev` and `telemetry-dev.byterover.dev` (the test defaults `BRV_ANALYTICS_BASE_URL` + `BRV_IAM_BASE_URL` to those; override via env to point at a different backend).
+- **Backend on the M4.x wire format**: this CLI sends each event's `created_at` as an ISO 8601 string with a timezone designator (e.g. `2026-05-28T21:32:11+07:00` or `...Z`), per the byterover-telemetry backend contract. The top-level `before()` runs one known-good POST and `this.skip()`s the entire suite with a clear reason if the backend rejects it. Last verified green against `https://telemetry-dev.byterover.dev` on 2026-05-29. If a future deployment regresses to the older numeric `timestamp` (epoch milliseconds) schema, every scenario would FAIL with retry-cap exhaustion - coordinate with the telemetry team before running.
+- For scenario 4: a browser to complete the OAuth login flow.
+
+**Test isolation**: each scenario builds a per-scenario `env` object with a temp `BRV_DATA_DIR` and a temp `HOME` and passes it to every `spawnSync(node, [bin/run.js, ...])`. That isolates the analytics JSONL queue, daemon log, auth token store, and the platform-derived global config path (`~/Library/Application Support/brv/config.json` on macOS) away from the developer's real profile. Teardown uses `brv restart` (with the scenario env) instead of `bin/kill-daemon.js` — `restart` properly cleans the SCENARIO's daemon + state files; calling `kill-daemon.js` without scoped env would read the user's real global `daemon.json` and leak the scenario daemon to the process table. The emit helper temporarily mutates `process.env.BRV_DATA_DIR` / `HOME` because `connectToDaemon` reads them for instance discovery, and restores in `finally` - safe because mocha runs scenarios sequentially. Do NOT pass `--parallel`.
+
+**What "PASS" actually proves**:
+
+The positive signal is `status: pending -> sent` in the JSONL for explicit post-enable test events. That flip happens only when the M4.2 `HttpAnalyticsSender` sees a 2xx response from the backend. So "PASS" means "the backend accepted the batch with 2xx" - sufficient for the M4.7 "events land within 30s" goal.
+
+Scenario 5 covers both halves of the M4.7 "backend down -> recovery" test: Phase A boots a TCP drop-proxy on a random localhost port, points the CLI at it, and asserts `backoff.consecutive_failures > 0` after the first flush tick; Phase B closes the drop-proxy and brings up a HTTP accept-proxy on the SAME port, then polls (up to ~90s, since M4.5 exponential backoff delays the next retry) for `consecutive_failures` to drop back to 0 + at least one row to flip to `status=sent`.
+
+**Postgres-side verification (DoD #7-8) is intentionally NOT in the auto path.** It needs ops-only read credentials that aren't available to the harness. The CLI-side proof (JSONL `status=sent` + backend 2xx) is sufficient for "the pipeline ships and the backend accepts" - asserting the row exists in dev-beta's `raw_events` is a separate ops/manual step. If you have those credentials, the manual SQL is:
+
+```sql
+-- replace device_id with the value from your test's $BRV_DATA_DIR/config.json
+SELECT id, event_name, identity_user_id, identity_device_id, received_at
+FROM raw_events
+WHERE identity_device_id = '<your-device-id>'
+ORDER BY received_at DESC
+LIMIT 25;
+```
+
+**Scenario 4 operator step**: the test prints the exact `HOME=... BRV_DATA_DIR=... BRV_IAM_BASE_URL=... node <repo>/bin/run.js login` command to run in another terminal. Use that exact command so the login writes into the scenario's isolated token/config paths instead of your normal profile.
+
+**Estimated runtime**: ~3 minutes for the auto suite (driven by the 30-45s interval windows in scenarios 3 + 5 + 6).
+
 ## Conventions
 
 - ES modules with `.js` import extensions required

eslint.config.mjs

@@ -23,6 +23,24 @@ export default [
       },
     },
   },
+  {
+    files: ['src/**/*.ts', 'src/**/*.tsx'],
+    ignores: ['src/server/infra/**'],
+    rules: {
+      'no-restricted-imports': [
+        'error',
+        {
+          patterns: [
+            {
+              group: ['**/analytics/i-analytics-client', '**/analytics/i-analytics-client.js'],
+              message:
+                'IAnalyticsClient is daemon-internal. Only code under src/server/infra/ may import it; other consumers should use the transport event analytics:track (M2.6).',
+            },
+          ],
+        },
+      ],
+    },
+  },
   // Web UI (browser environment) — allow browser globals and React naming conventions
   {
     files: ['src/webui/**/*.ts', 'src/webui/**/*.tsx'],

package.json

@@ -34,7 +34,7 @@
     "@ai-sdk/xai": "^2.0.57",
     "@anthropic-ai/sdk": "^0.70.1",
     "@campfirein/brv-transport-client": "github:campfirein/brv-transport-client#1.1.0",
-    "@campfirein/byterover-packages": "github:campfirein/byterover-packages#main",
+    "@campfirein/byterover-packages": "github:campfirein/byterover-packages#1.0.5",
     "@codemirror/lang-html": "^6.4.11",
     "@codemirror/lang-markdown": "^6.5.0",
     "@codemirror/theme-one-dark": "^6.1.3",
@@ -206,7 +206,7 @@
   },
   "repository": "campfirein/byterover-cli",
   "scripts": {
-    "build": "shx rm -rf dist && tsc -b && shx cp -r src/server/templates dist/server/templates && shx cp -r src/agent/resources dist/agent/resources && npm run build:ui",
+    "build": "shx rm -rf dist && tsc -b && shx cp -r src/server/templates dist/server/templates && shx cp -r src/agent/resources dist/agent/resources && shx cp -r src/shared/assets dist/shared/assets && npm run build:ui",
     "build:ui": "vite build src/webui --mode package",
     "build:ui:submodule": "node scripts/prepare-ui-submodule-links.mjs && vite build src/webui --mode submodule",
     "dev": "node bin/kill-daemon.js && npm run build && ./bin/dev.js",
@@ -219,6 +219,9 @@
     "prepack": "npm run build && BRV_ENV=production oclif manifest",
     "prepare": "husky",
     "test": "mocha --forbid-only \"test/**/*.test.ts\"",
+    "test:e2e:analytics": "npm run build && mocha --forbid-only --timeout 600000 \"test/e2e/analytics/dev-beta.e2e.ts\"",
+    "test:e2e:lifecycle": "npm run build && mocha --forbid-only --timeout 180000 \"test/e2e/analytics/lifecycle-wire.e2e.ts\"",
+    "test:e2e:db": "npm run build && mocha --forbid-only --timeout 300000 \"test/e2e/analytics/lifecycle-db.e2e.ts\"",
     "typecheck": "tsc --noEmit && tsc --noEmit -p src/webui/tsconfig.json",
     "version": "git add README.md"
   },

src/oclif/commands/locations.ts

@@ -1,9 +1,15 @@
+/* eslint-disable camelcase */
 import {Command, Flags} from '@oclif/core'
 import chalk from 'chalk'
 
 import type {ProjectLocationDTO} from '../../shared/transport/types/dto.js'
 
-import {LocationsEvents, type LocationsGetResponse} from '../../shared/transport/events/locations-events.js'
+import {
+  LocationsEvents,
+  type LocationsGetRequest,
+  type LocationsGetResponse,
+} from '../../shared/transport/events/locations-events.js'
+import {buildCliMetadata} from '../lib/build-cli-metadata.js'
 import {type DaemonClientOptions, formatConnectionError, withDaemonRetry} from '../lib/daemon-client.js'
 import {writeJsonResponse} from '../lib/json-response.js'
 
@@ -19,19 +25,27 @@ export default class Locations extends Command {
     }),
   }
 
-  protected async fetchLocations(options?: DaemonClientOptions): Promise<ProjectLocationDTO[]> {
+  protected async fetchLocations(
+    cliMetadata: ReturnType<typeof buildCliMetadata>,
+    options?: DaemonClientOptions,
+  ): Promise<ProjectLocationDTO[]> {
     return withDaemonRetry<ProjectLocationDTO[]>(async (client) => {
-      const response = await client.requestWithAck<LocationsGetResponse>(LocationsEvents.GET)
+      const request: LocationsGetRequest = {cli_metadata: cliMetadata}
+      const response = await client.requestWithAck<LocationsGetResponse, LocationsGetRequest>(
+        LocationsEvents.GET,
+        request,
+      )
       return response.locations
     }, options)
   }
 
   public async run(): Promise<void> {
-    const {flags} = await this.parse(Locations)
+    const {flags, metadata} = await this.parse(Locations)
     const isJson = flags.format === 'json'
+    const cliMetadata = buildCliMetadata(this.id ?? 'locations', {flags, metadata})
 
     try {
-      const locations = await this.fetchLocations({projectPath: process.cwd()})
+      const locations = await this.fetchLocations(cliMetadata, {projectPath: process.cwd()})
 
       if (isJson) {
         writeJsonResponse({command: 'locations', data: {locations}, success: true})