@reticlehq/server 3.8.2 → 3.9.0

package/dist/telemetry/argument-shape.js

@@ -18,7 +18,7 @@
  * exact values allowed — anything outside the list is reported as `other`, so a schema change can
  * never quietly start forwarding free text.
  */
-import { ActionType, FeedbackKind, QueryBy, SnapshotMode } from '@reticlehq/core';
+import { ActionType, FeedbackKind, QueryBy, ReticleTool, SnapshotMode } from '@reticlehq/core';
 /**
  * Parameters whose values are enums WE define, and the exact values allowed on the wire. An
  * unrecognized value reports `other` rather than itself; that fallback is what makes this safe
@@ -35,6 +35,9 @@ const SAFE_ENUM_PARAMS = new Map([
     ['by', new Set(Object.values(QueryBy))],
     ['mode', new Set(Object.values(SnapshotMode))],
     ['kind', new Set(Object.values(FeedbackKind))],
+    // `reticle_run { tool }` names the tool it calls. Our own tool names, so the session summary can
+    // say which tools agents reach through it. A name that is not a Reticle tool reports `other`.
+    ['tool', new Set(Object.values(ReticleTool))],
     // `level` has no core enum — console levels come from the DOM console API, not from us. Listed
     // literally BECAUSE there is nothing to derive from, which is a different situation from the four
     // above and the reason it is called out rather than left looking like an oversight.
@@ -49,10 +52,12 @@ export const OTHER_VALUE = 'other';
  */
 export function allowParamValues(name, values) {
     const allowed = SAFE_ENUM_PARAMS.get(name);
-    if (allowed === undefined)
+    if (allowed === undefined) {
         return;
-    for (const value of values)
+    }
+    for (const value of values) {
         allowed.add(value);
+    }
 }
 /**
  * The reportable form of one parameter: `name` on its own, or `name:value` when the parameter is a
@@ -60,10 +65,12 @@ export function allowParamValues(name, values) {
  */
 export function describeParam(name, value) {
     const allowed = SAFE_ENUM_PARAMS.get(name);
-    if (allowed === undefined)
+    if (allowed === undefined) {
         return name;
-    if (typeof value !== 'string')
+    }
+    if (typeof value !== 'string') {
         return name;
+    }
     return `${name}:${allowed.has(value) ? value : OTHER_VALUE}`;
 }
 /**
@@ -96,10 +103,12 @@ export function describeCliFlags(argv) {
     const flags = new Set();
     for (const arg of argv) {
         // A bare `--` ends the options: everything after it is passed through to something else.
-        if (END_OF_OPTIONS === arg)
+        if (END_OF_OPTIONS === arg) {
             break;
-        if (!arg.startsWith('--'))
+        }
+        if (!arg.startsWith('--')) {
             continue;
+        }
         // `--port=9000` — split so the NAME is reported and the value is discarded with everything else.
         const name = arg.split('=')[0] ?? arg;
         flags.add(KNOWN_CLI_FLAGS.has(name) ? name : OTHER_VALUE);

package/dist/telemetry/cli-telemetry.d.ts

@@ -4,7 +4,8 @@
  * Lives in its own module so `cli.ts` stays a dispatcher, and so the `_daemon` exclusion below sits
  * next to the explanation of why it exists rather than buried in a startup function.
  */
-import { TelemetryActor } from '@reticlehq/core/telemetry';
+import { TelemetryActor, type GateCompleted } from '@reticlehq/core/telemetry';
+import { type Telemetry } from './telemetry.js';
 /** True when this command represents a person typing something. Exported for the gate. */
 export declare function isHumanCliCommand(command: string): boolean;
 /**
@@ -23,3 +24,11 @@ export declare function cliActorOf(env: NodeJS.ProcessEnv): TelemetryActor;
  */
 export declare function claimInstallReport(command: string, firstRun: boolean, stateDir: string): boolean;
 export declare function reportCliRun(argv: readonly string[]): void;
