@reticlehq/server 2.14.0 → 3.2.0

package/dist/telemetry/harness-drive.js

@@ -0,0 +1,39 @@
+/**
+ * Whether the tool call running right now belongs to one of OUR drives.
+ *
+ * `reticle_verify { action: "explore" }` hands the app to a model inside the daemon, which drives
+ * through the same dispatch chokepoint every agent uses. That is the right design — the inner
+ * `act_and_wait` and `assert` calls are real verifications and must be counted — but it left every
+ * verdict a drive produced indistinguishable from one the user's own agent earned, under the same
+ * session and the same `actor: agent`. So "did this install ever verify anything by itself" had no
+ * answer, and any per-session rate read high by however much we drove.
+ *
+ * Module state, one flag, set for the span of the drive. The same one-hop pattern `tool-refused.ts`
+ * already uses for its pending reason, and for the same reason: the fact is produced in one place
+ * and needed in another, with a chokepoint in between that has no business taking an extra argument
+ * for a metric.
+ *
+ * A COUNTER rather than a boolean, so a drive nested inside a drive cannot clear the flag on its way
+ * out and leave the outer one unmarked.
+ */
+let depth = 0;
+/** Run `drive` with every verdict underneath it attributed to the harness. */
+export async function withHarnessDrive(drive) {
+    depth += 1;
+    try {
+        return await drive();
+    }
+    finally {
+        // In a `finally` because a drive that THREW still drove: leaving the flag raised would attribute
+        // the user's own next verdict to a harness that is no longer running.
+        depth -= 1;
+    }
+}
+/** True while a harness drive is in progress. */
+export function harnessDriving() {
+    return depth > 0;
+}
+/** Tests only — a leaked span would mis-attribute every verdict after it. */
+export function resetHarnessDrive() {
+    depth = 0;
+}

package/dist/telemetry/install-source.js

@@ -23,7 +23,7 @@
  * are indistinguishable once they are in the same column.
  */
 import { InstallSource } from '@reticlehq/core/telemetry';
-import { findProjectConfig } from '../cli/cli-port.js';
+import { findProjectConfig } from '../command/cli/ports/resolve/cli-port.js';
 /** The one marker. Set by a channel on the process that runs the install. */
 export const INSTALL_SOURCE_ENV = 'RETICLE_INSTALL_SOURCE';
 const KNOWN = new Set(Object.values(InstallSource));

package/dist/telemetry/install-trace.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Drain the installer's breadcrumbs, once.
+ *
+ * Deleted whether or not every line parsed: a file that stays is a file that re-reports the same
+ * install on every CLI invocation for the life of the machine, which would make the first funnel
+ * step count users-times-commands instead of users.
+ */
+export declare function drainInstallTrace(stateDir: string): number;

package/dist/telemetry/install-trace.js

