The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
Measure product activation, friction and retention with privacy controls (#1301)
Deece68e2fac27b
diff --git a/backend/README.md b/backend/README.mdindex c45d87800..52e992caa 100644--- a/backend/README.md+++ b/backend/README.md@@ -138,6 +138,94 @@ Prisma over the **same MongoDB** as the agent-manager (no migration files — `pstartup). The backend owns the `users` + `agent_bindings` collections; it never manages themanager-owned `agent_nodes`/`managers` (read those via raw queries when status enrichment is needed).+### Product usage with an account-wide privacy control++**Settings → Privacy → Share product usage data** on desktop and phone, or+`harness privacy status|on|off [--json]`, controls the signed-in account. New accounts default on;+an existing legacy opt-out stays off until the person explicitly enables sharing. Guest computers+send no product reports. This control does not disable operational records needed to run the service.++The gateway reduces lifecycle signals locally to a fixed vocabulary: active/working installation+days, first measured work and response, repeat work, D1/D7 and consecutive-week returns, app opens,+launch attempts and outcomes, request refusals, response waits, matched turn ends/interruption,+error-event counts, and coarse duration buckets. A first-launch cohort counts work and a text response+within 24 hours of an installation's first measured launch attempt. Only day and counts leave the+computer; its bounded local state keeps the follow-up flags. These are updated installations, not+necessarily new people, and a response is not a judgment of task success.++Launch outcomes follow the existing durable creation receipt. Status polling adds no attempts;+install/model/native waits stay pending until an observed created, failed, cancelled or unconfirmed+reply. A 15-minute observation bound or memory-cap eviction records an unknown outcome, not a+failure. A daemon restart loses in-flight matches. Fixed request counters also cover resume, restart,+model changes and history. Only exact known error codes select a fixed failure category; messages+are never read. The response timer measures the first text event after an observed turn start,+not model tokens or output quality; tool-only turns can have no text response.++No prompt, response text, transcript, code, file or project name, path, tool argument, error text,+engine name, or stable user/device/agent identifier is a report field. Agent and launch identifiers+exist only in bounded in-memory maps (1,000 entries each) and never enter disk queues or HTTP reports.+The server authenticates requests to check the preference; this is **not anonymous network traffic**.+No analytics SDK, session replay, fingerprinting, or third-party destination is added.++With sharing on, Privacy settings also offers optional feedback: Useful, Couldn't finish, Slow,+Confusing, or Missing a feature. A deliberate button press sends only the fixed choice and a random+retry receipt. It cannot include text, a task identifier or content. Ambiguous retries keep the same+receipt and answer. This is self-selected feedback, not the task success rate of all users.++The three new collections have distinct purposes:++| Collection | Fields retained | Lifetime |+| --- | --- | --- |+| `product_usage_preferences` | Account ID, enabled flag, revision | Saved account preference; no usage history |+| `product_usage_totals` | UTC day, allowlisted metric, sum (plus DB primary key) | 396 days, approximately 13 months |+| `product_usage_receipts` | Random report UUID and expiration date | Scheduled expiry 36 days from the report day |++No individual report body or arrival timestamp is stored. Receipt insertion and increments share a+Mongo transaction so ambiguous retries cannot count twice. Saving a preference advances its revision;+an old queued report is refused even after an off/on cycle. The client checks the choice before each+upload, polls at most once a minute, and stops collecting if it cannot confirm the choice. The server+checks every ingestion without caching an enabled answer. Already admitted in-flight operations can+finish; previously combined totals cannot be selectively removed for one person. Turning off clears+the local queue on its next successful preference check. Queued counters older than 35 days are+discarded when the app next runs; no task content is read to reconstruct missing metrics.++The worker installs Mongo TTL indexes after schema setup. Expiry is asynchronous: the Mongo+[TTL background worker](https://www.mongodb.com/docs/manual/core/index-ttl/) may delete later than+the configured threshold. It also expires the eight legacy daily+history collections after 35 days. The old collector endpoint accepts no new rows, relay tracking+writes only global event totals, and the existing account deletion control covers the six former+presence collections as well as the old collector tables. These database lifetimes do not assert+anything about infrastructure access logs or backup retention; verify those separately before rollout.++Read daily totals with a read-only database identity, supplying `DATABASE_URL` through the environment:++```bash+cd backend+npm run usage:daily -- 14+```++The JSON includes daily headlines, the last complete week's return rate, and a `review` section+with launch and response friction, fixed feedback counts, matured first-launch and D1/D7 cohorts,+and equal seven-day descriptive comparisons. Each comparison includes its numerator, denominator,+coverage limits and evidence caveats. Today and immature cohorts are excluded from comparisons.+Low counts or incomplete windows are explicitly marked; no causal improvement is inferred.+Suggested investigations use synthetic reproductions and benchmarks, never user content. Missing client data is+unknown, and today is explicitly incomplete. Population is participating signed-in **computers**,+including staff and both service environments, not unique people or an external-user cohort.+Relay connection/turn totals from old clients stay separate from new client counters. Background+windows can count as active, and human/automated work is combined. First measured work is not signup+activation; a turn ending is not task success. The report deliberately makes no signup-to-value+activation claim. Weekly return compares locally counted consecutive-week working computers with+the preceding complete week's working computers; opt-outs, reinstallations, preference changes,+offline gaps and client upgrades affect coverage. Do not compare this estimate directly with the+legacy account-cohort retention percentage or an industry benchmark.++Ship the backend and its worker together, verify the unique and TTL indexes using synthetic reports,+then ship the CLI and settings surfaces with a visible release note explaining the default and switch.+The daily decision workflow and release note are in [the measurement guide](../docs/product-measurement.md).+Mixed-version coverage remains explicit until clients update. The existing `usage:report` command+below reads the bounded **historical** tables; its current-day counts cease when new history writes stop.+### Client country (Cloudflare)Production DNS is proxied through Cloudflare, so every request and WebSocket upgrade arrives with a@@ -147,7 +235,7 @@ Production DNS is proxied through Cloudflare, so every request and WebSocket upg(`middlewares/authMiddleware.ts`), rate-floored to one write per user per hour unless the countrychanges. This is the "where is the user" answer.- `machines.countryCode` — the computer's country on its last `/api/adapter-ws` connect.-- `machine_daily_presence.countryCode` / `user_daily_device_presence.countryCode` — same header on the+- Legacy `machine_daily_presence.countryCode` / `user_daily_device_presence.countryCode` — same header on thedaily presence rows. `user_daily_presence` deliberately has none: it is keyed by(user, machine, day) and its socket is the daemon's, so the machine's country is the one on`machine_daily_presence` for that `machineId`.@@ -156,3 +244,53 @@ Off Cloudflare (local dev, direct origin hits) the header is absent and nothingis only ever set, never cleared.Historical architecture notes still live in `autonomous-code/docs`.++## Product usage report++`npm run usage:report` reads the existing relay presence and turn counters and prints an+aggregate JSON report. It covers observed app users, owners doing agent work, surfaces,+complete UTC day/week/month windows, weekly return, exact-day return after first observed+work, seven-day signup activation, and workload concentration. It also shows collection+coverage and reconciles machine and agent turn counters, which must never be added together.++Use a database account with **read-only** privileges. In Bash, from `backend/`:++```bash+read -r -s -p 'Read-only MongoDB URL: ' READ_ONLY_DATABASE_URL+export READ_ONLY_DATABASE_URL+mkdir -p ../.harness/usage+npm run usage:report -- --days 30 --out ../.harness/usage/report.json+unset READ_ONLY_DATABASE_URL+```++The command deliberately requires `READ_ONLY_DATABASE_URL`, does not load `.env`, and does+not import server startup, migrations, or the application database singleton. It issues+read-only aggregates with a 15-second server limit, bounded connection timeouts, and a+100,000-row result ceiling; exceeding the ceiling fails instead of returning partial figures.+It exports no emails, account IDs, machine IDs, agent IDs, hostnames, or credentials. Keep+production reports under ignored `.harness/usage/`, not in source control. Output files use+mode `0600` and are never overwritten.++Options:++- `--as-of YYYY-MM-DD`: exclusive UTC cutoff, default today; the current partial day is excluded.+- `--days N`: reported daily range, 1–365 days. The loader reads at least 90 days for historical+ context; `range.historyFrom` records the exact boundary.+- `--exclude-email-domain example.com`: repeatable, case-insensitive exact account-domain filter.+ Exclusions apply before all metrics and denominators. This is an account-domain segment,+ not a verified employee/customer classification; unmatched historical owners stay in the report+ and are counted under `observedUsersWithoutAccountRow`.++Interpretation limits are part of the output. App presence can mean an idle window, connected+computers can run without an open app, and turns include automation. Surface user counts overlap.+P2P offers measure attempts, not confirmed sessions or all remote usage. A cohort's first+observed turn is not necessarily its first-ever use. Retention excludes the initial observation+day and only includes accounts old enough for the requested return day; signup activation also+requires a full seven-day follow-up and signup after the observation boundary.++Coverage describes earliest/latest stored rows across all accounts, including accounts removed+by a segment filter; it does not certify uninterrupted collection. A missing row means no observed+activity, not proven inactivity. In particular, do not compare new surface instrumentation with+older desktop history as if both had equal coverage. The collector-based account dashboard+(`src/lib/analyticsQuery.ts`) is separate: stale collector rows cannot establish current engine+mix, completion rate, runtime, or token cost.diff --git a/backend/package.json b/backend/package.jsonindex ee56f7d8e..92b479c45 100644--- a/backend/package.json+++ b/backend/package.json@@ -10,6 +10,8 @@"build": "node build.mjs","build:tsc": "tsc","typecheck": "tsc --noEmit",+ "usage:report": "node --import tsx src/usageReport.ts",+ "usage:daily": "node --import tsx src/productUsageReport.ts","connectors:import": "tsx src/connectorAppsImport.ts","start": "pm2 start ecosystem.config.cjs","stop": "pm2 stop ecosystem.config.cjs",diff --git a/backend/prisma/schema.prisma b/backend/prisma/schema.prismaindex d2ec7ff46..9a82e3b65 100644--- a/backend/prisma/schema.prisma+++ b/backend/prisma/schema.prisma@@ -457,11 +457,36 @@ model Subdomain {@@map("subdomains")}-/// Harness Analytics — ADDITIVE counters only (see docs/design/harness-analytics.md).-/// Safe to sum along engine, mode, origin, machine, and day. A union of intervals or a distinct-/// count must NEVER live here: splitting one by engine and re-summing double-counts concurrency,-/// which is the exact error the wall-clock metric exists to prevent. Those live on-/// AnalyticsDailyMachine at (machine, day) granularity instead.+/// Account control only; no report times, usage counters or machine inventory.+model ProductUsagePreference {+ id String @id @default(auto()) @map("_id") @db.ObjectId+ userId String @unique+ enabled Boolean+ revision Int @default(1)++ @@map("product_usage_preferences")+}++/// Only fleet-wide counters. Never add an account, machine, agent, location or event timestamp.+model ProductUsageTotal {+ id String @id @default(auto()) @map("_id") @db.ObjectId+ dayUtc DateTime+ metric String+ value Int++ @@unique([dayUtc, metric])+ @@map("product_usage_totals")+}++/// Random report receipt, used only to prevent retries counting twice. No identity or report body.+model ProductUsageReceipt {+ id String @id @map("_id")+ expiresAt DateTime++ @@map("product_usage_receipts")+}++/// Legacy individual counters. New ingestion is disabled; dayUtc TTL removes these after 35 days.model AnalyticsDailyBucket {id String @id @default(auto()) @map("_id") @db.ObjectIduserId String@@ -489,6 +514,7 @@ model AnalyticsDailyBucket {@@map("analytics_daily_buckets")}+/// Legacy, no longer written. Retained only until the 35-day dayUtc expiry./// Harness Analytics — NON-ADDITIVE metrics plus the reporting heartbeat. Exactly one row per/// machine per day. A row with all-zero counters means "the machine was up and idle"; a MISSING row/// means "we have no data". The UI must never render those two states the same way.@@ -535,9 +561,8 @@ model AnalyticsMachineState {@@map("analytics_machine_states")}-/// Presence/remote-usage tracking — separate from the Analytics family above (not opt-in, not-/// collector-reported; derived directly from the relays: web-ws in src/lib/webWs.ts, device-ws in-/// src/lib/deviceWs.ts, adapter-ws in src/lib/adapterWs.ts).+/// Legacy presence histories: new writes are disabled and dayUtc expires after 35 days.+/// The comments below document old records for historical readers, not current collection./// Per-day record of whether a user had the desktop app open, and on which machine. One row per/// (user, machine, UTC day): "user online that day" is therefore a DISTINCT count of `userId`, whilediff --git a/backend/src/analytics/dailyProductReview.test.ts b/backend/src/analytics/dailyProductReview.test.tsnew file mode 100644index 000000000..efaba0daf--- /dev/null+++ b/backend/src/analytics/dailyProductReview.test.ts@@ -0,0 +1,46 @@+import { expect, it } from 'vitest'+import { dailyProductReview } from './dailyProductReview.js'+const row = (day: string, metric: string, value: number) => ({ dayUtc: new Date(day), metric, value })++it('keeps today out of comparisons and marks sparse or absent baselines honestly', () => {+ const r = dailyProductReview([+ row('2026-10-12', 'launch_created', 3), row('2026-10-12', 'launch_failed', 1),+ row('2026-10-12', 'launch_failed_setup', 1), row('2026-10-13', 'launch_failed', 999),+ ], new Date('2026-10-13T12:00:00Z'))+ expect(r.comparisons[0].current).toMatchObject({ numerator: 1, denominator: 4, percent: 25 })+ expect(r.comparisons[0].previous.percent).toBeNull()+ expect(r.comparisons[0].differencePercentagePoints).toBeNull()+ expect(r.comparisons[0].evidence).toContain('Sparse')+ expect(r.investigate[0]).toMatchObject({ area: 'Agent setup', count: 1 })+})++it('uses matured original working-day cohorts and refuses to interpret missing follow-up coverage as zero', () => {+ const r = dailyProductReview([+ row('2026-10-11', 'working_installation_days', 10), row('2026-10-11', 'd1_returning_work_installations', 6),+ row('2026-10-12', 'working_installation_days', 8),+ row('2026-10-04', 'working_installation_days', 12), row('2026-10-04', 'd7_returning_work_installations', 3),+ row('2026-10-05', 'working_installation_days', 7),+ ], new Date('2026-10-13'))+ expect(r.retention[0].cohorts.at(-1)).toMatchObject({ day: '2026-10-11', workingInstallations: 10, returned: 6, percent: 60 })+ expect(r.retention[1].cohorts.find(c => c.day === '2026-10-04')).toMatchObject({ percent: 25 })+ expect(r.retention[0].cohorts.find(c => c.day === '2026-10-05')?.percent).toBeNull()+ expect(r.retention[0].cohorts[0].percent).toBeNull()+})++it('reports voluntary feedback separately, never as a task success rate', () => {+ const r = dailyProductReview([row('2026-10-12', 'feedback_useful', 2), row('2026-10-12', 'feedback_slow', 1)], new Date('2026-10-13'))+ expect(r.feedback).toMatchObject({ useful: 2, slow: 1 })+ expect(r.comparisons.find(c => c.name.startsWith('Useful'))?.current.denominator).toBe(3)+ expect(r.gaps.join(' ')).toContain('self-selected')+ expect(r).not.toHaveProperty('taskSuccessRate')+})++it('compares first-launch installation cohorts only after every 24-hour window can mature', () => {+ const r = dailyProductReview([+ row('2026-10-11', 'first_launch_installations', 4), row('2026-10-11', 'first_launch_work_24h_installations', 3),+ row('2026-10-11', 'first_launch_response_24h_installations', 2), row('2026-10-12', 'first_launch_installations', 99),+ ], new Date('2026-10-13'))+ expect(r.firstLaunchCohorts.cohorts.at(-1)).toMatchObject({ day: '2026-10-11', firstLaunchInstallations: 4, workingWithin24h: 3, observedResponsePercent: 50 })+ expect(r.firstLaunchCohorts.cohorts.some(c => c.day === '2026-10-12')).toBe(false)+ expect(r.firstLaunchCohorts.cohorts[0].observedResponsePercent).toBeNull()+})diff --git a/backend/src/analytics/dailyProductReview.ts b/backend/src/analytics/dailyProductReview.tsnew file mode 100644index 000000000..c1c28892d--- /dev/null+++ b/backend/src/analytics/dailyProductReview.ts@@ -0,0 +1,110 @@+import { PRODUCT_FEEDBACK, PRODUCT_USAGE_ACTIONS } from '../types/productUsage.js'+import { DAILY_PRODUCT_METRICS } from './dailyProductUsage.js'++type Row = { dayUtc: Date; metric: string; value: number }+const DAY = 86400000+const dayKey = (stamp: number) => new Date(stamp).toISOString().slice(0, 10)+const rate = (n: number, d: number) => d > 0 && n >= 0 && n <= d ? Math.round(n / d * 1000) / 10 : null+const sum = (c: Record<string, number>, names: string[]) => names.reduce((n, key) => n + (c[key] ?? 0), 0)++/** Descriptive triage, not an automatic verdict or a causal claim about the latest release. */+export function dailyProductReview(rows: Row[], now: Date) {+ const today = Math.floor(now.getTime() / DAY) * DAY+ const byDay = new Map<string, Record<string, number>>()+ for (const row of rows) {+ if (!DAILY_PRODUCT_METRICS.includes(row.metric as typeof DAILY_PRODUCT_METRICS[number]) || !Number.isSafeInteger(row.value) || row.value < 0) continue+ const key = row.dayUtc.toISOString().slice(0, 10), c = byDay.get(key) ?? {}+ c[row.metric] = (c[row.metric] ?? 0) + row.value; byDay.set(key, c)+ }+ const window = (from: number, until: number) => {+ const counters: Record<string, number> = {}+ let observedDays = 0+ for (let day = from; day < until; day += DAY) {+ const c = byDay.get(dayKey(day))+ if (!c) continue+ if (Object.keys(c).some(k => !k.startsWith('relay_'))) observedDays+++ for (const [k, n] of Object.entries(c)) counters[k] = (counters[k] ?? 0) + n+ }+ return { from: dayKey(from), untilExclusive: dayKey(until), observedDays, counters }+ }+ const recent = window(today - 7 * DAY, today), baseline = window(today - 14 * DAY, today - 7 * DAY)+ const comparison = (name: string, numerator: string[], denominator: string[]) => {+ const side = (w: typeof recent) => {+ const n = sum(w.counters, numerator), d = sum(w.counters, denominator)+ return { numerator: n, denominator: d, percent: rate(n, d), observedDays: w.observedDays }+ }+ const current = side(recent), previous = side(baseline)+ return { name, current, previous,+ differencePercentagePoints: current.percent !== null && previous.percent !== null ? Math.round((current.percent - previous.percent) * 10) / 10 : null,+ evidence: current.denominator < 20 || previous.denominator < 20 || recent.observedDays < 7 || baseline.observedDays < 7+ ? 'Sparse or incomplete; inspect individual synthetic reproductions, do not claim a trend.'+ : 'Descriptive comparison only. Repeated work is not independent sampling; releases, adoption and population changes can confound it.',+ }+ }+ const comparisons = [+ comparison('Observed new-harness launch failure', ['launch_failed'], ['launch_created', 'launch_failed']),+ comparison('First response took at least one minute', ['response_1m_to_5m', 'response_over_5m'],+ ['response_under_10s', 'response_10s_to_1m', 'response_1m_to_5m', 'response_over_5m']),+ comparison('Matched turn ended without an observed text response', ['turns_ended_without_response'], ['turns_ended', 'turns_interrupted']),+ comparison('Matched turn interrupted', ['turns_interrupted'], ['turns_ended', 'turns_interrupted']),+ comparison('Useful among voluntary feedback responses', ['feedback_useful'], PRODUCT_FEEDBACK.map(a => `feedback_${a}`)),+ ...PRODUCT_USAGE_ACTIONS.map(action => comparison(`${action}: request refusal`, [`${action}_failed`], [`${action}_ok`, `${action}_failed`])),+ ]+ const c = recent.counters+ const signals = [+ { area: 'Agent setup', count: c.launch_failed_setup ?? 0, next: 'Reproduce a first launch on a clean machine; verify engine installation, tmux and native hook preparation.' },+ { area: 'Sign-in or permission', count: c.launch_failed_auth ?? 0, next: 'Exercise expired sign-in and reconnect with a test account; verify recovery and the visible explanation.' },+ { area: 'Dependency availability', count: c.launch_failed_unavailable ?? 0, next: 'Test an unavailable model/service and recovery; verify that a saved launch starts exactly once.' },+ { area: 'Launch choices', count: c.launch_failed_invalid ?? 0, next: 'Reproduce invalid project/model selections with fixtures; verify validation before starting work.' },+ { area: 'Unknown launch refusal', count: c.launch_failed_other ?? 0, next: 'Exercise launch failure fixtures and add a justified fixed category; do not retrieve user error messages.' },+ { area: 'Response wait', count: c.turns_waiting_over_1m ?? 0, next: 'Benchmark the same synthetic task and toolchain before/after; separate model wait from Harness overhead locally.' },+ { area: 'No observed response', count: c.turns_ended_without_response ?? 0, next: 'Reproduce interruptions, provider failures and tool-only turns; a missing text event alone does not establish task failure.' },+ { area: 'Launch outcome coverage', count: (c.launch_unobserved ?? 0) + (c.launch_unconfirmed ?? 0), next: 'Verify receipt polling, window close and daemon restart; unknown outcomes must not be counted as failed launches.' },+ ].filter(s => s.count > 0).sort((a, b) => b.count - a.count)+ const retention = [1, 7].map(lag => {+ const cohorts = Array.from({ length: 7 }, (_, i) => {+ const stamp = today - (lag + 7 - i) * DAY, cohort = byDay.get(dayKey(stamp)) ?? {}+ const denominator = cohort.working_installation_days ?? 0+ const followUpObserved = (byDay.get(dayKey(stamp + lag * DAY))?.working_installation_days ?? 0) > 0+ const returned = denominator && followUpObserved ? cohort[`d${lag}_returning_work_installations`] ?? 0 : null+ return { day: dayKey(stamp), workingInstallations: denominator || null, returned,+ percent: returned === null ? null : rate(returned, denominator) }+ })+ return { day: lag, definition: `Observed work on both the cohort's UTC day and UTC day +${lag}. Installation counts, not people.`, cohorts }+ })+ return {+ recent: { from: recent.from, untilExclusive: recent.untilExclusive, observedDays: recent.observedDays },+ baseline: { from: baseline.from, untilExclusive: baseline.untilExclusive, observedDays: baseline.observedDays },+ comparisons, investigate: signals, retention,+ firstLaunchCohorts: {+ definition: 'Participating installations after their first measured new-harness launch attempt. Work/response within 24 hours, counted locally on the original launch day. This is not signup activation or a same-task success rate; updated existing users are included.',+ cohorts: Array.from({ length: 7 }, (_, i) => {+ // A full UTC launch day needs the following UTC day to finish its 24-hour windows.+ const day = dayKey(today - (8 - i) * DAY), c = byDay.get(day) ?? {}+ const starts = c.first_launch_installations ?? 0+ const working = starts ? c.first_launch_work_24h_installations ?? 0 : null+ const responding = starts ? c.first_launch_response_24h_installations ?? 0 : null+ return { day, firstLaunchInstallations: starts || null, workingWithin24h: working, respondingWithin24h: responding,+ observedResponsePercent: responding === null ? null : rate(responding, starts) }+ }),+ caveat: 'No observed response is not proof of failure. Opt-outs, disconnected clients, late uploads and resets can reduce follow-up coverage.',+ },+ firstUse: { firstMeasuredWork: c.first_work_installations ?? null, firstObservedResponse: c.first_response_installations ?? null,+ launchAttempts: c.launch_started ?? null, observedLaunchesCreated: c.launch_created ?? null,+ interpretation: 'Post-sign-in first-use signals; these stage counts are not one signup cohort or a signup conversion rate. Already installed clients enter measurement when updated.' },+ feedback: Object.fromEntries(PRODUCT_FEEDBACK.map(answer => [answer, c[`feedback_${answer}`] ?? 0])),+ gaps: [+ 'Pre-sign-in setup and sign-in drop-off are not observed: signed-out clients send no reports. Test those paths synthetically.',+ 'Durable launch outcomes require observed receipt replies; status polling adds no attempts. Missing outcomes, restarts and the 15-minute observation bound reduce coverage.',+ 'Human and automated work are combined. App-open time is not productive use; technical completion is not task success.',+ 'Feedback is voluntary and self-selected, not a representative satisfaction survey or a success rate for all tasks.',+ 'Late reports, opt-outs, reinstallations and preference resets affect return counts. Today and immature return cohorts are excluded here.',+ ],+ nextReview: [+ 'Choose one observed friction and write a falsifiable hypothesis, target metric, guardrails and comparison window before changing code.',+ 'Reproduce with synthetic inputs, profile or benchmark the same workload, then add a regression test and review the fix.',+ 'Record the released commit and rollout time. Compare matured equal-length windows; inspect participation changes and competing releases.',+ 'Keep, revise or revert based on evidence. With little data, report uncertainty and continue observing instead of declaring a win.',+ ],+ }+}diff --git a/backend/src/analytics/dailyProductUsage.test.ts b/backend/src/analytics/dailyProductUsage.test.tsnew file mode 100644index 000000000..b4b18c969--- /dev/null+++ b/backend/src/analytics/dailyProductUsage.test.ts@@ -0,0 +1,38 @@+import { expect, it } from 'vitest'+import { dailyProductUsage } from './dailyProductUsage.js'++it('keeps missing client coverage separate from zero and separates relay activity', () => {+ const report = dailyProductUsage([+ { dayUtc: new Date('2026-10-12'), metric: 'relay_turns_started', value: 10 },+ { dayUtc: new Date('2026-10-12'), metric: 'feedback_useful', value: 2 },+ { dayUtc: new Date('2026-10-12'), metric: 'd1_returning_work_installations', value: 1 },+ { dayUtc: new Date('2026-10-13'), metric: 'active_installation_days', value: 10 },+ { dayUtc: new Date('2026-10-13'), metric: 'working_installation_days', value: 4 },+ { dayUtc: new Date('2026-10-13'), metric: 'PRIVATE_CANARY', value: 1 },+ ], 2, new Date('2026-10-13T12:00:00Z'))+ expect(report.daily[0].workingComputers).toBeNull()+ expect(report.daily[1]).toMatchObject({ period: 'incomplete', activeComputers: 10, workingComputers: 4, workingPctOfActive: 40 })+ expect(report.previousCompleteWeek.returningPct).toBeNull()+ expect(JSON.stringify(report)).not.toContain('PRIVATE_CANARY')+})++it('uses the preceding complete week as the retention denominator, never this partial week', () => {+ const report = dailyProductUsage([+ { dayUtc: new Date('2026-09-28'), metric: 'weekly_working_installations', value: 10 },+ { dayUtc: new Date('2026-10-05'), metric: 'weekly_returning_installations', value: 6 },+ { dayUtc: new Date('2026-10-05'), metric: 'weekly_working_installations', value: 8 },+ { dayUtc: new Date('2026-10-12'), metric: 'weekly_returning_installations', value: 99 },+ ], 21, new Date('2026-10-13'))+ expect(report.previousCompleteWeek).toMatchObject({ starting: '2026-10-05', denominatorWeekStarting: '2026-09-28', priorWorkingComputers: 10, returnedWorkingComputers: 6, returningPct: 60 })+})++it('does not call cross-midnight unmatched turn counts success, or emit impossible percentages', () => {+ const report = dailyProductUsage([+ { dayUtc: new Date('2026-10-13'), metric: 'turns_ended', value: 3 },+ { dayUtc: new Date('2026-10-13'), metric: 'turns_interrupted', value: 1 },+ { dayUtc: new Date('2026-10-13'), metric: 'working_installation_days', value: 9 },+ { dayUtc: new Date('2026-10-13'), metric: 'active_installation_days', value: 1 },+ ], 1, new Date('2026-10-13'))+ expect(report.daily[0]).toMatchObject({ workingPctOfActive: null, interruptedPctOfObservedEnds: 25 })+ expect(report.daily[0]).not.toHaveProperty('successRate')+})diff --git a/backend/src/analytics/dailyProductUsage.ts b/backend/src/analytics/dailyProductUsage.tsnew file mode 100644index 000000000..d4a3c5cb3--- /dev/null+++ b/backend/src/analytics/dailyProductUsage.ts@@ -0,0 +1,52 @@+import { PRODUCT_USAGE_METRICS } from '../types/productUsage.js'++const DAY = 86_400_000+export const DAILY_PRODUCT_METRICS = [...PRODUCT_USAGE_METRICS,+ 'relay_desktop_opens', 'relay_tui_opens', 'relay_mobile_opens', 'relay_web_opens',+ 'relay_harness-os_opens', 'relay_harness-os-pi_opens',+ 'relay_device_connections', 'relay_machine_connections', 'relay_remote_sessions', 'relay_turns_started',+] as const+type Row = { dayUtc: Date; metric: string; value: number }+const key = (stamp: number) => new Date(stamp).toISOString().slice(0, 10)+const percentage = (n: number, d: number): number | null => d > 0 && n <= d ? Math.round(n / d * 1000) / 10 : null++/** Only additive fleet totals enter here. Missing reports never become a claim of zero users. */+export function dailyProductUsage(rows: Row[], days: number, now: Date) {+ const today = Math.floor(now.getTime() / DAY) * DAY+ const byDay = new Map<string, Record<string, number>>()+ for (const row of rows) {+ if (!DAILY_PRODUCT_METRICS.includes(row.metric as typeof DAILY_PRODUCT_METRICS[number])+ || !Number.isSafeInteger(row.value) || row.value < 0) continue+ const day = row.dayUtc.toISOString().slice(0, 10)+ const counts = byDay.get(day) ?? {}+ counts[row.metric] = (counts[row.metric] ?? 0) + row.value+ byDay.set(day, counts)+ }+ const daily = Array.from({ length: days }, (_, i) => {+ const stamp = today - (days - 1 - i) * DAY, day = key(stamp), c = byDay.get(day) ?? {}+ // Feedback and backdated cohort counters alone do not establish current-day activity coverage.+ const observed = c.active_installation_days !== undefined+ const count = (metric: string) => observed ? c[metric] ?? 0 : null+ const ended = (c.turns_ended ?? 0) + (c.turns_interrupted ?? 0)+ return { day, period: stamp === today ? 'incomplete' : 'ended; late reports possible',+ clientCoverage: observed ? 'reports received; participation unknown' : 'no client measurements',+ activeComputers: count('active_installation_days'), workingComputers: count('working_installation_days'),+ firstMeasuredWork: count('first_work_installations'), repeatWorkingComputers: count('repeat_work_installation_days'),+ workingPctOfActive: percentage(c.working_installation_days ?? 0, c.active_installation_days ?? 0),+ turnsStarted: count('turns_started'), turnsEnded: count('turns_ended'), turnsInterrupted: count('turns_interrupted'),+ interruptedPctOfObservedEnds: percentage(c.turns_interrupted ?? 0, ended),+ counters: c,+ }+ })+ const thisMonday = today - ((now.getUTCDay() + 6) % 7) * DAY+ const weekTotal = (monday: number, metric: string) => Array.from({ length: 7 }, (_, i) => byDay.get(key(monday + i * DAY))?.[metric] ?? 0).reduce((a, b) => a + b, 0)+ const priorWorkers = weekTotal(thisMonday - 14 * DAY, 'weekly_working_installations')+ const weekObserved = weekTotal(thisMonday - 7 * DAY, 'weekly_working_installations') > 0+ const returned = weekTotal(thisMonday - 7 * DAY, 'weekly_returning_installations')+ return { daily, previousCompleteWeek: {+ starting: key(thisMonday - 7 * DAY), denominatorWeekStarting: key(thisMonday - 14 * DAY),+ priorWorkingComputers: priorWorkers || null, returnedWorkingComputers: priorWorkers && weekObserved ? returned : null,+ returningPct: weekObserved ? percentage(returned, priorWorkers) : null,+ interpretation: 'Consecutive-week working computers among participating installations; not signup-cohort or person retention. Opt-outs, reinstalls and missing reports can change this estimate.',+ } }+}diff --git a/backend/src/analytics/productUsage.test.ts b/backend/src/analytics/productUsage.test.tsnew file mode 100644index 000000000..bd15643ae--- /dev/null+++ b/backend/src/analytics/productUsage.test.ts@@ -0,0 +1,105 @@+import { describe, expect, it } from 'vitest'+import { productUsageReport, SOURCES, validateOptions, type UsageData } from './productUsage.js'++function fixture(): UsageData {+ return { historyFrom: '2026-07-12', users: [+ { userId: 'a', signupDay: '2026-09-18', emailDomain: 'autonomous.ai' },+ { userId: 'b', signupDay: '2026-09-20', emailDomain: 'example.com' },+ ], rows: { desktop: [], clients: [], devices: [], remote: [], machines: [], agents: [], collector: [] },+ coverage: Object.fromEntries(SOURCES.map(s => [s, { rows: 100, firstDay: '2026-09-16', lastDay: '2026-10-09' }])) as UsageData['coverage'] }+}+const opts = { asOf: '2026-10-10', days: 30 }++describe('product usage metrics', () => {+ it('deduplicates people across machines and surfaces, and excludes the partial day', () => {+ const data = fixture()+ data.rows.desktop = [+ { day: '2026-10-09', userId: 'a', machineId: 'm1' },+ { day: '2026-10-09', userId: 'a', machineId: 'm2' },+ { day: '2026-10-10', userId: 'b', machineId: 'm3' },+ ]+ data.rows.clients = [{ day: '2026-10-09', userId: 'a', surface: 'tui' }, { day: '2026-10-09', userId: 'b', surface: 'mobile' }]+ const result = productUsageReport(data, opts)+ expect(result.windows.day.appUsers).toBe(2)+ expect(result.windows.day.surfaces).toEqual({ desktop: 1, tui: 1, mobile: 1, web: 0 })+ expect(result.windows.day.workingUsers).toBe(0)+ expect(result.daily).toHaveLength(30)+ expect(result.daily.at(-1)?.from).toBe('2026-10-09')+ })++ it('counts distinct machine/agent pairs across days and reconciles rather than adds counters', () => {+ const data = fixture()+ data.rows.machines = [+ { day: '2026-10-08', userId: 'a', machineId: 'm1', turnsStarted: 5 },+ { day: '2026-10-09', userId: 'a', machineId: 'm1', turnsStarted: 10 },+ { day: '2026-10-09', userId: 'b', machineId: 'm2', turnsStarted: 0 },+ ]+ data.rows.agents = [+ { day: '2026-10-08', userId: 'a', machineId: 'm1', agentId: 'same', turnsStarted: 4 },+ { day: '2026-10-09', userId: 'a', machineId: 'm1', agentId: 'same', turnsStarted: 9 },+ { day: '2026-10-09', userId: 'a', machineId: 'm2', agentId: 'same', turnsStarted: 1 },+ ]+ const period = productUsageReport(data, opts).period+ expect(period).toMatchObject({ connectedOwners: 2, workingUsers: 1, turnsStarted: 15, agentTurnsStarted: 14, turnCounterDelta: 1, activeAgents: 2 })+ })++ it('uses only matured, non-left-censored cohorts for exact-day retention', () => {+ const data = fixture()+ data.rows.machines = [+ { day: '2026-09-16', userId: 'old', turnsStarted: 1 },+ { day: '2026-10-02', userId: 'a', turnsStarted: 1 },+ { day: '2026-10-09', userId: 'a', turnsStarted: 1 },+ { day: '2026-10-03', userId: 'b', turnsStarted: 1 },+ { day: '2026-10-10', userId: 'b', turnsStarted: 1 },+ ]+ const retention = productUsageReport(data, opts).firstObservedWorkRetention+ expect(retention.excludedLeftCensoredUsers).toBe(1)+ expect(retention.exactDayRetention[1]).toEqual({ day: 7, eligible: 1, returned: 1, rate: 1 })+ expect(retention.exactDayRetention[2]).toEqual({ day: 14, eligible: 0, returned: 0, rate: null })+ })++ it('compares distinct prior-week users and applies exclusions before all denominators', () => {+ const data = fixture()+ data.rows.machines = [+ { day: '2026-09-26', userId: 'a', turnsStarted: 100 },+ { day: '2026-09-27', userId: 'b', turnsStarted: 10 },+ { day: '2026-10-03', userId: 'b', turnsStarted: 2 },+ { day: '2026-10-09', userId: 'unknown', turnsStarted: 3 },+ ]+ const result = productUsageReport(data, { ...opts, excludeEmailDomains: ['AUTONOMOUS.AI'] })+ expect(result.weeklyWorkReturn).toEqual({ previousUsers: 1, currentUsers: 2, returned: 1, rate: 1, currentOnly: 1, previousOnly: 0 })+ expect(result.population).toMatchObject({ excludedAccounts: 1, knownAccounts: 1, observedUsersWithoutAccountRow: 1 })+ expect(result.intensity.medianTurns).toBe(7.5)+ expect(result.intensity.top1Share).toBe(12 / 15)+ expect(JSON.stringify(result)).not.toContain('"userId"')+ expect(JSON.stringify(result)).not.toContain('"machineId"')+ })++ it('requires a full seven-day observation window for signup activation', () => {+ const data = fixture()+ data.users = [+ { userId: 'a', signupDay: '2026-10-03', emailDomain: 'example.com' },+ { userId: 'b', signupDay: '2026-10-04', emailDomain: 'example.com' },+ { userId: 'c', signupDay: '2026-09-15', emailDomain: 'example.com' },+ ]+ data.rows.machines = [{ day: '2026-10-09', userId: 'a', turnsStarted: 1 }, { day: '2026-10-09', userId: 'b', turnsStarted: 1 }]+ expect(productUsageReport(data, opts).signupActivationWithin7Days).toEqual({ eligible: 1, activated: 1, rate: 1 })+ })++ it('keeps empty data and late instrumentation visible instead of inventing a rate', () => {+ const data = fixture()+ data.coverage.clients = { rows: 3, firstDay: '2026-10-07', lastDay: '2026-10-09' }+ data.coverage.collector = { rows: 97, firstDay: '2026-08-11', lastDay: '2026-08-24' }+ const result = productUsageReport(data, opts)+ expect(result.windows.week.observedCoverage.clients.startsBeforeWindow).toBe(false)+ expect(result.windows.week.observedCoverage.collector.hasRowsOnFinalDay).toBe(false)+ expect(result.intensity.top1Share).toBeNull()+ expect(result.intensity.medianTurns).toBeNull()+ expect(result.weeklyWorkReturn.rate).toBeNull()+ })++ it('rejects invalid dates and unbounded report ranges', () => {+ for (const asOf of ['2026-02-30', '2026-10-10T01:00:00Z', 'bad']) expect(() => validateOptions({ ...opts, asOf })).toThrow()+ for (const days of [0, -1, 366, 1.5, NaN]) expect(() => validateOptions({ ...opts, days })).toThrow()+ })+})diff --git a/backend/src/analytics/productUsage.ts b/backend/src/analytics/productUsage.tsnew file mode 100644index 000000000..34955fe18--- /dev/null+++ b/backend/src/analytics/productUsage.ts@@ -0,0 +1,163 @@+/** Product-wide usage from relay observations. No account identifiers leave this reducer. */+export const DAY_MS = 86_400_000+export const SOURCES = ['desktop', 'clients', 'devices', 'remote', 'machines', 'agents', 'collector'] as const+export type Source = typeof SOURCES[number]+export interface UsageRow {+ day: string+ userId: string+ machineId?: string+ agentId?: string+ surface?: string+ turnsStarted?: number+ connections?: number+ sessions?: number+}+export interface UsageUser { userId: string; signupDay: string; emailDomain: string }+export interface Coverage { rows: number; firstDay: string | null; lastDay: string | null }+export interface UsageData {+ users: UsageUser[]+ rows: Record<Source, UsageRow[]>+ coverage: Record<Source, Coverage>+ historyFrom: string+}+export interface UsageOptions { asOf: string; days: number; excludeEmailDomains?: string[] }++export function validDay(value: string): boolean {+ return /^\d{4}-\d{2}-\d{2}$/.test(value) && Number.isFinite(Date.parse(value)) &&+ new Date(value).toISOString().slice(0, 10) === value+}+export function shiftDay(day: string, offset: number): string {+ return new Date(Date.parse(day) + offset * DAY_MS).toISOString().slice(0, 10)+}+export function validateOptions(opts: UsageOptions): void {+ if (!validDay(opts.asOf)) throw new Error('asOf must be a real UTC date (YYYY-MM-DD)')+ if (!Number.isInteger(opts.days) || opts.days < 1 || opts.days > 365) throw new Error('days must be an integer from 1 to 365')+}+const distinct = (rows: UsageRow[]) => new Set(rows.map(r => r.userId))+const sum = (rows: UsageRow[], field: 'turnsStarted' | 'sessions') => rows.reduce((n, r) => n + (r[field] ?? 0), 0)+const rate = (n: number, denominator: number) => denominator ? n / denominator : null+const countOverlap = (a: Set<string>, b: Set<string>) => [...a].filter(id => b.has(id)).length+function quantile(sorted: number[], p: number): number | null {+ if (!sorted.length) return null+ const i = (sorted.length - 1) * p, lo = Math.floor(i), hi = Math.ceil(i)+ return sorted[lo] + (sorted[hi] - sorted[lo]) * (i - lo)+}++export function productUsageReport(data: UsageData, opts: UsageOptions) {+ validateOptions(opts)+ const from = shiftDay(opts.asOf, -opts.days)+ const domains = new Set((opts.excludeEmailDomains ?? []).map(d => d.trim().toLowerCase()).filter(Boolean))+ const excluded = new Set(data.users.filter(u => domains.has(u.emailDomain.toLowerCase())).map(u => u.userId))+ const users = data.users.filter(u => !excluded.has(u.userId) && u.signupDay < opts.asOf)+ const knownUsers = new Set(data.users.map(u => u.userId))+ const rows = Object.fromEntries(SOURCES.map(source => [source, data.rows[source].filter(r =>+ r.day >= data.historyFrom && r.day < opts.asOf && !excluded.has(r.userId),+ )])) as Record<Source, UsageRow[]>+ const inRange = (source: Source, start: string, end: string) => rows[source].filter(r => r.day >= start && r.day < end)+ const working = (start: string, end: string) => inRange('machines', start, end).filter(r => (r.turnsStarted ?? 0) > 0)+ const apps = (start: string, end: string) => [...inRange('desktop', start, end),+ ...inRange('clients', start, end).filter(r => ['tui', 'mobile', 'web'].includes(r.surface ?? ''))]++ function summary(start: string, end: string) {+ const machines = inRange('machines', start, end), work = working(start, end)+ const agents = inRange('agents', start, end).filter(r => (r.turnsStarted ?? 0) > 0)+ const clients = inRange('clients', start, end), remote = inRange('remote', start, end)+ const turnsStarted = sum(machines, 'turnsStarted'), agentTurnsStarted = sum(agents, 'turnsStarted')+ return {+ from: start, toExclusive: end,+ appUsers: distinct(apps(start, end)).size,+ workingUsers: distinct(work).size,+ connectedOwners: distinct(machines).size,+ connectedMachines: new Set(machines.map(r => r.machineId)).size,+ workingMachines: new Set(work.map(r => r.machineId)).size,+ activeAgents: new Set(agents.map(r => JSON.stringify([r.machineId, r.agentId]))).size,+ turnsStarted, agentTurnsStarted, turnCounterDelta: turnsStarted - agentTurnsStarted,+ surfaces: {+ desktop: distinct(inRange('desktop', start, end)).size,+ tui: distinct(clients.filter(r => r.surface === 'tui')).size,+ mobile: distinct(clients.filter(r => r.surface === 'mobile')).size,+ web: distinct(clients.filter(r => r.surface === 'web')).size,+ },+ hardwareOwners: distinct(inRange('devices', start, end)).size,+ remoteOfferUsers: distinct(remote).size,+ remoteOffers: sum(remote, 'sessions'),+ observedCoverage: Object.fromEntries(SOURCES.map(source => [source, {+ startsBeforeWindow: data.coverage[source].firstDay !== null && data.coverage[source].firstDay! < start,+ hasRowsOnFinalDay: data.coverage[source].lastDay === shiftDay(end, -1) ||+ inRange(source, shiftDay(end, -1), end).length > 0,+ }])),+ }+ }++ const workDays = new Map<string, Set<string>>()+ for (const r of working(data.historyFrom, opts.asOf)) {+ const days = workDays.get(r.userId) ?? new Set<string>()+ days.add(r.day)+ workDays.set(r.userId, days)+ }+ const firstWork = [...workDays].map(([id, days]) => ({ id, first: [...days].sort()[0], days }))+ // The initial observed day is left-censored. Neither these nor later cohorts imply a new account.+ const boundary = [data.historyFrom, data.coverage.machines.firstDay ?? opts.asOf].sort().at(-1)!+ const cohorts = firstWork.filter(u => u.first > boundary && u.first >= from)+ const exactDayRetention = [1, 7, 14].map(offset => {+ const eligible = cohorts.filter(u => shiftDay(u.first, offset) < opts.asOf)+ const returned = eligible.filter(u => u.days.has(shiftDay(u.first, offset))).length+ return { day: offset, eligible: eligible.length, returned, rate: rate(returned, eligible.length) }+ })+ const signupEligible = users.filter(u => u.signupDay > boundary && u.signupDay >= from && shiftDay(u.signupDay, 7) <= opts.asOf)+ const activated = signupEligible.filter(u => [...(workDays.get(u.userId) ?? [])]+ .some(day => day >= u.signupDay && day < shiftDay(u.signupDay, 7))).length+ const previousWork = distinct(working(shiftDay(opts.asOf, -14), shiftDay(opts.asOf, -7)))+ const currentWork = distinct(working(shiftDay(opts.asOf, -7), opts.asOf))+ const returned = countOverlap(previousWork, currentWork)++ const power = new Map<string, { turns: number; days: Set<string> }>()+ for (const r of working(from, opts.asOf)) {+ const p = power.get(r.userId) ?? { turns: 0, days: new Set<string>() }+ p.turns += r.turnsStarted ?? 0+ p.days.add(r.day)+ power.set(r.userId, p)+ }+ const ranked = [...power.values()].sort((a, b) => b.turns - a.turns)+ const totalTurns = ranked.reduce((n, p) => n + p.turns, 0)+ const turns = ranked.map(p => p.turns).sort((a, b) => a - b)+ const activeDays = ranked.map(p => p.days.size).sort((a, b) => a - b)+ const orphanIds = distinct(SOURCES.flatMap(source => inRange(source, from, opts.asOf)).filter(r => !knownUsers.has(r.userId)))+ const daily = Array.from({ length: opts.days }, (_, i) => {+ const day = shiftDay(from, i)+ const point = summary(day, shiftDay(day, 1))+ const { observedCoverage: _coverage, ...counts } = point+ return counts+ })+ return {+ schemaVersion: 1,+ range: { from, toExclusive: opts.asOf, days: opts.days, timezone: 'UTC', historyFrom: data.historyFrom },+ population: { excludedEmailDomains: [...domains].sort(), excludedAccounts: excluded.size,+ knownAccounts: users.length, accountsCreatedInPeriod: users.filter(u => u.signupDay >= from).length,+ observedUsersWithoutAccountRow: orphanIds.size },+ definitions: {+ appUsers: 'Distinct accounts observed in desktop, TUI, mobile or web presence; an open client is not proof of active work. Surface counts overlap.',+ workingUsers: 'Distinct owners of machines with at least one observed turn_started; includes automated work and only connected, reporting machines.',+ turnsStarted: 'Machine relay counter. Agent counters are an independent reconciliation, never added to machine counters.',+ activeAgents: 'Distinct (machineId, agentId) pairs across the window, not the sum of daily distinct counts.',+ remoteOffers: 'Accepted P2P offers, not confirmed successful sessions; relay-only remote use is not represented.',+ retention: 'Exact-day return after first observed work in the loaded history; excludes its initial, left-censored day. Not signup retention.',+ coverage: 'Earliest/latest stored observations before the cutoff, across all accounts. Not proof of continuous instrumentation; absent observations do not prove inactivity.',+ },+ coverage: data.coverage,+ period: summary(from, opts.asOf),+ windows: { day: summary(shiftDay(opts.asOf, -1), opts.asOf), week: summary(shiftDay(opts.asOf, -7), opts.asOf),+ previousWeek: summary(shiftDay(opts.asOf, -14), shiftDay(opts.asOf, -7)), month: summary(shiftDay(opts.asOf, -30), opts.asOf) },+ weeklyWorkReturn: { previousUsers: previousWork.size, currentUsers: currentWork.size, returned,+ rate: rate(returned, previousWork.size), currentOnly: currentWork.size - returned, previousOnly: previousWork.size - returned },+ firstObservedWorkRetention: { cohorts: cohorts.length, excludedLeftCensoredUsers: firstWork.filter(u => u.first <= boundary).length, exactDayRetention },+ signupActivationWithin7Days: { eligible: signupEligible.length, activated, rate: rate(activated, signupEligible.length) },+ intensity: { workingUsers: ranked.length, medianTurns: quantile(turns, .5), p90Turns: quantile(turns, .9),+ medianActiveDays: quantile(activeDays, .5), usersWithAtLeast5ActiveDays: ranked.filter(p => p.days.size >= 5).length,+ top1Share: rate(ranked.slice(0, 1).reduce((n, p) => n + p.turns, 0), totalTurns),+ top5Share: rate(ranked.slice(0, 5).reduce((n, p) => n + p.turns, 0), totalTurns),+ top10Share: rate(ranked.slice(0, 10).reduce((n, p) => n + p.turns, 0), totalTurns),+ topAccounts: ranked.slice(0, 10).map((p, i) => ({ rank: i + 1, turns: p.turns, activeDays: p.days.size })) },+ daily,+ }+}diff --git a/backend/src/analytics/readProductUsage.test.ts b/backend/src/analytics/readProductUsage.test.tsnew file mode 100644index 000000000..950ea73a3--- /dev/null+++ b/backend/src/analytics/readProductUsage.test.ts@@ -0,0 +1,32 @@+import type { PrismaClient } from '@prisma/client'+import { describe, expect, it, vi } from 'vitest'+import { readProductUsage } from './readProductUsage.js'++function mockDb(result: unknown = []) {+ const aggregateRaw = vi.fn().mockResolvedValue(result)+ const models = ['user', 'userDailyPresence', 'userDailyClientPresence', 'userDailyDevicePresence', 'userDailyRemoteUsage',+ 'machineDailyPresence', 'agentDailyPresence', 'analyticsDailyBucket']+ return { aggregateRaw, db: Object.fromEntries(models.map(m => [m, { aggregateRaw }])) as unknown as PrismaClient }+}++describe('read-only usage extraction', () => {+ it('bounds every query and projects only usage fields, with an exclusive UTC cutoff', async () => {+ const { db, aggregateRaw } = mockDb()+ const result = await readProductUsage(db, { asOf: '2026-10-10', days: 30 })+ expect(result.historyFrom).toBe('2026-07-12')+ expect(result.coverage.collector).toEqual({ rows: 0, firstDay: null, lastDay: null })+ expect(aggregateRaw).toHaveBeenCalledTimes(15)+ for (const [args] of aggregateRaw.mock.calls) {+ expect(args.options).toEqual({ maxTimeMS: 15000, allowDiskUse: false })+ expect(args.pipeline.at(-1)).toEqual({ $limit: 100001 })+ expect(JSON.stringify(args)).not.toMatch(/\$out|\$merge|passwordHash|apiKey|externalId|hostname/)+ expect(JSON.stringify(args.pipeline[0])).toContain('2026-10-10T00:00:00.000Z')+ }+ expect(aggregateRaw.mock.calls[0][0].pipeline[1].$project.email).toBeUndefined()+ })++ it('fails rather than silently truncating a large result or accepting a malformed response', async () => {+ await expect(readProductUsage(mockDb(new Array(100001).fill({})).db, { asOf: '2026-10-10', days: 30 })).rejects.toThrow('100,000')+ await expect(readProductUsage(mockDb({ cursor: {} }).db, { asOf: '2026-10-10', days: 30 })).rejects.toThrow('Unexpected')+ })+})diff --git a/backend/src/analytics/readProductUsage.ts b/backend/src/analytics/readProductUsage.tsnew file mode 100644index 000000000..9f9b64c1f--- /dev/null+++ b/backend/src/analytics/readProductUsage.ts@@ -0,0 +1,46 @@+import type { Prisma, PrismaClient } from '@prisma/client'+import { SOURCES, shiftDay, validateOptions, type Coverage, type UsageData, type UsageOptions, type UsageRow, type UsageUser } from './productUsage.js'++const QUERY_OPTIONS = { maxTimeMS: 15_000, allowDiskUse: false }+const MAX_ROWS = 100_000+type Reader = { aggregateRaw(args: { pipeline: Prisma.InputJsonObject[]; options: Prisma.InputJsonObject }): PromiseLike<unknown> }+const dateString = (field: string) => ({ $dateToString: { date: field, format: '%Y-%m-%d', timezone: 'UTC' } })++/** Only bounded read aggregates; deliberately does not import the application's startup or Prisma singleton. */+export async function readProductUsage(db: PrismaClient, opts: UsageOptions): Promise<UsageData> {+ validateOptions(opts)+ const historyFrom = shiftDay(opts.asOf, -Math.max(90, opts.days))+ const until = { $date: `${opts.asOf}T00:00:00.000Z` }+ const since = { $date: `${historyFrom}T00:00:00.000Z` }+ async function read<T>(model: Reader, pipeline: Prisma.InputJsonObject[]): Promise<T[]> {+ const result = await model.aggregateRaw({ pipeline: [...pipeline, { $limit: MAX_ROWS + 1 }], options: QUERY_OPTIONS })+ if (!Array.isArray(result)) throw new Error('Unexpected database aggregation response')+ if (result.length > MAX_ROWS) throw new Error('Usage query exceeded 100,000 rows; narrow the date range or aggregate on the server')+ return result as T[]+ }+ const users = await read<UsageUser>(db.user, [+ { $match: { createdAt: { $lt: until } } },+ { $project: { _id: 0, userId: { $toString: '$_id' }, signupDay: dateString('$createdAt'),+ emailDomain: { $arrayElemAt: [{ $split: [{ $toLower: { $ifNull: ['$email', ''] } }, '@'] }, -1] } } },+ ])+ const models: Record<typeof SOURCES[number], Reader> = {+ desktop: db.userDailyPresence, clients: db.userDailyClientPresence, devices: db.userDailyDevicePresence,+ remote: db.userDailyRemoteUsage, machines: db.machineDailyPresence, agents: db.agentDailyPresence, collector: db.analyticsDailyBucket,+ }+ const rows = {} as UsageData['rows'], coverage = {} as UsageData['coverage']+ // Sequential bounded aggregates keep load predictable on the production read replica/primary.+ for (const source of SOURCES) {+ const stats = await read<Coverage>(models[source], [+ { $match: { dayUtc: { $lt: until } } },+ { $group: { _id: null, rows: { $sum: 1 }, first: { $min: '$dayUtc' }, last: { $max: '$dayUtc' } } },+ { $project: { _id: 0, rows: 1, firstDay: dateString('$first'), lastDay: dateString('$last') } },+ ])+ coverage[source] = stats[0] ?? { rows: 0, firstDay: null, lastDay: null }+ rows[source] = await read<UsageRow>(models[source], [+ { $match: { dayUtc: { $gte: since, $lt: until } } },+ { $project: { _id: 0, day: dateString('$dayUtc'), userId: 1, machineId: 1, agentId: 1, surface: 1,+ turnsStarted: { $ifNull: ['$turnsStarted', 0] }, connections: { $ifNull: ['$connections', 0] }, sessions: { $ifNull: ['$sessions', 0] } } },+ ])+ }+ return { users, rows, coverage, historyFrom }+}diff --git a/backend/src/lib/dailyTracking.test.ts b/backend/src/lib/dailyTracking.test.tsindex 9413fddd1..91d4d8874 100644--- a/backend/src/lib/dailyTracking.test.ts+++ b/backend/src/lib/dailyTracking.test.ts@@ -1,85 +1,28 @@import { beforeEach, describe, expect, it, vi } from 'vitest'--const db = vi.hoisted(() => ({- userPresenceUpsert: vi.fn(),- machinePresenceUpsert: vi.fn(),- agentPresenceUpsert: vi.fn(),- devicePresenceUpsert: vi.fn(),- clientPresenceUpsert: vi.fn(),-}))--vi.mock('./prisma.js', () => ({- prisma: {- userDailyPresence: { upsert: db.userPresenceUpsert },- machineDailyPresence: { upsert: db.machinePresenceUpsert },- agentDailyPresence: { upsert: db.agentPresenceUpsert },- userDailyDevicePresence: { upsert: db.devicePresenceUpsert },- userDailyClientPresence: { upsert: db.clientPresenceUpsert },- },-}))--import { CLIENT_SURFACES, presenceTracker, presenceWriteDue, recordTurnStarted, touchClientOnlineDay, touchDeviceOnlineDay, touchMachineOnlineDay, touchUserOnlineDay, TUI_SURFACES } from './dailyTracking.js'-import { utcDayStart } from '../types/analytics.js'--describe('touchUserOnlineDay', () => {- beforeEach(() => {- vi.clearAllMocks()- db.userPresenceUpsert.mockResolvedValue({})- })-- it('an app `open` upserts the (user, machine, UTC day) row and bumps connections', async () => {- const now = new Date('2026-09-16T10:15:30.000Z')- await touchUserOnlineDay('user-1', 'machine-a', now, { isNewConnection: true })-- expect(db.userPresenceUpsert).toHaveBeenCalledTimes(1)- const call = db.userPresenceUpsert.mock.calls[0][0]- expect(call.where).toEqual({- userId_machineId_dayUtc: { userId: 'user-1', machineId: 'machine-a', dayUtc: utcDayStart(now) },- })- expect(call.create).toEqual({- userId: 'user-1', machineId: 'machine-a', dayUtc: utcDayStart(now),- connections: 1, firstSeenAt: now, lastSeenAt: now,- })- expect(call.update).toEqual({ lastSeenAt: now, connections: { increment: 1 } })- })-- it('an app `ping` only touches lastSeenAt — a session spanning midnight opens no connection that day', async () => {- const now = new Date('2026-09-16T00:00:20.000Z')- await touchUserOnlineDay('user-1', 'machine-a', now, { isNewConnection: false })-- const call = db.userPresenceUpsert.mock.calls[0][0]- expect(call.update).toEqual({ lastSeenAt: now })- expect(call.create.connections).toBe(0)- })+const record = vi.hoisted(() => vi.fn())+vi.mock('./productUsage.js', () => ({ recordRelayUsage: record }))+import { CLIENT_SURFACES, TUI_SURFACES, presenceTracker, presenceWriteDue, recordRemoteUsage, recordTurnStarted, touchClientOnlineDay, touchDeviceOnlineDay, touchMachineOnlineDay, touchUserOnlineDay } from './dailyTracking.js'++beforeEach(() => { record.mockReset(); record.mockResolvedValue(undefined) })+it('forwards only the choice identity and a fixed metric, never device, agent or location', async () => {+ const now = new Date('2026-10-13T12:00:00Z')+ await touchUserOnlineDay('account', 'PRIVATE_MACHINE', now, { isNewConnection: true })+ await touchClientOnlineDay('account', 'mobile', now, { isNewConnection: true })+ await touchDeviceOnlineDay('account', 'PRIVATE_DEVICE', now, { isNewConnection: true, countryCode: 'VN' })+ await touchMachineOnlineDay('account', 'PRIVATE_MACHINE', now, { isNewConnection: true, countryCode: 'VN' })+ await recordRemoteUsage('account', 'PRIVATE_MACHINE', now)+ await recordTurnStarted('account', 'PRIVATE_MACHINE', 'PRIVATE_AGENT', now)+ expect(record.mock.calls.map(c => c[2])).toEqual(['relay_desktop_opens', 'relay_mobile_opens', 'relay_device_connections', 'relay_machine_connections', 'relay_remote_sessions', 'relay_turns_started'])+ expect(JSON.stringify(record.mock.calls)).not.toContain('PRIVATE_')+ expect(JSON.stringify(record.mock.calls)).not.toContain('VN')})--describe('touchClientOnlineDay', () => {- beforeEach(() => {- vi.clearAllMocks()- db.clientPresenceUpsert.mockResolvedValue({})- })-- it('upserts the (user, surface, UTC day) row — no machine — and only an open counts a connection', async () => {- const now = new Date('2026-10-07T08:00:00.000Z')- await touchClientOnlineDay('user-1', 'mobile', now, { isNewConnection: true })- await touchClientOnlineDay('user-1', 'mobile', now, { isNewConnection: false })-- const [open, ping] = db.clientPresenceUpsert.mock.calls.map((c) => c[0])- expect(open.where).toEqual({ userId_surface_dayUtc: { userId: 'user-1', surface: 'mobile', dayUtc: utcDayStart(now) } })- expect(open.create).toEqual({ userId: 'user-1', surface: 'mobile', dayUtc: utcDayStart(now), connections: 1, firstSeenAt: now, lastSeenAt: now })- expect(open.update).toEqual({ lastSeenAt: now, connections: { increment: 1 } })- expect(ping.update).toEqual({ lastSeenAt: now })- expect(ping.create.connections).toBe(0)- })-- it('tells a TUI on Harness OS, on a PC or an Orange Pi, from the TUI anywhere else', async () => {- expect([...TUI_SURFACES]).toEqual(['tui', 'harness-os', 'harness-os-pi'])- for (const surface of TUI_SURFACES) expect(CLIENT_SURFACES.has(surface)).toBe(true)- for (const other of ['desktop', 'mobile', 'web', 'orangepi', '']) expect(TUI_SURFACES.has(other)).toBe(false)- const now = new Date('2026-10-13T08:00:00.000Z')- await touchClientOnlineDay('user-1', 'harness-os-pi', now, { isNewConnection: true })- expect(db.clientPresenceUpsert.mock.calls[0][0].create).toMatchObject({ userId: 'user-1', surface: 'harness-os-pi' })- })+it('idle heartbeats add no analytics records', async () => {+ const now = new Date()+ await touchUserOnlineDay('a', 'm', now, { isNewConnection: false })+ await touchClientOnlineDay('a', 'tui', now, { isNewConnection: false })+ await touchDeviceOnlineDay('a', 'd', now, { isNewConnection: false })+ await touchMachineOnlineDay('a', 'm', now, { isNewConnection: false })+ expect(record).not.toHaveBeenCalled()})describe('presenceTracker', () => {@@ -128,140 +71,6 @@ describe('presenceTracker', () => {})})-describe('touchDeviceOnlineDay', () => {- beforeEach(() => {- vi.clearAllMocks()- db.devicePresenceUpsert.mockResolvedValue({})- })-- it('a connect upserts the (user, device, UTC day) row, bumps connections and stamps the country', async () => {- const now = new Date('2026-09-23T10:15:30.000Z')- await touchDeviceOnlineDay('user-1', 'device-a', now, { isNewConnection: true, countryCode: 'VN' })-- const call = db.devicePresenceUpsert.mock.calls[0][0]- expect(call.where).toEqual({- userId_deviceId_dayUtc: { userId: 'user-1', deviceId: 'device-a', dayUtc: utcDayStart(now) },- })- expect(call.create).toEqual({- userId: 'user-1', deviceId: 'device-a', dayUtc: utcDayStart(now),- connections: 1, firstSeenAt: now, lastSeenAt: now, countryCode: 'VN',- })- expect(call.update).toEqual({ lastSeenAt: now, connections: { increment: 1 }, countryCode: 'VN' })- })-- it('a refresh on an open socket only moves lastSeenAt — and a row it creates after midnight counts no connection', async () => {- const now = new Date('2026-09-23T00:05:00.000Z')- await touchDeviceOnlineDay('user-1', 'device-a', now, { isNewConnection: false })-- const call = db.devicePresenceUpsert.mock.calls[0][0]- expect(call.update).toEqual({ lastSeenAt: now })- expect(call.create.connections).toBe(0)- expect(call.create.countryCode).toBeUndefined()- })-})--describe('touchMachineOnlineDay', () => {- beforeEach(() => {- vi.clearAllMocks()- db.machinePresenceUpsert.mockResolvedValue({})- })-- it('upserts the (machine, UTC day) row and bumps connections on a new connection', async () => {- const now = new Date('2026-09-16T10:15:30.000Z')- await touchMachineOnlineDay('user-1', 'machine-a', now, { isNewConnection: true })-- expect(db.machinePresenceUpsert).toHaveBeenCalledTimes(1)- const call = db.machinePresenceUpsert.mock.calls[0][0]- expect(call.where).toEqual({ machineId_dayUtc: { machineId: 'machine-a', dayUtc: utcDayStart(now) } })- expect(call.create).toEqual({- machineId: 'machine-a', userId: 'user-1', dayUtc: utcDayStart(now),- connections: 1, firstSeenAt: now, lastSeenAt: now,- })- expect(call.update).toEqual({ lastSeenAt: now, connections: { increment: 1 } })- })-- it('only touches lastSeenAt on a heartbeat/close (no connections increment)', async () => {- const now = new Date('2026-09-16T23:59:59.000Z')- await touchMachineOnlineDay('user-1', 'machine-a', now, { isNewConnection: false })-- const call = db.machinePresenceUpsert.mock.calls[0][0]- expect(call.update).toEqual({ lastSeenAt: now })- // First write of a new UTC day from a session that spans midnight: the row exists, but no- // connection was opened on that day.- expect(call.create.connections).toBe(0)- })-- it('carries the Cloudflare country into both create and update (last write of the day wins)', async () => {- const now = new Date('2026-09-16T10:15:30.000Z')- await touchMachineOnlineDay('user-1', 'machine-a', now, { isNewConnection: false, countryCode: 'VN' })-- const call = db.machinePresenceUpsert.mock.calls[0][0]- expect(call.create.countryCode).toBe('VN')- expect(call.update).toEqual({ lastSeenAt: now, countryCode: 'VN' })- })-- it('never clears a country: a touch without one leaves the column out of the write', async () => {- const now = new Date('2026-09-16T10:15:30.000Z')- await touchMachineOnlineDay('user-1', 'machine-a', now, { isNewConnection: true })-- const call = db.machinePresenceUpsert.mock.calls[0][0]- expect(call.create).not.toHaveProperty('countryCode')- expect(call.update).not.toHaveProperty('countryCode')- })-- it('propagates a DB failure so the caller can log it and keep its guard unchanged', async () => {- db.machinePresenceUpsert.mockRejectedValueOnce(new Error('mongo down'))- await expect(- touchMachineOnlineDay('user-1', 'machine-a', new Date(), { isNewConnection: true }),- ).rejects.toThrow('mongo down')- })-})--describe('recordTurnStarted', () => {- const now = new Date('2026-09-16T10:15:30.000Z')-- beforeEach(() => {- vi.clearAllMocks()- db.machinePresenceUpsert.mockResolvedValue({})- db.agentPresenceUpsert.mockResolvedValue({})- })-- it('bumps turnsStarted on the machine row without counting a connection', async () => {- await recordTurnStarted('user-1', 'machine-a', 'agent-x', now)-- expect(db.machinePresenceUpsert).toHaveBeenCalledTimes(1)- const call = db.machinePresenceUpsert.mock.calls[0][0]- expect(call.where).toEqual({ machineId_dayUtc: { machineId: 'machine-a', dayUtc: utcDayStart(now) } })- expect(call.create).toEqual({- machineId: 'machine-a', userId: 'user-1', dayUtc: utcDayStart(now),- connections: 0, turnsStarted: 1, firstSeenAt: now, lastSeenAt: now,- })- expect(call.update).toEqual({ lastSeenAt: now, turnsStarted: { increment: 1 } })- })-- it('bumps the (machine, agent, day) row', async () => {- await recordTurnStarted('user-1', 'machine-a', 'agent-x', now)-- expect(db.agentPresenceUpsert).toHaveBeenCalledTimes(1)- const call = db.agentPresenceUpsert.mock.calls[0][0]- expect(call.where).toEqual({- machineId_agentId_dayUtc: { machineId: 'machine-a', agentId: 'agent-x', dayUtc: utcDayStart(now) },- })- expect(call.create).toEqual({- machineId: 'machine-a', agentId: 'agent-x', userId: 'user-1', dayUtc: utcDayStart(now),- turnsStarted: 1, firstSeenAt: now, lastSeenAt: now,- })- expect(call.update).toEqual({ lastSeenAt: now, turnsStarted: { increment: 1 } })- })-- it('propagates a failure from either upsert', async () => {- db.agentPresenceUpsert.mockRejectedValueOnce(new Error('agent row failed'))- await expect(recordTurnStarted('user-1', 'machine-a', 'agent-x', now)).rejects.toThrow('agent row failed')- // The machine write was still attempted — the two are independent.- expect(db.machinePresenceUpsert).toHaveBeenCalledTimes(1)- })-})-describe('presenceWriteDue', () => {const FIVE_MIN = 5 * 60_000const t0 = new Date('2026-09-16T10:00:00.000Z')@@ -287,3 +96,15 @@ describe('presenceWriteDue', () => {expect(presenceWriteDue(last, new Date('2026-09-17T00:00:05.000Z'), FIVE_MIN)).toBe(true)})})++it('keeps Harness OS and Orange Pi connections separate without storing identity', async () => {+ expect([...TUI_SURFACES]).toEqual(['tui', 'harness-os', 'harness-os-pi'])+ for (const surface of TUI_SURFACES) expect(CLIENT_SURFACES.has(surface)).toBe(true)+ for (const other of ['desktop', 'mobile', 'web', 'orangepi', '']) expect(TUI_SURFACES.has(other)).toBe(false)+ const now = new Date('2026-10-13T08:00:00.000Z')+ await touchClientOnlineDay('account', 'harness-os', now, { isNewConnection: true })+ await touchClientOnlineDay('account', 'harness-os-pi', now, { isNewConnection: true })+ expect(record.mock.calls).toEqual([+ ['account', now, 'relay_harness-os_opens'], ['account', now, 'relay_harness-os-pi_opens'],+ ])+})diff --git a/backend/src/lib/dailyTracking.ts b/backend/src/lib/dailyTracking.tsindex 789dbfc0b..e1b5d198e 100644--- a/backend/src/lib/dailyTracking.ts+++ b/backend/src/lib/dailyTracking.ts@@ -1,151 +1,26 @@-/**- * Presence / remote-usage daily tracking — write path for `UserDailyPresence`,- * `UserDailyClientPresence`, `UserDailyRemoteUsage`, `UserDailyDevicePresence`, `MachineDailyPresence` and- * `AgentDailyPresence` (prisma/schema.prisma). Separate model family and separate module from the- * opt-in `Analytics*` telemetry in analyticsIngest.ts: these signals are derived directly from the- * device-ws/adapter-ws relays (src/lib/deviceWs.ts, src/lib/adapterWs.ts) plus the p2p_offer tap on- * web-ws (src/lib/webWs.ts), not from a collector upload.- *- * Unlike analyticsIngest.ts, none of these rows need last-write-wins ordering (there's no- * client-supplied revision to defend against), so each touch is a plain atomic `upsert` on the- * day's unique key — no separate create-then-swallow-P2002 step that could drop a concurrent- * write's `lastSeenAt`/counter increment.- *- * All entry points are meant to be called fire-and-forget from the hot path (connection open,- * heartbeat/ping, p2p_offer) — callers must not await them inline.- *- * `countryCode` on the device and machine touches is Cloudflare's `CF-IPCountry` read at the WS- * upgrade (lib/clientGeo.ts). It is last-write-wins within the day and only ever SET, never cleared:- * a touch without one (local dev, a relay not fronted by Cloudflare) leaves whatever the row has.- * `touchUserOnlineDay` takes none on purpose — its socket belongs to the daemon, not the person- * (see the model doc in schema.prisma); the person's country is `User.lastCountryCode`.+/** Relay signals contribute only daily fleet totals. Operational live presence stays in Redis.+ * No new account/machine/agent activity history is written here. Older row types remain readable+ * during their bounded expiry window; their historical metrics must not be mixed with these totals.*/-import { prisma } from './prisma.js'-import { utcDayKey, utcDayStart } from '../types/analytics.js'+import { utcDayKey } from '../types/analytics.js'+import { recordRelayUsage } from './productUsage.js'-/** Options for the device/machine presence touches. */-export interface PresenceTouchOpts {- isNewConnection: boolean- /** ISO-2 from `CF-IPCountry` at the upgrade; omit when unknown (see module doc). */- countryCode?: string-}+export interface PresenceTouchOpts { isNewConnection: boolean; countryCode?: string }-/**- * Mark a user online, on `machineId`, for the UTC day containing `now`. The signal is the `harness`- * daemon's `app_presence` frame over adapter-ws (src/lib/adapterWs.ts), sent about its own loopback- * clients: `isNewConnection: true` when a desktop window just attached to the daemon (bumps- * `connections`), `false` for the periodic ping while one stays attached (just touches `lastSeenAt`,- * at most every USER_PRESENCE_WRITE_MS). Not the web-ws upgrade — the app never dials that itself.- *- * One row per (user, machine, day): a person with the app open on two computers gets two rows that- * day, so "users online on day X" is a distinct count of `userId`, never a row count.- *- * `connections` counts app sessions OPENED on that day: a touch that is the first write of a new- * UTC day but is not an open (a session spanning midnight) creates the row with `connections: 0`,- * so summing the column across days never double-counts one long session. Same rule for every- * `touch*OnlineDay` below.- */-export async function touchUserOnlineDay(- userId: string,- machineId: string,- now: Date,- opts: { isNewConnection: boolean },-): Promise<void> {- const dayUtc = utcDayStart(now)- await prisma.userDailyPresence.upsert({- where: { userId_machineId_dayUtc: { userId, machineId, dayUtc } },- create: { userId, machineId, dayUtc, connections: opts.isNewConnection ? 1 : 0, firstSeenAt: now, lastSeenAt: now },- update: {- lastSeenAt: now,- ...(opts.isNewConnection ? { connections: { increment: 1 } } : {}),- },- })+export async function touchUserOnlineDay(userId: string, _machineId: string, now: Date, opts: { isNewConnection: boolean }): Promise<void> {+ if (opts.isNewConnection) await recordRelayUsage(userId, now, 'relay_desktop_opens')}--/**- * Record that a user actually established a remote p2p connection (a `p2p_offer` frame passed- * through the relay) to `machineId` on the UTC day containing `now`.- */-export async function recordRemoteUsage(userId: string, machineId: string, now: Date): Promise<void> {- const dayUtc = utcDayStart(now)- await prisma.userDailyRemoteUsage.upsert({- where: { userId_machineId_dayUtc: { userId, machineId, dayUtc } },- create: { userId, machineId, dayUtc, sessions: 1, firstSeenAt: now, lastSeenAt: now },- update: { lastSeenAt: now, sessions: { increment: 1 } },- })+export async function recordRemoteUsage(userId: string, _machineId: string, now: Date): Promise<void> {+ await recordRelayUsage(userId, now, 'relay_remote_sessions')}--/**- * Mark a user's device online for the UTC day containing `now`, mirroring `touchUserOnlineDay`- * for the device-ws relay (src/lib/deviceWs.ts) instead of web-ws.- */-export async function touchDeviceOnlineDay(- userId: string,- deviceId: string,- now: Date,- opts: PresenceTouchOpts,-): Promise<void> {- const dayUtc = utcDayStart(now)- await prisma.userDailyDevicePresence.upsert({- where: { userId_deviceId_dayUtc: { userId, deviceId, dayUtc } },- create: { userId, deviceId, dayUtc, connections: opts.isNewConnection ? 1 : 0, firstSeenAt: now, lastSeenAt: now, ...(opts.countryCode ? { countryCode: opts.countryCode } : {}) },- update: {- lastSeenAt: now,- ...(opts.isNewConnection ? { connections: { increment: 1 } } : {}),- ...(opts.countryCode ? { countryCode: opts.countryCode } : {}),- },- })+export async function touchDeviceOnlineDay(userId: string, _deviceId: string, now: Date, opts: PresenceTouchOpts): Promise<void> {+ if (opts.isNewConnection) await recordRelayUsage(userId, now, 'relay_device_connections')}--/**- * Mark a machine's `harness` daemon online for the UTC day containing `now`, mirroring- * `touchUserOnlineDay` for the adapter-ws relay (src/lib/adapterWs.ts). `userId` is the owner at- * connect time, denormalized so per-user rollups need no join through `machines`.- */-export async function touchMachineOnlineDay(- userId: string,- machineId: string,- now: Date,- opts: PresenceTouchOpts,-): Promise<void> {- const dayUtc = utcDayStart(now)- await prisma.machineDailyPresence.upsert({- where: { machineId_dayUtc: { machineId, dayUtc } },- create: { machineId, userId, dayUtc, connections: opts.isNewConnection ? 1 : 0, firstSeenAt: now, lastSeenAt: now, ...(opts.countryCode ? { countryCode: opts.countryCode } : {}) },- update: {- lastSeenAt: now,- ...(opts.isNewConnection ? { connections: { increment: 1 } } : {}),- ...(opts.countryCode ? { countryCode: opts.countryCode } : {}),- },- })+export async function touchMachineOnlineDay(userId: string, _machineId: string, now: Date, opts: PresenceTouchOpts): Promise<void> {+ if (opts.isNewConnection) await recordRelayUsage(userId, now, 'relay_machine_connections')}--/**- * Count one `turn_started` the machine's daemon reported for `agentId` on the UTC day containing- * `now`: bumps the machine row's `turnsStarted` and the (machine, agent) row. Both also touch- * `lastSeenAt` — a turn is the strongest liveness signal there is. The two upserts are independent- * atomic `$inc`s, deliberately not a transaction: a partial failure under-counts one row by one and- * the caller's warn log says so, which beats a transaction retry loop on the relay's hot path.- */-export async function recordTurnStarted(- userId: string,- machineId: string,- agentId: string,- now: Date,-): Promise<void> {- const dayUtc = utcDayStart(now)- await Promise.all([- prisma.machineDailyPresence.upsert({- where: { machineId_dayUtc: { machineId, dayUtc } },- create: { machineId, userId, dayUtc, connections: 0, turnsStarted: 1, firstSeenAt: now, lastSeenAt: now },- update: { lastSeenAt: now, turnsStarted: { increment: 1 } },- }),- prisma.agentDailyPresence.upsert({- where: { machineId_agentId_dayUtc: { machineId, agentId, dayUtc } },- create: { machineId, agentId, userId, dayUtc, turnsStarted: 1, firstSeenAt: now, lastSeenAt: now },- update: { lastSeenAt: now, turnsStarted: { increment: 1 } },- }),- ])+export async function recordTurnStarted(userId: string, _machineId: string, _agentId: string, now: Date): Promise<void> {+ await recordRelayUsage(userId, now, 'relay_turns_started')}/** Last SUCCESSFUL presence write for one open socket — `dayKey` null until the first one lands. */@@ -163,40 +38,22 @@ export function presenceWriteDue(last: PresenceWriteState, now: Date, minIntervareturn now.getTime() - last.wroteAt >= minIntervalMs}-/** Surfaces other than the desktop app whose person is counted (`user_daily_client_presence`). */+/** Relay surfaces with separate connection totals, never distinct-person counts. */export type ClientSurface = 'tui' | 'harness-os' | 'harness-os-pi' | 'mobile' | 'web'export const CLIENT_SURFACES: ReadonlySet<string> = new Set<ClientSurface>(['tui', 'harness-os', 'harness-os-pi', 'mobile', 'web'])-/** What a daemon reports a `harness tui` window as: the TUI, or Harness OS on a PC or an Orange Pi- * (cli lib/windowSurfaces.ts tuiPresence), so a person's source is told apart. */+/** Known terminal surfaces retain their platform distinction in fleet connection totals. */export const TUI_SURFACES: ReadonlySet<string> = new Set<ClientSurface>(['tui', 'harness-os', 'harness-os-pi'])-/**- * `touchUserOnlineDay` for the other surfaces, one row per (user, surface, day): the TUI reported by- * the daemon like a desktop window (`app_presence { surface: 'tui' }`, src/lib/adapterWs.ts), the- * mobile app and the web viewer from their own web-ws sockets (src/lib/webWs.ts). No machine: the- * mobile app and the web hold one socket per machine they look at, and the person is the same.- */+/** Keep old protocol entry points while reducing only new connection events into fleet totals. */export async function touchClientOnlineDay(- userId: string,- surface: ClientSurface,- now: Date,- opts: { isNewConnection: boolean },+ userId: string, surface: ClientSurface, now: Date, opts: { isNewConnection: boolean },): Promise<void> {- const dayUtc = utcDayStart(now)- await prisma.userDailyClientPresence.upsert({- where: { userId_surface_dayUtc: { userId, surface, dayUtc } },- create: { userId, surface, dayUtc, connections: opts.isNewConnection ? 1 : 0, firstSeenAt: now, lastSeenAt: now },- update: {- lastSeenAt: now,- ...(opts.isNewConnection ? { connections: { increment: 1 } } : {}),- },- })+ if (opts.isNewConnection) await recordRelayUsage(userId, now, `relay_${surface}_opens`)}/**- * The write discipline every person-presence signal shares: `open` counts a session (at most once per- * `openFloorMs`, so a reconnect storm is not a hundred sessions), `ping` only refreshes `lastSeenAt`- * and at most every `pingFloorMs` (or on a new UTC day), and one write is in flight at a time.+ * The legacy protocol's cadence: `open` counts an event at most once per `openFloorMs`, so a reconnect+ * storm is not a hundred sessions. `ping` is still throttled but its callback no longer stores history.* `write` gets `isNewConnection`; failures go to `onError` — callers never await this.*/export function presenceTracker(diff --git a/backend/src/lib/productUsage.test.ts b/backend/src/lib/productUsage.test.tsnew file mode 100644index 000000000..0b496f320--- /dev/null+++ b/backend/src/lib/productUsage.test.ts@@ -0,0 +1,119 @@+import { beforeEach, describe, expect, it, vi } from 'vitest'+import { readFileSync } from 'node:fs'++const db = vi.hoisted(() => ({+ productUsagePreference: { findUnique: vi.fn(), upsert: vi.fn() },+ analyticsMachineState: { findFirst: vi.fn() },+ productUsageReceipt: { create: vi.fn(), findUnique: vi.fn() },+ productUsageTotal: { upsert: vi.fn(), update: vi.fn() },+ userDailyPresence: { deleteMany: vi.fn() }, userDailyClientPresence: { deleteMany: vi.fn() },+ userDailyRemoteUsage: { deleteMany: vi.fn() }, userDailyDevicePresence: { deleteMany: vi.fn() },+ machineDailyPresence: { deleteMany: vi.fn() }, agentDailyPresence: { deleteMany: vi.fn() },+ $transaction: vi.fn(), $runCommandRaw: vi.fn(),+}))+vi.mock('./prisma.js', () => ({ prisma: db }))+import { deleteLegacyProductUsage, ensureProductUsageExpiry, ingestProductUsage, productUsageChoice, recordRelayUsage, setProductUsageChoice } from './productUsage.js'+import type { ProductUsageReport } from '../types/productUsage.js'++const report: ProductUsageReport = { schemaVersion: 1, revision: 0, id: 'cf1c5a03-388c-4265-b5fb-a4c3d47e407f', day: '2026-10-13', counters: { turns_started: 4, turns_ended: 3 } }+const now = new Date('2026-10-13T12:00:00Z')+beforeEach(() => {+ vi.resetAllMocks()+ db.$transaction.mockImplementation((fn: (tx: typeof db) => unknown) => fn(db))+ db.productUsagePreference.findUnique.mockResolvedValue(null)+ db.analyticsMachineState.findFirst.mockResolvedValue(null)+})++it('keeps the client and server vocabulary identical', () => {+ expect(readFileSync(new URL('../../../cli/src/lib/productUsageContract.ts', import.meta.url), 'utf8'))+ .toBe(readFileSync(new URL('../types/productUsage.ts', import.meta.url), 'utf8'))+})++describe('preference', () => {+ it('defaults on but preserves a prior off choice', async () => {+ expect(await productUsageChoice('private-account')).toEqual({ enabled: true, revision: 0 })+ db.analyticsMachineState.findFirst.mockResolvedValue({ id: 'old-setting' })+ expect(await productUsageChoice('private-account')).toEqual({ enabled: false, revision: 0 })+ db.productUsagePreference.findUnique.mockResolvedValue({ enabled: false, revision: 9 })+ expect(await productUsageChoice('private-account')).toEqual({ enabled: false, revision: 9 })+ })+ it('advances the queue generation on every saved choice', async () => {+ await setProductUsageChoice('account', false)+ expect(db.productUsagePreference.upsert.mock.calls[0][0]).toMatchObject({+ create: { userId: 'account', enabled: false, revision: 1 }, update: { enabled: false, revision: { increment: 1 } },+ })+ })+})++describe('aggregate ingestion', () => {+ it('stores only totals and an unlinked receipt, in one transaction', async () => {+ expect(await ingestProductUsage('private-account', report, now)).toEqual({ accepted: true })+ expect(db.$transaction).toHaveBeenCalledOnce()+ expect(db.productUsageTotal.upsert).toHaveBeenCalledTimes(2)+ expect(db.productUsageTotal.upsert.mock.calls[0][0]).toEqual({+ where: { dayUtc_metric: { dayUtc: new Date('2026-10-13'), metric: 'turns_started' } },+ create: { dayUtc: new Date('2026-10-13'), metric: 'turns_started', value: 4 }, update: { value: { increment: 4 } },+ })+ const stored = JSON.stringify([db.productUsageTotal.upsert.mock.calls, db.productUsageReceipt.create.mock.calls])+ for (const forbidden of ['private-account', 'userId', 'machineId', 'agentId', 'revision', 'counters', 'receivedAt']) expect(stored).not.toContain(forbidden)+ })+ it('rejects opted-out and stale queued uploads without receipts or counters', async () => {+ db.productUsagePreference.findUnique.mockResolvedValue({ enabled: false, revision: 1 })+ expect(await ingestProductUsage('a', report, now)).toMatchObject({ accepted: false, reason: 'CHOICE_CHANGED' })+ db.productUsagePreference.findUnique.mockResolvedValue({ enabled: true, revision: 2 })+ expect(await ingestProductUsage('a', report, now)).toMatchObject({ accepted: false, reason: 'CHOICE_CHANGED' })+ expect(db.productUsageReceipt.create).not.toHaveBeenCalled()+ expect(db.productUsageTotal.upsert).not.toHaveBeenCalled()+ })+ it.each(['2026-09-08', '2026-10-14', '2026-02-30', 'bad'])('refuses expired/future/invalid day %s', async day => {+ expect(await ingestProductUsage('a', { ...report, day }, now)).toEqual({ accepted: false, reason: 'EXPIRED' })+ expect(db.$transaction).not.toHaveBeenCalled()+ })+ it('accepts a previously committed receipt without incrementing again', async () => {+ db.productUsageReceipt.create.mockRejectedValue({ code: 'P2002' })+ db.productUsageReceipt.findUnique.mockResolvedValue({ id: report.id })+ expect(await ingestProductUsage('a', report, now)).toEqual({ accepted: true })+ expect(db.productUsageTotal.upsert).not.toHaveBeenCalled()+ })+ it('does not mistake a rolled-back aggregate creation race for a received report', async () => {+ db.productUsageTotal.upsert.mockRejectedValue({ code: 'P2002' })+ db.productUsageReceipt.findUnique.mockResolvedValue(null)+ await expect(ingestProductUsage('a', report, now)).rejects.toMatchObject({ code: 'P2002' })+ })+ it('fails closed when the preference cannot be checked', async () => {+ db.productUsagePreference.findUnique.mockRejectedValue(new Error('unavailable'))+ await expect(ingestProductUsage('a', report, now)).rejects.toThrow()+ expect(db.productUsageReceipt.create).not.toHaveBeenCalled()+ })+})++it('the legacy relay respects off and writes only an aggregate counter when on', async () => {+ db.productUsagePreference.findUnique.mockResolvedValue({ enabled: false, revision: 1 })+ await recordRelayUsage('private-account', now, 'relay_turns_started')+ expect(db.productUsageTotal.upsert).not.toHaveBeenCalled()+ db.productUsagePreference.findUnique.mockResolvedValue({ enabled: true, revision: 2 })+ await recordRelayUsage('private-account', now, 'relay_turns_started')+ expect(JSON.stringify(db.productUsageTotal.upsert.mock.calls)).not.toContain('private-account')+})++it('a relay metrics failure cannot interrupt work or log an identity or database error', async () => {+ const log = vi.spyOn(console, 'warn').mockImplementation(() => {})+ db.productUsagePreference.findUnique.mockRejectedValue(new Error('PRIVATE_DATABASE_CANARY'))+ await expect(recordRelayUsage('PRIVATE_ACCOUNT_CANARY', now, 'relay_turns_started')).resolves.toBeUndefined()+ expect(JSON.stringify(log.mock.calls)).not.toContain('PRIVATE_')+ expect(db.productUsageTotal.upsert).not.toHaveBeenCalled()+ log.mockRestore()+})++it('the legacy delete path erases all six linked activity collections', async () => {+ await deleteLegacyProductUsage('account')+ for (const name of ['userDailyPresence', 'userDailyClientPresence', 'userDailyRemoteUsage', 'userDailyDevicePresence', 'machineDailyPresence', 'agentDailyPresence'] as const)+ expect(db[name].deleteMany).toHaveBeenCalledWith({ where: { userId: 'account' } })+})++it('installs database expiry for receipts, totals and every linked daily history', async () => {+ await ensureProductUsageExpiry()+ expect(db.$runCommandRaw).toHaveBeenCalledTimes(10)+ expect(db.$runCommandRaw.mock.calls[0][0]).toMatchObject({ createIndexes: 'product_usage_receipts', indexes: [{ expireAfterSeconds: 0 }] })+ expect(db.$runCommandRaw.mock.calls[2][0]).toMatchObject({ createIndexes: 'user_daily_presence', indexes: [{ expireAfterSeconds: 35 * 86400 }] })+})diff --git a/backend/src/lib/productUsage.ts b/backend/src/lib/productUsage.tsnew file mode 100644index 000000000..fe51aefe0--- /dev/null+++ b/backend/src/lib/productUsage.ts@@ -0,0 +1,108 @@+import type { Prisma } from '@prisma/client'+import { prisma } from './prisma.js'+import { PRODUCT_USAGE_DAYS, type ProductUsageChoice, type ProductUsageReport } from '../types/productUsage.js'++const DAY = 86_400_000+type Db = Pick<Prisma.TransactionClient, 'productUsagePreference' | 'analyticsMachineState'>++/** A pre-existing off choice wins over the new default. Never cache an enabled answer. */+export async function productUsageChoice(userId: string, db: Db = prisma): Promise<ProductUsageChoice> {+ const saved = await db.productUsagePreference.findUnique({ where: { userId }, select: { enabled: true, revision: true } })+ if (saved) return saved+ const off = await db.analyticsMachineState.findFirst({ where: { userId, consent: 'off' }, select: { id: true } })+ return { enabled: !off, revision: 0 }+}++export async function setProductUsageChoice(userId: string, enabled: boolean): Promise<ProductUsageChoice> {+ // Every explicit save advances the generation. A queue prepared before an off/on cycle is refused.+ return prisma.productUsagePreference.upsert({+ where: { userId }, create: { userId, enabled, revision: 1 },+ update: { enabled, revision: { increment: 1 } }, select: { enabled: true, revision: true },+ })+}++function validDay(day: string, now: Date): boolean {+ const stamp = Date.parse(day + 'T00:00:00.000Z')+ const today = Math.floor(now.getTime() / DAY) * DAY+ return Number.isFinite(stamp) && new Date(stamp).toISOString().slice(0, 10) === day+ && stamp <= today && stamp > today - PRODUCT_USAGE_DAYS * DAY+}++/** Identity is used for permission only. Neither it nor the report body reaches analytics storage. */+export async function ingestProductUsage(userId: string, report: ProductUsageReport, now = new Date()) {+ if (!validDay(report.day, now)) return { accepted: false, reason: 'EXPIRED' }+ try {+ return await prisma.$transaction(async tx => {+ const choice = await productUsageChoice(userId, tx)+ if (!choice.enabled || choice.revision !== report.revision) return { accepted: false, reason: 'CHOICE_CHANGED', ...choice }+ // Receipt and increments commit together; a lost HTTP response can be retried with the same id.+ await tx.productUsageReceipt.create({ data: {+ id: report.id, expiresAt: new Date(Date.parse(report.day) + (PRODUCT_USAGE_DAYS + 1) * DAY),+ } })+ for (const [metric, value] of Object.entries(report.counters)) {+ if (!value) continue+ await tx.productUsageTotal.upsert({+ where: { dayUtc_metric: { dayUtc: new Date(report.day), metric } },+ create: { dayUtc: new Date(report.day), metric, value }, update: { value: { increment: value } },+ })+ }+ return { accepted: true }+ })+ } catch (error) {+ // A competing first writer of a daily total is NOT a duplicate report: let the client retry it.+ if ((error as { code?: string }).code === 'P2002'+ && await prisma.productUsageReceipt.findUnique({ where: { id: report.id }, select: { id: true } })) return { accepted: true }+ throw error+ }+}++export type RelayUsageMetric = 'relay_desktop_opens' | 'relay_tui_opens' | 'relay_mobile_opens' | 'relay_web_opens'+ | 'relay_harness-os_opens' | 'relay_harness-os-pi_opens'+ | 'relay_device_connections' | 'relay_machine_connections' | 'relay_remote_sessions' | 'relay_turns_started'++let warnedAt = 0+/** Older clients still contribute totals. These are events, never distinct users or installations. */+export async function recordRelayUsage(userId: string, now: Date, metric: RelayUsageMetric): Promise<void> {+ try {+ if (!(await productUsageChoice(userId)).enabled) return+ const dayUtc = new Date(Math.floor(now.getTime() / DAY) * DAY)+ const where = { dayUtc_metric: { dayUtc, metric } }+ try {+ await prisma.productUsageTotal.upsert({ where, create: { dayUtc, metric, value: 1 }, update: { value: { increment: 1 } } })+ } catch (error) {+ if ((error as { code?: string }).code !== 'P2002') throw error+ await prisma.productUsageTotal.update({ where, data: { value: { increment: 1 } } })+ }+ } catch {+ // Do not let analytics break a session or reach callers that log the account/agent and DB error.+ if (Date.now() - warnedAt >= 60_000) {+ warnedAt = Date.now()+ console.warn('[product-usage] Some aggregate counts are unavailable.')+ }+ }+}++/** These were individual histories, not anonymous totals. The existing delete control must cover them. */+export async function deleteLegacyProductUsage(userId: string): Promise<void> {+ await Promise.all([+ prisma.userDailyPresence.deleteMany({ where: { userId } }),+ prisma.userDailyClientPresence.deleteMany({ where: { userId } }),+ prisma.userDailyRemoteUsage.deleteMany({ where: { userId } }),+ prisma.userDailyDevicePresence.deleteMany({ where: { userId } }),+ prisma.machineDailyPresence.deleteMany({ where: { userId } }),+ prisma.agentDailyPresence.deleteMany({ where: { userId } }),+ ])+}++/** Run only in the singleton worker. Expiry is enforced by Mongo, including during application downtime. */+export async function ensureProductUsageExpiry(): Promise<void> {+ for (const [collection, field, seconds] of [+ ['product_usage_receipts', 'expiresAt', 0],+ ['product_usage_totals', 'dayUtc', 396 * DAY / 1000],+ ...['user_daily_presence', 'user_daily_client_presence', 'user_daily_remote_usage', 'user_daily_device_presence',+ 'machine_daily_presence', 'agent_daily_presence', 'analytics_daily_buckets', 'analytics_daily_machines']+ .map(name => [name, 'dayUtc', PRODUCT_USAGE_DAYS * DAY / 1000]),+ ] as [string, string, number][]) {+ await prisma.$runCommandRaw({ createIndexes: collection, indexes: [{ key: { [field]: 1 }, name: 'product_usage_expiry', expireAfterSeconds: seconds }] })+ }+}diff --git a/backend/src/middlewares/authMiddleware.ts b/backend/src/middlewares/authMiddleware.tsindex dd3194ef1..6c993c82a 100644--- a/backend/src/middlewares/authMiddleware.ts+++ b/backend/src/middlewares/authMiddleware.ts@@ -106,7 +106,8 @@ export function registerAuthMiddleware(// Except the Grid profile route: its caller is the Grid control plane asking on the person's// behalf, from a datacenter, and stamping that would relabel them (routes/grid.ts).const countryCode = countryCodeFromHeaders(request.headers)- if (countryCode && !isGridProfileRequest(request)) void stampUserCountry(auth.user.sub, countryCode)+ if (countryCode && !isGridProfileRequest(request)+ && !request.url.split('?')[0].startsWith('/api/product-usage/')) void stampUserCountry(auth.user.sub, countryCode)return}return reply.code(auth.status).send({diff --git a/backend/src/productUsageReport.ts b/backend/src/productUsageReport.tsnew file mode 100644index 000000000..39207295c--- /dev/null+++ b/backend/src/productUsageReport.ts@@ -0,0 +1,28 @@+/** Aggregate-only daily report. Run with a read-only database identity; never prints identifiers. */+import { PrismaClient } from '@prisma/client'+import { DAILY_PRODUCT_METRICS, dailyProductUsage } from './analytics/dailyProductUsage.js'+import { dailyProductReview } from './analytics/dailyProductReview.js'+const days = Number(process.argv[2] ?? 14)+if (!Number.isInteger(days) || days < 1 || days > 90) throw new Error('Choose 1–90 days')+const db = new PrismaClient()+try {+ const today = Math.floor(Date.now() / 86400000) * 86400000+ const rows = await db.productUsageTotal.findMany({+ // Retention always needs the two preceding complete weeks, even for a one-day daily view.+ where: { dayUtc: { gte: new Date(today - Math.max(days - 1, 21) * 86400000), lt: new Date(today + 86400000) }, metric: { in: [...DAILY_PRODUCT_METRICS] } },+ select: { dayUtc: true, metric: true, value: true }, orderBy: [{ dayUtc: 'asc' }, { metric: 'asc' }], take: Math.max(days, 22) * DAILY_PRODUCT_METRICS.length,+ })+ console.log(JSON.stringify({ generatedAt: new Date().toISOString(), timezone: 'UTC',+ definitions: {+ population: 'Reporting signed-in computers, including staff and both service environments; opted-out accounts excluded. Not unique people.',+ active: 'An attached desktop/terminal window or a reported agent turn; background presence can count.',+ working: 'At least one new observed agent turn; human and automated work are combined.',+ first: 'First measured work since the current preference generation, not account signup or task success.',+ activation: 'No signup-to-value activation rate is inferred from first measured work. This report has no signup denominator or task-success signal.',+ weekly: 'Monday–Sunday UTC; compare weekly_returning_installations in a complete week with weekly_working_installations in the preceding complete week.',+ outcomes: 'Matched observed turn ends and interruptions, not task success. Missing or interrupted telemetry is not a failed task.',+ relay: 'Legacy relay event totals are separate; never add them to the client counters.',+ coverage: 'New local counters need updated clients. Delayed/offline reports and privacy changes can affect counts; today is incomplete.',+ }, ...dailyProductUsage(rows, days, new Date()), review: dailyProductReview(rows, new Date()) }, null, 2))+} catch { console.error('Could not read aggregate product usage. Check the read-only connection and schema.'); process.exitCode = 1 }+finally { await db.$disconnect() }diff --git a/backend/src/routes/analytics.ts b/backend/src/routes/analytics.tsindex c5f2cbe4e..5f196d110 100644--- a/backend/src/routes/analytics.ts+++ b/backend/src/routes/analytics.ts@@ -19,8 +19,8 @@ import { machineIdFromKey } from '../utils/crypto.js'import { validateBody, validateQuery } from '../middlewares/validation.js'import { sendSuccess, sendError } from '../utils/response.js'import { logger } from '../utils/logger.js'-import { AnalyticsEpochError, ingestReport } from '../lib/analyticsIngest.js'import { analyticsOverview, buildConsentView } from '../lib/analyticsQuery.js'+import { deleteLegacyProductUsage, setProductUsageChoice } from '../lib/productUsage.js'import {ANALYTICS_SCHEMA_VERSION,CONSENT_STATES,@@ -146,27 +146,10 @@ export async function analyticsRoutes(app: FastifyInstance): Promise<void> {'/api/analytics/report',{ bodyLimit: REPORT_BODY_LIMIT, preHandler: [machineAuth, validateBody(reportSchema)] },async (req, reply) => {- const ctx = (req as WithMachine).machineCtx!- try {- const body = req.body as AnalyticsReportRequest- const result = await ingestReport(ctx, {- ...body,- collector: { ...body.collector, enginesPresent: body.collector.enginesPresent ?? [] },- })- return sendSuccess(reply, result)- } catch (err) {- if (err instanceof AnalyticsEpochError) {- // 409 is the collector's signal to drop its local queue: this history was deleted.- return sendError(- reply,- `Analytics history was reset; current epoch is ${err.currentEpoch}`,- 'ANALYTICS_EPOCH_STALE',- 409,- )- }- logger.error('POST /api/analytics/report failed', err, { machineId: ctx.machineId })- return sendError(reply, 'Could not store analytics report', 'ANALYTICS_INGEST_FAILED', 500)- }+ const body = req.body as AnalyticsReportRequest+ // The old collector stored machine/account histories. Tell old clients to stop uploading;+ // the replacement is /api/product-usage/report with aggregate-only storage.+ return sendSuccess(reply, { consent: 'off', epoch: body.epoch, serverTime: new Date().toISOString(), accepted: 0, quarantined: 0 })},)@@ -215,6 +198,8 @@ export async function analyticsRoutes(app: FastifyInstance): Promise<void> {if (machineId && !(await ownedMachineIds(userId)).includes(machineId)) {return sendError(reply, 'Unknown machine', 'NO_MACHINE', 404)}+ // Preserve old switches as valid controls. A per-machine off is conservatively account-wide.+ if (consent === 'off' || !machineId) await setProductUsageChoice(userId, consent === 'on')for (const target of targets) {await prisma.analyticsMachineState.upsert({where: { machineId: target },@@ -236,6 +221,7 @@ export async function analyticsRoutes(app: FastifyInstance): Promise<void> {app.post('/api/analytics/delete', async (req, reply) => {const userId = req.user?.subif (!userId) return sendError(reply, 'Unauthorized', 'UNAUTHORIZED', 401)+ await deleteLegacyProductUsage(userId)const [buckets, machineDays] = await Promise.all([prisma.analyticsDailyBucket.deleteMany({ where: { userId } }),prisma.analyticsDailyMachine.deleteMany({ where: { userId } }),diff --git a/backend/src/routes/index.ts b/backend/src/routes/index.tsindex 2eaa3514c..f933ed11d 100644--- a/backend/src/routes/index.ts+++ b/backend/src/routes/index.ts@@ -8,6 +8,7 @@ export * from './devices.js'export * from './mobile.js'export * from './apps.js'export * from './analytics.js'+export * from './productUsage.js'export * from './agentRoute.js'export * from './jevRoute.js'export * from './store.js'diff --git a/backend/src/routes/productUsage.test.ts b/backend/src/routes/productUsage.test.tsnew file mode 100644index 000000000..d7f6b59c3--- /dev/null+++ b/backend/src/routes/productUsage.test.ts@@ -0,0 +1,80 @@+import Fastify, { type FastifyRequest } from 'fastify'+import { afterEach, beforeEach, expect, it, vi } from 'vitest'+const methods = vi.hoisted(() => ({ ingestProductUsage: vi.fn(), productUsageChoice: vi.fn(), setProductUsageChoice: vi.fn() }))+vi.mock('../lib/productUsage.js', () => methods)+import { productUsageRoutes } from './productUsage.js'+import { PRODUCT_USAGE_METRICS, PRODUCT_USAGE_MAX_COUNT } from '../types/productUsage.js'+let app: ReturnType<typeof Fastify>+beforeEach(async () => {+ vi.resetAllMocks()+ app = Fastify({ logger: false })+ app.addHook('onRequest', async (req: FastifyRequest) => { if (req.headers.authorization === 'fixture') req.user = { sub: 'account' } as typeof req.user })+ await app.register(productUsageRoutes)+ methods.productUsageChoice.mockResolvedValue({ enabled: true, revision: 0 })+ methods.ingestProductUsage.mockResolvedValue({ accepted: true })+})+afterEach(() => app.close())+const good = { schemaVersion: 1, revision: 0, id: 'cf1c5a03-388c-4265-b5fb-a4c3d47e407f', day: '2026-10-13', counters: { turns_started: 1 } }+const submit = (payload: unknown) => app.inject({ method: 'POST', url: '/api/product-usage/report', headers: { authorization: 'fixture' }, payload: payload as Record<string, unknown> })+it('requires a signed-in account and does not let the report choose its identity', async () => {+ expect((await app.inject({ method: 'POST', url: '/api/product-usage/report', payload: good })).statusCode).toBe(401)+ expect((await submit(good)).statusCode).toBe(200)+ expect(methods.ingestProductUsage).toHaveBeenCalledWith('account', good)+})+it.each([+ { ...good, prompt: 'PRIVATE_CANARY' }, { ...good, userId: 'PRIVATE_CANARY' },+ { ...good, counters: { 'PRIVATE_CANARY': 1 } }, { ...good, counters: { turns_started: 'PRIVATE_CANARY' } },+ { ...good, counters: { turns_started: -1 } }, { ...good, counters: { turns_started: 100001 } },+ { ...good, counters: { turns_started: 1.5 } }, { ...good, id: 'PRIVATE_CANARY' },+])('refuses unknown fields and malformed values without echoing them', async payload => {+ const response = await submit(payload)+ expect(response.statusCode).toBe(400)+ expect(response.body).not.toContain('PRIVATE_CANARY')+ expect(methods.ingestProductUsage).not.toHaveBeenCalled()+})+it('does not reflect a database error or report contents', async () => {+ methods.ingestProductUsage.mockRejectedValue(new Error('PRIVATE_CANARY'))+ const response = await submit(good)+ expect(response.statusCode).toBe(503)+ expect(response.body).not.toContain('PRIVATE_CANARY')+})+it('also sanitizes malformed JSON and oversized bodies before schema validation', async () => {+ for (const payload of ['{"prompt":"PRIVATE_CANARY', JSON.stringify({ prompt: 'PRIVATE_CANARY'.repeat(1000) })]) {+ const response = await app.inject({ method: 'POST', url: '/api/product-usage/report', headers: {+ authorization: 'fixture', 'content-type': 'application/json',+ }, payload })+ expect([400, 413]).toContain(response.statusCode)+ expect(response.body).not.toContain('PRIVATE_CANARY')+ expect(methods.ingestProductUsage).not.toHaveBeenCalled()+ }+})+it('does not expose preference lookup failures', async () => {+ methods.productUsageChoice.mockRejectedValue(new Error('PRIVATE_CANARY'))+ const response = await app.inject({ method: 'GET', url: '/api/product-usage/settings', headers: { authorization: 'fixture' } })+ expect(response.statusCode).toBe(503)+ expect(response.body).not.toContain('PRIVATE_CANARY')+})+it('the visible control changes only the authenticated account', async () => {+ const request = { method: 'POST' as const, url: '/api/product-usage/settings', headers: { authorization: 'fixture' }, payload: { enabled: false } }+ expect((await app.inject(request)).statusCode).toBe(200)+ expect(methods.setProductUsageChoice).toHaveBeenCalledWith('account', false)+ expect((await app.inject({ ...request, payload: { enabled: true, userId: 'another' } })).statusCode).toBe(400)+})++it('the full fixed vocabulary fits the bounded report body', async () => {+ const payload = { ...good, counters: Object.fromEntries(PRODUCT_USAGE_METRICS.map(k => [k, PRODUCT_USAGE_MAX_COUNT])) }+ expect(Buffer.byteLength(JSON.stringify(payload))).toBeLessThan(8192)+ expect((await submit(payload)).statusCode).toBe(200)+})++it('feedback reduces a voluntary fixed choice to one unlinked, retry-safe count', async () => {+ const request = { method: 'POST' as const, url: '/api/product-usage/feedback', headers: { authorization: 'fixture' }, payload: { id: good.id, answer: 'useful' } }+ expect((await app.inject(request)).statusCode).toBe(200)+ expect(methods.ingestProductUsage).toHaveBeenCalledWith('account', expect.objectContaining({ id: good.id, revision: 0, counters: { feedback_useful: 1 } }))+ methods.ingestProductUsage.mockClear()+ const bad = await app.inject({ ...request, payload: { ...request.payload, task: 'PRIVATE_CANARY' } })+ expect(bad.statusCode).toBe(400); expect(bad.body).not.toContain('PRIVATE_CANARY')+ methods.productUsageChoice.mockResolvedValue({ enabled: false, revision: 1 })+ expect((await app.inject(request)).statusCode).toBe(409)+ expect(methods.ingestProductUsage).not.toHaveBeenCalled()+})diff --git a/backend/src/routes/productUsage.ts b/backend/src/routes/productUsage.tsnew file mode 100644index 000000000..ccd74778a--- /dev/null+++ b/backend/src/routes/productUsage.ts@@ -0,0 +1,51 @@+import type { FastifyInstance } from 'fastify'+import { z } from 'zod'+import { ingestProductUsage, productUsageChoice, setProductUsageChoice } from '../lib/productUsage.js'+import { PRODUCT_FEEDBACK, PRODUCT_USAGE_MAX_COUNT, PRODUCT_USAGE_METRICS } from '../types/productUsage.js'+import { sendError, sendSuccess } from '../utils/response.js'++export const productUsageReportSchema = z.strictObject({+ schemaVersion: z.literal(1), revision: z.number().int().nonnegative(), id: z.uuid(),+ day: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),+ counters: z.partialRecord(z.enum(PRODUCT_USAGE_METRICS), z.number().int().min(0).max(PRODUCT_USAGE_MAX_COUNT)),+})+const feedbackSchema = z.strictObject({ id: z.uuid(), answer: z.enum(PRODUCT_FEEDBACK) })+const choiceSchema = z.strictObject({ enabled: z.boolean() })++export async function productUsageRoutes(app: FastifyInstance): Promise<void> {+ // Parser errors can contain a piece of malformed JSON. Keep this plugin's errors out of the+ // generic logger/response handler, including failures before the route's schema check runs.+ app.setErrorHandler((error, _req, reply) => {+ const code = (error as { statusCode?: number } | null)?.statusCode+ const status = code && code >= 400 && code < 500 ? code : 503+ return sendError(reply, 'Product usage request unavailable', 'USAGE_UNAVAILABLE', status)+ })+ app.get('/api/product-usage/settings', async (req, reply) => {+ if (!req.user?.sub) return sendError(reply, 'Unauthorized', 'UNAUTHORIZED', 401)+ return sendSuccess(reply, await productUsageChoice(req.user.sub))+ })+ app.post('/api/product-usage/settings', { bodyLimit: 128 }, async (req, reply) => {+ if (!req.user?.sub) return sendError(reply, 'Unauthorized', 'UNAUTHORIZED', 401)+ const parsed = choiceSchema.safeParse(req.body)+ if (!parsed.success) return sendError(reply, 'Invalid usage preference', 'INVALID_USAGE_PREFERENCE', 400)+ return sendSuccess(reply, await setProductUsageChoice(req.user.sub, parsed.data.enabled))+ })+ app.post('/api/product-usage/feedback', { bodyLimit: 256 }, async (req, reply) => {+ if (!req.user?.sub) return sendError(reply, 'Unauthorized', 'UNAUTHORIZED', 401)+ const parsed = feedbackSchema.safeParse(req.body)+ if (!parsed.success) return sendError(reply, 'Invalid feedback', 'INVALID_FEEDBACK', 400)+ const choice = await productUsageChoice(req.user.sub)+ if (!choice.enabled) return sendError(reply, 'Product usage sharing is off', 'SHARING_DISABLED', 409)+ const result = await ingestProductUsage(req.user.sub, { schemaVersion: 1, revision: choice.revision,+ id: parsed.data.id, day: new Date().toISOString().slice(0, 10), counters: { [`feedback_${parsed.data.answer}`]: 1 } })+ return sendSuccess(reply, result)+ })+ app.post('/api/product-usage/report', { bodyLimit: 8192 }, async (req, reply) => {+ if (!req.user?.sub) return sendError(reply, 'Unauthorized', 'UNAUTHORIZED', 401)+ const parsed = productUsageReportSchema.safeParse(req.body)+ // Never reflect rejected fields, values or raw validation errors into logs or responses.+ if (!parsed.success) return sendError(reply, 'Invalid usage report', 'INVALID_USAGE_REPORT', 400)+ try { return sendSuccess(reply, await ingestProductUsage(req.user.sub, parsed.data)) }+ catch { return sendError(reply, 'Usage report unavailable', 'USAGE_UNAVAILABLE', 503) }+ })+}diff --git a/backend/src/server.ts b/backend/src/server.tsindex 1eb3ebf6c..d25305632 100644--- a/backend/src/server.ts+++ b/backend/src/server.ts@@ -25,7 +25,7 @@ import { experimentalSettingsRoutes } from './routes/experimentalSettings.js'import { describeDaemonsSwitch } from './lib/daemonsSwitch.js'import { handleObserverUpgrade } from './lib/observerWs.js'import { deviceAuthRoutes } from './routes/deviceAuth.js'-import { healthRoutes, authRoutes, userRoutes, machineRoutes, planRoutes, gridRoutes, deviceRoutes, mobileRoutes, appRoutes, analyticsRoutes, agentRouteRoutes, jevRouteRoutes, storeRoutes } from './routes/index.js'+import { healthRoutes, authRoutes, userRoutes, machineRoutes, planRoutes, gridRoutes, deviceRoutes, mobileRoutes, appRoutes, analyticsRoutes, productUsageRoutes, agentRouteRoutes, jevRouteRoutes, storeRoutes } from './routes/index.js'import { startSubdomainProxy, startMeshProxy } from './lib/subdomainProxy.js'import { handleDeviceUpgrade } from './lib/deviceWs.js'import { handleWebUpgrade } from './lib/webWs.js'@@ -168,6 +168,7 @@ async function start(): Promise<void> {await app.register(mobileRoutes)await app.register(appRoutes)await app.register(analyticsRoutes)+ await app.register(productUsageRoutes)await app.register(agentRouteRoutes) // which agent a task belongs to — the prompt lives here, not in the CLIawait app.register(jevRouteRoutes, { count: redisCount }) // ⌘B's Jev decisions on Harness's key, for people with none of their ownawait app.register(cursorRoutes) // standalone STT + LLM for the Cursor desktop app (self-contained)diff --git a/backend/src/types/productUsage.ts b/backend/src/types/productUsage.tsnew file mode 100644index 000000000..5b86f7317--- /dev/null+++ b/backend/src/types/productUsage.ts@@ -0,0 +1,35 @@+/** Fixed vocabulary only. Keep the CLI copy identical; conformance is tested. */+export const PRODUCT_USAGE_VERSION = 1+export const PRODUCT_USAGE_DAYS = 35+export const PRODUCT_USAGE_MAX_COUNT = 100_000+export const PRODUCT_FEEDBACK = ['useful', 'could_not_finish', 'slow', 'confusing', 'missing_feature'] as const+export const PRODUCT_USAGE_ACTIONS = ['create', 'resume', 'restart', 'model_change', 'history'] as const+export const PRODUCT_USAGE_ACTION_MEASURES = ['requests', 'ok', 'failed', 'pending', 'unknown',+ 'error_setup', 'error_auth', 'error_unavailable', 'error_invalid', 'error_other',+ 'under_1s', '1s_to_10s', '10s_to_1m', 'over_1m'] as const+export const PRODUCT_USAGE_METRICS = [+ 'active_installation_days', 'working_installation_days', 'first_work_installations',+ 'repeat_work_installation_days', 'weekly_working_installations', 'weekly_returning_installations',+ 'turns_started', 'turns_ended', 'turns_interrupted',+ 'duration_under_10s', 'duration_10s_to_1m', 'duration_1m_to_5m', 'duration_over_5m',+ 'desktop_opens', 'tui_opens',+ 'launch_started', 'launch_created', 'launch_failed', 'launch_cancelled', 'launch_unconfirmed', 'launch_unobserved',+ 'launch_wait_install', 'launch_wait_model', 'launch_wait_native', 'launch_wait_other',+ 'launch_failed_setup', 'launch_failed_auth', 'launch_failed_unavailable', 'launch_failed_invalid', 'launch_failed_other',+ 'launch_under_10s', 'launch_10s_to_1m', 'launch_1m_to_5m', 'launch_over_5m',+ 'turns_with_response', 'turns_with_error', 'turns_ended_without_response', 'turns_waiting_over_1m',+ 'response_under_10s', 'response_10s_to_1m', 'response_1m_to_5m', 'response_over_5m',+ 'first_launch_installations', 'first_launch_work_24h_installations', 'first_launch_response_24h_installations',+ 'first_response_installations', 'd1_returning_work_installations', 'd7_returning_work_installations',+ ...PRODUCT_FEEDBACK.map(answer => `feedback_${answer}` as const),+ ...PRODUCT_USAGE_ACTIONS.flatMap(action => PRODUCT_USAGE_ACTION_MEASURES.map(measure => `${action}_${measure}` as const)),+] as const+export type ProductUsageMetric = typeof PRODUCT_USAGE_METRICS[number]+export interface ProductUsageReport {+ schemaVersion: 1+ revision: number+ id: string+ day: string+ counters: Partial<Record<ProductUsageMetric, number>>+}+export interface ProductUsageChoice { enabled: boolean; revision: number }diff --git a/backend/src/usageReport.ts b/backend/src/usageReport.tsnew file mode 100644index 000000000..d8967ee77--- /dev/null+++ b/backend/src/usageReport.ts@@ -0,0 +1,46 @@+import { PrismaClient } from '@prisma/client'+import { writeFile } from 'node:fs/promises'+import { parseArgs } from 'node:util'+import { productUsageReport, validateOptions } from './analytics/productUsage.js'+import { readProductUsage } from './analytics/readProductUsage.js'++async function main() {+ const { values } = parseArgs({ options: {+ days: { type: 'string', default: '30' }, 'as-of': { type: 'string' },+ 'exclude-email-domain': { type: 'string', multiple: true }, out: { type: 'string' }, help: { type: 'boolean' },+ } })+ if (values.help) {+ console.log('READ_ONLY_DATABASE_URL=<secret> npm run usage:report -- [--days 30] [--as-of YYYY-MM-DD] [--exclude-email-domain example.com] [--out report.json]\nThe cutoff is exclusive (UTC). Output contains aggregates only. Existing output files are not overwritten.')+ return+ }+ const today = new Date().toISOString().slice(0, 10)+ const opts = { days: Number(values.days), asOf: values['as-of'] ?? today, excludeEmailDomains: values['exclude-email-domain'] }+ validateOptions(opts)+ if (opts.asOf > today) throw new Error('as-of cannot be later than today; only complete UTC days are reported')+ const rawUrl = process.env.READ_ONLY_DATABASE_URL+ if (!rawUrl) throw new Error('Set READ_ONLY_DATABASE_URL to a read-only MongoDB connection; credentials are never accepted as command arguments')+ // Do not load .env or the server's default DATABASE_URL, which may carry write credentials.+ let url: URL+ try { url = new URL(rawUrl) } catch { throw new Error('READ_ONLY_DATABASE_URL is not a valid MongoDB URL') }+ if (!['mongodb:', 'mongodb+srv:'].includes(url.protocol)) throw new Error('A MongoDB URL is required')+ url.searchParams.set('connectTimeoutMS', '10000')+ url.searchParams.set('serverSelectionTimeoutMS', '10000')+ const db = new PrismaClient({ datasources: { db: { url: url.toString() } } })+ try {+ const data = await readProductUsage(db, opts)+ const report = { generatedAt: new Date().toISOString(), ...productUsageReport(data, opts) }+ const json = JSON.stringify(report, null, 2) + '\n'+ if (values.out) await writeFile(values.out, json, { mode: 0o600, flag: 'wx' })+ else process.stdout.write(json)+ } finally { await db.$disconnect() }+}++main().catch(error => {+ // Driver diagnostics can contain the URI. Only our validation messages and a driver code are safe.+ const known = error instanceof Error && (error.message.startsWith('asOf ') || error.message.startsWith('as-of ') ||+ error.message.startsWith('days ') || error.message.startsWith('Set READ_ONLY_') ||+ error.message.startsWith('READ_ONLY_DATABASE_URL ') || error.message === 'A MongoDB URL is required' ||+ error.message.startsWith('Usage query exceeded ') || error.message === 'Unexpected database aggregation response')+ console.error(known ? error.message : `Usage report failed (${String(error?.code ?? error?.name ?? 'unknown error').replace(/[^A-Za-z0-9_]/g, '')}); no report was produced.`)+ process.exitCode = 1+})diff --git a/backend/src/worker.ts b/backend/src/worker.tsindex b3fd84925..717cce9c1 100644--- a/backend/src/worker.ts+++ b/backend/src/worker.ts@@ -13,6 +13,7 @@ import {} from './lib/db/migrate.js'import { ensurePlans } from './lib/db/seed.js'import { prisma } from './lib/prisma.js'+import { ensureProductUsageExpiry } from './lib/productUsage.js'import { machineBillingWorkerService } from './services/MachineBillingWorkerService.js'import { logger } from './utils/logger.js'@@ -26,6 +27,7 @@ async function start(): Promise<void> {// Same reason: the old (user, day) unique must be gone before the push installs its replacement.await migrateUserPresencePerMachine()ensureSchema()+ await ensureProductUsageExpiry()// AFTER the push: it creates the new collections + their unique indexes, and the copy uses $merge// so those indexes survive. Copying first would leave the unique index build to fail silently.await migrateMachineRename()diff --git a/cli/e2e/harness/fakeBackend.ts b/cli/e2e/harness/fakeBackend.tsindex 8bd5b2b4f..3bd1c107d 100644--- a/cli/e2e/harness/fakeBackend.ts+++ b/cli/e2e/harness/fakeBackend.ts@@ -83,6 +83,8 @@ const json = (value: unknown): string => JSON.stringify(value)const bytes = (raw: RawData): Uint8Array => new Uint8Array(Array.isArray(raw) ? Buffer.concat(raw) : raw instanceof ArrayBuffer ? raw : Buffer.from(raw))export class FakeBackend {+ /** Opt-in fixture: older scenarios keep the endpoint absent, as on an older backend. */+ productUsage: { enabled: boolean; revision: number; reports: Record<string, unknown>[] } | null = nullreadonly seen: string[] = []/** What `GET /api/agent-messages` answers: the account's tabs and who is in each; null, a 404. */agentMessages: Record<string, unknown> | null = null@@ -131,6 +133,27 @@ export class FakeBackend {res.setHeader('content-type', 'application/json')if (backend.down) { res.statusCode = 503; res.end(json({ success: false, error: { code: 'UNAVAILABLE' } })); return }if (!machine) { res.statusCode = 401; res.end(json({ success: false, error: { code: 'UNAUTHORIZED' } })); return }+ const usage = backend.productUsage+ if (usage && req.url === '/api/product-usage/settings' && req.method === 'GET') {+ res.end(json({ success: true, data: { enabled: usage.enabled, revision: usage.revision } })); return+ }+ if (usage && req.method === 'POST' && ['/api/product-usage/settings', '/api/product-usage/report'].includes(req.url ?? '')) {+ let body = ''+ req.on('data', chunk => { body += String(chunk) })+ req.on('end', () => {+ const parsed = JSON.parse(body) as Record<string, unknown>+ if (req.url === '/api/product-usage/settings') {+ usage.enabled = parsed.enabled === true; usage.revision+++ res.end(json({ success: true, data: { enabled: usage.enabled, revision: usage.revision } }))+ } else if (!usage.enabled || parsed.revision !== usage.revision) {+ res.end(json({ success: true, data: { accepted: false, reason: 'CHOICE_CHANGED' } }))+ } else {+ usage.reports.push(parsed)+ res.end(json({ success: true, data: { accepted: true } }))+ }+ })+ return+ }if (req.method === 'GET' && req.url?.split('?')[0] === '/api/machines') {res.end(json({ success: true, data: { machines: backend.rows() } }))returndiff --git a/cli/e2e/privacyCommand.e2e.ts b/cli/e2e/privacyCommand.e2e.tsnew file mode 100644index 000000000..637224d7d--- /dev/null+++ b/cli/e2e/privacyCommand.e2e.ts@@ -0,0 +1,23 @@+import { execFile } from 'node:child_process'+import { writeFileSync } from 'node:fs'+import { join } from 'node:path'+import { promisify } from 'node:util'+import { expect, it } from 'vitest'+import { CLI_ROOT, IsolatedDaemon } from './harness/daemon.js'+import { FakeBackend } from './harness/fakeBackend.js'+const exec = promisify(execFile)+it('the terminal command reads and changes the account preference without starting a daemon', async () => {+ const backend = await FakeBackend.start()+ backend.productUsage = {enabled:true,revision:0,reports:[]}+ const d = await IsolatedDaemon.create({env:{BACKEND_WS_URL:backend.wsUrl,WEB_URL:backend.httpUrl}})+ try {+ backend.addMachine({machineId:'c3'.repeat(16),computerId:d.computerId,name:'fixture',token:'fixture-privacy-token'})+ writeFileSync(join(d.root,'auth','session.json'),JSON.stringify({version:1,accessToken:'fixture-privacy-token',autonomousEnv:'prod',computerId:d.computerId,machineId:'c3'.repeat(16),expiresAt:Date.now()+86400000,updatedAt:Date.now(),signInEpoch:'fixture'}),{mode:0o600})+ for (const [action, enabled] of [['status',true],['off',false],['on',true]] as const) {+ const result=await exec(process.execPath,['--import','tsx',join(CLI_ROOT,'src/cli.ts'),'privacy',action,'--json'],{cwd:CLI_ROOT,env:d.env,timeout:30000})+ expect(JSON.parse(result.stdout)).toMatchObject({enabled})+ expect(result.stdout+result.stderr).not.toContain('fixture-privacy-token')+ }+ expect(d.child).toBeNull()+ } finally { await d.close(); await backend.close() }+},100000)diff --git a/cli/e2e/productUsage.e2e.ts b/cli/e2e/productUsage.e2e.tsnew file mode 100644index 000000000..898423ff6--- /dev/null+++ b/cli/e2e/productUsage.e2e.ts@@ -0,0 +1,65 @@+import { mkdirSync, writeFileSync } from 'node:fs'+import { join } from 'node:path'+import { afterEach, expect, it, onTestFailed } from 'vitest'+import { LocalClient } from './harness/client.js'+import { IsolatedDaemon, until } from './harness/daemon.js'+import { FakeBackend } from './harness/fakeBackend.js'++let daemon: IsolatedDaemon | undefined, backend: FakeBackend | undefined, client: LocalClient | undefined+afterEach(async () => { client?.close(); await daemon?.close(); await backend?.close() })++it('reports only local counters from a real turn, and the account switch stops them while work continues', async () => {+ backend = await FakeBackend.start()+ backend.productUsage = { enabled: true, revision: 0, reports: [] }+ const machine = { machineId: 'c3'.repeat(16), computerId: 'e2e-product-usage', name: 'fixture', token: 'e2e-product-token' }+ backend.addMachine(machine)+ const d = await IsolatedDaemon.create({ env: { BACKEND_WS_URL: backend.wsUrl, WEB_URL: backend.httpUrl, ADAPTER_COMPUTER_ID: machine.computerId } })+ daemon = d+ writeFileSync(join(d.root, 'auth', 'session.json'), JSON.stringify({ version: 1, accessToken: machine.token,+ autonomousEnv: 'prod', computerId: machine.computerId, machineId: machine.machineId,+ expiresAt: Date.now() + 86400000, updatedAt: Date.now(), signInEpoch: 'e2e' }), { mode: 0o600 })+ onTestFailed(() => console.log(d.log().split('\n').slice(-70).join('\n')))+ await d.start()+ await until('sharing preference read', () => backend!.seen.includes('GET /api/product-usage/settings') || null, 45000)+ const settings = `http://127.0.0.1:${d.port}/api/product-usage/settings`+ expect((await (await fetch(settings)).json())).toMatchObject({ data: { enabled: true } })+ client = await LocalClient.connect(d, { machineId: machine.machineId })+ const cwd = join(d.projectsDir, 'PRIVATE_PROJECT_CANARY'); mkdirSync(cwd, { recursive: true })+ const creationId = 'private-creation-canary'+ const launched = await client.request('agent_create', { creationId, engine: 'claude', cwd, bypassPermission: true }, 90000)+ expect(launched.error).toBeUndefined()+ const created = launched.state === 'created' ? launched : await until('durable launch completes', async () => {+ const reply = await client!.request('agent_create_status', { creationId })+ return reply.state === 'created' ? reply : null+ }, 90000)+ // Retrying the durable request or polling it must not create another launch measurement.+ await client.request('agent_create_status', { creationId })+ const refused = await client.request('agent_create', { creationId: 'synthetic-invalid-creation', engine: 'not-an-engine', cwd })+ expect(refused.error ?? refused.failure).toBeTruthy()+ const agentId = created.agent.id+ const turn = async () => {+ const ended = client!.next(frame => frame.type === 'turn_ended' && frame.agentId === agentId, 45000)+ client!.send('message', { agentId, content: 'PRIVATE_PROMPT_CANARY: say hello' })+ await ended+ }+ await until('agent ready', async () => {+ const rows = await client!.request('agents_list', { includeStopped: true })+ return rows.agents.some((a: Record<string, unknown>) => a.id === agentId && a.sessionId) || null+ }, 45000)+ await turn()+ await until('a reduced completed turn report', () => backend!.productUsage!.reports.some(r => ((r.counters as Record<string, number>).turns_ended ?? 0) > 0) || null, 75000)+ const sum = (metric: string) => backend!.productUsage!.reports.reduce((n, r) => n + ((r.counters as Record<string, number>)[metric] ?? 0), 0)+ expect(sum('launch_started')).toBe(2)+ expect(sum('launch_created')).toBe(1)+ expect(sum('launch_failed')).toBe(1)+ expect(sum('turns_with_response')).toBeGreaterThan(0)+ const wire = JSON.stringify(backend.productUsage.reports)+ for (const privateValue of ['PRIVATE_', creationId, machine.machineId, machine.computerId, machine.token, agentId, cwd, 'userMessage', 'payload']) expect(wire).not.toContain(privateValue)+ expect((await fetch(settings, { method: 'POST', headers: { 'content-type': 'application/json', 'x-adapter-local': '1' }, body: '{"enabled":false}' })).status).toBe(200)+ const reportsBefore = backend.productUsage.reports.length+ const checksBefore = backend.seen.filter(x => x === 'GET /api/product-usage/settings').length+ await turn()+ await until('collector observes the off choice', () => backend!.seen.filter(x => x === 'GET /api/product-usage/settings').length > checksBefore || null, 75000)+ expect(backend.productUsage.reports).toHaveLength(reportsBefore)+ expect(d.coresStarted()).toBe(1)+}, 240000)diff --git a/cli/src/backendSocket.ts b/cli/src/backendSocket.tsindex c35fa8843..c09bcac29 100644--- a/cli/src/backendSocket.ts+++ b/cli/src/backendSocket.ts@@ -1,3 +1,4 @@+import { productUsageLaunch, productUsageRequest } from './lib/productUsageSignals.js'import { isLocalOnly, withoutUpdate } from './lib/cardUpdate.js'import type { PurgeAgentService } from './lib/purgeAgentService.js'import { MESSAGES_REQUESTS, SHARE_REQUESTS, type Asker, type LocalWindows, type WindowSurface, type BackendNotice, type GatewayEvents, type GatewayPort, type ModelsPort, type RemoteClient, type RemoteRole, type RemoteTransport } from './core/api.js'@@ -818,7 +819,16 @@ export class BackendSocket {if (env.LOG_FRAMES && !MESSAGE_REQUESTS.has(type) && !ROUTE_COMMAND_TYPES.has(type) && !type.startsWith('terminal_') && !type.startsWith('viewer_') && !type.startsWith('grid_fleet_') && type !== 'agent_read_file' && type !== 'project_preview' && type !== 'git_project_info' && type !== 'scm_project_info' && type !== 'git_pull_request' && type !== 'agent_handoff_prepare' && type !== 'orchestrator' && type !== 'api_connections' && type !== 'connectors' && type !== 'browser_open' && type !== 'browser_callback' && type !== 'phone_pair' && !SHARE_REQUEST_TYPES.has(type) && !type.startsWith('pair')) {logFrame('←', connId ? `conn:${sid(connId)}` : 'backend', frame)}- const reply = (t: string, rid: unknown, p: Record<string, unknown>): void => this.emitReply(connId, t, rid, p)+ const launchMeasured = productUsageLaunch(type, (frame.payload as { creationId?: unknown } | undefined)?.creationId,+ signal => this.toGateway('usage', gateway => gateway.usageLaunch?.(signal)))+ const measured = productUsageRequest(type, (metric) => this.toGateway('usage', (gateway) => gateway.usageCounter?.(metric)))+ const reply = (t: string, rid: unknown, p: Record<string, unknown>): void => {+ if (t === type) {+ measured(p.error ?? (p.failure as { code?: unknown } | undefined)?.code, p.state, !!p.agent)+ launchMeasured(p.error ?? (p.failure as { code?: unknown } | undefined)?.code, p.state, !!p.agent, (p.held as { service?: unknown } | undefined)?.service)+ }+ this.emitReply(connId, t, rid, p)+ }// Who may act as this machine's owner: a process here, or the owner's own paired app or browser, whose// session the gateway says is a `web` one. A device or an observer may not.const owner = local || role === 'web'diff --git a/cli/src/cli.ts b/cli/src/cli.tsindex 14f28259f..613932d31 100644--- a/cli/src/cli.ts+++ b/cli/src/cli.ts@@ -90,6 +90,7 @@ import { ensureManagedGrid, ensureManagedRuntime } from './lib/runtimeInstall.js// which silently costs the daemon every pane it would have discovered. See lib/childLocale.ts.ensureUtf8Locale()import { prepareLogFile } from './lib/log.js'+import { privacyCommand } from './lib/privacyCommand.js'// Daemon stdout/stderr. Capped at LOG_MAX_BYTES — see prepareLogFile/trimLogFile in lib/log.ts.@@ -116,6 +117,7 @@ Machine:harness login --json emit machine-readable NDJSON instead of opening a browser (for GUI clients)harness login --entry-point=desktop record which surface started the sign-in (GUI clients; default cli)harness auth status --json print {loggedIn,...} for this computer's saved session+ harness privacy status|on|off view or change product usage sharing for this accountharness start start the adapter using the saved SSO sessionharness start -f run the daemon in the FOREGROUND (for a supervisor; logs to stdout): harnessd'smaster, as launchd and systemd run it, its core and services its children@@ -2514,6 +2516,9 @@ if (cmd === 'version' || cmd === '--version' || cmd === '-v') { console.log(VERSswitch (cmd) {+ case 'privacy':+ privacyCommand(args[0], flags.includes('--json')).catch(onError)+ breakcase 'send':sendCommand(rest).then(code => { process.exitCode = code }).catch(onError)breakdiff --git a/cli/src/core/api.ts b/cli/src/core/api.tsindex e89e3a1bb..7996fdf67 100644--- a/cli/src/core/api.ts+++ b/cli/src/core/api.ts@@ -1,3 +1,5 @@+import type { ProductUsageLaunchSignal } from '../lib/productUsageSignals.js'+import type { ProductUsageMetric } from '../lib/productUsageContract.js'import type { PreparedHandoff, HandoffPermit, HandoffOutcome } from '../lib/handoffAuthority.js'import type { AgentTokenUsage, AgentUsageTarget } from '../lib/agentUsageWire.js'import type { CloudHarness } from '../lib/cloudAgents.js'@@ -1173,6 +1175,9 @@ import type { LocalWindows, WindowSurface } from '../lib/windowSurfaces.js'/** What the core asks of the gateway: everything bound for a remote client, and the link's state. */export interface GatewayPort {+ /** Optional, fixed-name counter to the gateway; no user payload or identifier. */+ usageCounter?(metric: ProductUsageMetric): void+ usageLaunch?(signal: ProductUsageLaunchSignal): void/** Dial the backend: this daemon is signed in. */connect(): void/** Never dial: signed out, so nothing is sealed or queued for a link that will not open. */diff --git a/cli/src/core/gatewayLink.spec.ts b/cli/src/core/gatewayLink.spec.tsindex 868e1317a..e3ecf52d1 100644--- a/cli/src/core/gatewayLink.spec.ts+++ b/cli/src/core/gatewayLink.spec.ts@@ -97,12 +97,14 @@ describe('the gateway in its own process, as the core sees it', () => {expect(link.port.device('phone-1', 'autonomous_device_result', { c: 3 })).toBe(true)link.port.deviceClient('phone-1', 'PUB')link.port.windowOpened('tui')+ link.port.usageCounter?.('create_requests')+ link.port.usageLaunch?.({ id: 'creation-fixture-1', phase: 'start' })await link.port.local('local:w', { type: 'e2ee_pairings_list', payload: {} })expect(link.port.terminalBinary('phone-1', bytesOf('hi'))).toBe(true)// An id the binary frame cannot carry: refused, never sent half-framed.register(link, 'x'.repeat(300))expect(link.port.terminalBinary('x'.repeat(300), bytesOf('hi'))).toBe(false)- expect(kinds().slice(1)).toEqual(['broadcast', 'commander', 'user', 'reply', 'target', 'terminal', 'observer', 'device', 'deviceClient', 'windowOpened', 'localFrame'])+ expect(kinds().slice(1)).toEqual(['broadcast', 'commander', 'user', 'reply', 'target', 'terminal', 'observer', 'device', 'deviceClient', 'windowOpened', 'usageCounter', 'usageLaunch', 'localFrame'])expect(sent[4]).toEqual({ kind: 'reply', connId: 'phone-1', type: 'agents_list', requestId: 'r-1', payload: { agents: [] } })const framed = decodeGatewayBinary(binary[0])!expect(framed).toMatchObject({ kind: GatewayBinary.remote, id: 'phone-1' })diff --git a/cli/src/core/gatewayLink.ts b/cli/src/core/gatewayLink.tsindex d46d9657f..ad6edac1a 100644--- a/cli/src/core/gatewayLink.ts+++ b/cli/src/core/gatewayLink.ts@@ -174,6 +174,8 @@ export function createGatewayLink(deps: GatewayLinkDeps) {}const port: GatewayPort = {+ usageLaunch: (signal) => { send('usageLaunch', { signal }) },+ usageCounter: (metric) => { send('usageCounter', { metric }) },connect: () => { dial = 'connect'; need(); send('connect') },serveThisComputerOnly: () => { dial = 'local'; send('thisComputerOnly') },holdRequests: () => { requestsOpen = false; send('hold') },diff --git a/cli/src/core/main.ts b/cli/src/core/main.tsindex 70843ddaf..665626322 100644--- a/cli/src/core/main.ts+++ b/cli/src/core/main.ts@@ -1905,6 +1905,9 @@ async function runForeground(session: AuthSession | null): Promise<void> {onExperimentalWrite: (body) => agentSettings.experimentalWrite(body),onAgentSettingsRead: () => agentSettings.settingsRead(),onAgentSettingsWrite: (body) => agentSettings.settingsWrite(body),+ onProductFeedback: (body) => proxyBackend('POST', '/api/product-usage/feedback', body),+ onProductUsageRead: () => proxyBackend('GET', '/api/product-usage/settings'),+ onProductUsageWrite: (body) => proxyBackend('POST', '/api/product-usage/settings', body),onStore: (method, path, body) => proxyBackend(method, path, body),}, { socketPath: localSocketPath(env.ADAPTER_DATA_DIR, env.PORT), allowPortFallback: true })try { saveDaemonPort(env.ADAPTER_DATA_DIR, env.PORT, hookPort) } catch (error) {diff --git a/cli/src/gateway/accountHttp.spec.ts b/cli/src/gateway/accountHttp.spec.tsindex f95b4f8fb..cc237ff04 100644--- a/cli/src/gateway/accountHttp.spec.ts+++ b/cli/src/gateway/accountHttp.spec.ts@@ -23,6 +23,16 @@ function setup() {}describe('account HTTP in the gateway', () => {+ it('does not send a queued report if sign-in changes while a token is being read', async () => {+ const { api, tokens, request, account } = setup()+ let resolve!: (token: string) => void+ tokens.accessToken.mockImplementationOnce(() => new Promise(done => { resolve = done }))+ const pending = api.backend('POST', '/api/product-usage/report', { counters: { turns_started: 1 } })+ account({ machineId: 'account-b', signIn: null, autonomousEnv: 'test' })+ resolve('other-account-token')+ expect(await pending).toMatchObject({ status: 409, body: { error: { code: 'ACCOUNT_CHANGED' } } })+ expect(request).not.toHaveBeenCalled()+ })it('forwards response bodies, status, credentials and environment without holding a credential', async () => {const { api, request, tokens } = setup()request.mockResolvedValueOnce(response({ error: { code: 'CONFLICT' } }, 409))diff --git a/cli/src/gateway/accountHttp.ts b/cli/src/gateway/accountHttp.tsindex 434c6e8e9..ea7e43d20 100644--- a/cli/src/gateway/accountHttp.ts+++ b/cli/src/gateway/accountHttp.ts@@ -23,12 +23,22 @@ const failure = (status: number, code: string, message: string): HttpAnswer =>export function createAccountHttp(deps: AccountHttpDeps) {const request = deps.request ?? fetch+ const accountFence = () => {+ const account = deps.account()+ return [account.machineId, account.autonomousEnv, account.signIn?.epoch, account.signIn?.acct]+ }async function backend(method: string, path: string, body?: unknown, timeoutMs = PROXY_BACKEND_TIMEOUT_MS): Promise<HttpAnswer> {+ const owner = accountFence()let accessToken: stringtry { accessToken = await deps.tokens.accessToken() } catch (error) {const signedOut = error instanceof AuthSessionError && error.code !== 'UNAVAILABLE'return failure(signedOut ? 401 : 502, signedOut ? 'NOT_SIGNED_IN' : 'AUTH_UNAVAILABLE', error instanceof Error ? error.message : String(error))}+ // Token refresh can overlap sign-out/sign-in. In particular, a queued usage report must not+ // be admitted under a different account's sharing choice after that await.+ if (accountFence().some((value, index) => value !== owner[index])) {+ return failure(409, 'ACCOUNT_CHANGED', 'The account changed. Refresh and try again.')+ }let res: Responsetry {res = await request(`${(deps.base ?? backendHttpBase)()}${path}`, {diff --git a/cli/src/gateway/gateway.spec.ts b/cli/src/gateway/gateway.spec.tsindex 3fb4c3b2d..df68dedbe 100644--- a/cli/src/gateway/gateway.spec.ts+++ b/cli/src/gateway/gateway.spec.ts@@ -23,6 +23,28 @@ const MACHINE = 'a1b2c3d4e5f60718293a4b5c6d7e8f90'afterEach(() => vi.restoreAllMocks())+it('passes only lifecycle scalars to product reporting and keeps relaying if reporting fails', async () => {+ const socket = relaySocket(MACHINE)+ const gateway = gatewayOf(socket)+ const observe = vi.fn()+ gateway.productUsage = { observe, opened: vi.fn(), presence: vi.fn() }+ gateway.broadcast({ type: 'turn_ended', agentId: 'fixture-agent', payload: { aborted: true, content: 'PRIVATE_CANARY' } })+ expect(observe).toHaveBeenCalledWith('turn_ended', 'fixture-agent', false, true)+ gateway.broadcast({ type: 'text_delta', agentId: 'fixture-agent', payload: { text: 'PRIVATE_CANARY' } })+ expect(observe).toHaveBeenCalledWith('text_delta', 'fixture-agent', false, false)+ gateway.broadcast({ type: 'error', agentId: 'fixture-agent', payload: { message: 'PRIVATE_CANARY' } })+ expect(observe).toHaveBeenCalledWith('error', 'fixture-agent', false, false)+ expect(JSON.stringify(observe.mock.calls)).not.toContain('PRIVATE_CANARY')+ const fail = () => { throw new Error('Reporting unavailable') }+ gateway.productUsage = { observe: fail, opened: fail, presence: fail, counter: fail, launch: fail }+ expect(() => gateway.usageCounter('create_requests')).not.toThrow()+ expect(() => gateway.usageLaunch({ id: 'synthetic-creation-1', phase: 'start' })).not.toThrow()+ expect(() => gateway.broadcast({ type: 'turn_started', agentId: 'fixture-agent' })).not.toThrow()+ expect(() => gateway.windowOpened('desktop')).not.toThrow()+ expect(() => gateway.localClients({ desktop: 1, tui: 0 })).not.toThrow()+ await socket.stop()+})+type Frame = Record<string, unknown>/** What the gateway queued for the relay, addressed to one connection. */diff --git a/cli/src/gateway/gateway.ts b/cli/src/gateway/gateway.tsindex bd07e03a8..08636d52e 100644--- a/cli/src/gateway/gateway.ts+++ b/cli/src/gateway/gateway.ts@@ -15,6 +15,8 @@*/import { env } from '../config/env.js'import type { GatewayEvents, GatewayPort, RemoteRole, RemoteTransport } from '../core/api.js'+import type { ProductUsageLaunchSignal } from '../lib/productUsageSignals.js'+import type { ProductUsageMetric } from '../lib/productUsageContract.js'import { WINDOW_SURFACES, type LocalWindows, type WindowSurface } from '../lib/windowSurfaces.js'import { deviceDump } from '../lib/autonomous-device/dump.js'import type { AuthSessionManager } from '../lib/authSession.js'@@ -49,6 +51,14 @@ export interface RelayGatewayOptions {}export class RelayGateway implements GatewayPort {+ /** Optional scalar-only measurement hooks. Never hand a frame or user payload to the collector. */+ productUsage?: {+ launch?(signal: ProductUsageLaunchSignal): void+ counter?(metric: ProductUsageMetric): void+ presence(active: boolean): void+ opened(surface: WindowSurface): void+ observe(type: 'turn_started' | 'turn_ended' | 'text_delta' | 'error', agent: string, replay: boolean, interrupted?: boolean): void+ }/** Web↔adapter E2EE: group-encrypts user events, runs the CPace pairing, holds per-conn sessions. */readonly e2ee: E2eeManagerreadonly machineId: string@@ -209,10 +219,22 @@ export class RelayGateway implements GatewayPort {this.openRequestGate()}- windowOpened(surface: WindowSurface): void { this.link.sendAppPresence('open', surface) }+ usageLaunch(signal: ProductUsageLaunchSignal): void {+ try { this.productUsage?.launch?.(signal) } catch { /* Optional measurement. */ }+ }++ usageCounter(metric: ProductUsageMetric): void {+ try { this.productUsage?.counter?.(metric) } catch { /* Work never waits for reporting. */ }+ }++ windowOpened(surface: WindowSurface): void {+ try { this.productUsage?.opened(surface) } catch { /* Reporting must not affect the relay. */ }+ this.link.sendAppPresence('open', surface)+ }localClients(windows: LocalWindows): void {this.localWindows = windows+ try { this.productUsage?.presence(windows.desktop + windows.tui > 0) } catch { /* Reporting is optional. */ }for (const surface of WINDOW_SURFACES) if (windows[surface] === 0) this.link.noLocalClients(surface)}@@ -220,6 +242,10 @@ export class RelayGateway implements GatewayPort {/** User-content events are group-encrypted (E2EE) here; system frames pass through as plaintext. */broadcast(frame: Frame): void {+ if ((frame.type === 'turn_started' || frame.type === 'turn_ended' || frame.type === 'text_delta' || frame.type === 'error') && typeof frame.agentId === 'string') {+ const interrupted = frame.type === 'turn_ended' && (frame.payload as { aborted?: unknown } | undefined)?.aborted === true+ try { this.productUsage?.observe(frame.type, frame.agentId, frame.replay === true, interrupted) } catch { /* Work continues without metrics. */ }+ }if (this.link.servesThisComputerOnly()) returnthis.link.enqueue({ t: 'up', frame: this.e2ee.wrapUp(frame) })}diff --git a/cli/src/gateway/gatewayProcess.spec.ts b/cli/src/gateway/gatewayProcess.spec.tsindex 1c1900230..715a93dcf 100644--- a/cli/src/gateway/gatewayProcess.spec.ts+++ b/cli/src/gateway/gatewayProcess.spec.ts@@ -18,7 +18,7 @@ const clear: TerminalBinaryClear = { kind: TerminalBinaryKind.input, streamId: Sfunction stubGateway() {const port = {- connect: vi.fn(), serveThisComputerOnly: vi.fn(), holdRequests: vi.fn(), openRequests: vi.fn(), connected: vi.fn(() => true),+ usageLaunch: vi.fn(), usageCounter: vi.fn(), connect: vi.fn(), serveThisComputerOnly: vi.fn(), holdRequests: vi.fn(), openRequests: vi.fn(), connected: vi.fn(() => true),broadcast: vi.fn(), commander: vi.fn(), user: vi.fn(), reply: vi.fn(), target: vi.fn(() => true), terminal: vi.fn(() => true),terminalBinary: vi.fn(() => true), observer: vi.fn(() => true), windowOpened: vi.fn(), localClients: vi.fn(), local: vi.fn(async () => {}),device: vi.fn(() => true), deviceClient: vi.fn(), stop: vi.fn(async () => {}),@@ -119,6 +119,10 @@ describe('the gateway\'s process, spoken to by the core', () => {expect(gateway.ops.reachable).toHaveBeenCalledWith(['m2'])expect(gateway.ops.wifiService).toHaveBeenCalledWith(true)expect(gateway.port.connect).toHaveBeenCalled()+ w.link.port.usageLaunch?.({ id: 'creation-fixture-1', phase: 'start' })+ expect(gateway.port.usageLaunch).toHaveBeenCalledWith({ id: 'creation-fixture-1', phase: 'start' })+ w.link.port.usageCounter?.('create_failed')+ expect(gateway.port.usageCounter).toHaveBeenCalledWith('create_failed')// Its tokens and its reads of the backend are the core's to hand out.expect(await w.hosts[0].tokens.accessToken({ force: true })).toBe('token-a')expect(w.tokens.accessToken).toHaveBeenCalledWith({ force: true })diff --git a/cli/src/gateway/gatewayProcess.ts b/cli/src/gateway/gatewayProcess.tsindex 3b598aea4..ba0171478 100644--- a/cli/src/gateway/gatewayProcess.ts+++ b/cli/src/gateway/gatewayProcess.ts@@ -10,6 +10,8 @@* and the core going away stops it: a core's restart is the relay's, as it always was, so a remote client* that kept its socket opens a new session, as it did when both ran in one process.*/+import type { ProductUsageLaunchSignal } from '../lib/productUsageSignals.js'+import type { ProductUsageMetric } from '../lib/productUsageContract.js'import type { GatewayAccount, GatewayEvents, WindowRelaySession } from '../core/api.js'import { localWindowsOf, windowSurfaceOf } from '../lib/windowSurfaces.js'import { decodeGatewayBinary, encodeGatewayBinary, GatewayBinary, GATEWAY_CALLS } from '../lib/gatewayWire.js'@@ -155,6 +157,8 @@ export function runGatewayService(options: GatewayServiceOptions): ServiceProcesconst { port, ops } = gatewayconst connId = text(payload.connId)switch (kind) {+ case 'usageLaunch': port.usageLaunch?.(payload.signal as ProductUsageLaunchSignal); return+ case 'usageCounter': port.usageCounter?.(payload.metric as ProductUsageMetric); returncase 'connect': port.connect(); returncase 'thisComputerOnly': port.serveThisComputerOnly(); returncase 'hold': port.holdRequests(); returndiff --git a/cli/src/gateway/productUsage.spec.ts b/cli/src/gateway/productUsage.spec.tsnew file mode 100644index 000000000..745aa6ecf--- /dev/null+++ b/cli/src/gateway/productUsage.spec.ts@@ -0,0 +1,203 @@+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'+import { join } from 'node:path'+import { tmpdir } from 'node:os'+import { afterEach, beforeEach, expect, it, vi } from 'vitest'+import { createProductUsage, type ProductUsageDeps } from './productUsage.js'++let dir: string, file: string, now: number, enabled: boolean, revision: number+let usage: ReturnType<typeof createProductUsage>+let sent: unknown[], retry: boolean+let request: ReturnType<typeof vi.fn<ProductUsageDeps['request']>>+beforeEach(() => {+ dir = mkdtempSync(join(tmpdir(), 'harness-product-usage-')); file = join(dir, 'counts.json')+ now = Date.parse('2026-10-12T10:00:00Z'); enabled = true; revision = 0; sent = []; retry = false+ request = vi.fn(async (method: string, _path: string, body?: unknown) => {+ if (method === 'GET') return { status: 200, body: { data: { enabled, revision } } }+ sent.push(structuredClone(body))+ return { status: retry ? 503 : 200, body: { data: { accepted: !retry } } }+ })+ usage = createProductUsage({ file, now: () => now, request })+})+afterEach(() => { usage.stop(); rmSync(dir, { recursive: true, force: true }) })+const totals = () => {+ const result: Record<string, number> = {}+ for (const report of sent as { counters: Record<string, number> }[]) for (const [k, v] of Object.entries(report.counters)) result[k] = (result[k] ?? 0) + v+ return result+}++it('keeps first-launch 24-hour value counts on their original cohort day across restart, without an identity', async () => {+ await usage.sync()+ now = Date.parse('2026-10-12T23:30:00Z')+ usage.launch({ id: 'PRIVATE_CREATION_CANARY', phase: 'start' }); await usage.sync(); usage.stop()+ usage = createProductUsage({ file, now: () => now, request }); await usage.sync()+ now += 2 * 3600000+ usage.observe('turn_started', 'PRIVATE_AGENT_CANARY', false)+ usage.observe('text_delta', 'PRIVATE_AGENT_CANARY', false)+ usage.observe('text_delta', 'PRIVATE_AGENT_CANARY', false)+ usage.observe('turn_ended', 'PRIVATE_AGENT_CANARY', false)+ await usage.sync(); await usage.sync()+ expect(totals()).toMatchObject({ first_launch_installations: 1, first_launch_work_24h_installations: 1, first_launch_response_24h_installations: 1 })+ const cohortReports = (sent as { day: string; counters: Record<string, number> }[]).filter(r => r.counters.first_launch_response_24h_installations)+ expect(cohortReports.map(r => r.day)).toEqual(['2026-10-12'])+ expect(JSON.stringify(sent)).not.toContain('PRIVATE_')+ expect(readFileSync(file, 'utf8')).not.toContain('PRIVATE_')+})++it('does not count late work as first-launch 24-hour value or restart the cohort for another launch', async () => {+ await usage.sync(); usage.launch({ id: 'synthetic-creation-1', phase: 'start' })+ now += 86400001+ usage.launch({ id: 'synthetic-creation-2', phase: 'start' })+ usage.observe('turn_started', 'a', false); usage.observe('text_delta', 'a', false)+ await usage.sync(); await usage.sync()+ expect(totals().first_launch_installations).toBe(1)+ expect(totals().first_launch_response_24h_installations).toBeUndefined()+})++it('collects nothing before it can check the preference, and respects off', async () => {+ usage.observe('turn_started', 'private-agent', false)+ enabled = false+ await usage.sync()+ usage.observe('turn_started', 'private-agent', false)+ usage.opened('desktop'); await usage.sync()+ expect(sent).toEqual([])+})++it('reduces turns locally, excludes replay, and never persists or uploads agent identity', async () => {+ await usage.sync()+ usage.opened('desktop')+ usage.observe('turn_started', 'PRIVATE_CANARY', true)+ usage.observe('turn_started', 'PRIVATE_CANARY', false)+ usage.observe('turn_started', 'PRIVATE_CANARY', false)+ now += 22_000+ usage.observe('turn_ended', 'PRIVATE_CANARY', false)+ usage.observe('turn_ended', 'PRIVATE_CANARY', false)+ await usage.sync()+ expect(totals()).toMatchObject({ active_installation_days: 1, working_installation_days: 1, first_work_installations: 1,+ weekly_working_installations: 1, turns_started: 1, turns_ended: 1, duration_10s_to_1m: 1, desktop_opens: 1 })+ expect(JSON.stringify(sent)).not.toContain('PRIVATE_CANARY')+ expect(readFileSync(file, 'utf8')).not.toContain('PRIVATE_CANARY')+ expect(sent[0]).not.toHaveProperty('userId')+})++it('keeps the receipt immutable across uncertain responses and process restarts', async () => {+ await usage.sync(); usage.observe('turn_started', 'a', false); retry = true+ await usage.sync(); const first = structuredClone(sent[0]); usage.stop()+ usage = createProductUsage({ file, now: () => now, request })+ retry = false; await usage.sync()+ expect(sent[1]).toEqual(first)+ expect(JSON.parse(readFileSync(file, 'utf8')).pending).toBeNull()+})++it('drops a pre-opt-out queue even if the next observed choice is on again', async () => {+ await usage.sync(); usage.observe('turn_started', 'a', false); retry = true; await usage.sync()+ revision = 2; retry = false+ await usage.sync()+ expect(sent).toHaveLength(1)+ expect(JSON.parse(readFileSync(file, 'utf8')).pending).toBeNull()+})++it('counts repeat days and consecutive weeks once, independently of event volume', async () => {+ await usage.sync(); usage.observe('turn_started', 'a', false); usage.observe('turn_ended', 'a', false); await usage.sync()+ now = Date.parse('2026-10-13T10:00:00Z')+ usage.observe('turn_started', 'a', false); usage.observe('turn_ended', 'a', false, true); await usage.sync()+ now = Date.parse('2026-10-19T10:00:00Z')+ usage.observe('turn_started', 'a', false); await usage.sync()+ // Cohort returns use earlier day buckets; the bounded uploader sends one day per sync.+ for (let i = 0; i < 4; i++) await usage.sync()+ expect(totals()).toMatchObject({ working_installation_days: 3, repeat_work_installation_days: 2,+ first_work_installations: 1, weekly_working_installations: 2, weekly_returning_installations: 1, turns_interrupted: 1 })+})++it('treats unknown preference and unavailable servers as missing coverage', async () => {+ request.mockResolvedValue({ status: 503, body: {} })+ await usage.sync(); usage.observe('turn_started', 'a', false)+ expect(sent).toHaveLength(0)+})++it('rebuilds a persisted report from its allowlist, removing content injected into local storage', async () => {+ usage.stop()+ writeFileSync(file, JSON.stringify({ revision: 0, days: { '2026-10-12': { turns_started: 1, prompt: 'PRIVATE_CANARY' } },+ pending: { schemaVersion: 1, revision: 0, id: 'cf1c5a03-388c-4265-b5fb-a4c3d47e407f', day: '2026-10-12',+ counters: { turns_ended: 1, result: 'PRIVATE_CANARY' }, prompt: 'PRIVATE_CANARY' } }))+ usage = createProductUsage({ file, now: () => now, request })+ await usage.sync(); await usage.sync()+ expect(totals()).toEqual({ turns_ended: 1, turns_started: 1 })+ expect(JSON.stringify(sent)).not.toContain('PRIVATE_CANARY')+ expect(readFileSync(file, 'utf8')).not.toContain('PRIVATE_CANARY')+})++it('expires pending reports instead of replaying them beyond the server dedupe window', async () => {+ await usage.sync(); usage.observe('turn_started', 'a', false); retry = true; await usage.sync()+ now += 36 * 86400000; retry = false+ await usage.sync()+ expect(sent).toHaveLength(1)+})++it('can discard its queue when the signed-in account changes', async () => {+ await usage.sync(); usage.observe('turn_started', 'a', false); retry = true; await usage.sync()+ usage.stop(true)+ expect(JSON.parse(readFileSync(file, 'utf8')).pending).toBeNull()+ expect(JSON.parse(readFileSync(file, 'utf8')).days).toEqual({})+})++it('ignores an oversized local file and starts a bounded queue', async () => {+ usage.stop(); writeFileSync(file, ' '.repeat(300_000))+ usage = createProductUsage({ file, now: () => now, request })+ await usage.sync(); usage.observe('turn_started', 'a', false); await usage.sync()+ expect(totals().turns_started).toBe(1)+ expect(readFileSync(file).length).toBeLessThan(64 * 1024)+})++it('counts first-response latency, silent waits and errors once without reading content', async () => {+ await usage.sync(); usage.observe('turn_started', 'PRIVATE_AGENT', false)+ now += 61_000; await usage.sync(); await usage.sync()+ usage.observe('error', 'PRIVATE_AGENT', false); usage.observe('error', 'PRIVATE_AGENT', false)+ usage.observe('text_delta', 'PRIVATE_AGENT', true)+ usage.observe('text_delta', 'PRIVATE_AGENT', false); usage.observe('text_delta', 'PRIVATE_AGENT', false)+ usage.observe('turn_ended', 'PRIVATE_AGENT', false)+ usage.observe('turn_started', 'another', false); usage.observe('turn_ended', 'another', false)+ await usage.sync()+ expect(totals()).toMatchObject({ turns_waiting_over_1m: 1, turns_with_error: 1, turns_with_response: 1,+ response_1m_to_5m: 1, first_response_installations: 1, turns_ended_without_response: 1 })+ expect(JSON.stringify(sent)).not.toContain('PRIVATE_AGENT')+})++it('attributes D1/D7 return to the original working day, surviving restarts and deduplicating turns', async () => {+ const work = async () => { usage.observe('turn_started', 'a', false); usage.observe('turn_ended', 'a', false); await usage.sync() }+ await usage.sync(); await work(); usage.stop()+ now += 86400000; usage = createProductUsage({ file, now: () => now, request }); await usage.sync()+ await work(); await work()+ now += 6 * 86400000; await work()+ await usage.sync() // the remaining current-day batch+ const returns = (sent as {day: string; counters: Record<string, number>}[]).filter(r => r.counters.d1_returning_work_installations || r.counters.d7_returning_work_installations)+ expect(returns.map(r => r.day)).toEqual(['2026-10-12', '2026-10-12'])+ expect(totals()).toMatchObject({ d1_returning_work_installations: 1, d7_returning_work_installations: 1 })+})++it('accepts only known scalar counters and stops diagnostics with the privacy choice', async () => {+ await usage.sync(); usage.counter('create_requests'); usage.counter('PRIVATE_CANARY' as never); await usage.sync()+ enabled = false; await usage.sync(); usage.counter('create_failed'); await usage.sync()+ expect(totals()).toEqual({ create_requests: 1 })+})++it('tracks a durable launch through polls without persisting its receipt or counting polls as attempts', async () => {+ await usage.sync()+ const id = 'PRIVATE_CREATION_CANARY'+ usage.launch({ id, phase: 'start' }); usage.launch({ id, phase: 'start' })+ usage.launch({ id, phase: 'pending', wait: 'install' }); usage.launch({ id, phase: 'pending', wait: 'install' })+ now += 65_000+ usage.launch({ id, phase: 'failed', failure: 'setup' }); usage.launch({ id, phase: 'failed', failure: 'setup' })+ await usage.sync()+ expect(totals()).toEqual({ first_launch_installations: 1, launch_started: 1, launch_wait_install: 1, launch_failed: 1, launch_failed_setup: 1, launch_1m_to_5m: 1 })+ expect(JSON.stringify(sent) + readFileSync(file, 'utf8')).not.toContain(id)+})++it('calls an unobserved launch unknown, not failed, and drops launch observations on opt-out', async () => {+ await usage.sync(); usage.launch({ id: 'fixture-creation-one', phase: 'start' })+ now += 16 * 60_000; await usage.sync()+ expect(totals()).toEqual({ first_launch_installations: 1, launch_started: 1, launch_unobserved: 1 })+ usage.launch({ id: 'fixture-creation-two', phase: 'start' }); enabled = false; await usage.sync()+ enabled = true; revision++; await usage.sync()+ usage.launch({ id: 'fixture-creation-two', phase: 'created' }); await usage.sync()+ expect(totals().launch_created).toBeUndefined()+})diff --git a/cli/src/gateway/productUsage.ts b/cli/src/gateway/productUsage.tsnew file mode 100644index 000000000..cb78ee93f--- /dev/null+++ b/cli/src/gateway/productUsage.ts@@ -0,0 +1,263 @@+import { mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs'+import { dirname } from 'node:path'+import { randomUUID } from 'node:crypto'+import type { ProductUsageLaunchSignal } from '../lib/productUsageSignals.js'+import { PRODUCT_USAGE_DAYS, PRODUCT_USAGE_MAX_COUNT, PRODUCT_USAGE_METRICS,+ type ProductUsageChoice, type ProductUsageMetric, type ProductUsageReport } from '../lib/productUsageContract.js'++const DAY = 86_400_000+const key = (now: number) => new Date(now).toISOString().slice(0, 10)+const week = (now: number) => { const d = new Date(now); return key(now - ((d.getUTCDay() + 6) % 7) * DAY) }+type Counters = Partial<Record<ProductUsageMetric, number>>+interface State {+ revision: number+ activeDay: string | null+ workDay: string | null+ workWeek: string | null+ workedBefore: boolean+ respondedBefore: boolean+ launchedBefore: boolean+ firstLaunchAt: number | null+ launchWorked: boolean+ launchResponded: boolean+ workDays: string[]+ days: Record<string, Counters>+ pending: ProductUsageReport | null+}+const fresh = (revision: number): State => ({ revision, activeDay: null, workDay: null, workWeek: null,+ workedBefore: false, respondedBefore: false, launchedBefore: false, firstLaunchAt: null,+ launchWorked: false, launchResponded: false, workDays: [], days: {}, pending: null })+export interface ProductUsageDeps {+ file: string+ request(method: string, path: string, body?: unknown): Promise<{ status: number; body: Record<string, unknown> }>+ now?(): number+ uuid?(): string+}++/** A reporting component of the gateway service; the core never waits for it.+ * Counts lifecycle facts only. No transcript, prompt, response, tool or error object enters this API.+ * Agent identifiers live only in the bounded in-memory duration map and never reach disk or HTTP.+ */+export function createProductUsage(deps: ProductUsageDeps) {+ const now = deps.now ?? Date.now, uuid = deps.uuid ?? randomUUID+ let state = fresh(-1), enabled = false, stopped = false, active = false+ let syncing: Promise<void> | null = null, persistTimer: ReturnType<typeof setTimeout> | undefined+ const running = new Map<string, { started: number; response: boolean; error: boolean; waited: boolean }>()+ const launches = new Map<string, { started: number; done: boolean; waits: Set<string> }>()+ try {+ if (statSync(deps.file).size > 256 * 1024) throw new Error('Usage queue exceeds its bound')+ // Reconstruct every field; even a corrupted local file cannot introduce a new upload property.+ const saved = JSON.parse(readFileSync(deps.file, 'utf8')) as State+ if (Number.isSafeInteger(saved.revision) && saved.revision >= 0) {+ state = fresh(saved.revision)+ for (const field of ['activeDay', 'workDay', 'workWeek'] as const) {+ if (typeof saved[field] === 'string' && validDay(saved[field]!)) state[field] = saved[field]+ }+ state.workedBefore = saved.workedBefore === true+ state.respondedBefore = saved.respondedBefore === true+ state.launchedBefore = saved.launchedBefore === true+ state.firstLaunchAt = Number.isSafeInteger(saved.firstLaunchAt) && saved.firstLaunchAt! <= now()+ && validDay(key(saved.firstLaunchAt!)) ? saved.firstLaunchAt : null+ state.launchWorked = saved.launchWorked === true+ state.launchResponded = saved.launchResponded === true+ state.workDays = Array.isArray(saved.workDays) ? [...new Set(saved.workDays.filter(d => typeof d === 'string' && validDay(d)))].slice(-35) : []+ for (const [day, counters] of Object.entries(saved.days ?? {})) if (validDay(day)) state.days[day] = clean(counters)+ const pending = saved.pending+ if (pending && pending.schemaVersion === 1 && pending.revision === state.revision && validDay(pending.day)+ && typeof pending.id === 'string' && /^[a-f0-9-]{36}$/.test(pending.id)) {+ state.pending = { schemaVersion: 1, revision: state.revision, id: pending.id, day: pending.day, counters: clean(pending.counters) }+ }+ }+ } catch { /* Missing or unreadable telemetry must not affect a session. */ }++ function validDay(day: string): boolean {+ const stamp = Date.parse(day + 'T00:00:00.000Z'), today = Math.floor(now() / DAY) * DAY+ return /^\d{4}-\d{2}-\d{2}$/.test(day) && Number.isFinite(stamp) && key(stamp) === day+ && stamp <= today && stamp > today - PRODUCT_USAGE_DAYS * DAY+ }+ function clean(input: Counters): Counters {+ const result: Counters = {}+ for (const metric of PRODUCT_USAGE_METRICS) {+ const value = input?.[metric]+ if (typeof value === 'number' && Number.isSafeInteger(value) && value > 0 && value <= PRODUCT_USAGE_MAX_COUNT) result[metric] = value+ }+ return result+ }+ function persist(): boolean {+ clearTimeout(persistTimer); persistTimer = undefined+ for (const field of ['activeDay', 'workDay', 'workWeek'] as const) if (state[field] && !validDay(state[field]!)) state[field] = null+ for (const day of Object.keys(state.days)) if (!validDay(day)) delete state.days[day]+ state.workDays = state.workDays.filter(validDay)+ if (state.firstLaunchAt !== null && !validDay(key(state.firstLaunchAt))) state.firstLaunchAt = null+ if (state.pending && !validDay(state.pending.day)) state.pending = null+ try {+ mkdirSync(dirname(deps.file), { recursive: true, mode: 0o700 })+ writeFileSync(deps.file + '.tmp', JSON.stringify(state), { mode: 0o600 })+ renameSync(deps.file + '.tmp', deps.file)+ return true+ } catch { enabled = false; return false }+ }+ function dirty(): void {+ if (!persistTimer) { persistTimer = setTimeout(persist, 1000); persistTimer.unref() }+ }+ function add(metric: ProductUsageMetric, day = key(now())): void {+ const counters = state.days[day] ??= {}+ counters[metric] = Math.min(PRODUCT_USAGE_MAX_COUNT, (counters[metric] ?? 0) + 1)+ dirty()+ }+ function markActive(): void {+ if (!enabled || stopped) return+ if (state.activeDay !== key(now())) { state.activeDay = key(now()); add('active_installation_days') }+ }+ function launchValue(response: boolean): void {+ if (state.firstLaunchAt === null || now() < state.firstLaunchAt || now() - state.firstLaunchAt > DAY) return+ const field = response ? 'launchResponded' : 'launchWorked'+ if (!state[field]) {+ state[field] = true+ add(response ? 'first_launch_response_24h_installations' : 'first_launch_work_24h_installations', key(state.firstLaunchAt))+ }+ }+ function choice(value: ProductUsageChoice): void {+ if (state.revision !== value.revision || !value.enabled) {+ state = fresh(value.revision); running.clear(); launches.clear()+ enabled = false+ if (!persist()) return+ }+ enabled = value.enabled && !stopped+ }+ async function syncOnce(): Promise<void> {+ try {+ const response = await deps.request('GET', '/api/product-usage/settings')+ if (stopped) return+ const body = response.body.data as ProductUsageChoice | undefined+ if (response.status !== 200 || typeof body?.enabled !== 'boolean'+ || !Number.isSafeInteger(body.revision) || body.revision < 0) { enabled = false; running.clear(); launches.clear(); return }+ choice(body)+ if (!enabled) return+ for (const turn of running.values()) if (!turn.response && !turn.waited && now() - turn.started >= 60_000) {+ turn.waited = true; add('turns_waiting_over_1m')+ }+ for (const [id, launch] of launches) {+ if (!launch.done && now() - launch.started >= 15 * 60_000) { launch.done = true; add('launch_unobserved') }+ if (now() - launch.started >= 35 * 60_000) launches.delete(id)+ }+ if (active) markActive()+ if (!state.pending) {+ const day = Object.keys(state.days).sort().find(d => validDay(d) && Object.keys(state.days[d]).length)+ if (!day) return+ state.pending = { schemaVersion: 1, revision: state.revision, id: uuid(), day, counters: state.days[day] }+ delete state.days[day]+ }+ // Persist the immutable receipt before sending. A crash or ambiguous response retries that id.+ if (!persist()) return+ const report = state.pending+ if (!report) return+ const answer = await deps.request('POST', '/api/product-usage/report', report)+ if (stopped) return+ const result = answer.body.data as { accepted?: boolean; reason?: string } | undefined+ if (answer.status === 200 && result?.accepted === true) { state.pending = null; persist() }+ else if (result?.reason === 'CHOICE_CHANGED') { enabled = false; state = fresh(-1); running.clear(); launches.clear(); persist() }+ else if (result?.reason === 'EXPIRED') { state.pending = null; persist() }+ } catch { enabled = false; running.clear(); launches.clear() /* No error text or request body in logs. */ }+ }+ const sync = (): Promise<void> => syncing ??= syncOnce().finally(() => { syncing = null })+ const timer = setInterval(() => { void sync() }, 60_000)+ timer.unref()++ return {+ sync,+ counter(metric: ProductUsageMetric): void {+ if (enabled && !stopped && PRODUCT_USAGE_METRICS.includes(metric)) add(metric)+ },+ launch(signal: ProductUsageLaunchSignal): void {+ if (!enabled || stopped || !signal || typeof signal.id !== 'string' || !/^[a-zA-Z0-9_-]{16,96}$/.test(signal.id)) return+ if (signal.phase === 'start') {+ if (launches.has(signal.id)) return+ if (!state.launchedBefore) {+ state.launchedBefore = true; state.firstLaunchAt = now(); add('first_launch_installations')+ }+ if (launches.size >= 1000) {+ const oldest = launches.keys().next().value!+ if (!launches.get(oldest)!.done) add('launch_unobserved')+ launches.delete(oldest)+ }+ launches.set(signal.id, { started: now(), done: false, waits: new Set() }); add('launch_started'); return+ }+ const launch = launches.get(signal.id)+ if (!launch || launch.done) return+ if (signal.phase === 'pending') {+ const wait = ['install', 'model', 'native'].includes(signal.wait ?? '') ? signal.wait! : 'other'+ if (!launch.waits.has(wait)) { launch.waits.add(wait); add(`launch_wait_${wait}` as ProductUsageMetric) }+ return+ }+ if (!['created', 'failed', 'cancelled', 'unconfirmed'].includes(signal.phase)) return+ launch.done = true+ add(`launch_${signal.phase}` as ProductUsageMetric)+ if (signal.phase === 'failed') {+ const kind = ['setup', 'auth', 'unavailable', 'invalid'].includes(signal.failure ?? '') ? signal.failure! : 'other'+ add(`launch_failed_${kind}` as ProductUsageMetric)+ }+ const elapsed = Math.max(0, now() - launch.started)+ add(elapsed < 10_000 ? 'launch_under_10s' : elapsed < 60_000 ? 'launch_10s_to_1m' : elapsed < 300_000 ? 'launch_1m_to_5m' : 'launch_over_5m')+ },+ presence(value: boolean): void { active = value; if (value) markActive() },+ opened(surface: 'desktop' | 'tui'): void {+ if (!enabled || stopped) return+ markActive(); add(surface === 'desktop' ? 'desktop_opens' : 'tui_opens')+ },+ observe(type: 'turn_started' | 'turn_ended' | 'text_delta' | 'error', agent: string, replay: boolean, interrupted = false): void {+ if (!enabled || stopped || replay || !agent || agent.length > 256) return+ if (type === 'turn_started') {+ if (running.has(agent) || running.size >= 1000) return+ running.set(agent, { started: now(), response: false, error: false, waited: false }); markActive(); add('turns_started')+ launchValue(false)+ if (state.workDay !== key(now())) {+ add('working_installation_days')+ add(state.workedBefore ? 'repeat_work_installation_days' : 'first_work_installations')+ state.workDay = key(now()); state.workedBefore = true+ // Return counters belong to the earlier working-day cohort, not today's new starts.+ // Only these date flags stay here; no server-side installation/user join is needed.+ for (const [lag, metric] of [[1, 'd1_returning_work_installations'], [7, 'd7_returning_work_installations']] as const) {+ const cohort = key(now() - lag * DAY)+ if (state.workDays.includes(cohort)) add(metric, cohort)+ }+ state.workDays = [...state.workDays.filter(validDay), key(now())]+ }+ const currentWeek = week(now())+ if (state.workWeek !== currentWeek) {+ add('weekly_working_installations')+ if (state.workWeek === key(Date.parse(currentWeek) - 7 * DAY)) add('weekly_returning_installations')+ state.workWeek = currentWeek+ }+ } else {+ const turn = running.get(agent)+ if (!turn) return+ const elapsed = Math.max(0, now() - turn.started)+ if (!turn.response && !turn.waited && elapsed >= 60_000) { turn.waited = true; add('turns_waiting_over_1m') }+ if (type === 'error') {+ if (!turn.error) { turn.error = true; add('turns_with_error') }+ return+ }+ if (type === 'text_delta') {+ if (!turn.response) {+ turn.response = true; add('turns_with_response')+ // Do not attribute a response from a turn already running when the first launch began.+ if (state.firstLaunchAt !== null && turn.started >= state.firstLaunchAt) launchValue(true)+ if (!state.respondedBefore) { state.respondedBefore = true; add('first_response_installations') }+ add(elapsed < 10_000 ? 'response_under_10s' : elapsed < 60_000 ? 'response_10s_to_1m' : elapsed < 300_000 ? 'response_1m_to_5m' : 'response_over_5m')+ }+ return+ }+ running.delete(agent)+ if (!turn.response) add('turns_ended_without_response')+ add(interrupted ? 'turns_interrupted' : 'turns_ended')+ add(elapsed < 10_000 ? 'duration_under_10s' : elapsed < 60_000 ? 'duration_10s_to_1m' : elapsed < 300_000 ? 'duration_1m_to_5m' : 'duration_over_5m')+ }+ },+ stop(discard = false): void {+ stopped = true; enabled = false; clearInterval(timer); running.clear(); launches.clear()+ if (discard) state = fresh(-1)+ persist()+ },+ }+}diff --git a/cli/src/gateway/start.ts b/cli/src/gateway/start.tsindex ac80024c0..a74bb144f 100644--- a/cli/src/gateway/start.ts+++ b/cli/src/gateway/start.ts@@ -17,6 +17,8 @@import { renameSync } from 'node:fs'import { hostname } from 'node:os'import { join } from 'node:path'+import { createHash } from 'node:crypto'+import { createProductUsage } from './productUsage.js'import { env } from '../config/env.js'import type { GatewayAccount, GatewayEvents, GatewayOps, HttpAnswer, WindowRelay } from '../core/api.js'import { AutonomousDeviceDirect } from '../lib/autonomous-device/direct.js'@@ -134,6 +136,12 @@ export function startGateway(host: GatewayHost): StartedGateway {const gateway = new RelayGateway({machineId: host.machineId, auth: host.tokens, computerId: host.computerId, autonomousEnv: host.autonomousEnv, core: host.events,})+ // Account separation is local only. Neither this filename nor the machine identity is uploaded.+ const usage = host.signedIn ? createProductUsage({+ file: join(env.ADAPTER_DATA_DIR, 'product-usage', createHash('sha256').update(host.autonomousEnv + ':' + host.machineId).digest('hex') + '.json'),+ request: (method, path, body) => accountHttp.backend(method, path, body),+ }) : null+ if (usage) { gateway.productUsage = usage; void usage.sync() }/** The identity this machine was removed under is never used again: the next start mints a new one. */const spendIdentity = (): void => {@@ -487,6 +495,10 @@ export function startGateway(host: GatewayHost): StartedGateway {},revokeIdentity: (identity) => { gateway.e2ee.revoke(fingerprint(b64d(identity))) },account: (next) => {+ // Tokens may change before this process restarts. Never send the previous account's queue+ // under a new sign-in, even when both accounts happen to have the same preference revision.+ if (next.machineId !== account.machineId || next.autonomousEnv !== account.autonomousEnv+ || next.signIn?.epoch !== account.signIn?.epoch || next.signIn?.acct !== account.signIn?.acct) usage?.stop(true)account = nextstartGroup()registerAndSweep()@@ -518,6 +530,7 @@ export function startGateway(host: GatewayHost): StartedGateway {ops,windowRelay,stop: async () => {+ usage?.stop()clearInterval(devlogTimer)syncer.stop()direct?.stop()diff --git a/cli/src/hookServer.spec.ts b/cli/src/hookServer.spec.tsindex fd5ce499b..33f5b6501 100644--- a/cli/src/hookServer.spec.ts+++ b/cli/src/hookServer.spec.ts@@ -342,6 +342,34 @@ describe('the Agent Messages proxy', () => {})describe('account Experimental settings proxy', () => {+ it('proxies only voluntary fixed-choice feedback and guards it from cross-origin requests', async () => {+ const send = vi.fn(async () => ({ status: 200, body: { success: true, data: { accepted: true } } }))+ const { base } = await start({ onProductFeedback: send })+ const path = `${base}/api/product-usage/feedback`+ const body = { id: '12345678-1234-4234-8234-123456789012', answer: 'useful' }+ const headers = { 'x-adapter-local': '1', 'content-type': 'application/json' }+ for (const h of [{}, { ...headers, origin: 'https://untrusted.example' }]) {+ expect((await fetch(path, { method: 'POST', headers: h, body: JSON.stringify(body) })).status).toBe(403)+ }+ for (const invalid of [{ ...body, text: 'PRIVATE_CANARY' }, { ...body, answer: 'PRIVATE_CANARY' }, { ...body, id: 'PRIVATE_CANARY' }]) {+ expect((await fetch(path, { method: 'POST', headers, body: JSON.stringify(invalid) })).status).toBe(400)+ }+ expect(send).not.toHaveBeenCalled()+ expect((await fetch(path, { method: 'POST', headers, body: JSON.stringify(body) })).status).toBe(200)+ expect(send).toHaveBeenCalledExactlyOnceWith(body)+ })+ it('serves the Privacy switch and rejects cross-origin, extra-field and malformed writes', async () => {+ const write = vi.fn(async () => ({ status: 200, body: { success: true, data: { enabled: false, revision: 1 } } }))+ const { base } = await start({ onProductUsageRead: async () => ({ status: 200, body: { success: true, data: { enabled: true, revision: 0 } } }), onProductUsageWrite: write })+ expect((await (await fetch(`${base}/api/product-usage/settings`)).json())).toMatchObject({ data: { enabled: true } })+ const path = `${base}/api/product-usage/settings`+ expect((await fetch(path, { method: 'POST', body: '{"enabled":false}' })).status).toBe(403)+ const headers = { 'x-adapter-local': '1', 'content-type': 'application/json' }+ expect((await fetch(path, { method: 'POST', headers: { ...headers, origin: 'https://untrusted.example' }, body: '{"enabled":false}' })).status).toBe(403)+ expect((await fetch(path, { method: 'POST', headers, body: '{"enabled":false,"userId":"other"}' })).status).toBe(400)+ expect((await fetch(path, { method: 'POST', headers, body: '{"enabled":false}' })).status).toBe(200)+ expect(write).toHaveBeenCalledExactlyOnceWith({ enabled: false })+ })it('reads through the account proxy and guards writes with the local header', async () => {const snapshot = { accountId: 'owner', revision: 0, features: { focus_bar_creature: false, share_button: false } }const write = vi.fn(async (body: unknown) => ({ status: 200, body: { success: true, data: { ...snapshot, echo: body } } }))diff --git a/cli/src/hookServer.ts b/cli/src/hookServer.tsindex 2dbd84b2b..e1bd045fd 100644--- a/cli/src/hookServer.ts+++ b/cli/src/hookServer.ts@@ -1,3 +1,4 @@+import { PRODUCT_FEEDBACK } from './lib/productUsageContract.js'/*** Tiny localhost HTTP server for the Claude Code hook callbacks. `hook/notify.mjs` POSTs here on* SessionStart/SessionEnd (127.0.0.1:<PORT>). This replaces the old Fastify routes — the browser@@ -181,6 +182,9 @@ export interface HookServerHandlers {* here too (core/experiments.ts `createAgentSettingsSync`). */onExperimentalRead?: () => Promise<PairOutcome>onExperimentalWrite?: (body: unknown) => Promise<PairOutcome>+ onProductFeedback?: (body: unknown) => Promise<PairOutcome>+ onProductUsageRead?: () => Promise<PairOutcome>+ onProductUsageWrite?: (body: unknown) => Promise<PairOutcome>/** /api/store/* — proxy the Harness Store's ratings and reviews to backend the same way: reads* ungated like the machine list, writes (PUT/DELETE) CSRF-guarded like a rename. See storeProxy.ts. */onStore?: StoreHandler@@ -1024,6 +1028,33 @@ export function startHookServer(if (!handlers.onExperimentalRead) { json(503, { error: 'UNAVAILABLE' }); return }await proxied(handlers.onExperimentalRead); return}+ if (req.method === 'POST' && url === '/api/product-usage/feedback') {+ if (!localOk) { json(403, { error: 'FORBIDDEN' }); return }+ if (!handlers.onProductFeedback) { json(503, { error: 'UNAVAILABLE' }); return }+ let body: unknown+ try { body = JSON.parse(await readBody(req)) } catch { json(400, { error: 'BAD_REQUEST' }); return }+ const feedback = body as { answer?: unknown; id?: unknown } | null+ if (!feedback || typeof feedback !== 'object' || Object.keys(feedback).length !== 2+ || !PRODUCT_FEEDBACK.includes(feedback.answer as never) || typeof feedback.id !== 'string'+ || !/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(feedback.id)) {+ json(400, { error: 'BAD_REQUEST' }); return+ }+ await proxied(() => handlers.onProductFeedback!(feedback)); return+ }+ if (req.method === 'GET' && url === '/api/product-usage/settings') {+ if (!handlers.onProductUsageRead) { json(503, { error: 'UNAVAILABLE' }); return }+ await proxied(handlers.onProductUsageRead); return+ }+ if (req.method === 'POST' && url === '/api/product-usage/settings') {+ if (!localOk) { json(403, { error: 'FORBIDDEN' }); return }+ if (!handlers.onProductUsageWrite) { json(503, { error: 'UNAVAILABLE' }); return }+ let body: unknown+ try { body = JSON.parse(await readBody(req)) } catch { json(400, { error: 'BAD_REQUEST' }); return }+ if (!body || typeof body !== 'object' || Object.keys(body).length !== 1 || typeof (body as { enabled?: unknown }).enabled !== 'boolean') {+ json(400, { error: 'BAD_REQUEST' }); return+ }+ await proxied(() => handlers.onProductUsageWrite!(body)); return+ }if (req.method === 'PATCH' && url === '/api/experimental-settings') {if (!localOk) { json(403, { error: 'FORBIDDEN' }); return }if (!handlers.onExperimentalWrite) { json(503, { error: 'UNAVAILABLE' }); return }diff --git a/cli/src/lib/privacyCommand.spec.ts b/cli/src/lib/privacyCommand.spec.tsnew file mode 100644index 000000000..5a84cbe25--- /dev/null+++ b/cli/src/lib/privacyCommand.spec.ts@@ -0,0 +1,17 @@+import { beforeEach, expect, it, vi } from 'vitest'+const deps = vi.hoisted(() => ({ controlPlaneAuth: vi.fn(), requestJson: vi.fn() }))+vi.mock('./controlPlane.js', () => deps)+import { privacyCommand } from './privacyCommand.js'+beforeEach(() => { vi.restoreAllMocks(); vi.resetAllMocks(); deps.controlPlaneAuth.mockResolvedValue({ headers: { authorization: 'fixture' } }); deps.requestJson.mockResolvedValue({ enabled: false, revision: 1 }) })+it('reads or writes the account preference, without putting credentials in output', async () => {+ const log = vi.spyOn(console, 'log').mockImplementation(() => {})+ await privacyCommand('off', true)+ expect(deps.requestJson).toHaveBeenCalledWith('POST', '/api/product-usage/settings', { enabled: false }, { authorization: 'fixture' })+ expect(log).toHaveBeenCalledWith('{"enabled":false,"revision":1}')+ await privacyCommand()+ expect(deps.requestJson).toHaveBeenLastCalledWith('GET', '/api/product-usage/settings', undefined, { authorization: 'fixture' })+})+it('rejects unknown commands before reading credentials', async () => {+ await expect(privacyCommand('force')).rejects.toThrow('Usage:')+ expect(deps.controlPlaneAuth).not.toHaveBeenCalled()+})diff --git a/cli/src/lib/privacyCommand.ts b/cli/src/lib/privacyCommand.tsnew file mode 100644index 000000000..164b5f0ba--- /dev/null+++ b/cli/src/lib/privacyCommand.ts@@ -0,0 +1,12 @@+import { controlPlaneAuth, requestJson } from './controlPlane.js'+import type { ProductUsageChoice } from './productUsageContract.js'++/** Account-wide preference: the CLI works even when the local daemon is stopped. */+export async function privacyCommand(action = 'status', json = false): Promise<void> {+ if (!['status', 'on', 'off'].includes(action)) throw new Error('Usage: harness privacy status|on|off [--json]')+ const { headers } = await controlPlaneAuth()+ const state = await requestJson<ProductUsageChoice>(action === 'status' ? 'GET' : 'POST', '/api/product-usage/settings',+ action === 'status' ? undefined : { enabled: action === 'on' }, headers)+ if (typeof state?.enabled !== 'boolean') throw new Error('Update the Harness server to manage product usage sharing.')+ console.log(json ? JSON.stringify(state) : `Share product usage data: ${state.enabled ? 'on' : 'off'} (all computers on this account).`)+}diff --git a/cli/src/lib/productUsageContract.ts b/cli/src/lib/productUsageContract.tsnew file mode 100644index 000000000..5b86f7317--- /dev/null+++ b/cli/src/lib/productUsageContract.ts@@ -0,0 +1,35 @@+/** Fixed vocabulary only. Keep the CLI copy identical; conformance is tested. */+export const PRODUCT_USAGE_VERSION = 1+export const PRODUCT_USAGE_DAYS = 35+export const PRODUCT_USAGE_MAX_COUNT = 100_000+export const PRODUCT_FEEDBACK = ['useful', 'could_not_finish', 'slow', 'confusing', 'missing_feature'] as const+export const PRODUCT_USAGE_ACTIONS = ['create', 'resume', 'restart', 'model_change', 'history'] as const+export const PRODUCT_USAGE_ACTION_MEASURES = ['requests', 'ok', 'failed', 'pending', 'unknown',+ 'error_setup', 'error_auth', 'error_unavailable', 'error_invalid', 'error_other',+ 'under_1s', '1s_to_10s', '10s_to_1m', 'over_1m'] as const+export const PRODUCT_USAGE_METRICS = [+ 'active_installation_days', 'working_installation_days', 'first_work_installations',+ 'repeat_work_installation_days', 'weekly_working_installations', 'weekly_returning_installations',+ 'turns_started', 'turns_ended', 'turns_interrupted',+ 'duration_under_10s', 'duration_10s_to_1m', 'duration_1m_to_5m', 'duration_over_5m',+ 'desktop_opens', 'tui_opens',+ 'launch_started', 'launch_created', 'launch_failed', 'launch_cancelled', 'launch_unconfirmed', 'launch_unobserved',+ 'launch_wait_install', 'launch_wait_model', 'launch_wait_native', 'launch_wait_other',+ 'launch_failed_setup', 'launch_failed_auth', 'launch_failed_unavailable', 'launch_failed_invalid', 'launch_failed_other',+ 'launch_under_10s', 'launch_10s_to_1m', 'launch_1m_to_5m', 'launch_over_5m',+ 'turns_with_response', 'turns_with_error', 'turns_ended_without_response', 'turns_waiting_over_1m',+ 'response_under_10s', 'response_10s_to_1m', 'response_1m_to_5m', 'response_over_5m',+ 'first_launch_installations', 'first_launch_work_24h_installations', 'first_launch_response_24h_installations',+ 'first_response_installations', 'd1_returning_work_installations', 'd7_returning_work_installations',+ ...PRODUCT_FEEDBACK.map(answer => `feedback_${answer}` as const),+ ...PRODUCT_USAGE_ACTIONS.flatMap(action => PRODUCT_USAGE_ACTION_MEASURES.map(measure => `${action}_${measure}` as const)),+] as const+export type ProductUsageMetric = typeof PRODUCT_USAGE_METRICS[number]+export interface ProductUsageReport {+ schemaVersion: 1+ revision: number+ id: string+ day: string+ counters: Partial<Record<ProductUsageMetric, number>>+}+export interface ProductUsageChoice { enabled: boolean; revision: number }diff --git a/cli/src/lib/productUsageSignals.spec.ts b/cli/src/lib/productUsageSignals.spec.tsnew file mode 100644index 000000000..275a6108e--- /dev/null+++ b/cli/src/lib/productUsageSignals.spec.ts@@ -0,0 +1,31 @@+import { expect, it, vi } from 'vitest'+import { productUsageLaunch, productUsageRequest } from './productUsageSignals.js'++it('distinguishes a pending launch from a launched harness, and counts replies once', () => {+ let now = 0+ const emit = vi.fn(), done = productUsageRequest('agent_create', emit, () => now)+ now = 12_000; done(undefined, 'pending', false); done(undefined, 'created', true)+ expect(emit.mock.calls.flat()).toEqual(['create_requests', 'create_pending', 'create_10s_to_1m'])+})+it('maps known failures and never emits raw or unknown error strings', () => {+ const emit = vi.fn()+ productUsageRequest('agent_create', emit)('ENGINE_UNAVAILABLE', undefined, false)+ productUsageRequest('agent_restart', emit)('PRIVATE_ERROR_WITH_PATH', 'failed', false)+ expect(emit.mock.calls.flat()).toContain('create_error_setup')+ expect(emit.mock.calls.flat()).toContain('restart_error_other')+ expect(JSON.stringify(emit.mock.calls)).not.toContain('PRIVATE_')+})+it('ignores arbitrary RPC names and status polling and survives unavailable reporting', () => {+ const emit = vi.fn()+ for (const type of ['PRIVATE_METHOD', 'agent_create_status', 'text_delta']) productUsageRequest(type, emit)(undefined, undefined, true)+ expect(emit).not.toHaveBeenCalled()+ expect(() => productUsageRequest('agent_create', () => { throw Error('offline') })(undefined, 'created', true)).not.toThrow()+})++it('reduces durable launch statuses to fixed categories without forwarding error or hold text', () => {+ const emit = vi.fn(), id = 'fixture-creation-one'+ productUsageLaunch('agent_create', id, emit)(undefined, 'pending', false, 'install')+ productUsageLaunch('agent_create_status', id, emit)('PRIVATE_CANARY', 'failed', false, 'PRIVATE_CANARY')+ expect(emit.mock.calls.flat()).toEqual([{ id, phase: 'start' }, { id, phase: 'pending', wait: 'install' }, { id, phase: 'failed', failure: 'other' }])+ expect(JSON.stringify(emit.mock.calls)).not.toContain('PRIVATE_CANARY')+})diff --git a/cli/src/lib/productUsageSignals.ts b/cli/src/lib/productUsageSignals.tsnew file mode 100644index 000000000..3d29a1d52--- /dev/null+++ b/cli/src/lib/productUsageSignals.ts@@ -0,0 +1,67 @@+import type { ProductUsageMetric } from './productUsageContract.js'++const actions = { agent_create: 'create', agent_resume: 'resume', agent_restart: 'restart',+ agent_retarget: 'model_change', agent_recent: 'history' } as const+const setup = new Set(['TMUX_UNAVAILABLE', 'TMUX_TOO_OLD_FOR_DSH', 'TMUX_TOO_OLD_FOR_GRID', 'ENGINE_UNAVAILABLE',+ 'NATIVE_LAUNCH_HELD', 'DSH_MATERIALIZE_FAILED', 'SPAWN_FAILED', 'REGISTRATION_FAILED', 'GRID_CONFIG_FAILED'])+const auth = new Set(['UNAUTHORIZED', 'AUTH_REQUIRED', 'LOGIN_REQUIRED', 'OWNER_REQUIRED', 'E2EE_REQUIRED'])+const unavailable = new Set(['SERVICE_UNAVAILABLE', 'SERVICE_FAILED', 'GRID_UNAVAILABLE', 'API_UNAVAILABLE',+ 'UNSUPPORTED', 'UNSUPPORTED_ON_REMOTE', 'TIMEOUT', 'NATIVE_UNAVAILABLE'])+const invalid = new Set(['INVALID_ENGINE', 'INVALID_CWD', 'CWD_NOT_FOUND', 'INVALID_GRID', 'INVALID_DSH',+ 'INVALID_MODEL', 'INVALID_PERMISSION_MODE', 'INVALID_CREATION_ID', 'INVALID_PROJECT_SOURCE', 'WORKTREE_BUSY'])++type Failure = 'setup' | 'auth' | 'unavailable' | 'invalid' | 'other'+function failureKind(error: unknown): Failure {+ return typeof error !== 'string' ? 'other' : setup.has(error) ? 'setup' : auth.has(error) ? 'auth'+ : unavailable.has(error) ? 'unavailable' : invalid.has(error) ? 'invalid' : 'other'+}+export interface ProductUsageLaunchSignal {+ /** Local RAM only, discarded on stop/choice change; never part of a report or persisted queue. */+ id: string+ phase: 'start' | 'pending' | 'created' | 'failed' | 'cancelled' | 'unconfirmed'+ failure?: Failure+ wait?: 'install' | 'model' | 'native' | 'other'+}++/** Observe an actual new-harness receipt through subsequent status polls. Polling adds no attempts. */+export function productUsageLaunch(type: string, id: unknown, emit: (signal: ProductUsageLaunchSignal) => void) {+ const known = ['agent_create', 'agent_create_status', 'agent_create_cancel'].includes(type)+ && typeof id === 'string' && /^[a-zA-Z0-9_-]{16,96}$/.test(id)+ const send = (signal: Omit<ProductUsageLaunchSignal, 'id'>) => {+ if (known) { try { emit({ id: id as string, ...signal }) } catch { /* Optional measurement. */ } }+ }+ if (type === 'agent_create') send({ phase: 'start' })+ return (error: unknown, state: unknown, hasAgent: boolean, held: unknown) => {+ if (error != null || state === 'failed') send({ phase: 'failed', failure: failureKind(error) })+ else if (state === 'created' || hasAgent) send({ phase: 'created' })+ else if (state === 'pending') send({ phase: 'pending', wait: held === 'install' ? 'install' : held === 'models' ? 'model' : held === 'native' ? 'native' : 'other' })+ else if (state === 'cancelled') send({ phase: 'cancelled' })+ else if (state === 'unconfirmed' || state === 'unavailable' || state === 'missing') send({ phase: 'unconfirmed' })+ }+}++/** Reduce an RPC at its existing boundary. Only fixed counter names leave this helper.+ * No request, reply, error message, path, agent name or identifier is handed to the collector.+ * A pending durable launch is an acknowledgement, never a successful launch. Status polling is+ * excluded: counting each poll as a launch would turn a slow install into hundreds of attempts.+ */+export function productUsageRequest(type: string, emit: (metric: ProductUsageMetric) => void, now = Date.now) {+ const action = Object.hasOwn(actions, type) ? actions[type as keyof typeof actions] : null+ const started = now()+ let answered = false+ const count = (measure: string) => { if (action) { try { emit(`${action}_${measure}` as ProductUsageMetric) } catch { /* Optional measurement. */ } } }+ count('requests')+ return (error: unknown, state: unknown, hasAgent: boolean) => {+ if (!action || answered) return+ answered = true+ if (error != null || state === 'failed') {+ count('failed')+ count(`error_${failureKind(error)}`)+ } else if (state === 'pending' || state === 'preparing' || state === 'starting') count('pending')+ else if (state === 'unconfirmed' || state === 'unavailable' || state === 'cancelled') count('unknown')+ else if (action === 'history' || action === 'model_change' || hasAgent || state === 'created') count('ok')+ else count('unknown')+ const elapsed = Math.max(0, now() - started)+ count(elapsed < 1000 ? 'under_1s' : elapsed < 10_000 ? '1s_to_10s' : elapsed < 60_000 ? '10s_to_1m' : 'over_1m')+ }+}diff --git a/desktop/design/review/2026-10-13-product-privacy/desktop.png b/desktop/design/review/2026-10-13-product-privacy/desktop.pngnew file mode 100644index 000000000..bf7bbedcdBinary files /dev/null and b/desktop/design/review/2026-10-13-product-privacy/desktop.png differdiff --git a/desktop/design/review/2026-10-13-product-privacy/phone.png b/desktop/design/review/2026-10-13-product-privacy/phone.pngnew file mode 100644index 000000000..9a5614f54Binary files /dev/null and b/desktop/design/review/2026-10-13-product-privacy/phone.png differdiff --git a/desktop/lib/api/api_client.dart b/desktop/lib/api/api_client.dartindex 2bcff60d4..1964a35df 100644--- a/desktop/lib/api/api_client.dart+++ b/desktop/lib/api/api_client.dart@@ -107,6 +107,26 @@ class ApiClient {}// -- auth (proxied by the local CLI — no credential on this leg) --+ Future<void> productUsageFeedback(String answer, String receipt) async {+ final response = await _dio.post(+ '/api/product-usage/feedback',+ data: {'answer': answer, 'id': receipt},+ options: Options(headers: {'x-adapter-local': '1'}),+ );+ final result = unwrapApiResponse(response);+ if (result is! Map || result['accepted'] != true) {+ throw StateError('Feedback was not accepted');+ }+ }++ Future<Map<String, dynamic>> productUsageSettings({bool? enabled}) async {+ final response = enabled == null+ ? await _dio.get('/api/product-usage/settings')+ : await _dio.post('/api/product-usage/settings', data: {'enabled': enabled},+ options: Options(headers: {'x-adapter-local': '1'}));+ return Map<String, dynamic>.from(unwrapApiResponse(response) as Map);+ }+Future<Map<String, dynamic>?> me() async {final res = await _dio.get('/api/auth/me');return unwrapApiResponse(res) as Map<String, dynamic>?;diff --git a/desktop/lib/settings/sections/privacy_section.dart b/desktop/lib/settings/sections/privacy_section.dartnew file mode 100644index 000000000..2e2ef6bed--- /dev/null+++ b/desktop/lib/settings/sections/privacy_section.dart@@ -0,0 +1,164 @@+import 'package:flutter/material.dart';++import '../../shared/widgets/section_scaffold.dart';+import '../../shared/widgets/setting_row.dart';+import '../../shared/widgets/product_feedback.dart';+import '../../state/app_state.dart';++typedef UsagePreferenceRequest = Future<Map<String, dynamic>> Function({+ bool? enabled,+});++class PrivacySection extends StatelessWidget {+ const PrivacySection({super.key, required this.notifier});+ final AppNotifier notifier;++ @override+ Widget build(BuildContext context) => ListenableBuilder(+ listenable: notifier,+ builder: (context, _) => SectionScaffold(+ title: 'Privacy',+ subtitle: 'Choose what you share to help improve Harness.',+ child: notifier.isGuest+ ? const Text(+ 'No product usage reports are sent while you’re signed out.',+ )+ : ProductUsagePreference(+ key: ObjectKey(notifier.api),+ request: notifier.api.productUsageSettings,+ feedback: notifier.api.productUsageFeedback,+ ),+ ),+ );+}++/// This switch shows the server's saved answer, never an optimistic default.+class ProductUsagePreference extends StatefulWidget {+ const ProductUsagePreference({+ super.key,+ required this.request,+ this.feedback,+ });+ final UsagePreferenceRequest request;+ final ProductFeedbackRequest? feedback;++ @override+ State<ProductUsagePreference> createState() => _ProductUsagePreferenceState();+}++class _ProductUsagePreferenceState extends State<ProductUsagePreference> {+ bool? _enabled;+ bool _busy = true, _details = false;+ String? _error;++ @override+ void initState() {+ super.initState();+ _read();+ }++ Future<void> _read({bool? enabled}) async {+ setState(() {+ _busy = true;+ _error = null;+ });+ try {+ final result = await widget.request(enabled: enabled);+ if (!mounted) return;+ if (result['enabled'] is! bool) throw const FormatException();+ setState(() {+ _enabled = result['enabled'] as bool;+ });+ } catch (_) {+ if (mounted) {+ setState(() {+ _error = enabled == null+ ? 'Couldn’t load this setting. Update Harness or try again.'+ : 'Couldn’t confirm the change. Reload to check your saved setting.';+ // An ambiguous write must not leave a switch claiming the old value is still saved.+ if (enabled != null) _enabled = null;+ });+ }+ } finally {+ if (mounted) {+ setState(() {+ _busy = false;+ });+ }+ }+ }++ @override+ Widget build(BuildContext context) => SingleChildScrollView(+ child: Column(+ crossAxisAlignment: CrossAxisAlignment.stretch,+ children: [+ SettingRow(+ title: 'Share product usage data',+ detail:+ 'Help improve Harness by sharing usage counts and duration statistics. '+ 'Your prompts, code, files, and conversations are never included.',+ controlSemanticLabel: 'Share product usage data',+ control: _enabled == null+ ? _busy+ ? const SizedBox.square(+ dimension: 20,+ child: CircularProgressIndicator(strokeWidth: 2),+ )+ : const Text('Unavailable')+ : Switch(+ value: _enabled!,+ onChanged: _busy ? null : (value) => _read(enabled: value),+ ),+ footer: const Text(+ 'Applies to every computer and app signed in to this account. '+ 'Turning this off stops new product usage reports. Essential service and security records are separate.',+ ),+ ),+ if (_error != null) ...[+ const SizedBox(height: 12),+ Text(_error!),+ Align(+ alignment: Alignment.centerLeft,+ child: TextButton(+ onPressed: _busy ? null : () => _read(),+ child: const Text('Reload'),+ ),+ ),+ ],+ Align(+ alignment: Alignment.centerLeft,+ child: TextButton(+ onPressed: () => setState(() {+ _details = !_details;+ }),+ child: Text(_details ? 'Hide shared fields' : 'See what’s shared'),+ ),+ ),+ if (_enabled == true && widget.feedback != null)+ ProductFeedback(send: widget.feedback!),+ if (_details)+ const SelectableText(+ 'Shared fields\n'+ '• UTC day and a random report receipt to prevent duplicate counts\n'+ '• Active and working computer counts; first and repeat work\n'+ '• Desktop and terminal app opens\n'+ '• Agent turns started, ended, or interrupted (including automated work)\n'+ '• Turn durations: under 10 seconds, 10–60 seconds, 1–5 minutes, or over 5 minutes\n'+ '• Launch, resume, restart, model change and history request outcomes, fixed failure categories and wait buckets\n'+ '• First response waits, missing responses and error-event counts; first-launch 24-hour response counts and D1/D7 working-day returns\n'+ '• A fixed feedback answer only when you choose to send one\n'+ '• Protocol version and the revision of your sharing preference\n\n'+ 'Older apps contribute connection, remote-session, and turn-start totals. '+ 'These event counts are separate from active computer counts.\n\n'+ 'Sign-in checks your preference. Account, computer, and agent identifiers are not stored '+ 'with the new totals. Queued local counters older than 35 days are discarded when Harness next runs. '+ 'Server retry receipts are scheduled to expire after 36 days; combined totals after 13 months. Background cleanup may lag. '+ 'Combined totals cannot be removed for one person. New reports create no per-person history. '+ 'Previously collected activity records expire after 35 days. '+ 'A turn ending does not tell us whether your task succeeded.',+ ),+ ],+ ),+ );+}diff --git a/desktop/lib/settings/settings_body.dart b/desktop/lib/settings/settings_body.dartindex 6d2bebe61..5160ee4fe 100644--- a/desktop/lib/settings/settings_body.dart+++ b/desktop/lib/settings/settings_body.dart@@ -8,6 +8,7 @@ import 'sections/connectors_section.dart';import 'sections/debug_section.dart';import 'sections/experimental_section.dart';import 'sections/notifications_section.dart';+import 'sections/privacy_section.dart';import 'sections/shortcuts_section.dart';import 'sections/usage_section.dart';import 'settings_section.dart';@@ -38,6 +39,7 @@ class SettingsBody extends StatelessWidget {'Customization opens over the workspace.',),SettingsSection.notifications => const NotificationsSection(),+ SettingsSection.privacy => PrivacySection(notifier: notifier),SettingsSection.experimental => ExperimentalSection(store: experimentalFeatures ?? notifier.experimentalFeatures,),diff --git a/desktop/lib/settings/settings_section.dart b/desktop/lib/settings/settings_section.dartindex bb7c8f924..34e294949 100644--- a/desktop/lib/settings/settings_section.dart+++ b/desktop/lib/settings/settings_section.dart@@ -34,6 +34,7 @@ enum SettingsSection {],),notifications(AppIcons.bell, 'Notifications'),+ privacy(AppIcons.shieldCheck, 'Privacy'),shortcuts(AppIcons.keyboard, 'Keyboard shortcuts'),connectors(AppIcons.plug, 'Connectors'),usage(AppIcons.chartNoAxesColumn, 'Usage'),@@ -118,6 +119,7 @@ const _kSettingsGroups = [// work — and NOT inside it, which is where the alert switch started. A sound is not a look,// and somebody turning one off does not think to look under Appearance for it.SettingsSection.notifications,+ SettingsSection.privacy,SettingsSection.shortcuts,]),// What agents may do with Harness is the account's: Labs ▸ Experimental (owner, 2026-10-12).diff --git a/desktop/lib/shared/widgets/product_feedback.dart b/desktop/lib/shared/widgets/product_feedback.dartnew file mode 100644index 000000000..2f88e6af6--- /dev/null+++ b/desktop/lib/shared/widgets/product_feedback.dart@@ -0,0 +1,101 @@+import 'dart:math';++import 'package:flutter/material.dart';++typedef ProductFeedbackRequest = Future<void> Function(+ String answer,+ String receipt,+);++/// A voluntary, fixed-choice response. It carries no task, account or session context.+class ProductFeedback extends StatefulWidget {+ const ProductFeedback({super.key, required this.send});+ final ProductFeedbackRequest send;+ @override+ State<ProductFeedback> createState() => _ProductFeedbackState();+}++class _ProductFeedbackState extends State<ProductFeedback> {+ static const choices = {+ 'useful': 'Useful',+ 'could_not_finish': 'Couldn’t finish',+ 'slow': 'Slow',+ 'confusing': 'Confusing',+ 'missing_feature': 'Missing a feature',+ };+ final String _receipt = _newReceipt();+ String? _answer, _status;+ bool _busy = false, _sent = false;++ static String _newReceipt() {+ final random = Random.secure();+ final bytes = List.generate(16, (_) => random.nextInt(256));+ bytes[6] = (bytes[6] & 15) | 64;+ bytes[8] = (bytes[8] & 63) | 128;+ final h = bytes.map((b) => b.toRadixString(16).padLeft(2, '0')).join();+ return '${h.substring(0, 8)}-${h.substring(8, 12)}-${h.substring(12, 16)}-${h.substring(16, 20)}-${h.substring(20)}';+ }++ Future<void> _send(String answer) async {+ setState(() {+ _busy = true;+ _answer = answer;+ _status = null;+ });+ try {+ await widget.send(answer, _receipt);+ if (mounted) {+ setState(() {+ _sent = true;+ _status = 'Feedback sent. Thank you.';+ });+ }+ } catch (_) {+ if (mounted) {+ setState(() {+ _status = 'Couldn’t confirm receipt. You can retry the same answer.';+ });+ }+ } finally {+ if (mounted) {+ setState(() {+ _busy = false;+ });+ }+ }+ }++ @override+ Widget build(BuildContext context) => Padding(+ padding: const EdgeInsets.only(top: 20),+ child: Column(+ crossAxisAlignment: CrossAxisAlignment.start,+ children: [+ Text(+ 'How did your latest task go?',+ style: Theme.of(context).textTheme.titleSmall,+ ),+ const SizedBox(height: 8),+ const Text(+ 'Optional feedback. Select an answer to share only that choice, without your task or its contents.',+ ),+ const SizedBox(height: 8),+ Wrap(+ spacing: 8,+ runSpacing: 4,+ children: [+ for (final choice in choices.entries)+ OutlinedButton(+ onPressed:+ _busy || _sent || (_answer != null && _answer != choice.key)+ ? null+ : () => _send(choice.key),+ child: Text(choice.value),+ ),+ ],+ ),+ if (_status != null) Text(_status!),+ ],+ ),+ );+}diff --git a/desktop/test/privacy_section_test.dart b/desktop/test/privacy_section_test.dartnew file mode 100644index 000000000..1456e631b--- /dev/null+++ b/desktop/test/privacy_section_test.dart@@ -0,0 +1,81 @@+import 'dart:async';++import 'package:flutter/material.dart';+import 'package:flutter_test/flutter_test.dart';+import 'package:harness/settings/sections/privacy_section.dart';++void main() {+ Future<void> show(WidgetTester tester, UsagePreferenceRequest request) async {+ await tester.pumpWidget(+ MaterialApp(+ home: Scaffold(+ body: ProductUsagePreference(+ request: request,+ feedback: (_, _) async {},+ ),+ ),+ ),+ );+ await tester.pumpAndSettle();+ }++ testWidgets(+ 'shows the saved preference and turns sharing off for the account',+ (tester) async {+ final changes = <bool>[];+ await show(tester, ({bool? enabled}) async {+ if (enabled != null) changes.add(enabled);+ return {'enabled': enabled ?? true, 'revision': 1};+ });+ expect(tester.widget<Switch>(find.byType(Switch)).value, isTrue);+ expect(find.text('How did your latest task go?'), findsOneWidget);+ await tester.tap(find.byType(Switch));+ await tester.pumpAndSettle();+ expect(changes, [false]);+ expect(tester.widget<Switch>(find.byType(Switch)).value, isFalse);+ expect(find.text('How did your latest task go?'), findsNothing);+ expect(find.textContaining('every computer and app'), findsOneWidget);+ await tester.tap(find.text('See what’s shared'));+ await tester.pumpAndSettle();+ expect(find.textContaining('random report receipt'), findsOneWidget);+ expect(+ find.textContaining('does not tell us whether your task succeeded'),+ findsOneWidget,+ );+ },+ );+ testWidgets(+ 'does not pretend an ambiguous save succeeded or retained its old value',+ (tester) async {+ await show(tester, ({bool? enabled}) async {+ if (enabled != null) throw StateError('PRIVATE_CANARY');+ return {'enabled': true};+ });+ await tester.tap(find.byType(Switch));+ await tester.pumpAndSettle();+ expect(find.byType(Switch), findsNothing);+ expect(find.text('Unavailable'), findsOneWidget);+ expect(find.textContaining('Couldn’t confirm'), findsOneWidget);+ expect(find.textContaining('PRIVATE_CANARY'), findsNothing);+ },+ );+ testWidgets('keeps the control unavailable until a real preference arrives', (+ tester,+ ) async {+ final pending = Completer<Map<String, dynamic>>();+ await tester.pumpWidget(+ MaterialApp(+ home: Scaffold(+ body: ProductUsagePreference(+ request: ({bool? enabled}) => pending.future,+ ),+ ),+ ),+ );+ await tester.pump();+ expect(find.byType(Switch), findsNothing);+ pending.complete({'enabled': false});+ await tester.pumpAndSettle();+ expect(tester.widget<Switch>(find.byType(Switch)).value, isFalse);+ });+}diff --git a/desktop/test/product_feedback_test.dart b/desktop/test/product_feedback_test.dartnew file mode 100644index 000000000..45df24f1a--- /dev/null+++ b/desktop/test/product_feedback_test.dart@@ -0,0 +1,51 @@+import 'package:flutter/material.dart';+import 'package:flutter_test/flutter_test.dart';+import 'package:harness/shared/widgets/product_feedback.dart';++void main() {+ testWidgets(+ 'voluntary feedback sends only a fixed answer and retries the same receipt',+ (tester) async {+ final calls = <List<String>>[];+ await tester.pumpWidget(+ MaterialApp(+ home: Scaffold(+ body: ProductFeedback(+ send: (answer, receipt) async {+ calls.add([answer, receipt]);+ if (calls.length == 1) throw StateError('PRIVATE_CANARY');+ },+ ),+ ),+ ),+ );+ expect(calls, isEmpty);+ await tester.tap(find.text('Useful'));+ await tester.pumpAndSettle();+ expect(find.textContaining('PRIVATE_CANARY'), findsNothing);+ expect(find.textContaining('Couldn’t confirm'), findsOneWidget);+ await tester.tap(find.text('Useful'));+ await tester.pumpAndSettle();+ expect(calls.length, 2);+ expect(calls[0], calls[1]);+ expect(calls[0][0], 'useful');+ expect(+ calls[0][1],+ matches(+ RegExp(+ r'^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$',+ ),+ ),+ );+ expect(find.text('Feedback sent. Thank you.'), findsOneWidget);+ expect(+ tester+ .widget<OutlinedButton>(+ find.widgetWithText(OutlinedButton, 'Useful'),+ )+ .onPressed,+ isNull,+ );+ },+ );+}diff --git a/desktop/test/settings_section_test.dart b/desktop/test/settings_section_test.dartindex 75c84d582..43e529d37 100644--- a/desktop/test/settings_section_test.dart+++ b/desktop/test/settings_section_test.dart@@ -30,6 +30,7 @@ void main() {SettingsSection.account,SettingsSection.customize,SettingsSection.notifications,+ SettingsSection.privacy,SettingsSection.shortcuts,// What agents may do is the account's, under Experimental (owner, 2026-10-12).if (!kIsWeb) SettingsSection.connectors,@@ -56,6 +57,7 @@ void main() {[SettingsSection.customize,SettingsSection.notifications,+ SettingsSection.privacy,SettingsSection.shortcuts,],[if (!kIsWeb) SettingsSection.connectors, SettingsSection.usage],diff --git a/docs/product-measurement.md b/docs/product-measurement.mdnew file mode 100644index 000000000..f11d1b022--- /dev/null+++ b/docs/product-measurement.md@@ -0,0 +1,87 @@+# Product measurement and the daily improvement review++We use aggregated product signals to decide what to reproduce, fix and measure next. We do not+inspect people's work to explain a count, and a daily review does not imply a daily release or an+automatically proven improvement. Changes still need review, tests and a deliberate release.++## Measurements and their limits++| Question | Signal | Interpretation |+| --- | --- | --- |+| Does first measured use lead to work? | First-launch installation cohorts; work and first text response within 24 hours | Same participating installation, not signup conversion, same-task success or unique people. Existing users enter when updated; mature only after the full follow-up day ends. |+| Where does a launch stall or fail? | Pending install/model/native waits; observed launch created/failed/cancelled/unconfirmed; fixed failure categories and duration buckets | Polls are not attempts. Missing outcomes, daemon restarts and the 15-minute observation bound reduce coverage. Inspect unknowns alongside failures. |+| Which actions break? | Create, resume, restart, model-change and history requests, fixed outcomes/errors and latency buckets | Request acceptance is not task success. Pending/unknown requests are separate from completed replies. |+| Does work get a response promptly? | First text response buckets; over-one-minute waits; error events; matched ends without text; interruptions | Includes automation. Tool-only turns, interruptions and missing lifecycle events can explain missing text. No message is inspected. |+| Do installations return to work? | D1/D7 working-day cohorts and consecutive complete-week returns | Any working day can be a cohort; not new-signup retention. Local date flags produce unlinked totals. Opt-outs, reinstallations, resets and missing uploads affect results. |+| Was the task useful? | Optional five-choice feedback in Privacy settings | Voluntary and self-selected; not representative success or satisfaction. There is no free-text input. |+| Is there usage at all? | Active and working computer counts; app opens; older-client relay totals | Background windows can count as active. Relay events are not distinct people; the populations must not be added together. |++Pre-sign-in setup and sign-in abandonment remain unobserved. Signed-out clients send no product+reports. Reproduce those paths with test accounts and synthetic inputs. No screen recordings,+click trails, stable analytics identifiers, locations, content or arbitrary properties are added.+The exact counter vocabulary is in [productUsage.ts](../backend/src/types/productUsage.ts).++Reports combine participating signed-in installations, including staff and both environments.+They are not all-user counts and are not directly comparable with earlier account-cohort reports+or industry retention benchmarks. No per-person analytics history or joining key is stored.+Authenticated requests still reach the service; infrastructure request logs and backups have their+own retention, which the release owner must verify separately. The account preference remains+linked to the account so the switch works everywhere.++## Each daily review++1. Run `cd backend && npm run usage:daily -- 14` with a read-only `DATABASE_URL` supplied through the+ environment. Keep output in ignored `.harness/usage/`; never commit credentials or production+ exports. The command reads only allowlisted aggregate rows, performs no writes, and uses UTC days.+2. Check collection coverage, missing days, unknown outcomes and participating-installation counts+ before interpreting a rate. Preserve the numerator and denominator. Today is partial; late+ reports can change earlier days. A 24-hour first check can catch friction; D7 cannot mature in a day.+3. Pick one product problem together. Record a hypothesis, target metric, guardrails, observation+ window, release commit/time and expected result **before** implementing it. Keep fixed cohorts+ and equal-length periods; do not select a favorable window after seeing the outcome.+4. Reproduce with synthetic inputs. Profile or benchmark a fixed workload on the same machine and+ toolchain before and after. Add a regression test for the behavior and check failures recover.+ In production compare reliability and wait buckets, not captured user errors or work.+5. Review and release. Record rollout boundaries outside the analytics data; do not infer exposure+ from a global date alone. Allow enough time for adoption and the selected follow-up window.+6. Compare the report's complete seven-day windows and mature cohorts. Repeated work is not+ independent sampling. A change in client adoption or participation can change a rate without a+ product effect. With little data, record "inconclusive" and the next observation date. Keep, revise+ or revert together; do not claim causality from a before/after count.++A review record can use this compact shape (no user or task identifiers):++```text+Question / hypothesis:+Synthetic reproduction and benchmark:+Primary metric / numerator / denominator:+Guardrails: launch failures, unknown outcomes, response waits, interruptions, privacy choice+Baseline dates / follow-up dates / cohort maturity:+Released commit / UTC rollout time / overlapping changes:+Observed coverage and uncertainty:+Decision: keep | revise | revert | inconclusive+Next review date:+```++The `review` output proposes investigations, not code changes or automatic deployments. Feedback+is one source of evidence; a missing response does not identify why a person stopped using Harness.++## Rollout and privacy controls++Deploy backend schema and the singleton worker first, including unique indexes and TTL indexes.+Use synthetic data to verify duplicate receipts, transaction rollback/retry, off/on revision fencing+and expiry. Then release CLI, desktop and phone together. Check that the switch saves and that reports+stop when it is off. Old clients stop contributing individual daily histories when the backend changes;+the historical reporting command will no longer be a current-usage source.++Suggested visible release note:++> Harness now shares limited product usage counts by default to help us find broken or slow flows.+> These counts do not include your prompts, responses, code, files or project details. Turn sharing+> off for your account in Settings → Privacy → Share product usage data, or use `harness privacy off`.+> Existing opt-outs stay off. Optional feedback sends only the answer you choose.++Sharing off prevents subsequent admission of new reports and clears local queues at the next+successful preference check. An already admitted operation may finish. Combined totals cannot be+removed for one person because they have no identity link. The [backend guide](../backend/README.md#product-usage-with-an-account-wide-privacy-control)+documents queue bounds, retention, legacy deletion and the separate infrastructure checks.diff --git a/mobile/lib/api/api_client.dart b/mobile/lib/api/api_client.dartindex 5d77cf9e0..84025a81a 100644--- a/mobile/lib/api/api_client.dart+++ b/mobile/lib/api/api_client.dart@@ -15,6 +15,24 @@ import 'multipart_body.dart';/// Authenticated control-plane REST client for the phone.class ApiClient {+ Future<void> productUsageFeedback(String answer, String receipt) async {+ final response = await _dio.post(+ '/api/product-usage/feedback',+ data: {'answer': answer, 'id': receipt},+ );+ final result = unwrapApiResponse(response);+ if (result is! Map || result['accepted'] != true) {+ throw StateError('Feedback was not accepted');+ }+ }++ Future<Map<String, dynamic>> productUsageSettings({bool? enabled}) async {+ final response = enabled == null+ ? await _dio.get('/api/product-usage/settings')+ : await _dio.post('/api/product-usage/settings', data: {'enabled': enabled});+ return Map<String, dynamic>.from(unwrapApiResponse(response) as Map);+ }+final AppConfig config;final AuthSession session;final AccessTokenSource? auth;diff --git a/mobile/lib/phone/privacy_page.dart b/mobile/lib/phone/privacy_page.dartnew file mode 100644index 000000000..1015f7a59--- /dev/null+++ b/mobile/lib/phone/privacy_page.dart@@ -0,0 +1,125 @@+import 'package:flutter/material.dart';++import '../shared/widgets/product_feedback.dart';++typedef UsagePreferenceRequest = Future<Map<String, dynamic>> Function({+ bool? enabled,+});++/// Account-wide privacy control, available without a connected computer.+class PrivacyPage extends StatefulWidget {+ const PrivacyPage({super.key, required this.request, this.feedback});+ final UsagePreferenceRequest request;+ final ProductFeedbackRequest? feedback;++ @override+ State<PrivacyPage> createState() => _PrivacyPageState();+}++class _PrivacyPageState extends State<PrivacyPage> {+ bool? _enabled;+ bool _busy = true, _details = false;+ String? _error;++ @override+ void initState() {+ super.initState();+ _read();+ }++ Future<void> _read({bool? enabled}) async {+ setState(() {+ _busy = true;+ _error = null;+ });+ try {+ final result = await widget.request(enabled: enabled);+ if (!mounted) return;+ if (result['enabled'] is! bool) throw const FormatException();+ setState(() {+ _enabled = result['enabled'] as bool;+ });+ } catch (_) {+ if (mounted) {+ setState(() {+ _error = enabled == null ? 'Couldn’t load this setting. Try again.' : 'Couldn’t confirm the change. Reload to check your saved setting.';+ if (enabled != null) _enabled = null;+ });+ }+ } finally {+ if (mounted) {+ setState(() {+ _busy = false;+ });+ }+ }+ }++ @override+ Widget build(BuildContext context) => Scaffold(+ appBar: AppBar(title: const Text('Privacy')),+ body: ListView(+ padding: const EdgeInsets.all(20),+ children: [+ if (_enabled == null)+ ListTile(+ contentPadding: EdgeInsets.zero,+ title: const Text('Share product usage data'),+ subtitle: Text(+ _busy ? 'Checking your saved preference…' : 'Setting unavailable',+ ),+ )+ else+ SwitchListTile.adaptive(+ contentPadding: EdgeInsets.zero,+ title: const Text('Share product usage data'),+ subtitle: const Text(+ 'Help improve Harness by sharing usage counts and duration statistics. '+ 'Your prompts, code, files, and conversations are never included.',+ ),+ value: _enabled!,+ onChanged: _busy ? null : (value) => _read(enabled: value),+ ),+ if (_busy) const LinearProgressIndicator(),+ const SizedBox(height: 12),+ const Text(+ 'Applies to every computer and app signed in to this account. '+ 'Turning this off stops new product usage reports. Essential service and security records are separate.',+ ),+ if (_error != null) ...[+ const SizedBox(height: 12),+ Text(_error!),+ TextButton(+ onPressed: _busy ? null : () => _read(),+ child: const Text('Reload'),+ ),+ ],+ TextButton(+ onPressed: () => setState(() {+ _details = !_details;+ }),+ child: Text(_details ? 'Hide shared fields' : 'See what’s shared'),+ ),+ if (_enabled == true && widget.feedback != null)+ ProductFeedback(send: widget.feedback!),+ if (_details)+ const Text(+ 'Shared fields: UTC day, a random retry receipt, protocol and preference revisions; '+ 'active/working computer counts, first/repeat work, desktop/terminal opens, '+ 'turns started/ended/interrupted (including automation), and duration buckets '+ '(under 10 seconds, 10–60 seconds, 1–5 minutes, over 5 minutes). '+ 'Also: request outcomes and fixed failure categories for launch/resume/restart/model changes/history, '+ 'response wait buckets, missing responses and error-event counts, and first-launch 24-hour response counts and D1/D7 working-day returns. '+ 'Feedback is a fixed answer sent only when you choose one. '+ 'Older apps contribute connection, remote-session and turn-start totals separately.\n\n'+ 'Sign-in checks your preference. Account, computer and agent identifiers are not stored '+ 'with new totals. Queued local counters older than 35 days are discarded when Harness next runs. '+ 'Server retry receipts are scheduled to expire after 36 days; combined totals after 13 months. Background cleanup may lag. '+ 'Combined totals cannot be removed for one person. '+ 'Previously collected activity records expire after 35 days. '+ 'A turn ending does not establish task success.',+ ),+ ],+ ),+ );+}diff --git a/mobile/lib/phone/settings_page.dart b/mobile/lib/phone/settings_page.dartindex 8740e30b0..558040efe 100644--- a/mobile/lib/phone/settings_page.dart+++ b/mobile/lib/phone/settings_page.dart@@ -23,6 +23,7 @@ import 'phone_navigation.dart' show phoneRoute;import 'phone_name_store.dart';import 'phone_sheet.dart';import 'settings_row.dart';+import 'privacy_page.dart';import 'welcome/how_it_works.dart';import 'welcome/focus_hints.dart';import 'tty_controls.dart';@@ -162,6 +163,10 @@ class _Body extends StatelessWidget {// alone, and that is deliberate: it is the only row here anybody opens twice.// No Stats row: counters this app keeps about itself are nobody's daily question.buildUsageSettingsRow(context, notifier),+ if (_sample(context) == null)+ SettingsRow(title: 'Privacy', onTap: () => Navigator.of(context).push(+ phoneRoute((_) => PrivacyPage(request: notifier.api.productUsageSettings, feedback: notifier.api.productUsageFeedback)),+ )),// The computers this phone reaches — here rather than a menu of their own: linking one is// a once-a-while errand, and Find already reaches every agent on them.SettingsRow(diff --git a/mobile/lib/shared/widgets/product_feedback.dart b/mobile/lib/shared/widgets/product_feedback.dartnew file mode 100644index 000000000..2f88e6af6--- /dev/null+++ b/mobile/lib/shared/widgets/product_feedback.dart@@ -0,0 +1,101 @@+import 'dart:math';++import 'package:flutter/material.dart';++typedef ProductFeedbackRequest = Future<void> Function(+ String answer,+ String receipt,+);++/// A voluntary, fixed-choice response. It carries no task, account or session context.+class ProductFeedback extends StatefulWidget {+ const ProductFeedback({super.key, required this.send});+ final ProductFeedbackRequest send;+ @override+ State<ProductFeedback> createState() => _ProductFeedbackState();+}++class _ProductFeedbackState extends State<ProductFeedback> {+ static const choices = {+ 'useful': 'Useful',+ 'could_not_finish': 'Couldn’t finish',+ 'slow': 'Slow',+ 'confusing': 'Confusing',+ 'missing_feature': 'Missing a feature',+ };+ final String _receipt = _newReceipt();+ String? _answer, _status;+ bool _busy = false, _sent = false;++ static String _newReceipt() {+ final random = Random.secure();+ final bytes = List.generate(16, (_) => random.nextInt(256));+ bytes[6] = (bytes[6] & 15) | 64;+ bytes[8] = (bytes[8] & 63) | 128;+ final h = bytes.map((b) => b.toRadixString(16).padLeft(2, '0')).join();+ return '${h.substring(0, 8)}-${h.substring(8, 12)}-${h.substring(12, 16)}-${h.substring(16, 20)}-${h.substring(20)}';+ }++ Future<void> _send(String answer) async {+ setState(() {+ _busy = true;+ _answer = answer;+ _status = null;+ });+ try {+ await widget.send(answer, _receipt);+ if (mounted) {+ setState(() {+ _sent = true;+ _status = 'Feedback sent. Thank you.';+ });+ }+ } catch (_) {+ if (mounted) {+ setState(() {+ _status = 'Couldn’t confirm receipt. You can retry the same answer.';+ });+ }+ } finally {+ if (mounted) {+ setState(() {+ _busy = false;+ });+ }+ }+ }++ @override+ Widget build(BuildContext context) => Padding(+ padding: const EdgeInsets.only(top: 20),+ child: Column(+ crossAxisAlignment: CrossAxisAlignment.start,+ children: [+ Text(+ 'How did your latest task go?',+ style: Theme.of(context).textTheme.titleSmall,+ ),+ const SizedBox(height: 8),+ const Text(+ 'Optional feedback. Select an answer to share only that choice, without your task or its contents.',+ ),+ const SizedBox(height: 8),+ Wrap(+ spacing: 8,+ runSpacing: 4,+ children: [+ for (final choice in choices.entries)+ OutlinedButton(+ onPressed:+ _busy || _sent || (_answer != null && _answer != choice.key)+ ? null+ : () => _send(choice.key),+ child: Text(choice.value),+ ),+ ],+ ),+ if (_status != null) Text(_status!),+ ],+ ),+ );+}diff --git a/mobile/test/privacy_page_test.dart b/mobile/test/privacy_page_test.dartnew file mode 100644index 000000000..db33783f9--- /dev/null+++ b/mobile/test/privacy_page_test.dart@@ -0,0 +1,54 @@+import 'package:flutter/material.dart';+import 'package:flutter_test/flutter_test.dart';+import 'package:harness_mobile/phone/privacy_page.dart';++void main() {+ testWidgets('the phone can turn off sharing for the whole account', (+ tester,+ ) async {+ final changes = <bool>[];+ await tester.pumpWidget(+ MaterialApp(+ home: PrivacyPage(+ feedback: (_, _) async {},+ request: ({bool? enabled}) async {+ if (enabled != null) changes.add(enabled);+ return {'enabled': enabled ?? true};+ },+ ),+ ),+ );+ await tester.pumpAndSettle();+ expect(find.text('How did your latest task go?'), findsOneWidget);+ await tester.tap(find.byType(Switch));+ await tester.pumpAndSettle();+ expect(changes, [false]);+ expect(find.text('How did your latest task go?'), findsNothing);+ expect(find.textContaining('every computer and app'), findsOneWidget);+ await tester.tap(find.text('See what’s shared'));+ await tester.pumpAndSettle();+ expect(find.textContaining('random retry receipt'), findsOneWidget);+ });+ testWidgets(+ 'a failed write leaves an unavailable switch and a reload action',+ (tester) async {+ await tester.pumpWidget(+ MaterialApp(+ home: PrivacyPage(+ request: ({bool? enabled}) async {+ if (enabled != null) throw StateError('PRIVATE_CANARY');+ return {'enabled': true};+ },+ ),+ ),+ );+ await tester.pumpAndSettle();+ await tester.tap(find.byType(Switch));+ await tester.pumpAndSettle();+ expect(find.byType(Switch), findsNothing);+ expect(find.text('Setting unavailable'), findsOneWidget);+ expect(find.text('Reload'), findsOneWidget);+ expect(find.textContaining('PRIVATE_CANARY'), findsNothing);+ },+ );+}diff --git a/mobile/test/product_feedback_test.dart b/mobile/test/product_feedback_test.dartnew file mode 100644index 000000000..a5ecb3e94--- /dev/null+++ b/mobile/test/product_feedback_test.dart@@ -0,0 +1,51 @@+import 'package:flutter/material.dart';+import 'package:flutter_test/flutter_test.dart';+import 'package:harness_mobile/shared/widgets/product_feedback.dart';++void main() {+ testWidgets(+ 'voluntary feedback sends only a fixed answer and retries the same receipt',+ (tester) async {+ final calls = <List<String>>[];+ await tester.pumpWidget(+ MaterialApp(+ home: Scaffold(+ body: ProductFeedback(+ send: (answer, receipt) async {+ calls.add([answer, receipt]);+ if (calls.length == 1) throw StateError('PRIVATE_CANARY');+ },+ ),+ ),+ ),+ );+ expect(calls, isEmpty);+ await tester.tap(find.text('Useful'));+ await tester.pumpAndSettle();+ expect(find.textContaining('PRIVATE_CANARY'), findsNothing);+ expect(find.textContaining('Couldn’t confirm'), findsOneWidget);+ await tester.tap(find.text('Useful'));+ await tester.pumpAndSettle();+ expect(calls.length, 2);+ expect(calls[0], calls[1]);+ expect(calls[0][0], 'useful');+ expect(+ calls[0][1],+ matches(+ RegExp(+ r'^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$',+ ),+ ),+ );+ expect(find.text('Feedback sent. Thank you.'), findsOneWidget);+ expect(+ tester+ .widget<OutlinedButton>(+ find.widgetWithText(OutlinedButton, 'Useful'),+ )+ .onPressed,+ isNull,+ );+ },+ );+}