@reticlehq/server 2.4.0 → 2.6.0

package/dist/telemetry/session-metrics.js

@@ -19,8 +19,20 @@ import { BrowserLaunchKind, } from '@reticlehq/core';
 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';
 /** Cap the distinct error shapes held in memory — a pathological loop must not grow unbounded. */
 const MAX_ERROR_KINDS = 40;
+/** Distinct tool names whose repeat-runs are tracked. Its own cap: the tool surface, not error shapes. */
+const MAX_REPEAT_TOOLS = 64;
+/**
+ * Tool errors that all mean the same thing to a user: the agent asked, and there was no app it could
+ * reach. Three different messages, one experience — "nothing is connected" — and it is the error
+ * that ends most sessions before a single verification happens.
+ *
+ * `multiple sessions connected` belongs here too: the agent could not reach AN app because it could
+ * not tell which one, and the outcome is identical.
+ */
+const NO_SESSION_ERROR = /no browser session connected|no connected session with id|multiple sessions connected/i;
 /** Cap distinct MCP clients recorded; more than a handful on one daemon is already the story. */
 const MAX_CLIENTS = 8;
 /** Bounds on the parameter map. Our own schemas are already finite; these are a belt-and-braces cap. */
@@ -35,6 +47,13 @@ const MAX_PARAMS_PER_TOOL = 24;
  * strings and costs nothing to hold.
  */
 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.
+ */
+const UNVERIFIED_ACTION_NUDGE_AT = 3;
 /**
  * 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.
@@ -43,6 +62,27 @@ export class SessionMetrics {
     #toolCalls = 0;
     #toolErrors = 0;
     #verifications = 0;
+    /**
+     * 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.
+     *
+     * Measured 2026-08-10/11: **496 of 499 `daemon_stopped` rows 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.
+     *
+     * 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.
+     */
+    #lifetimeToolCalls = 0;
+    #lifetimeToolErrors = 0;
+    #lifetimeVerifications = 0;
+    #lifetimeBugsFound = 0;
     #toolCounts = new Map();
     #toolParams = new Map();
     /** Ring of the most recent tool NAMES — the agent's approach run, for a crash report. */
