Skip to content

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.

Measure product activation, friction and retention with privacy controls (#1301)

Deece68e2fac27b
diff --git a/backend/README.md b/backend/README.md
index 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 — `p
startup). The backend owns the `users` + `agent_bindings` collections; it never manages the
manager-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 country
changes. 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 the
daily 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 nothing
is 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.json
index 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.prisma
index 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.ObjectId
userId 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`, while
diff --git a/backend/src/analytics/dailyProductReview.test.ts b/backend/src/analytics/dailyProductReview.test.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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_000
const 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.ts
index 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, minInterva
return 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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?.sub
if (!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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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 CLI
await app.register(jevRouteRoutes, { count: redisCount }) // ⌘B's Jev decisions on Harness's key, for people with none of their own
await 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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 = null
readonly 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() } }))
return
diff --git a/cli/e2e/privacyCommand.e2e.ts b/cli/e2e/privacyCommand.e2e.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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 account
harness start start the adapter using the saved SSO session
harness start -f run the daemon in the FOREGROUND (for a supervisor; logs to stdout): harnessd's
master, 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(VERS
switch (cmd) {
+ case 'privacy':
+ privacyCommand(args[0], flags.includes('--json')).catch(onError)
+ break
case 'send':
sendCommand(rest).then(code => { process.exitCode = code }).catch(onError)
break
diff --git a/cli/src/core/api.ts b/cli/src/core/api.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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: string
try { 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: Response
try {
res = await request(`${(deps.base ?? backendHttpBase)()}${path}`, {
diff --git a/cli/src/gateway/gateway.spec.ts b/cli/src/gateway/gateway.spec.ts
index 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.ts
index 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: E2eeManager
readonly 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()) return
this.link.enqueue({ t: 'up', frame: this.e2ee.wrapUp(frame) })
}
diff --git a/cli/src/gateway/gatewayProcess.spec.ts b/cli/src/gateway/gatewayProcess.spec.ts
index 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: S
function 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.ts
index 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): ServiceProces
const { port, ops } = gateway
const connId = text(payload.connId)
switch (kind) {
+ case 'usageLaunch': port.usageLaunch?.(payload.signal as ProductUsageLaunchSignal); return
+ case 'usageCounter': port.usageCounter?.(payload.metric as ProductUsageMetric); return
case 'connect': port.connect(); return
case 'thisComputerOnly': port.serveThisComputerOnly(); return
case 'hold': port.holdRequests(); return
diff --git a/cli/src/gateway/productUsage.spec.ts b/cli/src/gateway/productUsage.spec.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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 = next
startGroup()
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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.png
new file mode 100644
index 000000000..bf7bbedcd
Binary files /dev/null and b/desktop/design/review/2026-10-13-product-privacy/desktop.png differ
diff --git a/desktop/design/review/2026-10-13-product-privacy/phone.png b/desktop/design/review/2026-10-13-product-privacy/phone.png
new file mode 100644
index 000000000..9a5614f54
Binary files /dev/null and b/desktop/design/review/2026-10-13-product-privacy/phone.png differ
diff --git a/desktop/lib/api/api_client.dart b/desktop/lib/api/api_client.dart
index 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.dart
new file mode 100644
index 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.dart
index 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.dart
index 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.dart
new file mode 100644
index 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.dart
new file mode 100644
index 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.dart
new file mode 100644
index 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.dart
index 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.md
new file mode 100644
index 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.dart
index 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.dart
new file mode 100644
index 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.dart
index 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.dart
new file mode 100644
index 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.dart
new file mode 100644
index 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.dart
new file mode 100644
index 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,
+ );
+ },
+ );
+}