The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
Measurement: count what actually happened (setup steps, agent-start codes, late failures, clean stops, report bursts, unknown names) (#1393)
Deef159353084ea
diff --git a/backend/src/analytics/dailyProductReview.test.ts b/backend/src/analytics/dailyProductReview.test.tsindex dabbfba1f..1f2e1c5e9 100644--- a/backend/src/analytics/dailyProductReview.test.ts+++ b/backend/src/analytics/dailyProductReview.test.ts@@ -14,6 +14,21 @@ it('keeps today out of comparisons and marks sparse or absent baselines honestlyexpect(r.investigate[0]).toMatchObject({ area: 'Agent setup', count: 1 })})+it('names the most frequent codes of unknown launch refusals and of engines that did not start after a create', () => {+ const r = dailyProductReview([+ row('2026-10-12', 'launch_failed_other', 9), row('2026-10-12', 'launch_failed_code_invalid_prompt', 4),+ row('2026-10-11', 'launch_failed_code_invalid_prompt', 1), row('2026-10-12', 'launch_failed_code_unlisted', 2),+ ...['clone_failed', 'internal', 'busy', 'none'].map(code => row('2026-10-12', `launch_failed_code_${code}`, 1)),+ row('2026-10-12', 'launch_late_failed', 3), row('2026-10-12', 'launch_late_failed_code_start_timeout', 3),+ row('2026-10-12', 'launch_failed_code_PRIVATE_CANARY', 50),+ ], new Date('2026-10-13T12:00:00Z'))+ const unknown = r.investigate.find(s => s.area === 'Unknown launch refusal')+ expect(unknown).toMatchObject({ count: 9, codes: [{ code: 'invalid_prompt', count: 5 }, { code: 'unlisted', count: 2 },+ { code: 'busy', count: 1 }, { code: 'clone_failed', count: 1 }, { code: 'internal', count: 1 }] })+ expect(r.investigate.find(s => s.area === 'Engine did not start after create')).toMatchObject({ count: 3, codes: [{ code: 'start_timeout', count: 3 }] })+ expect(JSON.stringify(r)).not.toContain('PRIVATE_CANARY')+})+it('uses matured original working-day cohorts and refuses to interpret missing follow-up coverage as zero', () => {const r = dailyProductReview([row('2026-10-11', 'working_installation_days', 10), row('2026-10-11', 'd1_returning_work_installations', 6),diff --git a/backend/src/analytics/dailyProductReview.ts b/backend/src/analytics/dailyProductReview.tsindex 534213f3f..4074baee1 100644--- a/backend/src/analytics/dailyProductReview.ts+++ b/backend/src/analytics/dailyProductReview.ts@@ -1,4 +1,4 @@-import { PRODUCT_FEEDBACK, PRODUCT_FEEDBACK_REASONS, PRODUCT_FEEDBACK_OUTCOMES, PRODUCT_USAGE_ACTIONS, PRODUCT_USAGE_AUTOMATIC_ACTIONS, PRODUCT_USAGE_FLOWS, PRODUCT_USAGE_LONG_FLOWS, PRODUCT_USAGE_LONG_MEASURES, PRODUCT_USAGE_ONBOARDING_MARKS, PRODUCT_USAGE_SETUP_FLOWS, PRODUCT_USAGE_SURFACES, PRODUCT_USAGE_UI_SURFACES, PRODUCT_USAGE_USER_OPENED_ACTIONS } from '../types/productUsage.js'+import { LAUNCH_ERROR_CODES, LAUNCH_ERROR_FAMILIES, PRODUCT_FEEDBACK, PRODUCT_FEEDBACK_REASONS, PRODUCT_FEEDBACK_OUTCOMES, PRODUCT_USAGE_ACTIONS, PRODUCT_USAGE_AUTOMATIC_ACTIONS, PRODUCT_USAGE_FLOWS, PRODUCT_USAGE_LONG_FLOWS, PRODUCT_USAGE_LONG_MEASURES, PRODUCT_USAGE_ONBOARDING_MARKS, PRODUCT_USAGE_SETUP_FLOWS, PRODUCT_USAGE_SURFACES, PRODUCT_USAGE_UI_SURFACES, PRODUCT_USAGE_USER_OPENED_ACTIONS } from '../types/productUsage.js'import { DAILY_PRODUCT_METRICS } from './dailyProductUsage.js'type Row = { dayUtc: Date; metric: string; value: number }@@ -52,6 +52,11 @@ export function dailyProductReview(rows: Row[], now: Date) {...PRODUCT_USAGE_ACTIONS.map(action => comparison(`${action}: request refusal`, [`${action}_failed`], [`${action}_ok`, `${action}_failed`])),]const c = recent.counters+ // The fixed codes counted beside an `other` total, most frequent first: production had 23 of 25 launch failures+ // as `other` on 2026-10-16 with nothing to say which. Codes only; there is no message to look up.+ const topCodes = (family: typeof LAUNCH_ERROR_FAMILIES[number]) => LAUNCH_ERROR_CODES+ .map(code => ({ code, count: c[`${family}_${code}`] ?? 0 })).filter(entry => entry.count > 0)+ .sort((a, b) => b.count - a.count || a.code.localeCompare(b.code)).slice(0, 5)const marksOf = (prefix: string) => {const marks = PRODUCT_USAGE_ONBOARDING_MARKS.filter(metric => metric.startsWith(prefix))return marks.length ? { marks: Object.fromEntries(marks.map(metric => [metric.slice(prefix.length), c[metric] ?? 0])) } : {}@@ -61,7 +66,8 @@ export function dailyProductReview(rows: Row[], now: Date) {{ area: 'Sign-in or permission', count: c.launch_failed_auth ?? 0, next: 'Exercise expired sign-in and reconnect with a test account; verify recovery and the visible explanation.' },{ area: 'Dependency availability', count: c.launch_failed_unavailable ?? 0, next: 'Test an unavailable model/service and recovery; verify that a saved launch starts exactly once.' },{ area: 'Launch choices', count: c.launch_failed_invalid ?? 0, next: 'Reproduce invalid project/model selections with fixtures; verify validation before starting work.' },- { area: 'Unknown launch refusal', count: c.launch_failed_other ?? 0, next: 'Exercise launch failure fixtures and add a justified fixed category; do not retrieve user error messages.' },+ { area: 'Unknown launch refusal', count: c.launch_failed_other ?? 0, codes: topCodes('launch_failed_code'), next: 'Reproduce the most frequent codes with launch failure fixtures and add a justified fixed category; `unlisted` is a code missing from LAUNCH_ERROR_CODES. Do not retrieve user error messages.' },+ { area: 'Engine did not start after create', count: c.launch_late_failed ?? 0, codes: topCodes('launch_late_failed_code'), next: 'Reproduce an engine that exits, is missing or never shows its process in a new pane; these launches are also counted as created.' },{ area: 'Response wait', count: c.turns_waiting_over_1m ?? 0, next: 'Benchmark the same synthetic task and toolchain before/after; separate model wait from Harness overhead locally.' },{ area: 'No observed response', count: c.turns_ended_without_response ?? 0, next: 'Reproduce interruptions, provider failures and tool-only turns; a missing text event alone does not establish task failure.' },{ area: 'Launch outcome coverage', count: (c.launch_unobserved ?? 0) + (c.launch_unconfirmed ?? 0), next: 'Verify receipt polling, window close and daemon restart; unknown outcomes must not be counted as failed launches.' },diff --git a/backend/src/lib/productUsage.test.ts b/backend/src/lib/productUsage.test.tsindex 37856f32a..f2cd91cbc 100644--- a/backend/src/lib/productUsage.test.ts+++ b/backend/src/lib/productUsage.test.ts@@ -20,7 +20,7 @@ vi.mock('./prisma.js', () => ({ prisma: db }))// A configured key, so deletion through setProductUsageChoice and the legacy delete path is real.vi.mock('../config/env.js', () => ({ env: { PRODUCT_USAGE_SUBJECT_KEY: 'k'.repeat(32) } }))import { activitySubject, deleteActivity, deleteLegacyProductUsage, ensureProductUsageExpiry, markActivity, resetActivityMarksForTests, ingestProductUsage, ingestSetupUsage, productUsageChoice, recordRelayUsage, setProductUsageChoice } from './productUsage.js'-import type { ProductUsageReport } from '../types/productUsage.js'+import { LAUNCH_ERROR_CODES, LAUNCH_ERROR_FAMILIES, PRODUCT_USAGE_METRICS, type ProductUsageReport } from '../types/productUsage.js'it('commits release and platform margins under the same unlinked receipt and discards development reports', async () => {const context = { surface: 'desktop', release: '1.2.73', platform: 'macos', channel: 'production' } as const@@ -53,6 +53,23 @@ it('keeps the client and server vocabulary identical', () => {.toBe(readFileSync(new URL('../types/productUsage.ts', import.meta.url), 'utf8'))})+it('names every launch code in each of its families, once, as a fixed word that can carry no message', () => {+ const metrics = new Set<string>(PRODUCT_USAGE_METRICS)+ expect(metrics.size).toBe(PRODUCT_USAGE_METRICS.length)+ for (const family of LAUNCH_ERROR_FAMILIES) for (const code of LAUNCH_ERROR_CODES) expect(metrics.has(`${family}_${code}`), `${family}_${code}`).toBe(true)+ for (const code of LAUNCH_ERROR_CODES) expect(code).toMatch(/^[a-z][a-z0-9_]{1,39}$/)+ expect(new Set(LAUNCH_ERROR_CODES).size).toBe(LAUNCH_ERROR_CODES.length)+ expect(LAUNCH_ERROR_CODES).toEqual(expect.arrayContaining(['unlisted', 'none']))+ for (const name of ['launch_late_failed', 'first_launch_engine_opencode', 'first_launch_engine_other', 'first_launch_codex_signed_out']) expect(metrics.has(name), name).toBe(true)+})++it('stores launch codes as day totals like any other counter', async () => {+ const counters = { launch_failed_other: 2, launch_failed_code_invalid_prompt: 1, launch_failed_code_unlisted: 1, first_launch_claude_signed_in: 1 }+ expect(await ingestProductUsage('private-account', { ...report, counters }, now)).toEqual({ accepted: true })+ expect(db.$runCommandRaw.mock.calls[0][0].updates.map((u: { q: { metric: string }; u: unknown }) => [u.q.metric, u.u]))+ .toEqual(Object.entries(counters).map(([metric, value]) => [metric, { $inc: { value } }]))+})+describe('preference', () => {it('defaults on but preserves a prior off choice', async () => {expect(await productUsageChoice('private-account')).toEqual({ enabled: true, revision: 0 })diff --git a/backend/src/routes/productUsage.test.ts b/backend/src/routes/productUsage.test.tsindex 860d3dbb5..7223e09d3 100644--- a/backend/src/routes/productUsage.test.ts+++ b/backend/src/routes/productUsage.test.ts@@ -34,6 +34,22 @@ it.each([expect(response.body).not.toContain('PRIVATE_CANARY')expect(methods.ingestProductUsage).not.toHaveBeenCalled()})+it('keeps a report with a name this backend does not know yet, without that name', async () => {+ const context = { surface: 'cli', release: '0.4.18', platform: 'macos', channel: 'production' }+ const response = await submit({ ...good, context, counters: { turns_started: 2, PRIVATE_CANARY_from_a_newer_client: 1 } })+ expect(response.statusCode).toBe(200)+ expect(response.body).not.toContain('PRIVATE_CANARY')+ expect(methods.ingestProductUsage).toHaveBeenCalledExactlyOnceWith('account',+ { ...good, context, counters: { turns_started: 2, health_cli_report_unknown_metric: 1 } })+})+it('keeps a setup report with a name this backend does not know yet, without that name', async () => {+ const setup = { schemaVersion: 1, id: good.id, day: good.day, sharing: 'default',+ counters: { setup_desktop_sign_in_started: 1, setup_desktop_PRIVATE_CANARY: 1 } }+ const response = await app.inject({ method: 'POST', url: '/api/product-usage/setup', payload: setup })+ expect(response.statusCode).toBe(200)+ expect(methods.ingestSetupUsage).toHaveBeenCalledExactlyOnceWith(+ { ...setup, counters: { setup_desktop_sign_in_started: 1 } })+})it('does not reflect a database error or report contents', async () => {methods.ingestProductUsage.mockRejectedValue(new Error('PRIVATE_CANARY'))const response = await submit(good)@@ -93,6 +109,28 @@ it('the complete vocabulary fits bounded chunks, including the longest metric ke}})+it('takes the CLI\'s launch codes, late launch failures and first launches by engine, and still no name outside the list', async () => {+ const context = { surface: 'cli', release: '0.4.9', platform: 'macos', channel: 'production' }+ const counters = { launch_failed_other: 2, launch_failed_code_invalid_prompt: 1, launch_failed_code_unlisted: 1,+ launch_late_failed: 1, launch_late_failed_code_engine_did_not_start: 1, create_error_code_none: 1,+ resume_error_code_session_not_found: 1, first_launch_engine_claude: 1, first_launch_claude_signed_in: 1,+ first_launch_engine_other: 1, first_launch_codex_unknown: 1 }+ expect((await submit({ ...good, context, counters })).statusCode).toBe(200)+ expect(methods.ingestProductUsage).toHaveBeenCalledWith('account', expect.objectContaining({ counters }))+ methods.ingestProductUsage.mockClear()+ // A name outside the list is never stored: the report keeps its known counters without it (an unknown+ // name no longer refuses the whole report), and alone it is still refused.+ for (const name of ['launch_failed_code_PRIVATE_CANARY', 'launch_failed_code_ENGINE_DID_NOT_START', 'restart_error_code_internal',+ 'first_launch_engine_cursor', 'first_launch_opencode_signed_in', 'launch_late_failed_other']) {+ const response = await submit({ ...good, context, counters: { launch_late_failed: 1, [name]: 1 } })+ expect(response.statusCode, name).toBe(200)+ expect(response.body).not.toContain('PRIVATE_CANARY')+ expect(methods.ingestProductUsage).toHaveBeenLastCalledWith('account', expect.objectContaining(+ { counters: { launch_late_failed: 1, health_cli_report_unknown_metric: 1 } }))+ expect((await submit({ ...good, context, counters: { [name]: 1 } })).statusCode, name).toBe(400)+ }+})+it('takes a phone build context: its release and iOS or Android, nothing finer', async () => {for (const platform of ['ios', 'android']) {const response = await submit({ ...good, context: { surface: 'phone', release: '1.0.3', platform, channel: 'production' } })diff --git a/backend/src/routes/productUsage.ts b/backend/src/routes/productUsage.tsindex e8f4d89d2..569e5bff1 100644--- a/backend/src/routes/productUsage.ts+++ b/backend/src/routes/productUsage.ts@@ -38,6 +38,23 @@ export const setupUsageSchema = z.union([Object.keys(report.counters).every(key => key.startsWith(prefix)))),])+const REPORT_METRICS = new Set<string>(PRODUCT_USAGE_METRICS)+const SETUP_METRICS = new Set<string>(PRODUCT_USAGE_SETUP_METRICS)+/** A client a release ahead of this backend can name a counter the contract here does not have yet.+ * Rejecting the whole report for it lost every other counter in it — up to 64 per CLI report — and the+ * client retried the same rejected report for days. Keep the known counters, drop the unknown names+ * (never stored or echoed) and say how many reports that happened to. A report with no known counter+ * left is still refused. Values and every other field are validated as before. */+function withoutUnknownCounters(body: unknown, allowed: Set<string>): { body: unknown; dropped: boolean } {+ if (!body || typeof body !== 'object' || Array.isArray(body)) return { body, dropped: false }+ const counters = (body as { counters?: unknown }).counters+ if (!counters || typeof counters !== 'object' || Array.isArray(counters)) return { body, dropped: false }+ const all = Object.entries(counters)+ const known = all.filter(([metric]) => allowed.has(metric))+ if (!known.length || known.length === all.length) return { body, dropped: false }+ return { body: { ...body, counters: Object.fromEntries(known) }, dropped: true }+}+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.@@ -51,7 +68,7 @@ export async function productUsageRoutes(app: FastifyInstance): Promise<void> {})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)+ const parsed = setupUsageSchema.safeParse(withoutUnknownCounters(req.body, SETUP_METRICS).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 }@@ -83,9 +100,13 @@ export async function productUsageRoutes(app: FastifyInstance): Promise<void> {})app.post('/api/product-usage/report', { bodyLimit: 8192 }, async (req, reply) => {if (!req.user?.sub) return sendError(reply, 'Unauthorized', 'UNAUTHORIZED', 401)- const parsed = productUsageReportSchema.safeParse(req.body)+ const cleaned = withoutUnknownCounters(req.body, REPORT_METRICS)+ const parsed = productUsageReportSchema.safeParse(cleaned.body)// Never reflect rejected fields, values or raw validation errors into logs or responses.if (!parsed.success) return sendError(reply, 'Invalid usage report', 'INVALID_USAGE_REPORT', 400)+ if (cleaned.dropped && parsed.data.context) {+ parsed.data.counters[`health_${parsed.data.context.surface}_report_unknown_metric`] = 1+ }try { return sendSuccess(reply, await ingestProductUsage(req.user.sub, parsed.data)) }catch (error) {// A fixed category can diagnose delivery without exposing database errors or report contents.diff --git a/backend/src/types/productUsage.ts b/backend/src/types/productUsage.tsindex f8568c358..f1ec00673 100644--- a/backend/src/types/productUsage.ts+++ b/backend/src/types/productUsage.ts@@ -59,6 +59,8 @@ export const PRODUCT_USAGE_FLOW_MEASURES = ['started', 'ok', 'failed', 'cancelle'under_1s', '1s_to_10s', '10s_to_1m', 'over_1m'] as constexport const PRODUCT_USAGE_UI_METRICS = PRODUCT_USAGE_UI_SURFACES.flatMap(surface =>PRODUCT_USAGE_FLOWS.flatMap(flow => PRODUCT_USAGE_FLOW_MEASURES.map(measure => `ui_${surface}_${flow}_${measure}` as const)))+export const PRODUCT_USAGE_SETUP_DOWNLOADS = ['opencode', 'codex', 'claude'] as const+export const PRODUCT_USAGE_SETUP_DOWNLOAD_MEASURES = ['started', 'ok', 'failed', 'under_1m', '1m_to_5m', 'over_5m'] 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 =>PRODUCT_USAGE_SETUP_FLOWS.flatMap(flow =>@@ -66,6 +68,56 @@ export const PRODUCT_USAGE_SETUP_METRICS = [...PRODUCT_USAGE_SURFACES.flatMap(su...(['funnel_setup_seen', 'funnel_sign_in_seen', 'funnel_workspace_ready', 'funnel_first_work', 'funnel_first_response','first_work_under_1m', 'first_work_1m_to_5m', 'first_work_over_5m','first_response_under_1m', 'first_response_1m_to_5m', 'first_response_over_5m'] as const).map(m => `setup_desktop_${m}` as const),+ // A step's tool was not installed yet when Desktop checked, so setup installed it: once per step per+ // setup, beside the step's own outcome. Signed-out only (a signed-in report passes an older CLI).+ ...(['setup_harness', 'setup_tmux', 'setup_clipboard'] as const).map(flow => `setup_desktop_${flow}_missing` as const),+ // The agents a new computer downloads beside setup (desktop/lib/bootstrap/agent_prefetch.dart): whether each+ // download put its agent in place, and how long it took. Engine names only, never a path or log line.+ ...PRODUCT_USAGE_SETUP_DOWNLOADS.flatMap(engine => PRODUCT_USAGE_SETUP_DOWNLOAD_MEASURES+ .map(measure => `setup_desktop_agent_download_${engine}_${measure}` as const)),+] as const+/** A new-harness, create or resume refusal outside the four fixed kinds (setup, auth, unavailable,+ * invalid), by its code: the daemon's own fixed error names, lower-cased. On 2026-10-16 production counted+ * 23 of 25 launch failures, 22 create refusals and 9 resume refusals as `other`, with nothing to say+ * which. `unlisted` is a code not named here, `none` a refusal that named no code; each family adds up to+ * its `_other` total, and the late failures to `launch_late_failed`. Codes only, never a message. */+export const LAUNCH_ERROR_CODES = [+ // What a new harness asked for, refused before anything starts (core/agents/launches.ts, lib/engineLaunch.ts).+ 'invalid_codex_home', 'invalid_prompt', 'prompt_too_long', 'prompt_unsupported', 'invalid_agent', 'invalid_session',+ 'invalid_started_by', 'agent_unsupported', 'invalid_runtime_profile', 'grid_engine_unsupported', 'codex_cli_too_old',+ // A new project's folder (lib/projectFolder.ts) and the launch's durable receipt (lib/agentCreationReceipt.ts).+ 'project_exists', 'invalid_repository', 'clone_failed', 'clone_timeout', 'git_unavailable', 'project_preparation_failed',+ 'creation_conflict', 'creation_storage_failed', 'launch_authority_changed', 'internal',+ // The engine itself: preparing it (engines/nativeLaunch.ts) and its start (core/agents/newPane.ts).+ 'engine_cannot_run', 'engine_install_failed', 'engine_did_not_start', 'engine_not_installed', 'start_timeout',+ // A Store harness (core/agents/dshThrough.ts, services/storeLaunch.ts).+ 'dsh_not_installed', 'dsh_unavailable', 'dsh_runtime_failed',+ // A conversation Harness did not start, opened in it (core/agents/adopt.ts, externalResume.ts, lib/registry.ts).+ 'core_not_ready', 'search_unavailable', 'session_in_harness', 'session_not_found', 'session_archived', 'session_folder_gone',+ 'session_open_elsewhere', 'session_busy_in_terminal', 'session_open_in_terminal', 'session_changed', 'resume_session_mismatch',+ // A cloud agent (cloud/).+ 'not_connected', 'cloud_failed', 'rate_limited', 'unreachable', 'busy', 'invalid_request', 'connections_unavailable',+ // A harness that exists: resumed, restarted, changed, closed or deleted (lib/resumeAgentService.ts, core/agents/).+ 'missing_agent_id', 'delete_in_progress', 'agent_busy', 'agent_not_found', 'agent_changed', 'resume_failed', 'resume_unavailable',+ 'resume_preparation_failed', 'grid_credential_required', 'permission_change_requires_stop', 'identity_unavailable',+ 'restart_failed', 'restart_unsupported_backend', 'retarget_unsupported_backend', 'fork_on_grid_unsupported',+ 'no_active_process', 'opencode_sqlite_missing', 'unavailable', 'missing_name', 'missing_update',+ 'invalid_close_request', 'invalid_delete_request', 'close_failed', 'delete_failed',+ 'unlisted', 'none',+] as const+export type LaunchErrorCode = typeof LAUNCH_ERROR_CODES[number]+/** The families counted by code: a launch's failure, its start failing after it was created, and the create+ * and resume requests' refusals. */+export const LAUNCH_ERROR_FAMILIES = ['launch_failed_code', 'launch_late_failed_code', 'create_error_code', 'resume_error_code'] as const+/** The engine an installation's first launch asked for; any other engine is `other`. */+export const PRODUCT_USAGE_LAUNCH_ENGINES = ['opencode', 'claude', 'codex', 'other'] as const+export type ProductUsageLaunchEngine = typeof PRODUCT_USAGE_LAUNCH_ENGINES[number]+/** Whether that engine had a credential on this computer, by presence only (cli/src/lib/engineAccount.ts). */+export const PRODUCT_USAGE_ENGINE_ACCOUNTS = ['signed_in', 'signed_out', 'unknown'] as const+export const PRODUCT_USAGE_LAUNCH_METRICS = [+ ...LAUNCH_ERROR_FAMILIES.flatMap(family => LAUNCH_ERROR_CODES.map(code => `${family}_${code}` as const)),+ ...PRODUCT_USAGE_LAUNCH_ENGINES.map(engine => `first_launch_engine_${engine}` as const),+ ...(['claude', 'codex'] as const).flatMap(engine => PRODUCT_USAGE_ENGINE_ACCOUNTS.map(account => `first_launch_${engine}_${account}` as const)),] as constexport const PRODUCT_USAGE_ACTION_MEASURES = ['requests', 'ok', 'failed', 'pending', 'unknown','error_setup', 'error_auth', 'error_unavailable', 'error_invalid', 'error_other',@@ -80,6 +132,8 @@ export const PRODUCT_USAGE_METRICS = ['duration_under_10s', 'duration_10s_to_1m', 'duration_1m_to_5m', 'duration_over_5m','desktop_opens', 'tui_opens','launch_started', 'launch_created', 'launch_failed', 'launch_cancelled', 'launch_unconfirmed', 'launch_unobserved',+ // A created launch whose engine then did not start: one of the launch_created, never also a launch_failed.+ 'launch_late_failed','launch_wait_install', 'launch_wait_model', 'launch_wait_native', 'launch_wait_other','launch_failed_setup', 'launch_failed_auth', 'launch_failed_unavailable', 'launch_failed_invalid', 'launch_failed_other','launch_under_10s', 'launch_10s_to_1m', 'launch_1m_to_5m', 'launch_over_5m',@@ -87,6 +141,7 @@ export const PRODUCT_USAGE_METRICS = ['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', 'd28_returning_work_installations',+ ...PRODUCT_USAGE_LAUNCH_METRICS,...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)),@@ -95,6 +150,9 @@ export const PRODUCT_USAGE_METRICS = [...PRODUCT_USAGE_UI_METRICS,...PRODUCT_USAGE_ONBOARDING_METRICS,...PRODUCT_USAGE_PHONE_SCREEN_METRICS,+ // Written by the backend itself: a report that named counters this backend does not know yet, which+ // it kept without them (routes/productUsage.ts). One per report, never the names.+ 'health_cli_report_unknown_metric', 'health_desktop_report_unknown_metric', 'health_phone_report_unknown_metric',] as constexport type ProductUsageMetric = typeof PRODUCT_USAGE_METRICS[number]export interface ProductUsageReport {diff --git a/cli/src/backendSocket.spec.ts b/cli/src/backendSocket.spec.tsindex 8b3580f55..61a457bb5 100644--- a/cli/src/backendSocket.spec.ts+++ b/cli/src/backendSocket.spec.ts@@ -2058,6 +2058,42 @@ describe('BackendSocket outbound queue', () => {}})+ it('tells the gateway a launch\'s engine and the agent it created, and then that agent\'s start failing', async () => {+ // A create whose engine then did not start was counted as a launch that worked: the reply had said created+ // (core/agents/newPane.ts; production counters, 2026-10-16). Only fixed names and the agent's id leave here.+ const socket = relaySocket('token')+ bindLaunchRequests(socket)+ const signals: unknown[] = []+ vi.spyOn(gatewayOf(socket), 'usageLaunch').mockImplementation((signal) => { signals.push(signal) })+ const states: unknown[][] = []+ gatewayOf(socket).productUsage = { observe: vi.fn(), opened: vi.fn(), presence: vi.fn(), launchState: (...args) => { states.push(args) } }+ socket.registerLocalClient('local:measured', { sendFrame: () => true, sendBinary: () => true })+ const session: RegisteredSession = {+ schemaVersion: 2, active: true, launch: { state: 'starting' },+ agentId: 'measured-agent', sessionId: '', boundAt: null, engine: 'claude',+ transcriptPath: null, projectDir: 'work', cwd: '/tmp/work',+ runtimes: [{ backend: 'tmux', paneId: '%measured' }], primaryRuntimeKey: 'tmux/%measured', tmuxPane: '%measured',+ source: null, title: 'PRIVATE_CANARY', model: null, cliVersion: null, processIdentity: null,+ registeredAt: 1, touchedAt: 1, lastHookAt: 1, lastTranscriptAt: 1,+ }+ vi.spyOn(registry, 'byAgent').mockReturnValue(session)+ socket.onCreateAgent = vi.fn(async () => ({ ok: true as const, session }))+ const creationId = randomUUID()+ try {+ socket.handleLocalFrame('local:measured', { type: 'agent_create', payload: { requestId: 'measured', creationId, engine: 'claude', cwd: '/tmp/work' } })+ await vi.waitFor(() => expect(signals).toHaveLength(2))+ expect(signals).toEqual([{ id: creationId, phase: 'start', engine: 'claude' }, { id: creationId, phase: 'created', agent: 'measured-agent' }])+ socket.send({ type: 'agent_synced', payload: { agent: { ...await socket.toProject(session),+ launch: { state: 'failed', error: 'ENGINE_DID_NOT_START', detail: 'PRIVATE_CANARY could not start' } } } })+ socket.send({ type: 'agent_synced', payload: { agent: await socket.toProject({ ...session, launch: { state: 'ready' } }) } })+ expect(states).toEqual([['measured-agent', 'failed', 'engine_did_not_start'], ['measured-agent', 'ready', undefined]])+ expect(JSON.stringify([signals, states])).not.toContain('PRIVATE_CANARY')+ } finally {+ await socket.unregisterLocalClient('local:measured')+ await socket.stop()+ }+ })+it('explains invalid repository choices without echoing credentials or preparing a folder', async () => {const socket = relaySocket('token')bindLaunchRequests(socket)diff --git a/cli/src/backendSocket.ts b/cli/src/backendSocket.tsindex 99eebb385..8773f1c06 100644--- a/cli/src/backendSocket.ts+++ b/cli/src/backendSocket.ts@@ -836,7 +836,7 @@ export class BackendSocket {logFrame('←', connId ? `conn:${sid(connId)}` : 'backend', frame)}const launchMeasured = productUsageLaunch(type, (frame.payload as { creationId?: unknown } | undefined)?.creationId,- signal => this.toGateway('usage', gateway => gateway.usageLaunch?.(signal)))+ signal => this.toGateway('usage', gateway => gateway.usageLaunch?.(signal)), (frame.payload as { engine?: unknown } | undefined)?.engine)const usageSource = productUsageSource(local, !!connId && this.toolClients.has(connId), role, frame.payload)const measured = productUsageRequest(type, (metric) => this.toGateway('usage', (gateway) => gateway.usageCounter?.(metric)), Date.now, usageSource,(frame.payload as { userAction?: unknown } | undefined)?.userAction === true)@@ -846,7 +846,8 @@ export class BackendSocket {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, p.ok)- launchMeasured(p.error ?? (p.failure as { code?: unknown } | undefined)?.code, p.state, !!p.agent, (p.held as { service?: unknown } | undefined)?.service)+ // The agent frame itself: a created launch's agent is watched until it starts (gateway/productUsage.ts).+ 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/gateway/accountHttp.spec.ts b/cli/src/gateway/accountHttp.spec.tsindex cc237ff04..fb9249e43 100644--- a/cli/src/gateway/accountHttp.spec.ts+++ b/cli/src/gateway/accountHttp.spec.ts@@ -4,7 +4,7 @@ import { join } from 'node:path'import { afterEach, describe, expect, it, vi } from 'vitest'import type { GatewayAccount } from '../core/api.js'import { AuthSessionError } from '../lib/authSession.js'-import { createAccountHttp } from './accountHttp.js'+import { createAccountHttp, retryAfterMs } from './accountHttp.js'const roots: string[] = []afterEach(() => { for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }) })@@ -47,6 +47,22 @@ describe('account HTTP in the gateway', () => {request.mockResolvedValueOnce(new Response('not json', { status: 502 }))expect(await api.backend('GET', '/api/auth/me')).toEqual({ status: 502, body: {} })})+ it('says when a busy or failing backend asks to be tried again, for the usage reports\' backoff', async () => {+ const { api, request } = setup()+ const at = (status: number, retryAfter: string) => new Response('{}', { status, headers: { 'retry-after': retryAfter } })+ request.mockResolvedValueOnce(at(429, '120'))+ expect(await api.backend('POST', '/api/product-usage/report', {})).toEqual({ status: 429, body: {}, retryAfterMs: 120_000 })+ request.mockResolvedValueOnce(at(503, new Date(Date.now() + 60_000).toUTCString()))+ expect((await api.backend('POST', '/api/product-usage/report', {})).retryAfterMs).toBeGreaterThan(50_000)+ // Unreadable, or on an answer that is not a busy one: nothing said.+ request.mockResolvedValueOnce(at(429, 'soon'))+ expect(await api.backend('POST', '/api/product-usage/report', {})).toEqual({ status: 429, body: {} })+ request.mockResolvedValueOnce(at(200, '120'))+ expect(await api.backend('POST', '/api/product-usage/report', {})).toEqual({ status: 200, body: {} })+ expect(retryAfterMs(null)).toBeNull()+ expect(retryAfterMs(' 7 ', 0)).toBe(7_000)+ expect(retryAfterMs('Thu, 01 Jan 1970 00:00:01 GMT', 5_000)).toBe(0)+ })it.each([['MISSING', 401, 'NOT_SIGNED_IN'], ['INVALID_REFRESH', 401, 'NOT_SIGNED_IN'], ['UNAVAILABLE', 502, 'AUTH_UNAVAILABLE']] as const)('distinguishes %s from an unreachable backend', async (code, status, answer) => {diff --git a/cli/src/gateway/accountHttp.ts b/cli/src/gateway/accountHttp.tsindex ea7e43d20..b12a67329 100644--- a/cli/src/gateway/accountHttp.ts+++ b/cli/src/gateway/accountHttp.ts@@ -21,13 +21,24 @@ interface AccountHttpDeps {const failure = (status: number, code: string, message: string): HttpAnswer =>({ status, body: { success: false, error: { code, message } } })+/** A Retry-After header as milliseconds from [now]: delta-seconds or an HTTP date; null when absent or unreadable. */+export function retryAfterMs(header: string | null, now = Date.now()): number | null {+ const value = header?.trim()+ if (!value) return null+ if (/^\d{1,9}$/.test(value)) return Number(value) * 1000+ const at = Date.parse(value)+ return Number.isFinite(at) ? Math.max(0, at - now) : null+}+export function createAccountHttp(deps: AccountHttpDeps) {const request = deps.request ?? fetchconst accountFence = () => {const account = deps.account()return [account.machineId, account.autonomousEnv, account.signIn?.epoch, account.signIn?.acct]}- async function backend(method: string, path: string, body?: unknown, timeoutMs = PROXY_BACKEND_TIMEOUT_MS): Promise<HttpAnswer> {+ /** `retryAfterMs` comes with a busy or failing answer (429, 5xx) that says when to try again: the usage+ * reports' backoff honours it (gateway/productUsage.ts). */+ async function backend(method: string, path: string, body?: unknown, timeoutMs = PROXY_BACKEND_TIMEOUT_MS): Promise<HttpAnswer & { retryAfterMs?: number }> {const owner = accountFence()let accessToken: stringtry { accessToken = await deps.tokens.accessToken() } catch (error) {@@ -55,7 +66,8 @@ export function createAccountHttp(deps: AccountHttpDeps) {}return failure(502, 'BACKEND_UNREACHABLE', `Could not reach the Harness backend (${e.cause?.message ?? e.message}). Check the connection and try again.`)}- return { status: res.status, body: await res.json().catch(() => ({})) as Record<string, unknown> }+ const retry = res.status === 429 || res.status >= 500 ? retryAfterMs(res.headers?.get?.('retry-after') ?? null) : null+ return { status: res.status, body: await res.json().catch(() => ({})) as Record<string, unknown>, ...(retry !== null ? { retryAfterMs: retry } : {}) }}const cache = new MachineListCache(() => backend('GET', '/api/machines'), () => deps.computer.id,diff --git a/cli/src/gateway/gateway.spec.ts b/cli/src/gateway/gateway.spec.tsindex df68dedbe..1040b9849 100644--- a/cli/src/gateway/gateway.spec.ts+++ b/cli/src/gateway/gateway.spec.ts@@ -35,7 +35,17 @@ it('passes only lifecycle scalars to product reporting and keeps relaying if repgateway.broadcast({ type: 'error', agentId: 'fixture-agent', payload: { message: 'PRIVATE_CANARY' } })expect(observe).toHaveBeenCalledWith('error', 'fixture-agent', false, false)expect(JSON.stringify(observe.mock.calls)).not.toContain('PRIVATE_CANARY')+ // An agent's launch state, from its frame: the state and a listed code, never the frame or its words.+ const launchState = vi.fn()+ gateway.productUsage = { observe, opened: vi.fn(), presence: vi.fn(), launchState }+ gateway.broadcast({ type: 'agent_synced', payload: { agent: { id: 'fixture-agent', name: 'PRIVATE_CANARY',+ launch: { state: 'failed', error: 'START_TIMEOUT', detail: 'PRIVATE_CANARY' } } } })+ gateway.broadcast({ type: 'agent_synced', payload: { agent: { id: 'fixture-agent', launch: { state: 'PRIVATE_CANARY' } } } })+ gateway.broadcast({ type: 'agent_synced', payload: { agent: { name: 'no id' } } })+ gateway.broadcast({ type: 'agent_renamed', payload: { agentId: 'fixture-agent', name: 'PRIVATE_CANARY' } })+ expect(launchState.mock.calls).toEqual([['fixture-agent', 'failed', 'start_timeout'], ['fixture-agent', 'other', undefined]])const fail = () => { throw new Error('Reporting unavailable') }+ expect(() => { gateway.productUsage = { observe, opened: vi.fn(), presence: vi.fn(), launchState: fail }; gateway.broadcast({ type: 'agent_synced', payload: { agent: { id: 'a', launch: { state: 'ready' } } } }) }).not.toThrow()gateway.productUsage = { observe: fail, opened: fail, presence: fail, counter: fail, launch: fail }expect(() => gateway.usageCounter('create_requests')).not.toThrow()expect(() => gateway.usageLaunch({ id: 'synthetic-creation-1', phase: 'start' })).not.toThrow()diff --git a/cli/src/gateway/gateway.ts b/cli/src/gateway/gateway.tsindex 08636d52e..10aac6fa4 100644--- a/cli/src/gateway/gateway.ts+++ b/cli/src/gateway/gateway.ts@@ -15,8 +15,8 @@*/import { env } from '../config/env.js'import type { GatewayEvents, GatewayPort, RemoteRole, RemoteTransport } from '../core/api.js'-import type { ProductUsageLaunchSignal } from '../lib/productUsageSignals.js'-import type { ProductUsageMetric } from '../lib/productUsageContract.js'+import { launchErrorCode, type ProductUsageLaunchSignal } from '../lib/productUsageSignals.js'+import type { LaunchErrorCode, ProductUsageMetric } from '../lib/productUsageContract.js'import { WINDOW_SURFACES, type LocalWindows, type WindowSurface } from '../lib/windowSurfaces.js'import { deviceDump } from '../lib/autonomous-device/dump.js'import type { AuthSessionManager } from '../lib/authSession.js'@@ -58,6 +58,8 @@ export class RelayGateway implements GatewayPort {presence(active: boolean): voidopened(surface: WindowSurface): voidobserve(type: 'turn_started' | 'turn_ended' | 'text_delta' | 'error', agent: string, replay: boolean, interrupted?: boolean): void+ /** An agent's launch state as its `agent_synced` frame says it, the failure's code a listed name only. */+ launchState?(agent: string, state: 'starting' | 'ready' | 'failed' | 'held' | 'other', code?: LaunchErrorCode): void}/** Web↔adapter E2EE: group-encrypts user events, runs the CPace pairing, holds per-conn sessions. */readonly e2ee: E2eeManager@@ -246,6 +248,19 @@ export class RelayGateway implements GatewayPort {const interrupted = frame.type === 'turn_ended' && (frame.payload as { aborted?: unknown } | undefined)?.aborted === truetry { this.productUsage?.observe(frame.type, frame.agentId, frame.replay === true, interrupted) } catch { /* Work continues without metrics. */ }}+ // A created harness whose engine then did not start is announced, not replied: the reply already said+ // created (core/agents/newPane.ts), so these were counted as launches that worked (production counters,+ // 2026-10-16). The core says it to every remote client in this frame; the gateway reads its launch state.+ if (frame.type === 'agent_synced' && this.productUsage?.launchState) {+ try {+ const agent = (frame.payload as { agent?: { id?: unknown; launch?: { state?: unknown; error?: unknown } } } | undefined)?.agent+ const state = agent?.launch?.state+ if (typeof agent?.id === 'string') {+ this.productUsage.launchState(agent.id, state === 'starting' || state === 'ready' || state === 'failed' || state === 'held' ? state : 'other',+ state === 'failed' ? launchErrorCode(agent.launch?.error) : undefined)+ }+ } catch { /* Work continues without metrics. */ }+ }if (this.link.servesThisComputerOnly()) returnthis.link.enqueue({ t: 'up', frame: this.e2ee.wrapUp(frame) })}diff --git a/cli/src/gateway/gatewayProcess.spec.ts b/cli/src/gateway/gatewayProcess.spec.tsindex d750926bb..67fb4bee6 100644--- a/cli/src/gateway/gatewayProcess.spec.ts+++ b/cli/src/gateway/gatewayProcess.spec.ts@@ -77,9 +77,10 @@ function wire() {let options!: ServiceProcessOptionsconst gateways: Array<ReturnType<typeof stubGateway>> = []const hosts: GatewayHost[] = []- runGatewayService({+ const linkStop = vi.fn()+ const service = runGatewayService({dataDir: '/data', socketPath: '/data/daemon.sock', machineId: 'computer-1', token: 'token',- run: (given) => { options = given; return { stop: vi.fn() } },+ run: (given) => { options = given; return { stop: linkStop } },start: (host) => { hosts.push(host); const stub = stubGateway(); gateways.push(stub); return stub as unknown as StartedGateway },})const heard = {@@ -107,7 +108,7 @@ function wire() {}const connect = () => { options.onConnected!(core); link.connected() }const disconnect = () => { options.onDisconnected!(); link.disconnected() }- return { link, heard, gateways, hosts, connect, disconnect, tokens, backend, options: () => options }+ return { link, heard, gateways, hosts, connect, disconnect, tokens, backend, options: () => options, service, linkStop }}describe('the gateway\'s process, spoken to by the core', () => {@@ -149,6 +150,30 @@ describe('the gateway\'s process, spoken to by the core', () => {expect(w.gateways[1].port.holdRequests).not.toHaveBeenCalled()})+ it('stops the gateway, and its usage collector with it, before its link closes as the process goes', async () => {+ // The process's stop used to close the link and nothing else: the gateway's stop waited for the link's close+ // event, which the process's exit came before, so its collector never wrote a clean exit+ // (health_cli_unclean_restart, 69 to 170 on 2026-10-16, production counters).+ const w = wire()+ w.connect()+ const [gateway] = w.gateways+ let finished = false+ gateway.stop.mockImplementation(async () => { await new Promise((resolve) => setTimeout(resolve, 5)); finished = true })+ const stopping = w.service.stop()+ expect(gateway.stop).toHaveBeenCalledOnce()+ expect(w.linkStop).toHaveBeenCalledOnce()+ expect(gateway.stop.mock.invocationCallOrder[0]).toBeLessThan(w.linkStop.mock.invocationCallOrder[0])+ await stopping+ expect(finished).toBe(true)+ // The link's close that follows finds nothing left to stop.+ w.disconnect()+ expect(gateway.stop).toHaveBeenCalledOnce()+ // Never started: the process still goes.+ const idle = wire()+ await idle.service.stop()+ expect(idle.linkStop).toHaveBeenCalledOnce()+ })+it('starts once it knows the core took its link, though the core says start a frame before', () => {const w = wire()// The core's link says start as it takes the connection, before the `connected` that tells this process.diff --git a/cli/src/gateway/gatewayProcess.ts b/cli/src/gateway/gatewayProcess.tsindex 21e0ebad9..42ff0878e 100644--- a/cli/src/gateway/gatewayProcess.ts+++ b/cli/src/gateway/gatewayProcess.ts@@ -76,20 +76,20 @@ export function runGatewayService(options: GatewayServiceOptions): ServiceProces* the session's own error. */const { accessToken } = accountLink((query, payload) => (core ? core.query(query, payload) : Promise.reject(new Error('not connected to the core'))))- /** The gateway stopped: its link closed, its windows' sessions let go. Not waited on: what comes after it- * on the link (a new `start`) must not wait for the old link's goodbye. */+ /** The gateway stopped: its link closed, its windows' sessions let go. Not waited on here: what comes after it+ * on the link (a new `start`) must not wait for the old link's goodbye. The process's own stop waits for it. */let pendingStart: Payload | null = null- const stop = (): void => {+ const stop = (): Promise<void> => {pendingStart = nullconst was = runningrunning = nullfor (const session of windows.values()) session.detach()windows.clear()- void was?.stop().catch((error: unknown) => console.warn(`[gateway] stopping: ${error instanceof Error ? error.message : String(error)}`))+ return was ? was.stop().catch((error: unknown) => console.warn(`[gateway] stopping: ${error instanceof Error ? error.message : String(error)}`)) : Promise.resolve()}const begin = (payload: Payload): void => {- stop()+ void stop()const started = (options.start ?? startGateway)({events,machineId: text(payload.machineId),@@ -154,7 +154,7 @@ export function runGatewayService(options: GatewayServiceOptions): ServiceProces// dial would ask the core for a token on a link this process does not know is up yet, and wait a second// to try again. Started once it knows.if (kind === 'start') { if (core) begin(payload); else pendingStart = payload; return }- if (kind === 'stop') { stop(); return }+ if (kind === 'stop') { void stop(); return }if (kind === 'windowOpen') { void openWindow(payload); return }const gateway = runningif (!gateway) return@@ -286,7 +286,7 @@ export function runGatewayService(options: GatewayServiceOptions): ServiceProces},}- return (options.run ?? runServiceProcess)({+ const service = (options.run ?? runServiceProcess)({name: 'gateway',socketPath: options.socketPath,machineId: options.machineId,@@ -302,7 +302,19 @@ export function runGatewayService(options: GatewayServiceOptions): ServiceProces},onDisconnected: () => {core = null- stop()+ void stop()},})+ return {+ // The process is going (the master's SIGTERM, the master gone, services/process.ts `leave`): the gateway and its+ // usage collector stop first, while the link is still up, and the process waits for them. Closing the link alone+ // left them to its close event, which the exit came before: the collector never wrote its clean exit, and+ // `harness stop`, updates, sign-in restarts, service installs and OS logouts all counted as unclean restarts+ // (health_cli_unclean_restart, 69 to 170 on 2026-10-16, production counters).+ stop: async () => {+ const stopping = stop()+ await service.stop()+ await stopping+ },+ }}diff --git a/cli/src/gateway/productHealth.spec.ts b/cli/src/gateway/productHealth.spec.tsindex 330a1932f..83b65c759 100644--- a/cli/src/gateway/productHealth.spec.ts+++ b/cli/src/gateway/productHealth.spec.ts@@ -25,7 +25,17 @@ it('counts only explicit interactive intent and never serializes its identifiersexpect(add.mock.calls.filter(([k]) => k === 'health_cli_first_interactive_work')).toHaveLength(1)})-it('bounds RAM, expires unobserved intent, resets on a changed choice and samples at most once a minute', () => {+it('samples once a tick, the shortest of which is 45 seconds, so the minute on average keeps its count', () => {+ let now = Date.parse('2026-10-01T12:00:00Z')+ const health = createProductHealth(vi.fn(), () => now, cleanHealthState(null, now))+ const sample = vi.fn(() => ({ rss: 1 }))+ health.sample(sample); now += 44_999; health.sample(sample)+ expect(sample).toHaveBeenCalledOnce()+ now += 1; health.sample(sample)+ expect(sample).toHaveBeenCalledTimes(2)+})++it('bounds RAM, expires unobserved intent, resets on a changed choice and samples at most once a tick', () => {let now = Date.parse('2026-10-01T12:00:00Z')const add = vi.fn(), health = createProductHealth(add, () => now, cleanHealthState(null, now))for (let i = 0; i < 1001; i++) health.intent(`intent-${i}`, 'interactive')diff --git a/cli/src/gateway/productHealth.ts b/cli/src/gateway/productHealth.tsindex 6b0d5be6c..01238f292 100644--- a/cli/src/gateway/productHealth.ts+++ b/cli/src/gateway/productHealth.ts@@ -67,7 +67,9 @@ export function createProductHealth(add: (metric: ProductUsageMetric, day?: stristate.week = week},sample(sample?: () => { rss: number; cpuPercent?: number }) {- if (!sample || now() - sampledAt < 60000) return+ // Once a tick: the collector's ticks are 45 to 75 seconds apart (gateway/productUsage.ts), a minute on+ // average, so a 60-second floor would skip every other short tick and undercount the samples.+ if (!sample || now() - sampledAt < 45000) returnsampledAt = now()try {const value = sample()diff --git a/cli/src/gateway/productUsage.spec.ts b/cli/src/gateway/productUsage.spec.tsindex 632fcb764..d95754ea6 100644--- a/cli/src/gateway/productUsage.spec.ts+++ b/cli/src/gateway/productUsage.spec.ts@@ -1,7 +1,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 { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'import { PRODUCT_USAGE_METRICS } from '../lib/productUsageContract.js'import { createProductUsage, type ProductUsageDeps } from './productUsage.js'@@ -342,14 +342,14 @@ it('tracks a durable launch through polls without persisting its receipt or counnow += 65_000usage.launch({ id, phase: 'failed', failure: 'setup' }); usage.launch({ id, phase: 'failed', failure: 'setup' })await usage.sync()- 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(totals()).toEqual({ measurement_v2_installation_days: 1, first_launch_installations: 1, first_launch_engine_other: 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({ measurement_v2_installation_days: 1, first_launch_installations: 1, launch_started: 1, launch_unobserved: 1 })+ expect(totals()).toEqual({ measurement_v2_installation_days: 1, first_launch_installations: 1, first_launch_engine_other: 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()@@ -362,7 +362,9 @@ it('batches the complete vocabulary below the wire bound without losing counts',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)+ // Summed once: summing every report again for each of the vocabulary's names took most of this test's time.+ const all = totals()+ for (const metric of PRODUCT_USAGE_METRICS) expect(all[metric], metric).toBeGreaterThanOrEqual(1)expect(JSON.parse(readFileSync(file, 'utf8')).days).toEqual({})})@@ -436,3 +438,281 @@ it('drops a corrupt oversized pending report without sending an oversized requesexpect(totals().turns_started).toBe(1)expect(Buffer.byteLength(JSON.stringify(sent[0]))).toBeLessThan(8192)})++const CLI = { surface: 'cli', release: '0.4.9', platform: 'macos', channel: 'production' } as const+const ID = 'fixture-creation-one'+const flush = async () => { for (let i = 0; i < 4; i++) await usage.sync() }++it('names the code of an `other` launch failure, so the codes add up to launch_failed_other', async () => {+ await usage.sync()+ const fail = (id: string, signal: Partial<Parameters<typeof usage.launch>[0]>) => {+ usage.launch({ id, phase: 'start' }); usage.launch({ id, phase: 'failed', ...signal })+ }+ fail('fixture-creation-one', { failure: 'other', code: 'invalid_prompt' })+ fail('fixture-creation-two', { failure: 'other', code: 'PRIVATE_CANARY' as never })+ fail('fixture-creation-three', { failure: 'other' })+ fail('fixture-creation-four', { failure: 'other', code: 'none' })+ fail('fixture-creation-five', { failure: 'setup', code: 'invalid_prompt' })+ await flush()+ const t = totals()+ expect(t).toMatchObject({ launch_failed: 5, launch_failed_other: 4, launch_failed_setup: 1,+ launch_failed_code_invalid_prompt: 1, launch_failed_code_unlisted: 2, launch_failed_code_none: 1 })+ const codes = Object.entries(t).filter(([name]) => name.startsWith('launch_failed_code_')).reduce((n, [, v]) => n + v, 0)+ expect(codes).toBe(t.launch_failed_other)+ expect(JSON.stringify(sent)).not.toContain('PRIVATE_CANARY')+})++it('counts a created launch whose engine then did not start as a late failure, once, by its code', async () => {+ await usage.sync()+ usage.launch({ id: ID, phase: 'start' })+ usage.launch({ id: ID, phase: 'created', agent: 'PRIVATE_AGENT_CANARY' })+ usage.launchState('PRIVATE_AGENT_CANARY', 'starting')+ usage.launchState('PRIVATE_AGENT_CANARY', 'failed', 'engine_did_not_start')+ usage.launchState('PRIVATE_AGENT_CANARY', 'failed', 'engine_did_not_start')+ // An agent that started is no late failure, and neither is one no launch here created.+ usage.launch({ id: 'fixture-creation-two', phase: 'start' })+ usage.launch({ id: 'fixture-creation-two', phase: 'created', agent: 'started-agent' })+ usage.launchState('started-agent', 'ready'); usage.launchState('started-agent', 'failed', 'start_timeout')+ usage.launchState('another-agent', 'failed', 'start_timeout')+ // Already failed when a status poll's reply said created.+ usage.launch({ id: 'fixture-creation-three', phase: 'start' })+ usage.launch({ id: 'fixture-creation-three', phase: 'created', late: true, code: 'start_timeout' })+ usage.launch({ id: 'fixture-creation-four', phase: 'start' })+ usage.launch({ id: 'fixture-creation-four', phase: 'created', agent: 'timed-agent' })+ usage.launchState('timed-agent', 'failed', 'PRIVATE_CANARY' as never)+ await flush()+ expect(totals()).toMatchObject({ launch_created: 4, launch_late_failed: 3, launch_late_failed_code_engine_did_not_start: 1,+ launch_late_failed_code_start_timeout: 1, launch_late_failed_code_unlisted: 1 })+ expect(totals().launch_failed).toBeUndefined()+ expect(JSON.stringify(sent) + readFileSync(file, 'utf8')).not.toContain('CANARY')+})++it('watches a created launch\'s agent for a bounded time, and not past an opt-out', async () => {+ await usage.sync()+ usage.launch({ id: ID, phase: 'start' }); usage.launch({ id: ID, phase: 'created', agent: 'slow-agent' })+ now += 15 * 60_000; await usage.sync()+ usage.launchState('slow-agent', 'failed', 'start_timeout')+ usage.launch({ id: 'fixture-creation-two', phase: 'start' }); usage.launch({ id: 'fixture-creation-two', phase: 'created', agent: 'kept-agent' })+ enabled = false; await usage.sync(); enabled = true; await usage.sync()+ usage.launchState('kept-agent', 'failed', 'start_timeout')+ await flush()+ expect(totals().launch_late_failed).toBeUndefined()+})++it('counts an installation\'s first launch by its engine and, for Claude Code or Codex, whether it was signed in, once', async () => {+ await usage.stop()+ const engineSignedIn = vi.fn(async (engine: 'claude' | 'codex') => engine === 'claude')+ usage = createProductUsage({ file, now: () => now, request, engineSignedIn })+ await usage.sync()+ usage.launch({ id: ID, phase: 'start', engine: 'claude' })+ usage.launch({ id: 'fixture-creation-two', phase: 'start', engine: 'codex' })+ await vi.waitFor(() => expect(engineSignedIn).toHaveBeenCalledOnce())+ await flush()+ expect(totals()).toMatchObject({ first_launch_installations: 1, first_launch_engine_claude: 1, first_launch_claude_signed_in: 1 })+ expect(Object.keys(totals()).filter(name => name.startsWith('first_launch_') && !name.includes('_24h_')).sort())+ .toEqual(['first_launch_claude_signed_in', 'first_launch_engine_claude', 'first_launch_installations'])++ for (const [engine, answer, counted] of [['codex', null, 'first_launch_codex_unknown'], ['codex', false, 'first_launch_codex_signed_out'],+ ['claude', 'throws', 'first_launch_claude_unknown']] as const) {+ await usage.stop(); rmSync(file, { force: true }); sent = []+ const check = vi.fn(async () => { if (answer === 'throws') throw new Error('PRIVATE_CANARY'); return answer })+ usage = createProductUsage({ file, now: () => now, request, engineSignedIn: check })+ await usage.sync(); usage.launch({ id: ID, phase: 'start', engine })+ await vi.waitFor(() => expect(check).toHaveBeenCalledOnce())+ await flush()+ expect(totals()).toMatchObject({ [`first_launch_engine_${engine}`]: 1, [counted]: 1 })+ }+ // Another engine, or none named: its name only, and no look at any account.+ for (const engine of ['opencode', 'cursor', undefined] as const) {+ await usage.stop(); rmSync(file, { force: true }); sent = []+ const check = vi.fn(async () => true)+ usage = createProductUsage({ file, now: () => now, request, engineSignedIn: check })+ await usage.sync(); usage.launch({ id: ID, phase: 'start', engine: engine as never })+ await flush()+ expect(totals()).toMatchObject({ [`first_launch_engine_${engine === 'opencode' ? 'opencode' : 'other'}`]: 1 })+ expect(check).not.toHaveBeenCalled()+ }+ expect(JSON.stringify(sent)).not.toContain('PRIVATE_CANARY')+})++it('drops a first launch\'s account answer that comes after the choice changed', async () => {+ await usage.stop()+ let answer!: (value: boolean) => void+ usage = createProductUsage({ file, now: () => now, request, engineSignedIn: () => new Promise(resolve => { answer = resolve }) })+ await usage.sync(); usage.launch({ id: ID, phase: 'start', engine: 'codex' })+ await vi.waitFor(() => expect(answer).toBeTypeOf('function'))+ revision = 1; await usage.sync()+ answer(true); await flush()+ expect(totals().first_launch_codex_signed_in).toBeUndefined()+})++it('writes a clean exit before stop() returns: a collector started next on its file sees no unclean restart', async () => {+ await usage.stop()+ usage = createProductUsage({ file, now: () => now, request, context: CLI })+ await usage.sync()+ expect(JSON.parse(readFileSync(file, 'utf8')).health.cleanExit).toBe(false)+ // Not awaited, as the gateway's stop never waited for it, and its process exited next.+ void usage.stop()+ expect(JSON.parse(readFileSync(file, 'utf8')).health.cleanExit).toBe(true)+ usage = createProductUsage({ file, now: () => now, request, context: CLI })+ await flush()+ expect(totals().health_cli_unclean_restart).toBeUndefined()+ expect(totals().health_cli_install_unknown).toBe(2)+})++it('does not let a write already on its way put an older state over the clean exit', async () => {+ await usage.stop()+ let release: (() => void) | undefined, block = false+ usage = createProductUsage({ file, now: () => now, request, context: CLI, write: async (target, data) => {+ if (block) await new Promise<void>(resolve => { release = resolve })+ writeFileSync(target, data)+ } })+ await usage.sync()+ block = true+ usage.counter('create_requests')+ const flushing = usage.sync()+ await vi.waitFor(() => expect(release).toBeTypeOf('function'))+ const stopped = usage.stop()+ expect(JSON.parse(readFileSync(file, 'utf8')).health.cleanExit).toBe(true)+ release!()+ await stopped; await flushing+ expect(JSON.parse(readFileSync(file, 'utf8')).health.cleanExit).toBe(true)+ usage = createProductUsage({ file, now: () => now, request, context: CLI })+ await flush()+ expect(totals().health_cli_unclean_restart).toBeUndefined()+})++it('counts a collector that was killed, without stop(), as exactly one unclean restart', async () => {+ await usage.stop()+ usage = createProductUsage({ file, now: () => now, request, context: CLI, random: () => 0.999 })+ await usage.sync()+ // Killed: no stop(), nothing written after this.+ usage = createProductUsage({ file, now: () => now, request, context: CLI })+ await usage.sync(); await usage.stop()+ usage = createProductUsage({ file, now: () => now, request, context: CLI })+ await flush()+ expect(totals().health_cli_unclean_restart).toBe(1)+})++it('stops once: a second stop writes nothing over the first one\'s final state', async () => {+ await usage.sync(); usage.observe('turn_started', 'a', false); retry = true; await usage.sync()+ await usage.stop(true)+ expect(await usage.stop()).toBe(true)+ expect(JSON.parse(readFileSync(file, 'utf8'))).toMatchObject({ pending: null, days: {} })+})++describe('when reports go', () => {+ const T0 = Date.parse('2026-10-16T09:45:00Z')+ const at = (ms: number) => T0 + ms+ let posts: number[], answers: Array<{ status: number; body: Record<string, unknown>; retryAfterMs?: number }>+ const start = (random: () => number) => {+ usage = createProductUsage({ file, now: () => Date.now(), request, random,+ write: async (target, data) => { writeFileSync(target, data) } })+ }+ beforeEach(async () => {+ await usage.stop()+ vi.useFakeTimers({ now: T0 })+ posts = []; answers = []+ request.mockImplementation(async (method: string, _path: string, body?: unknown) => {+ if (method === 'GET') return { status: 200, body: { data: { enabled: true, revision: 0 } } }+ posts.push(Date.now()); sent.push(structuredClone(body))+ return answers.shift() ?? { status: 200, body: { data: { accepted: true } } }+ })+ })+ afterEach(() => { vi.useRealTimers() })++ it.each([[0, 10_000], [0.5, 35_000], [0.99999, 59_999]])('sends the first report a random 10 to 60 seconds after the gateway starts (%s)', async (r, first) => {+ // What the last run left to send, which a gateway started by a release used to send that same second.+ writeFileSync(file, JSON.stringify({ revision: 0, days: { '2026-10-16': { search_requests: 1 } } }))+ start(() => r)+ // The gateway's own first read: the choice, so collection starts, and no report.+ await usage.sync(false); usage.counter('search_requests')+ expect(posts).toEqual([])+ await vi.advanceTimersByTimeAsync(first - 1)+ expect(posts).toEqual([])+ await vi.advanceTimersByTimeAsync(1)+ expect(posts).toEqual([at(first)])+ })++ it('spreads the later ticks across 45 to 75 seconds', async () => {+ const values = [0, 0, 0.5, 0.99999]+ start(() => values.shift() ?? 0)+ const reads: number[] = []+ const answer = request.getMockImplementation()!+ request.mockImplementation(async (method, path, body) => { if (method === 'GET') reads.push(Date.now()); return answer(method, path, body) })+ await usage.sync(false)+ await vi.advanceTimersByTimeAsync(200_000)+ // The gateway's own read, then a tick 10 s on (the first report's), then 45, 60 and 74.999 s apart.+ expect(reads).toEqual([at(0), at(10_000), at(55_000), at(115_000), at(189_999)])+ })++ it('backs off a busy backend, longer each time and at most half an hour, counting each attempt as before', async () => {+ start(() => 0.5)+ await usage.sync(false); usage.counter('search_requests')+ answers = Array.from({ length: 12 }, () => ({ status: 429, body: { error: { code: 'USAGE_BUSY' } } }))+ await vi.advanceTimersByTimeAsync(3 * 3600_000)+ // Ticks every 60 s here (0.5 of 45 to 75) and half of a ceiling that doubles from two minutes to the half+ // hour: twelve refusals in 2.3 hours, where a report each minute made 135 attempts.+ const gaps = posts.slice(1, 13).map((t, i) => t - posts[i])+ expect(gaps).toEqual([60_000, 120_000, 240_000, 480_000, ...Array(8).fill(900_000)])+ // Answered again: a report each tick, and each refused attempt counted once.+ const attempts = posts.length+ usage.counter('search_requests'); await vi.advanceTimersByTimeAsync(60_000)+ usage.counter('search_requests'); await vi.advanceTimersByTimeAsync(60_000)+ expect(posts.length).toBe(attempts + 2)+ expect(totals().health_cli_report_rejected).toBe(12)+ expect(totals().health_cli_report_failure_rate_limited).toBe(12)+ })++ it.each([[503, 'USAGE_WRITE_CONFLICT'], [504, 'BACKEND_TIMEOUT'], [502, 'BACKEND_UNREACHABLE']])('backs off a %i (%s) too', async (status, code) => {+ start(() => 0.5)+ await usage.sync(false); usage.counter('search_requests')+ answers = [{ status, body: { error: { code } } }, { status, body: { error: { code } } }]+ await vi.advanceTimersByTimeAsync(35_000 + 60_000 + 60_000)+ expect(posts).toEqual([at(35_000), at(95_000)])+ })++ it('backs off a report whose request threw, and not one the backend refused as invalid', async () => {+ start(() => 0.5)+ await usage.sync(false); usage.counter('search_requests')+ const choice = async () => ({ status: 200, body: { data: { enabled: true, revision: 0 } } })+ const thrown = async () => { posts.push(Date.now()); throw new Error('PRIVATE_CANARY') }+ request.mockImplementationOnce(choice).mockImplementationOnce(thrown).mockImplementationOnce(choice).mockImplementationOnce(thrown)+ await vi.advanceTimersByTimeAsync(95_000)+ expect(posts).toEqual([at(35_000), at(95_000)])+ // Two in a row: up to four minutes, here two, so the tick at 155 s sends nothing.+ answers = [{ status: 400, body: {} }]+ await vi.advanceTimersByTimeAsync(120_000)+ expect(posts).toEqual([at(35_000), at(95_000), at(215_000)])+ // The backend's answer, if a refusal: the next report goes at the next tick.+ usage.counter('search_requests'); await vi.advanceTimersByTimeAsync(60_000)+ expect(posts).toEqual([at(35_000), at(95_000), at(215_000), at(275_000)])+ expect(JSON.stringify(sent)).not.toContain('PRIVATE_CANARY')+ })++ it('waits at least what Retry-After asks, held to the half-hour ceiling', async () => {+ start(() => 0)+ await usage.sync(false); usage.counter('search_requests')+ answers = [{ status: 429, body: {}, retryAfterMs: 10 * 60_000 }, { status: 503, body: {}, retryAfterMs: 5 * 3600_000 }]+ await vi.advanceTimersByTimeAsync(10_000)+ expect(posts).toEqual([at(10_000)])+ await vi.advanceTimersByTimeAsync(10 * 60_000 - 1)+ expect(posts).toHaveLength(1)+ await vi.advanceTimersByTimeAsync(45_000)+ expect(posts).toHaveLength(2)+ expect(posts[1]).toBe(at(640_000))+ // Five hours asked: held to the half hour.+ await vi.advanceTimersByTimeAsync(at(640_000 + 30 * 60_000) - 1 - Date.now())+ expect(posts).toHaveLength(2)+ await vi.advanceTimersByTimeAsync(1)+ expect(posts).toEqual([at(10_000), at(640_000), at(2_440_000)])+ })++ it('stops ticking once stopped', async () => {+ start(() => 0)+ await usage.sync(false); usage.counter('search_requests')+ await usage.stop()+ await vi.advanceTimersByTimeAsync(10 * 60_000)+ expect(request).toHaveBeenCalledTimes(1)+ })+})diff --git a/cli/src/gateway/productUsage.ts b/cli/src/gateway/productUsage.tsindex 952d30977..26fd12f9c 100644--- a/cli/src/gateway/productUsage.ts+++ b/cli/src/gateway/productUsage.ts@@ -1,20 +1,40 @@import { cleanUsageContext, type ProductUsageContext } from '../lib/productHealthContract.js'import { cleanHealthState, createProductHealth, type HealthState } from './productHealth.js'import { reportFailure } from './reportFailure.js'-import { readFileSync, statSync } from 'node:fs'+import { mkdirSync, readFileSync, renameSync, statSync, writeFileSync } 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_ACTIONS, PRODUCT_USAGE_AUTOMATIC_ACTIONS, PRODUCT_USAGE_DAYS, PRODUCT_USAGE_MAX_COUNT, PRODUCT_USAGE_METRICS,- PRODUCT_USAGE_USER_OPENED_ACTIONS,- type ProductUsageChoice, type ProductUsageMetric, type ProductUsageReport } from '../lib/productUsageContract.js'+import { engineAccount } from '../lib/engineAccount.js'+import { loginShellEnvironment } from '../lib/loginShellEnv.js'+import { launchEngine, type ProductUsageLaunchSignal } from '../lib/productUsageSignals.js'+import { LAUNCH_ERROR_CODES, PRODUCT_USAGE_ACTIONS, PRODUCT_USAGE_AUTOMATIC_ACTIONS, PRODUCT_USAGE_DAYS,+ PRODUCT_USAGE_MAX_COUNT, PRODUCT_USAGE_METRICS, PRODUCT_USAGE_USER_OPENED_ACTIONS,+ type LaunchErrorCode, type ProductUsageChoice, type ProductUsageMetric, type ProductUsageReport } from '../lib/productUsageContract.js'const DAY = 86_400_000const 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 = 64const metricSet = new Set<string>(PRODUCT_USAGE_METRICS)+const launchCodes = new Set<string>(LAUNCH_ERROR_CODES)+const listed = (code: unknown): LaunchErrorCode => typeof code === 'string' && launchCodes.has(code) ? code as LaunchErrorCode : 'unlisted'+// Every daemon of a release updates at the same second (:45), so with a report at start and then one a minute+// the fleet reported together: the backend's write conflicts and USAGE_BUSY refusals (41 and 48 on 2026-10-16,+// production counters). The first report waits a random 10 to 60 seconds and each later tick 45 to 75, so the+// fleet spreads out again; the mean interval stays a minute.+const FIRST_REPORT_MS: readonly [number, number] = [10_000, 60_000]+const TICK_MS: readonly [number, number] = [45_000, 75_000]+// A refusal that says the backend is busy or down (429, 5xx, a timeout) waits longer each time it repeats: full+// jitter under a doubling ceiling, at most half an hour, and never sooner than its Retry-After.+const BACKOFF_BASE_MS = 60_000+const BACKOFF_MAX_MS = 30 * 60_000+// A created launch's agent is watched this long for its start failing: the new-pane watcher gives an engine ten+// minutes (core/agents/newPane.ts).+const LATE_FAILURE_WATCH_MS = 15 * 60_000+/** Which collector of this process last opened each file: a stopped collector's write that lands late puts its+ * final state back only while no newer one (the gateway started again) writes that file. */+const writers = new Map<string, object>()// Feature reach is a person's use; the reads the apps make on their own count only their reliability,// unless the app says a person opened that list (`<action>_user_requests`, its own first/repeat).type Reach = typeof PRODUCT_USAGE_ACTIONS[number] | `${typeof PRODUCT_USAGE_USER_OPENED_ACTIONS[number]}_user`@@ -57,23 +77,40 @@ export interface ProductUsageDeps {file: stringcontext?: ProductUsageContextsample?: () => { rss: number; cpuPercent?: number }- request(method: string, path: string, body?: unknown): Promise<{ status: number; body: Record<string, unknown> }>+ /** `retryAfterMs`: the answer's Retry-After, when it had one (gateway/accountHttp.ts). */+ request(method: string, path: string, body?: unknown): Promise<{ status: number; body: Record<string, unknown>; retryAfterMs?: number }>now?(): numberuuid?(): string+ /** In [0, 1): when reports go. A seam for tests. */+ random?(): number+ /** Whether Claude Code or Codex has a credential here: true, false, or null when this computer cannot say. */+ engineSignedIn?(engine: 'claude' | 'codex'): Promise<boolean | null>/** Test seam for a slow or unavailable disk; never called from an event observer. */write?(file: string, value: string): Promise<void>}+/** Presence only (lib/engineAccount.ts: a credential file stat'ed or parsed for a token, a Keychain item looked up+ * without its secret), in this process's own environment: the gateway starts no login shell for it, so a key only+ * a shell profile exports reads as signed out to a daemon launchd or systemd started. No folder is scanned. */+const engineSignedIn = async (engine: 'claude' | 'codex'): Promise<boolean | null> =>+ (await engineAccount(engine, { env: { ...loginShellEnvironment(), ...process.env }, lastUsed: false })).signedIn+/** A reporting component of the gateway service; the core never waits for it.* Counts lifecycle facts only. No transcript, prompt, response, tool or error object enters this API.- * Agent identifiers live only in the bounded in-memory duration map and never reach disk or HTTP.+ * Agent identifiers live only in the bounded in-memory turn and launch maps and never reach disk or HTTP.*/export function createProductUsage(deps: ProductUsageDeps) {- const now = deps.now ?? Date.now, uuid = deps.uuid ?? randomUUID+ const now = deps.now ?? Date.now, uuid = deps.uuid ?? randomUUID, random = deps.random ?? Math.randomconst context = cleanUsageContext(deps.context)let state = fresh(-1), enabled = false, stopped = false, active = falselet syncing: Promise<void> | null = null, persistTimer: ReturnType<typeof setTimeout> | undefinedlet writing: Promise<boolean> | null = null, writeAgain = false+ // What stop() wrote as the process went: nothing written after it may replace it.+ let final: string | null = null+ const writer = {}+ writers.set(deps.file, writer)+ // A report waits until `postAt` after a busy or failing backend; `backoffs` counts those refusals in a row.+ let postAt = 0, backoffs = 0// hn's counters: those it observed before the first choice read, held in RAM until that is known// (hn is often opened at the daemon's start), and the UTC day a backend from before `tui` refused// them. Neither is persisted; a restart tries again.@@ -81,6 +118,9 @@ export function createProductUsage(deps: ProductUsageDeps) {const tuiRefused = (): boolean => tuiRefusedDay === key(now())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> }>()+ /** The agents of created launches still starting, by agent id (RAM only), with when each was created. */+ const starting = new Map<string, number>()+ const forget = (): void => { running.clear(); launches.clear(); starting.clear() }try {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.@@ -159,7 +199,20 @@ export function createProductUsage(deps: ProductUsageDeps) {if (pruned) (state.days[key(now())] ??= {}).measurement_queue_pruned = 1return JSON.stringify(state)}+ /** The final state, on disk before stop() returns. `harness stop`, an update, a sign-in's restart, a service+ * install and an OS logout end the process right after it, and the asynchronous write went with it: every+ * planned stop read as an unclean restart (health_cli_unclean_restart, 69 to 170 on 2026-10-16, production+ * counters). Its own temporary file, so it never interleaves with a write still on its way; at most 256 KiB. */+ function writeFinal(value: string): boolean {+ try {+ mkdirSync(dirname(deps.file), { recursive: true, mode: 0o700 })+ writeFileSync(deps.file + '.final.tmp', value, { mode: 0o600 })+ renameSync(deps.file + '.final.tmp', deps.file)+ return true+ } catch { return false }+ }function persist(): Promise<boolean> {+ if (final !== null) return writing ?? Promise.resolve(true)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.@@ -172,11 +225,18 @@ export function createProductUsage(deps: ProductUsageDeps) {else {await mkdir(dirname(deps.file), { recursive: true, mode: 0o700 })await writeFile(deps.file + '.tmp', value, { mode: 0o600 })+ // Stopped meanwhile: the final state is on disk, and this older snapshot must not go over it.+ if (final !== null) breakawait rename(deps.file + '.tmp', deps.file)}- } while (writeAgain)+ } while (writeAgain && final === null)return true} catch { enabled = false; return false }+ finally {+ // A write already on its way when stop() wrote can land after it: the final state goes back, unless a+ // newer collector in this process (the gateway started again) writes this file now.+ if (final !== null && writers.get(deps.file) === writer) writeFinal(final)+ }})().finally(() => { writing = null })}function dirty(): void {@@ -213,19 +273,34 @@ export function createProductUsage(deps: ProductUsageDeps) {}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(); health.reset()+ state = fresh(value.revision); forget(); health.reset()enabled = falseif (!await persist()) return}enabled = value.enabled && !stopped}- async function syncOnce(): Promise<void> {+ /** After a refusal that says the backend is busy or failing: full jitter under a ceiling that doubles with each+ * one in a row, up to half an hour, and not before the answer's Retry-After (also held to that half hour). */+ function backOff(retryAfterMs?: number): void {+ backoffs = Math.min(backoffs + 1, 16)+ const ceiling = Math.min(BACKOFF_MAX_MS, BACKOFF_BASE_MS * 2 ** backoffs)+ const asked = typeof retryAfterMs === 'number' && Number.isFinite(retryAfterMs) && retryAfterMs > 0 ? retryAfterMs : 0+ postAt = now() + Math.min(BACKOFF_MAX_MS, Math.max(asked, Math.floor(unit() * ceiling)))+ }+ /** A random number in [0, 1); anything else the source gives reads as the middle. */+ function unit(): number { const r = random(); return Number.isFinite(r) && r >= 0 && r < 1 ? r : 0.5 }+ /** A delay in [low, high) milliseconds, at random: the fleet's reports spread out across it. */+ const between = ([low, high]: readonly [number, number]): number => low + Math.floor(unit() * (high - low))+ /** [post]: send a report now. The gateway's first read of the choice does not, so collection starts at once+ * and the report waits for the first tick; every tick reads the choice and posts unless backing off. */+ async function syncOnce(post: boolean): Promise<void> {+ let posting = falsetry {const response = await deps.request('GET', '/api/product-usage/settings')if (stopped) returnconst body = response.body.data as ProductUsageChoice | undefinedif (response.status !== 200 || typeof body?.enabled !== 'boolean'- || !Number.isSafeInteger(body.revision) || body.revision < 0) { enabled = false; running.clear(); launches.clear(); health.clearObservations(); return }+ || !Number.isSafeInteger(body.revision) || body.revision < 0) { enabled = false; forget(); health.clearObservations(); return }await choice(body)if (!choiceKnown) {// Counted only now that sharing is known to be on; discarded when it is off.@@ -246,12 +321,14 @@ export function createProductUsage(deps: ProductUsageDeps) {if (!launch.done && now() - launch.started >= 15 * 60_000) { launch.done = true; add('launch_unobserved') }if (now() - launch.started >= 35 * 60_000) launches.delete(id)}+ for (const [agent, at] of starting) if (now() - at >= LATE_FAILURE_WATCH_MS) starting.delete(agent)if (active) markActive()// Refused today: hn's counts go, rather than waiting to become a past day's report.if (tuiRefused()) for (const day of Object.keys(state.days)) {for (const metric of Object.keys(state.days[day])) if (isTuiMetric(metric)) delete state.days[day][metric as ProductUsageMetric]if (!Object.keys(state.days[day]).length) { delete state.days[day]; delete state.dayContexts[day] }}+ if (!post) returnif (!state.pending) {const day = Object.keys(state.days).sort().find(d => validDay(d) && Object.keys(state.days[d]).length)if (!day) return@@ -269,11 +346,16 @@ export function createProductUsage(deps: ProductUsageDeps) {if (!await persist() || stopped || !enabled) returnconst report = state.pendingif (!report) return+ posting = trueconst answer = await deps.request('POST', '/api/product-usage/report', report)if (stopped) return+ // Busy, failing or out of time (429, 5xx; a timeout is a 504): the next report waits. Anything else is an+ // answer, and the reports go at the ticks again. Either way each attempt counts as before.+ if (answer.status === 429 || answer.status >= 500) backOff(answer.retryAfterMs)+ else { backoffs = 0; postAt = 0 }const result = answer.body.data as { accepted?: boolean; reason?: string } | undefinedif (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(); health.reset(); await persist() }+ else if (result?.reason === 'CHOICE_CHANGED') { enabled = false; state = fresh(-1); forget(); health.reset(); await persist() }else if (result?.reason === 'EXPIRED') { state.pending = null; add('health_cli_report_expired'); await persist() }else if (answer.status === 400 && Object.keys(report.counters).length && Object.keys(report.counters).every(isTuiMetric)) {// A backend from before `tui` knows none of hn's names. That is not a failed delivery, so it@@ -287,13 +369,40 @@ export function createProductUsage(deps: ProductUsageDeps) {if (answer.status === 400 || answer.status === 413) { state.pending = null; await persist() }}} catch {+ if (posting) backOff()if (enabled) add('health_cli_report_failed')- enabled = false; running.clear(); launches.clear(); health.clearObservations() /* No error text or request body in logs. */+ enabled = false; forget(); health.clearObservations() /* No error text or request body in logs. */}}- const sync = (): Promise<void> => syncing ??= syncOnce().finally(() => { syncing = null })- const timer = setInterval(() => { void sync() }, 60_000)- timer.unref()+ /** Read the choice and, with [post] (the default), send a report now. */+ const sync = (post = true): Promise<void> => syncing ??= syncOnce(post).finally(() => { syncing = null })+ let timer: ReturnType<typeof setTimeout> | undefined+ const schedule = (ms: number): void => {+ if (stopped) return+ timer = setTimeout(() => { void sync(now() >= postAt).finally(() => schedule(between(TICK_MS))) }, ms)+ timer.unref?.()+ }+ schedule(between(FIRST_REPORT_MS))++ /** A created launch's start failed after its reply said created: counted once, by its listed code. */+ function lateFailure(code: unknown): void {+ add('launch_late_failed')+ add(`launch_late_failed_code_${listed(code)}`)+ }+ /** The engine of an installation's first launch, and for Claude Code or Codex whether it had a credential here:+ * one look, once per installation, counted on the first launch's day. */+ function firstLaunch(engine: unknown): void {+ const name = launchEngine(engine)+ add(`first_launch_engine_${name}`)+ if (name !== 'claude' && name !== 'codex') return+ const owner = state, day = key(state.firstLaunchAt ?? now())+ const counted = (signedIn: boolean | null): void => {+ // A choice change or a stop since then took this cohort's counts with it.+ if (!enabled || stopped || state !== owner) return+ add(`first_launch_${name}_${signedIn === true ? 'signed_in' : signedIn === false ? 'signed_out' : 'unknown'}`, day)+ }+ void Promise.resolve().then(() => (deps.engineSignedIn ?? engineSignedIn)(name)).then(counted, () => counted(null))+ }return {sync,@@ -324,6 +433,7 @@ export function createProductUsage(deps: ProductUsageDeps) {if (launches.has(signal.id)) returnif (!state.launchedBefore) {state.launchedBefore = true; state.firstLaunchAt = now(); add('first_launch_installations')+ firstLaunch(signal.engine)}if (launches.size >= 1000) {const oldest = launches.keys().next().value!@@ -345,10 +455,29 @@ export function createProductUsage(deps: ProductUsageDeps) {if (signal.phase === 'failed') {const kind = ['setup', 'auth', 'unavailable', 'invalid'].includes(signal.failure ?? '') ? signal.failure! : 'other'add(`launch_failed_${kind}` as ProductUsageMetric)+ // 23 of 25 launch failures were `other` on 2026-10-16 (production counters): the code says which.+ if (kind === 'other') add(`launch_failed_code_${listed(signal.code)}`)+ }+ if (signal.phase === 'created') {+ // Its start had already failed by the reply that said created (a status poll), or it is still starting:+ // watched for its agent's frame saying failed (launchState below).+ if (signal.late === true) lateFailure(signal.code)+ else if (typeof signal.agent === 'string' && signal.agent.length > 0 && signal.agent.length <= 256) {+ if (starting.size >= 1000) starting.delete(starting.keys().next().value!)+ starting.set(signal.agent, now())+ }}const elapsed = Math.max(0, now() - launch.started)add(elapsed < 10_000 ? 'launch_under_10s' : elapsed < 60_000 ? 'launch_10s_to_1m' : elapsed < 300_000 ? 'launch_1m_to_5m' : 'launch_over_5m')},+ /** An agent's launch state from its frame. Only an agent a created launch made is looked at, until its start+ * is decided: failed is a late failure (ENGINE_DID_NOT_START, ENGINE_NOT_INSTALLED, START_TIMEOUT set after the+ * reply said created, core/agents/newPane.ts), ready ends the watch. */+ launchState(agent: string, value: string, code?: LaunchErrorCode): void {+ if (!enabled || stopped || !starting.size || !starting.has(agent)) return+ if (value === 'failed') { starting.delete(agent); lateFailure(code) }+ else if (value === 'ready') starting.delete(agent)+ },presence(value: boolean): void { active = value; if (value) markActive() },opened(surface: 'desktop' | 'tui'): void {if (!enabled || stopped) return@@ -412,10 +541,15 @@ 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')}},+ /** Stops collecting and writes the final state (clean, or emptied with [discard]) before it returns, so a+ * process that exits next keeps it. The promise settles once a write already on its way has too. */stop(discard = false): Promise<boolean> {- stopped = true; enabled = false; clearInterval(timer); running.clear(); launches.clear(); health.stop(); tuiHeld = []+ if (final !== null) return writing ? writing.then(() => true) : Promise.resolve(true)+ stopped = true; enabled = false; clearTimeout(timer); forget(); health.stop(); tuiHeld = []if (discard) { state = fresh(-1); health.reset() }- return persist()+ final = snapshot()+ const written = writeFinal(final)+ return writing ? writing.then(() => written) : Promise.resolve(written)},}}diff --git a/cli/src/gateway/start.ts b/cli/src/gateway/start.tsindex d25a43d2b..10718d64a 100644--- a/cli/src/gateway/start.ts+++ b/cli/src/gateway/start.ts@@ -148,7 +148,9 @@ export function startGateway(host: GatewayHost): StartedGateway {context: { surface: 'cli', release: VERSION, platform: process.platform === 'darwin' ? 'macos' : process.platform === 'linux' ? 'linux' : process.platform === 'win32' ? 'windows' : 'other', channel: host.autonomousEnv === 'prod' && IS_RELEASE_BUILD ? 'production' : 'development' },sample: gatewayResourceSample(),}) : null- if (usage) { gateway.productUsage = usage; void usage.sync() }+ // The choice is read at once, so collection starts with the gateway; its first report waits for its first+ // tick, a random 10 to 60 seconds on (gateway/productUsage.ts), rather than the second a release started it.+ if (usage) { gateway.productUsage = usage; void usage.sync(false) }/** The identity this machine was removed under is never used again: the next start mints a new one. */const spendIdentity = (): void => {@@ -558,8 +560,11 @@ export function startGateway(host: GatewayHost): StartedGateway {ops,windowRelay,stop: async () => {- // Shutdown never waits for the optional disk queue. The stopped collector cannot upload.- void usage?.stop()+ // Shutdown never waits for the optional disk queue. The stopped collector cannot upload. Its final, clean+ // state is on disk when stop() returns (written synchronously), so a process that exits next keeps it. A write+ // already on its way can still rename an older snapshot over it and put the final state back after: waited for+ // below, at most half a second, so an exit in between does not read as an unclean restart (review of #1393).+ const usageStopped = usage?.stop()clearInterval(devlogTimer)syncer.stop()direct?.stop()@@ -569,6 +574,10 @@ export function startGateway(host: GatewayHost): StartedGateway {tabKey.clear()tabRelay.closeAll()await gateway.stop()+ if (usageStopped) {+ await Promise.race([usageStopped.catch(() => false),+ new Promise<void>(resolve => { setTimeout(resolve, 500).unref?.() })])+ }},}}diff --git a/cli/src/lib/engineAccount.spec.ts b/cli/src/lib/engineAccount.spec.tsindex 5ddb4f9e4..ec09180e2 100644--- a/cli/src/lib/engineAccount.spec.ts+++ b/cli/src/lib/engineAccount.spec.ts@@ -72,6 +72,9 @@ describe('engineAccount', () => {touch(join(root, '.codex', 'sessions', '2026', '09', '30'), 1_850_000_000)expect((await engineAccount('codex', { home: root, ...linux })).lastUsedAt).toBe(1_800_000_000_000)expect((await engineAccount('codex', { home: home(), ...linux })).lastUsedAt).toBeNull()+ // Asked for the sign-in alone (the gateway's first-launch count): no folder is scanned.+ expect(await engineAccount('claude', { home: root, ...linux, lastUsed: false })).toEqual({ signedIn: false, lastUsedAt: null })+ expect(await engineAccount('codex', { home: root, ...linux, lastUsed: false })).toEqual({ signedIn: false, lastUsedAt: null })})it('finds Codex signed in only with a token or key in auth.json, or an API key', async () => {diff --git a/cli/src/lib/engineAccount.ts b/cli/src/lib/engineAccount.tsindex ac808dcbf..00140b78a 100644--- a/cli/src/lib/engineAccount.ts+++ b/cli/src/lib/engineAccount.ts@@ -37,6 +37,9 @@ export interface EngineAccountDeps {platform?: NodeJS.Platform/** Whether a macOS Keychain generic-password item with this service exists. */keychainHas?: (service: string) => Promise<boolean>+ /** False: whether it is signed in only, without the session folders' scan (`lastUsedAt` null). The gateway's+ * first-launch count asks this, once per installation (gateway/productUsage.ts). */+ lastUsed?: boolean}const exists = (path: string) => stat(path).then(() => true, () => false)@@ -86,7 +89,7 @@ export async function engineAccount(engine: AgentEngine, deps: EngineAccountDepsif (engine === 'claude') {const custom = env.CLAUDE_CONFIG_DIRconst dir = custom || join(home, '.claude')- const lastUsedAt = await newestChild(join(dir, 'projects'))+ const lastUsedAt = deps.lastUsed === false ? null : await newestChild(join(dir, 'projects'))if (CLAUDE_ENV.some(name => Boolean(env[name]))) return { signedIn: true, lastUsedAt }if (await exists(join(dir, '.credentials.json'))) return { signedIn: true, lastUsedAt }if (typeof (await readJson(join(dir, 'settings.json')))?.apiKeyHelper === 'string') return { signedIn: true, lastUsedAt }@@ -101,7 +104,7 @@ export async function engineAccount(engine: AgentEngine, deps: EngineAccountDeps}if (engine === 'codex') {const dir = env.CODEX_HOME || join(home, '.codex')- const lastUsedAt = await newestDay(join(dir, 'sessions'))+ const lastUsedAt = deps.lastUsed === false ? null : await newestDay(join(dir, 'sessions'))if (env.OPENAI_API_KEY) return { signedIn: true, lastUsedAt }const auth = await readJson(join(dir, 'auth.json'))const tokens = auth?.tokens as Record<string, unknown> | null | undefineddiff --git a/cli/src/lib/productUsageContract.ts b/cli/src/lib/productUsageContract.tsindex f8568c358..f1ec00673 100644--- a/cli/src/lib/productUsageContract.ts+++ b/cli/src/lib/productUsageContract.ts@@ -59,6 +59,8 @@ export const PRODUCT_USAGE_FLOW_MEASURES = ['started', 'ok', 'failed', 'cancelle'under_1s', '1s_to_10s', '10s_to_1m', 'over_1m'] as constexport const PRODUCT_USAGE_UI_METRICS = PRODUCT_USAGE_UI_SURFACES.flatMap(surface =>PRODUCT_USAGE_FLOWS.flatMap(flow => PRODUCT_USAGE_FLOW_MEASURES.map(measure => `ui_${surface}_${flow}_${measure}` as const)))+export const PRODUCT_USAGE_SETUP_DOWNLOADS = ['opencode', 'codex', 'claude'] as const+export const PRODUCT_USAGE_SETUP_DOWNLOAD_MEASURES = ['started', 'ok', 'failed', 'under_1m', '1m_to_5m', 'over_5m'] 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 =>PRODUCT_USAGE_SETUP_FLOWS.flatMap(flow =>@@ -66,6 +68,56 @@ export const PRODUCT_USAGE_SETUP_METRICS = [...PRODUCT_USAGE_SURFACES.flatMap(su...(['funnel_setup_seen', 'funnel_sign_in_seen', 'funnel_workspace_ready', 'funnel_first_work', 'funnel_first_response','first_work_under_1m', 'first_work_1m_to_5m', 'first_work_over_5m','first_response_under_1m', 'first_response_1m_to_5m', 'first_response_over_5m'] as const).map(m => `setup_desktop_${m}` as const),+ // A step's tool was not installed yet when Desktop checked, so setup installed it: once per step per+ // setup, beside the step's own outcome. Signed-out only (a signed-in report passes an older CLI).+ ...(['setup_harness', 'setup_tmux', 'setup_clipboard'] as const).map(flow => `setup_desktop_${flow}_missing` as const),+ // The agents a new computer downloads beside setup (desktop/lib/bootstrap/agent_prefetch.dart): whether each+ // download put its agent in place, and how long it took. Engine names only, never a path or log line.+ ...PRODUCT_USAGE_SETUP_DOWNLOADS.flatMap(engine => PRODUCT_USAGE_SETUP_DOWNLOAD_MEASURES+ .map(measure => `setup_desktop_agent_download_${engine}_${measure}` as const)),+] as const+/** A new-harness, create or resume refusal outside the four fixed kinds (setup, auth, unavailable,+ * invalid), by its code: the daemon's own fixed error names, lower-cased. On 2026-10-16 production counted+ * 23 of 25 launch failures, 22 create refusals and 9 resume refusals as `other`, with nothing to say+ * which. `unlisted` is a code not named here, `none` a refusal that named no code; each family adds up to+ * its `_other` total, and the late failures to `launch_late_failed`. Codes only, never a message. */+export const LAUNCH_ERROR_CODES = [+ // What a new harness asked for, refused before anything starts (core/agents/launches.ts, lib/engineLaunch.ts).+ 'invalid_codex_home', 'invalid_prompt', 'prompt_too_long', 'prompt_unsupported', 'invalid_agent', 'invalid_session',+ 'invalid_started_by', 'agent_unsupported', 'invalid_runtime_profile', 'grid_engine_unsupported', 'codex_cli_too_old',+ // A new project's folder (lib/projectFolder.ts) and the launch's durable receipt (lib/agentCreationReceipt.ts).+ 'project_exists', 'invalid_repository', 'clone_failed', 'clone_timeout', 'git_unavailable', 'project_preparation_failed',+ 'creation_conflict', 'creation_storage_failed', 'launch_authority_changed', 'internal',+ // The engine itself: preparing it (engines/nativeLaunch.ts) and its start (core/agents/newPane.ts).+ 'engine_cannot_run', 'engine_install_failed', 'engine_did_not_start', 'engine_not_installed', 'start_timeout',+ // A Store harness (core/agents/dshThrough.ts, services/storeLaunch.ts).+ 'dsh_not_installed', 'dsh_unavailable', 'dsh_runtime_failed',+ // A conversation Harness did not start, opened in it (core/agents/adopt.ts, externalResume.ts, lib/registry.ts).+ 'core_not_ready', 'search_unavailable', 'session_in_harness', 'session_not_found', 'session_archived', 'session_folder_gone',+ 'session_open_elsewhere', 'session_busy_in_terminal', 'session_open_in_terminal', 'session_changed', 'resume_session_mismatch',+ // A cloud agent (cloud/).+ 'not_connected', 'cloud_failed', 'rate_limited', 'unreachable', 'busy', 'invalid_request', 'connections_unavailable',+ // A harness that exists: resumed, restarted, changed, closed or deleted (lib/resumeAgentService.ts, core/agents/).+ 'missing_agent_id', 'delete_in_progress', 'agent_busy', 'agent_not_found', 'agent_changed', 'resume_failed', 'resume_unavailable',+ 'resume_preparation_failed', 'grid_credential_required', 'permission_change_requires_stop', 'identity_unavailable',+ 'restart_failed', 'restart_unsupported_backend', 'retarget_unsupported_backend', 'fork_on_grid_unsupported',+ 'no_active_process', 'opencode_sqlite_missing', 'unavailable', 'missing_name', 'missing_update',+ 'invalid_close_request', 'invalid_delete_request', 'close_failed', 'delete_failed',+ 'unlisted', 'none',+] as const+export type LaunchErrorCode = typeof LAUNCH_ERROR_CODES[number]+/** The families counted by code: a launch's failure, its start failing after it was created, and the create+ * and resume requests' refusals. */+export const LAUNCH_ERROR_FAMILIES = ['launch_failed_code', 'launch_late_failed_code', 'create_error_code', 'resume_error_code'] as const+/** The engine an installation's first launch asked for; any other engine is `other`. */+export const PRODUCT_USAGE_LAUNCH_ENGINES = ['opencode', 'claude', 'codex', 'other'] as const+export type ProductUsageLaunchEngine = typeof PRODUCT_USAGE_LAUNCH_ENGINES[number]+/** Whether that engine had a credential on this computer, by presence only (cli/src/lib/engineAccount.ts). */+export const PRODUCT_USAGE_ENGINE_ACCOUNTS = ['signed_in', 'signed_out', 'unknown'] as const+export const PRODUCT_USAGE_LAUNCH_METRICS = [+ ...LAUNCH_ERROR_FAMILIES.flatMap(family => LAUNCH_ERROR_CODES.map(code => `${family}_${code}` as const)),+ ...PRODUCT_USAGE_LAUNCH_ENGINES.map(engine => `first_launch_engine_${engine}` as const),+ ...(['claude', 'codex'] as const).flatMap(engine => PRODUCT_USAGE_ENGINE_ACCOUNTS.map(account => `first_launch_${engine}_${account}` as const)),] as constexport const PRODUCT_USAGE_ACTION_MEASURES = ['requests', 'ok', 'failed', 'pending', 'unknown','error_setup', 'error_auth', 'error_unavailable', 'error_invalid', 'error_other',@@ -80,6 +132,8 @@ export const PRODUCT_USAGE_METRICS = ['duration_under_10s', 'duration_10s_to_1m', 'duration_1m_to_5m', 'duration_over_5m','desktop_opens', 'tui_opens','launch_started', 'launch_created', 'launch_failed', 'launch_cancelled', 'launch_unconfirmed', 'launch_unobserved',+ // A created launch whose engine then did not start: one of the launch_created, never also a launch_failed.+ 'launch_late_failed','launch_wait_install', 'launch_wait_model', 'launch_wait_native', 'launch_wait_other','launch_failed_setup', 'launch_failed_auth', 'launch_failed_unavailable', 'launch_failed_invalid', 'launch_failed_other','launch_under_10s', 'launch_10s_to_1m', 'launch_1m_to_5m', 'launch_over_5m',@@ -87,6 +141,7 @@ export const PRODUCT_USAGE_METRICS = ['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', 'd28_returning_work_installations',+ ...PRODUCT_USAGE_LAUNCH_METRICS,...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)),@@ -95,6 +150,9 @@ export const PRODUCT_USAGE_METRICS = [...PRODUCT_USAGE_UI_METRICS,...PRODUCT_USAGE_ONBOARDING_METRICS,...PRODUCT_USAGE_PHONE_SCREEN_METRICS,+ // Written by the backend itself: a report that named counters this backend does not know yet, which+ // it kept without them (routes/productUsage.ts). One per report, never the names.+ 'health_cli_report_unknown_metric', 'health_desktop_report_unknown_metric', 'health_phone_report_unknown_metric',] as constexport 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.tsindex 13c14501a..b7f202e0a 100644--- a/cli/src/lib/productUsageSignals.spec.ts+++ b/cli/src/lib/productUsageSignals.spec.ts@@ -1,6 +1,9 @@+import { readdirSync, readFileSync } from 'node:fs'+import { join } from 'node:path'+import { fileURLToPath } from 'node:url'import { expect, it, vi } from 'vitest'-import { productObservation, productUsageIntent, productUsageLaunch, productUsageRequest, productUsageSource } from './productUsageSignals.js'-import { PRODUCT_USAGE_FLOWS, PRODUCT_USAGE_METRICS, PRODUCT_USAGE_SETUP_METRICS } from './productUsageContract.js'+import { failureKind, launchErrorCode, productObservation, productUsageIntent, productUsageLaunch, productUsageRequest, productUsageSource } from './productUsageSignals.js'+import { LAUNCH_ERROR_CODES, PRODUCT_USAGE_FLOWS, PRODUCT_USAGE_METRICS, PRODUCT_USAGE_SETUP_METRICS } from './productUsageContract.js'import { HEALTH_MEASURES } from './productHealthContract.js'it('separates automated polling, tool and app RPCs without inspecting error objects or content', () => {@@ -76,10 +79,93 @@ it('reduces durable launch statuses to fixed categories without forwarding errorconst emit = vi.fn(), id = 'fixture-creation-one'productUsageLaunch('agent_create', id, emit)(undefined, 'pending', false, 'install')productUsageLaunch('agent_create_status', id, emit)('PRIVATE_CANARY', 'failed', false, 'PRIVATE_CANARY')- expect(emit.mock.calls.flat()).toEqual([{ id, phase: 'start' }, { id, phase: 'pending', wait: 'install' }, { id, phase: 'failed', failure: 'other' }])+ expect(emit.mock.calls.flat()).toEqual([{ id, phase: 'start', engine: 'other' }, { id, phase: 'pending', wait: 'install' },+ { id, phase: 'failed', failure: 'other', code: 'unlisted' }])expect(JSON.stringify(emit.mock.calls)).not.toContain('PRIVATE_CANARY')})+it.each([+ ['INVALID_PROMPT', 'invalid_prompt'], ['ENGINE_INSTALL_FAILED', 'engine_install_failed'], ['CREATION_STORAGE_FAILED', 'creation_storage_failed'],+ ['PRIVATE_ERROR_WITH_PATH', 'unlisted'], ['__proto__', 'unlisted'], ['UNLISTED', 'unlisted'], ['NONE', 'unlisted'],+ ['INTERNAL'.repeat(20), 'unlisted'], [undefined, 'none'], [{ code: 'INVALID_PROMPT' }, 'none'],+])('names the code of an `other` launch failure %s as %s, from the fixed list only', (error, code) => {+ expect(launchErrorCode(error)).toBe(code)+ const emit = vi.fn()+ productUsageLaunch('agent_create_status', 'fixture-creation-one', emit)(error, 'failed', false, undefined)+ expect(emit).toHaveBeenCalledWith({ id: 'fixture-creation-one', phase: 'failed', failure: 'other', code })+ expect(LAUNCH_ERROR_CODES).toContain(code)+})+it('names no code for a failure of a fixed kind, which its kind already says', () => {+ const emit = vi.fn()+ productUsageLaunch('agent_create_status', 'fixture-creation-one', emit)('TMUX_UNAVAILABLE', 'failed', false, undefined)+ expect(emit).toHaveBeenCalledWith({ id: 'fixture-creation-one', phase: 'failed', failure: 'setup' })+})++it('counts the code of an `other` create or resume refusal beside its kind, so each code family adds up to its `_other`', () => {+ const emit = vi.fn()+ productUsageRequest('agent_create', emit, () => 0, 'app')('PROMPT_TOO_LONG', undefined, false)+ productUsageRequest('agent_create', emit, () => 0, 'app')('PRIVATE_ERROR_WITH_PATH', 'failed', false)+ productUsageRequest('agent_create', emit, () => 0, 'app')(undefined, 'failed', false)+ productUsageRequest('agent_create', emit, () => 0, 'app')('INVALID_CWD', undefined, false)+ productUsageRequest('agent_resume', emit, () => 0, 'app')('SESSION_NOT_FOUND', 'failed', false)+ productUsageRequest('agent_resume', emit, () => 0, 'app')(undefined, undefined, false, false)+ // Other actions keep their kinds only.+ productUsageRequest('agent_restart', emit, () => 0, 'app')('RESTART_FAILED', 'failed', false)+ const names: string[] = emit.mock.calls.flat()+ const family = (prefix: string) => names.filter(name => name.startsWith(prefix)).sort()+ expect(family('create_error_code_')).toEqual(['create_error_code_none', 'create_error_code_prompt_too_long', 'create_error_code_unlisted'])+ expect(names.filter(name => name === 'create_error_other')).toHaveLength(3)+ expect(family('resume_error_code_')).toEqual(['resume_error_code_none', 'resume_error_code_session_not_found'])+ expect(names.filter(name => name === 'resume_error_other')).toHaveLength(2)+ expect(names.some(name => name.startsWith('restart_error_code_'))).toBe(false)+ for (const name of names) expect(PRODUCT_USAGE_METRICS).toContain(name)+ expect(JSON.stringify(names)).not.toContain('PRIVATE_')+})++it('says which engine a new launch asked for, as a fixed name', () => {+ const emit = vi.fn()+ for (const engine of ['claude', 'codex', 'opencode', 'cursor', 'other', 'PRIVATE_ENGINE', undefined, { name: 'claude' }]) {+ productUsageLaunch('agent_create', 'fixture-creation-one', emit, engine)+ }+ expect(emit.mock.calls.map(([signal]) => signal.engine)).toEqual(['claude', 'codex', 'opencode', 'other', 'other', 'other', 'other', 'other'])+ // A status poll is no new launch: it says no engine.+ emit.mockClear(); productUsageLaunch('agent_create_status', 'fixture-creation-one', emit, 'claude')+ expect(emit).not.toHaveBeenCalled()+})++it('hands a created launch\'s starting agent on for its start, or says its start had already failed', () => {+ const emit = vi.fn(), id = 'fixture-creation-one'+ const done = (agent: unknown) => productUsageLaunch('agent_create_status', id, emit)(undefined, 'created', agent, undefined)+ done({ id: 'fixture-agent', launch: { state: 'starting' }, name: 'PRIVATE_CANARY' })+ done({ id: 'fixture-agent', launch: { state: 'failed', error: 'ENGINE_DID_NOT_START', detail: 'PRIVATE_CANARY' } })+ done({ id: 'fixture-agent', launch: { state: 'failed', error: 'PRIVATE_CANARY' } })+ done({ id: 'fixture-agent', launch: { state: 'ready' } })+ done({ id: 'x'.repeat(257), launch: { state: 'starting' } })+ done(true)+ expect(emit.mock.calls.flat()).toEqual([+ { id, phase: 'created', agent: 'fixture-agent' },+ { id, phase: 'created', late: true, code: 'engine_did_not_start' },+ { id, phase: 'created', late: true, code: 'unlisted' },+ { id, phase: 'created' }, { id, phase: 'created' }, { id, phase: 'created' },+ ])+ expect(JSON.stringify(emit.mock.calls)).not.toContain('PRIVATE_CANARY')+})++it('keeps every refusal core/agents can answer named: in a fixed kind, or in the code list', () => {+ // A code missing from both reads as `unlisted` and says nothing again (production counters, 2026-10-16).+ const root = fileURLToPath(new URL('../core/agents/', import.meta.url))+ const codes = new Set<string>()+ for (const name of readdirSync(root)) {+ if (!name.endsWith('.ts') || name.endsWith('.spec.ts')) continue+ for (const match of readFileSync(join(root, name), 'utf8').matchAll(/error: '([A-Z][A-Z0-9_]*)'/g)) codes.add(match[1])+ }+ expect(codes.size).toBeGreaterThan(40)+ const unnamed = [...codes].filter(code => failureKind(code) === 'other' && launchErrorCode(code) === 'unlisted')+ expect(unnamed, 'add each to LAUNCH_ERROR_CODES (lib/productUsageContract.ts and its backend copy)').toEqual([])+ // The codes the new-pane watcher sets after a create replied, which no `error: '…'` literal names.+ for (const code of ['ENGINE_DID_NOT_START', 'ENGINE_NOT_INSTALLED', 'START_TIMEOUT']) expect(launchErrorCode(code)).toBe(code.toLowerCase())+})+it('observes Store, search and model operations without their arguments and rejects explicit false outcomes', () => {const emit = vi.fn()@@ -114,6 +200,9 @@ it.each([['GRID_CREDENTIAL_REQUIRED', 'credentials_missing'], ['AGENT_BUSY', 'busy'],['RESUME_PREPARATION_FAILED', 'preparation_failed'], ['RESUME_FAILED', 'launch_failed'],['INVALID_PERMISSION_MODE', 'invalid'], ['PRIVATE_ERROR_WITH_PATH', 'other'], ['__proto__', 'other'],+ // Fell to `other` until 2026-10-16's counters showed them.+ ['ENGINE_DID_NOT_START', 'launch_failed'], ['ENGINE_NOT_INSTALLED', 'launch_failed'], ['START_TIMEOUT', 'launch_failed'],+ ['DELETE_IN_PROGRESS', 'busy'], ['MISSING_AGENT_ID', 'invalid'],])('reduces resume condition %s to an approved counter without retaining it', (error, reason) => {const emit = vi.fn(), done = productUsageRequest('agent_resume', emit, () => 0, 'app')done(error, 'failed', false); done(error, 'failed', false)diff --git a/cli/src/lib/productUsageSignals.ts b/cli/src/lib/productUsageSignals.tsindex 7cac2668c..c34d59494 100644--- a/cli/src/lib/productUsageSignals.ts+++ b/cli/src/lib/productUsageSignals.ts@@ -1,5 +1,6 @@import { HEALTH_MEASURES, type HealthSource, type ResumeReason } from './productHealthContract.js'-import { PRODUCT_USAGE_FLOWS, PRODUCT_USAGE_USER_OPENED_ACTIONS, type ProductUsageMetric } from './productUsageContract.js'+import { LAUNCH_ERROR_CODES, PRODUCT_USAGE_FLOWS, PRODUCT_USAGE_LAUNCH_ENGINES, PRODUCT_USAGE_USER_OPENED_ACTIONS,+ type LaunchErrorCode, type ProductUsageLaunchEngine, type ProductUsageMetric } from './productUsageContract.js'const actions = { agent_create: 'create', agent_resume: 'resume', agent_restart: 'restart',agent_retarget: 'model_change', agent_recent: 'history',@@ -28,34 +29,75 @@ const resumeReasons = new Map<string, ResumeReason>([['AGENT_CHANGED', 'changed'], ['RESUME_UNCONFIRMED', 'unconfirmed'],['RESUME_PREPARATION_FAILED', 'preparation_failed'], ['RESUME_FAILED', 'launch_failed'],['INVALID_PERMISSION_MODE', 'invalid'], ['INVALID_CREATION_ID', 'invalid'],+ // Codes a resume reply carries that fell to `other` (production counters, 2026-10-16): the engine of a resumed+ // harness that did not start (lib/restoreAgents.ts), a resume while the harness is being deleted (backendSocket.ts)+ // and a request that named no harness.+ ['ENGINE_DID_NOT_START', 'launch_failed'], ['ENGINE_NOT_INSTALLED', 'launch_failed'], ['START_TIMEOUT', 'launch_failed'],+ ['DELETE_IN_PROGRESS', 'busy'], ['MISSING_AGENT_ID', 'invalid'],])type Failure = 'setup' | 'auth' | 'unavailable' | 'invalid' | 'other'-function failureKind(error: unknown): Failure {+/** The fixed kind of a refusal; exported for the guard that keeps every code of core/agents named somewhere. */+export function failureKind(error: unknown): Failure {return typeof error !== 'string' ? 'other' : setup.has(error) ? 'setup' : auth.has(error) ? 'auth': unavailable.has(error) ? 'unavailable' : invalid.has(error) ? 'invalid' : 'other'}+const listedCodes = new Set<string>(LAUNCH_ERROR_CODES.filter(code => code !== 'unlisted' && code !== 'none'))+/** Which listed code an `other` refusal had (`LAUNCH_ERROR_CODES`): the daemon's own name lower-cased, `unlisted`+ * for any other string and `none` for no code at all. Only a name from the fixed list leaves here. */+export function launchErrorCode(error: unknown): LaunchErrorCode {+ if (typeof error !== 'string') return 'none'+ const code = error.length <= 64 ? error.toLowerCase() : ''+ return listedCodes.has(code) ? code as LaunchErrorCode : 'unlisted'+}+/** The engine a launch asked for, as one of the fixed names. */+export function launchEngine(engine: unknown): ProductUsageLaunchEngine {+ return (PRODUCT_USAGE_LAUNCH_ENGINES as readonly unknown[]).includes(engine) ? engine as ProductUsageLaunchEngine : 'other'+}export interface ProductUsageLaunchSignal {/** Local RAM only, discarded on stop/choice change; never part of a report or persisted queue. */id: stringphase: 'start' | 'pending' | 'created' | 'failed' | 'cancelled' | 'unconfirmed' | 'work_requested'origin?: 'interactive' | 'tool'failure?: Failure+ /** The listed code of an `other` failure, or of a created launch's late one (`late`). */+ code?: LaunchErrorCodewait?: 'install' | 'model' | 'native' | 'other'+ /** The engine a new launch asked for (`start`), as a fixed name: an installation's first launch counts it. */+ engine?: ProductUsageLaunchEngine+ /** The agent a created launch made, still starting: local RAM only, like `id`, so that the gateway can tell its+ * start failing later (core/agents/newPane.ts) from the agent's other frames. */+ agent?: string+ /** A created launch whose start had already failed when the reply that said so was read (a status poll). */+ late?: true}-/** Observe an actual new-harness receipt through subsequent status polls. Polling adds no attempts. */-export function productUsageLaunch(type: string, id: unknown, emit: (signal: ProductUsageLaunchSignal) => void) {+/** A created launch, as its reply's agent frame shows it: still starting (watched by its agent), already+ * failed (`late`), or ready. The frame is read here and nothing of it but those leaves. */+function createdSignal(agent: unknown): Omit<ProductUsageLaunchSignal, 'id'> {+ const frame = agent && typeof agent === 'object' ? agent as { id?: unknown; launch?: { state?: unknown; error?: unknown } } : null+ const launch = frame?.launch && typeof frame.launch === 'object' ? frame.launch : null+ if (launch?.state === 'failed') return { phase: 'created', late: true, code: launchErrorCode(launch.error) }+ const id = frame?.id+ return { phase: 'created', ...(typeof id === 'string' && id.length > 0 && id.length <= 256 && launch?.state !== 'ready' ? { agent: id } : {}) }+}++/** Observe an actual new-harness receipt through subsequent status polls. Polling adds no attempts.+ * [engine] is the request's `engine`; the reply's [agent] is its agent frame, or whether it had one. */+export function productUsageLaunch(type: string, id: unknown, emit: (signal: ProductUsageLaunchSignal) => void, engine?: unknown) {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 unmeasuredconst send = (signal: Omit<ProductUsageLaunchSignal, 'id'>) => {if (known) { try { emit({ id: id as string, ...signal }) } catch { /* Optional measurement. */ } }}- if (type === 'agent_create') send({ phase: 'start' })- return (error: unknown, state: unknown, hasAgent: boolean, held: unknown) => {- if (error != null || state === 'failed') send({ phase: 'failed', failure: failureKind(error) })- else if (state === 'created' || hasAgent) send({ phase: 'created' })+ if (type === 'agent_create') send({ phase: 'start', engine: launchEngine(engine) })+ return (error: unknown, state: unknown, agent: unknown, held: unknown) => {+ if (error != null || state === 'failed') {+ const failure = failureKind(error)+ send({ phase: 'failed', failure, ...(failure === 'other' ? { code: launchErrorCode(error) } : {}) })+ }+ else if (state === 'created' || agent) send(createdSignal(agent))else if (state === 'pending') send({ phase: 'pending', wait: held === 'install' ? 'install' : held === 'models' ? 'model' : held === 'native' ? 'native' : 'other' })else if (state === 'cancelled') send({ phase: 'cancelled' })else if (state === 'unconfirmed' || state === 'unavailable' || state === 'missing') send({ phase: 'unconfirmed' })@@ -106,7 +148,11 @@ export function productUsageRequest(type: string, emit: (metric: ProductUsageMetcount('unknown'); detail(error === 'AGENT_CHANGED' ? 'cancelled' : 'unknown')} else if (error != null || state === 'failed' || ok === false) {count('failed'); detail('failed')- count(`error_${failureKind(error)}`)+ const kind = failureKind(error)+ count(`error_${kind}`)+ // Which code an `other` refusal of a create or a resume had: 22 creates and 9 resumes were `other` on+ // 2026-10-16 (production counters), with nothing to say why. A fixed name from the list, or unlisted.+ if (kind === 'other' && (action === 'create' || action === 'resume')) count(`error_code_${launchErrorCode(error)}`)detail(`error_${error === 'TIMEOUT' ? 'timeout' : typeof error === 'string' && ['AGENT_NOT_FOUND', 'SESSION_NOT_FOUND', 'NOT_FOUND'].includes(error) ? 'not_found' : typeof error === 'string' && ['DELETE_IN_PROGRESS', 'WORKTREE_BUSY', 'BUSY'].includes(error) ? 'conflict' : failureKind(error)}`)} else if (state === 'pending' || state === 'preparing' || state === 'starting') { count('pending'); detail('pending') }else if (state === 'unconfirmed' || state === 'unavailable' || state === 'cancelled') { count('unknown'); detail(state === 'cancelled' ? 'cancelled' : 'unknown') }diff --git a/desktop/lib/bootstrap/agent_prefetch.dart b/desktop/lib/bootstrap/agent_prefetch.dartindex ddc699ac0..964437c59 100644--- a/desktop/lib/bootstrap/agent_prefetch.dart+++ b/desktop/lib/bootstrap/agent_prefetch.dart@@ -95,6 +95,10 @@ class AgentPrefetch {/// `harness_wait_download`). Null writes none (tests).final String? Function() _markerDir;+ /// Told when each engine's download starts (`ok` null) and how it settled, for the setup counts+ /// (ProductMeasurement.setupDownload): the engine's fixed name only, never a path, log or exit code.+ void Function(String engine, {bool? ok, Duration? took})? onDownload;+/// Runs OpenCode once after its download ([_warmOpenCode]). Off under test unless asked for.final bool _warm;@@ -198,6 +202,7 @@ class AgentPrefetch {// A fresh Ubuntu has no curl until setup's apt step installs it (`environment_provisioner.dart`).if (!await _until(_curl)) {_log('OpenCode was not downloaded during setup: curl never arrived');+ _notStarted(const ['opencode']);return;}// A create's wait counts from the download itself, not from the wait for curl before it.@@ -250,6 +255,7 @@ class AgentPrefetch {_log('Codex and Claude Code were not downloaded during setup: Harness\'s Node never arrived',);+ _notStarted(const ['codex', 'claude']);return;}// A create's wait counts from the download itself, not from the wait for Node before it.@@ -281,6 +287,18 @@ class AgentPrefetch {) async {final started = _now();final markers = <File>[];+ var settled = false;+ void settle(bool Function(String engine) ok) {+ if (settled) return;+ settled = true;+ for (final engine in engines) {+ _tell(engine, ok: ok(engine), took: _now().difference(started));+ }+ }++ for (final engine in engines) {+ _tell(engine);+ }try {final process = await _start(_shell, ['-c',@@ -327,6 +345,7 @@ class AgentPrefetch {final seconds = _now().difference(started).inMilliseconds / 1000;// Judged by the binary, as the CLI judges an install: an exit code alone says nothing about// which half of a pipeline failed.+ settle((engine) => code == 0 && _installed(engine));_log(code == 0 && inPlace()? '$what downloaded during setup in ${seconds.toStringAsFixed(1)}s'@@ -335,6 +354,7 @@ class AgentPrefetch {'${tail.join(' | ')}',);} catch (error) {+ settle((_) => false);_log('$what download during setup did not start: $error');} finally {for (final marker in markers) {@@ -371,6 +391,23 @@ class AgentPrefetch {return found;}+ /// A download that could not run because what it needs (curl, Harness's Node) never arrived:+ /// started and failed, so the counts show it rather than a computer that never downloaded.+ void _notStarted(List<String> engines) {+ for (final engine in engines) {+ _tell(engine);+ _tell(engine, ok: false, took: Duration.zero);+ }+ }++ void _tell(String engine, {bool? ok, Duration? took}) {+ try {+ onDownload?.call(engine, ok: ok, took: took);+ } catch (_) {+ // Optional measurement never touches a download.+ }+ }+/// curl on the PATH the app runs downloads with.static bool _hasCurl() => (Platform.environment['PATH'] ?? '/usr/bin:/bin').split(':')diff --git a/desktop/lib/measurement/product_measurement.dart b/desktop/lib/measurement/product_measurement.dartindex 8c21d7f8e..7d2362097 100644--- a/desktop/lib/measurement/product_measurement.dart+++ b/desktop/lib/measurement/product_measurement.dart@@ -115,6 +115,8 @@ class ProductMeasurement extends ChangeNotifier {final _pending = <String, Map<String, dynamic>>{};final _setup = <ProductFlow, void Function(ProductOutcome)>{};final _setupFacts = <ProductFlow, String>{};+ // Steps whose tool was missing at a check during the span now open; counted once per span.+ final _setupMissing = <ProductFlow>{};bool get sharing =>_account != null &&@@ -165,6 +167,7 @@ class ProductMeasurement extends ChangeNotifier {choiceLoaded = true;_clear('setup');_setup.clear();+ _setupMissing.clear();if (enabled) _observeSetupFacts();notifyListeners();}@@ -201,6 +204,7 @@ class ProductMeasurement extends ChangeNotifier {if (surface != 'desktop') signedOutSharing = false;_clear('setup');_setup.clear();+ _setupMissing.clear();}_account = scope;_enabled = null;@@ -250,6 +254,7 @@ class ProductMeasurement extends ChangeNotifier {signedOutSharing = false;_clear('setup');_setup.clear();+ _setupMissing.clear();}notifyListeners();}@@ -432,14 +437,23 @@ class ProductMeasurement extends ChangeNotifier {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)) {+ // `missing`: a check found the step's tool not installed yet, so setup goes on to install it.+ // The step stays open until the install ends; only a setup that ends failed fails it.+ if (const [+ 'pending',+ 'running',+ 'needsTerminal',+ 'missing',+ ].contains(entry.value)) {_setup.putIfAbsent(entry.key, () => begin(entry.key));+ if (entry.value == 'missing') _countSetupMissing(entry.key);} else if (const ['ready','notApplicable','failed','unavailable',].contains(entry.value)) {+ _setupMissing.remove(entry.key);_setup.remove(entry.key)?.call(@@ -451,6 +465,47 @@ class ProductMeasurement extends ChangeNotifier {}}+ /// How many new computers needed a tool installed: a signed-out setup count only, because a+ /// signed-in report goes through the local CLI, whose copy of the contract may be older.+ void _countSetupMissing(ProductFlow flow) {+ if (sharing || !_setupAllowed || surface != 'desktop' || _disposed) return;+ if (!_setupMissing.add(flow)) return;+ _count(+ 'setup',+ _now().toUtc().toIso8601String().substring(0, 10),+ 'setup_${surface}_${flow.wire}_missing',+ );+ }++ /// An agent download beside setup (AgentPrefetch): started when [ok] is null, then ok or failed+ /// with how long it took. Anonymous setup counts only, so the setup preference governs them+ /// whether or not the person has signed in meanwhile; a fixed engine name, nothing else.+ void setupDownload(String engine, {bool? ok, Duration? took}) {+ if (!_setupAllowed ||+ surface != 'desktop' ||+ _disposed ||+ !const ['opencode', 'codex', 'claude'].contains(engine)) {+ return;+ }+ final day = _now().toUtc().toIso8601String().substring(0, 10);+ final prefix = 'setup_desktop_agent_download_${engine}_';+ if (ok == null) {+ _count('setup', day, '${prefix}started');+ return;+ }+ _count('setup', day, '$prefix${ok ? 'ok' : 'failed'}');+ final minutes = (took ?? Duration.zero).inSeconds / 60;+ _count(+ 'setup',+ day,+ '$prefix${minutes < 1+ ? 'under_1m'+ : minutes < 5+ ? '1m_to_5m'+ : 'over_5m'}',+ );+ }+void _count(String channel, String day, String metric) {final today = _now().toUtc();final date = DateTime.parse(day);@@ -611,6 +666,7 @@ class ProductMeasurement extends ChangeNotifier {_days.clear();_pending.clear();_setup.clear();+ _setupMissing.clear();_active.clear();_expires.clear();_expire.clear();diff --git a/desktop/lib/measurement/product_runtime_health.dart b/desktop/lib/measurement/product_runtime_health.dartindex 3ced73f40..4ddc69251 100644--- a/desktop/lib/measurement/product_runtime_health.dart+++ b/desktop/lib/measurement/product_runtime_health.dart@@ -3,7 +3,9 @@ import 'dart:convert';import 'dart:io';import 'package:cryptography/dart.dart' show DartSha256;+import 'package:flutter/foundation.dart' show visibleForTesting;import 'package:flutter/scheduler.dart';+import 'package:flutter/widgets.dart' show AppLifecycleListener;import '../core/app_version.dart';import '../core/harness_file_store.dart';@@ -22,13 +24,17 @@ class ProductRuntimeHealth {this.readState,this.writeState,this.readVersion,- }) {+ AppLifecycleState? Function()? lifecycle,+ }) : _lifecycle =+ lifecycle ?? (() => SchedulerBinding.instance.lifecycleState) {measurement.addListener(_choiceChanged);}final ProductMeasurement measurement;final Future<Map<String, dynamic>> Function()? readState;final Future<void> Function(Map<String, dynamic>)? writeState;final Future<String> Function()? readVersion;+ final AppLifecycleState? Function() _lifecycle;+ AppLifecycleListener? _lifecycleListener;String? _scope;String? _accountId;int _epoch = 0, _revision = -1, _frame = 0;@@ -36,7 +42,8 @@ class ProductRuntimeHealth {_active = false,_timingsInstalled = false,_ready = false,- _readyCounted = false;+ _readyCounted = false,+ _skipCatchUp = false;bool newInstallation = false;Timer? _sample;Map<String, dynamic> _state = {};@@ -131,6 +138,9 @@ class ProductRuntimeHealth {if (_ready) ready();SchedulerBinding.instance.addTimingsCallback(_frames);_timingsInstalled = true;+ _lifecycleListener ??= AppLifecycleListener(+ onStateChange: lifecycleChanged,+ );_sample = Timer.periodic(const Duration(minutes: 1),(_) => sampleResources(),@@ -209,10 +219,40 @@ class ProductRuntimeHealth {}}+ @visibleForTesting+ void framesForTest(List<FrameTiming> timings) => _frames(timings);++ /// Hidden, minimised or occluded: the first frame reported after it is the+ /// OS throttling's catch-up (or one drawn while hidden), not the app's.+ /// Flutter draws nothing while hidden, so no batch arrives to say so.+ @visibleForTesting+ void lifecycleChanged(AppLifecycleState state) {+ if (_hidden(state)) _skipCatchUp = true;+ }++ static bool _hidden(AppLifecycleState? state) =>+ state == AppLifecycleState.hidden ||+ state == AppLifecycleState.paused ||+ state == AppLifecycleState.detached;+void _frames(List<FrameTiming> timings) {if (!_active || _state.isEmpty || !measurement.sharing) return;+ // A hidden, minimised or occluded window is throttled by the OS (App Nap, the compositor), so its+ // frames time the OS, not the app; the first frame back is that throttling's catch-up. Frames of a+ // visible window without focus (inactive) still count: a person can see them.+ if (_hidden(_lifecycle())) {+ _skipCatchUp = true;+ return;+ }for (final frame in timings) {- if (_frame++ % 60 != 0) continue;+ // Not counted towards the one-in-60 either: the next frame takes its place.+ if (_skipCatchUp) {+ _skipCatchUp = false;+ continue;+ }+ // Every 60th frame, never the first: `_frame++` sampled index 0, each launch's workspace+ // restore, which app_start already times. Oct 16 had 155 app starts, one long sample each.+ if (++_frame % 60 != 0) continue;final ms = frame.totalSpan.inMilliseconds;measurement.health(ms < 16@@ -259,6 +299,8 @@ class ProductRuntimeHealth {SchedulerBinding.instance.removeTimingsCallback(_frames);_timingsInstalled = false;}+ _lifecycleListener?.dispose();+ _lifecycleListener = null;_workspace = null;_state = {};_readyCounted = false;diff --git a/desktop/lib/state/app_state.dart b/desktop/lib/state/app_state.dartindex 9eb466fd3..d17181dc4 100644--- a/desktop/lib/state/app_state.dart+++ b/desktop/lib/state/app_state.dart@@ -3743,6 +3743,7 @@ class AppNotifier extends ChangeNotifier {sendDesktopSetupMeasurement(this.config.apiBaseUrl, report),);productConnections = ProductConnections(this.productMeasurement);+ this.agentPrefetch?.onDownload ??= this.productMeasurement.setupDownload;this.productMeasurement.addListener(_measurementChoiceChanged);if (!kUnderTest && this.productMeasurement.healthEnabled) {productRuntimeHealth = ProductRuntimeHealth(this.productMeasurement);@@ -5301,12 +5302,18 @@ class AppNotifier extends ChangeNotifier {EnvironmentSetupPhase.failed => 'failed',_ => 'running',},+ // A check marks a tool that is not installed yet as failed, and setup then installs it. That+ // is `missing`, not a failure: on Oct 16 every new computer counted its Harness CLI and tmux+ // as failed steps while 0 setups failed. Only a setup that ends failed fails its step.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,+ }: entry.value == EnvironmentStepStatus.failed &&+ value.phase != EnvironmentSetupPhase.failed+ ? 'missing'+ : entry.value.name,});}diff --git a/desktop/test/agent_prefetch_test.dart b/desktop/test/agent_prefetch_test.dartindex fbf671f3c..194cb1cde 100644--- a/desktop/test/agent_prefetch_test.dart+++ b/desktop/test/agent_prefetch_test.dart@@ -207,6 +207,49 @@ void main() {]);});+ test('tells each engine\'s download start and how it settled, by name only', () async {+ final opencode = _Install();+ final npm = _Install();+ final inPlace = <String>{};+ final told = <String>[];+ final prefetch = prefetchWith(installs: [opencode, npm], inPlace: inPlace)+ ..onDownload = (engine, {ok, took}) => told.add(+ ok == null ? '$engine started' : '$engine ${ok ? 'ok' : 'failed'}',+ );+ prefetch.start();+ await pumpEventQueue();+ inPlace.add('opencode');+ opencode.finish(0);+ // npm exits 0 but put only Codex in place: Claude Code did not download.+ inPlace.add('codex');+ npm.finish(0);+ await prefetch.everything;+ expect(told, [+ 'opencode started',+ 'codex started',+ 'claude started',+ 'opencode ok',+ 'codex ok',+ 'claude failed',+ ]);+ });++ test('a download whose Node never arrives counts as started and failed', () async {+ final told = <String>[];+ final prefetch = AgentPrefetch(+ start: (_, _) async => _Install()..finish(0),+ skip: () => false,+ installed: (_) => false,+ managedNode: () => null,+ nodePoll: const Duration(milliseconds: 1),+ nodeWait: Duration.zero,+ )..onDownload = (engine, {ok, took}) =>+ told.add(ok == null ? '$engine started' : '$engine $ok');+ prefetch.start();+ await prefetch.everything;+ expect(told, containsAll(['codex started', 'codex false', 'claude started', 'claude false']));+ });+test('waits for Harness\'s Node before npm, and gives up on it after a while',() async {diff --git a/desktop/test/product_health_test.dart b/desktop/test/product_health_test.dartindex c20de4381..a5d70371d 100644--- a/desktop/test/product_health_test.dart+++ b/desktop/test/product_health_test.dart@@ -1,4 +1,5 @@import 'dart:convert';+import 'dart:ui' show AppLifecycleState, FrameTiming;import 'package:flutter_test/flutter_test.dart';import 'package:harness/measurement/product_measurement.dart';@@ -243,6 +244,50 @@ void main() {},);+ testWidgets(+ 'frames sample every 60th visible frame, never the first or a hidden one',+ (tester) async {+ var lifecycle = AppLifecycleState.resumed;+ final runtime = ProductRuntimeHealth(+ usage,+ readState: () async => {},+ writeState: (_) async {},+ readVersion: () async => '1.2.73',+ lifecycle: () => lifecycle,+ );+ runtime.account('PRIVATE_ACCOUNT');+ await usage.flush();+ await tester.pump();+ FrameTiming frame(int ms) => FrameTiming(+ vsyncStart: 0,+ buildStart: 0,+ buildFinish: 0,+ rasterStart: 0,+ rasterFinish: ms * 1000,+ rasterFinishWallTime: ms * 1000,+ );+ // A launch's first frame is its heavy workspace restore: not a sample+ // (frames 1–59 are not sampled; the 60th is).+ runtime.framesForTest([frame(900), for (var i = 1; i < 59; i++) frame(5)]);+ // Minimised, then shown: the first frame back is the catch-up, and would+ // otherwise be the 60th, the sampled one.+ runtime.lifecycleChanged(AppLifecycleState.hidden);+ runtime.lifecycleChanged(AppLifecycleState.inactive);+ runtime.framesForTest([frame(700), frame(5)]);+ // A batch reported while hidden is the OS's throttling: none of it counts.+ lifecycle = AppLifecycleState.hidden;+ runtime.framesForTest([for (var i = 0; i < 120; i++) frame(400)]);+ // Visible but without focus (inactive) still counts: a person sees it.+ lifecycle = AppLifecycleState.inactive;+ runtime.framesForTest([frame(700), for (var i = 0; i < 60; i++) frame(5)]);+ await usage.flush();+ expect(totals()['health_desktop_frame_under_16ms'], 2);+ expect(totals()['health_desktop_frame_over_250ms'], isNull);+ runtime.dispose();+ await tester.pump();+ },+ );+testWidgets('relaunch confirms only the expected public version and sharing revision',(tester) async {diff --git a/desktop/test/product_measurement_test.dart b/desktop/test/product_measurement_test.dartindex 0a14b312d..bc41dc64c 100644--- a/desktop/test/product_measurement_test.dart+++ b/desktop/test/product_measurement_test.dart@@ -376,6 +376,55 @@ void main() {expect(setup.length, 1);},);+ test('a missing tool keeps its setup step open and is marked once', () async {+ usage.setupFacts({ProductFlow.setupHarness: 'pending'});+ usage.setupFacts({ProductFlow.setupHarness: 'missing'});+ usage.setupFacts({ProductFlow.setupHarness: 'missing'});+ usage.setupFacts({ProductFlow.setupHarness: 'running'});+ usage.setupFacts({ProductFlow.setupHarness: 'ready'});+ await usage.flush();+ expect(setup.single['counters'], {+ 'setup_desktop_setup_harness_started': 1,+ 'setup_desktop_setup_harness_missing': 1,+ 'setup_desktop_setup_harness_ok': 1,+ 'setup_desktop_setup_harness_under_1s': 1,+ });+ });+ test('a signed-in setup step counts no missing mark', () async {+ await account();+ usage.setupFacts({ProductFlow.setupTmux: 'missing'});+ usage.setupFacts({ProductFlow.setupTmux: 'ready'});+ await usage.flush();+ expect(reports.last['counters'], {+ 'ui_desktop_setup_tmux_started': 1,+ 'ui_desktop_setup_tmux_ok': 1,+ 'ui_desktop_setup_tmux_under_1s': 1,+ });+ expect(setup, isEmpty);+ });+ test('agent downloads are anonymous setup counts by engine name', () async {+ usage.setupDownload('codex');+ usage.setupDownload('codex', ok: true, took: const Duration(seconds: 95));+ usage.setupDownload('claude');+ usage.setupDownload('claude', ok: false, took: const Duration(minutes: 7));+ usage.setupDownload('/Users/PRIVATE/.local/bin/x', ok: true);+ await account();+ usage.setupDownload('opencode');+ await usage.flush();+ final counters = {+ for (final report in setup) ...(report['counters'] as Map),+ };+ expect(counters, {+ 'setup_desktop_agent_download_codex_started': 1,+ 'setup_desktop_agent_download_codex_ok': 1,+ 'setup_desktop_agent_download_codex_1m_to_5m': 1,+ 'setup_desktop_agent_download_claude_started': 1,+ 'setup_desktop_agent_download_claude_failed': 1,+ 'setup_desktop_agent_download_claude_over_5m': 1,+ 'setup_desktop_agent_download_opencode_started': 1,+ });+ expect(jsonEncode(setup), isNot(contains('PRIVATE')));+ });test('flow observations are bounded and unknown operations never upload content',() async {diff --git a/desktop/test/setup_step_measurement_test.dart b/desktop/test/setup_step_measurement_test.dartnew file mode 100644index 000000000..6c2a6e4e9--- /dev/null+++ b/desktop/test/setup_step_measurement_test.dart@@ -0,0 +1,166 @@+import 'dart:convert';++import 'package:flutter_test/flutter_test.dart';+import 'package:harness/auth/auth_session.dart';+import 'package:harness/auth/cli_login.dart';+import 'package:harness/bootstrap/environment_provisioner.dart';+import 'package:harness/core/config.dart';+import 'package:harness/measurement/product_measurement.dart';++import 'support/guest_app.dart';++class _SignedOut extends CliLogin {+ @override+ Future<CliAuthStatus> checkStatus() async =>+ const CliAuthStatus(loggedIn: false);+}++/// Replays what the real provisioner reports on a new Mac, one list of progress values per call.+class _Replay extends EnvironmentProvisioner {+ _Replay(this.calls) : super(isMacOS: true);+ final List<List<EnvironmentReadiness>> calls;+ var call = 0;++ @override+ Future<EnvironmentReadiness> ensureReady({+ required void Function(EnvironmentReadiness value) onProgress,+ EnvironmentReadiness? resumeFrom,+ bool install = true,+ EnvironmentSetupMode? mode,+ }) async {+ final values = calls[call < calls.length ? call : calls.length - 1];+ call++;+ for (final value in values) {+ onProgress(value);+ }+ return values.last;+ }+}++EnvironmentReadiness _state(+ EnvironmentSetupPhase phase, {+ EnvironmentStepStatus harness = EnvironmentStepStatus.ready,+ EnvironmentStepStatus tmux = EnvironmentStepStatus.ready,+ EnvironmentStepStatus clipboard = EnvironmentStepStatus.ready,+ EnvironmentFailure? failure,+}) => EnvironmentReadiness(+ steps: {+ EnvironmentStep.harness: harness,+ EnvironmentStep.tmux: tmux,+ EnvironmentStep.clipboard: clipboard,+ },+ phase: phase,+ mode: EnvironmentSetupMode.automatic,+ failure: failure,+);++void main() {+ TestWidgetsFlutterBinding.ensureInitialized();+ const failed = EnvironmentStepStatus.failed;+ const running = EnvironmentStepStatus.running;+ const pending = EnvironmentStepStatus.pending;++ // The first check finds both tools missing (the probe reports them as failed), the review is+ // skipped because everything installs in-app, and the install re-checks before installing.+ final check = [+ _state(+ EnvironmentSetupPhase.preflight,+ harness: pending,+ tmux: pending,+ clipboard: pending,+ ),+ _state(EnvironmentSetupPhase.preflight, harness: failed, tmux: failed),+ _state(EnvironmentSetupPhase.review, harness: failed, tmux: failed),+ ];+ final installStart = [+ _state(EnvironmentSetupPhase.installing, harness: running, tmux: running),+ _state(EnvironmentSetupPhase.installing, harness: failed, tmux: failed),+ _state(EnvironmentSetupPhase.installing, harness: failed, tmux: running),+ _state(EnvironmentSetupPhase.installing, harness: failed),+ _state(EnvironmentSetupPhase.installing, harness: running),+ ];++ Future<Map<String, dynamic>> run(+ List<List<EnvironmentReadiness>> calls,+ ) async {+ final sent = <Map<String, dynamic>>[];+ final usage = ProductMeasurement(+ surface: 'desktop',+ automatic: false,+ sendSetup: (report) async {+ sent.add(jsonDecode(jsonEncode(report)) as Map<String, dynamic>);+ return {'accepted': true};+ },+ );+ final app = GuestTestApp(+ config: AppConfig.dev,+ authSession: AuthSession(),+ configStore: null,+ cliLogin: _SignedOut(),+ environmentProvisioner: _Replay(calls),+ productMeasurement: usage,+ );+ await app.bootstrap();+ await usage.flush();+ app.dispose(); // Disposes the measurement it was given too.+ return {+ for (final report in sent) ...report['counters'] as Map<String, dynamic>,+ };+ }++ test(+ 'a new computer whose missing tools install counts no failed step',+ () async {+ final counters = await run([+ check,+ [+ ...installStart,+ _state(EnvironmentSetupPhase.installing),+ _state(EnvironmentSetupPhase.verifying),+ _state(EnvironmentSetupPhase.ready),+ ],+ ]);+ for (final step in ['harness', 'tmux']) {+ expect(+ counters['setup_desktop_setup_${step}_started'],+ 1,+ reason: step,+ );+ expect(counters['setup_desktop_setup_${step}_ok'], 1, reason: step);+ expect(+ counters['setup_desktop_setup_${step}_missing'],+ 1,+ reason: step,+ );+ expect(counters, isNot(contains('setup_desktop_setup_${step}_failed')));+ }+ expect(counters['setup_desktop_setup_clipboard_ok'], 1);+ expect(+ counters,+ isNot(contains('setup_desktop_setup_clipboard_missing')),+ );+ expect(counters['setup_desktop_setup_ok'], 1);+ },+ );++ test('a setup that ends failed still fails the step that failed', () async {+ final counters = await run([+ check,+ [+ ...installStart,+ _state(+ EnvironmentSetupPhase.failed,+ harness: failed,+ failure: const EnvironmentFailure(+ title: 'Setup could not finish',+ detail: 'synthetic',+ ),+ ),+ ],+ ]);+ expect(counters['setup_desktop_setup_harness_failed'], 1);+ expect(counters['setup_desktop_setup_harness_missing'], 1);+ expect(counters['setup_desktop_setup_tmux_ok'], 1);+ expect(counters['setup_desktop_setup_failed'], 1);+ });+}diff --git a/desktop/test/support/guest_app.dart b/desktop/test/support/guest_app.dartindex 6b92a890f..5572bd3dc 100644--- a/desktop/test/support/guest_app.dart+++ b/desktop/test/support/guest_app.dart@@ -11,6 +11,7 @@ class GuestTestApp extends AppNotifier {super.agentPrefetch,super.localManualFixture,super.paneLayoutStore,+ super.productMeasurement,});var daemonGates = 0;diff --git a/docs/product-measurement.md b/docs/product-measurement.mdindex d3717ae83..10e400408 100644--- a/docs/product-measurement.md+++ b/docs/product-measurement.md@@ -8,16 +8,16 @@ automatically proven improvement. Changes still need review, tests and a deliber| Question | Signal | Interpretation || --- | --- | --- |-| Does first measured use lead to work? | First-launch installation cohorts; work and first text response within 24 hours | Same participating installation, not signup conversion, same-task success or unique people. Existing users enter when updated; mature only after the full follow-up day ends. |-| Where does a launch stall or fail? | Pending install/model/native waits; observed launch created/failed/cancelled/unconfirmed; fixed failure categories and duration buckets | Polls are not attempts. Missing outcomes, daemon restarts and the 15-minute observation bound reduce coverage. Inspect unknowns alongside failures. |-| Which actions break? | Create, resume, restart, model-change, 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. Requests are also counted by source: `app`, `tool`, `automatic` (fixed polls, whichever app makes them), `unknown` and `phone` — the phone marks the requests the daemon measures (`usageSurface: 'phone'`, inside the E2EE payload); older phones still count as `app`. |+| Does first measured use lead to work? | First-launch installation cohorts; work and first text response within 24 hours; the first launch's engine (`first_launch_engine_opencode`, `_claude`, `_codex`, `_other`) and, for Claude Code and Codex, whether that engine had a credential here (`first_launch_<engine>_signed_in`, `_signed_out`, `_unknown`) | 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. The credential is one presence check per installation, in the gateway (`cli/src/lib/engineAccount.ts`: a file stat'ed or parsed for a token, a Keychain item looked up without its secret); it reads the gateway's own environment and starts no login shell, so a key only a shell profile exports reads as signed out on a daemon launchd or systemd started. `unknown` is a Codex that keeps its tokens in the OS keyring, or a check that failed. An answer lost to a stop or a choice change leaves the engine count without one. |+| Where does a launch stall or fail? | Pending install/model/native waits; observed launch created/failed/cancelled/unconfirmed; fixed failure categories and duration buckets; an `other` failure's code (`launch_failed_code_<code>`); a created launch whose engine then did not start (`launch_late_failed`, by code in `launch_late_failed_code_<code>`) | Polls are not attempts. Missing outcomes, daemon restarts and the 15-minute observation bound reduce coverage. Inspect unknowns alongside failures. Codes are the daemon's own fixed names, lower-cased (`LAUNCH_ERROR_CODES`); `unlisted` is a code not in the list and `none` a failure that named none, so the codes add up to `launch_failed_other`. A late failure (the new-pane watcher's ENGINE_DID_NOT_START, ENGINE_NOT_INSTALLED or START_TIMEOUT, set after the reply said created) is one of the `launch_created`, never a `launch_failed`; the gateway reads it from the agent's own announcement for 15 minutes after the launch was created, and earlier CLI releases counted these only as created (compare releases separately). |+| 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; the code of an `other` create or resume refusal (`create_error_code_<code>`, `resume_error_code_<code>`) | Request acceptance is not task success. Pending/unknown requests are separate from completed replies. Requests are also counted by source: `app`, `tool`, `automatic` (fixed polls, whichever app makes them), `unknown` and `phone` — the phone marks the requests the daemon measures (`usageSurface: 'phone'`, inside the E2EE payload); older phones still count as `app`. Each code family adds up to its `create_error_other` or `resume_error_other`. || 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/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 from clients that offer feedback; current Desktop Settings no longer exposes feedback controls | 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. An open is a surface going from no attached window to one, not each connection (the desktop holds one per machine and redials). Relay events are not distinct people; the populations must not be added together. || Which features get tried and used again? | First measured installations and daily first/repeat feature reach | Locally deduplicated installation-days, not unique accounts. Reads the apps make on their own (history, history paging, Store list, model list; `PRODUCT_USAGE_AUTOMATIC_ACTIONS`) count reliability only. The Store and model lists get reach only from the request an app marks `userAction` when a person opens them (`<action>_user_*`, `PRODUCT_USAGE_USER_OPENED_ACTIONS`); history has none. |-| 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. |+| 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; a setup step whose tool was missing at a check (`setup_desktop_setup_<step>_missing`); the agents a new computer downloads beside setup (`setup_desktop_agent_download_<opencode\|codex\|claude>_started`, `_ok`, `_failed`, with under 1 min, 1–5 min and over 5 min) | 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. A setup step stays open from the first check until its tool is in place, so a tool that was missing and then installed is one ok step and one `_missing` mark; only a setup that ends failed fails its step. Earlier Desktop releases counted every check that found a tool missing as a failed step (on 2026-10-16 the Harness step read 72 failed of 221 while 0 setups failed): compare releases separately. `_missing` is any tool a check found absent or out of date (a Harness CLI older than this Desktop needs, on a computer already in use, counts too), not only new computers. A step left waiting (the review, a Linux Terminal handoff, manual mode, someone who walks away) now ends `unknown` at the 15-minute observation bound instead of `failed`, so expect `setup_*_unknown` to rise, mostly on Linux. `_missing` and the download counts are anonymous setup counts only. A download whose prerequisite (curl, Harness's Node) never arrived counts as started and failed; `ok` means the agent's program is in place, judged per engine. || Where does the phone's onboarding stall? | After sign-in: waiting for the first computer, opening its session, the first message, the notification prompt. A sign-in that went through, by button, counted again under the account's sharing. Waits past a minute split into 1–5 min, 5–15 min, 15 min–1 h and over 1 h for the computer and the first message. Once per step per sign-in: `resumed` (reopened in a run that did not sign in), "Not you? Sign out", the address sent from the share sheet, a joining computer that wants its password or is offline | Stage totals per day, not a linked funnel. Subtract `resumed` from starts for fresh starts; an unmatched start is a closed app or a step still waiting. A resumed step's duration starts at the reopening. Signed-in sign-in counts are successes only; failures and cancels before an account remain the signed-out counts', but a success is marked `retried` (a failed or cancelled try came first in that app run) or `switched` (another button was tried first). Phone reports carry release and iOS/Android, so every phone count also splits by those two margins (above 20 collector days); debug builds are not kept. A chosen sign-out sends what is queued first (up to 2 s), so "Not you? Sign out" reaches the totals. || How fast does the phone get back to work? | A launch that came back signed in, to its first computer answering (`app_start`); a dial the person asked for ("Try again", `connect_user`) apart from the app's own (`connect_auto`), beside the unchanged `remote_connect`; a stopped harness resumed from the phone, to its first live turn (`resume_recovery`) | A launch that signs in is the onboarding's and is not counted; one that leaves the screen before a computer answers is `unknown`, one whose computers never answer stays started. An asked-for dial fails at 12 s, as Desktop Connect does. A phone dial is `failed` only when the phone knows why (locked or offline), `unknown` otherwise; the reasons (`connect_error_*`) are Desktop health counters. || Are the phone's side pages used? | Find and Computers opens, by a sideways swipe on the terminal or by a button (Computers' row in Settings, its link on a long wait at home) | Which page and which way, nothing more. Find's key and screen-reader actions are not counted; a swipe that lets Find go back opened nothing. |@@ -84,9 +84,12 @@ measurement change is not evidence that fewer people encountered linking troublecounters do not count affected people. Retry suppression adds no identifiers or stored history.The startup bucket measures launch to the first consented observation of a connected workspace,including preference/sign-in delay. One in 60 rendered frames supplies a coarse duration bucket;-it cannot reliably detect an idle freeze. Error hooks pass only framework/async categories.-Desktop RSS and gateway RSS/CPU sample once per minute; they describe those processes, not the-whole machine or agents. Sampling adds no core timer, process enumeration, or subprocess.+it cannot reliably detect an idle freeze. Frames of a hidden, minimised or occluded window, and the+first frame after it is shown again, are not sampled (the OS throttles them), nor is each launch's+first frame, which `app_start` already times; earlier releases sampled both. Error hooks pass only framework/async categories.+Desktop RSS samples once per minute and gateway RSS/CPU once per report tick (45 to 75 seconds, a+minute on average); they describe those processes, not the whole machine or agents. Sampling adds+no core timer, process enumeration, or subprocess.Desktop keeps its setup-sharing preference and pending opt-out booleans, plus the last sharing-enabled run's version, clean-exit/update flags, choicerevision and a local-only account-scope hash. One serialized asynchronous write plus one latest@@ -107,13 +110,33 @@ Unmeasured RPCs return a shared no-op immediately. The `HARNESSD_SERVICES=none`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+and bounds in-memory turn/launch observations at 1,000 each (and the created launches' agents it+watches for a late failure, for 15 minutes each). Reports contain at most 64 counters and stay below+8 KiB. One sync runs at a time, with five-second network deadlines. The gateway reads the sharing+choice as it starts, so collection starts with it, and sends its first report a random 10 to 60+seconds later; each later tick comes a random 45 to 75 seconds after the last. Every daemon of a+release updated at the same second, and a report at start then one each minute made the fleet report+together: backend write conflicts and `USAGE_BUSY` refusals (41 and 48 on 2026-10-16). A report the+backend refuses as busy or failing (429, 5xx, a timeout) waits for a full-jitter backoff whose ceiling+doubles from two minutes to half an hour with each such refusal in a row, and never less than the+answer's Retry-After (held to the same half hour); any other answer resets it. Ticks still read the+choice meanwhile. Unknown or failed preference checks stop collection. Slow or failed reporting canlose counts and cannot become a product dependency. A failed disk write also disables collection.+Stopping the gateway writes the collector's final, clean state synchronously before it returns+(a temporary file and a rename, at most the 256 KiB queue), and its process stops the gateway before+it closes the core's link and exits. A write still on its way cannot put an older state over it.+Earlier releases wrote the clean exit asynchronously and their process exited first, so `harness+stop`, updates, sign-in and sign-out restarts, service installs and OS logouts all counted as+`health_cli_unclean_restart` (69, then 170 on 2026-10-16, production counters). Compare that counter+by release across this change; now it counts a process that ended without stopping (a crash, a kill,+power loss, a stop that outlasted its five-second grace).+`health_cli_report_rejected` counts unsuccessful delivery attempts, including retries; it is not-a count of lost reports. New `health_cli_report_failure_*` counters split those attempts into fixed+a count of lost reports. A report that names a counter this backend does not know yet (a client a+release ahead of it) is kept without that name, never stored or echoed, and counted once as+`health_<cli|desktop|phone>_report_unknown_metric`; before, the whole report was refused and retried.+A report with no known counter left is still refused. New `health_cli_report_failure_*` counters split those attempts into fixedinvalid, too-large, authentication, rate-limit, timeout, unreachable, write-conflict, transaction,server and other categories. A transaction failure does not by itself prove a timeout. No raw errormessage, database detail, URL or unknown error code is collected. These diagnostics share the same@@ -174,6 +197,9 @@ image build can be distinguished from the version actually serving requests.Resume diagnostics add fixed conditions by request source: runtime unavailable, saved state missing,project missing, harness missing, credentials missing, busy, changed, unconfirmed, preparation failed,launch failed, invalid and other. These come only from known error codes, never error text or paths.+An engine of a resumed harness that did not start (ENGINE_DID_NOT_START, ENGINE_NOT_INSTALLED,+START_TIMEOUT) is a launch failure, a resume while the harness is being deleted is busy, and a request+that named no harness is invalid; earlier releases counted these as `other`.From CLI 0.4.3, an unconfirmed runtime counts as unknown and a concurrently changed harness ascancelled (legacy aggregate: unknown), rather than failed. Compare releases separately across thisdefinition change; a lower failure rate alone is not proof the product improved.@@ -219,7 +245,9 @@ Decision: keep | revise | revert | inconclusiveNext review date:```-The `review` output proposes investigations, not code changes or automatic deployments. Feedback+The `review` output proposes investigations, not code changes or automatic deployments. Its unknown+launch refusals and its engines that did not start after a create each name their five most frequent+codes; a large `unlisted` share means a code is missing from `LAUNCH_ERROR_CODES`. Feedbackis one source of evidence; a missing response does not identify why a person stopped using Harness.## Rollout and privacy controls@@ -228,7 +256,7 @@ Deploy backend schema and the singleton worker first, including unique indexes aUse synthetic data to verify duplicate receipts, transaction rollback/retry, off/on revision fencingand expiry. Then release CLI, desktop and phone together. An older backend refuses a whole reportcarrying a counter it does not know (a phone page opening, a `request_phone_*` count, a phone-`sharing: "default"` setup report), so the backend always goes first. Check that the switch saves and that reports+`sharing: "default"` setup report, a launch code or a first launch's engine), so the backend always goes first. Check that the switch saves and that reportsstop when it is off. Old clients stop contributing individual daily histories when the backend changes;the historical reporting command will no longer be a current-usage source.