@andorra-labs/code 0.0.0-stage → 0.1.5

package/dist/src/telemetry/classify.js

@@ -0,0 +1,252 @@
+/**
+ * Deterministic local classification.
+ *
+ * The ADR replaces free text with closed, locally derived labels: a failure class from the
+ * runtime's own reason, a task category from the tool calls and local path comparisons the run
+ * already made, and a language/framework mix from file extensions and manifest files. Nothing here
+ * reads a prompt, a response, or a file's contents beyond a package manifest, and nothing here
+ * sends a path — the paths are compared and discarded.
+ */
+import { TELEMETRY_FRAMEWORKS, TELEMETRY_LANGUAGES, bucketWorkspaceFiles, } from './schema.js';
+/**
+ * Map a terminal status onto the ADR's total outcome/failure mapping.
+ *
+ * The last `exhausted` row is the important one: the runtime's reason set is not closed, and one
+ * value embeds a user-chosen graph node id. An unrecognized reason degrades to `limit` rather than
+ * being sent as text or rejecting the record.
+ */
+export function classifyOutcome(status, evidence = {}) {
+    if (status === 'succeeded')
+        return { outcome: 'completed' };
+    if (status === 'cancelled')
+        return { outcome: 'cancelled' };
+    if (status === 'needs_clarification')
+        return { outcome: 'needs_clarification' };
+    if (status === 'interrupted')
+        return { outcome: 'interrupted' };
+    if (status === 'exhausted')
+        return { outcome: 'failed', failureClass: exhaustionClass(evidence.reason ?? '') };
+    // Provider failures reach `infrastructure_error`, not a separate status. The structured flag is
+    // what separates them; a classified context overflow is a limit, not a provider failure.
+    if (evidence.providerOverflow)
+        return { outcome: 'failed', failureClass: 'limit' };
+    if (evidence.providerRequestFailed)
+        return { outcome: 'failed', failureClass: 'provider_error' };
+    return { outcome: 'failed', failureClass: 'infrastructure' };
+}
+function exhaustionClass(reason) {
+    if (reason === 'wallTimeMs')
+        return 'timeout';
+    if (reason === 'repeatedToolFailure')
+        return 'tool_error';
+    if (reason === 'maxIterations' || reason === 'maxToolCalls' || reason === 'maxTodoCalls' || reason === 'maxContextChars')
+        return 'limit';
+    // `loop.maxIterations:<nodeId>` and every `... metadata allowance exhausted` reason.
+    if (reason.startsWith('loop.maxIterations:') || reason.includes('metadata allowance exhausted'))
+        return 'limit';
+    // `maxNodeVisits:<nodeId>` is a graph-level exhaustion, also a limit.
+    if (reason.startsWith('maxNodeVisits:'))
+        return 'limit';
+    return 'limit';
+}
+/** Extension table for the language mix. Values not listed are omitted entirely. */
+const LANGUAGE_BY_EXTENSION = {
+    ts: 'typescript', tsx: 'typescript', mts: 'typescript', cts: 'typescript',
+    js: 'javascript', jsx: 'javascript', mjs: 'javascript', cjs: 'javascript',
+    py: 'python', pyi: 'python', go: 'go', rs: 'rust',
+    java: 'java', kt: 'kotlin', kts: 'kotlin', swift: 'swift', cs: 'csharp',
+    cpp: 'cpp', cc: 'cpp', cxx: 'cpp', hpp: 'cpp', hh: 'cpp', hxx: 'cpp',
+    c: 'c', h: 'c',
+    rb: 'ruby', rake: 'ruby', php: 'php', scala: 'scala', sc: 'scala',
+    ex: 'elixir', exs: 'elixir', dart: 'dart',
+    sh: 'shell', bash: 'shell', zsh: 'shell', ksh: 'shell', fish: 'shell',
+    sql: 'sql', html: 'html', htm: 'html', css: 'css', scss: 'css', sass: 'css', less: 'css',
+};
+/** The language a path names, if the table knows its extension. */
+export function languageForPath(filePath) {
+    const name = filePath.slice(filePath.lastIndexOf('/') + 1);
+    const dot = name.lastIndexOf('.');
+    if (dot < 0)
+        return undefined;
+    return LANGUAGE_BY_EXTENSION[name.slice(dot + 1).toLowerCase()];
+}
+const DOCUMENTATION_EXTENSIONS = new Set(['md', 'mdx', 'rst', 'txt', 'adoc']);
+const DOCUMENTATION_BASENAMES = new Set(['license', 'notice', 'changelog']);
+function normalized(filePath) {
+    return filePath.replace(/\\/g, '/').replace(/^\.\//, '');
+}
+/** A documentation path, by extension or by a basename a project uses for the same purpose. */
+export function isDocumentationPath(filePath) {
+    const name = normalized(filePath);
+    const base = name.slice(name.lastIndexOf('/') + 1);
+    const dot = base.lastIndexOf('.');
+    if (dot >= 0 && DOCUMENTATION_EXTENSIONS.has(base.slice(dot + 1).toLowerCase()))
+        return true;
+    return DOCUMENTATION_BASENAMES.has(base.toLowerCase());
+}
+/** A test path: a conventional directory, or a conventional file suffix. */
+export function isTestPath(filePath) {
+    const name = `/${normalized(filePath)}`;
+    if (/\/(?:test|tests|spec|__tests__)\//.test(name))
+        return true;
+    const base = name.slice(name.lastIndexOf('/') + 1);
+    return /\.(?:test|spec)\.[^./]+$/.test(base) || /_test\.[^./]+$/.test(base);
+}
+const TEST_RUNNERS = new Set(['pytest', 'jest', 'vitest', 'ctest']);
+const TEST_COMMAND_PAIRS = new Set(['cargo test', 'go test', 'mvn test', 'gradle test', 'dotnet test']);
+/**
+ * Whether an executed command is a test command.
+ *
+ * Closed for schema version 1: the executable and first argument naming `test`, or one of the
+ * fixed runner names. Changing this list is a schema change.
+ */
+export function isTestCommand(argv) {
+    if (!argv.length)
+        return false;
+    const program = argv[0].slice(argv[0].lastIndexOf('/') + 1).slice(argv[0].lastIndexOf('\\') + 1).toLowerCase();
+    const stripExtension = program.replace(/\.(?:exe|cmd|bat|ps1)$/, '');
+    if (stripExtension === 'test')
+        return true;
+    if (TEST_RUNNERS.has(stripExtension))
+        return true;
+    // `npx vitest`, `pnpm jest`, and the like name the runner as the first argument.
+    if (argv[1] !== undefined && TEST_RUNNERS.has(argv[1].toLowerCase()))
+        return true;
+    if (stripExtension === 'npx' || stripExtension === 'pnpm' || stripExtension === 'yarn' || stripExtension === 'npm' || stripExtension === 'bun') {
+        if (argv[1] === 'test' || argv[1] === 'run' && argv[2] === 'test')
+            return true;
+    }
+    const joined = argv.slice(0, 3).join(' ').toLowerCase();
+    for (const pair of TEST_COMMAND_PAIRS)
+        if (joined.includes(pair))
+            return true;
+    return false;
+}
+/**
+ * Tokenize a shell command line just far enough to recognize a test runner.
+ *
+ * The command is never sent: this runs locally to answer one closed question.
+ */
+export function isTestCommandLine(command) {
+    // A shell line may chain segments (`cd packages/api && npm test`) or pipe them. Inspecting only
+    // the first token of the whole line would let a leading `cd` hide the runner.
+    return command.split(/&&|\|\||[;|]/).some(segment => {
+        const tokens = segment.trim().split(/\s+/).map(token => token.replace(/^['"]|['"]$/g, '')).filter(Boolean);
+        return isTestCommand(tokens);
+    });
+}
+/**
+ * The task category, from the fixed ordered rules.
+ *
+ * `refactor` and `review` are absent because neither is observable without reading the task.
+ */
+export function classifyTaskCategory(evidence) {
+    if (!evidence.hadToolActivity)
+        return undefined;
+    const edited = evidence.editedPaths;
+    if (edited.length === 0 && !evidence.ranTestCommand)
+        return 'investigate';
+    if (edited.length > 0 && edited.every(isDocumentationPath))
+        return 'docs';
+    if ((edited.length > 0 && edited.every(isTestPath)) || (edited.length === 0 && evidence.ranTestCommand))
+        return 'test';
+    if (evidence.createdPaths.length > 0)
+        return 'implement';
+    if (edited.length > 0)
+        return 'fix';
+    return 'investigate';
+}
+const FRAMEWORK_MARKERS = [
+    { file: 'package.json', framework: 'react', pattern: /"(?:react|react-dom)"\s*:/ },
+    { file: 'package.json', framework: 'vue', pattern: /"vue"\s*:/ },
+    { file: 'package.json', framework: 'angular', pattern: /"@angular\/(?:core|cli)"\s*:/ },
+    { file: 'package.json', framework: 'svelte', pattern: /"svelte"\s*:/ },
+    { file: 'package.json', framework: 'nextjs', pattern: /"next"\s*:/ },
+    { file: 'package.json', framework: 'nestjs', pattern: /"@nestjs\/(?:core|common)"\s*:/ },
+    { file: 'package.json', framework: 'express', pattern: /"express"\s*:/ },
+    { file: 'package.json', framework: 'electron', pattern: /"electron"\s*:/ },
+    { file: 'package.json', framework: 'tauri', pattern: /"@tauri-apps\/api"\s*:/ },
+    { file: 'Cargo.toml', framework: 'actix', pattern: /^\s*actix-web\s*=/m },
+    { file: 'Cargo.toml', framework: 'axum', pattern: /^\s*axum\s*=/m },
+    { file: 'Cargo.toml', framework: 'tauri', pattern: /^\s*tauri\s*=/m },
+    { file: 'pyproject.toml', framework: 'fastapi', pattern: /fastapi/i },
+    { file: 'pyproject.toml', framework: 'django', pattern: /django/i },
+    { file: 'pyproject.toml', framework: 'flask', pattern: /flask/i },
+    { file: 'requirements.txt', framework: 'fastapi', pattern: /^\s*fastapi\b/im },
+    { file: 'requirements.txt', framework: 'django', pattern: /^\s*django\b/im },
+    { file: 'requirements.txt', framework: 'flask', pattern: /^\s*flask\b/im },
+    { file: 'go.mod', framework: 'gin', pattern: /gin-gonic\/gin/ },
+    { file: 'pubspec.yaml', framework: 'flutter', pattern: /^\s*flutter\s*:/m },
+    { file: 'pom.xml', framework: 'spring', pattern: /spring-boot/ },
+    { file: 'build.gradle', framework: 'spring', pattern: /spring-boot/ },
+    { file: 'Gemfile', framework: 'rails', pattern: /^\s*gem\s+['"]rails['"]/m },
+    { file: 'composer.json', framework: 'laravel', pattern: /laravel\/framework/ },
+];
+/** Manifest files whose presence is evidence of their own; contents are read only for markers. */
+const MANIFEST_LANGUAGES = {
+    'package.json': 'javascript', 'tsconfig.json': 'typescript', 'Cargo.toml': 'rust', 'go.mod': 'go',
+    'pyproject.toml': 'python', 'setup.py': 'python', 'requirements.txt': 'python', 'pom.xml': 'java',
+    'build.gradle': 'java', 'build.gradle.kts': 'kotlin', 'Gemfile': 'ruby', 'composer.json': 'php',
+    'pubspec.yaml': 'dart', 'mix.exs': 'elixir',
+};
+/**
+ * The language and framework mix, ranked by matching file count with ties in table order, capped at
+ * five distinct values. Unknown values are omitted rather than bucketed, because a workspace whose
+ * mix is unknown reports fewer values rather than a misleading `other`.
+ */
+export function classifyWorkspace(observation) {
+    const counts = new Map();
+    for (const filePath of observation.filePaths) {
+        const language = languageForPath(filePath);
+        if (language)
+            counts.set(language, (counts.get(language) ?? 0) + 1);
+    }
+    for (const manifestPath of Object.keys(observation.manifests)) {
+        const file = manifestPath.split('/').pop() ?? manifestPath;
+        const language = MANIFEST_LANGUAGES[file];
+        if (language && !counts.has(language))
+            counts.set(language, 1);
+    }
+    if (observation.sawCsproj && !counts.has('csharp'))
+        counts.set('csharp', 1);
+    const languages = [...counts.entries()]
+        .sort((a, b) => b[1] - a[1] || TELEMETRY_LANGUAGES.indexOf(a[0]) - TELEMETRY_LANGUAGES.indexOf(b[0]))
+        .slice(0, 5).map(([language]) => language);
+    // How many manifests declare each framework, so the cap keeps the prevalent ones. A Set would
+    // discard that: a monorepo-wide framework could be dropped in favour of one seen once.
+    const frameworks = new Map();
+    for (const marker of FRAMEWORK_MARKERS) {
+        // Any manifest of that name counts, wherever it sits: a workspace's framework is often
+        // declared in a package below a root manifest that says nothing about it.
+        const matches = Object.entries(observation.manifests).filter(([manifestPath, text]) => (manifestPath.split('/').pop() ?? manifestPath) === marker.file && marker.pattern.test(text)).length;
+        if (matches > 0)
+            frameworks.set(marker.framework, (frameworks.get(marker.framework) ?? 0) + matches);
+    }
+    if (observation.sawCsproj)
+        frameworks.set('dotnet', (frameworks.get('dotnet') ?? 0) + 1);
+    const ranked = [...frameworks.entries()]
+        .sort((a, b) => b[1] - a[1] || TELEMETRY_FRAMEWORKS.indexOf(a[0]) - TELEMETRY_FRAMEWORKS.indexOf(b[0]))
+        .slice(0, 5).map(([framework]) => framework);
+    return { languages, frameworks: ranked, workspaceFiles: bucketWorkspaceFiles(observation.totalFiles) };
+}
+/**
+ * The same ordered rules over retained counts.
+ *
+ * This is the form the runtime capture uses: the pictures the rules need are "every edit was
+ * documentation", "every edit was a test", and "an edit created a file", and counts answer all
+ * three without keeping a path.
+ */
+export function classifyTaskCounts(evidence) {
+    if (!evidence.activity)
+        return undefined;
+    const edits = evidence.documentation + evidence.test + evidence.otherEdits;
+    if (edits === 0 && !evidence.testCommand)
+        return 'investigate';
+    if (edits > 0 && evidence.documentation === edits)
+        return 'docs';
+    if ((edits > 0 && evidence.test === edits) || (edits === 0 && evidence.testCommand))
+        return 'test';
+    if (evidence.created > 0)
+        return 'implement';
+    return edits > 0 ? 'fix' : 'investigate';
+}

package/dist/src/telemetry/decision-capture.d.ts

@@ -0,0 +1,13 @@
+/** Request-level attribution, independent of the model/tool telemetry collectors. */
+export interface DecisionCapture {
+    jev: {
+        requested: number;
+        completed: number;
+        applied: number;
+        fallback: number;
+        unavailable: number;
+    };
+    pendingQuestions: number;
+    pendingByInvocation: Record<string, number>;
+}
+export declare function captureDecision(tally: DecisionCapture, type: string, data: Record<string, unknown>): boolean;

package/dist/src/telemetry/decision-capture.js

@@ -0,0 +1,40 @@
+const unavailable = new Set(['provider_unavailable', 'provider_error', 'active_unsupported', 'timeout', 'authentication_required', 'decision_service_unavailable', 'decision_protocol_unsupported', 'decision_input_too_large']);
+export function captureDecision(tally, type, data) {
+    if (!['decision.requested', 'decision.completed', 'decision.applied', 'decision.fallback'].includes(type))
+        return false;
+    const request = typeof data.requestId === 'string' && data.requestId ? `request:${data.requestId}` : undefined;
+    const key = request ?? (typeof data.invocationId === 'string' ? data.invocationId : '');
+    const keyedTotal = () => Object.values(tally.pendingByInvocation).reduce((a, b) => a + b, 0);
+    let legacyPending = Math.max(0, tally.pendingQuestions - keyedTotal());
+    const pending = key ? tally.pendingByInvocation[key] ?? 0 : legacyPending;
+    const settle = () => {
+        if (key)
+            delete tally.pendingByInvocation[key];
+        else
+            legacyPending = 0;
+        tally.pendingQuestions = legacyPending + keyedTotal();
+    };
+    if (type === 'decision.requested') {
+        const count = Array.isArray(data.questions) ? data.questions.length : 0;
+        tally.jev.requested += count;
+        if (key)
+            tally.pendingByInvocation[key] = count;
+        else
+            legacyPending = count;
+        tally.pendingQuestions = legacyPending + keyedTotal();
+    }
+    else if (type === 'decision.completed') {
+        tally.jev.completed += data.decisions && typeof data.decisions === 'object' ? Object.keys(data.decisions).length : 0;
+        settle();
+    }
+    else if (type === 'decision.applied')
+        tally.jev.applied++;
+    else {
+        const count = typeof data.question === 'string' ? 1 : pending;
+        tally.jev.fallback += count;
+        if (unavailable.has(String(data.reason)))
+            tally.jev.unavailable += count;
+        settle();
+    }
+    return true;
+}

package/dist/src/telemetry/emitter.d.ts

@@ -0,0 +1,77 @@
+import { type Config } from '../config.js';
+import { type ClassifiableStatus } from './classify.js';
+import { type RunTelemetry } from './capture.js';
+export type TelemetryDecisionRouting = 'off' | 'shadow' | 'active';
+export interface TelemetryContext {
+    /** The installation home; defaults to the configured one. */
+    home?: string;
+    /** The loaded configuration, when the caller already has it. */
+    config?: Config;
+    /** The signed-in subject, used only to look up the local plan cache. */
+    subject?: string;
+    surface: 'cli' | 'desktop' | 'remote' | 'subagent';
+    /** Names this process's spool; stable for the process's lifetime. */
+    engineId: string;
+}
+export interface RunDimensions {
+    graphId?: string;
+    nodes: number;
+    subagents: boolean;
+    permissionMode?: string;
+    jevEnabled?: boolean;
+    decisionRouting?: string;
+}
+export interface RunFinishInput extends TelemetryContext, RunDimensions {
+    /** The start for this run was queued, so the finish is sent even if the preference changed. */
+    paired?: boolean;
+    /**
+     * The preference generation the start was queued under. A `paired` finish is only sent while
+     * that generation is still current: an opt-out purges the outbox and bumps it, so an older
+     * generation's start is gone and its finish would have nothing to join.
+     */
+    startGeneration?: number;
+    /**
+     * A derived id for a finish that recovery may emit more than once. The ingest is idempotent by
+     * `eventId`, so a re-emission after a crash stores nothing new.
+     */
+    eventId?: string;
+    /** The random telemetry run id, not the persisted run id. */
+    runId: string;
+    startedAt: string;
+    status: ClassifiableStatus;
+    reason?: string;
+    providerRequestFailed?: boolean;
+    providerOverflow?: boolean;
+    /** The runtime's capture, when the surface carried one. */
+    telemetry?: RunTelemetry;
+    /** The workspace root, scanned locally for the language/framework mix. */
+    workspace?: string;
+    /** Totals the surface already knows, used when the runtime capture is absent. */
+    toolCalls?: number;
+    toolFailures?: number;
+    attempts?: number;
+    retries?: number;
+}
+/**
+ * `session.started` is emitted once when a persisted conversation is created — never for a reopen,
+ * a reconnect, an application launch, or per node.
+ */
+export declare function emitSessionStarted(context: TelemetryContext & {
+    workspace?: string;
+}): Promise<void>;
+/** One `run.started` when the run begins, so a run that never finishes is still visible. */
+export declare function emitRunStarted(context: TelemetryContext, input: RunDimensions & {
+    runId: string;
+    eventId?: string;
+}): Promise<number | undefined>;
+/**
+ * The finish repeats the start's dimensions so a finished run is self-describing: a run that
+ * crosses UTC midnight lands its two events in different date partitions, and the dimensions on the
+ * finish are what let every segmented metric be computed from finish records alone.
+ */
+export declare function emitRunFinished(context: TelemetryContext, input: RunFinishInput): Promise<boolean>;
+export declare function emitInterruptedRun(context: TelemetryContext, record: Record<string, unknown>): Promise<boolean>;
+/** The spool this process owns. */
+export declare function engineSpoolId(prefix: string): string;
+/** A home-scoped path helper, so a caller does not have to import the identity module. */
+export declare function telemetryHome(home?: string): string;

package/dist/src/telemetry/emitter.js

@@ -0,0 +1,279 @@
+/**
+ * The telemetry emitter.
+ *
+ * Every event is built field by field from the ADR's inventory. Nothing is spread from an internal
+ * record, so a newly added property on a run record cannot ride along: a field crosses the network
+ * only because a line here names it. That is the primary anonymity guard, and the tests assert the
+ * serialized body rather than the object handed to the queue.
+ *
+ * Emission never fails the work it describes. Each entry point swallows its own errors: telemetry
+ * is optional, and a full disk or an unreadable config must not fail a run.
+ */
+import { createHash } from 'node:crypto';
+import { release } from 'node:os';
+import { configDirectory, loadConfig } from '../config.js';
+import { classifyOutcome, classifyTaskCounts } from './classify.js';
+import { hasRunTelemetry } from './capture.js';
+import { aggregateModelTuples } from './aggregate.js';
+import { ensureInstallId, telemetryDirectory } from './identity.js';
+import { TELEMETRY_PERMISSION_MODES, TELEMETRY_ROUTING, bucketAppVersion, bucketArchitecture, bucketGraph, bucketOperatingSystem, isMetadataTool, telemetryEventId, telemetryTimestamp, validateTelemetryEvent, } from './schema.js';
+import { telemetryGate } from './gate.js';
+import { queueEvent } from './uploader.js';
+import { appVersion } from './version.js';
+import { inspectWorkspace, workspaceShape } from './workspace.js';
+/** The build's operating-system major version, with a bounded fallback. */
+function osMajor() {
+    const match = /^(\d+)/.exec(release());
+    const value = match ? Number(match[1]) : NaN;
+    return Number.isSafeInteger(value) && value >= 0 && value <= 999 ? value : 0;
+}
+function routing(value) {
+    return TELEMETRY_ROUTING.includes(value ?? '') ? value : 'off';
+}
+function permission(value) {
+    return TELEMETRY_PERMISSION_MODES.includes(value ?? '') ? value : 'ask-for-approval';
+}
+function resolvedConfig(context) {
+    return context.config ? Promise.resolve(context.config) : loadConfig(context.home ?? configDirectory());
+}
+/** Build the identity and context fields every event carries. */
+async function identityFor(context, pairedGeneration) {
+    // The preference is read from disk at decision time, not from the caller's startup snapshot:
+    // another process — a CLI in a second terminal, the desktop — may have opted out since this
+    // one started, and a stale snapshot would report one more run against that choice.
+    const config = await loadConfig(context.home ?? configDirectory());
+    const telemetry = telemetryDirectory(context.home ?? configDirectory());
+    const gate = await telemetryGate({ home: context.home, config, subject: context.subject });
+    // A finish whose start is still on the spool under the current generation is sent even when the
+    // preference is now off: suppressing it would leave that start unmatched. The generation check
+    // matters because an opt-out purges the outbox and bumps the generation — a start queued under
+    // the purged generation is gone, so pairing it again would store a finish nothing joins.
+    if (!gate.report && !(pairedGeneration !== undefined && gate.generation === pairedGeneration))
+        return undefined;
+    const installId = await ensureInstallId(telemetry);
+    return {
+        identity: {
+            schema: 1,
+            eventId: telemetryEventId(),
+            installId,
+            ts: telemetryTimestamp(),
+            appVersion: bucketAppVersion(await appVersion()),
+            surface: context.surface,
+            os: bucketOperatingSystem(process.platform),
+            osMajor: osMajor(),
+            arch: bucketArchitecture(process.arch),
+            plan: gate.plan,
+        },
+        generation: gate.generation,
+    };
+}
+async function queue(context, generation, event) {
+    await queueEvent(telemetryDirectory(context.home ?? configDirectory()), context.engineId, generation, validateTelemetryEvent(event));
+}
+/** Never let telemetry's own failure surface to the caller. */
+async function safely(run) {
+    try {
+        await run();
+    }
+    catch { /* Telemetry is optional. */ }
+}
+/** The language and framework mix, when the caller knows the workspace root. */
+async function workspaceMix(root) {
+    if (!root)
+        return {};
+    try {
+        const shape = workspaceShape(await inspectWorkspace(root));
+        return {
+            ...(shape.languages.length ? { languages: shape.languages } : {}),
+            ...(shape.frameworks.length ? { frameworks: shape.frameworks } : {}),
+            workspaceFiles: shape.workspaceFiles,
+        };
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * `session.started` is emitted once when a persisted conversation is created — never for a reopen,
+ * a reconnect, an application launch, or per node.
+ */
+export async function emitSessionStarted(context) {
+    await safely(async () => {
+        const resolved = await identityFor(context);
+        if (!resolved)
+            return;
+        const mix = await workspaceMix(context.workspace);
+        const event = {
+            ...resolved.identity,
+            event: 'session.started',
+            ...(mix.workspaceFiles === undefined ? {} : { workspaceFiles: mix.workspaceFiles }),
+        };
+        await queue(context, resolved.generation, event);
+    });
+}
+/** One `run.started` when the run begins, so a run that never finishes is still visible. */
+export async function emitRunStarted(context, input) {
+    let generation;
+    await safely(async () => {
+        const resolved = await identityFor(context);
+        if (!resolved)
+            return;
+        const config = await resolvedConfig(context);
+        const event = {
+            ...resolved.identity,
+            ...(input.eventId === undefined ? {} : { eventId: input.eventId }),
+            event: 'run.started',
+            runId: input.runId,
+            graph: bucketGraph(input.graphId),
+            nodes: Math.max(0, Math.min(10_000, input.nodes)),
+            subagents: input.subagents,
+            permissionMode: permission(input.permissionMode),
+            jevEnabled: input.jevEnabled ?? config.jevEnabled !== false,
+            decisionRouting: routing(input.decisionRouting ?? config.decisions?.mode),
+        };
+        await queue(context, resolved.generation, event);
+        generation = resolved.generation;
+    });
+    return generation;
+}
+/**
+ * The finish repeats the start's dimensions so a finished run is self-describing: a run that
+ * crosses UTC midnight lands its two events in different date partitions, and the dimensions on the
+ * finish are what let every segmented metric be computed from finish records alone.
+ */
+export async function emitRunFinished(context, input) {
+    let queued = false;
+    await safely(async () => {
+        const resolved = await identityFor(context, input.paired === true ? input.startGeneration : undefined);
+        if (!resolved)
+            return;
+        const config = await resolvedConfig(context);
+        const capture = hasRunTelemetry(input.telemetry) ? input.telemetry : undefined;
+        // A shadow decision request can outlive its node. Waiting here is bounded by the decision
+        // request's own timeout and keeps completion/fallback rates out of run-duration artefacts.
+        if (capture?.pendingDecisions?.length)
+            await Promise.allSettled(capture.pendingDecisions);
+        const outcome = classifyOutcome(input.status, {
+            reason: input.reason,
+            providerRequestFailed: input.providerRequestFailed,
+            providerOverflow: input.providerOverflow ?? capture?.providerOverflow,
+        });
+        const mix = await workspaceMix(input.workspace);
+        const toolCalls = Math.min(capture?.toolCalls ?? input.toolCalls ?? 0, 10_000_000_000_000);
+        const toolFailures = Math.min(capture?.toolFailures ?? input.toolFailures ?? 0, 10_000_000_000_000);
+        // `tools[]` must sum to the totals it accompanies, and only the capture can guarantee that.
+        const tools = capture
+            ? Object.entries(capture.tools)
+                .filter(([name]) => !isMetadataTool(name))
+                .map(([name, counts]) => ({ name: name, calls: counts.calls, failures: counts.failures }))
+                .slice(0, 32)
+            : [];
+        const finished = {
+            ...resolved.identity,
+            ...(input.eventId === undefined ? {} : { eventId: input.eventId }),
+            event: 'run.finished',
+            runId: input.runId,
+            graph: bucketGraph(input.graphId),
+            nodes: Math.max(0, Math.min(10_000, input.nodes)),
+            subagents: input.subagents,
+            permissionMode: permission(input.permissionMode),
+            jevEnabled: input.jevEnabled ?? config.jevEnabled !== false,
+            decisionRouting: routing(input.decisionRouting ?? config.decisions?.mode),
+            outcome: outcome.outcome,
+            ...(outcome.failureClass === undefined ? {} : { failureClass: outcome.failureClass }),
+            durationMs: Math.max(0, Math.min(1_000_000_000_000, Date.now() - Date.parse(input.startedAt) || 0)),
+            // Absent a capture, no node executed: a run that failed in graph loading or model preflight
+            // reports zero attempts rather than one it never made.
+            attempts: capture?.attempts ?? input.attempts ?? 0,
+            retries: capture?.retries ?? input.retries ?? 0,
+            toolCalls,
+            toolFailures,
+            ...(capture && capture.models.length ? { models: aggregateModelTuples(capture.models) } : {}),
+            ...(tools.length ? { tools } : {}),
+            ...(capture ? { jev: { ...capture.jev } } : {}),
+            ...(mix.languages === undefined ? {} : { languages: mix.languages }),
+            ...(mix.frameworks === undefined ? {} : { frameworks: mix.frameworks }),
+            ...(capture ? category(capture) : {}),
+        };
+        await queue(context, resolved.generation, finished);
+        queued = true;
+    });
+    return queued;
+}
+function category(capture) {
+    const value = classifyTaskCounts(capture.task);
+    return value === undefined ? {} : { taskCategory: value };
+}
+/**
+ * The finish for a run whose engine died.
+ *
+ * Recovery finds the open record, marks it interrupted, and hands it here: the telemetry run id and
+ * the start's dimensions were written into that record precisely so the pair can still join.
+ */
+/** A stable id for one recovery event, so a repeated pass cannot store it twice. */
+function recoveryEventId(kind, runId) {
+    const value = createHash('sha256').update(`${kind}:${runId}`).digest('hex').slice(0, 32);
+    // A UUIDv5-shaped string; the schema only requires a UUID, not a particular version.
+    return `${value.slice(0, 8)}-${value.slice(8, 12)}-${value.slice(12, 16)}-${value.slice(16, 20)}-${value.slice(20, 32)}`;
+}
+export async function emitInterruptedRun(context, record) {
+    const telemetry = record.telemetry;
+    if (!telemetry || typeof telemetry.runId !== 'string')
+        return false;
+    // Each surface records the mode where its open record already keeps it: the CLI under
+    // `telemetry.permissions`, the app-server under `telemetry.permissionMode`. Reading only the
+    // top level loses it for both, so a recovered `full-access` run is reported as unstated.
+    const permissionMode = typeof record.permissions === 'string' ? record.permissions
+        : typeof telemetry.permissions === 'string' ? telemetry.permissions
+            : typeof telemetry.permissionMode === 'string' ? telemetry.permissionMode : undefined;
+    const startedAt = typeof record.startedAt === 'string' ? record.startedAt : new Date().toISOString();
+    const graph = record.graph && typeof record.graph === 'object' ? record.graph.id : undefined;
+    const nodes = typeof telemetry.nodes === 'number' ? telemetry.nodes : 1;
+    // A record written before its start was queued (the process died during graph resolution) would
+    // otherwise leave a finish with no start. Only an explicit `false` means the start was never
+    // queued: older records and the CLI/subagent paths omit the flag and have already emitted one.
+    if (telemetry.startSent === false) {
+        const started = await emitRunStarted(context, {
+            ...context,
+            runId: telemetry.runId,
+            // The record still says `startSent: false` when this process dies before the finish is
+            // queued, so a later pass synthesizes this start again: the derived id makes that a no-op
+            // instead of a second start for the same run.
+            eventId: recoveryEventId('start', telemetry.runId),
+            graphId: typeof graph === 'string' ? graph : undefined,
+            nodes,
+            subagents: telemetry.subagents === true,
+            permissionMode,
+            jevEnabled: telemetry.jevEnabled === true,
+            decisionRouting: typeof telemetry.decisionRouting === 'string' ? telemetry.decisionRouting : undefined,
+        });
+        // The finish must not land without the start it synthesizes: a transient enqueue failure that
+        // clears before the finish is queued would store an unmatched finish, and the caller would
+        // clear the pending marker on the strength of it.
+        if (started === undefined)
+            return false;
+    }
+    // The return value is what lets recovery keep its pending marker until the finish is really on
+    // the spool: a full disk or a busy lock suppresses the exception, so "no throw" is not "queued".
+    return emitRunFinished(context, {
+        ...context,
+        runId: telemetry.runId,
+        eventId: recoveryEventId('interrupted', telemetry.runId),
+        startedAt,
+        status: 'interrupted',
+        graphId: typeof graph === 'string' ? graph : undefined,
+        nodes,
+        subagents: telemetry.subagents === true,
+        permissionMode,
+        jevEnabled: telemetry.jevEnabled === true,
+        decisionRouting: typeof telemetry.decisionRouting === 'string' ? telemetry.decisionRouting : undefined,
+    });
+}
+/** The spool this process owns. */
+export function engineSpoolId(prefix) {
+    return `${prefix}-${process.pid}-${Math.random().toString(36).slice(2, 10)}`;
+}
+/** A home-scoped path helper, so a caller does not have to import the identity module. */
+export function telemetryHome(home) {
+    return telemetryDirectory(home ?? configDirectory());
+}