+/**
+ * `gate_completed`: how one `reticle gate` run ended.
+ *
+ * `cli_command_run` says that the gate ran. Only this event says whether it passed. The gate is a
+ * one-shot command that exits immediately, so the send is DETACHED, like `init_completed`.
+ * Best-effort: a metric never changes what the gate decides.
+ */
+export declare function reportGateCompleted(gate: GateCompleted, telemetry?: Pick<Telemetry, 'emit'>): void;

package/dist/telemetry/cli-telemetry.js

@@ -161,3 +161,18 @@ export function reportCliRun(argv) {
         flags: describeCliFlags(argv),
     });
 }
+/**
+ * `gate_completed`: how one `reticle gate` run ended.
+ *
+ * `cli_command_run` says that the gate ran. Only this event says whether it passed. The gate is a
+ * one-shot command that exits immediately, so the send is DETACHED, like `init_completed`.
+ * Best-effort: a metric never changes what the gate decides.
+ */
+export function reportGateCompleted(gate, telemetry = getTelemetry()) {
+    try {
+        void telemetry.emit(TelemetryEventKind.GATE_COMPLETED, { gate, detach: true });
+    }
+    catch {
+        /* a metric never fails the gate */
+    }
+}

package/dist/telemetry/init-telemetry.d.ts

@@ -11,6 +11,7 @@
  * event loop alive and tax the command by most of a second.
  */
 import { type InitOutcome } from '@reticlehq/core/telemetry';
-export { InitFailure } from '@reticlehq/init';
+import { InitFailure } from '@reticlehq/init';
+export { InitFailure };
 /** Report one init outcome. Best-effort; setup must never fail because a metric did. */
 export declare function reportInitOutcome(init: InitOutcome): void;

package/dist/telemetry/init-telemetry.js

@@ -10,12 +10,56 @@
  * same treatment `cli_command_run` gets, for the same reason: an in-process fetch would keep the
  * event loop alive and tax the command by most of a second.
  */
-import { TelemetryEventKind } from '@reticlehq/core/telemetry';
+import { OnboardingPhase, OnboardingStop, TelemetryEventKind, } from '@reticlehq/core/telemetry';
+import { InitFailure } from '@reticlehq/init';
 import { getTelemetry } from './telemetry.js';
 import { INSTALL_STATE_DIR, resolveInstallSource } from './install-source.js';
+import { reportOnboardingStop } from './onboarding-funnel.js';
 // The failure vocabulary lives in `@reticlehq/init`, which is what classifies a failed run.
 // Re-exported so every consumer here is unchanged.