@@ -58,6 +98,12 @@ export class SessionMetrics {
     #concurrent = 0;
     #peakConcurrent = 0;
     #unknownToolCalls = 0;
+    /**
+     * Names the agent guessed at, session-LIFETIME — a guess made early must still be reported at
+     * the end, so this is deliberately not cleared by a flush.
+     */
+    #unknownTools = new Map();
+    #lifetimeUnknownToolCalls = 0;
     #bugsFound = 0;
     #browserMs = 0;
     #browserCommands = 0;
@@ -71,7 +117,52 @@ export class SessionMetrics {
      * capped: the kind vocabulary is a bounded enum plus oracle names, not user data.
      */
     #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.
+     */
+    #noSessionErrors = 0;
+    /** Longest back-to-back run per tool — a retry loop, which `toolCounts` cannot distinguish. */
+    #repeatRuns = new Map();
+    #lastTool;
+    #currentRun = 0;
+    /**
+     * Actions driven since the last verdict — the run that is left hanging if the loop stops here.
+     *
+     * NOT `actions - verifications`. That difference ignores ORDER, so a verdict that drove nothing
+     * (a `flow_verify` over saved flows) silently paid for a genuinely abandoned action elsewhere, and
+     * a session could verify first and act after and look settled. What is abandoned is the trailing
+     * run, which is exactly what the field claims to mean.
+     */
+    #unsettledActions = 0;
+    /** One-shot latch for the verdict nudge — see takeUnverifiedNudge. */
+    #nudgedUnverified = false;
+    /** The agent detached. The one part of `endReason` a query cannot derive. */
+    #clientLeft = false;
+    /** Feedback invitations shown, session-lifetime — the denominator for feedback_submitted. */
+    #feedbackPrompted = 0;
+    /** Error buckets by whose defect. Session-lifetime: the mix is a fact about the session. */
+    #errorClasses = new Map();
+    /**
+     * The recovery hinge. A call's outcome is only known once the NEXT one starts, so the verdict for
+     * call N-1 is resolved at the start of call N (and for the last call, at summarize).
+     */
+    #currentCallErrored = false;
+    #priorCallErrored = false;
+    #errorsRecovered = 0;
+    #errorsRepeated = 0;
+    /**
+     * App SDK connections, session-lifetime. NOT reset by a flush: "did an app ever connect" is a
+     * fact about the session, and a page reload after a flush must not erase it.
+     */
+    #appConnects = 0;
+    #firstAppAt;
     #clients = new Set();
+    /** Client name -> version, session-lifetime. Never cleared: who drove is a fact about the session. */
+    #clientVersions = new Map();
+    /** Which tool surface the daemon advertised. */
+    #surface;
     #startedAt;
     #now;
     /** Clock injected — this file must stay testable without a real one, per the repo's clock rule. */
@@ -116,11 +207,48 @@ export class SessionMetrics {
         this.#browserCommands += 1;
     }
     /** A call for a tool that does not exist. Non-zero means our surface is confusing the agent. */
-    recordUnknownTool() {
+    /**
+     * An agent reached for a tool that does not exist — and WHAT it reached for.
+     *
+     * The name is the point. A count says the surface confused someone; the name says which
+     * capability they expected us to have, in their own vocabulary. Safe to keep: it is a name from
+     * our own namespace, never app data. Bounded and truncated, because a guess is a short
+     * identifier and anything longer is not one.
+     */
+    recordUnknownTool(name) {
         this.#unknownToolCalls += 1;
+        this.#lifetimeUnknownToolCalls += 1;
+        if (name === undefined || 0 === name.length)
+            return;
+        const key = name.slice(0, 64);
+        const seen = this.#unknownTools.get(key);
+        if (seen !== undefined) {
+            this.#unknownTools.set(key, seen + 1);
+            return;
+        }
+        // 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)
+            return;
+        this.#unknownTools.set(key, 1);
     }
     recordToolCall(tool, args) {
+        // `recordToolCall` runs BEFORE a handler and `recordToolError` after it fails, so a call's
+        // outcome is only known once the NEXT call starts. Resolve the one before it here; the final
+        // call is resolved in summarize.
+        this.#resolveRecovery();
+        // A run of the same tool back to back. Five calls to reticle_act is engagement; five in a row
+        // after four failures is an agent stuck, and toolCounts reports both as "5".
+        this.#currentRun = tool === this.#lastTool ? this.#currentRun + 1 : 1;
+        this.#lastTool = tool;
+        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.set(tool, this.#currentRun);
+        }
         this.#toolCalls += 1;
+        this.#lifetimeToolCalls += 1;
         bump(this.#toolCounts, tool);
         this.#inFlight = tool;
         this.#breadcrumb.push(tool);
@@ -150,6 +278,13 @@ export class SessionMetrics {
      */
     recordToolError(message, tool) {
         this.#toolErrors += 1;
+        this.#lifetimeToolErrors += 1;
+        // Whose defect. Only the `schema` bucket is fixable by writing better descriptions, and it was
+        // indistinguishable from the rest inside one `toolErrors` count.
+        bump(this.#errorClasses, classifyError(message));
+        this.#currentCallErrored = true;
+        if (NO_SESSION_ERROR.test(message))
+            this.#noSessionErrors += 1;
         const fingerprint = fingerprintError(message);
         const existing = this.#errorKinds.get(fingerprint);
         if (existing !== undefined) {
@@ -194,8 +329,51 @@ export class SessionMetrics {
     get trail() {
         return { breadcrumb: [...this.#breadcrumb], inFlight: this.#inFlight };
     }
+    /**
+     * Ask the agent for a verdict, once, when it has driven the page without asking for one.
+     *
+     * Measured 2026-08-10/11: of 170 sessions that made a tool call, 140 produced no verdict — and
+     * **137 of those never called a verdict-producing tool even once.** They drove the app 269 times
+     * with `reticle_act` and never asked whether it worked. This counter already existed
+     * (`abandonedActions`, non-zero in 58 sessions); it was reported to US and never to the agent.
+     *
+     * 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.
+     */
+    takeUnverifiedNudge() {
+        if (this.#unsettledActions < UNVERIFIED_ACTION_NUDGE_AT || this.#nudgedUnverified) {
+            return undefined;
+        }
+        this.#nudgedUnverified = true;
+        return (`you have driven this page ${String(this.#unsettledActions)} times without asking for a ` +
+            'verdict. Only reticle_act_and_wait and reticle_assert produce one — everything else moves ' +
+            'or reads the app and proves nothing. Name the consequence you expect and check it: ' +
+            'reticle_assert({ sessionId, since, predicate }), or use reticle_act_and_wait({ ref, ' +
+            'action, until }) for the next step so the action and its check are one call.');
+    }
+    /**
+     * An app's SDK dialled this daemon.
+     *
+     * Zero of these at shutdown means the daemon ran and no app ever connected — a broken install.
+     * Non-zero with no tool calls is the opposite problem. See SessionSummary.appConnects.
+     */
+    recordAppConnected() {
+        this.#appConnects += 1;
+        this.#firstAppAt ??= this.#now();
+    }
+    /** One action driven at the page. Settled by the next verdict; see #unsettledActions. */
+    recordAction() {
+        this.#unsettledActions += 1;
+    }
     recordVerification() {
         this.#verifications += 1;
+        this.#lifetimeVerifications += 1;
+        // A verdict settles whatever was outstanding, however many actions it took to get there.
+        this.#unsettledActions = 0;
+        // Re-arm the nudge: the loop can break more than once in an 11-hour session, and an agent that
+        // complied once and then drifted again is exactly the case worth catching.
+        this.#nudgedUnverified = false;
     }
     /**
      * One defect found in the app under test — the outcome number, kept broken down by kind.
@@ -206,6 +384,7 @@ export class SessionMetrics {
      */
     recordBug(kind) {
         this.#bugsFound += 1;
+        this.#lifetimeBugsFound += 1;
         if (this.#bugKinds.size < MAX_ERROR_KINDS || this.#bugKinds.has(kind))
             bump(this.#bugKinds, kind);
         const first = !this.#seenBugKinds.has(kind);
@@ -237,27 +416,83 @@ export class SessionMetrics {
             stats.failures[failure] = (stats.failures[failure] ?? 0) + 1;
         };
     }
-    recordClient(name) {
+    recordClient(name, version) {
+        const key = name.slice(0, 64);
         if (this.#clients.size < MAX_CLIENTS)
-            this.#clients.add(name.slice(0, 64));
+            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) {
+            this.#clientVersions.set(key, version.slice(0, 32));
+        }
+    }
+    /**
+     * The agent's client went away.
+     *
+     * This is the only part of `endReason` that a query cannot derive from the counters: "the client
+     * detached" and "the agent stopped asking" produce identical numbers and are different findings —
+     * one is the task ending, the other is us losing them.
+     */
+    recordClientLeft() {
+        this.#clientLeft = true;
+    }
+    /** How many times in a row the current tool has been called. Read by the friction invite. */
+    get currentRun() {
+        return this.#currentRun;
+    }
+    /** Reticle invited the agent to send feedback. The denominator for feedback_submitted. */
+    recordFeedbackPrompt() {
+        this.#feedbackPrompted += 1;
+    }
+    /** Which tool surface was advertised to agents this session. */
+    recordSurface(surface) {
+        this.#surface = surface.slice(0, 32);
     }
     /**
      * Roll the counters into the event payload. `final` marks a clean shutdown; a periodic flush passes
      * false so a session killed before it can exit is not lost entirely (see the flush note in cli.ts).
      */
-    summarize(final) {
+    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)
+            this.#resolveRecovery();
         const machine = machineSnapshot();
+        // A FINAL summary reports the session; a periodic flush reports its window. `durationMs` was
+        // always session-lifetime, so a windowed count next to it described a 30-minute session that
+        // made no calls. The histograms below stay windowed by design — summing them across a session's
+        // events is correct, and duplicating every map to make them lifetime would double the memory
+        // this class exists to keep small.
+        const scalars = final
+            ? {
+                toolCalls: this.#lifetimeToolCalls,
+                toolErrors: this.#lifetimeToolErrors,
+                verifications: this.#lifetimeVerifications,
+                bugsFound: this.#lifetimeBugsFound,
+            }
+            : {
+                toolCalls: this.#toolCalls,
+                toolErrors: this.#toolErrors,
+                verifications: this.#verifications,
+                bugsFound: this.#bugsFound,
+            };
         return {
             durationMs: Math.max(0, this.#now() - this.#startedAt),
-            toolCalls: this.#toolCalls,
+            toolCalls: scalars.toolCalls,
             toolCounts: Object.fromEntries(this.#toolCounts),
-            toolErrors: this.#toolErrors,
+            toolErrors: scalars.toolErrors,
             ...(this.#errorKinds.size > 0 ? { errors: [...this.#errorKinds.values()] } : {}),
             sdkFailures: this.#sdkFailures,
             ...(this.#sdkFailureKinds.size > 0 ? { sdkErrors: [...this.#sdkFailureKinds.values()] } : {}),
-            verifications: this.#verifications,
-            bugsFound: this.#bugsFound,
+            verifications: scalars.verifications,
+            bugsFound: scalars.bugsFound,
             ...(this.#bugKinds.size > 0 ? { bugKinds: Object.fromEntries(this.#bugKinds) } : {}),
+            ...(this.#noSessionErrors > 0 ? { noSessionErrors: this.#noSessionErrors } : {}),
+            ...(this.#repeatRuns.size > 0
+                ? { consecutiveRepeats: Object.fromEntries(this.#repeatRuns) }
+                : {}),
+            // Absent rather than zero, so the PRESENCE of the field is the signal on a dashboard.
+            ...(this.#unsettledActions > 0 ? { abandonedActions: this.#unsettledActions } : {}),
             ...(this.#toolParams.size > 0
                 ? {
                     toolParams: Object.fromEntries([...this.#toolParams].map(([tool, params]) => [tool, Object.fromEntries(params)])),
@@ -269,25 +504,87 @@ export class SessionMetrics {
             browserMs: this.#browserMs,
             browserCommands: this.#browserCommands,
             peakConcurrentTools: this.#peakConcurrent,
-            unknownToolCalls: this.#unknownToolCalls,
+            unknownToolCalls: final ? this.#lifetimeUnknownToolCalls : this.#unknownToolCalls,
+            ...(this.#unknownTools.size > 0
+                ? { unknownTools: Object.fromEntries(this.#unknownTools) }
+                : {}),
             ...(machine !== undefined ? { machine } : {}),
             ...(this.#clients.size > 0 ? { clients: [...this.#clients] } : {}),
+            ...(this.#clientVersions.size > 0
+                ? { clientVersions: Object.fromEntries(this.#clientVersions) }
+                : {}),
+            ...(this.#surface === undefined ? {} : { surface: this.#surface }),
+            ...(final ? { endReason: this.#endReason() } : {}),
+            ...(this.#feedbackPrompted > 0 ? { feedbackPrompted: this.#feedbackPrompted } : {}),
+            ...(this.#errorClasses.size > 0
+                ? { errorClasses: Object.fromEntries(this.#errorClasses) }
+                : {}),
+            ...(this.#errorsRecovered > 0 ? { errorsRecovered: this.#errorsRecovered } : {}),
+            ...(this.#errorsRepeated > 0 ? { errorsRepeated: this.#errorsRepeated } : {}),
+            // Always present, including zero: absence and "no app ever connected" must not look alike,
+            // because zero IS the finding here.
+            appConnects: this.#appConnects,
+            ...(this.#firstAppAt === undefined
+                ? {}
+                : { msToFirstApp: Math.max(0, this.#firstAppAt - this.#startedAt) }),
             final,
+            // Only on a real exit. A periodic flush carrying `exit: "unknown"` would read as a daemon that
+            // died without a shutdown path, which is the one thing this field exists to make visible.
+            ...(final && exit !== undefined ? { exit } : {}),
         };
     }
+    /**
+     * Decide whether the error before the previous call was recovered from or repeated.
+     *
+     * Called at the start of each new call (resolving the one before it) and once at summarize (for
+     * the last call). Shifting rather than counting on the spot is what makes "the agent tried
+     * something else and it worked" distinguishable from "it failed the same way again" — an earlier
+     * version counted a recovery the moment a call STARTED, so a call that then failed was recorded
+     * as a success.
+     */
+    #resolveRecovery() {
+        if (this.#priorCallErrored) {
+            if (this.#currentCallErrored)
+                this.#errorsRepeated += 1;
+            else
+                this.#errorsRecovered += 1;
+        }
+        this.#priorCallErrored = this.#currentCallErrored;
+        this.#currentCallErrored = false;
+    }
+    /**
+     * What state the agent's work was in at the end. Ordered by which fact outranks which: a client
+     * that left explains everything after it, and a verdict settles whatever preceded it.
+     */
+    #endReason() {
+        if (0 === this.#lifetimeToolCalls)
+            return 'never_used';
+        if (this.#clientLeft)
+            return 'client_left';
+        if (this.#unsettledActions > 0)
+            return 'abandoned';
+        if (this.#lifetimeVerifications > 0)
+            return 'verified';
+        return 'explored';
+    }
     /** True when nothing at all happened — a flush of an idle daemon is not worth an event. */
     get empty() {
-        return (this.#toolCalls === 0 &&
-            this.#verifications === 0 &&
-            this.#toolErrors === 0 &&
-            this.#bugsFound === 0 &&
-            this.#sdkFailures === 0);
+        return (0 === this.#toolCalls &&
+            0 === this.#verifications &&
+            0 === this.#toolErrors &&
+            0 === this.#bugsFound &&
+            0 === this.#sdkFailures);
     }
     /** Zero the counters after a non-final flush so the next flush reports the NEXT window, not a total. */
     reset() {
         this.#toolCalls = 0;
         this.#toolErrors = 0;
         this.#verifications = 0;
+        this.#noSessionErrors = 0;
+        this.#repeatRuns.clear();
+        this.#lastTool = undefined;
+        this.#currentRun = 0;
+        this.#unsettledActions = 0;
         this.#toolCounts.clear();
         this.#toolParams.clear();
         this.#errorKinds.clear();
@@ -302,7 +599,10 @@ export class SessionMetrics {
         this.#unknownToolCalls = 0;
         this.#bugsFound = 0;
         this.#bugKinds.clear();
-        this.#seenBugKinds.clear();
+        // #seenBugKinds is deliberately NOT cleared. It is not a window counter — it is the
+        // session-lifetime memory behind `repeat` on bug_found, and zeroing it made the same defect,
+        // found again after a flush, report as a newly distinct one. Sessions run to 11.5 hours in the
+        // data, so that was up to 23 chances to count one defect many times.
     }
 }
 function bump(map, key) {

package/dist/telemetry/telemetry.d.ts

@@ -1,4 +1,38 @@
-import { TelemetryEventKind, type Crash, type Feedback, type Identity, type BugFound, type InitOutcome, type McpConnection, type ProjectProfile, type SessionSummary, type TelemetryActor, type Verification, type VersionChange } from '@reticlehq/core';
+import { TelemetryEventKind, ProjectIdSource, type Crash, type Feedback, type Identity, type BugFound, type InitOutcome, type McpConnection, type McpOutage, type ProjectProfile, type SessionSummary, type TelemetryActor, type Verification, type VersionChange } from '@reticlehq/core';
+/**
+ * Feedback gets its own, much larger budget — and a retry.
+ *
+ * 2s + drop is right for a usage counter: the metric is worthless if it costs the user latency, and
+ * losing one changes nothing. Feedback is the opposite on both counts. It is the only qualitative
+ * channel the product has, it carries an agent's entire root-cause analysis, and losing one loses
+ * work that cannot be reconstructed.
+ *
+ * Measured to the collector with a WARM DNS cache: dns 0.003s, connect 0.233s, tls 0.467s, total
+ * 0.694s — a third of the old budget gone before any payload moves, on the good path. A fresh
+ * short-lived CLI process pays cold DNS and a cold route on top, which is exactly the case that
+ * failed in the field and then succeeded on retry from a warmer process.
+ */
+export declare const FEEDBACK_TIMEOUT_MS = 15000;
+export declare const FEEDBACK_RETRIES = 1;
+export declare const FEEDBACK_RETRY_BACKOFF_MS = 750;
+/**
+ * One-way project fingerprint: distinct-count of this = "projects Reticle is used in", reveals nothing.
+ *
+ * Prefers a hash of the git ORIGIN over a hash of the cwd. The contract in `@reticlehq/core` always
+ * said "one-way hash of the git remote (or cwd)", but the implementation only ever hashed the path —
+ * which meant the same repo cloned by four teammates, or checked out twice on one machine, counted as
+ * four separate projects. That inflates the project count and, worse, makes team adoption look like
+ * unrelated individuals. Hashing the origin dedupes a real project down to one id across every clone.
+ *
+ * Still one-way, still non-reversible, and still exactly what the published policy describes: the
+ * remote URL itself never leaves the machine, only its SHA-256. The URL is normalized first (scheme,
+ * credentials, `.git` suffix and case removed) so `git@github.com:acme/web.git` and
+ * `https://github.com/Acme/web` are recognized as the same project rather than two.
+ */
+export declare const projectFingerprint: (cwd: string) => {
+    projectId: string;
+    source: ProjectIdSource;
+};
 /** The current telemetry state and which control set it — what `reticle telemetry status` prints. */
 export declare const describeTelemetry: (env?: NodeJS.ProcessEnv, dir?: string, cwd?: string) => {
     enabled: boolean;
@@ -38,6 +72,8 @@ export interface TelemetryExtra {
     init?: InitOutcome;
     /** `bug_found`: one defect Reticle found in the app under test. */
     bug?: BugFound;
+    /** `mcp_connection_lost`: the agent lost its tools — which stage, and why. */
+    outage?: McpOutage;
 }
 export interface Telemetry {
     /**
@@ -45,7 +81,14 @@ export interface Telemetry {
      * CLI process can exit immediately instead of waiting out the POST (use it from command entry
      * points; daemon-side events send in-process).
      */
-    emit(kind: TelemetryEventKind, extra?: TelemetryExtra): Promise<void>;
+    /**
+     * Send one event. Resolves to whether it was DELIVERED.
+     *
+     * Almost every caller ignores the result and should — a lost metric must never surface to a user.
+     * `reticle_feedback` is the exception: it hands a receipt to an agent, and reporting "filed" for a
+     * send that failed loses the report and lies about it in the same breath.
+     */
+    emit(kind: TelemetryEventKind, extra?: TelemetryExtra): Promise<boolean>;
     readonly enabled: boolean;
     /** True the very first run on this machine — the CLI emits INSTALL alongside the first INVOKE. */
     readonly firstRun: boolean;