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
import { cleanUsageContext, type ProductUsageContext } from '../lib/productHealthContract.js'
import { cleanHealthState, createProductHealth, type HealthState } from './productHealth.js'
import { reportFailure } from './reportFailure.js'
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 { 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_000
const MAX_QUEUE_BYTES = 256 * 1024
// A report stays below the server's 8 KiB body bound even with the complete vocabulary.
const MAX_REPORT_METRICS = 64
const metricSet = new Set<string>(PRODUCT_USAGE_METRICS)
const 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]
// Spec 2026-11-02-poll-cost Part 4.1: every tick read the choice and reported (prod 2026-11-02: 330 settings GETs and 284
// report POSTs a minute). The ticks stay, for the counts kept on this computer (the resource samples need them 45 s apart),
// but the choice is read at start, when it is made on this computer (`choiceChanged`), after a failed read or request, and then hourly: a report
// carries its revision, so one sent after an opt-out elsewhere is refused (CHOICE_CHANGED) and the choice read at the next
// tick. Reports go at most every 5 minutes, from the queue kept on disk.
const SETTINGS_EVERY_MS = 3_600_000
const REPORT_EVERY_MS = 300_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`
const REACHES: readonly Reach[] = [...PRODUCT_USAGE_ACTIONS, ...PRODUCT_USAGE_USER_OPENED_ACTIONS.map(action => `${action}_user` as const)]
const requestActions = new Map<string, Reach>([
...PRODUCT_USAGE_ACTIONS.filter(action => !PRODUCT_USAGE_AUTOMATIC_ACTIONS.includes(action)).map(action => [`${action}_requests`, action] as const),
...PRODUCT_USAGE_USER_OPENED_ACTIONS.map(action => [`${action}_user_requests`, `${action}_user`] as const),
])
const isTuiMetric = (metric: string): boolean => metric.startsWith('ui_tui_') || metric.startsWith('health_tui_')
const key = (now: number) => new Date(now).toISOString().slice(0, 10)
const week = (now: number) => { const d = new Date(now); return key(now - ((d.getUTCDay() + 6) % 7) * DAY) }
type Counters = Partial<Record<ProductUsageMetric, number>>
interface State {
dayContexts: Record<string, ProductUsageContext>
health: HealthState
healthDay: string | null
revision: number
activeDay: string | null
workDay: string | null
workWeek: string | null
workMonth: string | null
measurementDay: string | null
featureDays: Partial<Record<Reach, string>>
featuresUsed: Reach[]
workedBefore: boolean
respondedBefore: boolean
launchedBefore: boolean
firstLaunchAt: number | null
launchWorked: boolean
launchResponded: boolean
workDays: string[]
days: Record<string, Counters>
pending: ProductUsageReport | null
}
const fresh = (revision: number): State => ({ dayContexts: {}, health: cleanHealthState(null, Date.now()), healthDay: null, revision, activeDay: null, workDay: null, workWeek: null,
workMonth: null, measurementDay: null, featureDays: {}, featuresUsed: [],
workedBefore: false, respondedBefore: false, launchedBefore: false, firstLaunchAt: null,
launchWorked: false, launchResponded: false, workDays: [], days: {}, pending: null })
export interface ProductUsageDeps {
file: string
context?: ProductUsageContext
sample?: () => { rss: number; cpuPercent?: number }
/** `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?(): number
uuid?(): 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 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, random = deps.random ?? Math.random
const context = cleanUsageContext(deps.context)
let state = fresh(-1), enabled = false, stopped = false, active = false
let syncing: Promise<void> | null = null, persistTimer: ReturnType<typeof setTimeout> | undefined
let writing: Promise<boolean> | null = null, writeAgain = false
// 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
// When the ticks next read the choice and next report (SETTINGS_EVERY_MS, REPORT_EVERY_MS).
let settingsAt = 0, reportAt = 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.
let choiceKnown = false, tuiHeld: ProductUsageMetric[] = [], tuiRefusedDay: string | null = null
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>; agent: boolean }>()
/** 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.
const saved = JSON.parse(readFileSync(deps.file, 'utf8')) as State
if (Number.isSafeInteger(saved.revision) && saved.revision >= 0) {
state = fresh(saved.revision)
state.health = cleanHealthState(saved.health, now())
state.healthDay = typeof saved.healthDay === 'string' && validDay(saved.healthDay) ? saved.healthDay : null
for (const field of ['activeDay', 'workDay', 'workWeek', 'measurementDay'] as const) {
if (typeof saved[field] === 'string' && validDay(saved[field]!)) state[field] = saved[field]
}
if (typeof saved.workMonth === 'string' && /^\d{4}-\d{2}$/.test(saved.workMonth)) state.workMonth = saved.workMonth
for (const action of REACHES) {
if (validDay(saved.featureDays?.[action] ?? '')) state.featureDays[action] = saved.featureDays![action]
if (saved.featuresUsed?.includes(action)) state.featuresUsed.push(action)
}
state.workedBefore = saved.workedBefore === true
state.respondedBefore = saved.respondedBefore === true
state.launchedBefore = saved.launchedBefore === true
state.firstLaunchAt = Number.isSafeInteger(saved.firstLaunchAt) && saved.firstLaunchAt! <= now()
&& validDay(key(saved.firstLaunchAt!)) ? saved.firstLaunchAt : null
state.launchWorked = saved.launchWorked === true
state.launchResponded = saved.launchResponded === true
state.workDays = Array.isArray(saved.workDays) ? [...new Set(saved.workDays.filter(d => typeof d === 'string' && validDay(d)))].slice(-35) : []
for (const [day, counters] of Object.entries(saved.days ?? {})) if (validDay(day)) {
state.days[day] = clean(counters)
const c = cleanUsageContext(saved.dayContexts?.[day])
if (c) state.dayContexts[day] = c
else if (context) state.dayContexts[day] = { ...context, release: 'unknown', platform: 'other' }
}
const pending = saved.pending
if (pending && pending.schemaVersion === 1 && pending.revision === state.revision && validDay(pending.day)
&& typeof pending.id === 'string' && /^[a-f0-9-]{36}$/.test(pending.id)) {
const restored = { schemaVersion: 1 as const, revision: state.revision, id: pending.id, day: pending.day, counters: clean(pending.counters), ...(cleanUsageContext(pending.context) ? { context: cleanUsageContext(pending.context) } : {}) }
if (Buffer.byteLength(JSON.stringify(restored)) <= 8192) state.pending = restored
}
}
} catch { /* Missing or unreadable telemetry must not affect a session. */ }
const health = createProductHealth(add, now, state.health)
function validDay(day: string): boolean {
const stamp = Date.parse(day + 'T00:00:00.000Z'), today = Math.floor(now() / DAY) * DAY
return /^\d{4}-\d{2}-\d{2}$/.test(day) && Number.isFinite(stamp) && key(stamp) === day
&& stamp <= today && stamp > today - PRODUCT_USAGE_DAYS * DAY
}
function clean(input: Counters): Counters {
const result: Counters = {}
for (const metric of PRODUCT_USAGE_METRICS) {
const value = input?.[metric]
if (typeof value === 'number' && Number.isSafeInteger(value) && value > 0 && value <= PRODUCT_USAGE_MAX_COUNT) result[metric] = value
}
return result
}
function snapshot(): string {
state.health = health.snapshot()
clearTimeout(persistTimer); persistTimer = undefined
for (const field of ['activeDay', 'workDay', 'workWeek', 'measurementDay'] as const) if (state[field] && !validDay(state[field]!)) state[field] = null
for (const day of Object.keys(state.days)) if (!validDay(day)) delete state.days[day]
for (const day of Object.keys(state.dayContexts)) if (!state.days[day]) delete state.dayContexts[day]
for (const action of REACHES) if (!validDay(state.featureDays[action] ?? '')) delete state.featureDays[action]
state.workDays = state.workDays.filter(validDay)
if (state.firstLaunchAt !== null && !validDay(key(state.firstLaunchAt))) state.firstLaunchAt = null
if (state.pending && !validDay(state.pending.day)) state.pending = null
// Size each day once, keeping the most recent ones. Repeatedly serializing a full
// offline backlog to remove its oldest day would stall the gateway on a reconnect.
let bytes = Buffer.byteLength(JSON.stringify({ ...state, days: {} })) + 1024
const kept: State['days'] = {}
let pruned = false
for (const day of Object.keys(state.days).sort().reverse()) {
const size = Buffer.byteLength(JSON.stringify(state.days[day])) + 16
if (bytes + size > MAX_QUEUE_BYTES) { pruned = true; continue }
kept[day] = state.days[day]; bytes += size
}
state.days = kept
if (pruned) (state.days[key(now())] ??= {}).measurement_queue_pruned = 1
return JSON.stringify(state)
}
/** 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.
return writing ??= (async () => {
try {
do {
writeAgain = false
const value = snapshot()
if (deps.write) await deps.write(deps.file, value)
else {
await mkdir(dirname(deps.file), { recursive: true, mode: 0o700 })
await writeFile(deps.file + '.tmp', value, { mode: 0o600 })
// Stopped meanwhile: the final state is on disk, and this older snapshot must not go over it.
if (final !== null) break
await rename(deps.file + '.tmp', deps.file)
}
} 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 {
if (!persistTimer) { persistTimer = setTimeout(() => { void persist() }, 1000); persistTimer.unref() }
}
function add(metric: ProductUsageMetric, day = key(now())): void {
if (state.measurementDay !== key(now())) {
state.measurementDay = key(now())
;(state.days[state.measurementDay] ??= {}).measurement_v2_installation_days = 1
}
const counters = state.days[day] ??= {}
if (context) {
const prior = state.dayContexts[day]
state.dayContexts[day] = !prior ? context : { ...context,
release: prior.release === context.release ? context.release : 'unknown',
platform: prior.platform === context.platform ? context.platform : 'other',
channel: prior.channel === 'production' && context.channel === 'production' ? 'production' : 'development' }
if ((counters[metric] ?? 0) >= PRODUCT_USAGE_MAX_COUNT) counters.health_cli_queue_capped = 1
}
counters[metric] = Math.min(PRODUCT_USAGE_MAX_COUNT, (counters[metric] ?? 0) + 1)
dirty()
}
function markActive(): void {
if (!enabled || stopped) return
if (state.activeDay !== key(now())) { state.activeDay = key(now()); add('active_installation_days') }
}
function launchValue(response: boolean): void {
if (state.firstLaunchAt === null || now() < state.firstLaunchAt || now() - state.firstLaunchAt > DAY) return
const field = response ? 'launchResponded' : 'launchWorked'
if (!state[field]) {
state[field] = true
add(response ? 'first_launch_response_24h_installations' : 'first_launch_work_24h_installations', key(state.firstLaunchAt))
}
}
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); forget(); health.reset()
enabled = false
if (!await persist()) return
}
enabled = value.enabled && !stopped
}
/** 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))
/** [read]: read the choice first; [post]: send a report now. The gateway's first read of the choice does not
* report, so collection starts at once and the report waits for the first tick; a tick reads the choice when it is
* due (SETTINGS_EVERY_MS) and reports when one is due (REPORT_EVERY_MS) unless backing off. */
async function syncOnce(read: boolean, post: boolean): Promise<void> {
let posting = false
try {
if (read) {
const response = await deps.request('GET', '/api/product-usage/settings')
if (stopped) return
const body = response.body.data as ProductUsageChoice | undefined
if (response.status !== 200 || typeof body?.enabled !== 'boolean'
|| !Number.isSafeInteger(body.revision) || body.revision < 0) { enabled = false; forget(); health.clearObservations(); return }
await choice(body)
settingsAt = now() + SETTINGS_EVERY_MS
if (!choiceKnown) {
// Counted only now that sharing is known to be on; discarded when it is off.
choiceKnown = true
const held = tuiHeld
tuiHeld = []
if (enabled && !tuiRefused()) for (const metric of held) add(metric)
}
}
if (!enabled) return
if (context) {
health.start(context.release); health.checkpoint(); health.sample(deps.sample)
if (state.healthDay !== key(now())) { state.healthDay = key(now()); add('health_cli_collector_days') }
}
for (const turn of running.values()) if (!turn.response && !turn.waited && now() - turn.started >= 60_000) {
turn.waited = true; add('turns_waiting_over_1m')
}
for (const [id, launch] of launches) {
if (!launch.done && now() - launch.started >= 15 * 60_000) { launch.done = true; add('launch_unobserved') }
if (now() - launch.started >= 35 * 60_000) launches.delete(id)
}
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) return
if (!state.pending) {
const day = Object.keys(state.days).sort().find(d => validDay(d) && Object.keys(state.days[d]).length)
if (!day) return
// hn's counters travel alone: a backend from before `tui` refuses its whole report (400), and
// that refusal drops the report, so it must never carry the daemon's or the Desktop's counts.
const entries = Object.entries(state.days[day])
const own = entries.filter(([metric]) => !isTuiMetric(metric))
const counters = Object.fromEntries((own.length ? own : entries).slice(0, MAX_REPORT_METRICS)) as Counters
const reportContext = state.dayContexts[day] ?? context
state.pending = { schemaVersion: 1, revision: state.revision, id: uuid(), day, counters, ...(reportContext ? { context: reportContext } : {}) }
for (const metric of Object.keys(counters)) delete state.days[day][metric as ProductUsageMetric]
if (!Object.keys(state.days[day]).length) { delete state.days[day]; delete state.dayContexts[day] }
}
// Persist the immutable receipt before sending. A crash or ambiguous response retries that id.
if (!await persist() || stopped || !enabled) return
const report = state.pending
if (!report) return
posting = true
reportAt = now() + REPORT_EVERY_MS
const 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 } | undefined
if (answer.status === 200 && result?.accepted === true) { state.pending = null; await persist() }
else if (result?.reason === 'CHOICE_CHANGED') { enabled = false; settingsAt = 0; 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
// is not counted as one: the report goes, and hn's counts with it until the next UTC day.
state.pending = null; tuiRefusedDay = key(now()); await persist()
}
else {
add('health_cli_report_rejected')
add(`health_cli_report_failure_${reportFailure(answer)}`)
// A permanently invalid packet must not block every future report behind it.
if (answer.status === 400 || answer.status === 413) { state.pending = null; await persist() }
}
} catch {
if (posting) backOff()
if (enabled) add('health_cli_report_failed')
// Off until the choice is read again, at the next tick.
enabled = false; settingsAt = 0; forget(); health.clearObservations() /* No error text or request body in logs. */
}
}
/** Read the choice and, with [post] (the default), send a report now. */
const sync = (post = true): Promise<void> => syncing ??= syncOnce(true, post).finally(() => { syncing = null })
const tick = (): Promise<void> => syncing ??= syncOnce(now() >= settingsAt, now() >= postAt && now() >= reportAt).finally(() => { syncing = null })
/** The choice was just made on this computer: read it now, without a report. After whatever is already on its way,
* since a read in that run may have come back before the choice was made. */
const choiceChanged = async (): Promise<void> => {
while (syncing) await syncing
if (!stopped) await sync(false)
}
let timer: ReturnType<typeof setTimeout> | undefined
const schedule = (ms: number): void => {
if (stopped) return
timer = setTimeout(() => { void tick().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,
choiceChanged,
counter(metric: ProductUsageMetric): void {
if (stopped || !metricSet.has(metric)) return
if (isTuiMetric(metric)) {
if (!enabled) { if (!choiceKnown && tuiHeld.length < 64) tuiHeld.push(metric); return }
if (tuiRefused()) return
}
if (!enabled) return
add(metric)
const action = requestActions.get(metric)
if (action && state.featureDays[action] !== key(now())) {
add(`${action}_installation_days`)
add(`${action}_${state.featuresUsed.includes(action) ? 'repeat_installation_days' : 'first_installations'}`)
if (!state.featuresUsed.includes(action)) state.featuresUsed.push(action)
state.featureDays[action] = key(now())
}
},
launch(signal: ProductUsageLaunchSignal): void {
if (!enabled || stopped || !signal || typeof signal.id !== 'string') return
if (signal.phase === 'work_requested') {
if (!running.has(signal.id) && signal.id.length > 0 && signal.id.length <= 256 && (signal.origin === 'interactive' || signal.origin === 'tool')) health.intent(signal.id, signal.origin)
return
}
if (!/^[a-zA-Z0-9_-]{16,96}$/.test(signal.id)) return
if (signal.phase === 'start') {
if (launches.has(signal.id)) return
if (!state.launchedBefore) {
state.launchedBefore = true; state.firstLaunchAt = now(); add('first_launch_installations')
firstLaunch(signal.engine)
}
if (launches.size >= 1000) {
const oldest = launches.keys().next().value!
if (!launches.get(oldest)!.done) add('launch_unobserved')
launches.delete(oldest)
}
const agent = signal.agentStarted === true
launches.set(signal.id, { started: now(), done: false, waits: new Set(), agent }); add('launch_started')
if (agent) add('launch_agent_started')
return
}
const launch = launches.get(signal.id)
if (!launch || launch.done) return
if (signal.phase === 'pending') {
const wait = ['install', 'model', 'native'].includes(signal.wait ?? '') ? signal.wait! : 'other'
if (!launch.waits.has(wait)) { launch.waits.add(wait); add(`launch_wait_${wait}` as ProductUsageMetric) }
return
}
if (!['created', 'failed', 'refused', 'cancelled', 'unconfirmed'].includes(signal.phase)) return
launch.done = true
add(`launch_${signal.phase}` as ProductUsageMetric)
// Agents' and Swarms' launches, counted again: since Oct 21 there are many more of them, and they moved a rate
// people read as a person's. A person's own are the total less these.
if (launch.agent && ['created', 'failed', 'refused'].includes(signal.phase)) add(`launch_agent_${signal.phase}` as ProductUsageMetric)
if (signal.phase === 'refused') add(`launch_refused_code_${listed(signal.code)}`)
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)}`)
// Setup's 10 failures on 2026-10-21 could not say which prerequisite failed. A separate family
// keeps the existing `other` code totals comparable; the launch map still counts polls only once.
if (kind === 'setup') add(`launch_failed_setup_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
markActive(); add(surface === 'desktop' ? 'desktop_opens' : 'tui_opens')
},
observe(type: 'turn_started' | 'turn_ended' | 'text_delta' | 'error', agent: string, replay: boolean, interrupted = false): void {
if (!enabled || stopped || replay || !agent || agent.length > 256) return
if (type === 'turn_started') {
if (running.has(agent)) return
if (running.size >= 1000) { add('turn_observation_overflow'); return }
running.set(agent, { started: now(), response: false, error: false, waited: false }); markActive(); add('turns_started'); if (context) health.work(agent)
launchValue(false)
if (state.workDay !== key(now())) {
if (state.workDay && now() - Date.parse(state.workDay) >= 7 * DAY) add('reactivated_after_7d_installations')
add('working_installation_days')
add(state.workedBefore ? 'repeat_work_installation_days' : 'first_work_installations')
state.workDay = key(now()); state.workedBefore = true
// Return counters belong to the earlier working-day cohort, not today's new starts.
// Only these date flags stay here; no server-side installation/user join is needed.
for (const [lag, metric] of [[1, 'd1_returning_work_installations'], [7, 'd7_returning_work_installations'], [28, 'd28_returning_work_installations']] as const) {
const cohort = key(now() - lag * DAY)
if (state.workDays.includes(cohort)) add(metric, cohort)
}
state.workDays = [...state.workDays.filter(validDay), key(now())]
}
const currentMonth = key(now()).slice(0, 7)
if (state.workMonth !== currentMonth) {
add('monthly_working_installations')
const prior = new Date(currentMonth + '-01T00:00:00Z'); prior.setUTCMonth(prior.getUTCMonth() - 1)
if (state.workMonth === key(prior.getTime()).slice(0, 7)) add('monthly_returning_installations')
state.workMonth = currentMonth
}
const currentWeek = week(now())
if (state.workWeek !== currentWeek) {
add('weekly_working_installations')
if (state.workWeek === key(Date.parse(currentWeek) - 7 * DAY)) add('weekly_returning_installations')
state.workWeek = currentWeek
}
} else {
const turn = running.get(agent)
if (!turn) return
const elapsed = Math.max(0, now() - turn.started)
if (!turn.response && !turn.waited && elapsed >= 60_000) { turn.waited = true; add('turns_waiting_over_1m') }
if (type === 'error') {
if (!turn.error) { turn.error = true; add('turns_with_error') }
return
}
if (type === 'text_delta') {
if (!turn.response) {
turn.response = true; add('turns_with_response')
// Do not attribute a response from a turn already running when the first launch began.
if (state.firstLaunchAt !== null && turn.started >= state.firstLaunchAt) launchValue(true)
if (!state.respondedBefore) { state.respondedBefore = true; add('first_response_installations') }
add(elapsed < 10_000 ? 'response_under_10s' : elapsed < 60_000 ? 'response_10s_to_1m' : elapsed < 300_000 ? 'response_1m_to_5m' : 'response_over_5m')
}
return
}
running.delete(agent)
if (!turn.response) add('turns_ended_without_response')
add(interrupted ? 'turns_interrupted' : 'turns_ended')
add(elapsed < 10_000 ? 'duration_under_10s' : elapsed < 60_000 ? 'duration_10s_to_1m' : elapsed < 300_000 ? 'duration_1m_to_5m' : 'duration_over_5m')
}
},
/** 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> {
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() }
final = snapshot()
const written = writeFinal(final)
return writing ? writing.then(() => written) : Promise.resolve(written)
},
}
}