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.

Expand privacy-preserving product measurement and bound reporting cost (#1303)

Dee17ee12593c34
diff --git a/backend/README.md b/backend/README.md
index 52e992caa..9787393b7 100644
--- a/backend/README.md
+++ b/backend/README.md
@@ -294,3 +294,13 @@ activity, not proven inactivity. In particular, do not compare new surface instr
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.
+
+
+The expanded measurement contract adds fixed app-flow and feature-use counts, D28 and calendar-month
+installation returns, and voluntary task outcomes. Native signed-out setup is a separate explicit
+session opt-in at `POST /api/product-usage/setup`; it rejects credentials and arbitrary fields and
+has a process-wide admission budget without storing IP addresses. Web signed-out reporting is disabled.
+Daily reports keep these populations separate, show unmatched outcomes and measurement loss, and
+compare only mature periods. See [measurement definitions and runtime bounds](../docs/product-measurement.md).
+Deploy this additive allowlist before releasing the new clients. This change does not add identity
+markers or make installation counts comparable to people-based DAU or retention benchmarks.
diff --git a/backend/src/analytics/dailyProductReview.test.ts b/backend/src/analytics/dailyProductReview.test.ts
index efaba0daf..7ca6b14a3 100644
--- a/backend/src/analytics/dailyProductReview.test.ts
+++ b/backend/src/analytics/dailyProductReview.test.ts
@@ -44,3 +44,30 @@ it('compares first-launch installation cohorts only after every 24-hour window c
expect(r.firstLaunchCohorts.cohorts.some(c => c.day === '2026-10-12')).toBe(false)
expect(r.firstLaunchCohorts.cohorts[0].observedResponsePercent).toBeNull()
})
+
+it('keeps feedback denominators and setup coverage separate from daemon participation', () => {
+ const r = dailyProductReview([
+ row('2026-10-12', 'feedback_useful', 2), row('2026-10-12', 'feedback_completed', 3), row('2026-10-12', 'feedback_not_completed', 1),
+ row('2026-10-12', 'setup_desktop_sign_in_started', 5), row('2026-10-12', 'setup_desktop_sign_in_ok', 2),
+ ], new Date('2026-10-13'))
+ expect(r.comparisons.find(c => c.name.startsWith('Useful'))?.current.denominator).toBe(2)
+ expect(r.comparisons.find(c => c.name.startsWith('Completed'))?.current).toMatchObject({ denominator: 4, percent: 75 })
+ expect(r.recent.observedDays).toBe(0)
+ expect(r.flows.find(f => f.channel === 'setup' && f.surface === 'desktop' && f.flow === 'sign_in')).toMatchObject({ started: 5, unmatchedStarts: 3 })
+ expect(r.flows.find(f => f.channel === 'ui' && f.flow === 'update_stage')?.started).toBeNull()
+})
+it('uses complete calendar months rather than adding daily installations into MAU', () => {
+ const r = dailyProductReview([
+ row('2026-08-12', 'monthly_working_installations', 10), row('2026-09-12', 'monthly_working_installations', 8),
+ row('2026-09-12', 'monthly_returning_installations', 6), row('2026-10-12', 'monthly_returning_installations', 99),
+ ], new Date('2026-10-13'))
+ expect(r.monthlyRetention).toMatchObject({ from: '2026-09-01', untilExclusive: '2026-10-01', percent: 60 })
+})
+
+it('does not turn old collector work into zero D28 retention during rollout', () => {
+ const rows = [row('2026-09-14', 'working_installation_days', 10), row('2026-10-12', 'working_installation_days', 8)]
+ const cohort = (input: typeof rows) => dailyProductReview(input, new Date('2026-10-14')).retention[2].cohorts.find(c => c.day === '2026-09-14')
+ expect(cohort(rows)).toMatchObject({ measurementAvailable: false, returned: null, percent: null })
+ expect(cohort([...rows, row('2026-09-14', 'measurement_v2_installation_days', 10)]))
+ .toMatchObject({ measurementAvailable: true, returned: 0, percent: 0 })
+})
diff --git a/backend/src/analytics/dailyProductReview.ts b/backend/src/analytics/dailyProductReview.ts
index c1c28892d..ee37f5145 100644
--- a/backend/src/analytics/dailyProductReview.ts
+++ b/backend/src/analytics/dailyProductReview.ts
@@ -1,4 +1,4 @@
-import { PRODUCT_FEEDBACK, PRODUCT_USAGE_ACTIONS } from '../types/productUsage.js'
+import { PRODUCT_FEEDBACK, PRODUCT_FEEDBACK_REASONS, PRODUCT_FEEDBACK_OUTCOMES, PRODUCT_USAGE_ACTIONS, PRODUCT_USAGE_FLOWS, PRODUCT_USAGE_SURFACES } from '../types/productUsage.js'
import { DAILY_PRODUCT_METRICS } from './dailyProductUsage.js'
type Row = { dayUtc: Date; metric: string; value: number }
@@ -22,7 +22,7 @@ export function dailyProductReview(rows: Row[], now: Date) {
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++
+ if ((c.active_installation_days ?? 0) > 0 || (c.working_installation_days ?? 0) > 0 || (c.measurement_v2_installation_days ?? 0) > 0) observedDays++
for (const [k, n] of Object.entries(c)) counters[k] = (counters[k] ?? 0) + n
}
return { from: dayKey(from), untilExclusive: dayKey(until), observedDays, counters }
@@ -47,7 +47,8 @@ export function dailyProductReview(rows: Row[], now: Date) {
['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}`)),
+ comparison('Useful among voluntary feedback responses', ['feedback_useful'], PRODUCT_FEEDBACK_REASONS.map(a => `feedback_${a}`)),
+ comparison('Completed among voluntary task-outcome responses', ['feedback_completed'], PRODUCT_FEEDBACK_OUTCOMES.map(a => `feedback_${a}`)),
...PRODUCT_USAGE_ACTIONS.map(action => comparison(`${action}: request refusal`, [`${action}_failed`], [`${action}_ok`, `${action}_failed`])),
]
const c = recent.counters
@@ -61,18 +62,48 @@ export function dailyProductReview(rows: Row[], now: Date) {
{ 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 retention = [1, 7, 28].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,
+ // Older collectors reported work but had no D28 counter. Their missing metric is unknown, not zero retention.
+ const measurementAvailable = lag !== 28 || (cohort.measurement_v2_installation_days ?? 0) > 0
+ const returned = denominator && followUpObserved && measurementAvailable ? cohort[`d${lag}_returning_work_installations`] ?? 0 : null
+ return { day: dayKey(stamp), workingInstallations: denominator || null, returned, measurementAvailable,
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 }
})
+ const month = new Date(today)
+ const monthStart = Date.UTC(month.getUTCFullYear(), month.getUTCMonth(), 1)
+ const priorStart = Date.UTC(month.getUTCFullYear(), month.getUTCMonth() - 1, 1)
+ const earlierStart = Date.UTC(month.getUTCFullYear(), month.getUTCMonth() - 2, 1)
+ const completeMonth = window(priorStart, monthStart), previousMonth = window(earlierStart, priorStart)
+ const monthDenominator = previousMonth.counters.monthly_working_installations ?? 0
+ const monthReturn = completeMonth.counters.monthly_returning_installations ?? 0
return {
+ monthlyRetention: { from: completeMonth.from, untilExclusive: completeMonth.untilExclusive,
+ previousWorkingInstallations: monthDenominator || null,
+ returningInstallations: monthDenominator && completeMonth.counters.monthly_working_installations ? monthReturn : null,
+ percent: completeMonth.counters.monthly_working_installations ? rate(monthReturn, monthDenominator) : null,
+ definition: 'Participating installations with work in two consecutive complete UTC calendar months; late uploads and measurement rollout affect coverage.',
+ },
+ flows: ['setup', 'ui'].flatMap(channel => PRODUCT_USAGE_SURFACES.flatMap(surface => PRODUCT_USAGE_FLOWS
+ .filter(flow => channel !== 'setup' || ['setup', 'setup_harness', 'setup_tmux', 'setup_clipboard', 'sign_in'].includes(flow))
+ .map(flow => {
+ const prefix = `${channel}_${surface}_${flow}_`
+ const started = c[`${prefix}started`] ?? null
+ const observed = ['ok', 'failed', 'cancelled', 'unknown'].reduce((n, outcome) => n + (c[`${prefix}${outcome}`] ?? 0), 0)
+ return { channel, surface, flow, started,
+ outcomes: Object.fromEntries(['ok', 'failed', 'cancelled', 'unknown'].map(outcome => [outcome, c[`${prefix}${outcome}`] ?? (started ? 0 : null)])),
+ unmatchedStarts: started === null ? null : Math.max(0, started - observed),
+ durationBuckets: Object.fromEntries(['under_1s', '1s_to_10s', '10s_to_1m', 'over_1m'].map(bucket => [bucket, c[`${prefix}${bucket}`] ?? (started ? 0 : null)])),
+ interpretation: channel === 'setup'
+ ? 'Optional signed-out app-session counts, untrusted and self-selected. No cross-step linkage, unique people or signup conversion. Web pre-sign-in is not collected.'
+ : 'Observed app operations, possibly automatic. Missing outcomes include closed apps, offline reports and choice changes; absence is not failure. Viewer opening is not page rendering; update staging is not successful relaunch.',
+ }
+ }))),
recent: { from: recent.from, untilExclusive: recent.untilExclusive, observedDays: recent.observedDays },
baseline: { from: baseline.from, untilExclusive: baseline.untilExclusive, observedDays: baseline.observedDays },
comparisons, investigate: signals, retention,
@@ -93,8 +124,18 @@ export function dailyProductReview(rows: Row[], now: Date) {
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])),
+ features: PRODUCT_USAGE_ACTIONS.map(action => ({ action, requests: c[`${action}_requests`] ?? 0,
+ installationDays: c[`${action}_installation_days`] ?? null,
+ firstMeasuredInstallations: c[`${action}_first_installations`] ?? null,
+ repeatInstallationDays: c[`${action}_repeat_installation_days`] ?? null,
+ interpretation: 'An operation was requested, possibly automatically. Reach is installation-days, not unique people, UI clicks or successful feature use.',
+ })),
+ measurementHealth: { updatedInstallationDays: c.measurement_v2_installation_days ?? null,
+ queuePruning: c.measurement_queue_pruned ?? 0, turnObservationOverflow: c.turn_observation_overflow ?? 0,
+ interpretation: 'Loss signals establish incomplete coverage; no loss signal does not prove complete collection.',
+ },
gaps: [
- 'Pre-sign-in setup and sign-in drop-off are not observed: signed-out clients send no reports. Test those paths synthetically.',
+ 'Signed-out setup/sign-in counts cover only explicitly participating native app sessions. Stage totals are not a linked funnel; web, app closures and privacy choices leave gaps. 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.',
diff --git a/backend/src/analytics/dailyProductUsage.ts b/backend/src/analytics/dailyProductUsage.ts
index d4a3c5cb3..058025c3c 100644
--- a/backend/src/analytics/dailyProductUsage.ts
+++ b/backend/src/analytics/dailyProductUsage.ts
@@ -1,7 +1,7 @@
-import { PRODUCT_USAGE_METRICS } from '../types/productUsage.js'
+import { PRODUCT_USAGE_METRICS, PRODUCT_USAGE_SETUP_METRICS } from '../types/productUsage.js'
const DAY = 86_400_000
-export const DAILY_PRODUCT_METRICS = [...PRODUCT_USAGE_METRICS,
+export const DAILY_PRODUCT_METRICS = [...PRODUCT_USAGE_METRICS, ...PRODUCT_USAGE_SETUP_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',
diff --git a/backend/src/lib/productUsage.test.ts b/backend/src/lib/productUsage.test.ts
index 0b496f320..678ff5ee1 100644
--- a/backend/src/lib/productUsage.test.ts
+++ b/backend/src/lib/productUsage.test.ts
@@ -12,7 +12,7 @@ const db = vi.hoisted(() => ({
$transaction: vi.fn(), $runCommandRaw: vi.fn(),
}))
vi.mock('./prisma.js', () => ({ prisma: db }))
-import { deleteLegacyProductUsage, ensureProductUsageExpiry, ingestProductUsage, productUsageChoice, recordRelayUsage, setProductUsageChoice } from './productUsage.js'
+import { deleteLegacyProductUsage, ensureProductUsageExpiry, ingestProductUsage, ingestSetupUsage, 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 } }
@@ -117,3 +117,20 @@ it('installs database expiry for receipts, totals and every linked daily history
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 }] })
})
+
+it('setup ingestion never reads an account and expires after yesterday', async () => {
+ const setup = { id: report.id, day: report.day, counters: { setup_desktop_sign_in_ok: 1 } }
+ expect(await ingestSetupUsage(setup, now)).toEqual({ accepted: true })
+ expect(db.productUsagePreference.findUnique).not.toHaveBeenCalled()
+ expect(db.analyticsMachineState.findFirst).not.toHaveBeenCalled()
+ expect(JSON.stringify(db.productUsageReceipt.create.mock.calls)).not.toContain('setup_desktop')
+ expect(await ingestSetupUsage({ ...setup, day: '2026-10-11' }, now)).toMatchObject({ reason: 'EXPIRED' })
+ expect(await ingestSetupUsage({ ...setup, day: '2026-10-12' }, now)).toMatchObject({ accepted: true })
+})
+
+it('keeps the native app collectors and anonymous transport identical', () => {
+ for (const file of ['product_measurement.dart', 'setup_transport.dart', 'setup_usage_choice.dart']) {
+ expect(readFileSync(new URL(`../../../desktop/lib/measurement/${file}`, import.meta.url), 'utf8'))
+ .toBe(readFileSync(new URL(`../../../mobile/lib/measurement/${file}`, import.meta.url), 'utf8'))
+ }
+})
diff --git a/backend/src/lib/productUsage.ts b/backend/src/lib/productUsage.ts
index fe51aefe0..d0b67828c 100644
--- a/backend/src/lib/productUsage.ts
+++ b/backend/src/lib/productUsage.ts
@@ -31,10 +31,24 @@ function validDay(day: string, now: Date): boolean {
/** 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' }
+ return ingestCounters(report, userId)
+}
+
+export interface SetupUsageReport { id: string; day: string; counters: Record<string, number> }
+/** Only the dedicated route's narrow schema may call this. No account/authentication lookup. */
+export async function ingestSetupUsage(report: SetupUsageReport, now = new Date()) {
+ const age = Math.floor(now.getTime() / DAY) * DAY - Date.parse(report.day + 'T00:00:00Z')
+ if (!validDay(report.day, now) || age > DAY) return { accepted: false, reason: 'EXPIRED' }
+ return ingestCounters(report)
+}
+
+async function ingestCounters(report: SetupUsageReport & { revision?: number }, userId?: string) {
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 }
+ if (userId) {
+ 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),
diff --git a/backend/src/middlewares/authMiddleware.test.ts b/backend/src/middlewares/authMiddleware.test.ts
index 82ae40e67..bdb8517ec 100644
--- a/backend/src/middlewares/authMiddleware.test.ts
+++ b/backend/src/middlewares/authMiddleware.test.ts
@@ -98,3 +98,8 @@ describe('control-plane SSO auth middleware', () => {
})
})
})
+
+it('exempts only the exact credential-free setup endpoint from authentication', () => {
+ expect(shouldSkipAuth('/api/product-usage/setup')).toBe(true)
+ for (const path of ['/api/product-usage/report', '/api/product-usage/settings', '/api/product-usage/setup/extra']) expect(shouldSkipAuth(path)).toBe(false)
+})
diff --git a/backend/src/middlewares/authMiddleware.ts b/backend/src/middlewares/authMiddleware.ts
index 6c993c82a..33ab9160f 100644
--- a/backend/src/middlewares/authMiddleware.ts
+++ b/backend/src/middlewares/authMiddleware.ts
@@ -20,6 +20,8 @@ export function shouldSkipAuth(url: string): boolean {
const path = url.split('?')[0]
return (
path === '/api/health' ||
+ // Explicitly enabled, credential-free setup totals; its own schema and workload budget apply.
+ path === '/api/product-usage/setup' ||
// Web-driven SSO login (pre-session): /authorize returns the SSO URL, /exchange trades the code
// for the SSO access token, /logout-url returns the SSO end-session URL. All fetched by web XHR.
path === '/api/auth/authorize' ||
diff --git a/backend/src/productUsageReport.ts b/backend/src/productUsageReport.ts
index 39207295c..872f4dde1 100644
--- a/backend/src/productUsageReport.ts
+++ b/backend/src/productUsageReport.ts
@@ -8,17 +8,17 @@ 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,
+ // Four-week cohorts need their full follow-up; calendar-month comparisons need both prior months.
+ where: { dayUtc: { gte: new Date(today - 92 * 86400000), lt: new Date(today + 86400000) }, metric: { in: [...DAILY_PRODUCT_METRICS] } },
+ select: { dayUtc: true, metric: true, value: true }, orderBy: [{ dayUtc: 'asc' }, { metric: 'asc' }], take: 93 * 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.',
+ population: 'Daemon counts cover participating signed-in installations, including staff and both service environments. App flows and optional signed-out setup counts are separate populations, never 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.',
+ activation: 'No signup-to-value activation rate is inferred from first measured work. This report has no unique signup denominator; task outcomes are optional self-reports, not an objective success measure.',
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.',
diff --git a/backend/src/routes/productUsage.test.ts b/backend/src/routes/productUsage.test.ts
index d7f6b59c3..614a9d389 100644
--- a/backend/src/routes/productUsage.test.ts
+++ b/backend/src/routes/productUsage.test.ts
@@ -1,6 +1,6 @@
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() }))
+const methods = vi.hoisted(() => ({ ingestProductUsage: vi.fn(), ingestSetupUsage: 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'
@@ -12,6 +12,7 @@ beforeEach(async () => {
await app.register(productUsageRoutes)
methods.productUsageChoice.mockResolvedValue({ enabled: true, revision: 0 })
methods.ingestProductUsage.mockResolvedValue({ accepted: true })
+ methods.ingestSetupUsage.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 } }
@@ -61,10 +62,41 @@ it('the visible control changes only the authenticated account', async () => {
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('the complete vocabulary fits bounded chunks, including the longest metric keys', async () => {
+ for (let i = 0; i < PRODUCT_USAGE_METRICS.length; i += 64) {
+ const payload = { ...good, counters: Object.fromEntries(PRODUCT_USAGE_METRICS.slice(i, i + 64).map(k => [k, PRODUCT_USAGE_MAX_COUNT])) }
+ expect(Buffer.byteLength(JSON.stringify(payload))).toBeLessThan(8192)
+ expect((await submit(payload)).statusCode).toBe(200)
+ }
+})
+
+const setup = { schemaVersion: 1, consent: true, id: good.id, day: good.day, counters: { setup_desktop_sign_in_started: 1 } }
+const sendSetup = (payload: unknown = setup, headers = {}) => app.inject({ method: 'POST', url: '/api/product-usage/setup', payload: payload as Record<string, unknown>, headers })
+it('accepts only explicitly enabled setup counts without credentials or account lookup', async () => {
+ expect((await sendSetup()).statusCode).toBe(200)
+ expect(methods.ingestSetupUsage).toHaveBeenCalledWith(setup)
+ expect(methods.productUsageChoice).not.toHaveBeenCalled()
+ expect(methods.ingestProductUsage).not.toHaveBeenCalled()
+ for (const payload of [{ ...setup, consent: false }, { ...setup, account: 'PRIVATE_CANARY' },
+ { ...setup, counters: { turns_started: 1 } }, { ...setup, counters: { setup_desktop_sign_in_started: 1001 } }]) {
+ const response = await sendSetup(payload)
+ expect(response.statusCode).toBe(400)
+ expect(response.body).not.toContain('PRIVATE_CANARY')
+ }
+ for (const headers of [{ authorization: 'fixture' }, { cookie: 'PRIVATE_CANARY' }]) expect((await sendSetup(setup, headers)).statusCode).toBe(400)
+})
+it('bounds untrusted setup writes independently of signed-in reports', async () => {
+ let finish!: (value: unknown) => void
+ methods.ingestSetupUsage.mockImplementation(() => new Promise(resolve => { finish = resolve }))
+ // A shared deferred completion releases all four admitted requests.
+ const done = new Promise(resolve => { finish = resolve })
+ methods.ingestSetupUsage.mockReturnValue(done)
+ const pending = Array.from({ length: 4 }, () => sendSetup().then((r: { statusCode: number }) => r.statusCode))
+ await vi.waitFor(() => expect(methods.ingestSetupUsage).toHaveBeenCalledTimes(4))
+ expect((await sendSetup()).statusCode).toBe(429)
+ expect((await submit(good)).statusCode).toBe(200)
+ finish({ accepted: true })
+ expect(await Promise.all(pending)).toEqual([200, 200, 200, 200])
})
it('feedback reduces a voluntary fixed choice to one unlinked, retry-safe count', async () => {
diff --git a/backend/src/routes/productUsage.ts b/backend/src/routes/productUsage.ts
index ccd74778a..3533f945a 100644
--- a/backend/src/routes/productUsage.ts
+++ b/backend/src/routes/productUsage.ts
@@ -1,7 +1,7 @@
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 { ingestProductUsage, ingestSetupUsage, productUsageChoice, setProductUsageChoice } from '../lib/productUsage.js'
+import { PRODUCT_FEEDBACK, PRODUCT_USAGE_MAX_COUNT, PRODUCT_USAGE_METRICS, PRODUCT_USAGE_SETUP_METRICS } from '../types/productUsage.js'
import { sendError, sendSuccess } from '../utils/response.js'
export const productUsageReportSchema = z.strictObject({
@@ -11,8 +11,17 @@ export const productUsageReportSchema = z.strictObject({
})
const feedbackSchema = z.strictObject({ id: z.uuid(), answer: z.enum(PRODUCT_FEEDBACK) })
const choiceSchema = z.strictObject({ enabled: z.boolean() })
+export const setupUsageSchema = z.strictObject({
+ schemaVersion: z.literal(1), consent: z.literal(true), id: z.uuid(),
+ day: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+ counters: z.partialRecord(z.enum(PRODUCT_USAGE_SETUP_METRICS), z.number().int().min(1).max(1000))
+ .refine(c => Object.keys(c).length > 0 && Object.keys(c).length <= 32),
+})
export async function productUsageRoutes(app: FastifyInstance): Promise<void> {
+ // A process-wide budget bounds untrusted pre-sign-in counts without collecting IPs or cookies.
+ // Exhaustion loses measurement only; it never shares a gate with sign-in or product traffic.
+ let setupWindow = 0, setupRequests = 0, setupInFlight = 0
// 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) => {
@@ -20,6 +29,18 @@ export async function productUsageRoutes(app: FastifyInstance): Promise<void> {
const status = code && code >= 400 && code < 500 ? code : 503
return sendError(reply, 'Product usage request unavailable', 'USAGE_UNAVAILABLE', status)
})
+ app.post('/api/product-usage/setup', { bodyLimit: 4096 }, async (req, reply) => {
+ if (req.headers.authorization || req.headers.cookie) return sendError(reply, 'Setup reports must omit credentials', 'INVALID_SETUP_REPORT', 400)
+ const parsed = setupUsageSchema.safeParse(req.body)
+ if (!parsed.success) return sendError(reply, 'Invalid setup report', 'INVALID_SETUP_REPORT', 400)
+ const minute = Math.floor(Date.now() / 60_000)
+ if (minute !== setupWindow) { setupWindow = minute; setupRequests = 0 }
+ if (setupRequests >= 120 || setupInFlight >= 4) return sendError(reply, 'Setup measurement busy', 'USAGE_UNAVAILABLE', 429)
+ setupRequests++; setupInFlight++
+ try { return sendSuccess(reply, await ingestSetupUsage(parsed.data)) }
+ catch { return sendError(reply, 'Setup measurement unavailable', 'USAGE_UNAVAILABLE', 503) }
+ finally { setupInFlight-- }
+ })
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))
diff --git a/backend/src/types/productUsage.ts b/backend/src/types/productUsage.ts
index 5b86f7317..b520dd9da 100644
--- a/backend/src/types/productUsage.ts
+++ b/backend/src/types/productUsage.ts
@@ -2,14 +2,32 @@
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_FEEDBACK_REASONS = ['useful', 'could_not_finish', 'slow', 'confusing', 'missing_feature'] as const
+export const PRODUCT_FEEDBACK_OUTCOMES = ['completed', 'partly_completed', 'not_completed'] as const
+export const PRODUCT_FEEDBACK = [...PRODUCT_FEEDBACK_REASONS, ...PRODUCT_FEEDBACK_OUTCOMES] as const
+export const PRODUCT_USAGE_ACTIONS = ['create', 'resume', 'restart', 'model_change', 'history',
+ 'fork', 'close', 'delete', 'search', 'history_page', 'store_list', 'store_install', 'store_update', 'store_remove',
+ 'model_list', 'model_download', 'model_start', 'model_stop', 'browser_open'] as const
+export const PRODUCT_USAGE_FEATURE_MEASURES = ['installation_days', 'first_installations', 'repeat_installation_days'] as const
+export const PRODUCT_USAGE_SURFACES = ['desktop', 'phone', 'web'] as const
+export const PRODUCT_USAGE_FLOWS = ['setup', 'setup_harness', 'setup_tmux', 'setup_clipboard', 'sign_in',
+ 'workspace_connect', 'computer_link', 'remote_connect', 'viewer_open', 'update_check', 'update_stage'] as const
+export const PRODUCT_USAGE_FLOW_MEASURES = ['started', 'ok', 'failed', 'cancelled', 'unknown',
+ 'under_1s', '1s_to_10s', '10s_to_1m', 'over_1m'] as const
+export const PRODUCT_USAGE_UI_METRICS = PRODUCT_USAGE_SURFACES.flatMap(surface =>
+ PRODUCT_USAGE_FLOWS.flatMap(flow => PRODUCT_USAGE_FLOW_MEASURES.map(measure => `ui_${surface}_${flow}_${measure}` as const)))
+// A signed-out report is explicitly enabled on this app. It cannot carry account/work metrics.
+export const PRODUCT_USAGE_SETUP_METRICS = PRODUCT_USAGE_SURFACES.flatMap(surface =>
+ (['setup', 'setup_harness', 'setup_tmux', 'setup_clipboard', 'sign_in'] as const).flatMap(flow =>
+ PRODUCT_USAGE_FLOW_MEASURES.map(measure => `setup_${surface}_${flow}_${measure}` 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',
+ 'monthly_working_installations', 'monthly_returning_installations', 'reactivated_after_7d_installations',
+ 'measurement_v2_installation_days', 'measurement_queue_pruned', 'turn_observation_overflow',
'turns_started', 'turns_ended', 'turns_interrupted',
'duration_under_10s', 'duration_10s_to_1m', 'duration_1m_to_5m', 'duration_over_5m',
'desktop_opens', 'tui_opens',
@@ -20,9 +38,11 @@ export const PRODUCT_USAGE_METRICS = [
'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',
+ 'first_response_installations', 'd1_returning_work_installations', 'd7_returning_work_installations', 'd28_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)),
+ ...PRODUCT_USAGE_ACTIONS.flatMap(action => PRODUCT_USAGE_FEATURE_MEASURES.map(measure => `${action}_${measure}` as const)),
+ ...PRODUCT_USAGE_UI_METRICS,
] as const
export type ProductUsageMetric = typeof PRODUCT_USAGE_METRICS[number]
export interface ProductUsageReport {
diff --git a/cli/e2e/harness/corePerf.cjs b/cli/e2e/harness/corePerf.cjs
index 3dff524ea..3f5893ce1 100644
--- a/cli/e2e/harness/corePerf.cjs
+++ b/cli/e2e/harness/corePerf.cjs
@@ -1,6 +1,7 @@
// Test-only preload. QA needed the core's CPU, not its master's or its children's.
// Nothing is loaded into production; only the opt-in E2E supplies these settings.
-if ((process.argv.includes('__run') || (process.env.HARNESS_E2E_PERF_READERS === '1'
+if ((process.argv.includes('__run') || (process.env.HARNESS_E2E_PERF_GATEWAY === '1'
+ && process.argv.includes('__service') && process.env.HARNESSD_SERVICE === 'gateway') || (process.env.HARNESS_E2E_PERF_READERS === '1'
&& process.argv.includes('__service') && /^engine-(claude|codex)$/.test(process.env.HARNESSD_SERVICE || ''))) && process.env.HARNESS_E2E_PERF_DIR && process.env.HARNESS_E2E_PERF_TOKEN) {
const { createServer } = require('node:http')
const { writeFileSync, renameSync } = require('node:fs')
diff --git a/cli/e2e/harness/fakeBackend.ts b/cli/e2e/harness/fakeBackend.ts
index 3bd1c107d..fde14c216 100644
--- a/cli/e2e/harness/fakeBackend.ts
+++ b/cli/e2e/harness/fakeBackend.ts
@@ -84,7 +84,7 @@ const bytes = (raw: RawData): Uint8Array => new Uint8Array(Array.isArray(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
+ productUsage: { enabled: boolean; revision: number; reports: Record<string, unknown>[]; stallReports?: boolean } | 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
@@ -138,6 +138,7 @@ export class FakeBackend {
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 ?? '')) {
+ if (usage.stallReports && req.url === '/api/product-usage/report') { req.resume(); return }
let body = ''
req.on('data', chunk => { body += String(chunk) })
req.on('end', () => {
diff --git a/cli/e2e/productUsage.e2e.ts b/cli/e2e/productUsage.e2e.ts
index 898423ff6..a0ade49d2 100644
--- a/cli/e2e/productUsage.e2e.ts
+++ b/cli/e2e/productUsage.e2e.ts
@@ -46,9 +46,17 @@ it('reports only local counters from a real turn, and the account switch stops t
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 client.request('session_search', { query: 'PRIVATE_SEARCH_CANARY' })
+ const appReport = { schemaVersion: 1, revision: 0, id: '27b07da5-033b-412e-b91f-7316b254f991', day: new Date().toISOString().slice(0, 10), counters: { ui_desktop_computer_link_failed: 1 } }
+ const forwarded = await fetch(`http://127.0.0.1:${d.port}/api/product-usage/report`, { method: 'POST', headers: { 'content-type': 'application/json', 'x-adapter-local': '1' }, body: JSON.stringify(appReport) })
+ expect(forwarded.status).toBe(200)
+ expect(backend.productUsage.reports).toContainEqual(appReport)
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('search_requests')).toBe(1)
+ expect(sum('search_first_installations')).toBe(1)
+ expect(sum('measurement_v2_installation_days')).toBe(1)
expect(sum('launch_started')).toBe(2)
expect(sum('launch_created')).toBe(1)
expect(sum('launch_failed')).toBe(1)
diff --git a/cli/e2e/productUsagePerf.e2e.ts b/cli/e2e/productUsagePerf.e2e.ts
new file mode 100644
index 000000000..f300e542c
--- /dev/null
+++ b/cli/e2e/productUsagePerf.e2e.ts
@@ -0,0 +1,102 @@
+/** USAGE_PERF=1 E2E_BUNDLE=1. Run alone: real isolated daemon, fake engine/backend, same workload off/on/stalled. */
+import { createHash, randomUUID } from 'node:crypto'
+import { execFileSync } from 'node:child_process'
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs'
+import { cpus, loadavg, tmpdir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { expect, it } from 'vitest'
+import { LocalClient } from './harness/client.js'
+import { CLI_ROOT, until } from './harness/daemon.js'
+import { FakeBackend } from './harness/fakeBackend.js'
+import { signedInDaemon } from './harness/fleet.js'
+import { harnessdProcesses } from './harness/endurance.js'
+
+const sleep = (ms: number) => new Promise<void>(done => setTimeout(done, ms))
+const percentile = (values: number[], fraction: number) => [...values].sort((a, b) => a - b)[Math.min(values.length - 1, Math.floor(values.length * fraction))] ?? null
+
+it.runIf(process.env.USAGE_PERF === '1')('measures the core and gateway while reporting is off, on, or unable to answer', async () => {
+ const bundle = process.env.E2E_BUNDLE_PATH
+ if (!bundle) throw Error('Use E2E_BUNDLE=1 or E2E_BUNDLE_PATH')
+ const seconds = Number(process.env.USAGE_PERF_SECONDS ?? 65)
+ if (!Number.isInteger(seconds) || seconds < 65 || seconds > 180) throw Error('Use 65–180 seconds so a report flush occurs')
+ const output = resolve(process.env.USAGE_PERF_REPORT ?? '../.harness/measurement-coverage/daemon-after.json')
+ const results: unknown[] = []
+ const report = () => {
+ mkdirSync(dirname(output), { recursive: true })
+ writeFileSync(output, JSON.stringify({ source: process.env.USAGE_PERF_SOURCE ?? execFileSync('git', ['rev-parse', 'HEAD'], { cwd: CLI_ROOT, encoding: 'utf8' }).trim(),
+ bundleSha256: createHash('sha256').update(readFileSync(bundle)).digest('hex'), node: process.version,
+ workload: { seconds, agents: 1, turnEveryMs: 1500, requestEveryMs: 125, requests: ['agents_list', 'agent_recent', 'session_search'] },
+ machine: { cpu: cpus()[0]?.model, logicalCpus: cpus().length },
+ limits: 'One run per state, loopback backend and fake engine; descriptive, not a production SLO or a real model latency benchmark.', results }, null, 2) + '\n')
+ }
+ for (const mode of ['off', 'on', 'stalled'] as const) {
+ const backend = await FakeBackend.start()
+ backend.productUsage = { enabled: mode !== 'off', revision: 0, reports: [], stallReports: mode === 'stalled' }
+ const spec = { machineId: 'b7'.repeat(16), computerId: 'synthetic-usage-performance', name: 'fixture', token: 'synthetic-token' }
+ backend.addMachine(spec)
+ const artifact = mkdtempSync(join(tmpdir(), 'harness-usage-perf-')), token = randomUUID()
+ const preload = fileURLToPath(new URL('./harness/corePerf.cjs', import.meta.url))
+ const daemon = await signedInDaemon(backend, spec, { NODE_OPTIONS: `--require=${JSON.stringify(preload)}`,
+ HARNESS_E2E_PERF_GATEWAY: '1', HARNESS_E2E_PERF_DIR: artifact, HARNESS_E2E_PERF_TOKEN: token })
+ let client: LocalClient | undefined
+ try {
+ await daemon.start()
+ await until('collector checked the synthetic choice', () => backend.seen.includes('GET /api/product-usage/settings') || null, 45000)
+ client = await LocalClient.connect(daemon, { machineId: spec.machineId })
+ const launched = await client.request('agent_create', { engine: 'claude', cwd: daemon.projectsDir, bypassPermission: true }, 90000)
+ const id = launched.agent.id
+ await until('synthetic agent ready', async () => {
+ const list = await client!.request('agents_list', {})
+ return list.agents.some((a: { id: string; sessionId?: string }) => a.id === id && a.sessionId) || null
+ }, 45000)
+ const pids = harnessdProcesses(daemon)
+ const probes = await Promise.all(['core', 'gateway'].map(async name => {
+ const pid = pids.get(name)!
+ const file = join(artifact, `core-${pid}.json`)
+ await until(`${name} probe`, () => existsSync(file) || null, 10000)
+ const { port } = JSON.parse(readFileSync(file, 'utf8')) as { port: number }
+ return { name, call: async (action: string) => {
+ const response = await fetch(`http://127.0.0.1:${port}/${action}`, { method: 'POST',
+ headers: { 'content-type': 'application/json', 'x-harness-perf-token': token }, body: JSON.stringify({ label: mode }), signal: AbortSignal.timeout(5000) })
+ expect(response.ok).toBe(true)
+ return response.json()
+ } }
+ }))
+ await sleep(3000)
+ await Promise.all(probes.map(p => p.call('start')))
+ const start = performance.now(), latency: number[] = [], turns: number[] = [], load = loadavg()
+ const requests = (async () => {
+ let i = 0
+ while (performance.now() - start < seconds * 1000) {
+ const type = ['agents_list', 'agent_recent', 'session_search'][i++ % 3]
+ const before = performance.now()
+ await client!.request(type, { agentId: id, query: 'SYNTHETIC_PRIVATE_QUERY' }, 10000)
+ latency.push(performance.now() - before)
+ await sleep(125)
+ }
+ })()
+ const working = (async () => {
+ while (performance.now() - start < seconds * 1000) {
+ const ended = client!.next(f => f.type === 'turn_ended' && f.agentId === id, 30000)
+ const before = performance.now()
+ client!.send('message', { agentId: id, content: 'SYNTHETIC_PRIVATE_PROMPT' })
+ await ended; turns.push(performance.now() - before)
+ await sleep(1500)
+ }
+ })()
+ await Promise.all([requests, working])
+ const processes = await Promise.all(probes.map(async p => ({ name: p.name, ...await p.call('end') })))
+ expect(daemon.coresStarted()).toBe(1)
+ expect(turns.length).toBeGreaterThan(0)
+ const wire = JSON.stringify(backend.productUsage.reports)
+ for (const forbidden of ['SYNTHETIC_PRIVATE', spec.machineId, spec.token, id]) expect(wire).not.toContain(forbidden)
+ if (mode === 'on') expect(backend.productUsage.reports.length).toBeGreaterThan(0)
+ else expect(backend.productUsage.reports).toHaveLength(0)
+ results.push({ mode, processes, requests: latency.length, rpcMs: { p50: percentile(latency, .5), p95: percentile(latency, .95), p99: percentile(latency, .99) },
+ turns: turns.length, fakeTurnMs: { p50: percentile(turns, .5), p95: percentile(turns, .95) }, reports: backend.productUsage.reports.length,
+ reportBytes: backend.productUsage.reports.reduce((n, r) => n + Buffer.byteLength(JSON.stringify(r)), 0), loadAverage: { start: load, end: loadavg() } })
+ report()
+ } finally { client?.close(); await daemon.close(); await backend.close() }
+ }
+}, 900000)
diff --git a/cli/src/backendSocket.ts b/cli/src/backendSocket.ts
index c09bcac29..4c1b64e90 100644
--- a/cli/src/backendSocket.ts
+++ b/cli/src/backendSocket.ts
@@ -824,7 +824,7 @@ export class BackendSocket {
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)
+ measured(p.error ?? (p.failure as { code?: unknown } | undefined)?.code, p.state, !!p.agent, p.ok)
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)
diff --git a/cli/src/core/gatewayLink.spec.ts b/cli/src/core/gatewayLink.spec.ts
index e3ecf52d1..70b13d001 100644
--- a/cli/src/core/gatewayLink.spec.ts
+++ b/cli/src/core/gatewayLink.spec.ts
@@ -3,7 +3,7 @@ import { decodeGatewayBinary, encodeGatewayBinary, GatewayBinary, GATEWAY_CALLS
import { RelayConnectError } from '../lib/relayFrames.js'
import { decodeTerminalLocal, encodeTerminalLocal, TerminalBinaryKind, type TerminalBinaryClear } from '../lib/terminalBinary.js'
import type { GatewayEvents, LaneSeal } from './api.js'
-import { createGatewayLink, GATEWAY_BUFFER_LIMIT, LANE_WAIT_MS, laneOf, OWED_MAX, PAIR_WAIT_MS, WINDOW_GATEWAY_GONE } from './gatewayLink.js'
+import { createGatewayLink, GATEWAY_BUFFER_LIMIT, GATEWAY_USAGE_BUFFER_LIMIT, LANE_WAIT_MS, laneOf, OWED_MAX, PAIR_WAIT_MS, WINDOW_GATEWAY_GONE } from './gatewayLink.js'
import { ON_DEMAND_START_MS } from './serviceLinks.js'
const STREAM = '00000000-0000-4000-8000-000000000001'
@@ -113,6 +113,22 @@ describe('the gateway in its own process, as the core sees it', () => {
expect(kinds().at(-1)).toBe('stop')
})
+ it('drops optional measurement before relay traffic and never wakes a stopped gateway', () => {
+ const { link, kinds, setBuffered, want } = setup()
+ link.port.usageCounter?.('create_requests')
+ expect(kinds()).toEqual([])
+ expect(want).not.toHaveBeenCalled()
+ link.connected()
+ setBuffered(GATEWAY_USAGE_BUFFER_LIMIT)
+ link.port.usageCounter?.('create_requests')
+ link.port.usageLaunch?.({ id: 'creation-fixture-1', phase: 'start' })
+ link.port.broadcast({ type: 'turn_started' })
+ expect(kinds()).toEqual(['start', 'broadcast'])
+ setBuffered(0)
+ link.port.usageCounter?.('create_requests')
+ expect(kinds().at(-1)).toBe('usageCounter')
+ })
+
it('drops what would pile up on the socket to a gateway that reads nothing, and says so once a minute', () => {
const { link, kinds, setBuffered, log, tick } = setup()
link.connected()
diff --git a/cli/src/core/gatewayLink.ts b/cli/src/core/gatewayLink.ts
index ad6edac1a..9d0ca011b 100644
--- a/cli/src/core/gatewayLink.ts
+++ b/cli/src/core/gatewayLink.ts
@@ -59,6 +59,9 @@ export interface GatewayLinkDeps {
* remote clients would wait in the core's memory meanwhile. */
export const GATEWAY_BUFFER_LIMIT = 16 * 1024 * 1024
+/** Optional counters yield long before relay traffic does. Never queue measurements for a restart. */
+export const GATEWAY_USAGE_BUFFER_LIMIT = 64 * 1024
+
/** How long a pairing may take: the code is typed on one screen and checked over the relay, round by round. */
export const PAIR_WAIT_MS = 120_000
@@ -174,8 +177,8 @@ export function createGatewayLink(deps: GatewayLinkDeps) {
}
const port: GatewayPort = {
- usageLaunch: (signal) => { send('usageLaunch', { signal }) },
- usageCounter: (metric) => { send('usageCounter', { metric }) },
+ usageLaunch: (signal) => { if (deps.buffered() < GATEWAY_USAGE_BUFFER_LIMIT) send('usageLaunch', { signal }) },
+ usageCounter: (metric) => { if (deps.buffered() < GATEWAY_USAGE_BUFFER_LIMIT) 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 665626322..0eac2d835 100644
--- a/cli/src/core/main.ts
+++ b/cli/src/core/main.ts
@@ -1906,6 +1906,7 @@ async function runForeground(session: AuthSession | null): Promise<void> {
onAgentSettingsRead: () => agentSettings.settingsRead(),
onAgentSettingsWrite: (body) => agentSettings.settingsWrite(body),
onProductFeedback: (body) => proxyBackend('POST', '/api/product-usage/feedback', body),
+ onProductUsageReport: (body) => proxyBackend('POST', '/api/product-usage/report', 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),
diff --git a/cli/src/gateway/productUsage.spec.ts b/cli/src/gateway/productUsage.spec.ts
index 745aa6ecf..610704b47 100644
--- a/cli/src/gateway/productUsage.spec.ts
+++ b/cli/src/gateway/productUsage.spec.ts
@@ -2,6 +2,7 @@ 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 { PRODUCT_USAGE_METRICS } from '../lib/productUsageContract.js'
import { createProductUsage, type ProductUsageDeps } from './productUsage.js'
let dir: string, file: string, now: number, enabled: boolean, revision: number
@@ -18,7 +19,7 @@ beforeEach(() => {
})
usage = createProductUsage({ file, now: () => now, request })
})
-afterEach(() => { usage.stop(); rmSync(dir, { recursive: true, force: true }) })
+afterEach(async () => { await 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
@@ -28,7 +29,7 @@ const totals = () => {
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.launch({ id: 'PRIVATE_CREATION_CANARY', phase: 'start' }); await usage.sync(); await usage.stop()
usage = createProductUsage({ file, now: () => now, request }); await usage.sync()
now += 2 * 3600000
usage.observe('turn_started', 'PRIVATE_AGENT_CANARY', false)
@@ -81,7 +82,7 @@ it('reduces turns locally, excludes replay, and never persists or uploads agent
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()
+ await usage.sync(); const first = structuredClone(sent[0]); await usage.stop()
usage = createProductUsage({ file, now: () => now, request })
retry = false; await usage.sync()
expect(sent[1]).toEqual(first)
@@ -115,7 +116,7 @@ it('treats unknown preference and unavailable servers as missing coverage', asyn
})
it('rebuilds a persisted report from its allowlist, removing content injected into local storage', async () => {
- usage.stop()
+ await 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' } }))
@@ -135,13 +136,13 @@ it('expires pending reports instead of replaying them beyond the server dedupe w
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)
+ await 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))
+ await 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)
@@ -164,7 +165,7 @@ it('counts first-response latency, silent waits and errors once without reading
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()
+ await usage.sync(); await work(); await usage.stop()
now += 86400000; usage = createProductUsage({ file, now: () => now, request }); await usage.sync()
await work(); await work()
now += 6 * 86400000; await work()
@@ -177,7 +178,7 @@ it('attributes D1/D7 return to the original working day, surviving restarts and
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 })
+ expect(totals()).toEqual({ create_requests: 1, create_installation_days: 1, create_first_installations: 1, measurement_v2_installation_days: 1 })
})
it('tracks a durable launch through polls without persisting its receipt or counting polls as attempts', async () => {
@@ -188,16 +189,97 @@ it('tracks a durable launch through polls without persisting its receipt or coun
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(totals()).toEqual({ measurement_v2_installation_days: 1, 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 })
+ expect(totals()).toEqual({ measurement_v2_installation_days: 1, 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()
})
+
+
+it('batches the complete vocabulary below the wire bound without losing counts', async () => {
+ await usage.sync()
+ for (const metric of PRODUCT_USAGE_METRICS) usage.counter(metric)
+ for (let i = 0; i < Math.ceil(PRODUCT_USAGE_METRICS.length / 64) + 3; i++) await usage.sync()
+ for (const report of sent) expect(Buffer.byteLength(JSON.stringify(report))).toBeLessThan(8192)
+ for (const metric of PRODUCT_USAGE_METRICS) expect(totals()[metric], metric).toBeGreaterThanOrEqual(1)
+ expect(JSON.parse(readFileSync(file, 'utf8')).days).toEqual({})
+})
+
+it('counts feature reach and repeat use once per installation day, independently of requests', async () => {
+ await usage.sync()
+ usage.counter('store_install_requests'); usage.counter('store_install_requests'); await usage.sync()
+ await usage.stop()
+ usage = createProductUsage({ file, now: () => now, request }); await usage.sync()
+ usage.counter('store_install_requests'); await usage.sync()
+ now += 86400000
+ usage.counter('store_install_requests'); await usage.sync()
+ expect(totals()).toMatchObject({ store_install_requests: 4, store_install_installation_days: 2,
+ store_install_first_installations: 1, store_install_repeat_installation_days: 1 })
+})
+
+it('attributes four-week return to its original day and counts consecutive calendar months', async () => {
+ const work = () => { usage.observe('turn_started', 'synthetic', false); usage.observe('turn_ended', 'synthetic', false) }
+ await usage.sync(); work(); await usage.sync()
+ now += 28 * 86400000; work()
+ await usage.sync(); await usage.sync()
+ expect(totals()).toMatchObject({ d28_returning_work_installations: 1, monthly_working_installations: 2,
+ monthly_returning_installations: 1, reactivated_after_7d_installations: 1 })
+ const report = (sent as { day: string; counters: Record<string, number> }[]).find(r => r.counters.d28_returning_work_installations)
+ expect(report?.day).toBe('2026-10-12')
+})
+
+it('keeps memory and disk bounded during a long reporting outage', async () => {
+ await usage.sync()
+ for (let day = 0; day < 35; day++) {
+ for (const metric of PRODUCT_USAGE_METRICS) usage.counter(metric)
+ now += 86400000
+ }
+ await usage.stop()
+ expect(Buffer.byteLength(readFileSync(file))).toBeLessThanOrEqual(256 * 1024)
+ expect(Object.keys(JSON.parse(readFileSync(file, 'utf8')).days).length).toBeLessThanOrEqual(35)
+})
+
+it('does not upload before persistence or block observers on a slow disk, and fences stop during a save', async () => {
+ await usage.stop()
+ let release: (() => void) | undefined, writes = 0, block = false
+ usage = createProductUsage({ file, now: () => now, request, write: async (_file, data) => {
+ writes++
+ if (block) await new Promise<void>(resolve => { release = resolve })
+ writeFileSync(file, data)
+ } })
+ await usage.sync(); block = true
+ usage.counter('create_requests')
+ const flushing = usage.sync()
+ await vi.waitFor(() => expect(release).toBeTypeOf('function'))
+ const before = writes
+ for (let i = 0; i < 1000; i++) usage.counter('create_requests')
+ expect(writes).toBe(before)
+ expect(sent).toHaveLength(0)
+ const stopped = usage.stop(true)
+ block = false; release!()
+ await stopped; await flushing
+ expect(sent).toHaveLength(0)
+ expect(JSON.parse(readFileSync(file, 'utf8')).days).toEqual({})
+})
+
+it('drops a corrupt oversized pending report without sending an oversized request', async () => {
+ await usage.stop()
+ writeFileSync(file, JSON.stringify({ revision: 0, pending: {
+ schemaVersion: 1, revision: 0, id: '12345678-1234-4234-8234-123456789012', day: '2026-10-12',
+ counters: Object.fromEntries(PRODUCT_USAGE_METRICS.map(metric => [metric, 100000])),
+ } }))
+ usage = createProductUsage({ file, now: () => now, request })
+ await usage.sync()
+ expect(sent).toHaveLength(0)
+ usage.observe('turn_started', 'PRIVATE_AGENT', false); await usage.sync()
+ expect(totals().turns_started).toBe(1)
+ expect(Buffer.byteLength(JSON.stringify(sent[0]))).toBeLessThan(8192)
+})
diff --git a/cli/src/gateway/productUsage.ts b/cli/src/gateway/productUsage.ts
index cb78ee93f..ccb61adf6 100644
--- a/cli/src/gateway/productUsage.ts
+++ b/cli/src/gateway/productUsage.ts
@@ -1,11 +1,17 @@
-import { mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs'
+import { readFileSync, statSync } from 'node:fs'
+import { mkdir, rename, writeFile } from 'node:fs/promises'
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,
+import { PRODUCT_USAGE_ACTIONS, 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 MAX_QUEUE_BYTES = 256 * 1024
+// A report stays below the server's 8 KiB body bound even with the complete vocabulary.
+const MAX_REPORT_METRICS = 64
+const metricSet = new Set<string>(PRODUCT_USAGE_METRICS)
+const requestActions = new Map(PRODUCT_USAGE_ACTIONS.map(action => [`${action}_requests`, action]))
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>>
@@ -14,6 +20,10 @@ interface State {
activeDay: string | null
workDay: string | null
workWeek: string | null
+ workMonth: string | null
+ measurementDay: string | null
+ featureDays: Partial<Record<typeof PRODUCT_USAGE_ACTIONS[number], string>>
+ featuresUsed: typeof PRODUCT_USAGE_ACTIONS[number][]
workedBefore: boolean
respondedBefore: boolean
launchedBefore: boolean
@@ -25,6 +35,7 @@ interface State {
pending: ProductUsageReport | null
}
const fresh = (revision: number): State => ({ revision, activeDay: null, workDay: null, workWeek: null,
+ workMonth: null, measurementDay: null, featureDays: {}, featuresUsed: [],
workedBefore: false, respondedBefore: false, launchedBefore: false, firstLaunchAt: null,
launchWorked: false, launchResponded: false, workDays: [], days: {}, pending: null })
export interface ProductUsageDeps {
@@ -32,6 +43,8 @@ export interface ProductUsageDeps {
request(method: string, path: string, body?: unknown): Promise<{ status: number; body: Record<string, unknown> }>
now?(): number
uuid?(): string
+ /** Test seam for a slow or unavailable disk; never called from an event observer. */
+ write?(file: string, value: string): Promise<void>
}
/** A reporting component of the gateway service; the core never waits for it.
@@ -42,17 +55,23 @@ 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
+ let writing: Promise<boolean> | null = null, writeAgain = false
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')
+ if (statSync(deps.file).size > MAX_QUEUE_BYTES) 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) {
+ for (const field of ['activeDay', 'workDay', 'workWeek', 'measurementDay'] as const) {
if (typeof saved[field] === 'string' && validDay(saved[field]!)) state[field] = saved[field]
}
+ if (typeof saved.workMonth === 'string' && /^\d{4}-\d{2}$/.test(saved.workMonth)) state.workMonth = saved.workMonth
+ for (const action of PRODUCT_USAGE_ACTIONS) {
+ if (validDay(saved.featureDays?.[action] ?? '')) state.featureDays[action] = saved.featureDays![action]
+ if (saved.featuresUsed?.includes(action)) state.featuresUsed.push(action)
+ }
state.workedBefore = saved.workedBefore === true
state.respondedBefore = saved.respondedBefore === true
state.launchedBefore = saved.launchedBefore === true
@@ -65,7 +84,8 @@ export function createProductUsage(deps: ProductUsageDeps) {
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) }
+ const restored = { schemaVersion: 1 as const, revision: state.revision, id: pending.id, day: pending.day, counters: clean(pending.counters) }
+ if (Buffer.byteLength(JSON.stringify(restored)) <= 8192) state.pending = restored
}
}
} catch { /* Missing or unreadable telemetry must not affect a session. */ }
@@ -83,24 +103,56 @@ export function createProductUsage(deps: ProductUsageDeps) {
}
return result
}
- function persist(): boolean {
+ function snapshot(): string {
clearTimeout(persistTimer); persistTimer = undefined
- for (const field of ['activeDay', 'workDay', 'workWeek'] as const) if (state[field] && !validDay(state[field]!)) state[field] = null
+ for (const field of ['activeDay', 'workDay', 'workWeek', 'measurementDay'] 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]
+ for (const action of PRODUCT_USAGE_ACTIONS) if (!validDay(state.featureDays[action] ?? '')) delete state.featureDays[action]
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 }
+ // Size each day once, keeping the most recent ones. Repeatedly serializing a full
+ // offline backlog to remove its oldest day would stall the gateway on a reconnect.
+ let bytes = Buffer.byteLength(JSON.stringify({ ...state, days: {} })) + 1024
+ const kept: State['days'] = {}
+ let pruned = false
+ for (const day of Object.keys(state.days).sort().reverse()) {
+ const size = Buffer.byteLength(JSON.stringify(state.days[day])) + 16
+ if (bytes + size > MAX_QUEUE_BYTES) { pruned = true; continue }
+ kept[day] = state.days[day]; bytes += size
+ }
+ state.days = kept
+ if (pruned) (state.days[key(now())] ??= {}).measurement_queue_pruned = 1
+ return JSON.stringify(state)
+ }
+ function persist(): Promise<boolean> {
+ writeAgain = true
+ // Coalesce concurrent saves to one in-flight write and the latest bounded state.
+ // A slow disk must not create a promise/file queue or block the relay's event loop.
+ return writing ??= (async () => {
+ try {
+ do {
+ writeAgain = false
+ const value = snapshot()
+ if (deps.write) await deps.write(deps.file, value)
+ else {
+ await mkdir(dirname(deps.file), { recursive: true, mode: 0o700 })
+ await writeFile(deps.file + '.tmp', value, { mode: 0o600 })
+ await rename(deps.file + '.tmp', deps.file)
+ }
+ } while (writeAgain)
+ return true
+ } catch { enabled = false; return false }
+ })().finally(() => { writing = null })
}
function dirty(): void {
- if (!persistTimer) { persistTimer = setTimeout(persist, 1000); persistTimer.unref() }
+ if (!persistTimer) { persistTimer = setTimeout(() => { void persist() }, 1000); persistTimer.unref() }
}
function add(metric: ProductUsageMetric, day = key(now())): void {
+ if (state.measurementDay !== key(now())) {
+ state.measurementDay = key(now())
+ ;(state.days[state.measurementDay] ??= {}).measurement_v2_installation_days = 1
+ }
const counters = state.days[day] ??= {}
counters[metric] = Math.min(PRODUCT_USAGE_MAX_COUNT, (counters[metric] ?? 0) + 1)
dirty()
@@ -117,11 +169,11 @@ export function createProductUsage(deps: ProductUsageDeps) {
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) {
+ async function choice(value: ProductUsageChoice): Promise<void> {
+ if (state.revision !== value.revision || (!value.enabled && (enabled || state.pending || Object.keys(state.days).length))) {
state = fresh(value.revision); running.clear(); launches.clear()
enabled = false
- if (!persist()) return
+ if (!await persist()) return
}
enabled = value.enabled && !stopped
}
@@ -132,7 +184,7 @@ export function createProductUsage(deps: ProductUsageDeps) {
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)
+ await 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')
@@ -145,19 +197,21 @@ export function createProductUsage(deps: ProductUsageDeps) {
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]
+ const counters = Object.fromEntries(Object.entries(state.days[day]).slice(0, MAX_REPORT_METRICS)) as Counters
+ state.pending = { schemaVersion: 1, revision: state.revision, id: uuid(), day, counters }
+ for (const metric of Object.keys(counters)) delete state.days[day][metric as ProductUsageMetric]
+ if (!Object.keys(state.days[day]).length) delete state.days[day]
}
// Persist the immutable receipt before sending. A crash or ambiguous response retries that id.
- if (!persist()) return
+ if (!await persist() || stopped || !enabled) 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() }
+ if (answer.status === 200 && result?.accepted === true) { state.pending = null; await persist() }
+ else if (result?.reason === 'CHOICE_CHANGED') { enabled = false; state = fresh(-1); running.clear(); launches.clear(); await persist() }
+ else if (result?.reason === 'EXPIRED') { state.pending = null; await 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 })
@@ -167,7 +221,15 @@ export function createProductUsage(deps: ProductUsageDeps) {
return {
sync,
counter(metric: ProductUsageMetric): void {
- if (enabled && !stopped && PRODUCT_USAGE_METRICS.includes(metric)) add(metric)
+ if (!enabled || stopped || !metricSet.has(metric)) return
+ add(metric)
+ const action = requestActions.get(metric)
+ if (action && state.featureDays[action] !== key(now())) {
+ add(`${action}_installation_days`)
+ add(`${action}_${state.featuresUsed.includes(action) ? 'repeat_installation_days' : 'first_installations'}`)
+ if (!state.featuresUsed.includes(action)) state.featuresUsed.push(action)
+ state.featureDays[action] = key(now())
+ }
},
launch(signal: ProductUsageLaunchSignal): void {
if (!enabled || stopped || !signal || typeof signal.id !== 'string' || !/^[a-zA-Z0-9_-]{16,96}$/.test(signal.id)) return
@@ -208,21 +270,30 @@ export function createProductUsage(deps: ProductUsageDeps) {
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
+ if (running.has(agent)) return
+ if (running.size >= 1000) { add('turn_observation_overflow'); return }
running.set(agent, { started: now(), response: false, error: false, waited: false }); markActive(); add('turns_started')
launchValue(false)
if (state.workDay !== key(now())) {
+ if (state.workDay && now() - Date.parse(state.workDay) >= 7 * DAY) add('reactivated_after_7d_installations')
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) {
+ for (const [lag, metric] of [[1, 'd1_returning_work_installations'], [7, 'd7_returning_work_installations'], [28, 'd28_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 currentMonth = key(now()).slice(0, 7)
+ if (state.workMonth !== currentMonth) {
+ add('monthly_working_installations')
+ const prior = new Date(currentMonth + '-01T00:00:00Z'); prior.setUTCMonth(prior.getUTCMonth() - 1)
+ if (state.workMonth === key(prior.getTime()).slice(0, 7)) add('monthly_returning_installations')
+ state.workMonth = currentMonth
+ }
const currentWeek = week(now())
if (state.workWeek !== currentWeek) {
add('weekly_working_installations')
@@ -254,10 +325,10 @@ export function createProductUsage(deps: ProductUsageDeps) {
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 {
+ stop(discard = false): Promise<boolean> {
stopped = true; enabled = false; clearInterval(timer); running.clear(); launches.clear()
if (discard) state = fresh(-1)
- persist()
+ return persist()
},
}
}
diff --git a/cli/src/gateway/start.ts b/cli/src/gateway/start.ts
index a74bb144f..d039a2e23 100644
--- a/cli/src/gateway/start.ts
+++ b/cli/src/gateway/start.ts
@@ -139,7 +139,7 @@ export function startGateway(host: GatewayHost): StartedGateway {
// 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),
+ request: (method, path, body) => accountHttp.backend(method, path, body, 5_000),
}) : null
if (usage) { gateway.productUsage = usage; void usage.sync() }
@@ -498,7 +498,7 @@ export function startGateway(host: GatewayHost): StartedGateway {
// 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)
+ || next.signIn?.epoch !== account.signIn?.epoch || next.signIn?.acct !== account.signIn?.acct) void usage?.stop(true)
account = next
startGroup()
registerAndSweep()
@@ -530,7 +530,8 @@ export function startGateway(host: GatewayHost): StartedGateway {
ops,
windowRelay,
stop: async () => {
- usage?.stop()
+ // Shutdown never waits for the optional disk queue. The stopped collector cannot upload.
+ void usage?.stop()
clearInterval(devlogTimer)
syncer.stop()
direct?.stop()
diff --git a/cli/src/hookServer.spec.ts b/cli/src/hookServer.spec.ts
index 33f5b6501..5e9066ac5 100644
--- a/cli/src/hookServer.spec.ts
+++ b/cli/src/hookServer.spec.ts
@@ -358,6 +358,28 @@ describe('account Experimental settings proxy', () => {
expect((await fetch(path, { method: 'POST', headers, body: JSON.stringify(body) })).status).toBe(200)
expect(send).toHaveBeenCalledExactlyOnceWith(body)
})
+ it('accepts only bounded fixed app counts through the local gateway proxy', async () => {
+ const send = vi.fn(async () => ({ status: 200, body: { success: true, data: { accepted: true } } }))
+ const { base } = await start({ onProductUsageReport: send })
+ const body = { schemaVersion: 1, revision: 0, id: '12345678-1234-4234-8234-123456789012', day: '2026-10-14', counters: { ui_desktop_sign_in_ok: 1 } }
+ const headers = { 'x-adapter-local': '1', 'content-type': 'application/json' }
+ const post = (value: unknown, h = headers) => fetch(`${base}/api/product-usage/report`, { method: 'POST', headers: h, body: JSON.stringify(value) })
+ expect((await post(body, { ...headers, origin: 'https://untrusted.example' } as typeof headers)).status).toBe(403)
+ for (const bad of [{ ...body, prompt: 'PRIVATE_CANARY' }, { ...body, counters: { turns_started: 1 } },
+ { ...body, counters: { ui_desktop_sign_in_ok: -1 } }, { ...body, counters: { ui_desktop_sign_in_ok: 'PRIVATE_CANARY' } },
+ { ...body, counters: { 'PRIVATE_CANARY': 1 } }, { ...body, prompt: 'PRIVATE_CANARY'.repeat(1000) }]) {
+ const response = await post(bad)
+ expect(response.status).toBe(400)
+ expect(await response.text()).not.toContain('PRIVATE_CANARY')
+ }
+ expect(send).not.toHaveBeenCalled()
+ expect((await post(body)).status).toBe(200)
+ expect(send).toHaveBeenCalledExactlyOnceWith(body)
+ send.mockRejectedValueOnce(new Error('PRIVATE_CANARY'))
+ const failed = await post(body)
+ expect(failed.status).toBe(502)
+ expect(await failed.text()).not.toContain('PRIVATE_CANARY')
+ })
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 })
diff --git a/cli/src/hookServer.ts b/cli/src/hookServer.ts
index e1bd045fd..8f2879bc6 100644
--- a/cli/src/hookServer.ts
+++ b/cli/src/hookServer.ts
@@ -1,4 +1,4 @@
-import { PRODUCT_FEEDBACK } from './lib/productUsageContract.js'
+import { PRODUCT_FEEDBACK, PRODUCT_USAGE_UI_METRICS } 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
@@ -183,6 +183,7 @@ export interface HookServerHandlers {
onExperimentalRead?: () => Promise<PairOutcome>
onExperimentalWrite?: (body: unknown) => Promise<PairOutcome>
onProductFeedback?: (body: unknown) => Promise<PairOutcome>
+ onProductUsageReport?: (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
@@ -266,7 +267,7 @@ function validHookBody(value: unknown): value is BoundHookBody {
return true
}
-function readBody(req: http.IncomingMessage): Promise<string> {
+function readBody(req: http.IncomingMessage, maximum = MAX_HOOK_BODY_BYTES): Promise<string> {
return new Promise((resolve) => {
let data = ''
let bytes = 0
@@ -274,7 +275,7 @@ function readBody(req: http.IncomingMessage): Promise<string> {
req.setEncoding('utf8')
req.on('data', (chunk: string) => {
bytes += Buffer.byteLength(chunk)
- if (bytes > MAX_HOOK_BODY_BYTES) { oversized = true; data = ''; return }
+ if (bytes > maximum) { oversized = true; data = ''; return }
data += chunk
})
req.on('end', () => resolve(oversized ? '' : data))
@@ -1028,6 +1029,30 @@ export function startHookServer(
if (!handlers.onExperimentalRead) { json(503, { error: 'UNAVAILABLE' }); return }
await proxied(handlers.onExperimentalRead); return
}
+ if (req.method === 'POST' && url === '/api/product-usage/report') {
+ if (!localOk) { json(403, { error: 'FORBIDDEN' }); return }
+ if (!handlers.onProductUsageReport) { json(503, { error: 'UNAVAILABLE' }); return }
+ let body: unknown
+ try {
+ const raw = await readBody(req, 8192)
+ body = JSON.parse(raw)
+ } catch { json(400, { error: 'BAD_REQUEST' }); return }
+ const report = body as { schemaVersion?: unknown; revision?: unknown; id?: unknown; day?: unknown; counters?: unknown } | null
+ if (!report || typeof report !== 'object' || Object.keys(report).length !== 5 || report.schemaVersion !== 1
+ || typeof report.revision !== 'number' || !Number.isSafeInteger(report.revision) || report.revision < 0
+ || typeof report.id !== 'string' || !/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(report.id)
+ || typeof report.day !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(report.day)
+ || !report.counters || typeof report.counters !== 'object' || Array.isArray(report.counters)
+ || Object.entries(report.counters).some(([key, value]) => !PRODUCT_USAGE_UI_METRICS.includes(key as never)
+ || !Number.isSafeInteger(value) || value < 1 || value > 1000)) {
+ json(400, { error: 'BAD_REQUEST' }); return
+ }
+ try {
+ const result = await handlers.onProductUsageReport(report)
+ json(result.status, result.body)
+ } catch { json(502, { success: false, error: { code: 'USAGE_UNAVAILABLE', message: 'Product usage unavailable' } }) }
+ 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 }
diff --git a/cli/src/lib/productUsageContract.ts b/cli/src/lib/productUsageContract.ts
index 5b86f7317..b520dd9da 100644
--- a/cli/src/lib/productUsageContract.ts
+++ b/cli/src/lib/productUsageContract.ts
@@ -2,14 +2,32 @@
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_FEEDBACK_REASONS = ['useful', 'could_not_finish', 'slow', 'confusing', 'missing_feature'] as const
+export const PRODUCT_FEEDBACK_OUTCOMES = ['completed', 'partly_completed', 'not_completed'] as const
+export const PRODUCT_FEEDBACK = [...PRODUCT_FEEDBACK_REASONS, ...PRODUCT_FEEDBACK_OUTCOMES] as const
+export const PRODUCT_USAGE_ACTIONS = ['create', 'resume', 'restart', 'model_change', 'history',
+ 'fork', 'close', 'delete', 'search', 'history_page', 'store_list', 'store_install', 'store_update', 'store_remove',
+ 'model_list', 'model_download', 'model_start', 'model_stop', 'browser_open'] as const
+export const PRODUCT_USAGE_FEATURE_MEASURES = ['installation_days', 'first_installations', 'repeat_installation_days'] as const
+export const PRODUCT_USAGE_SURFACES = ['desktop', 'phone', 'web'] as const
+export const PRODUCT_USAGE_FLOWS = ['setup', 'setup_harness', 'setup_tmux', 'setup_clipboard', 'sign_in',
+ 'workspace_connect', 'computer_link', 'remote_connect', 'viewer_open', 'update_check', 'update_stage'] as const
+export const PRODUCT_USAGE_FLOW_MEASURES = ['started', 'ok', 'failed', 'cancelled', 'unknown',
+ 'under_1s', '1s_to_10s', '10s_to_1m', 'over_1m'] as const
+export const PRODUCT_USAGE_UI_METRICS = PRODUCT_USAGE_SURFACES.flatMap(surface =>
+ PRODUCT_USAGE_FLOWS.flatMap(flow => PRODUCT_USAGE_FLOW_MEASURES.map(measure => `ui_${surface}_${flow}_${measure}` as const)))
+// A signed-out report is explicitly enabled on this app. It cannot carry account/work metrics.
+export const PRODUCT_USAGE_SETUP_METRICS = PRODUCT_USAGE_SURFACES.flatMap(surface =>
+ (['setup', 'setup_harness', 'setup_tmux', 'setup_clipboard', 'sign_in'] as const).flatMap(flow =>
+ PRODUCT_USAGE_FLOW_MEASURES.map(measure => `setup_${surface}_${flow}_${measure}` 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',
+ 'monthly_working_installations', 'monthly_returning_installations', 'reactivated_after_7d_installations',
+ 'measurement_v2_installation_days', 'measurement_queue_pruned', 'turn_observation_overflow',
'turns_started', 'turns_ended', 'turns_interrupted',
'duration_under_10s', 'duration_10s_to_1m', 'duration_1m_to_5m', 'duration_over_5m',
'desktop_opens', 'tui_opens',
@@ -20,9 +38,11 @@ export const PRODUCT_USAGE_METRICS = [
'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',
+ 'first_response_installations', 'd1_returning_work_installations', 'd7_returning_work_installations', 'd28_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)),
+ ...PRODUCT_USAGE_ACTIONS.flatMap(action => PRODUCT_USAGE_FEATURE_MEASURES.map(measure => `${action}_${measure}` as const)),
+ ...PRODUCT_USAGE_UI_METRICS,
] as const
export type ProductUsageMetric = typeof PRODUCT_USAGE_METRICS[number]
export interface ProductUsageReport {
diff --git a/cli/src/lib/productUsageSignals.spec.ts b/cli/src/lib/productUsageSignals.spec.ts
index 275a6108e..2f2b00e83 100644
--- a/cli/src/lib/productUsageSignals.spec.ts
+++ b/cli/src/lib/productUsageSignals.spec.ts
@@ -29,3 +29,17 @@ it('reduces durable launch statuses to fixed categories without forwarding error
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')
})
+
+
+it('observes Store, search and model operations without their arguments and rejects explicit false outcomes', () => {
+ const emit = vi.fn()
+ productUsageRequest('dsh_install', emit)(undefined, undefined, false, false)
+ productUsageRequest('session_search', emit)(undefined, undefined, false)
+ productUsageRequest('grid_fleet_model_download', emit)('TIMEOUT', undefined, false)
+ expect(emit.mock.calls.flat()).toEqual(expect.arrayContaining([
+ 'store_install_requests', 'store_install_failed', 'search_ok', 'model_download_error_unavailable',
+ ]))
+ const clock = vi.fn()
+ productUsageRequest('terminal_input', emit, clock)
+ expect(clock).not.toHaveBeenCalled()
+})
diff --git a/cli/src/lib/productUsageSignals.ts b/cli/src/lib/productUsageSignals.ts
index 3d29a1d52..f71b0b7ec 100644
--- a/cli/src/lib/productUsageSignals.ts
+++ b/cli/src/lib/productUsageSignals.ts
@@ -1,7 +1,15 @@
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
+ agent_retarget: 'model_change', agent_recent: 'history',
+ agent_fork: 'fork', agent_close: 'close', agent_delete: 'delete',
+ session_search: 'search', session_tail: 'history_page',
+ dsh_list: 'store_list', dsh_install: 'store_install', dsh_update: 'store_update', dsh_remove: 'store_remove',
+ models_list: 'model_list', grid_models_list: 'model_list',
+ grid_fleet_model_download: 'model_download', grid_fleet_model_start: 'model_start', grid_fleet_model_stop: 'model_stop',
+ browser_open: 'browser_open',
+} as const
+const unmeasured = (..._args: unknown[]): void => {}
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'])
@@ -27,6 +35,7 @@ export interface ProductUsageLaunchSignal {
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)
+ if (!known) return unmeasured
const send = (signal: Omit<ProductUsageLaunchSignal, 'id'>) => {
if (known) { try { emit({ id: id as string, ...signal }) } catch { /* Optional measurement. */ } }
}
@@ -47,19 +56,21 @@ export function productUsageLaunch(type: string, id: unknown, emit: (signal: Pro
*/
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
+ // In particular, streaming frames and polling do not allocate clocks or observers.
+ if (!action) return unmeasured
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) => {
+ return (error: unknown, state: unknown, hasAgent: boolean, ok?: unknown) => {
if (!action || answered) return
answered = true
- if (error != null || state === 'failed') {
+ if (error != null || state === 'failed' || ok === false) {
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 if (!['create', 'resume', 'restart', 'fork'].includes(action) || 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/lib/api/api_client.dart b/desktop/lib/api/api_client.dart
index 1964a35df..2def58121 100644
--- a/desktop/lib/api/api_client.dart
+++ b/desktop/lib/api/api_client.dart
@@ -9,7 +9,8 @@ import '../core/test_run.dart';
import '../logging/http_log.dart';
import '../viewer/device_ack.dart';
import '../viewer/device_log.dart';
-import '../viewer/device_log_sync.dart' show DeviceLogAppendAnswer, DeviceLogFetched;
+import '../viewer/device_log_sync.dart'
+ show DeviceLogAppendAnswer, DeviceLogFetched;
import '../ws/local_daemon_transport.dart';
import 'access_token_source.dart';
import 'bearer_auth_interceptor.dart';
@@ -107,6 +108,21 @@ class ApiClient {
}
// -- auth (proxied by the local CLI — no credential on this leg) --
+ Future<Map<String, dynamic>> productUsageReport(
+ Map<String, dynamic> report,
+ ) async {
+ final response = await _dio.post(
+ '/api/product-usage/report',
+ data: report,
+ options: Options(
+ headers: {'x-adapter-local': '1'},
+ receiveTimeout: const Duration(seconds: 5),
+ sendTimeout: const Duration(seconds: 5),
+ ),
+ );
+ return Map<String, dynamic>.from(unwrapApiResponse(response) as Map);
+ }
+
Future<void> productUsageFeedback(String answer, String receipt) async {
final response = await _dio.post(
'/api/product-usage/feedback',
@@ -121,9 +137,15 @@ class ApiClient {
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'}));
+ ? await _dio.get(
+ '/api/product-usage/settings',
+ options: Options(receiveTimeout: const Duration(seconds: 5)),
+ )
+ : 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);
}
@@ -290,11 +312,16 @@ class ApiClient {
/// [self]: this app's own key, which the backend counts as used just now (an older one ignores it).
Future<DeviceLogFetched?> deviceKeys(int since, {String? self}) async {
try {
- final res = await _dio.get('/api/device-keys', queryParameters: {'since': since, 'self': ?self});
+ final res = await _dio.get(
+ '/api/device-keys',
+ queryParameters: {'since': since, 'self': ?self},
+ );
if (res.statusCode != 200) return null;
final data = unwrapApiResponse(res);
if (data is! Map) return null;
- final acct = data['acct'], head = DevLogHead.fromJson(data['head']), entries = data['entries'];
+ final acct = data['acct'],
+ head = DevLogHead.fromJson(data['head']),
+ entries = data['entries'];
if (acct is! String || head == null || entries is! List) return null;
return (acct: acct, head: head, entries: entries.cast<Object?>());
} catch (_) {
@@ -306,14 +333,19 @@ class ApiClient {
/// reached; a refusal comes back as its code (`STALE_HEAD` with the current head).
Future<DeviceLogAppendAnswer?> appendDeviceKey(DevLogEntry entry) async {
try {
- final res = await _dio.post('/api/device-keys', data: {'entry': entry.toJson()});
+ final res = await _dio.post(
+ '/api/device-keys',
+ data: {'entry': entry.toJson()},
+ );
final body = res.data;
if (body is! Map) return null;
final data = body['data'];
final head = data is Map ? DevLogHead.fromJson(data['head']) : null;
if (res.statusCode == 200) return (head: head, error: null);
final error = body['error'];
- final code = error is Map && error['code'] is String ? error['code'] as String : 'HTTP_${res.statusCode}';
+ final code = error is Map && error['code'] is String
+ ? error['code'] as String
+ : 'HTTP_${res.statusCode}';
return (head: head, error: code);
} catch (_) {
return null;
@@ -344,7 +376,10 @@ class ApiClient {
/// devices. False when the backend did not keep it (or predates it).
Future<bool> postDeviceAck(DevAck ack) async {
try {
- final res = await _dio.post('/api/device-keys/acks', data: {'ack': ack.toJson()});
+ final res = await _dio.post(
+ '/api/device-keys/acks',
+ data: {'ack': ack.toJson()},
+ );
return res.statusCode == 200;
} catch (_) {
return false;
@@ -362,7 +397,8 @@ class ApiClient {
return {
if (seen is Map)
for (final e in seen.entries)
- if (e.key is String && e.value is int) e.key as String: e.value as int,
+ if (e.key is String && e.value is int)
+ e.key as String: e.value as int,
};
} catch (_) {
return const {};
@@ -377,7 +413,9 @@ class ApiClient {
try {
final res = await _dio.get('/api/devices');
final data = res.data;
- return res.statusCode == 200 && data is Map<String, dynamic> ? data : null;
+ return res.statusCode == 200 && data is Map<String, dynamic>
+ ? data
+ : null;
} catch (_) {
return null;
}
@@ -394,7 +432,9 @@ class ApiClient {
);
if (res.statusCode == 200) return null;
final data = res.data;
- return data is Map && data['error'] is String ? data['error'] as String : 'HTTP_${res.statusCode}';
+ return data is Map && data['error'] is String
+ ? data['error'] as String
+ : 'HTTP_${res.statusCode}';
} catch (_) {
return 'UNAVAILABLE';
}
@@ -418,11 +458,21 @@ class ApiClient {
/// list. [confirm]: "It's mine" for the one device named — the daemon shares it with the account's
/// other devices (one that predates it ignores the field and only marks it seen). False when the
/// daemon predates the route (an old one answers a `pubs` body with an error).
- Future<bool> daemonDismissDevices({String? pub, List<String>? pubs, bool baseline = false, bool confirm = false}) async {
+ Future<bool> daemonDismissDevices({
+ String? pub,
+ List<String>? pubs,
+ bool baseline = false,
+ bool confirm = false,
+ }) async {
try {
final res = await _dio.post(
'/api/devices/dismiss',
- data: {'pub': ?pub, 'pubs': ?pubs, if (baseline) 'baseline': true, if (confirm) 'confirm': true},
+ data: {
+ 'pub': ?pub,
+ 'pubs': ?pubs,
+ if (baseline) 'baseline': true,
+ if (confirm) 'confirm': true,
+ },
options: Options(headers: {'x-adapter-local': '1'}),
);
return res.statusCode == 200;
@@ -435,7 +485,10 @@ class ApiClient {
/// does it, for the list whose [head] (`{seq, hash}`) the preview showed. Null when the daemon could
/// not read a valid list; `{'error': 'LOG_CHANGED'}` when the list is not the one that was previewed;
/// `{'error': 'OTHER_ACCOUNT'}` when it is another account's than the one this computer is signed in to.
- Future<Map<String, dynamic>?> daemonRebaselineDevices({required bool confirm, Map<String, Object?>? head}) async {
+ Future<Map<String, dynamic>?> daemonRebaselineDevices({
+ required bool confirm,
+ Map<String, Object?>? head,
+ }) async {
try {
final res = await _dio.post(
'/api/devices/rebaseline',
@@ -444,9 +497,15 @@ class ApiClient {
);
final data = res.data;
if (res.statusCode == 409) {
- return {'error': data is Map && data['error'] == 'OTHER_ACCOUNT' ? 'OTHER_ACCOUNT' : 'LOG_CHANGED'};
+ return {
+ 'error': data is Map && data['error'] == 'OTHER_ACCOUNT'
+ ? 'OTHER_ACCOUNT'
+ : 'LOG_CHANGED',
+ };
}
- return res.statusCode == 200 && data is Map<String, dynamic> ? data : null;
+ return res.statusCode == 200 && data is Map<String, dynamic>
+ ? data
+ : null;
} catch (_) {
return null;
}
@@ -661,4 +720,3 @@ String describeApiError(Object error) {
}
return '$error';
}
-
diff --git a/desktop/lib/app_shell.dart b/desktop/lib/app_shell.dart
index fbe3fc134..fb8234d2a 100644
--- a/desktop/lib/app_shell.dart
+++ b/desktop/lib/app_shell.dart
@@ -1,4 +1,5 @@
import 'core/app_version.dart';
+import 'measurement/setup_usage_choice.dart';
import 'dart:async';
import 'dart:ui' show AppExitResponse;
@@ -414,6 +415,13 @@ class _RootShellState extends ConsumerState<RootShell>
if (app.deviceConflict != null && deviceBands)
DeviceConflictNoticeBand(notifier: app),
Expanded(child: framed),
+ if (!kIsWeb &&
+ !home &&
+ (touring ||
+ signInStep ||
+ app.status == AppStatus.preparingEnvironment ||
+ app.status == AppStatus.unauthenticated))
+ SetupUsageChoice(measurement: app.productMeasurement),
],
);
},
diff --git a/desktop/lib/measurement/product_measurement.dart b/desktop/lib/measurement/product_measurement.dart
new file mode 100644
index 000000000..8eb19d2dc
--- /dev/null
+++ b/desktop/lib/measurement/product_measurement.dart
@@ -0,0 +1,336 @@
+import 'dart:async';
+import 'dart:math';
+
+import 'package:flutter/foundation.dart';
+
+enum ProductFlow {
+ setup('setup'),
+ setupHarness('setup_harness'),
+ setupTmux('setup_tmux'),
+ setupClipboard('setup_clipboard'),
+ signIn('sign_in'),
+ workspaceConnect('workspace_connect'),
+ computerLink('computer_link'),
+ remoteConnect('remote_connect'),
+ viewerOpen('viewer_open'),
+ updateCheck('update_check'),
+ updateStage('update_stage');
+
+ const ProductFlow(this.wire);
+ final String wire;
+ bool get beforeSignIn => index <= ProductFlow.signIn.index;
+}
+
+enum ProductOutcome { ok, failed, cancelled, unknown }
+
+typedef ProductReportRequest = Future<Map<String, dynamic>> Function(
+ Map<String, dynamic> report,
+);
+typedef ProductChoiceRequest = Future<Map<String, dynamic>> Function();
+
+/// Fixed counters only: no event log, identifiers, errors, request/response objects or content.
+/// Nothing is saved. Signed-out sharing is an explicit choice for this app session; a close/crash can lose queued counts.
+/// Requests and retries are serialized and never awaited by a product action.
+class ProductMeasurement extends ChangeNotifier {
+ ProductMeasurement({
+ required this.surface,
+ required this.sendSetup,
+ DateTime Function()? now,
+ String Function()? receipt,
+ this.automatic = true,
+ }) : assert(const ['desktop', 'phone', 'web'].contains(surface)),
+ _now = now ?? DateTime.now,
+ _receipt = receipt ?? newProductReceipt {
+ choiceLoaded = true;
+ }
+
+ final String surface;
+ final ProductReportRequest sendSetup;
+ final bool automatic;
+ final DateTime Function() _now;
+ final String Function() _receipt;
+ bool signedOutSharing = false, choiceLoaded = false;
+ bool _disposed = false;
+ Object? _account;
+ bool? _enabled;
+ int _revision = -1, _accountEpoch = 0, _guestEpoch = 0;
+ ProductChoiceRequest? _readChoice;
+ ProductReportRequest? _sendAccount;
+ Timer? _timer;
+ DateTime? _lastAttempt;
+ final _active = <Object, String>{};
+ Future<void>? _flushing;
+ final _days = <String, Map<String, int>>{};
+ final _pending = <String, Map<String, dynamic>>{};
+ final _setup = <ProductFlow, void Function(ProductOutcome)>{};
+ final _setupFacts = <ProductFlow, String>{};
+
+ bool get sharing => _account != null && _enabled == true;
+ bool get _setupAllowed =>
+ surface != 'web' &&
+ signedOutSharing &&
+ (_account == null || _enabled == true);
+
+ Future<void> setSignedOutSharing(bool enabled) async {
+ _guestEpoch++;
+ signedOutSharing = enabled;
+ choiceLoaded = true;
+ _clear('setup');
+ _setup.clear();
+ if (enabled) _observeSetupFacts();
+ notifyListeners();
+ }
+
+ /// The scope is RAM-only and never serialized. A sign-out or account change discards its queue.
+ void account(
+ Object? scope, {
+ ProductChoiceRequest? choice,
+ ProductReportRequest? send,
+ }) {
+ if (_disposed || scope == _account) return;
+ _accountEpoch++;
+ _account = scope;
+ _enabled = null;
+ _revision = -1;
+ _readChoice = choice;
+ _sendAccount = send;
+ _clear('ui');
+ if (scope != null && automatic) unawaited(flush());
+ _schedule();
+ }
+
+ /// A saved switch applies immediately in this app, even while a report is in flight.
+ void savedChoice(Map<String, dynamic> value) {
+ final enabled = value['enabled'], revision = value['revision'];
+ if (enabled is! bool || revision is! int || revision < 0) {
+ _enabled = null;
+ return;
+ }
+ if (revision != _revision || !enabled) {
+ _accountEpoch++;
+ _clear('ui');
+ }
+ _revision = revision;
+ _enabled = enabled;
+ if (!enabled) {
+ _guestEpoch++;
+ signedOutSharing = false;
+ _clear('setup');
+ _setup.clear();
+ }
+ notifyListeners();
+ }
+
+ void _clear(String channel) {
+ _days.removeWhere((key, _) => key.startsWith('$channel:'));
+ _pending.remove(channel);
+ _active.removeWhere((_, value) => value == channel);
+ }
+
+ void Function(ProductOutcome) begin(ProductFlow flow) {
+ final channel = sharing
+ ? 'ui'
+ : flow.beforeSignIn && _setupAllowed
+ ? 'setup'
+ : null;
+ if (_disposed || channel == null || _active.length >= 64) return (_) {};
+ final epoch = channel == 'setup' ? _guestEpoch : _accountEpoch;
+ final started = _now().toUtc();
+ final watch = Stopwatch()..start();
+ final day = started.toIso8601String().substring(0, 10);
+ final prefix = '${channel}_${surface}_${flow.wire}_';
+ final ticket = Object();
+ _active[ticket] = channel;
+ _count(channel, day, '${prefix}started');
+ var done = false;
+ return (outcome) {
+ if (done) return;
+ done = true;
+ if (_active.remove(ticket) == null) return;
+ watch.stop();
+ if (_disposed ||
+ (channel == 'setup'
+ ? epoch != _guestEpoch || !signedOutSharing || _enabled == false
+ : epoch != _accountEpoch || !sharing)) {
+ return;
+ }
+ _count(channel, day, '$prefix${outcome.name}');
+ final ms = watch.elapsedMilliseconds;
+ _count(
+ channel,
+ day,
+ '$prefix${ms < 1000
+ ? 'under_1s'
+ : ms < 10000
+ ? '1s_to_10s'
+ : ms < 60000
+ ? '10s_to_1m'
+ : 'over_1m'}',
+ );
+ };
+ }
+
+ /// The adapter hands over only enum-derived status names, never setup logs or commands.
+ void setupFacts(Map<ProductFlow, String> facts) {
+ _setupFacts
+ ..clear()
+ ..addAll(facts);
+ _observeSetupFacts();
+ }
+
+ void _observeSetupFacts() {
+ if (!_setupAllowed && !sharing) return;
+ for (final entry in _setupFacts.entries) {
+ if (!entry.key.beforeSignIn || entry.key == ProductFlow.signIn) continue;
+ if (const ['pending', 'running', 'needsTerminal'].contains(entry.value)) {
+ _setup.putIfAbsent(entry.key, () => begin(entry.key));
+ } else if (const [
+ 'ready',
+ 'notApplicable',
+ 'failed',
+ 'unavailable',
+ ].contains(entry.value)) {
+ _setup
+ .remove(entry.key)
+ ?.call(
+ const ['ready', 'notApplicable'].contains(entry.value)
+ ? ProductOutcome.ok
+ : ProductOutcome.failed,
+ );
+ }
+ }
+ }
+
+ void _count(String channel, String day, String metric) {
+ final today = _now().toUtc();
+ final date = DateTime.parse(day);
+ if (today.difference(date).inDays > 1 || date.isAfter(today)) return;
+ _days.removeWhere(
+ (key, _) =>
+ today.difference(DateTime.parse(key.split(':')[1])).inDays > 1,
+ );
+ final counters = _days.putIfAbsent('$channel:$day', () => {});
+ counters[metric] = min(1000, (counters[metric] ?? 0) + 1);
+ _schedule();
+ }
+
+ void _schedule() {
+ if (!automatic ||
+ _disposed ||
+ _timer != null ||
+ (_account == null && _days.isEmpty && _pending.isEmpty)) {
+ return;
+ }
+ final delay = _lastAttempt == null
+ ? const Duration(seconds: 2)
+ : Duration(
+ milliseconds: max(
+ 1000,
+ 60000 - _now().difference(_lastAttempt!).inMilliseconds,
+ ),
+ );
+ _timer = Timer(delay, () {
+ _timer = null;
+ unawaited(flush());
+ });
+ }
+
+ Future<void> flush() => _flushing ??= _flush().whenComplete(() {
+ _flushing = null;
+ _schedule();
+ });
+
+ Future<void> _flush() async {
+ if (_disposed) return;
+ _lastAttempt = _now();
+ final account = _account, read = _readChoice;
+ final choiceEpoch = _accountEpoch;
+ if (account != null && read != null) {
+ try {
+ final choice = await read();
+ if (_disposed || account != _account || choiceEpoch != _accountEpoch) {
+ return;
+ }
+ savedChoice(choice);
+ } catch (_) {
+ _enabled = null;
+ return;
+ }
+ }
+ for (final channel in ['setup', 'ui']) {
+ if (_disposed || (channel == 'setup' ? !_setupAllowed : !sharing)) {
+ continue;
+ }
+ final epoch = channel == 'setup' ? _guestEpoch : _accountEpoch;
+ var report = _pending[channel];
+ if (report == null) {
+ final keys = _days.keys.where((k) => k.startsWith('$channel:')).toList()
+ ..sort();
+ if (keys.isEmpty) continue;
+ final key = keys.first, counts = _days[key]!;
+ final batch = Map<String, int>.fromEntries(counts.entries.take(32));
+ for (final metric in batch.keys) {
+ counts.remove(metric);
+ }
+ if (counts.isEmpty) _days.remove(key);
+ report = {
+ 'schemaVersion': 1,
+ 'id': _receipt(),
+ 'day': key.split(':')[1],
+ 'counters': batch,
+ if (channel == 'setup') 'consent': true else 'revision': _revision,
+ };
+ _pending[channel] = report;
+ }
+ if (_now()
+ .toUtc()
+ .difference(DateTime.parse(report['day'] as String))
+ .inDays >
+ 1) {
+ _pending.remove(channel);
+ continue;
+ }
+ try {
+ final result = await (channel == 'setup' ? sendSetup : _sendAccount!)(
+ report,
+ );
+ if (_disposed ||
+ (channel == 'setup'
+ ? epoch != _guestEpoch
+ : epoch != _accountEpoch)) {
+ continue;
+ }
+ if (result['accepted'] == true || result['reason'] == 'EXPIRED') {
+ _pending.remove(channel);
+ }
+ if (result['reason'] == 'CHOICE_CHANGED') {
+ _enabled = null;
+ _clear('ui');
+ _clear('setup');
+ }
+ } catch (_) {
+ /* Same receipt on the next timer. No logs, aggressive retry, or product failure. */
+ }
+ }
+ }
+
+ @override
+ void dispose() {
+ _disposed = true;
+ _timer?.cancel();
+ _days.clear();
+ _pending.clear();
+ _setup.clear();
+ _active.clear();
+ super.dispose();
+ }
+}
+
+String newProductReceipt() {
+ 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)}';
+}
diff --git a/desktop/lib/measurement/setup_transport.dart b/desktop/lib/measurement/setup_transport.dart
new file mode 100644
index 000000000..63fc64b65
--- /dev/null
+++ b/desktop/lib/measurement/setup_transport.dart
@@ -0,0 +1,35 @@
+import 'package:dio/dio.dart';
+import 'package:flutter/foundation.dart';
+
+import '../core/test_run.dart';
+
+/// Separate from every authenticated API client: no auth interceptor, cookie jar or device headers.
+/// Web pre-sign-in collection remains disabled until its transport can guarantee omitted cookies.
+Future<Map<String, dynamic>> sendSetupMeasurement(
+ String base,
+ Map<String, dynamic> report,
+) async {
+ if (kIsWeb) throw StateError('Signed-out web measurement is unavailable');
+ final uri = Uri.parse(base);
+ if (kUnderTest &&
+ !(const ['127.0.0.1', 'localhost', '::1'].contains(uri.host) &&
+ uri.hasPort)) {
+ throw StateError('Tests require an isolated measurement server');
+ }
+ final dio = Dio(
+ BaseOptions(
+ baseUrl: base,
+ connectTimeout: const Duration(seconds: 5),
+ receiveTimeout: const Duration(seconds: 5),
+ sendTimeout: const Duration(seconds: 5),
+ ),
+ );
+ try {
+ final response = await dio.post('/api/product-usage/setup', data: report);
+ final body = response.data;
+ if (body is! Map || body['data'] is! Map) return {};
+ return Map<String, dynamic>.from(body['data'] as Map);
+ } finally {
+ dio.close(force: true);
+ }
+}
diff --git a/desktop/lib/measurement/setup_usage_choice.dart b/desktop/lib/measurement/setup_usage_choice.dart
new file mode 100644
index 000000000..064e20cbc
--- /dev/null
+++ b/desktop/lib/measurement/setup_usage_choice.dart
@@ -0,0 +1,32 @@
+import 'dart:async';
+
+import 'package:flutter/material.dart';
+
+import 'product_measurement.dart';
+
+/// Visible before any optional signed-out report. It never blocks setup or sign-in.
+class SetupUsageChoice extends StatelessWidget {
+ const SetupUsageChoice({super.key, required this.measurement});
+ final ProductMeasurement measurement;
+
+ @override
+ Widget build(BuildContext context) => ListenableBuilder(
+ listenable: measurement,
+ builder: (context, _) => Material(
+ color: Theme.of(context).colorScheme.surface,
+ child: CheckboxListTile(
+ dense: true,
+ controlAffinity: ListTileControlAffinity.leading,
+ value: measurement.signedOutSharing,
+ onChanged: measurement.choiceLoaded
+ ? (value) =>
+ unawaited(measurement.setSignedOutSharing(value == true))
+ : null,
+ title: const Text('Share setup and sign-in counts'),
+ subtitle: const Text(
+ 'Optional for this app session. Help us find setup problems without sharing account details, prompts, or files.',
+ ),
+ ),
+ ),
+ );
+}
diff --git a/desktop/lib/measurement/task_feedback.dart b/desktop/lib/measurement/task_feedback.dart
new file mode 100644
index 000000000..2c026bfee
--- /dev/null
+++ b/desktop/lib/measurement/task_feedback.dart
@@ -0,0 +1,65 @@
+import 'package:flutter/material.dart';
+
+import '../shared/widgets/app_dialog.dart';
+import '../shared/widgets/product_feedback.dart';
+import '../widgets/desktop_chrome.dart';
+
+Future<void> showTaskFeedback(
+ BuildContext context, {
+ required Future<Map<String, dynamic>> Function() choice,
+ required ProductFeedbackRequest send,
+}) async {
+ final permitted = choice();
+ await showAppDialog<void>(
+ context: context,
+ builder: (context) => Dialog(
+ backgroundColor: Colors.transparent,
+ constraints: const BoxConstraints(maxWidth: 520),
+ child: DesktopDialogSurface(
+ child: SingleChildScrollView(
+ child: Column(
+ mainAxisSize: MainAxisSize.min,
+ crossAxisAlignment: CrossAxisAlignment.stretch,
+ children: [
+ DesktopDialogHeader(
+ title: 'Rate task outcome',
+ onClose: () => Navigator.of(context).pop(),
+ ),
+ Padding(
+ padding: const EdgeInsets.fromLTRB(24, 0, 24, 24),
+ child: FutureBuilder(
+ future: permitted,
+ builder: (context, snapshot) =>
+ snapshot.connectionState != ConnectionState.done
+ ? const Text('Checking your sharing preference…')
+ : snapshot.hasError
+ ? const Text(
+ 'Couldn’t check your sharing preference. Try again.',
+ )
+ : snapshot.data?['enabled'] != true
+ ? const Text(
+ 'Product usage sharing is off. You can change it in Settings → Privacy.',
+ )
+ : Column(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ ProductFeedback(
+ key: const ValueKey('outcome'),
+ send: send,
+ outcome: true,
+ ),
+ ProductFeedback(
+ key: const ValueKey('reason'),
+ send: send,
+ ),
+ ],
+ ),
+ ),
+ ),
+ ],
+ ),
+ ),
+ ),
+ ),
+ );
+}
diff --git a/desktop/lib/screens/swarm_screen.dart b/desktop/lib/screens/swarm_screen.dart
index 77ae3f721..2626eea2d 100644
--- a/desktop/lib/screens/swarm_screen.dart
+++ b/desktop/lib/screens/swarm_screen.dart
@@ -110,6 +110,7 @@ import '../widgets/rename_agent_dialog.dart';
import '../widgets/delete_agent_dialog.dart';
import '../widgets/fork_agent_dialog.dart';
import '../widgets/restart_agent_action.dart';
+import '../measurement/task_feedback.dart';
import '../widgets/new_agent_dialog.dart';
import '../widgets/box_chrome.dart';
import '../widgets/new_harness_form.dart';
@@ -6809,6 +6810,7 @@ class _SwarmScreenState extends State<SwarmScreen> {
),
),
'app.add_phone': () => unawaited(_addPhone()),
+ 'app.product_feedback': () => unawaited(showTaskFeedback(context, choice: () => app.api.productUsageSettings(), send: app.api.productUsageFeedback)),
'app.store': _openStore,
'app.daemon': _openCompanions,
'app.daemon_talk': _talkToDaemon,
diff --git a/desktop/lib/settings/sections/privacy_section.dart b/desktop/lib/settings/sections/privacy_section.dart
index 2e2ef6bed..312d918c3 100644
--- a/desktop/lib/settings/sections/privacy_section.dart
+++ b/desktop/lib/settings/sections/privacy_section.dart
@@ -4,6 +4,7 @@ import '../../shared/widgets/section_scaffold.dart';
import '../../shared/widgets/setting_row.dart';
import '../../shared/widgets/product_feedback.dart';
import '../../state/app_state.dart';
+import '../../measurement/setup_usage_choice.dart';
typedef UsagePreferenceRequest = Future<Map<String, dynamic>> Function({
bool? enabled,
@@ -20,12 +21,20 @@ class PrivacySection extends StatelessWidget {
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.',
- )
+ ? notifier.productMeasurement.surface == 'web'
+ ? const Text(
+ 'Product usage sharing is available after sign-in.',
+ )
+ : SetupUsageChoice(measurement: notifier.productMeasurement)
: ProductUsagePreference(
key: ObjectKey(notifier.api),
- request: notifier.api.productUsageSettings,
+ request: ({bool? enabled}) async {
+ final value = await notifier.api.productUsageSettings(
+ enabled: enabled,
+ );
+ notifier.productMeasurement.savedChoice(value);
+ return value;
+ },
feedback: notifier.api.productUsageFeedback,
),
),
@@ -146,7 +155,7 @@ class _ProductUsagePreferenceState extends State<ProductUsagePreference> {
'• 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'
+ '• First response waits, missing responses and error-event counts; first-launch 24-hour response counts and D1/D7/D28 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. '
@@ -156,6 +165,8 @@ class _ProductUsagePreferenceState extends State<ProductUsagePreference> {
'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. '
+ 'Fixed setup, sign-in, connection, viewer and update-stage outcomes; first and repeat feature use; weekly and monthly returns. '
+ 'Optional task feedback sends only your selected outcome or reason. '
'A turn ending does not tell us whether your task succeeded.',
),
],
diff --git a/desktop/lib/shared/widgets/product_feedback.dart b/desktop/lib/shared/widgets/product_feedback.dart
index 2f88e6af6..c8e64cb7c 100644
--- a/desktop/lib/shared/widgets/product_feedback.dart
+++ b/desktop/lib/shared/widgets/product_feedback.dart
@@ -9,8 +9,9 @@ typedef ProductFeedbackRequest = Future<void> Function(
/// A voluntary, fixed-choice response. It carries no task, account or session context.
class ProductFeedback extends StatefulWidget {
- const ProductFeedback({super.key, required this.send});
+ const ProductFeedback({super.key, required this.send, this.outcome = false});
final ProductFeedbackRequest send;
+ final bool outcome;
@override
State<ProductFeedback> createState() => _ProductFeedbackState();
}
@@ -23,6 +24,11 @@ class _ProductFeedbackState extends State<ProductFeedback> {
'confusing': 'Confusing',
'missing_feature': 'Missing a feature',
};
+ static const outcomes = {
+ 'completed': 'Completed',
+ 'partly_completed': 'Partly completed',
+ 'not_completed': 'Not completed',
+ };
final String _receipt = _newReceipt();
String? _answer, _status;
bool _busy = false, _sent = false;
@@ -72,7 +78,9 @@ class _ProductFeedbackState extends State<ProductFeedback> {
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Text(
- 'How did your latest task go?',
+ widget.outcome
+ ? 'Did you finish what you wanted?'
+ : 'How did your latest task go?',
style: Theme.of(context).textTheme.titleSmall,
),
const SizedBox(height: 8),
@@ -84,7 +92,7 @@ class _ProductFeedbackState extends State<ProductFeedback> {
spacing: 8,
runSpacing: 4,
children: [
- for (final choice in choices.entries)
+ for (final choice in (widget.outcome ? outcomes : choices).entries)
OutlinedButton(
onPressed:
_busy || _sent || (_answer != null && _answer != choice.key)
diff --git a/desktop/lib/shortcuts/keymap_commands.dart b/desktop/lib/shortcuts/keymap_commands.dart
index f899a9ebe..236250ebb 100644
--- a/desktop/lib/shortcuts/keymap_commands.dart
+++ b/desktop/lib/shortcuts/keymap_commands.dart
@@ -371,6 +371,8 @@ final harnessCommands = <HarnessCommand>[
],
),
const HarnessCommand('agent.stop', 'Stop Harness', ShortcutGroup.actions),
+ const HarnessCommand('app.product_feedback', 'Rate task outcome', ShortcutGroup.actions,
+ keywords: ['feedback', 'completed', 'useful', 'problem']),
const HarnessCommand('agent.fork', 'Fork Harness', ShortcutGroup.actions),
const HarnessCommand(
'agent.share',
diff --git a/desktop/lib/state/app_state.dart b/desktop/lib/state/app_state.dart
index 68cbf3de4..b5d4d7156 100644
--- a/desktop/lib/state/app_state.dart
+++ b/desktop/lib/state/app_state.dart
@@ -1,3 +1,5 @@
+import '../measurement/product_measurement.dart';
+import '../measurement/setup_transport.dart';
import 'attached_task_delivery.dart';
import 'task_route.dart';
import '../core/permission_modes.dart';
@@ -648,6 +650,8 @@ class AppNotifier extends ChangeNotifier {
AppConfig config;
late ApiClient api;
+ late final ProductMeasurement productMeasurement;
+ final _measurementConnections = <String, void Function(ProductOutcome)>{};
/// Signs in, and says whether this computer is signed in: the harness CLI in a desktop build,
/// [ViewerServices.login] in a viewer build — which has no CLI — under one name, so every call
@@ -3194,6 +3198,7 @@ class AppNotifier extends ChangeNotifier {
AgentPrefetch? agentPrefetch,
this.desktopUpdater,
this.connectionForTest,
+ ProductMeasurement? productMeasurement,
SignInClient? cliLogin,
CliLink? cliLink,
PeerLinkClient? peerLinks,
@@ -3244,6 +3249,19 @@ class AppNotifier extends ChangeNotifier {
this.peerLinks = peerLinks ?? this.viewer?.links ?? this.cliLink;
_autonomousEnv = this.config.autonomousEnv;
api = _newApiClient();
+ this.productMeasurement =
+ productMeasurement ??
+ ProductMeasurement(
+ surface: kIsWeb
+ ? 'web'
+ : this.viewer == null
+ ? 'desktop'
+ : 'phone',
+ automatic: !kUnderTest,
+ sendSetup: (report) =>
+ sendSetupMeasurement(this.config.apiBaseUrl, report),
+ );
+ addListener(_syncProductMeasurement);
_initDeviceLog();
// `grid.AppTheme.palette`, not the prefs store: main.dart copies the saved
// choice into the palette notifier while rebuilding, so the store fires
@@ -3266,6 +3284,48 @@ class AppNotifier extends ChangeNotifier {
appearancePrefsStore.addListener(_autoRenameChanged);
}
+ void _syncProductMeasurement() {
+ final scope =
+ signedIn &&
+ !signingIn &&
+ !signingOut &&
+ status == AppStatus.authenticated &&
+ currentUser?.id != null
+ ? (api, currentUser!.id)
+ : null;
+ productMeasurement.account(
+ scope,
+ choice: () => api.productUsageSettings(),
+ send: api.productUsageReport,
+ );
+ if (scope == null) _measurementConnections.clear();
+ }
+
+ // Connection keys already belong to the app. Only fixed outcomes reach measurement, never the key.
+ void _measureConnection(
+ String key,
+ ConnectionStatus status,
+ ProductFlow flow,
+ ) {
+ if (status == ConnectionStatus.connecting ||
+ status == ConnectionStatus.reconnecting) {
+ if (_measurementConnections.length < 64) {
+ _measurementConnections.putIfAbsent(
+ key,
+ () => productMeasurement.begin(flow),
+ );
+ }
+ } else {
+ _measurementConnections
+ .remove(key)
+ ?.call(
+ status == ConnectionStatus.connected
+ ? ProductOutcome.ok
+ : ProductOutcome.failed,
+ );
+ }
+ }
+
/// Through the local CLI in a desktop build; straight to the backend, signed, in a viewer.
ApiClient _newApiClient() => ApiClient(
config: config,
@@ -4628,6 +4688,22 @@ class AppNotifier extends ChangeNotifier {
/// Shared with [_prepareEnvironment]: runs the provisioner, updates
/// [environmentReadiness] as it streams progress, and reports the outcome.
+ void _measureSetup(EnvironmentReadiness value) {
+ productMeasurement.setupFacts({
+ ProductFlow.setup: switch (value.phase) {
+ EnvironmentSetupPhase.ready => 'ready',
+ EnvironmentSetupPhase.failed => 'failed',
+ _ => 'running',
+ },
+ for (final entry in value.steps.entries)
+ switch (entry.key) {
+ EnvironmentStep.harness => ProductFlow.setupHarness,
+ EnvironmentStep.tmux => ProductFlow.setupTmux,
+ EnvironmentStep.clipboard => ProductFlow.setupClipboard,
+ }: entry.value.name,
+ });
+ }
+
Future<EnvironmentReadiness> _runProvisioner({
EnvironmentReadiness? resumeFrom,
bool install = false,
@@ -4637,6 +4713,7 @@ class AppNotifier extends ChangeNotifier {
final provisioner = environmentProvisioner ?? EnvironmentProvisioner();
final result = await provisioner.ensureReady(
onProgress: (value) {
+ _measureSetup(value);
if (quiet &&
value.phase != EnvironmentSetupPhase.ready &&
value.phase != EnvironmentSetupPhase.failed) {
@@ -4664,6 +4741,7 @@ class AppNotifier extends ChangeNotifier {
install: install,
mode: mode,
);
+ _measureSetup(result);
environmentReadiness = result;
return result;
}
@@ -5832,8 +5910,16 @@ class AppNotifier extends ChangeNotifier {
}
Future<void> _checkForUpdates(Completer<ManualUpdateCheck> completion) async {
+ final finish = productMeasurement.begin(ProductFlow.updateCheck);
try {
final result = await _updater.check();
+ finish(
+ result.status == DesktopUpdateCheckStatus.failed
+ ? ProductOutcome.failed
+ : result.status == DesktopUpdateCheckStatus.disabled
+ ? ProductOutcome.cancelled
+ : ProductOutcome.ok,
+ );
_recordUpdateCheck(result, manual: true);
completion.complete(
ManualUpdateCheck(
@@ -5844,6 +5930,7 @@ class AppNotifier extends ChangeNotifier {
),
);
} catch (error) {
+ finish(ProductOutcome.failed);
debugPrint('AppNotifier.checkForUpdates: $error');
const failed = DesktopUpdateCheck.failed();
_recordUpdateCheck(failed);
@@ -5920,6 +6007,7 @@ class AppNotifier extends ChangeNotifier {
}
// Reassigned once the manifest has been re-read below; the failure messages
// at the end name whichever build was actually attempted.
+ final finish = productMeasurement.begin(ProductFlow.updateStage);
var info = chosen;
isInstallingUpdate = true;
updateDownloadFraction = null;
@@ -5945,6 +6033,7 @@ class AppNotifier extends ChangeNotifier {
// one is keyed on there being an offer — which there is not any more.
// Dropping the offer IS the state, and the dialog that asked turns
// itself into "You're up to date" on the false return.
+ finish(ProductOutcome.cancelled);
availableUpdate = null;
updateError = null;
return false;
@@ -5971,9 +6060,12 @@ class AppNotifier extends ChangeNotifier {
},
);
if (staged == null) {
+ finish(ProductOutcome.failed);
updateError = 'Could not download and verify Harness ${info.version}.';
return false;
}
+ // A staged download is observable; successful relaunch is not. Never delay the update for reporting.
+ finish(ProductOutcome.ok);
final applied = await updater.applyStaged(staged, selfPid: pid);
if (!applied) {
updateError =
@@ -5983,9 +6075,11 @@ class AppNotifier extends ChangeNotifier {
flushAppLog();
exit(0);
} catch (error) {
+ finish(ProductOutcome.failed);
updateError = 'Could not install Harness ${info.version}: $error';
return false;
} finally {
+ finish(ProductOutcome.unknown);
isInstallingUpdate = false;
updateDownloadFraction = null;
if (!_disposed) notifyListeners();
@@ -5996,6 +6090,7 @@ class AppNotifier extends ChangeNotifier {
/// button of its own to name it — the browser opens on the sign-in page's chooser.
Future<void> login([SignInProvider? provider]) async {
if (_disposed || signingIn || signingOut || signOutError != null) return;
+ final measureSignIn = productMeasurement.begin(ProductFlow.signIn);
final wasGuest = isGuest;
final revision = _invalidateAuthWork();
_closedHistory.clear();
@@ -6027,6 +6122,7 @@ class AppNotifier extends ChangeNotifier {
},
);
if (!_authWorkCurrent(revision)) return;
+ measureSignIn(ProductOutcome.ok);
_loginAuthorized = true;
pendingAuthorizeUrl = null;
_resetLoginBrowser();
@@ -6045,6 +6141,7 @@ class AppNotifier extends ChangeNotifier {
// The first sign-in on this computer offers Add Phone; a later one does not.
unawaited(_offerPhoneAfterSignIn(revision));
} catch (error) {
+ measureSignIn(ProductOutcome.failed);
if (!_authWorkCurrent(revision)) return;
status = wasGuest ? AppStatus.authenticated : AppStatus.unauthenticated;
_lastError = error.toString();
@@ -6053,6 +6150,11 @@ class AppNotifier extends ChangeNotifier {
unawaited(_becomeGuest(revision: revision));
}
} finally {
+ measureSignIn(
+ _authWorkCurrent(revision)
+ ? ProductOutcome.unknown
+ : ProductOutcome.cancelled,
+ );
// Takes the in-app browser view down once the redirect has landed; a no-op
// where the page opened in a browser of its own.
unawaited(closeSignInPage());
@@ -6190,6 +6292,7 @@ class AppNotifier extends ChangeNotifier {
client is! PhoneSignInClient) {
return;
}
+ final finish = productMeasurement.begin(ProductFlow.signIn);
final wasGuest = isGuest;
final revision = _invalidateAuthWork();
previousAccountEmail = currentUser?.email;
@@ -6222,6 +6325,7 @@ class AppNotifier extends ChangeNotifier {
},
);
if (!_authWorkCurrent(revision)) return;
+ finish(ProductOutcome.ok);
_loginAuthorized = true;
_clearPhoneSignIn();
notifyListeners();
@@ -6232,6 +6336,7 @@ class AppNotifier extends ChangeNotifier {
}
_guestDeskRestorePending = false;
} catch (error) {
+ finish(ProductOutcome.failed);
if (!_authWorkCurrent(revision)) return;
status = wasGuest ? AppStatus.authenticated : AppStatus.unauthenticated;
_lastError = error.toString();
@@ -6240,6 +6345,11 @@ class AppNotifier extends ChangeNotifier {
unawaited(_becomeGuest(revision: revision));
}
} finally {
+ finish(
+ _authWorkCurrent(revision)
+ ? ProductOutcome.unknown
+ : ProductOutcome.cancelled,
+ );
if (_authWorkCurrent(revision)) {
_loginAuthorized = false;
_clearPhoneSignIn();
@@ -6710,6 +6820,13 @@ class AppNotifier extends ChangeNotifier {
final settling =
nextStatus == ConnectionStatus.disconnected &&
_trustSettling.contains(machineId);
+ _measureConnection(
+ machineId,
+ settling ? ConnectionStatus.connecting : nextStatus,
+ machine.isLocalMachine
+ ? ProductFlow.workspaceConnect
+ : ProductFlow.remoteConnect,
+ );
machine.connectionStatus = settling
? ConnectionStatus.connecting
: nextStatus;
@@ -7653,6 +7770,7 @@ class AppNotifier extends ChangeNotifier {
_MachineLinkAttempt attempt,
void Function(String)? onProgress,
) async {
+ final measureLink = productMeasurement.begin(ProductFlow.computerLink);
String? error;
try {
final result = await peerLinks.connect(
@@ -7687,6 +7805,7 @@ class AppNotifier extends ChangeNotifier {
} catch (_) {
error = 'Could not link this machine. Try again.';
} finally {
+ measureLink(error == null ? ProductOutcome.ok : ProductOutcome.failed);
if (identical(_machineLinks[machineId], attempt)) {
_machineLinks.remove(machineId);
}
@@ -10515,6 +10634,10 @@ class AppNotifier extends ChangeNotifier {
ownerAgentId: agent.id,
);
swarm.panes.insert(insertion, pane);
+ // Counts opening a pane with a URL or a known launch error, not rendering its private page.
+ productMeasurement.begin(ProductFlow.viewerOpen)(
+ agent.viewerError == null ? ProductOutcome.ok : ProductOutcome.failed,
+ );
// The same bookkeeping a split does when it grows the grid by one:
// pins past the insertion slide right, and the shape is re-derived.
swarm.pinnedSlots.updateAll(
@@ -17901,6 +18024,8 @@ class AppNotifier extends ChangeNotifier {
@override
void dispose() {
+ productMeasurement.dispose();
+ _measurementConnections.clear();
if (cliLogin case final CliLogin cli) {
cli.waitingNote.removeListener(_loginWaitingChanged);
}
diff --git a/desktop/test/measurement_controls_test.dart b/desktop/test/measurement_controls_test.dart
new file mode 100644
index 000000000..2579b9f85
--- /dev/null
+++ b/desktop/test/measurement_controls_test.dart
@@ -0,0 +1,126 @@
+import 'dart:io';
+import 'dart:ui' as ui;
+
+import 'package:flutter/material.dart';
+import 'package:flutter/rendering.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/shared/theme/app_theme.dart' as grid;
+
+import 'package:harness/measurement/product_measurement.dart';
+import 'package:harness/measurement/setup_usage_choice.dart';
+import 'package:harness/measurement/task_feedback.dart';
+import 'package:harness/shared/widgets/product_feedback.dart';
+
+import 'support/real_fonts.dart';
+
+void main() {
+ setUpAll(loadRealFonts);
+ for (final brightness in Brightness.values) {
+ for (final scale in [1.0, 1.8]) {
+ testWidgets('measurement controls ${brightness.name} scale $scale', (
+ tester,
+ ) async {
+ tester.view.devicePixelRatio = 1;
+ tester.view.physicalSize = const Size(390, 844);
+ addTearDown(tester.view.reset);
+ final usage = ProductMeasurement(
+ surface: 'phone',
+ automatic: false,
+ sendSetup: (_) async => {},
+ );
+ addTearDown(usage.dispose);
+ final sent = <String>[];
+ final boundary = GlobalKey();
+ await tester.pumpWidget(
+ RepaintBoundary(
+ key: boundary,
+ child: MaterialApp(
+ theme: grid.buildAppTheme(brightness: brightness),
+ builder: (context, child) => MediaQuery(
+ data: MediaQuery.of(context)
+ .copyWith(textScaler: TextScaler.linear(scale)),
+ child: child!,
+ ),
+ home: Scaffold(
+ body: SafeArea(
+ child: SingleChildScrollView(
+ child: Padding(
+ padding: const EdgeInsets.all(16),
+ child: Column(
+ children: [
+ SetupUsageChoice(measurement: usage),
+ ProductFeedback(
+ outcome: true,
+ send: (answer, _) async => sent.add(answer),
+ ),
+ ],
+ ),
+ ),
+ ),
+ ),
+ ),
+ ),
+ ),
+ );
+ await tester.pumpAndSettle();
+ expect(tester.takeException(), isNull);
+ expect(usage.signedOutSharing, isFalse);
+ expect(sent, isEmpty);
+ final output = Platform.environment['HARNESS_MEASUREMENT_CAPTURE_DIR'];
+ if (output != null) {
+ final render =
+ boundary.currentContext!.findRenderObject()!
+ as RenderRepaintBoundary;
+ await tester.runAsync(() async {
+ final picture = await render.toImage(pixelRatio: 1);
+ final bytes = await picture.toByteData(
+ format: ui.ImageByteFormat.png,
+ );
+ await Directory(output).create(recursive: true);
+ await File('$output/controls-${brightness.name}-$scale.png')
+ .writeAsBytes(bytes!.buffer.asUint8List());
+ picture.dispose();
+ });
+ }
+ await tester.tap(find.byType(Checkbox));
+ await tester.pumpAndSettle();
+ expect(usage.signedOutSharing, isTrue);
+ await tester.ensureVisible(find.text('Partly completed'));
+ await tester.tap(find.text('Partly completed'));
+ await tester.pumpAndSettle();
+ expect(sent, ['partly_completed']);
+ expect(tester.takeException(), isNull);
+ });
+ }
+ }
+ testWidgets(
+ 'task feedback honors off and does not expose preference errors',
+ (tester) async {
+ final sent = <String>[];
+ await tester.pumpWidget(
+ MaterialApp(
+ home: Builder(
+ builder: (context) => Scaffold(
+ body: TextButton(
+ onPressed: () => showTaskFeedback(
+ context,
+ choice: () async => {'enabled': false},
+ send: (answer, _) async => sent.add(answer),
+ ),
+ child: const Text('Feedback'),
+ ),
+ ),
+ ),
+ ),
+ );
+ await tester.tap(find.text('Feedback'));
+ await tester.pumpAndSettle();
+ expect(
+ find.textContaining('Product usage sharing is off'),
+ findsOneWidget,
+ );
+ expect(find.text('Completed'), findsNothing);
+ expect(sent, isEmpty);
+ },
+ );
+}
diff --git a/desktop/test/product_measurement_test.dart b/desktop/test/product_measurement_test.dart
new file mode 100644
index 000000000..1418e13d1
--- /dev/null
+++ b/desktop/test/product_measurement_test.dart
@@ -0,0 +1,202 @@
+import 'dart:async';
+import 'dart:convert';
+
+import 'package:flutter_test/flutter_test.dart';
+
+import 'package:harness/measurement/product_measurement.dart';
+
+void main() {
+ late ProductMeasurement usage;
+ late List<Map<String, dynamic>> setup, reports;
+ late Map<String, dynamic> choice;
+ late DateTime now;
+ var fail = false;
+ setUp(() {
+ now = DateTime.utc(2026, 10, 14, 12);
+ setup = [];
+ reports = [];
+ choice = {'enabled': true, 'revision': 0};
+ fail = false;
+ usage = ProductMeasurement(
+ surface: 'desktop',
+ automatic: false,
+ now: () => now,
+ sendSetup: (r) async {
+ setup.add(jsonDecode(jsonEncode(r)));
+ return {'accepted': true};
+ },
+ );
+ });
+ tearDown(() => usage.dispose());
+ Future<void> account([Object id = 'PRIVATE_ACCOUNT']) async {
+ usage.account(
+ id,
+ choice: () async => choice,
+ send: (r) async {
+ reports.add(jsonDecode(jsonEncode(r)));
+ if (fail) throw StateError('PRIVATE_ERROR');
+ return {'accepted': true};
+ },
+ );
+ await usage.flush();
+ }
+
+ test(
+ 'signed-out sharing defaults off and opt-in never replays earlier actions',
+ () async {
+ usage.begin(ProductFlow.signIn)(ProductOutcome.failed);
+ await usage.flush();
+ expect(setup, isEmpty);
+ await usage.setSignedOutSharing(true);
+ final finish = usage.begin(ProductFlow.signIn);
+ finish(ProductOutcome.ok);
+ finish(ProductOutcome.failed);
+ await usage.flush();
+ expect(setup.single.keys.toSet(), {
+ 'schemaVersion',
+ 'consent',
+ 'id',
+ 'day',
+ 'counters',
+ });
+ expect(setup.single['counters'], {
+ 'setup_desktop_sign_in_started': 1,
+ 'setup_desktop_sign_in_ok': 1,
+ 'setup_desktop_sign_in_under_1s': 1,
+ });
+ },
+ );
+ test(
+ 'off and account changes discard queued counts and open observations',
+ () async {
+ await account();
+ final finish = usage.begin(ProductFlow.remoteConnect);
+ choice = {'enabled': false, 'revision': 1};
+ usage.savedChoice(choice);
+ finish(ProductOutcome.ok);
+ await usage.flush();
+ expect(reports, isEmpty);
+ choice = {'enabled': true, 'revision': 2};
+ await usage.flush();
+ usage.begin(ProductFlow.viewerOpen)(ProductOutcome.ok);
+ await account('OTHER_PRIVATE_ACCOUNT');
+ expect(reports, isEmpty);
+ usage.begin(ProductFlow.computerLink)(ProductOutcome.failed);
+ await usage.flush();
+ expect(jsonEncode(reports), isNot(contains('PRIVATE')));
+ expect(
+ (reports.single['counters'] as Map).keys,
+ everyElement(startsWith('ui_desktop_computer_link_')),
+ );
+ },
+ );
+ test(
+ 'retry is immutable, current events wait, and batching is bounded',
+ () async {
+ await account();
+ fail = true;
+ usage.begin(ProductFlow.signIn)(ProductOutcome.ok);
+ await usage.flush();
+ final first = jsonEncode(reports.single);
+ for (final flow in ProductFlow.values) {
+ usage.begin(flow)(ProductOutcome.failed);
+ }
+ await usage.flush();
+ expect(jsonEncode(reports.last), first);
+ fail = false;
+ await usage.flush();
+ expect(jsonEncode(reports.last), first);
+ await usage.flush();
+ await usage.flush();
+ for (final r in reports) {
+ expect((r['counters'] as Map).length, lessThanOrEqualTo(32));
+ expect(utf8.encode(jsonEncode(r)).length, lessThan(4096));
+ }
+ expect(reports.last['id'], isNot(reports.first['id']));
+ },
+ );
+ test(
+ 'stale preference response cannot undo an explicit off choice',
+ () async {
+ final pending = Completer<Map<String, dynamic>>();
+ usage.account(
+ 'PRIVATE_ACCOUNT',
+ choice: () => pending.future,
+ send: (r) async {
+ reports.add(r);
+ return {'accepted': true};
+ },
+ );
+ usage.savedChoice(choice);
+ usage.begin(ProductFlow.remoteConnect)(ProductOutcome.ok);
+ final flushing = usage.flush();
+ usage.savedChoice({'enabled': false, 'revision': 1});
+ pending.complete(choice);
+ await flushing;
+ expect(usage.sharing, isFalse);
+ expect(reports, isEmpty);
+ },
+ );
+ test(
+ 'unknown settings fail closed and account off also clears guest consent',
+ () async {
+ await usage.setSignedOutSharing(true);
+ usage.begin(ProductFlow.signIn)(ProductOutcome.ok);
+ choice = {'enabled': false, 'revision': 1};
+ await account();
+ expect(setup, isEmpty);
+ expect(usage.signedOutSharing, isFalse);
+ usage.savedChoice({'enabled': true});
+ expect(usage.sharing, isFalse);
+ },
+ );
+ test(
+ 'expired RAM queues are discarded and unmatched setup remains unknown',
+ () async {
+ await usage.setSignedOutSharing(true);
+ usage.setupFacts({ProductFlow.setupTmux: 'running'});
+ usage.setupFacts({ProductFlow.setupTmux: 'ready'});
+ usage.setupFacts({ProductFlow.setupTmux: 'ready'});
+ await usage.flush();
+ expect(
+ (setup.single['counters'] as Map)['setup_desktop_setup_tmux_ok'],
+ 1,
+ );
+ usage.begin(ProductFlow.signIn);
+ now = now.add(const Duration(days: 2));
+ await usage.flush();
+ expect(setup.length, 1);
+ },
+ );
+ test(
+ 'flow observations are bounded and unknown operations never upload content',
+ () async {
+ await account();
+ for (var i = 0; i < 1000; i++) {
+ usage.begin(ProductFlow.remoteConnect);
+ }
+ await usage.flush();
+ expect(reports.single['counters'], {
+ 'ui_desktop_remote_connect_started': 64,
+ });
+ },
+ );
+ test(
+ 'web never queues signed-out setup even if a caller enables it',
+ () async {
+ final web = ProductMeasurement(
+ surface: 'web',
+ automatic: false,
+ sendSetup: (r) async {
+ setup.add(r);
+ return {'accepted': true};
+ },
+ );
+ await web.setSignedOutSharing(true);
+ web.begin(ProductFlow.signIn)(ProductOutcome.ok);
+ await web.flush();
+ web.dispose();
+ expect(setup, isEmpty);
+ },
+ );
+}
diff --git a/desktop/test/setup_measurement_transport_test.dart b/desktop/test/setup_measurement_transport_test.dart
new file mode 100644
index 000000000..662207412
--- /dev/null
+++ b/desktop/test/setup_measurement_transport_test.dart
@@ -0,0 +1,53 @@
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/measurement/setup_transport.dart';
+
+void main() {
+ test('signed-out transport uses only a loopback fixture and sends no credentials', () async {
+ final server = await HttpServer.bind(InternetAddress.loopbackIPv4, 0);
+ final received = server.first.then((request) async {
+ expect(request.uri.path, '/api/product-usage/setup');
+ for (final header in [
+ 'authorization',
+ 'cookie',
+ 'x-device-id',
+ 'x-account-id',
+ ]) {
+ expect(request.headers.value(header), isNull);
+ }
+ final body = jsonDecode(await utf8.decoder.bind(request).join());
+ expect(body, {
+ 'schemaVersion': 1,
+ 'consent': true,
+ 'counters': {'setup_desktop_sign_in_started': 1},
+ });
+ request.response.headers.contentType = ContentType.json;
+ request.response.write(
+ jsonEncode({
+ 'success': true,
+ 'data': {'accepted': true},
+ }),
+ );
+ await request.response.close();
+ });
+ try {
+ expect(
+ await sendSetupMeasurement('http://127.0.0.1:${server.port}', {
+ 'schemaVersion': 1,
+ 'consent': true,
+ 'counters': {'setup_desktop_sign_in_started': 1},
+ }),
+ {'accepted': true},
+ );
+ await received;
+ await expectLater(
+ sendSetupMeasurement('https://not-a-fixture.invalid', {}),
+ throwsStateError,
+ );
+ } finally {
+ await server.close(force: true);
+ }
+ });
+}
diff --git a/docs/product-measurement.md b/docs/product-measurement.md
index f11d1b022..3530352f4 100644
--- a/docs/product-measurement.md
+++ b/docs/product-measurement.md
@@ -10,24 +10,70 @@ automatically proven improvement. Changes still need review, tests and a deliber
| --- | --- | --- |
| 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. |
+| Which actions break? | Create, resume, restart, model-change, history, fork, close, delete, search, history paging, Store list/install/update/remove, model list/download/start/stop and browser-open 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. |
+| Do installations return to work? | D1/D7/D28 working-day cohorts, consecutive complete-week and calendar-month returns, return after a seven-day gap | 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 Completed / Partly completed / Not completed plus five fixed reason choices, reachable from Rate task outcome and Privacy | 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,
+| Which features get tried and used again? | First measured installations and daily first/repeat feature reach | Locally deduplicated installation-days, not unique accounts. Some operations are automatic. |
+| Where do app flows break? | Setup, Harness/tmux/clipboard steps, sign-in, workspace/remote connections, computer linking, viewer-pane opening and manual update checking/staging | Fixed started/ok/failed/cancelled/unknown counts and coarse duration buckets. Opening a viewer pane is not rendering its content; staging an update is not a successful relaunch. |
+| Is measurement losing coverage? | Updated collector installation-days, pruned queues, full observation maps, unmatched app starts | Loss signals warrant caution. No signal does not prove complete collection. |
+
+Native signed-out sessions can explicitly enable **Share setup and sign-in counts**. It starts off
+on every app launch, sends no credentials/cookies, and never replays earlier actions. Setup state
+already visible when opted in can start an observation; duration then begins at that observation,
+not necessarily at installation start. An account's off choice disables it once known. Web pre-sign-in
+collection stays disabled because that transport cannot guarantee omitted cookies. These optional,
+untrusted, self-selected counts are a separate population from signed-in app/daemon reports. They
+show observed friction at each step, **not** unique signup conversion or a linked user funnel.
+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.
+Daemon reports combine participating signed-in installations, including staff and both environments.
+App reports are surface-specific operation totals; never add them to daemon or relay counts.
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.
+## Runtime and storage budget
+
+The daemon collector belongs to the gateway service, ordinarily a separate process. The core
+forwards fixed counters with a 64 KiB optional-traffic backpressure limit, never waits for reporting,
+and never wakes a service just to send measurement. Existing lifecycle broadcasts supply scalar
+facts; no extra per-token observer, content reader, thread or database dependency enters the core.
+Unmeasured RPCs return a shared no-op immediately. The `HARNESSD_SERVICES=none` development mode
+runs services inline; it does not provide process isolation.
+
+The gateway coalesces asynchronous disk writes, caps its local queue at 256 KiB / 35 UTC days,
+and bounds in-memory turn/launch observations at 1,000 each. Reports contain at most 64 counters
+and stay below 8 KiB. One sync runs at a time, with five-second network deadlines and a one-minute
+report interval. Unknown or failed preference checks stop collection. Slow or failed reporting can
+lose counts and cannot become a product dependency. A failed disk write also disables collection.
+
+Desktop and phone collectors keep only fixed counters in RAM, at most 64 in-flight observations,
+with at most 32 counters per report, one pending report per channel and one flush at a time.
+Callbacks from product actions never await measurement I/O. Reports retry no faster than once per
+minute with the same random receipt. Send/receive deadlines are five seconds; the authenticated
+app transport retains its existing 15-second connect timeout. Signed-out transport uses five seconds
+for all three phases. Counts expire after
+yesterday; app exit loses RAM counts. Update-stage outcomes may be lost during immediate exit;
+never delay an update to flush analytics. There is no persistent app identifier or local event log.
+
+The signed-out endpoint permits only setup counters and explicit consent, rejects auth/cookie
+headers, limits bodies to 4 KiB and values to 1,000, and admits at most 120 writes/minute and four
+concurrent writes per server process. No IP-based analytics or new rate-limit identity is stored.
+Exhaustion drops measurement rather than affecting sign-in. Public counts remain susceptible to
+fabrication; they are directional diagnostics, not trusted account acquisition metrics.
+
+Both ingestion paths atomically add only UTC-day/metric totals plus an unlinked random retry receipt.
+Receipts expire within 36 days and totals within 396 days through the existing Mongo TTL indexes.
+No account deduplication markers, stable hashes or cross-device histories are introduced. Exact
+people-based DAU/MAU and cross-device retention are deliberately unavailable.
+
## Each daily review
1. Run `cd backend && npm run usage:daily -- 14` with a read-only `DATABASE_URL` supplied through the
@@ -35,7 +81,7 @@ linked to the account so the switch works everywhere.
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.
+ reports can change earlier days. A 24-hour first check can catch friction; D7/D28 and calendar-month returns need their full follow-up windows. Missing metrics stay unknown during rollout, not evidence of zero use.
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.
diff --git a/mobile/lib/api/api_client.dart b/mobile/lib/api/api_client.dart
index 84025a81a..a94d86589 100644
--- a/mobile/lib/api/api_client.dart
+++ b/mobile/lib/api/api_client.dart
@@ -8,13 +8,28 @@ import '../core/models.dart';
import '../logging/http_log.dart';
import '../viewer/device_ack.dart';
import '../viewer/device_log.dart';
-import '../viewer/device_log_sync.dart' show DeviceLogAppendAnswer, DeviceLogFetched;
+import '../viewer/device_log_sync.dart'
+ show DeviceLogAppendAnswer, DeviceLogFetched;
import 'access_token_source.dart';
import 'bearer_auth_interceptor.dart';
import 'multipart_body.dart';
/// Authenticated control-plane REST client for the phone.
class ApiClient {
+ Future<Map<String, dynamic>> productUsageReport(
+ Map<String, dynamic> report,
+ ) async {
+ final response = await _dio.post(
+ '/api/product-usage/report',
+ data: report,
+ options: Options(
+ receiveTimeout: const Duration(seconds: 5),
+ sendTimeout: const Duration(seconds: 5),
+ ),
+ );
+ return Map<String, dynamic>.from(unwrapApiResponse(response) as Map);
+ }
+
Future<void> productUsageFeedback(String answer, String receipt) async {
final response = await _dio.post(
'/api/product-usage/feedback',
@@ -28,8 +43,14 @@ class ApiClient {
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});
+ ? await _dio.get(
+ '/api/product-usage/settings',
+ options: Options(receiveTimeout: const Duration(seconds: 5)),
+ )
+ : await _dio.post(
+ '/api/product-usage/settings',
+ data: {'enabled': enabled},
+ );
return Map<String, dynamic>.from(unwrapApiResponse(response) as Map);
}
@@ -118,11 +139,16 @@ class ApiClient {
/// [self]: this app's own key, which the backend counts as used just now (an older one ignores it).
Future<DeviceLogFetched?> deviceKeys(int since, {String? self}) async {
try {
- final res = await _dio.get('/api/device-keys', queryParameters: {'since': since, 'self': ?self});
+ final res = await _dio.get(
+ '/api/device-keys',
+ queryParameters: {'since': since, 'self': ?self},
+ );
if (res.statusCode != 200) return null;
final data = unwrapApiResponse(res);
if (data is! Map) return null;
- final acct = data['acct'], head = DevLogHead.fromJson(data['head']), entries = data['entries'];
+ final acct = data['acct'],
+ head = DevLogHead.fromJson(data['head']),
+ entries = data['entries'];
if (acct is! String || head == null || entries is! List) return null;
return (acct: acct, head: head, entries: entries.cast<Object?>());
} catch (_) {
@@ -134,14 +160,19 @@ class ApiClient {
/// be reached; a refusal comes back as its code (`STALE_HEAD` with the current head).
Future<DeviceLogAppendAnswer?> appendDeviceKey(DevLogEntry entry) async {
try {
- final res = await _dio.post('/api/device-keys', data: {'entry': entry.toJson()});
+ final res = await _dio.post(
+ '/api/device-keys',
+ data: {'entry': entry.toJson()},
+ );
final body = res.data;
if (body is! Map) return null;
final data = body['data'];
final head = data is Map ? DevLogHead.fromJson(data['head']) : null;
if (res.statusCode == 200) return (head: head, error: null);
final error = body['error'];
- final code = error is Map && error['code'] is String ? error['code'] as String : 'HTTP_${res.statusCode}';
+ final code = error is Map && error['code'] is String
+ ? error['code'] as String
+ : 'HTTP_${res.statusCode}';
return (head: head, error: code);
} catch (_) {
return null;
@@ -172,7 +203,10 @@ class ApiClient {
/// other devices. False when the backend did not keep it (or predates it).
Future<bool> postDeviceAck(DevAck ack) async {
try {
- final res = await _dio.post('/api/device-keys/acks', data: {'ack': ack.toJson()});
+ final res = await _dio.post(
+ '/api/device-keys/acks',
+ data: {'ack': ack.toJson()},
+ );
return res.statusCode == 200;
} catch (_) {
return false;
@@ -190,7 +224,8 @@ class ApiClient {
return {
if (seen is Map)
for (final e in seen.entries)
- if (e.key is String && e.value is int) e.key as String: e.value as int,
+ if (e.key is String && e.value is int)
+ e.key as String: e.value as int,
};
} catch (_) {
return const {};
@@ -206,11 +241,15 @@ class ApiClient {
}
Future<void> approveSignIn(String code) async {
- unwrapApiResponse(await _dio.post('/api/auth/qr/approve', data: {'code': code}));
+ unwrapApiResponse(
+ await _dio.post('/api/auth/qr/approve', data: {'code': code}),
+ );
}
Future<void> denySignIn(String code) async {
- unwrapApiResponse(await _dio.post('/api/auth/qr/deny', data: {'code': code}));
+ unwrapApiResponse(
+ await _dio.post('/api/auth/qr/deny', data: {'code': code}),
+ );
}
// -- the desk: the account's tabs, the same on every computer --
diff --git a/mobile/lib/app_shell.dart b/mobile/lib/app_shell.dart
index 437248283..5b1945b48 100644
--- a/mobile/lib/app_shell.dart
+++ b/mobile/lib/app_shell.dart
@@ -1,3 +1,5 @@
+import 'measurement/setup_usage_choice.dart';
+
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
@@ -240,18 +242,34 @@ class RootShell extends ConsumerWidget {
final app = ref.watch(appStateProvider);
return ListenableBuilder(
listenable: app,
- builder: (context, _) => switch (app.status) {
- // `bootstrapping` covers two unrelated moments: the app starting
- // cold, and a sign-in the user just began. The second keeps the
- // signed-out screen, which carries the wait as a state of its own
- // button; swapping the window for a separate screen there was a
- // hard cut in the middle of a flow, and it is why that button's
- // spinner was almost never seen. Keyed on `signingIn`, which spans
- // the whole of it — see [AppNotifier.signingIn].
- AppStatus.bootstrapping =>
- app.signingIn ? signedOutScreen(app) : bootScreen(app),
- AppStatus.unauthenticated => signedOutScreen(app),
- AppStatus.authenticated => authenticatedScreen(app),
+ builder: (context, _) {
+ final screen = switch (app.status) {
+ // `bootstrapping` covers two unrelated moments: the app starting
+ // cold, and a sign-in the user just began. The second keeps the
+ // signed-out screen, which carries the wait as a state of its own
+ // button; swapping the window for a separate screen there was a
+ // hard cut in the middle of a flow, and it is why that button's
+ // spinner was almost never seen. Keyed on `signingIn`, which spans
+ // the whole of it — see [AppNotifier.signingIn].
+ AppStatus.bootstrapping =>
+ app.signingIn ? signedOutScreen(app) : bootScreen(app),
+ AppStatus.unauthenticated => signedOutScreen(app),
+ AppStatus.authenticated => authenticatedScreen(app),
+ };
+ if (app.productMeasurement.surface == 'web' ||
+ app.status == AppStatus.authenticated ||
+ (app.status == AppStatus.bootstrapping && !app.signingIn)) {
+ return screen;
+ }
+ return Column(
+ children: [
+ Expanded(child: screen),
+ SafeArea(
+ top: false,
+ child: SetupUsageChoice(measurement: app.productMeasurement),
+ ),
+ ],
+ );
},
);
}
diff --git a/mobile/lib/measurement/product_measurement.dart b/mobile/lib/measurement/product_measurement.dart
new file mode 100644
index 000000000..8eb19d2dc
--- /dev/null
+++ b/mobile/lib/measurement/product_measurement.dart
@@ -0,0 +1,336 @@
+import 'dart:async';
+import 'dart:math';
+
+import 'package:flutter/foundation.dart';
+
+enum ProductFlow {
+ setup('setup'),
+ setupHarness('setup_harness'),
+ setupTmux('setup_tmux'),
+ setupClipboard('setup_clipboard'),
+ signIn('sign_in'),
+ workspaceConnect('workspace_connect'),
+ computerLink('computer_link'),
+ remoteConnect('remote_connect'),
+ viewerOpen('viewer_open'),
+ updateCheck('update_check'),
+ updateStage('update_stage');
+
+ const ProductFlow(this.wire);
+ final String wire;
+ bool get beforeSignIn => index <= ProductFlow.signIn.index;
+}
+
+enum ProductOutcome { ok, failed, cancelled, unknown }
+
+typedef ProductReportRequest = Future<Map<String, dynamic>> Function(
+ Map<String, dynamic> report,
+);
+typedef ProductChoiceRequest = Future<Map<String, dynamic>> Function();
+
+/// Fixed counters only: no event log, identifiers, errors, request/response objects or content.
+/// Nothing is saved. Signed-out sharing is an explicit choice for this app session; a close/crash can lose queued counts.
+/// Requests and retries are serialized and never awaited by a product action.
+class ProductMeasurement extends ChangeNotifier {
+ ProductMeasurement({
+ required this.surface,
+ required this.sendSetup,
+ DateTime Function()? now,
+ String Function()? receipt,
+ this.automatic = true,
+ }) : assert(const ['desktop', 'phone', 'web'].contains(surface)),
+ _now = now ?? DateTime.now,
+ _receipt = receipt ?? newProductReceipt {
+ choiceLoaded = true;
+ }
+
+ final String surface;
+ final ProductReportRequest sendSetup;
+ final bool automatic;
+ final DateTime Function() _now;
+ final String Function() _receipt;
+ bool signedOutSharing = false, choiceLoaded = false;
+ bool _disposed = false;
+ Object? _account;
+ bool? _enabled;
+ int _revision = -1, _accountEpoch = 0, _guestEpoch = 0;
+ ProductChoiceRequest? _readChoice;
+ ProductReportRequest? _sendAccount;
+ Timer? _timer;
+ DateTime? _lastAttempt;
+ final _active = <Object, String>{};
+ Future<void>? _flushing;
+ final _days = <String, Map<String, int>>{};
+ final _pending = <String, Map<String, dynamic>>{};
+ final _setup = <ProductFlow, void Function(ProductOutcome)>{};
+ final _setupFacts = <ProductFlow, String>{};
+
+ bool get sharing => _account != null && _enabled == true;
+ bool get _setupAllowed =>
+ surface != 'web' &&
+ signedOutSharing &&
+ (_account == null || _enabled == true);
+
+ Future<void> setSignedOutSharing(bool enabled) async {
+ _guestEpoch++;
+ signedOutSharing = enabled;
+ choiceLoaded = true;
+ _clear('setup');
+ _setup.clear();
+ if (enabled) _observeSetupFacts();
+ notifyListeners();
+ }
+
+ /// The scope is RAM-only and never serialized. A sign-out or account change discards its queue.
+ void account(
+ Object? scope, {
+ ProductChoiceRequest? choice,
+ ProductReportRequest? send,
+ }) {
+ if (_disposed || scope == _account) return;
+ _accountEpoch++;
+ _account = scope;
+ _enabled = null;
+ _revision = -1;
+ _readChoice = choice;
+ _sendAccount = send;
+ _clear('ui');
+ if (scope != null && automatic) unawaited(flush());
+ _schedule();
+ }
+
+ /// A saved switch applies immediately in this app, even while a report is in flight.
+ void savedChoice(Map<String, dynamic> value) {
+ final enabled = value['enabled'], revision = value['revision'];
+ if (enabled is! bool || revision is! int || revision < 0) {
+ _enabled = null;
+ return;
+ }
+ if (revision != _revision || !enabled) {
+ _accountEpoch++;
+ _clear('ui');
+ }
+ _revision = revision;
+ _enabled = enabled;
+ if (!enabled) {
+ _guestEpoch++;
+ signedOutSharing = false;
+ _clear('setup');
+ _setup.clear();
+ }
+ notifyListeners();
+ }
+
+ void _clear(String channel) {
+ _days.removeWhere((key, _) => key.startsWith('$channel:'));
+ _pending.remove(channel);
+ _active.removeWhere((_, value) => value == channel);
+ }
+
+ void Function(ProductOutcome) begin(ProductFlow flow) {
+ final channel = sharing
+ ? 'ui'
+ : flow.beforeSignIn && _setupAllowed
+ ? 'setup'
+ : null;
+ if (_disposed || channel == null || _active.length >= 64) return (_) {};
+ final epoch = channel == 'setup' ? _guestEpoch : _accountEpoch;
+ final started = _now().toUtc();
+ final watch = Stopwatch()..start();
+ final day = started.toIso8601String().substring(0, 10);
+ final prefix = '${channel}_${surface}_${flow.wire}_';
+ final ticket = Object();
+ _active[ticket] = channel;
+ _count(channel, day, '${prefix}started');
+ var done = false;
+ return (outcome) {
+ if (done) return;
+ done = true;
+ if (_active.remove(ticket) == null) return;
+ watch.stop();
+ if (_disposed ||
+ (channel == 'setup'
+ ? epoch != _guestEpoch || !signedOutSharing || _enabled == false
+ : epoch != _accountEpoch || !sharing)) {
+ return;
+ }
+ _count(channel, day, '$prefix${outcome.name}');
+ final ms = watch.elapsedMilliseconds;
+ _count(
+ channel,
+ day,
+ '$prefix${ms < 1000
+ ? 'under_1s'
+ : ms < 10000
+ ? '1s_to_10s'
+ : ms < 60000
+ ? '10s_to_1m'
+ : 'over_1m'}',
+ );
+ };
+ }
+
+ /// The adapter hands over only enum-derived status names, never setup logs or commands.
+ void setupFacts(Map<ProductFlow, String> facts) {
+ _setupFacts
+ ..clear()
+ ..addAll(facts);
+ _observeSetupFacts();
+ }
+
+ void _observeSetupFacts() {
+ if (!_setupAllowed && !sharing) return;
+ for (final entry in _setupFacts.entries) {
+ if (!entry.key.beforeSignIn || entry.key == ProductFlow.signIn) continue;
+ if (const ['pending', 'running', 'needsTerminal'].contains(entry.value)) {
+ _setup.putIfAbsent(entry.key, () => begin(entry.key));
+ } else if (const [
+ 'ready',
+ 'notApplicable',
+ 'failed',
+ 'unavailable',
+ ].contains(entry.value)) {
+ _setup
+ .remove(entry.key)
+ ?.call(
+ const ['ready', 'notApplicable'].contains(entry.value)
+ ? ProductOutcome.ok
+ : ProductOutcome.failed,
+ );
+ }
+ }
+ }
+
+ void _count(String channel, String day, String metric) {
+ final today = _now().toUtc();
+ final date = DateTime.parse(day);
+ if (today.difference(date).inDays > 1 || date.isAfter(today)) return;
+ _days.removeWhere(
+ (key, _) =>
+ today.difference(DateTime.parse(key.split(':')[1])).inDays > 1,
+ );
+ final counters = _days.putIfAbsent('$channel:$day', () => {});
+ counters[metric] = min(1000, (counters[metric] ?? 0) + 1);
+ _schedule();
+ }
+
+ void _schedule() {
+ if (!automatic ||
+ _disposed ||
+ _timer != null ||
+ (_account == null && _days.isEmpty && _pending.isEmpty)) {
+ return;
+ }
+ final delay = _lastAttempt == null
+ ? const Duration(seconds: 2)
+ : Duration(
+ milliseconds: max(
+ 1000,
+ 60000 - _now().difference(_lastAttempt!).inMilliseconds,
+ ),
+ );
+ _timer = Timer(delay, () {
+ _timer = null;
+ unawaited(flush());
+ });
+ }
+
+ Future<void> flush() => _flushing ??= _flush().whenComplete(() {
+ _flushing = null;
+ _schedule();
+ });
+
+ Future<void> _flush() async {
+ if (_disposed) return;
+ _lastAttempt = _now();
+ final account = _account, read = _readChoice;
+ final choiceEpoch = _accountEpoch;
+ if (account != null && read != null) {
+ try {
+ final choice = await read();
+ if (_disposed || account != _account || choiceEpoch != _accountEpoch) {
+ return;
+ }
+ savedChoice(choice);
+ } catch (_) {
+ _enabled = null;
+ return;
+ }
+ }
+ for (final channel in ['setup', 'ui']) {
+ if (_disposed || (channel == 'setup' ? !_setupAllowed : !sharing)) {
+ continue;
+ }
+ final epoch = channel == 'setup' ? _guestEpoch : _accountEpoch;
+ var report = _pending[channel];
+ if (report == null) {
+ final keys = _days.keys.where((k) => k.startsWith('$channel:')).toList()
+ ..sort();
+ if (keys.isEmpty) continue;
+ final key = keys.first, counts = _days[key]!;
+ final batch = Map<String, int>.fromEntries(counts.entries.take(32));
+ for (final metric in batch.keys) {
+ counts.remove(metric);
+ }
+ if (counts.isEmpty) _days.remove(key);
+ report = {
+ 'schemaVersion': 1,
+ 'id': _receipt(),
+ 'day': key.split(':')[1],
+ 'counters': batch,
+ if (channel == 'setup') 'consent': true else 'revision': _revision,
+ };
+ _pending[channel] = report;
+ }
+ if (_now()
+ .toUtc()
+ .difference(DateTime.parse(report['day'] as String))
+ .inDays >
+ 1) {
+ _pending.remove(channel);
+ continue;
+ }
+ try {
+ final result = await (channel == 'setup' ? sendSetup : _sendAccount!)(
+ report,
+ );
+ if (_disposed ||
+ (channel == 'setup'
+ ? epoch != _guestEpoch
+ : epoch != _accountEpoch)) {
+ continue;
+ }
+ if (result['accepted'] == true || result['reason'] == 'EXPIRED') {
+ _pending.remove(channel);
+ }
+ if (result['reason'] == 'CHOICE_CHANGED') {
+ _enabled = null;
+ _clear('ui');
+ _clear('setup');
+ }
+ } catch (_) {
+ /* Same receipt on the next timer. No logs, aggressive retry, or product failure. */
+ }
+ }
+ }
+
+ @override
+ void dispose() {
+ _disposed = true;
+ _timer?.cancel();
+ _days.clear();
+ _pending.clear();
+ _setup.clear();
+ _active.clear();
+ super.dispose();
+ }
+}
+
+String newProductReceipt() {
+ 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)}';
+}
diff --git a/mobile/lib/measurement/setup_transport.dart b/mobile/lib/measurement/setup_transport.dart
new file mode 100644
index 000000000..63fc64b65
--- /dev/null
+++ b/mobile/lib/measurement/setup_transport.dart
@@ -0,0 +1,35 @@
+import 'package:dio/dio.dart';
+import 'package:flutter/foundation.dart';
+
+import '../core/test_run.dart';
+
+/// Separate from every authenticated API client: no auth interceptor, cookie jar or device headers.
+/// Web pre-sign-in collection remains disabled until its transport can guarantee omitted cookies.
+Future<Map<String, dynamic>> sendSetupMeasurement(
+ String base,
+ Map<String, dynamic> report,
+) async {
+ if (kIsWeb) throw StateError('Signed-out web measurement is unavailable');
+ final uri = Uri.parse(base);
+ if (kUnderTest &&
+ !(const ['127.0.0.1', 'localhost', '::1'].contains(uri.host) &&
+ uri.hasPort)) {
+ throw StateError('Tests require an isolated measurement server');
+ }
+ final dio = Dio(
+ BaseOptions(
+ baseUrl: base,
+ connectTimeout: const Duration(seconds: 5),
+ receiveTimeout: const Duration(seconds: 5),
+ sendTimeout: const Duration(seconds: 5),
+ ),
+ );
+ try {
+ final response = await dio.post('/api/product-usage/setup', data: report);
+ final body = response.data;
+ if (body is! Map || body['data'] is! Map) return {};
+ return Map<String, dynamic>.from(body['data'] as Map);
+ } finally {
+ dio.close(force: true);
+ }
+}
diff --git a/mobile/lib/measurement/setup_usage_choice.dart b/mobile/lib/measurement/setup_usage_choice.dart
new file mode 100644
index 000000000..064e20cbc
--- /dev/null
+++ b/mobile/lib/measurement/setup_usage_choice.dart
@@ -0,0 +1,32 @@
+import 'dart:async';
+
+import 'package:flutter/material.dart';
+
+import 'product_measurement.dart';
+
+/// Visible before any optional signed-out report. It never blocks setup or sign-in.
+class SetupUsageChoice extends StatelessWidget {
+ const SetupUsageChoice({super.key, required this.measurement});
+ final ProductMeasurement measurement;
+
+ @override
+ Widget build(BuildContext context) => ListenableBuilder(
+ listenable: measurement,
+ builder: (context, _) => Material(
+ color: Theme.of(context).colorScheme.surface,
+ child: CheckboxListTile(
+ dense: true,
+ controlAffinity: ListTileControlAffinity.leading,
+ value: measurement.signedOutSharing,
+ onChanged: measurement.choiceLoaded
+ ? (value) =>
+ unawaited(measurement.setSignedOutSharing(value == true))
+ : null,
+ title: const Text('Share setup and sign-in counts'),
+ subtitle: const Text(
+ 'Optional for this app session. Help us find setup problems without sharing account details, prompts, or files.',
+ ),
+ ),
+ ),
+ );
+}
diff --git a/mobile/lib/measurement/task_feedback.dart b/mobile/lib/measurement/task_feedback.dart
new file mode 100644
index 000000000..92dceedf4
--- /dev/null
+++ b/mobile/lib/measurement/task_feedback.dart
@@ -0,0 +1,49 @@
+import 'package:flutter/material.dart';
+
+import '../shared/widgets/product_feedback.dart';
+
+Future<void> showTaskFeedback(
+ BuildContext context, {
+ required Future<Map<String, dynamic>> Function() choice,
+ required ProductFeedbackRequest send,
+}) async {
+ final permitted = choice();
+ await showDialog<void>(
+ context: context,
+ builder: (context) => AlertDialog(
+ title: const Text('Rate task outcome'),
+ content: SingleChildScrollView(
+ child: FutureBuilder(
+ future: permitted,
+ builder: (context, snapshot) =>
+ snapshot.connectionState != ConnectionState.done
+ ? const Text('Checking your sharing preference…')
+ : snapshot.hasError
+ ? const Text('Couldn’t check your sharing preference. Try again.')
+ : snapshot.data?['enabled'] != true
+ ? const Text(
+ 'Product usage sharing is off. You can change it in Settings → Privacy.',
+ )
+ : Column(
+ mainAxisSize: MainAxisSize.min,
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ ProductFeedback(
+ key: const ValueKey('outcome'),
+ send: send,
+ outcome: true,
+ ),
+ ProductFeedback(key: const ValueKey('reason'), send: send),
+ ],
+ ),
+ ),
+ ),
+ actions: [
+ TextButton(
+ onPressed: () => Navigator.of(context).pop(),
+ child: const Text('Close'),
+ ),
+ ],
+ ),
+ );
+}
diff --git a/mobile/lib/phone/privacy_page.dart b/mobile/lib/phone/privacy_page.dart
index 1015f7a59..238a864fb 100644
--- a/mobile/lib/phone/privacy_page.dart
+++ b/mobile/lib/phone/privacy_page.dart
@@ -109,8 +109,9 @@ class _PrivacyPageState extends State<PrivacyPage> {
'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. '
+ 'response wait buckets, missing responses and error-event counts, and first-launch 24-hour response counts and D1/D7/D28 working-day returns. '
+ 'Fixed setup, sign-in, connection, viewer and update-stage outcomes; first/repeat feature use and monthly returns. '
+ 'Feedback sends only your selected task outcome or reason. '
'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. '
diff --git a/mobile/lib/phone/settings_page.dart b/mobile/lib/phone/settings_page.dart
index 558040efe..731c71072 100644
--- a/mobile/lib/phone/settings_page.dart
+++ b/mobile/lib/phone/settings_page.dart
@@ -165,7 +165,11 @@ class _Body extends StatelessWidget {
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)),
+ phoneRoute((_) => PrivacyPage(request: ({bool? enabled}) async {
+ final value = await notifier.api.productUsageSettings(enabled: enabled);
+ notifier.productMeasurement.savedChoice(value);
+ return value;
+ }, 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.
diff --git a/mobile/lib/phone/terminal_page.dart b/mobile/lib/phone/terminal_page.dart
index 25fb8d1bf..1667e372b 100644
--- a/mobile/lib/phone/terminal_page.dart
+++ b/mobile/lib/phone/terminal_page.dart
@@ -1,3 +1,4 @@
+import '../measurement/task_feedback.dart';
import 'dart:async';
import 'dart:ui' as ui;
@@ -2350,6 +2351,14 @@ class _TerminalPageState extends State<TerminalPage>
label: 'Leave the sample',
onTap: () => sample.leave(),
),
+ if (SampleMode.maybeOf(context) == null)
+ PhoneSheetAction(
+ icon: LucideIcons.messageSquareText300,
+ label: 'Rate task outcome',
+ onTap: () => showTaskFeedback(context,
+ choice: () => widget.notifier.api.productUsageSettings(),
+ send: widget.notifier.api.productUsageFeedback),
+ ),
PhoneSheetAction(
icon: LucideIcons.settings300,
label: 'Settings',
diff --git a/mobile/lib/shared/widgets/product_feedback.dart b/mobile/lib/shared/widgets/product_feedback.dart
index 2f88e6af6..c8e64cb7c 100644
--- a/mobile/lib/shared/widgets/product_feedback.dart
+++ b/mobile/lib/shared/widgets/product_feedback.dart
@@ -9,8 +9,9 @@ typedef ProductFeedbackRequest = Future<void> Function(
/// A voluntary, fixed-choice response. It carries no task, account or session context.
class ProductFeedback extends StatefulWidget {
- const ProductFeedback({super.key, required this.send});
+ const ProductFeedback({super.key, required this.send, this.outcome = false});
final ProductFeedbackRequest send;
+ final bool outcome;
@override
State<ProductFeedback> createState() => _ProductFeedbackState();
}
@@ -23,6 +24,11 @@ class _ProductFeedbackState extends State<ProductFeedback> {
'confusing': 'Confusing',
'missing_feature': 'Missing a feature',
};
+ static const outcomes = {
+ 'completed': 'Completed',
+ 'partly_completed': 'Partly completed',
+ 'not_completed': 'Not completed',
+ };
final String _receipt = _newReceipt();
String? _answer, _status;
bool _busy = false, _sent = false;
@@ -72,7 +78,9 @@ class _ProductFeedbackState extends State<ProductFeedback> {
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Text(
- 'How did your latest task go?',
+ widget.outcome
+ ? 'Did you finish what you wanted?'
+ : 'How did your latest task go?',
style: Theme.of(context).textTheme.titleSmall,
),
const SizedBox(height: 8),
@@ -84,7 +92,7 @@ class _ProductFeedbackState extends State<ProductFeedback> {
spacing: 8,
runSpacing: 4,
children: [
- for (final choice in choices.entries)
+ for (final choice in (widget.outcome ? outcomes : choices).entries)
OutlinedButton(
onPressed:
_busy || _sent || (_answer != null && _answer != choice.key)
diff --git a/mobile/lib/state/app_state.dart b/mobile/lib/state/app_state.dart
index 1dba0a282..c7af3635c 100644
--- a/mobile/lib/state/app_state.dart
+++ b/mobile/lib/state/app_state.dart
@@ -1,3 +1,7 @@
+import '../core/test_run.dart';
+import '../measurement/product_measurement.dart';
+import '../measurement/setup_transport.dart';
+
import 'dart:async';
import 'dart:math' show Random;
@@ -257,6 +261,8 @@ class AppNotifier extends ChangeNotifier {
final AuthSession session;
AppConfig config;
late ApiClient api;
+ late final ProductMeasurement productMeasurement;
+ final _measurementConnections = <String, void Function(ProductOutcome)>{};
/// Says whether this device is signed in, and signs it out: [ViewerServices.login], the app's own
/// session. The name is the desktop's, where the harness CLI holds the session instead.
@@ -951,6 +957,7 @@ class AppNotifier extends ChangeNotifier {
required AuthSession authSession,
ConfigStore? configStore,
this.connectionForTest,
+ ProductMeasurement? productMeasurement,
SignInClient? cliLogin,
PeerLinkClient? peerLinks,
ViewerServices? viewer,
@@ -997,9 +1004,58 @@ class AppNotifier extends ChangeNotifier {
_groupSyncOverride = groupSync;
_autonomousEnv = this.config.autonomousEnv;
api = _newApiClient();
+ this.productMeasurement =
+ productMeasurement ??
+ ProductMeasurement(
+ surface: kIsWeb ? 'web' : 'phone',
+ automatic: !kUnderTest,
+ sendSetup: (report) =>
+ sendSetupMeasurement(this.config.apiBaseUrl, report),
+ );
+ addListener(_syncProductMeasurement);
_initDeviceLog();
}
+ void _syncProductMeasurement() {
+ final scope =
+ !signingIn &&
+ status == AppStatus.authenticated &&
+ currentUser?.id != null
+ ? (api, currentUser!.id)
+ : null;
+ productMeasurement.account(
+ scope,
+ choice: () => api.productUsageSettings(),
+ send: api.productUsageReport,
+ );
+ if (scope == null) _measurementConnections.clear();
+ }
+
+ // Connection keys already belong to the app. Only fixed outcomes reach measurement, never the key.
+ void _measureConnection(
+ String key,
+ ConnectionStatus status,
+ ProductFlow flow,
+ ) {
+ if (status == ConnectionStatus.connecting ||
+ status == ConnectionStatus.reconnecting) {
+ if (_measurementConnections.length < 64) {
+ _measurementConnections.putIfAbsent(
+ key,
+ () => productMeasurement.begin(flow),
+ );
+ }
+ } else {
+ _measurementConnections
+ .remove(key)
+ ?.call(
+ status == ConnectionStatus.connected
+ ? ProductOutcome.ok
+ : ProductOutcome.failed,
+ );
+ }
+ }
+
/// Straight to the backend, signed with this app's own session.
ApiClient _newApiClient() =>
ApiClient(config: config, session: session, auth: viewer.auth);
@@ -1433,6 +1489,7 @@ class AppNotifier extends ChangeNotifier {
}) async {
final login = viewer.emailLogin;
if (_disposed || signingIn) return;
+ final measureSignIn = productMeasurement.begin(ProductFlow.signIn);
final revision = _invalidateAuthWork();
_closedHistory.clear();
_lastError = null;
@@ -1441,15 +1498,22 @@ class AppNotifier extends ChangeNotifier {
try {
await login.signIn(email: email, code: code);
if (!_authWorkCurrent(revision)) return;
+ measureSignIn(ProductOutcome.ok);
status = AppStatus.bootstrapping;
notifyListeners();
await _enterSignedIn(revision);
} catch (_) {
+ measureSignIn(ProductOutcome.failed);
if (_authWorkCurrent(revision)) {
status = AppStatus.unauthenticated;
}
rethrow;
} finally {
+ measureSignIn(
+ _authWorkCurrent(revision)
+ ? ProductOutcome.unknown
+ : ProductOutcome.cancelled,
+ );
if (_authWorkCurrent(revision)) {
signingIn = false;
notifyListeners();
@@ -1463,6 +1527,7 @@ class AppNotifier extends ChangeNotifier {
Future<void> signInWithScan(String code) async {
final login = viewer.emailLogin;
if (_disposed || signingIn) return;
+ final measureSignIn = productMeasurement.begin(ProductFlow.signIn);
final revision = _invalidateAuthWork();
_closedHistory.clear();
_lastError = null;
@@ -1471,15 +1536,22 @@ class AppNotifier extends ChangeNotifier {
try {
await login.signInWithScan(code, label: phoneClientDescriptor().name);
if (!_authWorkCurrent(revision)) return;
+ measureSignIn(ProductOutcome.ok);
status = AppStatus.bootstrapping;
notifyListeners();
await _enterSignedIn(revision);
} catch (_) {
+ measureSignIn(ProductOutcome.failed);
if (_authWorkCurrent(revision)) {
status = AppStatus.unauthenticated;
}
rethrow;
} finally {
+ measureSignIn(
+ _authWorkCurrent(revision)
+ ? ProductOutcome.unknown
+ : ProductOutcome.cancelled,
+ );
if (_authWorkCurrent(revision)) {
signingIn = false;
notifyListeners();
@@ -1667,7 +1739,10 @@ class AppNotifier extends ChangeNotifier {
);
if (!current()) return;
if (registration == DeviceLogRegistration.frozen) {
- appLog.info('link', '$short refused ($reason): the device list is frozen');
+ appLog.info(
+ 'link',
+ '$short refused ($reason): the device list is frozen',
+ );
// The machine's password form says so (deviceListNeedsReview), from the listing.
unawaited(_syncPendingDevices());
_trustRounds[machineId] = _trustSettleRounds;
@@ -1678,7 +1753,10 @@ class AppNotifier extends ChangeNotifier {
return;
}
if (registration == DeviceLogRegistration.registered) {
- appLog.info('link', '$short refused ($reason): this phone joined the device list');
+ appLog.info(
+ 'link',
+ '$short refused ($reason): this phone joined the device list',
+ );
}
final pinned = await _holdsMachineKey(machineId);
if (!current()) return;
@@ -1783,6 +1861,11 @@ class AppNotifier extends ChangeNotifier {
final settling =
nextStatus == ConnectionStatus.disconnected &&
_trustSettling.contains(machineId);
+ _measureConnection(
+ machineId,
+ settling ? ConnectionStatus.connecting : nextStatus,
+ ProductFlow.remoteConnect,
+ );
machine.connectionStatus = settling
? ConnectionStatus.connecting
: nextStatus;
@@ -1886,7 +1969,9 @@ class AppNotifier extends ChangeNotifier {
/// fact the log keeps itself ([_beginDeviceLogSignIn]), never something the backend says, so
/// there is nothing to read first.
void _registerDeviceLog(int revision) {
- if (!_authWorkCurrent(revision) || status != AppStatus.authenticated || _deviceLogRegistered == revision) {
+ if (!_authWorkCurrent(revision) ||
+ status != AppStatus.authenticated ||
+ _deviceLogRegistered == revision) {
return;
}
_deviceLogRegistered = revision;
@@ -1895,10 +1980,9 @@ class AppNotifier extends ChangeNotifier {
// Normally already begun at the top of [_finishBootstrapSignedIn]; a no-op then.
_beginDeviceLogSignIn(revision);
unawaited(
- log
- .register()
- // Then what is still pending from before (a restart) comes back as the banner.
- .whenComplete(_syncPendingDevices),
+ log.register()
+ // Then what is still pending from before (a restart) comes back as the banner.
+ .whenComplete(_syncPendingDevices),
);
}
@@ -2172,28 +2256,37 @@ class AppNotifier extends ChangeNotifier {
void Function(String stage)? onProgress,
}) async {
if (password.isEmpty) return 'Enter the remote password first';
- final result = await peerLinks.connect(
- machineId,
- password,
- onProgress: onProgress,
- displayName: machineStates[machineId]?.machine.displayName,
- label: phoneClientDescriptor().name,
- );
- if (result.error != null) return result.error;
- final targetId = result.linkedMachineId ?? machineId;
- final state = machineStates[targetId];
- if (state != null) {
- state.needsLink = false;
- state.agentLoadStatus = AgentLoadStatus.idle;
- notifyListeners();
- // The old WsConn closed itself permanently on NO_PEER_LINK — connFor() would otherwise see a
- // matching endpointKey and hand back that dead connection instead of dialing a fresh one.
- await _pool?.closeMachine(targetId);
- _connectMachine(state);
+ final finish = productMeasurement.begin(ProductFlow.computerLink);
+ try {
+ final result = await peerLinks.connect(
+ machineId,
+ password,
+ onProgress: onProgress,
+ displayName: machineStates[machineId]?.machine.displayName,
+ label: phoneClientDescriptor().name,
+ );
+ finish(result.error == null ? ProductOutcome.ok : ProductOutcome.failed);
+ if (result.error != null) return result.error;
+ final targetId = result.linkedMachineId ?? machineId;
+ final state = machineStates[targetId];
+ if (state != null) {
+ state.needsLink = false;
+ state.agentLoadStatus = AgentLoadStatus.idle;
+ notifyListeners();
+ // The old WsConn closed itself permanently on NO_PEER_LINK — connFor() would otherwise see a
+ // matching endpointKey and hand back that dead connection instead of dialing a fresh one.
+ await _pool?.closeMachine(targetId);
+ _connectMachine(state);
+ }
+ // One password, the whole group: this machine learns the phone's other machines, and they it.
+ unawaited(_syncGroup(targetId, spread: true));
+ return null;
+ } catch (_) {
+ finish(ProductOutcome.failed);
+ rethrow;
+ } finally {
+ finish(ProductOutcome.unknown);
}
- // One password, the whole group: this machine learns the phone's other machines, and they it.
- unawaited(_syncGroup(targetId, spread: true));
- return null;
}
// -- the account's devices: the device key log (viewer/device_log_sync.dart) --------------------
@@ -2304,7 +2397,11 @@ class AppNotifier extends ChangeNotifier {
/// [confirm]: "It's mine" for the one device named — the account's other devices are told too, and
/// stop showing it as new.
- Future<void> _dismissInLog({String? pub, List<String>? pubs, bool confirm = false}) async {
+ Future<void> _dismissInLog({
+ String? pub,
+ List<String>? pubs,
+ bool confirm = false,
+ }) async {
final log = _deviceLog;
if (log == null) return;
try {
@@ -2321,7 +2418,10 @@ class AppNotifier extends ChangeNotifier {
// This phone's own key rides each read, so the backend counts it as used (not as abandoned).
fetch: (since) async => api.deviceKeys(
since,
- self: await viewer.keys.identity().then<String?>((i) => b64e(i.pub), onError: (Object _) => null),
+ self: await viewer.keys.identity().then<String?>(
+ (i) => b64e(i.pub),
+ onError: (Object _) => null,
+ ),
),
append: (entry) => api.appendDeviceKey(entry),
// "It's mine", once for the account: read what other devices confirmed, share what this one does.
@@ -2337,12 +2437,15 @@ class AppNotifier extends ChangeNotifier {
newDevices.add(m);
devicesRevision++;
final name = m.label.isEmpty ? 'A device' : m.label;
- unawaited(agentNotices.system.showAccountNotice(
- key: m.pub,
- title: 'New device on your account',
- body: '$name ${m.kind == 'machine' ? 'joined' : 'signed in to'} your account and can reach '
- 'your machines. Not yours? Remove it in Settings ▸ Your devices.',
- ));
+ unawaited(
+ agentNotices.system.showAccountNotice(
+ key: m.pub,
+ title: 'New device on your account',
+ body:
+ '$name ${m.kind == 'machine' ? 'joined' : 'signed in to'} your account and can reach '
+ 'your machines. Not yours? Remove it in Settings ▸ Your devices.',
+ ),
+ );
if (!_disposed) notifyListeners();
}),
onRemoved: (n) => _whenSignedIn(() => announceDeviceRemoval(n)),
@@ -2368,11 +2471,13 @@ class AppNotifier extends ChangeNotifier {
if (deviceRemovals.any((r) => r.pub == n.pub)) return;
deviceRemovals.add(n);
devicesRevision++;
- unawaited(agentNotices.system.showAccountNotice(
- key: n.red ? 'removedBy:${n.signer}:${n.pub}' : 'removed:${n.pub}',
- title: n.title,
- body: n.sentence,
- ));
+ unawaited(
+ agentNotices.system.showAccountNotice(
+ key: n.red ? 'removedBy:${n.signer}:${n.pub}' : 'removed:${n.pub}',
+ title: n.title,
+ body: n.sentence,
+ ),
+ );
if (!_disposed) notifyListeners();
}
@@ -2400,10 +2505,14 @@ class AppNotifier extends ChangeNotifier {
} catch (_) {
return;
}
- if (_disposed || gen != _pendingSyncGen || status != AppStatus.authenticated) return;
+ if (_disposed ||
+ gen != _pendingSyncGen ||
+ status != AppStatus.authenticated)
+ return;
final frozen = listing.frozen != null;
final tooMany = listing.registerError == 'TOO_MANY';
- final frozenChanged = frozen != _deviceListFrozen || tooMany != _deviceListTooMany;
+ final frozenChanged =
+ frozen != _deviceListFrozen || tooMany != _deviceListTooMany;
_deviceListFrozen = frozen;
_deviceListTooMany = tooMany;
final pending = listing.pending.toSet();
@@ -2424,9 +2533,14 @@ class AppNotifier extends ChangeNotifier {
for (final d in listing.departed)
if (!_failedDismissals.contains(d.pub)) d,
];
- final same = listEquals([for (final m in next) m.pub], [for (final m in newDevices) m.pub]);
- final sameDeparted =
- listEquals([for (final d in nextDeparted) d.pub], [for (final d in departedDevices) d.pub]);
+ final same = listEquals(
+ [for (final m in next) m.pub],
+ [for (final m in newDevices) m.pub],
+ );
+ final sameDeparted = listEquals(
+ [for (final d in nextDeparted) d.pub],
+ [for (final d in departedDevices) d.pub],
+ );
if (same && sameDeparted && !frozenChanged) return;
newDevices
..clear()
@@ -2462,7 +2576,8 @@ class AppNotifier extends ChangeNotifier {
/// The account's devices as this phone verified them. A seam of its own so a test can answer
/// without a real device log.
- Future<DeviceLogListing> deviceListing() async => await _deviceLog?.list() ?? DeviceLogListing.empty;
+ Future<DeviceLogListing> deviceListing() async =>
+ await _deviceLog?.list() ?? DeviceLogListing.empty;
DateTime? _deviceLogReadAt;
@@ -2473,7 +2588,9 @@ class AppNotifier extends ChangeNotifier {
final log = _deviceLog;
if (log == null) return;
final now = DateTime.now();
- if (_deviceLogReadAt case final last? when now.difference(last) < const Duration(seconds: 30)) return;
+ if (_deviceLogReadAt case final last?
+ when now.difference(last) < const Duration(seconds: 30))
+ return;
_deviceLogReadAt = now;
unawaited(log.ensureRegistered());
}
@@ -2485,14 +2602,20 @@ class AppNotifier extends ChangeNotifier {
/// [shown] is the banner's set as it was when the list was read: pass it when the page awaited
/// anything in between, or a device announced meanwhile — never shown — would be dismissed unseen.
/// Without it, the banner as it is now.
- void seenNewDevices({Iterable<String> pending = const [], Iterable<String>? shown}) {
+ void seenNewDevices({
+ Iterable<String> pending = const [],
+ Iterable<String>? shown,
+ }) {
final bannerPubs = (shown ?? newDevices.map((d) => d.pub)).toList();
if (bannerPubs.isEmpty && pending.isEmpty) return;
// Exactly what was shown, never "all": a device added since (and not yet shown) stays pending.
// And a device that left before anyone looked is cleared by its own "Got it" only: opening the
// list is not that.
final departed = {for (final d in departedDevices) d.pub};
- final marked = {...pending, ...bannerPubs}.where((p) => !departed.contains(p)).toList();
+ final marked = {
+ ...pending,
+ ...bannerPubs,
+ }.where((p) => !departed.contains(p)).toList();
// Nothing marked: a read of `pending` under way (the one a startup replay starts, which takes a
// departed key's stale "New device" down) is not stale — let it land.
if (marked.isEmpty) return;
@@ -2518,7 +2641,11 @@ class AppNotifier extends ChangeNotifier {
return;
}
_pendingSyncGen++;
- unawaited(liftSuspension ? _dismissInLog(pub: pub, confirm: true) : _dismissInLog(pubs: [pub], confirm: true));
+ unawaited(
+ liftSuspension
+ ? _dismissInLog(pub: pub, confirm: true)
+ : _dismissInLog(pubs: [pub], confirm: true),
+ );
notifyListeners();
}
@@ -2534,7 +2661,8 @@ class AppNotifier extends ChangeNotifier {
/// Every add and remove on the account as this phone verified it. A seam of its own so a test can
/// answer without a real device log.
Future<DeviceLogHistory> deviceHistory() async =>
- await _deviceLog?.history() ?? const DeviceLogHistory(rows: [], complete: false);
+ await _deviceLog?.history() ??
+ const DeviceLogHistory(rows: [], complete: false);
/// Take [pub] out of the account on every device. Null when done, else why not.
Future<String?> removeDevice(String pub) async {
@@ -2562,23 +2690,32 @@ class AppNotifier extends ChangeNotifier {
/// Pairs with [machineId] by the one-time code its desktop app showed, then reconnects it — the
/// QR's way in, where [connectWithPassword] is the password's. Null on success, or what to show.
Future<String?> connectWithCode(String machineId, String code) async {
- final result = await peerLinks.connectWithCode(
- machineId,
- code,
- label: phoneClientDescriptor().name,
- displayName: machineStates[machineId]?.machine.displayName,
- );
- if (result.error != null) return result.error;
- final state = machineStates[result.linkedMachineId ?? machineId];
- if (state != null) {
- state.needsLink = false;
- state.agentLoadStatus = AgentLoadStatus.idle;
- notifyListeners();
- await _pool?.closeMachine(state.machine.machineId);
- _connectMachine(state);
+ final finish = productMeasurement.begin(ProductFlow.computerLink);
+ try {
+ final result = await peerLinks.connectWithCode(
+ machineId,
+ code,
+ label: phoneClientDescriptor().name,
+ displayName: machineStates[machineId]?.machine.displayName,
+ );
+ finish(result.error == null ? ProductOutcome.ok : ProductOutcome.failed);
+ if (result.error != null) return result.error;
+ final state = machineStates[result.linkedMachineId ?? machineId];
+ if (state != null) {
+ state.needsLink = false;
+ state.agentLoadStatus = AgentLoadStatus.idle;
+ notifyListeners();
+ await _pool?.closeMachine(state.machine.machineId);
+ _connectMachine(state);
+ }
+ unawaited(_syncGroup(result.linkedMachineId ?? machineId, spread: true));
+ return null;
+ } catch (_) {
+ finish(ProductOutcome.failed);
+ rethrow;
+ } finally {
+ finish(ProductOutcome.unknown);
}
- unawaited(_syncGroup(result.linkedMachineId ?? machineId, spread: true));
- return null;
}
/// A test's stand-in for the trust-group roster swap; null uses [DirectLink.syncGroup].
@@ -6358,6 +6495,8 @@ class AppNotifier extends ChangeNotifier {
@override
void dispose() {
+ productMeasurement.dispose();
+ _measurementConnections.clear();
_disposed = true;
_closedHistory.clear();
_stopAccountTimers();
diff --git a/mobile/test/measurement_controls_test.dart b/mobile/test/measurement_controls_test.dart
new file mode 100644
index 000000000..dd3482d52
--- /dev/null
+++ b/mobile/test/measurement_controls_test.dart
@@ -0,0 +1,126 @@
+import 'dart:io';
+import 'dart:ui' as ui;
+
+import 'package:flutter/material.dart';
+import 'package:flutter/rendering.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness_mobile/shared/theme/app_theme.dart' as grid;
+
+import 'package:harness_mobile/measurement/product_measurement.dart';
+import 'package:harness_mobile/measurement/setup_usage_choice.dart';
+import 'package:harness_mobile/measurement/task_feedback.dart';
+import 'package:harness_mobile/shared/widgets/product_feedback.dart';
+
+import 'support/real_fonts.dart';
+
+void main() {
+ setUpAll(loadRealFonts);
+ for (final brightness in Brightness.values) {
+ for (final scale in [1.0, 1.8]) {
+ testWidgets('measurement controls ${brightness.name} scale $scale', (
+ tester,
+ ) async {
+ tester.view.devicePixelRatio = 1;
+ tester.view.physicalSize = const Size(390, 844);
+ addTearDown(tester.view.reset);
+ final usage = ProductMeasurement(
+ surface: 'phone',
+ automatic: false,
+ sendSetup: (_) async => {},
+ );
+ addTearDown(usage.dispose);
+ final sent = <String>[];
+ final boundary = GlobalKey();
+ await tester.pumpWidget(
+ RepaintBoundary(
+ key: boundary,
+ child: MaterialApp(
+ theme: grid.buildAppTheme(brightness: brightness),
+ builder: (context, child) => MediaQuery(
+ data: MediaQuery.of(context)
+ .copyWith(textScaler: TextScaler.linear(scale)),
+ child: child!,
+ ),
+ home: Scaffold(
+ body: SafeArea(
+ child: SingleChildScrollView(
+ child: Padding(
+ padding: const EdgeInsets.all(16),
+ child: Column(
+ children: [
+ SetupUsageChoice(measurement: usage),
+ ProductFeedback(
+ outcome: true,
+ send: (answer, _) async => sent.add(answer),
+ ),
+ ],
+ ),
+ ),
+ ),
+ ),
+ ),
+ ),
+ ),
+ );
+ await tester.pumpAndSettle();
+ expect(tester.takeException(), isNull);
+ expect(usage.signedOutSharing, isFalse);
+ expect(sent, isEmpty);
+ final output = Platform.environment['HARNESS_MEASUREMENT_CAPTURE_DIR'];
+ if (output != null) {
+ final render =
+ boundary.currentContext!.findRenderObject()!
+ as RenderRepaintBoundary;
+ await tester.runAsync(() async {
+ final picture = await render.toImage(pixelRatio: 1);
+ final bytes = await picture.toByteData(
+ format: ui.ImageByteFormat.png,
+ );
+ await Directory(output).create(recursive: true);
+ await File('$output/controls-${brightness.name}-$scale.png')
+ .writeAsBytes(bytes!.buffer.asUint8List());
+ picture.dispose();
+ });
+ }
+ await tester.tap(find.byType(Checkbox));
+ await tester.pumpAndSettle();
+ expect(usage.signedOutSharing, isTrue);
+ await tester.ensureVisible(find.text('Partly completed'));
+ await tester.tap(find.text('Partly completed'));
+ await tester.pumpAndSettle();
+ expect(sent, ['partly_completed']);
+ expect(tester.takeException(), isNull);
+ });
+ }
+ }
+ testWidgets(
+ 'task feedback honors off and does not expose preference errors',
+ (tester) async {
+ final sent = <String>[];
+ await tester.pumpWidget(
+ MaterialApp(
+ home: Builder(
+ builder: (context) => Scaffold(
+ body: TextButton(
+ onPressed: () => showTaskFeedback(
+ context,
+ choice: () async => {'enabled': false},
+ send: (answer, _) async => sent.add(answer),
+ ),
+ child: const Text('Feedback'),
+ ),
+ ),
+ ),
+ ),
+ );
+ await tester.tap(find.text('Feedback'));
+ await tester.pumpAndSettle();
+ expect(
+ find.textContaining('Product usage sharing is off'),
+ findsOneWidget,
+ );
+ expect(find.text('Completed'), findsNothing);
+ expect(sent, isEmpty);
+ },
+ );
+}
diff --git a/mobile/test/product_measurement_test.dart b/mobile/test/product_measurement_test.dart
new file mode 100644
index 000000000..6e480a004
--- /dev/null
+++ b/mobile/test/product_measurement_test.dart
@@ -0,0 +1,202 @@
+import 'dart:async';
+import 'dart:convert';
+
+import 'package:flutter_test/flutter_test.dart';
+
+import 'package:harness_mobile/measurement/product_measurement.dart';
+
+void main() {
+ late ProductMeasurement usage;
+ late List<Map<String, dynamic>> setup, reports;
+ late Map<String, dynamic> choice;
+ late DateTime now;
+ var fail = false;
+ setUp(() {
+ now = DateTime.utc(2026, 10, 14, 12);
+ setup = [];
+ reports = [];
+ choice = {'enabled': true, 'revision': 0};
+ fail = false;
+ usage = ProductMeasurement(
+ surface: 'desktop',
+ automatic: false,
+ now: () => now,
+ sendSetup: (r) async {
+ setup.add(jsonDecode(jsonEncode(r)));
+ return {'accepted': true};
+ },
+ );
+ });
+ tearDown(() => usage.dispose());
+ Future<void> account([Object id = 'PRIVATE_ACCOUNT']) async {
+ usage.account(
+ id,
+ choice: () async => choice,
+ send: (r) async {
+ reports.add(jsonDecode(jsonEncode(r)));
+ if (fail) throw StateError('PRIVATE_ERROR');
+ return {'accepted': true};
+ },
+ );
+ await usage.flush();
+ }
+
+ test(
+ 'signed-out sharing defaults off and opt-in never replays earlier actions',
+ () async {
+ usage.begin(ProductFlow.signIn)(ProductOutcome.failed);
+ await usage.flush();
+ expect(setup, isEmpty);
+ await usage.setSignedOutSharing(true);
+ final finish = usage.begin(ProductFlow.signIn);
+ finish(ProductOutcome.ok);
+ finish(ProductOutcome.failed);
+ await usage.flush();
+ expect(setup.single.keys.toSet(), {
+ 'schemaVersion',
+ 'consent',
+ 'id',
+ 'day',
+ 'counters',
+ });
+ expect(setup.single['counters'], {
+ 'setup_desktop_sign_in_started': 1,
+ 'setup_desktop_sign_in_ok': 1,
+ 'setup_desktop_sign_in_under_1s': 1,
+ });
+ },
+ );
+ test(
+ 'off and account changes discard queued counts and open observations',
+ () async {
+ await account();
+ final finish = usage.begin(ProductFlow.remoteConnect);
+ choice = {'enabled': false, 'revision': 1};
+ usage.savedChoice(choice);
+ finish(ProductOutcome.ok);
+ await usage.flush();
+ expect(reports, isEmpty);
+ choice = {'enabled': true, 'revision': 2};
+ await usage.flush();
+ usage.begin(ProductFlow.viewerOpen)(ProductOutcome.ok);
+ await account('OTHER_PRIVATE_ACCOUNT');
+ expect(reports, isEmpty);
+ usage.begin(ProductFlow.computerLink)(ProductOutcome.failed);
+ await usage.flush();
+ expect(jsonEncode(reports), isNot(contains('PRIVATE')));
+ expect(
+ (reports.single['counters'] as Map).keys,
+ everyElement(startsWith('ui_desktop_computer_link_')),
+ );
+ },
+ );
+ test(
+ 'retry is immutable, current events wait, and batching is bounded',
+ () async {
+ await account();
+ fail = true;
+ usage.begin(ProductFlow.signIn)(ProductOutcome.ok);
+ await usage.flush();
+ final first = jsonEncode(reports.single);
+ for (final flow in ProductFlow.values) {
+ usage.begin(flow)(ProductOutcome.failed);
+ }
+ await usage.flush();
+ expect(jsonEncode(reports.last), first);
+ fail = false;
+ await usage.flush();
+ expect(jsonEncode(reports.last), first);
+ await usage.flush();
+ await usage.flush();
+ for (final r in reports) {
+ expect((r['counters'] as Map).length, lessThanOrEqualTo(32));
+ expect(utf8.encode(jsonEncode(r)).length, lessThan(4096));
+ }
+ expect(reports.last['id'], isNot(reports.first['id']));
+ },
+ );
+ test(
+ 'stale preference response cannot undo an explicit off choice',
+ () async {
+ final pending = Completer<Map<String, dynamic>>();
+ usage.account(
+ 'PRIVATE_ACCOUNT',
+ choice: () => pending.future,
+ send: (r) async {
+ reports.add(r);
+ return {'accepted': true};
+ },
+ );
+ usage.savedChoice(choice);
+ usage.begin(ProductFlow.remoteConnect)(ProductOutcome.ok);
+ final flushing = usage.flush();
+ usage.savedChoice({'enabled': false, 'revision': 1});
+ pending.complete(choice);
+ await flushing;
+ expect(usage.sharing, isFalse);
+ expect(reports, isEmpty);
+ },
+ );
+ test(
+ 'unknown settings fail closed and account off also clears guest consent',
+ () async {
+ await usage.setSignedOutSharing(true);
+ usage.begin(ProductFlow.signIn)(ProductOutcome.ok);
+ choice = {'enabled': false, 'revision': 1};
+ await account();
+ expect(setup, isEmpty);
+ expect(usage.signedOutSharing, isFalse);
+ usage.savedChoice({'enabled': true});
+ expect(usage.sharing, isFalse);
+ },
+ );
+ test(
+ 'expired RAM queues are discarded and unmatched setup remains unknown',
+ () async {
+ await usage.setSignedOutSharing(true);
+ usage.setupFacts({ProductFlow.setupTmux: 'running'});
+ usage.setupFacts({ProductFlow.setupTmux: 'ready'});
+ usage.setupFacts({ProductFlow.setupTmux: 'ready'});
+ await usage.flush();
+ expect(
+ (setup.single['counters'] as Map)['setup_desktop_setup_tmux_ok'],
+ 1,
+ );
+ usage.begin(ProductFlow.signIn);
+ now = now.add(const Duration(days: 2));
+ await usage.flush();
+ expect(setup.length, 1);
+ },
+ );
+ test(
+ 'flow observations are bounded and unknown operations never upload content',
+ () async {
+ await account();
+ for (var i = 0; i < 1000; i++) {
+ usage.begin(ProductFlow.remoteConnect);
+ }
+ await usage.flush();
+ expect(reports.single['counters'], {
+ 'ui_desktop_remote_connect_started': 64,
+ });
+ },
+ );
+ test(
+ 'web never queues signed-out setup even if a caller enables it',
+ () async {
+ final web = ProductMeasurement(
+ surface: 'web',
+ automatic: false,
+ sendSetup: (r) async {
+ setup.add(r);
+ return {'accepted': true};
+ },
+ );
+ await web.setSignedOutSharing(true);
+ web.begin(ProductFlow.signIn)(ProductOutcome.ok);
+ await web.flush();
+ web.dispose();
+ expect(setup, isEmpty);
+ },
+ );
+}