@@ -0,0 +1,74 @@
+import { existsSync, readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { OnboardingStepSchema } from '@reticlehq/core/telemetry';
+import { reportOnboardingStep } from './onboarding-funnel.js';
+/**
+ * What the one-line installer could not report itself.
+ *
+ * `install.sh` runs before there is a CLI, so the three steps that can fail before Reticle exists —
+ * the script starting, the runtime check, the npm install — have nobody to emit them. It appends
+ * them to a file instead, and this drains that file on the first CLI run.
+ *
+ * The alternative was POSTing from bash, which means a second copy of the envelope: the anonymous
+ * id, the opt-out check, the event shape. That copy is a thing to keep in step with the original,
+ * and this repository's own history is a list of what happens when two lists must agree and one is
+ * edited. One emitter, one envelope.
+ *
+ * THE LIMIT, stated rather than discovered: an install that dies before the CLI exists is never
+ * reported at all. `runtime_ready failed no_node` is written and then nothing ever reads it. That
+ * is the cost of not duplicating the envelope, and it is bounded — the machines it loses are the
+ * ones with no Reticle on them.
+ */
+const TRACE_FILE = 'install-trace.jsonl';
+/**
+ * How many lines will ever be drained.
+ *
+ * The file is on disk, in a directory the user owns, and a runaway installer loop or a hand-edited
+ * file must not turn into thousands of events. Far above any real install, which writes three.
+ */
+const MAX_LINES = 32;
+/**
+ * Drain the installer's breadcrumbs, once.
+ *
+ * Deleted whether or not every line parsed: a file that stays is a file that re-reports the same
+ * install on every CLI invocation for the life of the machine, which would make the first funnel
+ * step count users-times-commands instead of users.
+ */
+export function drainInstallTrace(stateDir) {
+    const path = join(stateDir, TRACE_FILE);
+    if (!existsSync(path))
+        return 0;
+    let drained = 0;
+    try {
+        const lines = readFileSync(path, 'utf8')
+            .split('\n')
+            .filter((l) => l.trim().length > 0);
+        for (const line of lines.slice(0, MAX_LINES)) {
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                continue; // a truncated last write, or something that is not ours. Skip it, keep the rest.
+            }
+            // VALIDATED, because this came off disk. `reportOnboardingStep` validates too, and that is
+            // 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)
+                continue;
+            void reportOnboardingStep(step.data);
+            drained += 1;
+        }
+    }
+    catch {
+        /* unreadable trace is not worth a word to the user */
+    }
+    try {
+        rmSync(path, { force: true });
+    }
+    catch {
+        /* a trace we cannot delete would re-report; nothing we can do about it here */
+    }
+    return drained;
+}

package/dist/telemetry/license-activation.js

@@ -26,7 +26,7 @@
  * holds a customer list.
  */
 import { LicenseActivation } from '@reticlehq/core/telemetry';
-import { describeLicense, LICENSE_KEY_ENV } from '../license/license.js';
+import { describeLicense, LICENSE_KEY_ENV } from '../features/license/license.js';
 /**
  * Resolve activation for one event. The clock is passed in (rule 7) and is the EVENT's clock, not a
  * value captured at startup: sessions here run to eleven hours, so a key that expires mid-session must

package/dist/telemetry/mcp-connection.d.ts

@@ -1,5 +1,18 @@
 export declare function markDaemonStart(now: number): void;
-/** Report one client attaching. Best-effort; a metric must never affect whether a client connects. */
+/**
+ * Report one client attaching, BY NAME. Best-effort; a metric must never affect whether a client
+ * connects.
+ *
+ * The name is required in practice, and that is the fix rather than a restriction. `connection.client`
+ * was defined and documented and never once populated: the only caller reported from
+ * `transport.connect().then(...)`, which resolves when the SSE stream opens — before the client has
+ * said who it is. `clientInfo` first exists at `oninitialized`, so the event carried every fact about
+ * the connection except the one that makes "which agent client converts best" answerable at all.
+ *
+ * An unnamed call reports NOTHING. A stream that opens and never completes a handshake is a probe,
+ * not a client attaching, and counting it was what put an unattributable row exactly where the name
+ * belonged.
+ */
 export declare function reportMcpConnected(client?: string, now?: () => number): void;
 /** Tests only. */
 export declare function resetMcpConnections(): void;

package/dist/telemetry/mcp-connection.js

@@ -19,8 +19,23 @@ export function markDaemonStart(now) {
     daemonStartedAt = now;
     connectsSeen = 0;
 }
