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 { readdirSync, readFileSync } from 'node:fs'
import { join } from 'node:path'
import { fileURLToPath } from 'node:url'
import { expect, it, vi } from 'vitest'
import { failureKind, launchErrorCode, messageReceipt, storeErrorCode, productObservation, productUsageIntent, productUsageLaunch, productUsageRequest, productUsageSource } from './productUsageSignals.js'
import type { MessageOutcome } from './sessionInput.js'
import { LAUNCH_ERROR_CODES, PRODUCT_USAGE_AUTOMATIC_ACTIONS, PRODUCT_USAGE_FLOWS, PRODUCT_USAGE_METRICS, PRODUCT_USAGE_SETUP_METRICS } from './productUsageContract.js'
import { AUTOMATIC_POLL_ACTIONS, HEALTH_MEASURES } from './productHealthContract.js'
import { searchRequests } from '../services/search.js'
it('separates automated polling, tool and app RPCs without inspecting error objects or content', () => {
const emit = vi.fn()
productUsageRequest('models_list', emit, Date.now, 'app')(undefined, undefined, false)
productUsageRequest('models_list', emit, Date.now, 'tool')(undefined, undefined, false)
productUsageRequest('agent_resume', emit, Date.now, 'tool')('AGENT_NOT_FOUND', 'failed', false)
productUsageRequest('agent_close', emit, Date.now, 'app')(undefined, 'cancelled', false)
const secret = { toString() { throw Error('PRIVATE') } }
expect(() => productUsageRequest('agent_restart', emit, Date.now, 'unknown')(secret, 'failed', false)).not.toThrow()
expect(emit.mock.calls.flat()).toEqual(expect.arrayContaining(['request_automatic_model_list_ok', 'request_tool_resume_error_not_found', 'request_app_close_cancelled', 'request_unknown_restart_error_other']))
expect(JSON.stringify(emit.mock.calls)).not.toContain('PRIVATE')
expect(emit.mock.calls.flat()).toContain('request_tool_model_list_ok')
})
it('tells the phone apart from the browser only by its own word, and never a local or device client', () => {
expect(productUsageSource(true, true, null, {})).toBe('tool')
expect(productUsageSource(true, false, null, { usageSurface: 'phone' })).toBe('app')
expect(productUsageSource(false, false, 'web', { usageSurface: 'phone' })).toBe('phone')
expect(productUsageSource(false, false, 'web', {})).toBe('app')
expect(productUsageSource(false, false, 'web', undefined)).toBe('app')
expect(productUsageSource(false, false, 'web', { usageSurface: 'PRIVATE_LABEL' })).toBe('app')
expect(productUsageSource(false, false, 'device', { usageSurface: 'phone' })).toBe('unknown')
expect(productUsageSource(false, false, null, { usageSurface: 'phone' })).toBe('unknown')
})
it('counts what a person on the phone asked for as the phone\'s, and its polls as automatic', () => {
const emit = vi.fn()
productUsageRequest('agent_create', emit, Date.now, 'phone')(undefined, 'created', true)
productUsageRequest('agent_resume', emit, Date.now, 'phone')('AGENT_BUSY', 'failed', false)
productUsageRequest('agent_recent', emit, Date.now, 'phone')(undefined, undefined, false)
productUsageRequest('models_list', emit, Date.now, 'phone')(undefined, undefined, false)
const names = emit.mock.calls.flat()
expect(names).toEqual(expect.arrayContaining(['request_phone_create_started', 'request_phone_create_ok',
'request_phone_resume_error_other', 'request_phone_resume_reason_busy',
'request_automatic_history_ok', 'request_automatic_model_list_ok']))
expect(names).not.toContain('request_phone_history_ok')
// One list of the fixed polls, as the feature counts name them.
expect([...AUTOMATIC_POLL_ACTIONS]).toEqual([...PRODUCT_USAGE_AUTOMATIC_ACTIONS])
// The phone's polls again, apart from every app's `automatic`; nothing else of the phone's.
expect(names.filter(name => name.startsWith('request_phone_automatic_'))).toEqual(['request_phone_automatic_history_started',
'request_phone_automatic_history_ok', 'request_phone_automatic_model_list_started', 'request_phone_automatic_model_list_ok'])
for (const name of names) expect(PRODUCT_USAGE_METRICS).toContain(name)
const work = vi.fn()
productUsageIntent('message', 'interactive', 'agent', 'phone', work)
expect(work).toHaveBeenCalledWith({ id: 'agent', phase: 'work_requested', origin: 'interactive' })
})
it('requires an explicit composer marker for interactive work; raw terminal input is unclassified', () => {
const emit = vi.fn()
productUsageIntent('terminal_input', 'interactive', 'agent', 'app', emit)
productUsageIntent('message', undefined, 'agent', 'app', emit)
expect(emit).not.toHaveBeenCalled()
productUsageIntent('message', 'interactive', 'agent', 'app', emit)
expect(emit).toHaveBeenCalledWith({ id: 'agent', phase: 'work_requested', origin: 'interactive' })
expect(() => productUsageIntent('message', undefined, 'agent', 'tool', () => { throw Error() })).not.toThrow()
})
it('distinguishes a pending launch from a launched harness, and counts replies once', () => {
let now = 0
const emit = vi.fn(), done = productUsageRequest('agent_create', emit, () => now)
now = 12_000; done(undefined, 'pending', false); done(undefined, 'created', true)
expect(emit.mock.calls.flat()).toEqual(['create_requests', 'create_pending', 'create_10s_to_1m'])
})
it('maps known failures and never emits raw or unknown error strings', () => {
const emit = vi.fn()
productUsageRequest('agent_create', emit)('ENGINE_UNAVAILABLE', undefined, false)
productUsageRequest('agent_restart', emit)('PRIVATE_ERROR_WITH_PATH', 'failed', false)
expect(emit.mock.calls.flat()).toContain('create_error_setup')
expect(emit.mock.calls.flat()).toContain('restart_error_other')
expect(JSON.stringify(emit.mock.calls)).not.toContain('PRIVATE_')
})
it('ignores arbitrary RPC names and status polling and survives unavailable reporting', () => {
const emit = vi.fn()
for (const type of ['PRIVATE_METHOD', 'agent_create_status', 'text_delta']) productUsageRequest(type, emit)(undefined, undefined, true)
expect(emit).not.toHaveBeenCalled()
expect(() => productUsageRequest('agent_create', () => { throw Error('offline') })(undefined, 'created', true)).not.toThrow()
})
const ID = 'fixture-creation-one'
it('reduces durable launch statuses to fixed categories without forwarding error or hold text', () => {
const emit = vi.fn(), id = 'fixture-creation-one'
productUsageLaunch('agent_create', id, emit)(undefined, 'pending', false, 'install')
productUsageLaunch('agent_create_status', id, emit)('PRIVATE_CANARY', 'failed', false, 'PRIVATE_CANARY')
expect(emit.mock.calls.flat()).toEqual([{ id, phase: 'start', engine: 'other' }, { id, phase: 'pending', wait: 'install' },
{ id, phase: 'failed', failure: 'other', code: 'unlisted' }])
expect(JSON.stringify(emit.mock.calls)).not.toContain('PRIVATE_CANARY')
})
it.each([
['INVALID_PROMPT', 'invalid_prompt'], ['ENGINE_INSTALL_FAILED', 'engine_install_failed'], ['CREATION_STORAGE_FAILED', 'creation_storage_failed'],
['PRIVATE_ERROR_WITH_PATH', 'unlisted'], ['__proto__', 'unlisted'], ['UNLISTED', 'unlisted'], ['NONE', 'unlisted'],
['INTERNAL'.repeat(20), 'unlisted'], [undefined, 'none'], [{ code: 'INVALID_PROMPT' }, 'none'],
])('names the code of an `other` launch failure %s as %s, from the fixed list only', (error, code) => {
expect(launchErrorCode(error)).toBe(code)
const emit = vi.fn()
productUsageLaunch('agent_create_status', 'fixture-creation-one', emit)(error, 'failed', false, undefined)
expect(emit).toHaveBeenCalledWith({ id: 'fixture-creation-one', phase: 'failed', failure: 'other', code })
expect(LAUNCH_ERROR_CODES).toContain(code)
})
it.each(['ENGINE_LAUNCH_REFUSED', 'PTY_HOST_UNAVAILABLE', 'GIT_PROJECT_UNAVAILABLE', 'BRANCH_EXISTS',
'INVALID_BRANCH', 'BRANCH_SWITCH_FAILED', 'BRANCH_IN_USE', 'WORKTREE_FAILED'])('names the launch helper refusal %s', code => {
expect(launchErrorCode(code)).toBe(code.toLowerCase())
})
// Opening a conversation that is already a harness, or a cloud agent with no task, is the request turned down, not
// Harness failing: the Oct 26 report counted them as launch failures.
it.each(['SESSION_IN_HARNESS', 'SESSION_OPEN_ELSEWHERE', 'SESSION_OPEN_IN_TERMINAL', 'SESSION_BUSY_IN_TERMINAL', 'INVALID_REQUEST'])(
'counts the correct refusal %s as refused, not as a launch failure', error => {
const emit = vi.fn()
productUsageLaunch('agent_create', ID, emit)(error, undefined, false, undefined)
productUsageLaunch('agent_create_status', ID, emit)(error, 'failed', false, undefined)
const refused = { id: ID, phase: 'refused', code: error.toLowerCase() }
expect(emit.mock.calls.flat().slice(1)).toEqual([refused, refused])
})
it('still counts a failure that is no refusal as failed', () => {
const emit = vi.fn()
productUsageLaunch('agent_create_status', ID, emit)('SPAWN_FAILED', 'failed', false, undefined)
expect(emit).toHaveBeenCalledWith({ id: ID, phase: 'failed', failure: 'setup', code: 'spawn_failed' })
})
it('marks a launch an agent started, and only that one', () => {
const emit = vi.fn()
productUsageLaunch('agent_create', ID, emit, 'claude', true)
productUsageLaunch('agent_create', ID, emit, 'claude')
expect(emit.mock.calls.flat()).toEqual([{ id: ID, phase: 'start', engine: 'claude', agentStarted: true }, { id: ID, phase: 'start', engine: 'claude' }])
})
it('keeps a setup refusal\'s fixed code for the separate setup diagnostic, leaving other kinds alone', () => {
const emit = vi.fn()
productUsageLaunch('agent_create_status', 'fixture-creation-one', emit)('TMUX_UNAVAILABLE', 'failed', false, undefined)
expect(emit).toHaveBeenLastCalledWith({ id: 'fixture-creation-one', phase: 'failed', failure: 'setup', code: 'tmux_unavailable' })
for (const [error, failure] of [['AUTH_REQUIRED', 'auth'], ['TIMEOUT', 'unavailable'], ['INVALID_CWD', 'invalid']]) {
productUsageLaunch('agent_create_status', 'fixture-creation-one', emit)(error, 'failed', false, undefined)
expect(emit).toHaveBeenLastCalledWith({ id: 'fixture-creation-one', phase: 'failed', failure })
}
})
it('counts setup reasons once per create request, apart for the phone, without changing other-by-code totals', () => {
const emit = vi.fn()
const phone = productUsageRequest('agent_create', emit, () => 0, 'phone')
phone('TMUX_UNAVAILABLE', 'failed', false); phone('SPAWN_FAILED', 'failed', false)
productUsageRequest('agent_create', emit, () => 0, 'app')('NATIVE_LAUNCH_HELD', 'failed', false)
productUsageRequest('agent_create', emit, () => 0, 'tool')('PTY_HOST_UNAVAILABLE', 'failed', false)
productUsageRequest('agent_create', emit, () => 0, 'phone')('PRIVATE_CANARY', 'failed', false)
productUsageRequest('agent_create', emit, () => 0, 'phone')(undefined, 'pending', false)
productUsageRequest('agent_create_status', emit, () => 0, 'phone')('SPAWN_FAILED', 'failed', false)
const names: string[] = emit.mock.calls.flat()
expect(names.filter(name => name.startsWith('create_error_setup_code_')).sort()).toEqual([
'create_error_setup_code_native_launch_held', 'create_error_setup_code_pty_host_unavailable', 'create_error_setup_code_tmux_unavailable',
])
expect(names.filter(name => name.startsWith('phone_create_error_setup_code_'))).toEqual(['phone_create_error_setup_code_tmux_unavailable'])
expect(names.filter(name => name === 'create_error_setup')).toHaveLength(3)
expect(names.filter(name => name === 'request_phone_create_error_setup')).toHaveLength(1)
expect(names.filter(name => name.startsWith('create_error_code_'))).toEqual(['create_error_code_unlisted'])
for (const name of names) expect(PRODUCT_USAGE_METRICS).toContain(name)
expect(JSON.stringify(names)).not.toContain('PRIVATE_CANARY')
})
it('keeps a failed phone create measurable when the optional setup diagnostic cannot be recorded', () => {
const names: string[] = []
const measured = productUsageRequest('agent_create', metric => {
if (metric.startsWith('phone_create_error_setup_code_')) throw Error('reporting unavailable')
names.push(metric)
}, () => 0, 'phone')
expect(() => measured('TMUX_UNAVAILABLE', 'failed', false)).not.toThrow()
expect(names).toContain('request_phone_create_error_setup')
expect(names).toContain('create_error_setup_code_tmux_unavailable')
})
it('counts the code of an `other` create or resume refusal beside its kind, so each code family adds up to its `_other`', () => {
const emit = vi.fn()
productUsageRequest('agent_create', emit, () => 0, 'app')('PROMPT_TOO_LONG', undefined, false)
productUsageRequest('agent_create', emit, () => 0, 'app')('PRIVATE_ERROR_WITH_PATH', 'failed', false)
productUsageRequest('agent_create', emit, () => 0, 'app')(undefined, 'failed', false)
productUsageRequest('agent_create', emit, () => 0, 'app')('INVALID_CWD', undefined, false)
productUsageRequest('agent_resume', emit, () => 0, 'app')('SESSION_NOT_FOUND', 'failed', false)
productUsageRequest('agent_resume', emit, () => 0, 'app')(undefined, undefined, false, false)
// Other actions keep their kinds only.
productUsageRequest('agent_fork', emit, () => 0, 'app')('PRIVATE_FORK_ERROR', 'failed', false)
const names: string[] = emit.mock.calls.flat()
const family = (prefix: string) => names.filter(name => name.startsWith(prefix)).sort()
expect(family('create_error_code_')).toEqual(['create_error_code_none', 'create_error_code_prompt_too_long', 'create_error_code_unlisted'])
expect(names.filter(name => name === 'create_error_other')).toHaveLength(3)
expect(family('resume_error_code_')).toEqual(['resume_error_code_none', 'resume_error_code_session_not_found'])
expect(names.filter(name => name === 'resume_error_other')).toHaveLength(2)
expect(names.some(name => name.startsWith('fork_error_code_'))).toBe(false)
for (const name of names) expect(PRODUCT_USAGE_METRICS).toContain(name)
expect(JSON.stringify(names)).not.toContain('PRIVATE_')
})
it('measures a person\'s message by what became of it, under its source, once', () => {
const said = (outcome: MessageOutcome, source: 'phone' | 'app' = 'phone') => {
const emit = vi.fn()
const receipt = messageReceipt(productUsageRequest('message', emit, () => 0, source))
receipt(outcome)
receipt('started')
return emit.mock.calls.flat().filter(name => name !== `request_${source}_message_started`)
}
expect(said('started')).toEqual(['request_phone_message_ok'])
expect(said('taken', 'app')).toEqual(['request_app_message_ok'])
expect(said('agent_gone')).toEqual(['request_phone_message_failed', 'request_phone_message_error_not_found'])
expect(said('runtime_gone')).toEqual(['request_phone_message_failed', 'request_phone_message_error_unavailable'])
for (const busy of ['held', 'withheld', 'queue_full'] as const) {
expect(said(busy)).toEqual(['request_phone_message_failed', 'request_phone_message_error_conflict'])
}
for (const late of ['not_submitted', 'queue_expired'] as const) {
expect(said(late)).toEqual(['request_phone_message_failed', 'request_phone_message_error_timeout'])
}
expect(said('invalid')).toEqual(['request_phone_message_failed', 'request_phone_message_error_invalid'])
expect(said('paste_failed')).toEqual(['request_phone_message_failed', 'request_phone_message_error_other'])
for (const unsure of ['ambiguous', 'prompt_mismatch', 'turn_ended'] as const) {
expect(said(unsure)).toEqual(['request_phone_message_unknown'])
}
expect(said('cancelled')).toEqual(['request_phone_message_cancelled'])
// The message's own name is never a product counter, nor its time: as before, only its request's.
const every = (['started', 'agent_gone', 'cancelled', 'ambiguous'] as const).flatMap(outcome => said(outcome))
for (const name of every) {
expect(name).toMatch(/^request_phone_message_/)
expect(PRODUCT_USAGE_METRICS).toContain(name)
}
})
it('names a stop the machine could not confirm, rather than unlisted', () => {
// lib/stopAgentService.ts: `agent_delete` is Stop, and STOP_UNCONFIRMED is its own refusal.
const emit = vi.fn()
productUsageRequest('agent_delete', emit, () => 0, 'phone')('STOP_UNCONFIRMED', undefined, false)
const names: string[] = emit.mock.calls.flat()
expect(names).toContain('delete_error_code_stop_unconfirmed')
expect(names).toContain('phone_delete_error_code_stop_unconfirmed')
expect(names.filter(name => name.endsWith('_unlisted'))).toEqual([])
for (const name of names.filter(name => name.includes('error_code_'))) expect(PRODUCT_USAGE_METRICS).toContain(name)
})
it('counts every delete or restart refusal by its code, whatever its kind, so each family adds up to `_failed`', () => {
const emit = vi.fn()
productUsageRequest('agent_delete', emit, () => 0, 'phone')('DELETE_FAILED', undefined, false)
productUsageRequest('agent_delete', emit, () => 0, 'phone')('PRIVATE_ERROR_WITH_PATH', 'failed', false)
productUsageRequest('agent_delete', emit, () => 0, 'phone')({ message: 'PRIVATE_OBJECT' }, undefined, false)
productUsageRequest('agent_delete', emit, () => 0, 'phone')('DELETE_IN_PROGRESS', undefined, false)
productUsageRequest('agent_restart', emit, () => 0, 'phone')('SPAWN_FAILED', undefined, false)
productUsageRequest('agent_restart', emit, () => 0, 'phone')('TMUX_UNAVAILABLE', 'failed', false)
productUsageRequest('agent_restart', emit, () => 0, 'phone')('RESTART_FAILED', 'failed', false)
// Another client's: in the totals, never in the phone's own families.
productUsageRequest('agent_delete', emit, () => 0, 'app')('DELETE_FAILED', undefined, false)
productUsageRequest('agent_restart', emit, () => 0, 'tool')('SPAWN_FAILED', undefined, false)
// Answered without a refusal: no code.
productUsageRequest('agent_delete', emit, () => 0, 'phone')(undefined, undefined, false)
productUsageRequest('agent_restart', emit, () => 0, 'phone')(undefined, 'created', true)
const names: string[] = emit.mock.calls.flat()
const family = (prefix: string) => names.filter(name => name.startsWith(prefix)).sort()
expect(family('delete_error_code_')).toEqual(['delete_error_code_delete_failed', 'delete_error_code_delete_failed',
'delete_error_code_delete_in_progress', 'delete_error_code_none', 'delete_error_code_unlisted'])
expect(names.filter(name => name === 'delete_failed')).toHaveLength(5)
expect(family('restart_error_code_')).toEqual(['restart_error_code_restart_failed', 'restart_error_code_spawn_failed',
'restart_error_code_spawn_failed', 'restart_error_code_tmux_unavailable'])
expect(names.filter(name => name === 'restart_failed')).toHaveLength(4)
// The phone's own: its four delete and three restart refusals, nobody else's.
expect(family('phone_delete_error_code_')).toEqual(['phone_delete_error_code_delete_failed',
'phone_delete_error_code_delete_in_progress', 'phone_delete_error_code_none', 'phone_delete_error_code_unlisted'])
expect(family('phone_restart_error_code_')).toEqual(['phone_restart_error_code_restart_failed',
'phone_restart_error_code_spawn_failed', 'phone_restart_error_code_tmux_unavailable'])
expect(names.filter(name => name === 'restart_error_setup')).toHaveLength(3)
// The phone's own split is kept beside them.
expect(names.filter(name => name === 'request_phone_delete_error_other')).toHaveLength(3)
expect(names).toContain('request_phone_delete_error_conflict')
expect(names.filter(name => name === 'request_phone_restart_error_setup')).toHaveLength(2)
expect(names).toContain('delete_ok')
expect(names).toContain('restart_ok')
for (const name of names) expect(PRODUCT_USAGE_METRICS).toContain(name)
expect(JSON.stringify(names)).not.toContain('PRIVATE_')
})
it('says which engine a new launch asked for, as a fixed name', () => {
const emit = vi.fn()
for (const engine of ['claude', 'codex', 'opencode', 'cursor', 'other', 'PRIVATE_ENGINE', undefined, { name: 'claude' }]) {
productUsageLaunch('agent_create', 'fixture-creation-one', emit, engine)
}
expect(emit.mock.calls.map(([signal]) => signal.engine)).toEqual(['claude', 'codex', 'opencode', 'other', 'other', 'other', 'other', 'other'])
// A status poll is no new launch: it says no engine.
emit.mockClear(); productUsageLaunch('agent_create_status', 'fixture-creation-one', emit, 'claude')
expect(emit).not.toHaveBeenCalled()
})
it('hands a created launch\'s starting agent on for its start, or says its start had already failed', () => {
const emit = vi.fn(), id = 'fixture-creation-one'
const done = (agent: unknown) => productUsageLaunch('agent_create_status', id, emit)(undefined, 'created', agent, undefined)
done({ id: 'fixture-agent', launch: { state: 'starting' }, name: 'PRIVATE_CANARY' })
done({ id: 'fixture-agent', launch: { state: 'failed', error: 'ENGINE_DID_NOT_START', detail: 'PRIVATE_CANARY' } })
done({ id: 'fixture-agent', launch: { state: 'failed', error: 'PRIVATE_CANARY' } })
done({ id: 'fixture-agent', launch: { state: 'ready' } })
done({ id: 'x'.repeat(257), launch: { state: 'starting' } })
done(true)
expect(emit.mock.calls.flat()).toEqual([
{ id, phase: 'created', agent: 'fixture-agent' },
{ id, phase: 'created', late: true, code: 'engine_did_not_start' },
{ id, phase: 'created', late: true, code: 'unlisted' },
{ id, phase: 'created' }, { id, phase: 'created' }, { id, phase: 'created' },
])
expect(JSON.stringify(emit.mock.calls)).not.toContain('PRIVATE_CANARY')
})
it('keeps every refusal core/agents can answer named: in a fixed kind, or in the code list', () => {
// A code missing from both reads as `unlisted` and says nothing again (production counters, 2026-10-16).
const root = fileURLToPath(new URL('../core/agents/', import.meta.url))
const codes = new Set<string>()
for (const name of readdirSync(root)) {
if (!name.endsWith('.ts') || name.endsWith('.spec.ts')) continue
for (const match of readFileSync(join(root, name), 'utf8').matchAll(/error: '([A-Z][A-Z0-9_]*)'/g)) codes.add(match[1])
}
// These helpers answer through core/agents too. Scanning only that directory missed Windows' new
// refusal and every Git worktree refusal (five unlisted launch failures on 2026-10-21).
for (const [path, pattern] of [
['projectFolder.ts', /new (?:ProjectFolderError|RepositoryAccessError)\('([A-Z][A-Z0-9_]*)'/g],
['gitProject.ts', /new GitProjectError\('([A-Z][A-Z0-9_]*)'/g],
['windows/launch.ts', /error: '([A-Z][A-Z0-9_]*)'/g],
] as const) {
for (const match of readFileSync(new URL(path, import.meta.url), 'utf8').matchAll(pattern)) codes.add(match[1])
}
expect(codes.size).toBeGreaterThan(40)
const unnamed = [...codes].filter(code => failureKind(code) === 'other' && launchErrorCode(code) === 'unlisted')
expect(unnamed, 'add each to LAUNCH_ERROR_CODES (lib/productUsageContract.ts and its backend copy)').toEqual([])
// The codes the new-pane watcher sets after a create replied, which no `error: '…'` literal names.
for (const code of ['ENGINE_DID_NOT_START', 'ENGINE_NOT_INSTALLED', 'START_TIMEOUT']) expect(launchErrorCode(code)).toBe(code.toLowerCase())
// A backend's code is selected dynamically (terminalBackend.ts), so it is not an error literal in core.
for (const code of ['TMUX_UNAVAILABLE', 'PTY_HOST_UNAVAILABLE']) expect(launchErrorCode(code)).toBe(code.toLowerCase())
})
it('observes Store, search and model operations without their arguments and rejects explicit false outcomes', () => {
const emit = vi.fn()
productUsageRequest('dsh_install', emit)(undefined, undefined, false, false)
productUsageRequest('session_search', emit)(undefined, undefined, false)
productUsageRequest('grid_fleet_model_download', emit)('TIMEOUT', undefined, false)
expect(emit.mock.calls.flat()).toEqual(expect.arrayContaining([
'store_install_requests', 'store_install_failed', 'search_ok', 'model_download_error_unavailable',
]))
const clock = vi.fn()
productUsageRequest('terminal_input', emit, clock)
expect(clock).not.toHaveBeenCalled()
})
it.each([
// A prerequisite this machine lacks, or the harness's own setup or doctor failing on it.
['SETUP_FAILED', 'setup'], ['DOCTOR_FAILED', 'setup'], ['GIT_UNAVAILABLE', 'setup'], ['SHELL_UNAVAILABLE', 'setup'],
// The package's source could not be reached, or a viewer it needs could not be installed.
['CLONE_FAILED', 'unavailable'], ['VIEWER_UNAVAILABLE', 'unavailable'],
// The package itself, or what was asked of it, is wrong.
['INVALID_MANIFEST', 'invalid'], ['INVALID_SOURCE', 'invalid'], ['SOURCE_NOT_FOUND', 'invalid'],
['PACKAGE_ID_MISMATCH', 'invalid'], ['PACKAGE_KIND_MISMATCH', 'invalid'], ['LINKED_INSTALL', 'invalid'],
['BUNDLED_PACKAGE', 'invalid'], ['DSH_BUSY', 'conflict'], ['NOT_INSTALLED', 'not_found'],
])('gives a Store install or update refused with %s the kind %s, not `other`', (code, kind) => {
const emit = vi.fn()
productUsageRequest('dsh_install', emit, () => 0, 'app')(code, undefined, false)
productUsageRequest('dsh_update', emit, () => 0, 'app')(code, undefined, false)
const names: string[] = emit.mock.calls.flat()
expect(names).toContain(`request_app_store_install_error_${kind}`)
expect(names).toContain(`request_app_store_update_error_${kind}`)
// The detailed counters the prod watch reads; the action totals have five kinds only, `other` among them.
expect(names.filter(name => name.startsWith('request_') && name.endsWith('_error_other'))).toEqual([])
})
// 2026-10-28: 2,225 history page reads from macOS CLI 0.4.97 were `other`, about 12 a minute: a Desktop list re-reading,
// every 5 seconds, a conversation this computer's index no longer held. Its two refusals, as session_tail answers them.
it.each([
[{}, 'invalid', 'invalid'],
[{ sessionId: 'gone-session' }, 'invalid', 'not_found'],
])('counts a history page read refused for %o as %s (%s in detail), not `other`', async (payload, kind, detail) => {
const index = { search: () => { throw new Error('not searched') }, tail: async () => null }
const reply = await searchRequests(index as never).session_tail(payload, { local: false, owner: true, connection: 'c' })
const emit = vi.fn()
productUsageRequest('session_tail', emit, () => 0, 'app')(reply.error, reply.state, false)
const names: string[] = emit.mock.calls.flat()
expect(names).toEqual(expect.arrayContaining(['history_page_failed', `history_page_error_${kind}`,
`request_automatic_history_page_error_${detail}`]))
expect(names.filter(name => name.endsWith('_error_other'))).toEqual([])
})
it('counts a model switch held for an unreadable Swarm role as unavailable, which a retry once the Swarm answers clears', () => {
expect(failureKind('SWARM_ROLE_UNAVAILABLE')).toBe('unavailable')
})
it('keeps every refusal a Store install or update can answer in the code list', () => {
const codes = new Set<string>()
for (const path of ['../dsh/install.ts', '../dsh/update.ts', '../dsh/lock.ts', '../dsh/service.ts', '../services/store.ts']) {
const source = readFileSync(new URL(path, import.meta.url), 'utf8')
for (const match of source.matchAll(/(?:error: |fail\(|code: )'([A-Z][A-Z0-9_]*)'/g)) codes.add(match[1])
}
expect(codes.size).toBeGreaterThan(12)
expect([...codes].filter(code => storeErrorCode(code) === 'unlisted'),
'add each to STORE_ERROR_CODES (lib/productUsageContract.ts and its backend copy)').toEqual([])
// A list of its own: in the launch code list, each would have joined all twelve launch families, where it never
// occurs (+504 names, which pushed the whole-vocabulary report past its test's time).
expect(PRODUCT_USAGE_METRICS).toContain('store_install_error_code_shell_unavailable')
expect(PRODUCT_USAGE_METRICS).not.toContain('create_error_code_shell_unavailable')
})
it('counts every Store install or update refusal by its code, so the family adds up to `_failed`', () => {
// 2026-10-28: 11 Windows installs failed as `other` and the counters could not say which refusal they were.
const emit = vi.fn()
productUsageRequest('dsh_install', emit, () => 0, 'app')('GIT_UNAVAILABLE', undefined, false)
productUsageRequest('dsh_install', emit, () => 0, 'app')('SHELL_UNAVAILABLE', undefined, false)
productUsageRequest('dsh_install', emit, () => 0, 'app')('INTERNAL', undefined, false)
productUsageRequest('dsh_install', emit, () => 0, 'phone')('PRIVATE_ERROR_WITH_PATH', undefined, false)
productUsageRequest('dsh_install', emit, () => 0, 'app')(undefined, undefined, false, false)
productUsageRequest('dsh_update', emit, () => 0, 'app')('UPDATE_FAILED', undefined, false)
// Answered without a refusal: no code.
productUsageRequest('dsh_install', emit, () => 0, 'app')(undefined, undefined, false, true)
productUsageRequest('dsh_remove', emit, () => 0, 'app')('REMOVE_FAILED', undefined, false)
const names: string[] = emit.mock.calls.flat()
const family = (prefix: string) => names.filter(name => name.startsWith(prefix)).sort()
expect(family('store_install_error_code_')).toEqual(['store_install_error_code_git_unavailable', 'store_install_error_code_internal',
'store_install_error_code_none', 'store_install_error_code_shell_unavailable', 'store_install_error_code_unlisted'])
expect(names.filter(name => name === 'store_install_failed')).toHaveLength(5)
expect(family('store_update_error_code_')).toEqual(['store_update_error_code_update_failed'])
expect(family('store_remove_error_code_')).toEqual([])
for (const name of names.filter(name => name.includes('error_code_'))) expect(PRODUCT_USAGE_METRICS).toContain(name)
expect(JSON.stringify(emit.mock.calls)).not.toContain('PRIVATE')
})
it('marks a Store or model list a person opened, and only those', () => {
const emit = vi.fn()
productUsageRequest('dsh_list', emit, Date.now, 'app', true)(undefined, undefined, false)
productUsageRequest('grid_models_list', emit, Date.now, 'app', true)(undefined, undefined, false)
expect(emit.mock.calls.flat()).toEqual(expect.arrayContaining(['store_list_user_requests', 'model_list_user_requests']))
emit.mockClear()
// The Store's minute refresh, the pickers and the previews send no flag; history has no person behind it.
productUsageRequest('dsh_list', emit)(undefined, undefined, false)
productUsageRequest('agent_recent', emit, Date.now, 'app', true)(undefined, undefined, false)
productUsageRequest('session_tail', emit, Date.now, 'app', true)(undefined, undefined, false)
expect(emit.mock.calls.flat().filter(m => String(m).includes('_user_'))).toEqual([])
})
it.each([
['TMUX_UNAVAILABLE', 'runtime_unavailable'], ['NATIVE_LAUNCH_HELD', 'runtime_unavailable'],
['AGENT_NOT_FOUND', 'saved_state_missing'], ['RESUME_UNAVAILABLE', 'saved_state_missing'],
['CWD_NOT_FOUND', 'project_missing'], ['INVALID_DSH', 'harness_missing'],
['GRID_CREDENTIAL_REQUIRED', 'credentials_missing'], ['AGENT_BUSY', 'busy'],
['RESUME_PREPARATION_FAILED', 'preparation_failed'], ['RESUME_FAILED', 'launch_failed'],
['INVALID_PERMISSION_MODE', 'invalid'], ['PRIVATE_ERROR_WITH_PATH', 'other'], ['__proto__', 'other'],
// Fell to `other` until 2026-10-16's counters showed them.
['ENGINE_DID_NOT_START', 'launch_failed'], ['ENGINE_NOT_INSTALLED', 'launch_failed'], ['START_TIMEOUT', 'launch_failed'],
['DELETE_IN_PROGRESS', 'busy'], ['MISSING_AGENT_ID', 'invalid'],
])('reduces resume condition %s to an approved counter without retaining it', (error, reason) => {
const emit = vi.fn(), done = productUsageRequest('agent_resume', emit, () => 0, 'app')
done(error, 'failed', false); done(error, 'failed', false)
const names = emit.mock.calls.flat()
expect(names.filter(name => name.startsWith('request_app_resume_reason_'))).toEqual([`request_app_resume_reason_${reason}`])
expect(names).toContain('request_app_resume_failed')
for (const name of names) expect(PRODUCT_USAGE_METRICS).toContain(name)
expect(JSON.stringify(names)).not.toContain(error)
})
it('counts which check refused a resume\'s preparation, once, by a fixed name', () => {
const counted = (preparation?: unknown) => {
const emit = vi.fn(), done = productUsageRequest('agent_resume', emit, () => 0, 'app')
done('RESUME_PREPARATION_FAILED', undefined, false, false, undefined, preparation)
done('RESUME_PREPARATION_FAILED', undefined, false, false, undefined, preparation)
return emit.mock.calls.flat().filter(name => String(name).startsWith('request_app_resume_preparation_') || name === 'request_app_resume_reason_preparation_failed')
}
expect(counted('invalid_json')).toEqual(['request_app_resume_reason_preparation_failed', 'request_app_resume_preparation_invalid_json'])
expect(counted('/PRIVATE/path')).toEqual(['request_app_resume_reason_preparation_failed', 'request_app_resume_preparation_other'])
expect(counted()).toEqual(['request_app_resume_reason_preparation_failed'])
// Only a preparation failure names a kind: another refusal's reason is not one.
const emit = vi.fn()
productUsageRequest('agent_resume', emit, () => 0, 'app')('AGENT_BUSY', undefined, false, false, undefined, 'invalid_json')
expect(emit.mock.calls.flat().filter(name => String(name).includes('_preparation_'))).toEqual([])
})
it.each([
['RESUME_UNCONFIRMED', undefined, 'unconfirmed', 'unknown'],
[undefined, 'unconfirmed', 'unconfirmed', 'unknown'],
['AGENT_CHANGED', 'failed', 'changed', 'cancelled'],
])('does not call an unverified or superseded resume a failure', (error, state, reason, result) => {
const emit = vi.fn()
productUsageRequest('agent_resume', emit, () => 0, 'tool')(error, state, false)
expect(emit.mock.calls.flat()).toEqual(['resume_requests', 'request_tool_resume_started',
`request_tool_resume_reason_${reason}`, 'resume_unknown', `request_tool_resume_${result}`, 'resume_under_1s'])
})
it('never coerces private reply values and leaves successful resumes without a diagnostic', () => {
const emit = vi.fn(), privateValue = { toString() { throw Error('PRIVATE') } }
expect(() => productUsageRequest('agent_resume', emit, () => 0, 'unknown')(privateValue, privateValue, false)).not.toThrow()
expect(emit.mock.calls.flat()).toContain('request_unknown_resume_reason_other')
emit.mockClear()
productUsageRequest('agent_resume', emit, () => 0, 'app')(undefined, 'created', true)
expect(emit.mock.calls.flat()).toContain('request_app_resume_ok')
expect(emit.mock.calls.flat().some(name => name.includes('_reason_'))).toBe(false)
})
it('names every flow and health measure for hn, and no signed-out setup counter', () => {
const metrics = new Set<string>(PRODUCT_USAGE_METRICS)
for (const flow of PRODUCT_USAGE_FLOWS) for (const measure of ['started', 'ok', 'failed', 'cancelled', 'unknown', 'under_1s', 'over_1m']) {
expect(metrics.has(`ui_tui_${flow}_${measure}`), `${flow}_${measure}`).toBe(true)
}
for (const measure of HEALTH_MEASURES) expect(metrics.has(`health_tui_${measure}`), measure).toBe(true)
expect(PRODUCT_USAGE_SETUP_METRICS.some(metric => metric.includes('_tui_'))).toBe(false)
})
it('reduces hn\'s observations to the Desktop\'s flow and milestone counters, and nothing else', () => {
// Started when it begins, as the Desktop's `begin()` counts it; the outcome alone when it ends.
expect(productObservation({ flow: 'computer_link' })).toEqual(['ui_tui_computer_link_started'])
expect(productObservation({ flow: 'computer_link', outcome: 'ok', durationMs: 999 }))
.toEqual(['ui_tui_computer_link_ok', 'ui_tui_computer_link_under_1s'])
expect(productObservation({ durationMs: 1000, outcome: 'failed', flow: 'remote_connect' }))
.toEqual(['ui_tui_remote_connect_failed', 'ui_tui_remote_connect_1s_to_10s'])
expect(productObservation({ flow: 'resume_recovery', outcome: 'cancelled', durationMs: 59_999 })[1]).toBe('ui_tui_resume_recovery_10s_to_1m')
expect(productObservation({ flow: 'app_start', outcome: 'unknown', durationMs: 60_000 })[1]).toBe('ui_tui_app_start_over_1m')
expect(productObservation({ measure: 'funnel_first_work' })).toEqual(['health_tui_funnel_first_work'])
expect(productObservation({ measure: 'first_response_1m_to_5m' })).toEqual(['health_tui_first_response_1m_to_5m'])
const invalid = [null, undefined, 'sign_in', [], {}, { flow: 'PRIVATE_CANARY', outcome: 'ok', durationMs: 1 },
{ flow: 'sign_in', outcome: 'started', durationMs: 1 }, { flow: 'sign_in', outcome: 'PRIVATE_CANARY', durationMs: 1 },
...[-1, NaN, Infinity, '1', null].map(durationMs => ({ flow: 'sign_in', outcome: 'ok', durationMs })),
{ flow: 'sign_in', outcome: 'ok' }, { flow: 'sign_in', outcome: 'ok', durationMs: 1, path: 'PRIVATE_CANARY' },
{ flow: 'sign_in', durationMs: 1 }, { flow: 'sign_in', path: 'PRIVATE_CANARY' }, { flow: 'PRIVATE_CANARY' }, { flow: 1 },
{ measure: 'PRIVATE_CANARY' }, { measure: 'tui_opens' }, { measure: 'funnel_first_work', agentId: 'PRIVATE_CANARY' },
{ measure: 'funnel_first_work', flow: 'sign_in', outcome: 'ok', durationMs: 1 }, { flow: 'toString', outcome: 'ok', durationMs: 1 },
{ measure: 'constructor' }]
for (const value of invalid) expect(productObservation(value), JSON.stringify(value)).toEqual([])
const all = new Set<string>(PRODUCT_USAGE_METRICS)
for (const flow of PRODUCT_USAGE_FLOWS) {
for (const metric of productObservation({ flow })) expect(all.has(metric), metric).toBe(true)
for (const outcome of ['ok', 'failed', 'cancelled', 'unknown']) {
for (const metric of productObservation({ flow, outcome, durationMs: 0 })) expect(all.has(metric), metric).toBe(true)
}
}
})