-export { InitFailure } from '@reticlehq/init';
+export { InitFailure };
+const PROJECT_DETECTED = 'project_detected';
+const INSTRUMENTED = 'instrumented';
+const APP_CONNECTED = 'app_connected';
+/**
+ * Each init failure as one stop, with the first-run step it blocked. A `Record` over the whole
+ * enum, so a new `InitFailure` does not compile until it names its stop.
+ */
+const INIT_STOP = {
+    [InitFailure.NO_PACKAGE_JSON]: { step: PROJECT_DETECTED, stop: OnboardingStop.NO_WEB_APP },
+    [InitFailure.MALFORMED_PACKAGE_JSON]: {
+        step: PROJECT_DETECTED,
+        stop: OnboardingStop.SETUP_FAILED,
+    },
+    [InitFailure.PREFLIGHT]: { step: PROJECT_DETECTED, stop: OnboardingStop.SETUP_FAILED },
+    [InitFailure.DEPENDENCY_INSTALL]: { step: INSTRUMENTED, stop: OnboardingStop.SETUP_FAILED },
+    [InitFailure.MCP_REGISTRATION]: { step: INSTRUMENTED, stop: OnboardingStop.MCP_NOT_REGISTERED },
+    [InitFailure.OTHER]: { step: INSTRUMENTED, stop: OnboardingStop.UNCLASSIFIED },
+    [InitFailure.BRIDGE_OCCUPIED]: { step: APP_CONNECTED, stop: OnboardingStop.SETUP_FAILED },
+    [InitFailure.DEV_SERVER]: { step: APP_CONNECTED, stop: OnboardingStop.DEV_SERVER_FAILED },
+    [InitFailure.APP_CONNECTION]: { step: APP_CONNECTED, stop: OnboardingStop.APP_NOT_CONNECTED },
+    [InitFailure.RUNTIME_ERROR]: { step: APP_CONNECTED, stop: OnboardingStop.UNCLASSIFIED },
+    [InitFailure.INTERRUPTED]: { step: APP_CONNECTED, stop: OnboardingStop.INTERRUPTED },
+};
+const INIT_STOP_UNKNOWN = INIT_STOP[InitFailure.OTHER];
+function initStop(reason) {
+    if (reason !== undefined && Object.hasOwn(INIT_STOP, reason)) {
+        return INIT_STOP[reason];
+    }
+    return INIT_STOP_UNKNOWN;
+}
+/** The stop row of a failed init, or nothing for a run that worked. */
+function reportInitStop(init) {
+    if (init.ok) {
+        return;
+    }
+    reportOnboardingStop({
+        phase: OnboardingPhase.FIRST_RUN,
+        ...initStop(init.reason),
+        ...(init.reason === undefined ? {} : { reason: init.reason }),
+        ...(init.stack === undefined ? {} : { stack: init.stack }),
+    }, { detach: true });
+}
 /** Report one init outcome. Best-effort; setup must never fail because a metric did. */
 export function reportInitOutcome(init) {
     try {
@@ -27,6 +71,7 @@ export function reportInitOutcome(init) {
             // marker, same refusal to infer — see install-source.ts.
             installSource: resolveInstallSource(process.env, INSTALL_STATE_DIR),
         });
+        reportInitStop(init);
     }
     catch {
         /* a metric must never break `reticle init` */

package/dist/telemetry/install-trace.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
-import { OnboardingStepSchema } from '@reticlehq/core/telemetry';
+import { OnboardingStepSchema, OnboardingStop } from '@reticlehq/core/telemetry';
 import { reportOnboardingStep } from './onboarding-funnel.js';
 /**
  * What the one-line installer could not report itself.
@@ -27,6 +27,22 @@ const TRACE_FILE = 'install-trace.jsonl';
  * file must not turn into thousands of events. Far above any real install, which writes three.
  */
 const MAX_LINES = 32;
+/**
+ * The stop that each installer failure reason names. The keys are the reasons that `install.sh`
+ * and `install.ps1` write. A reason not in this table gets no stop.
+ */
+const INSTALLER_STOP = {
+    no_node: OnboardingStop.NO_NODE,
+    node_too_old: OnboardingStop.NODE_TOO_OLD,
+    no_npm: OnboardingStop.CLI_INSTALL_FAILED,
+    npm_install: OnboardingStop.CLI_INSTALL_FAILED,
+    not_on_path: OnboardingStop.CLI_INSTALL_FAILED,
+};
+function installerStop(reason) {
+    return reason !== undefined && Object.hasOwn(INSTALLER_STOP, reason)
+        ? INSTALLER_STOP[reason]
+        : undefined;
+}
 /**
  * Drain the installer's breadcrumbs, once.
  *
@@ -36,8 +52,9 @@ const MAX_LINES = 32;
  */
 export function drainInstallTrace(stateDir) {
     const path = join(stateDir, TRACE_FILE);
-    if (!existsSync(path))
+    if (!existsSync(path)) {
         return 0;
+    }
     let drained = 0;
     try {
         const lines = readFileSync(path, 'utf8')
@@ -55,9 +72,11 @@ export function drainInstallTrace(stateDir) {
             // deliberate belt-and-braces: this is the one path where the payload is a file a person can
             // edit, and rule 3 is that unvalidated text never reaches the wire.
             const step = OnboardingStepSchema.safeParse(parsed);
-            if (!step.success)
+            if (!step.success) {
                 continue;
-            void reportOnboardingStep(step.data);
+            }
+            const stop = installerStop(step.data.reason);
+            void reportOnboardingStep({ ...step.data, ...(stop === undefined ? {} : { stop }) });
             drained += 1;
         }
     }

package/dist/telemetry/onboarding-funnel.d.ts

@@ -1,4 +1,4 @@
-import { OnboardingPhase, type OnboardingStep } from '@reticlehq/core/telemetry';
+import { OnboardingPhase, type OnboardingStep, type OnboardingStop } from '@reticlehq/core/telemetry';
 /**
  * The one place an onboarding step is reported.
  *
@@ -11,7 +11,24 @@ import { OnboardingPhase, type OnboardingStep } from '@reticlehq/core/telemetry'
  * arriving as a step name would be a rule-3 leak that no reader would ever notice, because a funnel
  * with one weird row still renders.
  */
-export declare function reportOnboardingStep(step: OnboardingStep): Promise<boolean>;
+export declare function reportOnboardingStep(step: OnboardingStep, opts?: {
+    detach?: boolean;
+}): Promise<boolean>;
+/** One stop: the rung it blocked and its name. The status is always `failed`. */
+export type StopRow = Omit<OnboardingStep, 'status' | 'stop'> & {
+    stop: OnboardingStop;
+};
+/**
+ * Report one stop on the path to a first verdict, once for each process and stop name.
+ *
+ * A daemon can fail to launch Chromium on every lease. One row says the stop happened here; more
+ * rows count retries, not people. Use `detach` from a CLI that exits next, or the row is lost.
+ */
+export declare function reportOnboardingStop(row: StopRow, opts?: {
+    detach?: boolean;
+}): void;
+/** Tests only: forget the stops this process sent. */
+export declare function resetOnboardingStops(): void;
 /**
  * Time a step and report it, whatever happens to it.
  *

package/dist/telemetry/onboarding-funnel.js

@@ -12,13 +12,35 @@ import { getTelemetry } from './telemetry.js';
  * arriving as a step name would be a rule-3 leak that no reader would ever notice, because a funnel
  * with one weird row still renders.
  */
-export async function reportOnboardingStep(step) {
+export async function reportOnboardingStep(step, opts = {}) {
     const parsed = OnboardingStepSchema.safeParse(step);
     // A malformed step is DROPPED rather than sent or thrown. Sending it would put unvalidated text on
     // the wire; throwing would let a metric change what the user's install does, which rule 5 forbids.
-    if (!parsed.success)
+    if (!parsed.success) {
         return false;
-    return getTelemetry().emit(TelemetryEventKind.ONBOARDING_STEP, { onboarding: parsed.data });
+    }
+    return getTelemetry().emit(TelemetryEventKind.ONBOARDING_STEP, {
+        onboarding: parsed.data,
+        ...(true === opts.detach ? { detach: true } : {}),
+    });
+}
+const stopsSent = new Set();
+/**
+ * Report one stop on the path to a first verdict, once for each process and stop name.
+ *
+ * A daemon can fail to launch Chromium on every lease. One row says the stop happened here; more
+ * rows count retries, not people. Use `detach` from a CLI that exits next, or the row is lost.
+ */
+export function reportOnboardingStop(row, opts = {}) {
+    if (stopsSent.has(row.stop)) {
+        return;
+    }
+    stopsSent.add(row.stop);
+    void reportOnboardingStep({ ...row, status: OnboardingStepStatus.FAILED }, opts);
+}
+/** Tests only: forget the stops this process sent. */
+export function resetOnboardingStops() {
+    stopsSent.clear();
 }
 /**
  * Time a step and report it, whatever happens to it.

package/dist/telemetry/proxy-telemetry.d.ts

@@ -10,6 +10,7 @@
  * never arrived: the POST was killed every time and nothing threw.
  */
 import { type ProxyExitReason, type WakeRefusalPresence } from '@reticlehq/core/telemetry';
+import type { DaemonDeath } from '@reticlehq/core';
 import { type SessionMetrics } from './session-metrics.js';
 import { type Telemetry } from './telemetry.js';
 export declare function flushProxySessionMetrics(telemetry?: Telemetry, metrics?: SessionMetrics): Promise<void>;
@@ -37,7 +38,7 @@ export declare function reportProxyExited(reason: ProxyExitReason, telemetry?: T
 /** Everything the proxy sends on its way out. Awaited, then the caller exits. */
 export declare function flushProxyExit(reason: ProxyExitReason): Promise<void>;
 /** Send `daemon_died_unclean`. Fire-and-forget is fine for callers: the process lives on. */
-export declare function reportDaemonDiedUnclean(ageMs: number, telemetry?: Telemetry): Promise<void>;
+export declare function reportDaemonDiedUnclean(ageMs: number, cause?: Omit<DaemonDeath, 'ageMs'>, telemetry?: Telemetry): Promise<void>;
 /**
  * Send `wake_refused`, once per process. A dormant proxy refuses again on every client request, and
  * one event per request would count the client's retries, not the refusal.

package/dist/telemetry/proxy-telemetry.js

@@ -73,9 +73,9 @@ export async function flushProxyExit(reason) {
     await Promise.allSettled([flushProxySessionMetrics(), reportProxyExited(reason)]);
 }
 /** Send `daemon_died_unclean`. Fire-and-forget is fine for callers: the process lives on. */
-export async function reportDaemonDiedUnclean(ageMs, telemetry = getTelemetry()) {
+export async function reportDaemonDiedUnclean(ageMs, cause, telemetry = getTelemetry()) {
     await telemetry.emit(TelemetryEventKind.DAEMON_DIED_UNCLEAN, {
-        daemonDeath: { ageMs: Math.max(0, Math.round(ageMs)) },
+        daemonDeath: { ...cause, ageMs: Math.max(0, Math.round(ageMs)) },
     });
 }
 /**

package/dist/telemetry/session-metrics.d.ts

@@ -15,7 +15,7 @@
  * URLs, no error messages — the accumulator has no way to hold them, which is a stronger guarantee
  * than a rule saying it shouldn't.
  */
-import { BrowserLaunchKind, type AgentNudgeKind, type ConnectFailure, type SessionSummary } from '@reticlehq/core/telemetry';
+import { BrowserLaunchKind, ConnectFailure, type AgentNudgeKind, type SessionSummary } from '@reticlehq/core/telemetry';
 import type { HudUseData } from '@reticlehq/core';
 import { type HudSignals } from './hud-metrics.js';
 /**

package/dist/telemetry/session-metrics.js

@@ -15,12 +15,13 @@
  * URLs, no error messages — the accumulator has no way to hold them, which is a stronger guarantee
  * than a rule saying it shouldn't.
  */
-import { BrowserLaunchKind, } from '@reticlehq/core/telemetry';
+import { BrowserLaunchKind, ConnectFailure, OnboardingPhase, OnboardingStop, } from '@reticlehq/core/telemetry';
 import { errorSkeleton, fingerprintError } from './error-fingerprint.js';
 import { describeToolParams } from './argument-shape.js';
 import { machineSnapshot } from './machine-snapshot.js';
 import { classifyError } from './error-class.js';
 import { HudMetrics } from './hud-metrics.js';
+import { reportOnboardingStop } from './onboarding-funnel.js';
 import { releaseVersionOf } from '../command/update/version-seen.js';
 /** Cap the distinct error shapes held in memory — a pathological loop must not grow unbounded. */
 const MAX_ERROR_KINDS = 40;
@@ -58,6 +59,12 @@ const BREADCRUMB_LENGTH = 12;
  * never fires for the sessions that need it most.
  */
 const UNVERIFIED_ACTION_NUDGE_AT = 3;
+/** The launch failures that leave no browser to drive: a stop on the path to a first verdict. */
+const CHROMIUM_UNAVAILABLE = new Set([
+    ConnectFailure.CHROMIUM_MISSING,
+    ConnectFailure.PLAYWRIGHT_MISSING,
+]);
+const DRIVEN_STEP = 'driven';
 /**
  * Mutable counters for one daemon lifetime. A plain class, not a store: it is process-local, it never
  * persists, and it dies with the daemon.
@@ -187,10 +194,12 @@ export class SessionMetrics {
     }
     /** A tab went into the background (true) or came back (false): its HUD time pauses meanwhile. */
     setHudTabHidden(tab, hidden) {
-        if (hidden)
+        if (hidden) {
             this.#hud.hide(tab);
-        else
+        }
+        else {
             this.#hud.show(tab);
+        }
     }
     /** A tab went away: its HUD stops accruing time. */
     closeHudTab(tab) {
@@ -204,12 +213,14 @@ export class SessionMetrics {
     startToolCall(tool, args) {
         this.recordToolCall(tool, args);
         this.#concurrent += 1;
-        if (this.#concurrent > this.#peakConcurrent)
+        if (this.#concurrent > this.#peakConcurrent) {
             this.#peakConcurrent = this.#concurrent;
+        }
         let settled = false;
         return (durationMs) => {
-            if (settled)
-                return; // a double-settle would corrupt the concurrency count
+            if (settled) {
+                return;
+            } // a double-settle would corrupt the concurrency count
             settled = true;
             this.#concurrent = Math.max(0, this.#concurrent - 1);
             this.#busyMs += durationMs;
@@ -243,8 +254,9 @@ export class SessionMetrics {
      */
     recordUnknownTool(name) {
         this.#unknownToolCalls += 1;
-        if (name === undefined || 0 === name.length)
+        if (name === undefined || 0 === name.length) {
             return;
+        }
         const key = name.slice(0, 64);
         const seen = this.#unknownTools.get(key);
         if (seen !== undefined) {
@@ -253,8 +265,9 @@ export class SessionMetrics {
         }
         // Stop growing once full: a pathological loop must not balloon the payload. The head is what
         // gets built; the tail is noise.
-        if (this.#unknownTools.size >= MAX_ERROR_KINDS)
+        if (this.#unknownTools.size >= MAX_ERROR_KINDS) {
             return;
+        }
         this.#unknownTools.set(key, 1);
     }
     recordToolCall(tool, args) {
@@ -269,8 +282,9 @@ export class SessionMetrics {
         if (this.#currentRun > 1) {
             const best = this.#repeatRuns.get(tool) ?? 0;
             if (this.#currentRun > best &&
-                (this.#repeatRuns.has(tool) || this.#repeatRuns.size < MAX_REPEAT_TOOLS))
+                (this.#repeatRuns.has(tool) || this.#repeatRuns.size < MAX_REPEAT_TOOLS)) {
                 this.#repeatRuns.set(tool, this.#currentRun);
+            }
         }
         this.#toolCalls += 1;
         this.#lifetimeToolCalls += 1;
@@ -280,23 +294,27 @@ export class SessionMetrics {
         bump(this.#toolCounts, tool);
         this.#inFlight = tool;
         this.#breadcrumb.push(tool);
-        if (this.#breadcrumb.length > BREADCRUMB_LENGTH)
+        if (this.#breadcrumb.length > BREADCRUMB_LENGTH) {
             this.#breadcrumb.shift();
-        if (args === undefined)
+        }
+        if (args === undefined) {
             return;
+        }
         // Which PARAMETERS get used, per tool — names only (plus a short allowlist of our own enums).
         // Bounded by our own schemas: a tool has a fixed handful of declared parameters, so this map
         // cannot grow with traffic the way a value-carrying one would.
         let perTool = this.#toolParams.get(tool);
         if (perTool === undefined) {
-            if (this.#toolParams.size >= MAX_PARAM_TOOLS)
+            if (this.#toolParams.size >= MAX_PARAM_TOOLS) {
                 return;
+            }
             perTool = new Map();
             this.#toolParams.set(tool, perTool);
         }
         for (const param of describeToolParams(args)) {
-            if (perTool.size < MAX_PARAMS_PER_TOOL || perTool.has(param))
+            if (perTool.size < MAX_PARAMS_PER_TOOL || perTool.has(param)) {
                 bump(perTool, param);
+            }
         }
     }
     /**
@@ -310,8 +328,9 @@ export class SessionMetrics {
         // indistinguishable from the rest inside one `toolErrors` count.
         bump(this.#errorClasses, classifyError(message));
         this.#currentCallErrored = true;
-        if (NO_SESSION_ERROR.test(message))
+        if (NO_SESSION_ERROR.test(message)) {
             this.#noSessionErrors += 1;
+        }
         const fingerprint = fingerprintError(message);
         const existing = this.#errorKinds.get(fingerprint);
         if (existing !== undefined) {
@@ -319,8 +338,9 @@ export class SessionMetrics {
             return;
         }
         // Stop growing once the cap is hit; the tail is noise and the head is what gets fixed.
-        if (this.#errorKinds.size >= MAX_ERROR_KINDS)
+        if (this.#errorKinds.size >= MAX_ERROR_KINDS) {
             return;
+        }
         this.#errorKinds.set(fingerprint, {
             fingerprint,
             count: 1,
@@ -343,8 +363,9 @@ export class SessionMetrics {
             existing.count += 1;
             return;
         }
-        if (this.#sdkFailureKinds.size >= MAX_ERROR_KINDS)
+        if (this.#sdkFailureKinds.size >= MAX_ERROR_KINDS) {
             return;
+        }
         this.#sdkFailureKinds.set(fingerprint, {
             fingerprint,
             count: 1,
@@ -428,8 +449,9 @@ export class SessionMetrics {
     /** The 1-based occurrence of this finding in the session, or undefined past the cap. */
     recordBugOccurrence(fingerprint) {
         const seen = this.#bugOccurrences.get(fingerprint);
-        if (seen === undefined && this.#bugOccurrences.size >= MAX_BUG_FINGERPRINTS)
+        if (seen === undefined && this.#bugOccurrences.size >= MAX_BUG_FINGERPRINTS) {
             return undefined;
+        }
         const occurrence = (seen ?? 0) + 1;
         this.#bugOccurrences.set(fingerprint, occurrence);
         return occurrence;
@@ -437,8 +459,9 @@ export class SessionMetrics {
     recordBug(kind) {
         this.#bugsFound += 1;
         this.#lifetimeBugsFound += 1;
-        if (this.#bugKinds.size < MAX_ERROR_KINDS || this.#bugKinds.has(kind))
+        if (this.#bugKinds.size < MAX_ERROR_KINDS || this.#bugKinds.has(kind)) {
             bump(this.#bugKinds, kind);
+        }
         const first = !this.#seenBugKinds.has(kind);
         this.#seenBugKinds.add(kind);
         return first;
@@ -457,8 +480,9 @@ export class SessionMetrics {
         this.#connections.set(kind, stats);
         let settled = false;
         return (failure) => {
-            if (settled)
+            if (settled) {
                 return;
+            }
             settled = true;
             if (failure === undefined) {
                 stats.successes += 1;
@@ -466,12 +490,21 @@ export class SessionMetrics {
             }
             stats.failures ??= {};
             stats.failures[failure] = (stats.failures[failure] ?? 0) + 1;
+            if (CHROMIUM_UNAVAILABLE.has(failure)) {
+                reportOnboardingStop({
+                    phase: OnboardingPhase.FIRST_RUN,
+                    step: DRIVEN_STEP,
+                    reason: failure,
+                    stop: OnboardingStop.CHROMIUM_UNAVAILABLE,
+                });
+            }
         };
     }
     recordClient(name, version) {
         const key = name.slice(0, 64);
-        if (this.#clients.size < MAX_CLIENTS)
+        if (this.#clients.size < MAX_CLIENTS) {
             this.#clients.add(key);
+        }
         // The version was already in the handshake and was being dropped. A regression in agent
         // behaviour is usually a client version, and without this it is unattributable.
         if (version !== undefined && '' !== version && this.#clientVersions.size < MAX_CLIENTS) {
@@ -511,8 +544,9 @@ export class SessionMetrics {
     summarize(final, exit) {
         // The last call has no successor to resolve it, so resolve it here. Only on a FINAL summary:
         // a periodic flush is not the end of anything and would resolve a call still in flight.
-        if (final)
+        if (final) {
             this.#resolveRecovery();
+        }
         const machine = machineSnapshot();
         // EVERY event reports its own window, the final one included: summing a session's
         // `session_progress` + `daemon_stopped` rows is then its total. The final event used to swap in
@@ -612,10 +646,12 @@ export class SessionMetrics {
      */
     #resolveRecovery() {
         if (this.#priorCallErrored) {
-            if (this.#currentCallErrored)
+            if (this.#currentCallErrored) {
                 this.#errorsRepeated += 1;
-            else
+            }
+            else {
                 this.#errorsRecovered += 1;
+            }
         }
         this.#priorCallErrored = this.#currentCallErrored;
         this.#currentCallErrored = false;
@@ -625,14 +661,18 @@ export class SessionMetrics {
      * that left explains everything after it, and a verdict settles whatever preceded it.
      */
     #endReason() {
-        if (0 === this.#lifetimeToolCalls)
+        if (0 === this.#lifetimeToolCalls) {
             return 'never_used';
-        if (this.#clientLeft)
+        }
+        if (this.#clientLeft) {
             return 'client_left';
-        if (this.#unsettledActions > 0)
+        }
+        if (this.#unsettledActions > 0) {
             return 'abandoned';
-        if (this.#lifetimeVerifications > 0)
+        }
+        if (this.#lifetimeVerifications > 0) {
             return 'verified';
+        }
         return 'explored';
     }
     /**

package/dist/telemetry/telemetry.d.ts

@@ -1,4 +1,4 @@
-import { TelemetryEventKind, ProjectIdSource, type Crash, type Feedback, type Identity, type BugFound, type InitOutcome, type OnboardingStep, type InstallSource, type McpConnection, type McpOutage, type DaemonDeath, type ProxyExit, type WakeRefusal, type DaemonSpawnMethod, type ToolRefusal, type AppInstrumentation, type HarnessRun, type HudEvent, type PlatformLink, type ProjectProfile, type SessionSummary, type TelemetryActor, type Verification, type VersionChange } from '@reticlehq/core/telemetry';
+import { TelemetryEventKind, ProjectIdSource, type Crash, type Feedback, type Identity, type BugFound, type InitOutcome, type OnboardingStep, type InstallSource, type McpConnection, type McpOutage, type DaemonDeath, type GateCompleted, type ProxyExit, type WakeRefusal, type DaemonSpawnMethod, type ToolRefusal, type AppInstrumentation, type HarnessRun, type HudEvent, type PlatformLink, type ProjectProfile, type SessionSummary, type TelemetryActor, type Verification, type VersionChange } from '@reticlehq/core/telemetry';
 /**
  * Presence of this file marks the MACHINE as the Reticle team's own: every event carries
  * `internal: true`. The persistent twin of `RETICLE_INTERNAL=1`, for a dev machine where setting a
@@ -113,6 +113,8 @@ export interface TelemetryExtra {
     daemonDeath?: DaemonDeath;
     /** `wake_refused`: what held the port. */
     wakeRefusal?: WakeRefusal;
+    /** `gate_completed`: how `reticle gate` ended. */
+    gate?: GateCompleted;
     /** `daemon_started`: how the parent started the daemon. */
     spawnMethod?: DaemonSpawnMethod;
     /**