-/** Report one client attaching. Best-effort; a metric must never affect whether a client connects. */
+/**
+ * Report one client attaching, BY NAME. Best-effort; a metric must never affect whether a client
+ * connects.
+ *
+ * The name is required in practice, and that is the fix rather than a restriction. `connection.client`
+ * was defined and documented and never once populated: the only caller reported from
+ * `transport.connect().then(...)`, which resolves when the SSE stream opens — before the client has
+ * said who it is. `clientInfo` first exists at `oninitialized`, so the event carried every fact about
+ * the connection except the one that makes "which agent client converts best" answerable at all.
+ *
+ * An unnamed call reports NOTHING. A stream that opens and never completes a handshake is a probe,
+ * not a client attaching, and counting it was what put an unattributable row exactly where the name
+ * belonged.
+ */
 export function reportMcpConnected(client, now = () => Date.now()) {
+    if (client === undefined)
+        return;
     try {
         const reconnect = connectsSeen > 0;
         connectsSeen += 1;
@@ -30,7 +45,7 @@ export function reportMcpConnected(client, now = () => Date.now()) {
                 // A large value on the FIRST connect is the interesting case: Reticle was started and then
                 // sat there. On a reconnect it is just how long the daemon has been up.
                 daemonAgeMs: daemonStartedAt === undefined ? 0 : Math.max(0, now() - daemonStartedAt),
-                ...(client !== undefined ? { client } : {}),
+                client,
                 // WHAT THE AGENT HAD TO LOOK AT. Most clients that attach never call a tool, and that cohort
                 // emits nothing at all — an agent that reads the instructions, learns nothing is wired and
                 // stops has refused nothing, so `tool_refused` cannot see it either. Read off the same flag

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

@@ -0,0 +1,40 @@
+/** A tool call the daemon just ran. Called from the dispatch chokepoint, which sees every one. */
+export declare function noteOnboardingFirst(toolName: string): void;
+/**
+ * The first ACTION of this run, and the fact that this install has been driven at all.
+ *
+ * Called from the dispatch chokepoint's own action branch rather than matched on a tool name here.
+ * The name test was `toolName === ReticleTool.ACT`, on the worry that `act_and_wait` would report
+ * one call as two different firsts — and the worry was backwards: this server's instructions tell
+ * every agent to PREFER `act_and_wait`, so the step measured the tool we ask agents not to use and
+ * the ONBOARD phase read as "looked, never acted, then produced a verdict from nowhere". A call that
+ * both acts and proves genuinely did both, and `first_act` and `first_verdict` are different steps
+ * in different positions of the same funnel.
+ *
+ * Taking the decision from the caller is what keeps it from happening again: the dispatcher already
+ * owns the set of tools that drive the page, and a second copy of that set here is a second thing to
+ * update when a fourth driving tool arrives.
+ */
+export declare function noteActed(args: Record<string, unknown>): void;
+/**
+ * The first verdict of this run.
+ *
+ * Separate from `noteOnboardingFirst` because a verdict is not a tool NAME — it is a result shape,
+ * and only the site that already decided "this was a verification" can say so. Reported from there.
+ */
+export declare function noteFirstVerdict(): void;
+/**
+ * Something was driven on the user's own project — the FIRST_RUN rung between "the install worked"
+ * and "they used it".
+ *
+ * Declared in the closed step list from the day the funnel was written and emitted by no code at
+ * all, so any chart rendered over the declared order showed a 100% cliff in the middle of the
+ * conversion story. It reads as catastrophe and was an unwired emit.
+ *
+ * Reported from `noteActed`, so the one place that knows a tool drove the page is the one place that
+ * says so. That includes a drive we run on the user's behalf, whose own actions cross the same
+ * chokepoint — a drive that is refused before its first action drove nothing and says nothing.
+ */
+export declare function noteDriven(): void;
+/** Arm again for the next daemon run — the tests' seam, mirroring resetAppInstrumented. */
+export declare function resetOnboardingFirsts(): void;

package/dist/telemetry/onboarding-firsts.js

@@ -0,0 +1,109 @@
+import { ActionType, OnboardingPhase, OnboardingStepStatus, ReticleTool } from '@reticlehq/core';
+import { reportOnboardingStep } from './onboarding-funnel.js';
+/**
+ * The onboarding steps only the DAEMON can answer, reported once each per run.
+ *
+ * `reticle tutorial` renders a page; it cannot know whether the reader then looked at their app,
+ * drove it, or proved anything. Those three are facts here and assumptions anywhere else, so they
+ * are observed at the moment they happen rather than claimed when the tour is printed.
+ *
+ * ONCE per daemon run, exactly like `reportAppInstrumented` and for the same reason: the question is
+ * "did this install ever get past looking", which has one answer per run. A session that snapshots
+ * forty times is not forty people learning to look.
+ *
+ * The flags are module state rather than per-session, because a person who tours in one tab and
+ * drives in another has still only crossed each of these once.
+ */
+const seen = { look: false, act: false, verdict: false, driven: false };
+/** A tool call the daemon just ran. Called from the dispatch chokepoint, which sees every one. */
+export function noteOnboardingFirst(toolName) {
+    if (!seen.look && LOOK_TOOLS.has(toolName)) {
+        seen.look = true;
+        void reportOnboardingStep({
+            phase: OnboardingPhase.ONBOARD,
+            step: 'first_look',
+            status: OnboardingStepStatus.COMPLETED,
+        });
+    }
+}
+/**
+ * The first ACTION of this run, and the fact that this install has been driven at all.
+ *
+ * Called from the dispatch chokepoint's own action branch rather than matched on a tool name here.
+ * The name test was `toolName === ReticleTool.ACT`, on the worry that `act_and_wait` would report
+ * one call as two different firsts — and the worry was backwards: this server's instructions tell
+ * every agent to PREFER `act_and_wait`, so the step measured the tool we ask agents not to use and
+ * the ONBOARD phase read as "looked, never acted, then produced a verdict from nowhere". A call that
+ * both acts and proves genuinely did both, and `first_act` and `first_verdict` are different steps
+ * in different positions of the same funnel.
+ *
+ * Taking the decision from the caller is what keeps it from happening again: the dispatcher already
+ * owns the set of tools that drive the page, and a second copy of that set here is a second thing to
+ * update when a fourth driving tool arrives.
+ */
+export function noteActed(args) {
+    // A hover changes nothing and is not an action anybody drove.
+    if (args['action'] === ActionType.HOVER)
+        return;
+    noteDriven();
+    if (seen.act)
+        return;
+    seen.act = true;
+    void reportOnboardingStep({
+        phase: OnboardingPhase.ONBOARD,
+        step: 'first_act',
+        status: OnboardingStepStatus.COMPLETED,
+    });
+}
+/**
+ * The first verdict of this run.
+ *
+ * Separate from `noteOnboardingFirst` because a verdict is not a tool NAME — it is a result shape,
+ * and only the site that already decided "this was a verification" can say so. Reported from there.
+ */
+export function noteFirstVerdict() {
+    if (seen.verdict)
+        return;
+    seen.verdict = true;
+    void reportOnboardingStep({
+        phase: OnboardingPhase.ONBOARD,
+        step: 'first_verdict',
+        status: OnboardingStepStatus.COMPLETED,
+    });
+}
+/**
+ * Something was driven on the user's own project — the FIRST_RUN rung between "the install worked"
+ * and "they used it".
+ *
+ * Declared in the closed step list from the day the funnel was written and emitted by no code at
+ * all, so any chart rendered over the declared order showed a 100% cliff in the middle of the
+ * conversion story. It reads as catastrophe and was an unwired emit.
+ *
+ * Reported from `noteActed`, so the one place that knows a tool drove the page is the one place that
+ * says so. That includes a drive we run on the user's behalf, whose own actions cross the same
+ * chokepoint — a drive that is refused before its first action drove nothing and says nothing.
+ */
+export function noteDriven() {
+    if (seen.driven)
+        return;
+    seen.driven = true;
+    void reportOnboardingStep({
+        phase: OnboardingPhase.FIRST_RUN,
+        step: 'driven',
+        status: OnboardingStepStatus.COMPLETED,
+    });
+}
+/** Looking: the tools that read the page without changing it. */
+const LOOK_TOOLS = new Set([
+    ReticleTool.SNAPSHOT,
+    ReticleTool.QUERY,
+    ReticleTool.INSPECT,
+    ReticleTool.LOOK,
+]);
+/** Arm again for the next daemon run — the tests' seam, mirroring resetAppInstrumented. */
+export function resetOnboardingFirsts() {
+    seen.look = false;
+    seen.act = false;
+    seen.verdict = false;
+    seen.driven = false;
+}

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

@@ -0,0 +1,26 @@
+import { OnboardingPhase, type OnboardingStep } from '@reticlehq/core/telemetry';
+/**
+ * The one place an onboarding step is reported.
+ *
+ * A chokepoint for the reason rule 1 gives: telemetry fails silently, so a second emit site is a
+ * second place that can quietly stop firing, and nothing goes red when it does. Every phase reports
+ * here, and this is the only thing that knows the event kind.
+ *
+ * VALIDATED before sending, which is not ceremony. `step` is a free-ish string in the schema and
+ * the whole value of the funnel is that it holds OUR names — a path, a URL or an error message
+ * 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>;
+/**
+ * Time a step and report it, whatever happens to it.
+ *
+ * The `finally` is the point. A step that is STARTED and never resolved is indistinguishable in a
+ * funnel from one that was never reached, so an exception escaping without a report turns a FAILURE
+ * into an absence — and absence is how every drop-off is already explained away.
+ */
+export declare function trackOnboardingStep<T>(phase: OnboardingPhase, step: string, run: () => Promise<T>, opts?: {
+    now?: () => number;
+    unattended?: boolean;
+    stack?: string;
+}): Promise<T>;

package/dist/telemetry/onboarding-funnel.js

@@ -0,0 +1,60 @@
+import { OnboardingPhase, OnboardingStepSchema, OnboardingStepStatus, TelemetryEventKind, } from '@reticlehq/core/telemetry';
+import { getTelemetry } from './telemetry.js';
+/**
+ * The one place an onboarding step is reported.
+ *
+ * A chokepoint for the reason rule 1 gives: telemetry fails silently, so a second emit site is a
+ * second place that can quietly stop firing, and nothing goes red when it does. Every phase reports
+ * here, and this is the only thing that knows the event kind.
+ *
+ * VALIDATED before sending, which is not ceremony. `step` is a free-ish string in the schema and
+ * the whole value of the funnel is that it holds OUR names — a path, a URL or an error message
+ * 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) {
+    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)
+        return false;
+    return getTelemetry().emit(TelemetryEventKind.ONBOARDING_STEP, { onboarding: parsed.data });
+}
+/**
+ * Time a step and report it, whatever happens to it.
+ *
+ * The `finally` is the point. A step that is STARTED and never resolved is indistinguishable in a
+ * funnel from one that was never reached, so an exception escaping without a report turns a FAILURE
+ * into an absence — and absence is how every drop-off is already explained away.
+ */
+export async function trackOnboardingStep(phase, step, run, opts = {}) {
+    const now = opts.now ?? (() => Date.now());
+    const started = now();
+    const common = {
+        phase,
+        step,
+        ...(opts.unattended === undefined ? {} : { unattended: opts.unattended }),
+        ...(opts.stack === undefined ? {} : { stack: opts.stack }),
+    };
+    void reportOnboardingStep({ ...common, status: OnboardingStepStatus.STARTED });
+    try {
+        const result = await run();
+        void reportOnboardingStep({
+            ...common,
+            status: OnboardingStepStatus.COMPLETED,
+            elapsedMs: now() - started,
+        });
+        return result;
+    }
+    catch (error) {
+        void reportOnboardingStep({
+            ...common,
+            status: OnboardingStepStatus.FAILED,
+            elapsedMs: now() - started,
+            // The CLASS of failure, never the message: a message carries paths, hostnames and whatever
+            // the user typed. `reason` is capped at 64 for the same reason.
+            reason: error instanceof Error ? error.constructor.name : 'unknown',
+        });
+        throw error;
+    }
+}

package/dist/telemetry/project-profile.js

@@ -15,7 +15,7 @@ import { join } from 'node:path';
 import { ProjectSize, ReticleDir } from '@reticlehq/core';
 import { gitFacts } from './git-facts.js';
 import { detectStack } from './feedback-context.js';
-import { readProjectId } from '../cli/cli-port.js';
+import { readProjectId } from '../command/cli/ports/resolve/cli-port.js';
 /**
  * The feature FAMILIES, and the on-disk evidence that a project has adopted each. Named rather than
  * counted so the vocabulary stays stable as tools are added, renamed, or merged into action-dispatched

package/dist/telemetry/run-telemetry.js

@@ -26,6 +26,17 @@ export function reportRunTelemetry(run) {
         const metrics = getSessionMetrics();
         metrics.recordVerification();
         void getTelemetry().emit(TelemetryEventKind.VERIFICATION_COMPLETED, {
+            /*
+             * DETACHED, because `reticle verify` exits straight after this.
+             *
+             * `cli-verify.ts` calls `ports.exit(...)`, which is `process.exit`, and only microtasks sit
+             * between here and it. An in-process send carries a two-second budget and gets none of it, so
+             * the verdict from every unattended run -- CI, a scheduled gate, a one-shot check, which is the
+             * surface most likely to run at scale -- was dropped. The agent loop reports the same event
+             * from `invoke-tool.ts` and stays alive afterwards, so the number looked plausible while
+             * missing exactly the half nobody is watching.
+             */
+            detach: true,
             // A `reticle verify` was typed by a person or scheduled by their CI — either way it is not the
             // agent's own loop, which is the distinction `actor` exists to draw.
             actor: TelemetryActor.HUMAN,
@@ -45,6 +56,8 @@ export function reportRunTelemetry(run) {
             // fix far more often than it is forty.
             const first = metrics.recordBug('flow-regression');
             void getTelemetry().emit(TelemetryEventKind.BUG_FOUND, {
+                // Detached for the same reason as the verdict above: the process exits behind this loop.
+                detach: true,
                 actor: TelemetryActor.HUMAN,
                 bug: {
                     source: BugSource.REPLAY,

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

@@ -85,14 +85,13 @@ export declare class SessionMetrics {
     /**
      * Ask the agent for a verdict, once, when it has driven the page without asking for one.
      *
-     * In the field most sessions that made a tool call produced no verdict — and
-     * **almost all of those never called a verdict-producing tool even once.** They drove the app
-     * with `reticle_act` and never asked whether it worked. This counter already existed
-     * (`abandonedActions`); it was reported to US and never to the agent.
+     * A session that drives the app with `reticle_act` and never asks whether it worked proves
+     * nothing. The counter behind this (`abandonedActions`) already existed and was reported only in
+     * telemetry, never to the agent that could act on it.
      *
-     * Three is the threshold because the median verdict-less session made four tool calls: any higher
-     * and it never fires for the sessions that need it. Re-arms after a verdict, so a second
-     * abandoned run is caught — the loop can break more than once in a long session.
+     * Three is the threshold because a verdict-less session typically makes only a handful of calls:
+     * any higher and it never fires for the sessions that need it. Re-arms after a verdict, so a
+     * second abandoned run is caught — the loop can break more than once in a long session.
      */
     takeUnverifiedNudge(): string | undefined;
     /**

package/dist/telemetry/session-metrics.js

@@ -50,8 +50,8 @@ const BREADCRUMB_LENGTH = 12;
 /**
  * Actions driven with no verdict before Reticle asks for one.
  *
- * Three, because the median verdict-less session made FOUR tool calls (2026-08-10/11). A higher
- * threshold never fires for the sessions that need it most.
+ * Three, because a verdict-less session typically makes only a handful of calls. A higher threshold
+ * never fires for the sessions that need it most.
  */
 const UNVERIFIED_ACTION_NUDGE_AT = 3;
 /**
@@ -66,15 +66,10 @@ export class SessionMetrics {
      * Session-LIFETIME totals for the four numbers the funnel is computed from.
      *
      * `reset()` zeroes every window counter on each periodic flush, but `durationMs` is measured from
-     * `#startedAt` and is never reset. So the FINAL summary — the one whose docstring promises "the
-     * whole session in a single event" — reported a 30-minute session containing zero tool calls,
-     * because it only ever carried the residue since the last flush.
-     *
-     * In the field almost every `daemon_stopped` row had `toolCalls: 0`, at a median
-     * duration of 30.5 minutes, while `session_progress` for the same daemons carried real tool
-     * histograms. Anyone computing "did this session use Reticle" off the event named for the end of
-     * the session got `no` essentially always. That is not a small skew — it is the funnel reading
-     * zero at the exact step this release exists to raise.
+     * `#startedAt` and is never reset. Without these, the FINAL summary — the one whose docstring
+     * promises "the whole session in a single event" — reports a long session containing zero tool
+     * calls, because it carries only the residue since the last flush, and anyone computing "did this
+     * session use Reticle" off the event named for the end of the session reads `no`.
      *
      * Window semantics are unchanged: `session_progress` still reports its own window, so nothing that
      * already sums those events double-counts. Only `final: true` swaps in the lifetime numbers.
@@ -118,9 +113,8 @@ export class SessionMetrics {
      */
     #seenBugKinds = new Set();
     /**
-     * Tool errors meaning "the agent could not reach an app at all" — the single biggest drop-off in
-     * the funnel, and until now reachable only by unpacking `errors[]` in HogQL. 74% of daemons never
-     * call a tool, and of the sessions that made exactly one call, most bounced on this.
+     * Tool errors meaning "the agent could not reach an app at all" — counted as a field of its own
+     * because the alternative is unpacking `errors[]` in HogQL.
      */
     #noSessionErrors = 0;
     /** Connection-level MCP POST failures the SSE stream cannot see. See SessionSummary. */
@@ -356,14 +350,13 @@ export class SessionMetrics {
     /**
      * Ask the agent for a verdict, once, when it has driven the page without asking for one.
      *
-     * In the field most sessions that made a tool call produced no verdict — and
-     * **almost all of those never called a verdict-producing tool even once.** They drove the app
-     * with `reticle_act` and never asked whether it worked. This counter already existed
-     * (`abandonedActions`); it was reported to US and never to the agent.
+     * A session that drives the app with `reticle_act` and never asks whether it worked proves
+     * nothing. The counter behind this (`abandonedActions`) already existed and was reported only in
+     * telemetry, never to the agent that could act on it.
      *
-     * Three is the threshold because the median verdict-less session made four tool calls: any higher
-     * and it never fires for the sessions that need it. Re-arms after a verdict, so a second
-     * abandoned run is caught — the loop can break more than once in a long session.
+     * Three is the threshold because a verdict-less session typically makes only a handful of calls:
+     * any higher and it never fires for the sessions that need it. Re-arms after a verdict, so a
+     * second abandoned run is caught — the loop can break more than once in a long session.
      */
     takeUnverifiedNudge() {
         if (this.#unsettledActions < UNVERIFIED_ACTION_NUDGE_AT || this.#nudgedUnverified) {

package/dist/telemetry/telemetry.d.ts

@@ -1,4 +1,4 @@
-import { TelemetryEventKind, ProjectIdSource, type Crash, type Feedback, type Identity, type BugFound, type InitOutcome, type InstallSource, type McpConnection, type McpOutage, type ToolRefusal, type AppInstrumentation, 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 ToolRefusal, type AppInstrumentation, type ProjectProfile, type SessionSummary, type TelemetryActor, type Verification, type VersionChange } from '@reticlehq/core/telemetry';
 /**
  * PostHog's group type for a licensed customer. Sent as `$groups` so PostHog can aggregate a whole
  * organisation natively: per-company retention, "which orgs went quiet", one row per customer rather
@@ -65,6 +65,13 @@ export interface TelemetryExtra {
     connection?: McpConnection;
     /** `init_completed`: how `reticle init` went. */
     init?: InitOutcome;
+    /**
+     * `onboarding_step`: one step of install / onboard / first run.
+     *
+     * A block rather than top-level fields, like every other event's payload here, so a funnel query
+     * reads one shape and adding a field to it cannot collide with another event's.
+     */
+    onboarding?: OnboardingStep;
     /** `bug_found`: one defect Reticle found in the app under test. */
     bug?: BugFound;
     /** `tool_refused`: a call Reticle could not serve, and why. */

package/dist/telemetry/telemetry.js

@@ -1,7 +1,6 @@
 /**
- * Anonymous adoption telemetry — the OSS runtime's ONLY phone-home for product metrics (DAU/WAU/MAU,
- * invocations, sessions, installs, tool usage). It answers the "npm downloads don't count, show me
- * platform usage" question without collecting anything personal:
+ * Anonymous adoption telemetry — the runtime's ONLY phone-home for product metrics (invocations,
+ * sessions, installs, tool usage). It reports platform usage without collecting anything personal:
  *
  *   - identity is a random UUID minted locally at `~/.reticle/telemetry-id` (never derived from you),
  *   - the project is a one-way HASH of the cwd (counts DISTINCT projects, reveals none),
@@ -20,7 +19,7 @@ import { appendFileSync, readFileSync, writeFileSync, mkdirSync, existsSync, rmS
 import { homedir, platform } from 'node:os';
 import { dirname, join } from 'node:path';
 import { TelemetryEventKind, TELEMETRY_EVENT_VERSION, ProjectIdSource, isSessionScoped, } from '@reticlehq/core/telemetry';
-import { SERVER_VERSION } from '../version/server-version.js';
+import { SERVER_VERSION } from '../command/version/identity/server-version.js';
 const RETICLE_DIR = join(homedir(), '.reticle');
 const ID_FILE = join(RETICLE_DIR, 'telemetry-id');
 const NOTICE_FILE = join(RETICLE_DIR, 'telemetry-notice-shown');
@@ -359,6 +358,7 @@ export const createTelemetry = (opts) => {
             ...(extra?.identity !== undefined ? { identity: extra.identity } : {}),
             ...(extra?.connection !== undefined ? { connection: extra.connection } : {}),
             ...(extra?.init !== undefined ? { init: extra.init } : {}),
+            ...(extra?.onboarding !== undefined ? { onboarding: extra.onboarding } : {}),
             ...(extra?.bug !== undefined ? { bug: extra.bug } : {}),
             ...(extra?.refusal !== undefined ? { refusal: extra.refusal } : {}),
             ...(extra?.outage !== undefined ? { outage: extra.outage } : {}),
@@ -383,7 +383,7 @@ export const createTelemetry = (opts) => {
         // PostHog filters and breakdowns operate on top-level properties, so a nested `feedback.stack`
         // would be invisible to the exact "which stacks report the most bugs" question this exists to
         // answer. One prefix keeps them grouped in the UI without a nested path.
-        const { anonymousId: distinctId, event: name, ts, sessionId: eventSessionId, feedback, session, project, verification, versionChange, crash, identity, connection, init, bug, refusal, outage, instrumentation, ...rest } = event;
+        const { anonymousId: distinctId, event: name, ts, sessionId: eventSessionId, feedback, session, project, verification, versionChange, crash, identity, connection, init, onboarding, bug, refusal, outage, instrumentation, ...rest } = event;
         // `$session_id` is PostHog's OWN session property, so sending ours under that name lights up
         // its built-in session views and funnels for free rather than requiring custom HogQL everywhere.
         // `sessionId` rides only on events that happened inside a daemon run. A one-shot CLI command
@@ -410,6 +410,7 @@ export const createTelemetry = (opts) => {
             identity,
             connection,
             init,
+            onboarding,
             bug,
             refusal,
             outage,