Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

feat: implement privacy-preserving usage analytics collection and reporting system

0xken1534626b1ca12f
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index 7bbadb838..8948d1664 100644
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -44,6 +44,8 @@ import { Watcher, type LineEvent } from './watcher/watcher.js'
import { startHookServer } from './hookServer.js'
import { BackendSocket } from './backendSocket.js'
import { lastTurnTextFromRawLines, lineToEvents, newTurnState, type LiveEvent, type TurnState } from './lib/normalize.js'
+import { AnalyticsCollector } from './lib/analytics/collector.js'
+import { runAnalyticsCommand } from './lib/analytics/command.js'
import { AskQuestionController, pollsQuestions, QuestionWatcher } from './lib/askQuestion.js'
import { CommanderMirror } from './lib/commander.js'
import {
@@ -512,6 +514,20 @@ async function runForeground(token: string): Promise<void> {
const devinReaders = new Map<string, DevinReader>()
const commandcodeNormalizers = new Map<string, CommandCodeNormalizer>()
const watcher = new Watcher()
+ /**
+ * Harness Analytics (autonomous-code docs/design/harness-analytics.md).
+ *
+ * Collection starts now; NOTHING is uploaded until the account owner has acknowledged the field
+ * list — the backend answers `consent: "unacknowledged"` until then and the snapshot simply waits.
+ * That hold is what lets the CLI be on by default while running headless, where there is no screen
+ * to show a preview on.
+ */
+ const analytics = new AnalyticsCollector({
+ token: () => readSavedToken(),
+ enginesPresent: () => [...new Set(registry.list().map((entry) => entry.engine))],
+ collectorVersion: VERSION,
+ })
+ analytics.start()
const queuedSessionEvents: Array<{
sessionId: string
events: ReturnType<CursorNormalizer['ingest']>
@@ -931,6 +947,14 @@ async function runForeground(token: string): Promise<void> {
backend.send({ ...event, dbSessionId: sessionId })
if (event.type === 'turn_started') {
turnStartedAt.set(sessionId, Date.now())
+ // Analytics: count HERE, inside the one funnel every engine's normalizer feeds and BEFORE
+ // backend.send seals the frame. The relay only ever sees ciphertext, so this is the only
+ // layer that can tell a real instruction from a duplicated control frame.
+ analytics.sessionTurnStarted(
+ sessionId,
+ registry.bySession(sessionId)?.engine ?? 'claude',
+ agentIdFor(sessionId),
+ )
console.log(`[turn] ${sid(sessionId)} started · engine=${registry.bySession(sessionId)?.engine ?? 'claude'} · "${preview(event.payload.userMessage)}"`)
input.onTurnStarted(agentIdFor(sessionId), event.payload.userMessage)
startHeartbeat(sessionId)
@@ -938,6 +962,7 @@ async function runForeground(token: string): Promise<void> {
} else if (event.type === 'turn_ended') {
const startedAt = turnStartedAt.get(sessionId)
turnStartedAt.delete(sessionId)
+ analytics.sessionTurnEnded(sessionId, event.payload.aborted === true)
// Say when a turn was KILLED. The log previously showed an interrupt as a fresh `[turn] started
// "[Request interrupted by user]"`, which read like a new prompt and hid the bug for weeks.
console.log(
@@ -992,6 +1017,7 @@ async function runForeground(token: string): Promise<void> {
syncRecapPool()
turnStates.delete(sessionId)
turnStartedAt.delete(sessionId)
+ analytics.sessionClosed(sessionId) // an open turn here died with the session; count it as failed
codexNormalizers.delete(sessionId)
cursorNormalizers.delete(sessionId)
opencodeReaders.get(sessionId)?.stop()
@@ -2247,6 +2273,12 @@ switch (cmd) {
case 'reset':
resetCommand().catch(onError)
break
+ case 'analytics':
+ // Local half of the consent contract: see exactly what would leave this computer, and stop it.
+ // Runs without the daemon — it reads the persisted snapshot, so it works on a computer that has
+ // never uploaded anything.
+ console.log(runAnalyticsCommand(process.argv[3]))
+ break
case 'status':
status().catch(onError)
break
diff --git a/cli/src/config/env.ts b/cli/src/config/env.ts
index d9b265483..1a126cb59 100644
--- a/cli/src/config/env.ts
+++ b/cli/src/config/env.ts
@@ -168,6 +168,15 @@ const envSchema = z.object({
DEVIN_CONFIG_PATH: z.string().default(join(homedir(), '.config', 'devin', 'config.json')),
// Where the tmux-session registry + connect token are persisted.
ADAPTER_DATA_DIR: z.string().default(adapterDataDir),
+ // ---- Harness Analytics (see autonomous-code docs/design/harness-analytics.md) ----
+ // Collection is ON by default, but this computer uploads NOTHING until the account owner has
+ // acknowledged the field list — the backend answers `consent: "unacknowledged"` until then. This
+ // flag exists to switch the collector off entirely (tests, air-gapped installs).
+ ANALYTICS_ENABLED: z.string().default('true').transform((v) => v !== 'false'),
+ // Defaults to BACKEND_WS_URL over https — the ingest endpoint is the same host, and deliberately
+ // NOT the adapter socket: analytics must not share a pipe with the E2EE content channel.
+ ANALYTICS_BACKEND_URL: z.string().optional(),
+ ANALYTICS_FLUSH_INTERVAL_MS: z.string().default('60000').transform(Number),
// Set to 'true' to skip auto-installing lifecycle hooks for every supported engine.
DISABLE_HOOK_INSTALL: z.string().default('false').transform((v) => v === 'true'),
// How often (ms) the reaper checks tmux panes and drops dead sessions.
diff --git a/cli/src/engines/types.ts b/cli/src/engines/types.ts
index d64551123..90679d274 100644
--- a/cli/src/engines/types.ts
+++ b/cli/src/engines/types.ts
@@ -1,7 +1,19 @@
import type { LiveEvent } from '../lib/normalize.js'
import type { RegisteredSession } from '../lib/registry.js'
-export type AgentEngine = 'claude' | 'codex' | 'cursor' | 'opencode' | 'pi' | 'hermes' | 'commandcode' | 'devin' | 'muse' | 'amp' | 'kilo' | 'grok'
+/**
+ * Every engine this CLI integrates, as a value.
+ *
+ * `AgentEngine` alone cannot be iterated, and analytics has to report exactly what it instruments —
+ * so the list lives here once and both forms are derived from it. A new engine added to the union
+ * without being added here fails to compile.
+ */
+export const ENGINES = [
+ 'claude', 'codex', 'cursor', 'opencode', 'pi', 'hermes',
+ 'commandcode', 'devin', 'muse', 'amp', 'kilo', 'grok',
+] as const
+
+export type AgentEngine = (typeof ENGINES)[number]
export interface EngineNormalizer {
ingest(line: string): LiveEvent[]
diff --git a/cli/src/lib/analytics/collector.spec.ts b/cli/src/lib/analytics/collector.spec.ts
new file mode 100644
index 000000000..5c34dfcb9
--- /dev/null
+++ b/cli/src/lib/analytics/collector.spec.ts
@@ -0,0 +1,281 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { mkdtempSync, rmSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+
+const dataDir = mkdtempSync(join(tmpdir(), 'harness-analytics-'))
+process.env.ADAPTER_DATA_DIR = dataDir
+process.env.ANALYTICS_BACKEND_URL = 'https://backend.test'
+process.env.ANALYTICS_ENABLED = 'true'
+
+const { AnalyticsCollector, analyticsBaseUrl, extractEpoch } = await import('./collector.js')
+const { disableLocally, enableLocally, renderPreview, UPLOADED_FIELDS } = await import('./command.js')
+const { ENGINES } = await import('../../engines/types.js')
+
+const fetchMock = vi.fn()
+vi.stubGlobal('fetch', fetchMock)
+
+function respond(body: unknown, status = 200): void {
+ fetchMock.mockResolvedValueOnce({ ok: status >= 200 && status < 300, status, json: async () => body })
+}
+
+function sent(): Record<string, unknown> {
+ const [, init] = fetchMock.mock.calls[fetchMock.mock.calls.length - 1] as [string, { body: string }]
+ return JSON.parse(init.body)
+}
+
+let clock = Date.parse('2026-08-11T10:00:00Z')
+
+function collector(token: string | null = 'a'.repeat(64)): InstanceType<typeof AnalyticsCollector> {
+ const c = new AnalyticsCollector({
+ token: () => token,
+ enginesPresent: () => ['claude', 'kilo'],
+ collectorVersion: '1.2.3',
+ now: () => clock,
+ })
+ c.start()
+ return c
+}
+
+beforeEach(() => {
+ fetchMock.mockReset()
+ clock = Date.parse('2026-08-11T10:00:00Z')
+ // Consent is persisted on purpose — a restart must not re-upload what the owner turned off — so
+ // each test starts from a clean data dir.
+ rmSync(join(dataDir, 'analytics'), { recursive: true, force: true })
+})
+
+afterEach(() => {
+ rmSync(join(dataDir, 'analytics'), { recursive: true, force: true })
+})
+
+describe('the funnel hook', () => {
+ it('counts a completed turn from the per-session lifecycle events', async () => {
+ const c = collector()
+ c.sessionTurnStarted('s1', 'claude', 'agent-1')
+ clock += 20 * 60_000
+ c.sessionTurnEnded('s1', false)
+
+ respond({ data: { consent: 'on', epoch: 0, serverTime: '', accepted: 1, quarantined: 0 } })
+ await c.flush()
+
+ const day = (sent().days as { buckets: Record<string, number>[]; machineDay: Record<string, number> }[])[0]
+ expect(day.buckets[0].turnsCompleted).toBe(1)
+ expect(day.buckets[0].instructions).toBe(1)
+ expect(day.machineDay.wallClockActiveMs).toBe(20 * 60_000)
+ c.stop()
+ })
+
+ it('records an interrupted turn as cancelled, not completed', async () => {
+ const c = collector()
+ c.sessionTurnStarted('s1', 'codex', 'agent-1')
+ clock += 60_000
+ c.sessionTurnEnded('s1', true)
+
+ respond({ data: { consent: 'on', epoch: 0, serverTime: '', accepted: 1, quarantined: 0 } })
+ await c.flush()
+
+ const day = (sent().days as { buckets: Record<string, number>[] }[])[0]
+ expect(day.buckets[0].turnsCancelled).toBe(1)
+ expect(day.buckets[0].turnsCompleted).toBe(0)
+ c.stop()
+ })
+
+ it('closes a leaked turn when the same session starts another one', async () => {
+ const c = collector()
+ c.sessionTurnStarted('s1', 'claude', 'agent-1')
+ clock += 60_000
+ c.sessionTurnStarted('s1', 'claude', 'agent-1') // no turn_ended ever arrived
+ clock += 60_000
+ c.sessionTurnEnded('s1', false)
+
+ respond({ data: { consent: 'on', epoch: 0, serverTime: '', accepted: 1, quarantined: 0 } })
+ await c.flush()
+
+ const day = (sent().days as { buckets: Record<string, number>[] }[])[0]
+ expect(day.buckets[0].turnsFailed).toBe(1)
+ expect(day.buckets[0].turnsCompleted).toBe(1)
+ c.stop()
+ })
+
+ it('counts one active agent when two sessions belong to it', async () => {
+ const c = collector()
+ c.sessionTurnStarted('s1', 'claude', 'agent-1')
+ c.sessionTurnEnded('s1', false)
+ c.sessionTurnStarted('s2', 'codex', 'agent-1')
+ c.sessionTurnEnded('s2', false)
+
+ respond({ data: { consent: 'on', epoch: 0, serverTime: '', accepted: 1, quarantined: 0 } })
+ await c.flush()
+
+ const day = (sent().days as { machineDay: { activeAgents: number } }[])[0]
+ expect(day.machineDay.activeAgents).toBe(1)
+ c.stop()
+ })
+})
+
+describe('payload', () => {
+ it('claims coverage of every engine this CLI integrates', async () => {
+ const c = collector()
+ c.sessionTurnStarted('s1', 'claude', 'agent-1')
+ c.sessionTurnEnded('s1', false)
+
+ respond({ data: { consent: 'on', epoch: 0, serverTime: '', accepted: 1, quarantined: 0 } })
+ await c.flush()
+
+ const body = sent() as { collector: { engineCoverage: string[]; enginesPresent: string[]; version: string } }
+ expect(body.collector.engineCoverage).toEqual([...ENGINES])
+ expect(body.collector.enginesPresent).toEqual(['claude', 'kilo'])
+ expect(body.collector.version).toBe('1.2.3')
+ c.stop()
+ })
+
+ it('reports mode remote and never puts an agent id on the wire', async () => {
+ const c = collector()
+ c.sessionTurnStarted('s1', 'claude', 'a-very-identifying-agent-name')
+ c.sessionTurnEnded('s1', false)
+
+ respond({ data: { consent: 'on', epoch: 0, serverTime: '', accepted: 1, quarantined: 0 } })
+ await c.flush()
+
+ const raw = JSON.stringify(sent())
+ expect(raw).not.toContain('a-very-identifying-agent-name')
+ expect(raw).not.toContain('s1')
+ const day = (sent().days as { buckets: { mode: string }[] }[])[0]
+ expect(day.buckets[0].mode).toBe('remote')
+ c.stop()
+ })
+
+ it('derives the ingest endpoint from the backend socket host, not the socket itself', () => {
+ expect(analyticsBaseUrl()).toBe('https://backend.test')
+ })
+})
+
+describe('consent', () => {
+ it('uploads from the first flush, with no opt-in step', async () => {
+ const c = collector()
+ c.sessionTurnStarted('s1', 'claude', 'agent-1')
+ c.sessionTurnEnded('s1', false)
+
+ respond({ data: { consent: 'on', epoch: 0, serverTime: '', accepted: 1, quarantined: 0 } })
+ await c.flush()
+
+ expect((sent().days as unknown[]).length).toBe(1)
+ c.stop()
+ })
+
+ it('stops collecting when the owner turns it off', async () => {
+ const c = collector()
+ c.sessionTurnStarted('s1', 'claude', 'agent-1')
+ c.sessionTurnEnded('s1', false)
+
+ respond({ data: { consent: 'off', epoch: 0, serverTime: '', accepted: 0, quarantined: 0 } })
+ await c.flush()
+
+ c.sessionTurnStarted('s2', 'claude', 'agent-1')
+ c.sessionTurnEnded('s2', false)
+ fetchMock.mockReset()
+ await c.flush()
+
+ expect(fetchMock).not.toHaveBeenCalled()
+ c.stop()
+ })
+
+ it('obeys `harness analytics off` on this computer whatever the account says', async () => {
+ const c = collector()
+ disableLocally()
+
+ c.sessionTurnStarted('s1', 'claude', 'agent-1')
+ c.sessionTurnEnded('s1', false)
+ await c.flush()
+ expect(fetchMock).not.toHaveBeenCalled()
+
+ enableLocally()
+ c.sessionTurnStarted('s2', 'claude', 'agent-1')
+ c.sessionTurnEnded('s2', false)
+ respond({ data: { consent: 'on', epoch: 0, serverTime: '', accepted: 1, quarantined: 0 } })
+ await c.flush()
+ expect(fetchMock).toHaveBeenCalledTimes(1)
+ c.stop()
+ })
+
+ it('drops its records when the account history was deleted', async () => {
+ const c = collector()
+ c.sessionTurnStarted('s1', 'claude', 'agent-1')
+ c.sessionTurnEnded('s1', false)
+
+ respond({ error: { message: 'Analytics history was reset; current epoch is 9' } }, 409)
+ await c.flush()
+
+ fetchMock.mockReset()
+ await c.flush()
+ expect(fetchMock).not.toHaveBeenCalled()
+ c.stop()
+ })
+
+ it('keeps the snapshot when the network is down', async () => {
+ const c = collector()
+ c.sessionTurnStarted('s1', 'claude', 'agent-1')
+ c.sessionTurnEnded('s1', false)
+
+ fetchMock.mockRejectedValueOnce(new Error('ENOTFOUND'))
+ await expect(c.flush()).resolves.toBeUndefined()
+
+ respond({ data: { consent: 'on', epoch: 0, serverTime: '', accepted: 1, quarantined: 0 } })
+ await c.flush()
+ const day = (sent().days as { buckets: Record<string, number>[] }[])[0]
+ expect(day.buckets[0].turnsCompleted).toBe(1)
+ c.stop()
+ })
+
+ it('does not upload before this computer has joined', async () => {
+ const c = collector(null)
+ c.sessionTurnStarted('s1', 'claude', 'agent-1')
+ c.sessionTurnEnded('s1', false)
+
+ await c.flush()
+ expect(fetchMock).not.toHaveBeenCalled()
+ c.stop()
+ })
+})
+
+describe('harness analytics preview', () => {
+ it('shows every uploaded field and the never-sent list without contacting the backend', async () => {
+ const c = collector()
+ c.sessionTurnStarted('s1', 'claude', 'agent-1')
+ clock += 5 * 60_000
+ c.sessionTurnEnded('s1', false)
+ c.stop() // persists the snapshot the command reads
+
+ const text = renderPreview()
+
+ for (const field of UPLOADED_FIELDS) expect(text).toContain(field)
+ expect(text).toContain('what you typed, and what any engine replied')
+ expect(text).toContain('uploading')
+ expect(text).toContain('2026-08-11')
+ expect(fetchMock).not.toHaveBeenCalled()
+ })
+
+ it('says so plainly when nothing has been recorded', () => {
+ expect(renderPreview()).toContain('Nothing recorded yet')
+ })
+
+ it('deletes the local records when switched off', async () => {
+ const c = collector()
+ c.sessionTurnStarted('s1', 'claude', 'agent-1')
+ c.sessionTurnEnded('s1', false)
+ c.stop()
+
+ expect(renderPreview()).not.toContain('Nothing recorded yet')
+ disableLocally()
+ expect(renderPreview()).toContain('Nothing recorded yet')
+ enableLocally()
+ })
+})
+
+describe('extractEpoch', () => {
+ it('reads the epoch out of the 409 message', () => {
+ expect(extractEpoch('Analytics history was reset; current epoch is 9')).toBe(9)
+ expect(extractEpoch('nope')).toBeNull()
+ })
+})
diff --git a/cli/src/lib/analytics/collector.ts b/cli/src/lib/analytics/collector.ts
new file mode 100644
index 000000000..7a61ba660
--- /dev/null
+++ b/cli/src/lib/analytics/collector.ts
@@ -0,0 +1,317 @@
+/**
+ * Harness Analytics collector for the remote CLI.
+ *
+ * Design: `autonomous-code` docs/design/harness-analytics.md ("Source-specific collectors").
+ *
+ * This is the collector that matters most: it is the only layer that understands every engine's
+ * transcript well enough to count the same concept across all twelve, and it is the only one that
+ * can count at all — the relay sees `turn_started` and `turn_ended` as ciphertext
+ * (`ENCRYPTED_UP_TYPES` in `src/lib/e2ee/core.ts`), so a byte count there could never distinguish a
+ * real instruction from a duplicated control frame.
+ *
+ * Two behaviours are load-bearing and easy to get wrong:
+ *
+ * - **Collection starts immediately; uploading waits for acknowledgement.** Aggregates are
+ * snapshots, so holding them costs nothing and loses nothing. That is what lets the product be on
+ * by default while still being able to say, truthfully, that no byte left this computer before
+ * its owner read the field list. The CLI runs headless on servers and under `harness join`, where
+ * there is no screen to show a preview on, so the hold is the only honest mechanism available.
+ * - **The upload response is the control channel.** A daemon has no other way to learn the owner
+ * turned collection off or deleted the history.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs'
+import { dirname, join } from 'path'
+import { env } from '../../config/env.js'
+import { ENGINES as ALL_ENGINES, type AgentEngine } from '../../engines/types.js'
+import { AnalyticsReducer, type ReducerSnapshot } from './reducer.js'
+import {
+ ANALYTICS_SCHEMA_VERSION,
+ MAX_DAYS_PER_REPORT,
+ type AnalyticsReportResponse,
+ type ConsentState,
+ type Engine,
+ type Origin,
+ type TurnOutcome,
+} from './contract.js'
+
+const UPTIME_TICK_MS = 60_000
+/** A tick may credit at most this much, so a laptop that slept cannot claim the hours it was shut. */
+const UPTIME_MAX_CREDIT_MS = 90_000
+
+interface PersistedState {
+ version: 1
+ consent: ConsentState
+ epoch: number
+ reducer: ReducerSnapshot
+}
+
+/** Where the daemon keeps its analytics state, beside its other mutable data. */
+export function analyticsStateFile(): string {
+ return join(env.ADAPTER_DATA_DIR, 'analytics', 'state.json')
+}
+
+/** The CLI dials the backend over `wss://`; the ingest endpoint is the same host over `https://`. */
+export function analyticsBaseUrl(): string {
+ if (env.ANALYTICS_BACKEND_URL) return env.ANALYTICS_BACKEND_URL.replace(/\/$/, '')
+ return env.BACKEND_WS_URL.replace(/^ws/, 'http').replace(/\/$/, '')
+}
+
+export interface CollectorOptions {
+ /** Reads the machine api key. Kept as a callback because the daemon may join after start-up. */
+ token: () => string | null
+ /**
+ * Engines with a registered agent on this computer right now.
+ *
+ * `engineCoverage` alone cannot answer "is anything being missed": an engine absent from it is
+ * either uninstrumented or simply not installed. Only the difference is shown to the user, so the
+ * collector has to report what it can actually see.
+ */
+ enginesPresent: () => AgentEngine[]
+ collectorVersion: string
+ now?: () => number
+}
+
+export class AnalyticsCollector {
+ private reducer = new AnalyticsReducer()
+ // Collection is ON by default; the backend only ever tells us to stop.
+ private consent: ConsentState = 'on'
+ private epoch = 0
+ private lastTickAt: number
+ private uptimeTimer: NodeJS.Timeout | null = null
+ private flushTimer: NodeJS.Timeout | null = null
+ private started = false
+ private flushing = false
+ private dirty = false
+
+ /** The CLI instruments every engine it integrates — that is the point of putting it here. */
+ private readonly coverage: Engine[] = [...ALL_ENGINES] as Engine[]
+
+ constructor(private readonly opts: CollectorOptions) {
+ this.lastTickAt = this.now()
+ }
+
+ private now(): number {
+ return this.opts.now ? this.opts.now() : Date.now()
+ }
+
+ start(): void {
+ if (this.started || !env.ANALYTICS_ENABLED) return
+ this.started = true
+ this.load()
+ this.lastTickAt = this.now()
+
+ this.uptimeTimer = setInterval(() => this.tick(), UPTIME_TICK_MS)
+ this.uptimeTimer.unref?.()
+ this.flushTimer = setInterval(() => { void this.flush() }, env.ANALYTICS_FLUSH_INTERVAL_MS)
+ this.flushTimer.unref?.()
+ }
+
+ stop(): void {
+ this.started = false
+ if (this.uptimeTimer) clearInterval(this.uptimeTimer)
+ if (this.flushTimer) clearInterval(this.flushTimer)
+ this.uptimeTimer = null
+ this.flushTimer = null
+ this.persist()
+ }
+
+ /** Live turn id per session. The normalizers emit per-session lifecycle events, not turn ids. */
+ private readonly openTurns = new Map<string, string>()
+ private turnSeq = 0
+
+ /**
+ * A turn began on a session.
+ *
+ * Called from the single `emitSessionEvents` funnel, which every engine's normalizer feeds — so one
+ * hook covers all twelve, and a thirteenth engine is counted the day it joins that funnel.
+ *
+ * `agentId` is used ONLY to count distinct active agents for the day and never leaves this
+ * computer; the wire payload carries the integer alone.
+ */
+ sessionTurnStarted(
+ sessionId: string,
+ engine: AgentEngine,
+ agentId: string,
+ origin: Origin = 'human',
+ at = this.now(),
+ ): void {
+ if (!this.collecting()) return
+
+ // A previous turn that never terminated would otherwise leak and under-report the day.
+ const stale = this.openTurns.get(sessionId)
+ if (stale) this.reducer.turnFinished(stale, at, 'failed')
+
+ const turnId = `${sessionId}#${++this.turnSeq}`
+ this.openTurns.set(sessionId, turnId)
+ this.reducer.turnStarted(turnId, at, engine as Engine, 'remote', origin)
+ this.reducer.instruction(at, engine as Engine, 'remote', origin, agentId)
+ this.dirty = true
+ }
+
+ /** A turn terminated. `aborted` is the normalizers' word for an interrupt. */
+ sessionTurnEnded(sessionId: string, aborted: boolean, at = this.now()): void {
+ if (!this.collecting()) return
+ const turnId = this.openTurns.get(sessionId)
+ if (!turnId) return
+ this.openTurns.delete(sessionId)
+ this.reducer.turnFinished(turnId, at, aborted ? 'cancelled' : 'completed')
+ this.dirty = true
+ }
+
+ /** A session went away. Its open turn is a failure; dropping it would under-report the day. */
+ sessionClosed(sessionId: string, at = this.now()): void {
+ const turnId = this.openTurns.get(sessionId)
+ if (!turnId) return
+ this.openTurns.delete(sessionId)
+ if (!this.collecting()) return
+ this.reducer.turnFinished(turnId, at, 'failed')
+ this.dirty = true
+ }
+
+ /** Direct turn control, used by the conformance tests. */
+ turnFinished(turnId: string, outcome: TurnOutcome, at = this.now()): void {
+ if (!this.collecting()) return
+ this.reducer.turnFinished(turnId, at, outcome)
+ this.dirty = true
+ }
+
+ /**
+ * A `harness analytics off` run by the person at this computer wins over anything the account
+ * says. It is a marker file rather than a flag in the state JSON because that command is a
+ * separate short-lived process and two writers on one snapshot corrupts it.
+ */
+ private locallyDisabled(): boolean {
+ try { return existsSync(join(env.ADAPTER_DATA_DIR, 'analytics', 'disabled')) } catch { return false }
+ }
+
+ private collecting(): boolean {
+ return this.started && this.consent !== 'off' && !this.locallyDisabled()
+ }
+
+ private tick(): void {
+ const now = this.now()
+ const elapsed = now - this.lastTickAt
+ this.lastTickAt = now
+ if (!this.collecting()) return
+ this.reducer.tickUptime(now, elapsed, UPTIME_MAX_CREDIT_MS)
+ this.reducer.closeStaleTurns(now)
+ }
+
+ /** The report this computer would send, for `harness analytics preview` — nothing is uploaded. */
+ buildReport(now = new Date(this.now())): Record<string, unknown> {
+ const days = this.reducer.reportableDays().slice(-MAX_DAYS_PER_REPORT)
+ return {
+ schemaVersion: ANALYTICS_SCHEMA_VERSION,
+ epoch: this.epoch,
+ generatedAt: now.toISOString(),
+ collector: {
+ version: this.opts.collectorVersion,
+ engineCoverage: this.coverage,
+ enginesPresent: [...new Set(this.opts.enginesPresent())],
+ },
+ days: days.map((d) => this.reducer.reportFor(d, 'remote')).filter(Boolean),
+ }
+ }
+
+ consentState(): ConsentState {
+ return this.consent
+ }
+
+ async flush(now = new Date(this.now())): Promise<void> {
+ if (!this.started || this.flushing || this.locallyDisabled()) return
+ this.flushing = true
+ try {
+ if (this.dirty) { this.persist(); this.dirty = false }
+ const key = this.opts.token()
+ if (!key) return
+
+ const body = this.buildReport(now)
+ if ((body.days as unknown[]).length === 0) return
+
+ const res = await fetch(`${analyticsBaseUrl()}/api/analytics/report`, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json', 'x-api-key': key },
+ body: JSON.stringify(body),
+ })
+
+ if (res.status === 409) {
+ // The owner deleted this account's history. Anything still queued belongs to the old epoch,
+ // so it is dropped here rather than uploaded again on the next tick.
+ const payload = await res.json().catch(() => null) as { error?: { message?: string } } | null
+ this.epoch = extractEpoch(payload?.error?.message) ?? this.epoch + 1
+ this.reducer.clear()
+ this.persist()
+ console.log('[analytics] history was reset centrally; local records dropped')
+ return
+ }
+ if (!res.ok) return // transient: keep the snapshot and retry on the next flush
+
+ const parsed = await res.json().catch(() => null) as { data?: AnalyticsReportResponse } | null
+ const result = parsed?.data
+ if (!result) return
+
+ this.applyControl(result)
+ if (result.accepted > 0) {
+ // Keep a two-day tail so a late terminal event can still revise a recently-uploaded day.
+ const days = (body.days as { dayUtc: string }[]).map((d) => d.dayUtc)
+ this.reducer.forgetBefore(days[Math.max(0, days.length - 2)])
+ this.persist()
+ }
+ } catch {
+ // Offline, DNS down, backend restarting. The snapshot survives; the next flush retries.
+ } finally {
+ this.flushing = false
+ }
+ }
+
+ private applyControl(result: AnalyticsReportResponse): void {
+ const previous = this.consent
+ this.consent = result.consent
+ this.epoch = result.epoch
+
+ if (result.consent === 'off') {
+ this.reducer.clear()
+ this.persist()
+ if (previous !== 'off') console.log('[analytics] collection turned off by the account owner')
+ return
+ }
+ if (previous !== result.consent) this.persist()
+ }
+
+ private load(): void {
+ try {
+ const parsed = JSON.parse(readFileSync(analyticsStateFile(), 'utf8')) as PersistedState
+ if (parsed.version !== 1) return
+ this.consent = parsed.consent
+ this.epoch = parsed.epoch
+ this.reducer = new AnalyticsReducer(parsed.reducer)
+ } catch {
+ // No state yet, or unreadable. Starting clean loses at most today's counters, which is better
+ // than refusing to collect.
+ }
+ }
+
+ private persist(): void {
+ const payload: PersistedState = {
+ version: 1,
+ consent: this.consent,
+ epoch: this.epoch,
+ reducer: this.reducer.snapshot(),
+ }
+ try {
+ const target = analyticsStateFile()
+ mkdirSync(dirname(target), { recursive: true })
+ const tmp = `${target}.tmp`
+ writeFileSync(tmp, JSON.stringify(payload), 'utf8')
+ renameSync(tmp, target) // atomic: a crash mid-write must not leave a truncated state file
+ } catch {
+ // A read-only or full disk must not take the daemon down over analytics.
+ }
+ }
+}
+
+/** Pull the current epoch out of the 409 message so the collector resynchronises immediately. */
+export function extractEpoch(message: string | undefined): number | null {
+ const match = /current epoch is (\d+)/.exec(message ?? '')
+ return match ? Number(match[1]) : null
+}
diff --git a/cli/src/lib/analytics/command.ts b/cli/src/lib/analytics/command.ts
new file mode 100644
index 000000000..d68b841ec
--- /dev/null
+++ b/cli/src/lib/analytics/command.ts
@@ -0,0 +1,168 @@
+/**
+ * `harness analytics` — the local off switch and disclosure.
+ *
+ * Design: `autonomous-code` docs/design/harness-analytics.md ("Consent and privacy surfaces").
+ *
+ * Collection is on by default. The web app owns the account-level switch; this command owns what a
+ * person sitting at THIS computer can do without a browser: see exactly what is sent, and stop it.
+ *
+ * `off` writes a marker file rather than editing the daemon's state JSON, because these commands are
+ * short-lived processes running alongside a live daemon — two writers on one JSON file is a
+ * corrupted snapshot waiting to happen. The daemon polls the marker on its existing tick.
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs'
+import { dirname, join } from 'path'
+import { env } from '../../config/env.js'
+import { analyticsBaseUrl, analyticsStateFile } from './collector.js'
+import type { DailyReportPayload } from './contract.js'
+
+/** Presence of this file means "this computer does not report", whatever the account says. */
+export function analyticsDisabledFile(): string {
+ return join(env.ADAPTER_DATA_DIR, 'analytics', 'disabled')
+}
+
+export function isLocallyDisabled(): boolean {
+ try { return existsSync(analyticsDisabledFile()) } catch { return false }
+}
+
+/** Every field that can leave this computer, in the order the collector sends it. */
+export const UPLOADED_FIELDS: string[] = [
+ 'dayUtc', 'engine', 'mode', 'origin',
+ 'instructions', 'turnsStarted', 'turnsCompleted', 'turnsFailed',
+ 'turnsCancelled', 'turnsInputNeeded', 'agentRuntimeMs',
+ 'wallClockActiveMs', 'activeAgents', 'uptimeMs',
+ 'collectorVersion', 'engineCoverage', 'enginesPresent',
+]
+
+export const NEVER_SENT: string[] = [
+ 'what you typed, and what any engine replied',
+ 'file names, paths, code, or repository names',
+ 'tool names, tool arguments, or command output',
+ 'agent names, session ids, or workspace names',
+ 'any per-event timestamp — only daily totals',
+]
+
+interface PersistedState {
+ version?: number
+ consent?: string
+ epoch?: number
+ reducer?: unknown
+}
+
+function readState(): PersistedState | null {
+ try { return JSON.parse(readFileSync(analyticsStateFile(), 'utf8')) as PersistedState } catch { return null }
+}
+
+/**
+ * Render the local report.
+ *
+ * Deliberately reads the daemon's persisted snapshot rather than asking the backend: the whole point
+ * is to show what WOULD be sent, from a computer that may never have uploaded anything.
+ */
+export function localReport(): { days: DailyReportPayload[]; consent: string; epoch: number } {
+ const state = readState()
+ const reducer = state?.reducer as { days?: Record<string, unknown> } | undefined
+ const dayKeys = Object.keys(reducer?.days ?? {}).sort()
+ const days: DailyReportPayload[] = []
+
+ for (const key of dayKeys) {
+ const day = (reducer?.days as Record<string, {
+ buckets?: Record<string, Record<string, number>>
+ intervals?: [number, number][]
+ agents?: string[]
+ uptimeMs?: number
+ }>)[key]
+ const buckets = Object.entries(day.buckets ?? {}).map(([bucketKey, counters]) => {
+ const [engine, mode, origin] = bucketKey.split('|')
+ return { engine, mode, origin, ...counters } as unknown as DailyReportPayload['buckets'][number]
+ })
+ days.push({
+ dayUtc: key,
+ machineDay: {
+ wallClockActiveMs: (day.intervals ?? []).reduce((acc, [s, e]) => acc + (e - s), 0),
+ activeAgents: (day.agents ?? []).length,
+ uptimeMs: day.uptimeMs ?? 0,
+ reported: true,
+ },
+ buckets,
+ })
+ }
+
+ return { days, consent: state?.consent ?? 'on', epoch: state?.epoch ?? 0 }
+}
+
+function duration(ms: number): string {
+ const minutes = Math.round(ms / 60000)
+ const hours = Math.floor(minutes / 60)
+ return hours === 0 ? `${minutes}m` : `${hours}h ${String(minutes % 60).padStart(2, '0')}m`
+}
+
+export function renderPreview(): string {
+ const { days, consent, epoch } = localReport()
+ const out: string[] = []
+
+ out.push('Harness Analytics — what this computer would send')
+ out.push('')
+ out.push(` upload state ${isLocallyDisabled() ? 'off on this computer' : describeConsent(consent)}`)
+ out.push(` endpoint ${analyticsBaseUrl()}/api/analytics/report`)
+ out.push(` epoch ${epoch}`)
+ out.push('')
+ out.push('FIELDS — one row per engine, per day')
+ out.push('')
+ for (const field of UPLOADED_FIELDS) out.push(` ${field}`)
+ out.push('')
+ out.push('NEVER SENT')
+ out.push('')
+ for (const item of NEVER_SENT) out.push(` × ${item}`)
+ out.push('')
+
+ if (days.length === 0) {
+ out.push('Nothing recorded yet. Figures appear after your next agent turn.')
+ return out.join('\n')
+ }
+
+ out.push(`RECORDED LOCALLY — ${days.length} day${days.length === 1 ? '' : 's'}`)
+ out.push('')
+ for (const day of days.slice(-14)) {
+ const instructions = day.buckets.reduce((a, b) => a + b.instructions, 0)
+ const completed = day.buckets.reduce((a, b) => a + b.turnsCompleted, 0)
+ const failed = day.buckets.reduce((a, b) => a + b.turnsFailed + b.turnsCancelled, 0)
+ out.push(
+ ` ${day.dayUtc} ${String(instructions).padStart(4)} instructions` +
+ ` ${String(completed).padStart(4)} completed` +
+ ` ${String(failed).padStart(3)} failed/cancelled` +
+ ` ${duration(day.machineDay.wallClockActiveMs).padStart(8)} active`,
+ )
+ }
+ out.push('')
+ out.push('No prompt content is included, here or in what is uploaded.')
+ return out.join('\n')
+}
+
+function describeConsent(consent: string): string {
+ if (consent === 'off') return 'off (the account owner turned it off)'
+ // Collection is on by default; anything that is not an explicit off is uploading.
+ return 'uploading'
+}
+
+export function disableLocally(): string {
+ const target = analyticsDisabledFile()
+ mkdirSync(dirname(target), { recursive: true })
+ writeFileSync(target, `${new Date().toISOString()}\n`, 'utf8')
+ // Drop what was already collected: leaving it would upload the moment someone re-enabled.
+ try { rmSync(analyticsStateFile(), { force: true }) } catch { /* nothing to drop */ }
+ return 'Analytics is off on this computer. Local records were deleted.\nTurn it back on with: harness analytics on'
+}
+
+export function enableLocally(): string {
+ try { rmSync(analyticsDisabledFile(), { force: true }) } catch { /* already on */ }
+ return 'Analytics is on for this computer.'
+}
+
+/** Dispatch for `harness analytics [preview|on|off]`. */
+export function runAnalyticsCommand(sub: string | undefined): string {
+ if (sub === 'off') return disableLocally()
+ if (sub === 'on') return enableLocally()
+ if (!sub || sub === 'preview' || sub === 'status' || sub === 'report') return renderPreview()
+ return `Unknown subcommand "${sub}".\nUsage: harness analytics [preview|on|off]`
+}
diff --git a/cli/src/lib/analytics/contract.spec.ts b/cli/src/lib/analytics/contract.spec.ts
new file mode 100644
index 000000000..8e11cd987
--- /dev/null
+++ b/cli/src/lib/analytics/contract.spec.ts
@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest'
+import { ENGINES as CONTRACT_ENGINES, MODES, ORIGINS, TURN_OUTCOMES, utcDayKey } from './contract.js'
+import { ENGINES } from '../../engines/types.js'
+import { ENCRYPTED_UP_TYPES } from '../e2ee/core.js'
+
+/**
+ * Drift guards.
+ *
+ * `contract.ts` is a hand-kept mirror of `autonomous-code`'s copy — the two repositories share no
+ * package — so nothing but a test stops the copies from diverging. A thirteenth engine that reaches
+ * the CLI without reaching the analytics contract would silently report nothing, which the design
+ * names as the most damaging failure this product can have.
+ */
+describe('engine parity', () => {
+ it('counts exactly the engines this CLI integrates', () => {
+ expect([...CONTRACT_ENGINES].sort()).toEqual([...ENGINES].sort())
+ })
+})
+
+describe('lifecycle classification', () => {
+ it('still counts at the layer that can see plaintext', () => {
+ // If these frames stopped being encrypted the collector could in principle move; while they ARE
+ // encrypted, the relay cannot count them and this collector is the only layer that can.
+ expect(ENCRYPTED_UP_TYPES.has('turn_started')).toBe(true)
+ expect(ENCRYPTED_UP_TYPES.has('turn_ended')).toBe(true)
+ })
+})
+
+describe('vocabulary', () => {
+ it('pins the dimensions the backend indexes on', () => {
+ expect([...MODES]).toEqual(['self', 'managed', 'remote', 'provider'])
+ expect([...ORIGINS]).toEqual(['human', 'scheduled', 'system', 'api'])
+ expect([...TURN_OUTCOMES]).toEqual(['completed', 'failed', 'cancelled', 'input_required'])
+ })
+
+ it('agrees with the backend on what a day is', () => {
+ // Both sides key records by UTC midnight; a local-time day would move a machine's records the
+ // moment it travelled.
+ expect(utcDayKey('2026-08-11T23:59:59Z')).toBe('2026-08-11')
+ expect(utcDayKey('2026-08-12T00:00:00Z')).toBe('2026-08-12')
+ })
+})
diff --git a/cli/src/lib/analytics/contract.ts b/cli/src/lib/analytics/contract.ts
new file mode 100644
index 000000000..db314e6b2
--- /dev/null
+++ b/cli/src/lib/analytics/contract.ts
@@ -0,0 +1,163 @@
+/**
+ * Harness Analytics — the canonical, versioned contract.
+ *
+ * MIRROR of `autonomous-code`: apps/backend/src/types/analytics.ts. The two repositories share no
+ * package, so the copies are kept in sync by the conformance tests rather than by the module
+ * system. Edit the backend copy first, then mirror it here.
+ *
+ *
+ * Design: docs/design/harness-analytics.md
+ *
+ * The one rule that shapes everything here: ADDITIVE counters and NON-ADDITIVE metrics travel in
+ * different shapes. `DailyBucket` may be split by engine/mode/origin and re-summed; `MachineDay`
+ * may not, so it exists once per (machine, day) and is computed locally where every interval is
+ * visible.
+ */
+
+export const ANALYTICS_SCHEMA_VERSION = 1
+
+export const ENGINES = [
+ 'claude', 'codex', 'cursor', 'opencode', 'pi', 'hermes',
+ 'commandcode', 'devin', 'muse', 'amp', 'kilo', 'grok',
+] as const
+export type Engine = (typeof ENGINES)[number]
+
+export const MODES = ['self', 'managed', 'remote', 'provider'] as const
+export type Mode = (typeof MODES)[number]
+
+export const ORIGINS = ['human', 'scheduled', 'system', 'api'] as const
+export type Origin = (typeof ORIGINS)[number]
+
+export const TURN_OUTCOMES = ['completed', 'failed', 'cancelled', 'input_required'] as const
+export type TurnOutcome = (typeof TURN_OUTCOMES)[number]
+
+/**
+ * Collection is ON by default and can be turned off; there is no pending state.
+ *
+ * An earlier design held every upload until the account owner had acknowledged a field list. That
+ * gate was removed deliberately: it put a full-page interstitial in front of the dashboard, and the
+ * disclosure now lives as a non-blocking panel instead.
+ */
+export const CONSENT_STATES = ['on', 'off'] as const
+export type ConsentState = (typeof CONSENT_STATES)[number]
+
+/**
+ * Canonical activity events, emitted at the normalization boundary — before E2EE sealing on the
+ * remote CLI, because the relay cannot tell a real instruction from a duplicated control frame.
+ *
+ * `agentId` NEVER leaves the machine. It is present so the local reducer can compute a distinct
+ * active-agent count; only the resulting integer is uploaded.
+ */
+export type AnalyticsEventV1 =
+ | { type: 'instruction'; eventId: string; at: string; engine: Engine; origin: Origin }
+ | { type: 'turn_started'; turnId: string; at: string; engine: Engine; origin: Origin; agentId: string }
+ | { type: 'turn_finished'; turnId: string; at: string; outcome: TurnOutcome }
+
+/** ADDITIVE counters for one (day, engine, mode, origin). Safe to sum along any dimension. */
+export interface DailyBucketPayload {
+ engine: Engine
+ mode: Mode
+ origin: Origin
+ instructions: number
+ turnsStarted: number
+ turnsCompleted: number
+ turnsFailed: number
+ turnsCancelled: number
+ turnsInputNeeded: number
+ /** Sum of terminal turn durations. Concurrent agents overlap here by design. */
+ agentRuntimeMs: number
+}
+
+/**
+ * NON-ADDITIVE metrics for one (machine, day), plus the reporting heartbeat.
+ *
+ * Emitted for EVERY day the collector was alive, including an all-zero day: that is what lets the
+ * dashboard tell "up and idle" from "no data". A missing day is missing information, never zero.
+ */
+export interface MachineDayPayload {
+ /** Union of turn intervals — computed here, where the whole set is visible, and never split. */
+ wallClockActiveMs: number
+ /** Distinct agents with at least one accepted human instruction. */
+ activeAgents: number
+ /** Denominator for utilization. 0 when not meaningful (provider mode has no container). */
+ uptimeMs: number
+ reported: boolean
+}
+
+export interface DailyReportPayload {
+ /** Midnight UTC of the day, ISO-8601 (`2026-08-11` or a full timestamp). */
+ dayUtc: string
+ machineDay: MachineDayPayload
+ buckets: DailyBucketPayload[]
+}
+
+export interface CollectorInfo {
+ version: string
+ /** Engines this collector actually instruments. */
+ engineCoverage: Engine[]
+ /**
+ * Engines the collector can SEE on this machine (registered agents, discovered binaries).
+ *
+ * Coverage alone cannot answer "is anything being missed": an engine absent from `engineCoverage`
+ * is either uninstrumented or simply not installed, and reporting every engine the product knows
+ * about as "not instrumented" would be noise on every machine. The difference
+ * `enginesPresent - engineCoverage` is the honest set, and it is the only one the UI shows.
+ */
+ enginesPresent: Engine[]
+}
+
+/** Request body of `POST /api/analytics/report`. */
+export interface AnalyticsReportRequest {
+ schemaVersion: number
+ /** Account deletion epoch the collector last saw. An older epoch is refused. */
+ epoch: number
+ /** Client monotonic stamp; the server clamps it against its own clock. */
+ generatedAt: string
+ collector: CollectorInfo
+ days: DailyReportPayload[]
+}
+
+/**
+ * Response of `POST /api/analytics/report`. This doubles as the control channel: it is the only way
+ * a headless collector learns that the owner turned collection off or deleted the history.
+ */
+export interface AnalyticsReportResponse {
+ consent: ConsentState
+ epoch: number
+ serverTime: string
+ accepted: number
+ quarantined: number
+}
+
+/**
+ * How far a client stamp may sit from the server clock before its records are quarantined rather
+ * than stored. A machine whose clock is years off would otherwise write into a bucket far outside
+ * the range and take over every chart.
+ */
+export const CLOCK_SKEW_TOLERANCE_MS = 48 * 60 * 60 * 1000
+
+/** Days accepted in one report. A backlog flush after a long offline period needs several. */
+export const MAX_DAYS_PER_REPORT = 120
+
+/** Central retention for daily records: 13 months, so year-over-year views have a comparison. */
+export const RETENTION_DAYS = 396
+
+/** Buckets accepted for one day: 12 engines x 4 modes x 4 origins, with headroom. */
+export const MAX_BUCKETS_PER_DAY = 240
+
+/** Below this many terminal turns, a completion rate is suppressed instead of shown. */
+export const MIN_SAMPLE_FOR_RATE = 30
+
+/** Days of history required before an anomaly baseline is meaningful. */
+export const MIN_DAYS_FOR_BASELINE = 14
+
+/** Midnight UTC of the day containing `at`. The single definition of a day, used on both sides. */
+export function utcDayStart(at: Date | string): Date {
+ const d = typeof at === 'string' ? new Date(at) : at
+ return new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()))
+}
+
+/** `2026-08-11` — the wire form of a day key. */
+export function utcDayKey(at: Date | string): string {
+ return utcDayStart(at).toISOString().slice(0, 10)
+}
diff --git a/cli/src/lib/analytics/reducer.spec.ts b/cli/src/lib/analytics/reducer.spec.ts
new file mode 100644
index 000000000..4a198fda5
--- /dev/null
+++ b/cli/src/lib/analytics/reducer.spec.ts
@@ -0,0 +1,198 @@
+import { describe, expect, it } from 'vitest'
+import { AnalyticsReducer, mergeInterval, splitAcrossDays, unionMs } from './reducer.js'
+
+const MIN = 60_000
+const HOUR = 60 * MIN
+const DAY = 24 * HOUR
+
+const at = (iso: string): number => Date.parse(iso)
+
+function reducer(): AnalyticsReducer {
+ return new AnalyticsReducer()
+}
+
+describe('interval union', () => {
+ it('merges overlapping intervals instead of adding them', () => {
+ let merged: [number, number][] = []
+ merged = mergeInterval(merged, 0, 25 * MIN)
+ merged = mergeInterval(merged, 5 * MIN, 30 * MIN)
+
+ expect(merged).toEqual([[0, 30 * MIN]])
+ expect(unionMs(merged)).toBe(30 * MIN)
+ })
+
+ it('keeps disjoint intervals apart', () => {
+ let merged: [number, number][] = []
+ merged = mergeInterval(merged, 0, 10 * MIN)
+ merged = mergeInterval(merged, 40 * MIN, 50 * MIN)
+
+ expect(unionMs(merged)).toBe(20 * MIN)
+ })
+
+ it('closes a gap when a later interval bridges two existing ones', () => {
+ let merged: [number, number][] = []
+ merged = mergeInterval(merged, 0, 10 * MIN)
+ merged = mergeInterval(merged, 40 * MIN, 50 * MIN)
+ merged = mergeInterval(merged, 5 * MIN, 45 * MIN)
+
+ expect(merged).toEqual([[0, 50 * MIN]])
+ })
+})
+
+/**
+ * The first of the two additivity fixtures the design requires as permanent regressions.
+ */
+describe('overlapping turns on different engines', () => {
+ it('sums runtime but unions wall-clock time', () => {
+ const r = reducer()
+ r.turnStarted('a', at('2026-08-11T10:00:00Z'), 'claude', 'managed', 'human')
+ r.turnStarted('b', at('2026-08-11T10:05:00Z'), 'codex', 'managed', 'human')
+ r.turnFinished('a', at('2026-08-11T10:25:00Z'), 'completed')
+ r.turnFinished('b', at('2026-08-11T10:30:00Z'), 'completed')
+
+ const day = r.reportFor('2026-08-11', 'managed')!
+ const runtime = day.buckets.reduce((acc, b) => acc + b.agentRuntimeMs, 0)
+
+ expect(runtime).toBe(50 * MIN)
+ expect(day.machineDay.wallClockActiveMs).toBe(30 * MIN)
+ })
+})
+
+/**
+ * The second fixture: one agent, two origins, must still be one active agent.
+ */
+describe('one agent across two origins', () => {
+ it('counts the agent once while splitting its counters by origin', () => {
+ const r = reducer()
+ r.instruction(at('2026-08-11T09:00:00Z'), 'claude', 'managed', 'human', 'agent-1')
+ r.instruction(at('2026-08-11T11:00:00Z'), 'claude', 'managed', 'human', 'agent-1')
+ r.turnStarted('s', at('2026-08-11T12:00:00Z'), 'claude', 'managed', 'scheduled')
+ r.turnFinished('s', at('2026-08-11T12:10:00Z'), 'completed')
+
+ const day = r.reportFor('2026-08-11', 'managed')!
+
+ expect(day.machineDay.activeAgents).toBe(1)
+ expect(day.buckets).toHaveLength(2)
+ expect(day.buckets.find((b) => b.origin === 'human')!.instructions).toBe(2)
+ expect(day.buckets.find((b) => b.origin === 'scheduled')!.turnsCompleted).toBe(1)
+ })
+
+ it('does not count a scheduled turn towards active agents', () => {
+ const r = reducer()
+ r.instruction(at('2026-08-11T09:00:00Z'), 'claude', 'managed', 'scheduled', 'agent-1')
+
+ expect(r.reportFor('2026-08-11', 'managed')!.machineDay.activeAgents).toBe(0)
+ })
+})
+
+describe('midnight', () => {
+ it('splits a turn across the UTC day boundary', () => {
+ expect(splitAcrossDays(at('2026-08-11T23:30:00Z'), at('2026-08-12T00:30:00Z'))).toEqual([
+ { start: at('2026-08-11T23:30:00Z'), end: at('2026-08-12T00:00:00Z') },
+ { start: at('2026-08-12T00:00:00Z'), end: at('2026-08-12T00:30:00Z') },
+ ])
+ })
+
+ it('attributes runtime to both days and the outcome to the day it ended', () => {
+ const r = reducer()
+ r.turnStarted('t', at('2026-08-11T23:30:00Z'), 'claude', 'managed', 'human')
+ r.turnFinished('t', at('2026-08-12T00:30:00Z'), 'completed')
+
+ const first = r.reportFor('2026-08-11', 'managed')!
+ const second = r.reportFor('2026-08-12', 'managed')!
+
+ expect(first.machineDay.wallClockActiveMs).toBe(30 * MIN)
+ expect(second.machineDay.wallClockActiveMs).toBe(30 * MIN)
+ expect(first.buckets.reduce((a, b) => a + b.turnsCompleted, 0)).toBe(0)
+ expect(second.buckets.reduce((a, b) => a + b.turnsCompleted, 0)).toBe(1)
+ })
+})
+
+describe('stale turns', () => {
+ it('closes a turn the machine never finished, instead of losing the day', () => {
+ const r = reducer()
+ r.turnStarted('t', at('2026-08-11T10:00:00Z'), 'claude', 'managed', 'human')
+
+ expect(r.closeStaleTurns(at('2026-08-11T12:00:00Z'))).toBe(0)
+ expect(r.closeStaleTurns(at('2026-08-13T10:00:00Z'))).toBe(1)
+
+ const day = r.reportFor('2026-08-12', 'managed')!
+ expect(day.buckets.reduce((a, b) => a + b.turnsFailed, 0)).toBe(1)
+ })
+
+ it('ignores a turn_finished for an id it never saw start', () => {
+ const r = reducer()
+ r.turnFinished('ghost', at('2026-08-11T10:00:00Z'), 'completed')
+
+ expect(r.reportFor('2026-08-11', 'managed')).toBeNull()
+ })
+})
+
+describe('heartbeat and uptime', () => {
+ it('emits reported:true on a day with no activity at all', () => {
+ const r = reducer()
+ r.tickUptime(at('2026-08-11T10:00:00Z'), 60_000, 90_000)
+
+ const day = r.reportFor('2026-08-11', 'managed')!
+ expect(day.machineDay.reported).toBe(true)
+ expect(day.machineDay.wallClockActiveMs).toBe(0)
+ expect(day.buckets).toHaveLength(0)
+ })
+
+ it('caps a single uptime credit so a suspended container cannot claim the gap', () => {
+ const r = reducer()
+ r.tickUptime(at('2026-08-11T10:00:00Z'), 6 * HOUR, 90_000)
+
+ expect(r.reportFor('2026-08-11', 'managed')!.machineDay.uptimeMs).toBe(90_000)
+ })
+
+ it('splits an uptime credit that spans midnight', () => {
+ const r = reducer()
+ r.tickUptime(at('2026-08-12T00:00:30Z'), 60_000, 90_000)
+
+ expect(r.reportFor('2026-08-11', 'managed')!.machineDay.uptimeMs).toBe(30_000)
+ expect(r.reportFor('2026-08-12', 'managed')!.machineDay.uptimeMs).toBe(30_000)
+ })
+})
+
+describe('persistence', () => {
+ it('survives a restart with its open turns intact', () => {
+ const first = reducer()
+ first.turnStarted('t', at('2026-08-11T10:00:00Z'), 'claude', 'managed', 'human')
+
+ const revived = new AnalyticsReducer(JSON.parse(JSON.stringify(first.snapshot())))
+ revived.turnFinished('t', at('2026-08-11T10:20:00Z'), 'completed')
+
+ expect(revived.reportFor('2026-08-11', 'managed')!.machineDay.wallClockActiveMs).toBe(20 * MIN)
+ })
+
+ it('forgets days already stored centrally', () => {
+ const r = reducer()
+ r.tickUptime(at('2026-08-09T10:00:00Z'), 60_000, 90_000)
+ r.tickUptime(at('2026-08-11T10:00:00Z'), 60_000, 90_000)
+ r.forgetBefore('2026-08-11')
+
+ expect(r.reportableDays()).toEqual(['2026-08-11'])
+ })
+
+ it('keeps the local store bounded', () => {
+ const r = reducer()
+ const base = at('2020-01-01T00:00:00Z')
+ for (let i = 0; i < 130; i++) r.tickUptime(base + i * DAY, 1000, 90_000)
+
+ expect(r.reportableDays().length).toBeLessThanOrEqual(120)
+ })
+})
+
+describe('privacy', () => {
+ it('never puts an agent id on the wire', () => {
+ const r = reducer()
+ r.instruction(at('2026-08-11T09:00:00Z'), 'claude', 'managed', 'human', 'secret-agent-name')
+ r.turnStarted('t', at('2026-08-11T09:00:00Z'), 'claude', 'managed', 'human')
+ r.turnFinished('t', at('2026-08-11T09:10:00Z'), 'completed')
+
+ const wire = JSON.stringify(r.reportFor('2026-08-11', 'managed'))
+ expect(wire).not.toContain('secret-agent-name')
+ expect(JSON.parse(wire).machineDay.activeAgents).toBe(1)
+ })
+})
diff --git a/cli/src/lib/analytics/reducer.ts b/cli/src/lib/analytics/reducer.ts
new file mode 100644
index 000000000..fd003a7ae
--- /dev/null
+++ b/cli/src/lib/analytics/reducer.ts
@@ -0,0 +1,305 @@
+/**
+ * Harness Analytics — the local reducer.
+ *
+ * Design: docs/design/harness-analytics.md ("Local reducer and daily aggregates").
+ *
+ * This is where the additive/non-additive split is actually produced. Counters are accumulated per
+ * (day, engine, mode, origin); the union of turn intervals and the distinct agent count are computed
+ * HERE, per (machine, day), because this is the only place the whole set of intervals is visible.
+ * Splitting either of them by engine and re-summing later is the bug this shape exists to prevent.
+ *
+ * Nothing in this file keeps prompt text, tool data, file names, or timestamps beyond the day
+ * totals. `agentId` is held only long enough to count distinct agents and is never emitted.
+ */
+import {
+ utcDayKey,
+ type DailyBucketPayload,
+ type DailyReportPayload,
+ type Engine,
+ type Mode,
+ type Origin,
+ type TurnOutcome,
+} from './contract.js'
+
+const DAY_MS = 24 * 60 * 60 * 1000
+
+/** A turn still open after this long is closed as failed — the machine was almost certainly killed. */
+export const STALE_TURN_MS = 24 * 60 * 60 * 1000
+
+/** Days retained locally. Aggregates are tiny, but the queue must still be bounded. */
+export const MAX_LOCAL_DAYS = 120
+
+type BucketKey = string // `${engine}|${mode}|${origin}`
+
+interface Counters {
+ instructions: number
+ turnsStarted: number
+ turnsCompleted: number
+ turnsFailed: number
+ turnsCancelled: number
+ turnsInputNeeded: number
+ agentRuntimeMs: number
+}
+
+interface DayState {
+ buckets: Record<BucketKey, Counters>
+ /** Merged, disjoint, sorted [startMs, endMs) offsets within the day. */
+ intervals: [number, number][]
+ /** Agent ids with at least one accepted human instruction. Never leaves this process. */
+ agents: string[]
+ uptimeMs: number
+}
+
+interface OpenTurn {
+ turnId: string
+ startedAt: number
+ engine: Engine
+ mode: Mode
+ origin: Origin
+}
+
+export interface ReducerSnapshot {
+ version: 1
+ days: Record<string, DayState>
+ openTurns: Record<string, OpenTurn>
+}
+
+function emptyCounters(): Counters {
+ return {
+ instructions: 0,
+ turnsStarted: 0,
+ turnsCompleted: 0,
+ turnsFailed: 0,
+ turnsCancelled: 0,
+ turnsInputNeeded: 0,
+ agentRuntimeMs: 0,
+ }
+}
+
+function emptyDay(): DayState {
+ return { buckets: {}, intervals: [], agents: [], uptimeMs: 0 }
+}
+
+function dayStartMs(at: number): number {
+ const d = new Date(at)
+ return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate())
+}
+
+/**
+ * Merge `[start, end)` into a disjoint sorted interval set.
+ *
+ * This is the union that makes wall-clock time honest: two agents working 10:00-10:25 and
+ * 10:05-10:30 contribute 30 minutes here, while their runtimes contribute 50 minutes to the
+ * additive counter. Both numbers are correct and they answer different questions.
+ */
+export function mergeInterval(
+ intervals: [number, number][],
+ start: number,
+ end: number,
+): [number, number][] {
+ if (end <= start) return intervals
+ const out: [number, number][] = []
+ let lo = start
+ let hi = end
+ let inserted = false
+ for (const [s, e] of intervals) {
+ if (e < lo) {
+ out.push([s, e])
+ } else if (s > hi) {
+ if (!inserted) { out.push([lo, hi]); inserted = true }
+ out.push([s, e])
+ } else {
+ lo = Math.min(lo, s)
+ hi = Math.max(hi, e)
+ }
+ }
+ if (!inserted) out.push([lo, hi])
+ return out.sort((a, b) => a[0] - b[0])
+}
+
+export function unionMs(intervals: [number, number][]): number {
+ return intervals.reduce((acc, [s, e]) => acc + (e - s), 0)
+}
+
+/**
+ * The reducer.
+ *
+ * Deliberately pure with respect to time: every entry point takes an explicit timestamp, so the
+ * midnight-split, stale-turn, and uptime behaviours are testable without waiting for a clock.
+ */
+export class AnalyticsReducer {
+ private days = new Map<string, DayState>()
+ private open = new Map<string, OpenTurn>()
+
+ constructor(snapshot?: ReducerSnapshot) {
+ if (snapshot?.version === 1) {
+ for (const [day, state] of Object.entries(snapshot.days)) this.days.set(day, state)
+ for (const [id, turn] of Object.entries(snapshot.openTurns)) this.open.set(id, turn)
+ }
+ }
+
+ snapshot(): ReducerSnapshot {
+ return {
+ version: 1,
+ days: Object.fromEntries(this.days),
+ openTurns: Object.fromEntries(this.open),
+ }
+ }
+
+ private day(key: string): DayState {
+ let state = this.days.get(key)
+ if (!state) {
+ state = emptyDay()
+ this.days.set(key, state)
+ this.prune()
+ }
+ return state
+ }
+
+ private counters(dayKey: string, engine: Engine, mode: Mode, origin: Origin): Counters {
+ const state = this.day(dayKey)
+ const key: BucketKey = `${engine}|${mode}|${origin}`
+ state.buckets[key] = state.buckets[key] ?? emptyCounters()
+ return state.buckets[key]
+ }
+
+ private prune(): void {
+ if (this.days.size <= MAX_LOCAL_DAYS) return
+ const sorted = [...this.days.keys()].sort()
+ for (const key of sorted.slice(0, this.days.size - MAX_LOCAL_DAYS)) this.days.delete(key)
+ }
+
+ /**
+ * A human instruction was accepted. Called only for turns the normalizer classified as real user
+ * input — system prompts, tool results, replay, and compaction never reach here.
+ */
+ instruction(at: number, engine: Engine, mode: Mode, origin: Origin, agentId?: string): void {
+ const key = utcDayKey(new Date(at))
+ this.counters(key, engine, mode, origin).instructions++
+ if (origin === 'human' && agentId) {
+ const state = this.day(key)
+ if (!state.agents.includes(agentId)) state.agents.push(agentId)
+ }
+ }
+
+ turnStarted(turnId: string, at: number, engine: Engine, mode: Mode, origin: Origin): void {
+ this.counters(utcDayKey(new Date(at)), engine, mode, origin).turnsStarted++
+ this.open.set(turnId, { turnId, startedAt: at, engine, mode, origin })
+ }
+
+ /**
+ * Close a turn.
+ *
+ * The outcome counts on the day the turn ENDED, which is one arbitrary choice made consistently
+ * and stated in the metric tooltip. Runtime and the wall-clock union are split at the UTC day
+ * boundary, so a turn running across midnight contributes to both days truthfully.
+ */
+ turnFinished(turnId: string, at: number, outcome: TurnOutcome): void {
+ const turn = this.open.get(turnId)
+ if (!turn) return
+ this.open.delete(turnId)
+ const end = Math.max(at, turn.startedAt)
+
+ const counters = this.counters(utcDayKey(new Date(end)), turn.engine, turn.mode, turn.origin)
+ if (outcome === 'completed') counters.turnsCompleted++
+ else if (outcome === 'failed') counters.turnsFailed++
+ else if (outcome === 'cancelled') counters.turnsCancelled++
+ else counters.turnsInputNeeded++
+
+ for (const slice of splitAcrossDays(turn.startedAt, end)) {
+ const key = utcDayKey(new Date(slice.start))
+ const base = dayStartMs(slice.start)
+ this.counters(key, turn.engine, turn.mode, turn.origin).agentRuntimeMs += slice.end - slice.start
+ const state = this.day(key)
+ state.intervals = mergeInterval(state.intervals, slice.start - base, slice.end - base)
+ }
+ }
+
+ /**
+ * Close turns that outlived any plausible run.
+ *
+ * Without this a machine killed mid-turn would leave the turn open forever: its runtime would
+ * never land anywhere and the day would silently under-report. Truncating at the last observed
+ * event and calling it `failed` is the honest reading of "we stopped hearing about it".
+ */
+ closeStaleTurns(now: number): number {
+ let closed = 0
+ for (const [id, turn] of [...this.open]) {
+ if (now - turn.startedAt < STALE_TURN_MS) continue
+ this.turnFinished(id, turn.startedAt + STALE_TURN_MS, 'failed')
+ closed++
+ }
+ return closed
+ }
+
+ /**
+ * Credit time the collector was alive, for the utilization denominator.
+ *
+ * Bounded per call so a suspended container that wakes up hours later does not credit the gap: we
+ * only know the process was running when it was actually ticking.
+ */
+ tickUptime(now: number, elapsedMs: number, maxCreditMs: number): void {
+ const credit = Math.max(0, Math.min(elapsedMs, maxCreditMs))
+ if (credit === 0) return
+ for (const slice of splitAcrossDays(now - credit, now)) {
+ this.day(utcDayKey(new Date(slice.start))).uptimeMs += slice.end - slice.start
+ }
+ }
+
+ /** Days that have any activity or any credited uptime — i.e. days this collector was alive. */
+ reportableDays(): string[] {
+ return [...this.days.keys()].sort()
+ }
+
+ /**
+ * Build the wire payload for a day.
+ *
+ * `reported: true` on an all-zero day is the heartbeat: it is what lets the dashboard say "up and
+ * idle" instead of leaving a gap that looks identical to a machine that was switched off.
+ */
+ reportFor(dayKey: string, mode: Mode): DailyReportPayload | null {
+ const state = this.days.get(dayKey)
+ if (!state) return null
+ const buckets: DailyBucketPayload[] = Object.entries(state.buckets).map(([key, counters]) => {
+ const [engine, bucketMode, origin] = key.split('|') as [Engine, Mode, Origin]
+ return { engine, mode: bucketMode, origin, ...counters }
+ })
+ void mode
+ return {
+ dayUtc: dayKey,
+ machineDay: {
+ wallClockActiveMs: unionMs(state.intervals),
+ activeAgents: state.agents.length,
+ uptimeMs: state.uptimeMs,
+ reported: true,
+ },
+ buckets,
+ }
+ }
+
+ /** Drop everything. Used when the account turns collection off or deletes its history. */
+ clear(): void {
+ this.days.clear()
+ this.open.clear()
+ }
+
+ /** Forget days already stored centrally, keeping a small tail in case a later revision arrives. */
+ forgetBefore(dayKey: string): void {
+ for (const key of [...this.days.keys()]) {
+ if (key < dayKey) this.days.delete(key)
+ }
+ }
+}
+
+/** Split `[start, end)` at UTC midnights, so no interval is ever attributed to the wrong day. */
+export function splitAcrossDays(start: number, end: number): { start: number; end: number }[] {
+ const out: { start: number; end: number }[] = []
+ let cursor = start
+ while (cursor < end) {
+ const boundary = dayStartMs(cursor) + DAY_MS
+ const stop = Math.min(end, boundary)
+ out.push({ start: cursor, end: stop })
+ cursor = stop
+ }
+ return out
+}