@reticlehq/server 2.6.0 → 2.8.0

package/dist/telemetry/bug-found.js

@@ -16,7 +16,7 @@
  * anyone's app: that a class of defect was found, never what it was found in.
  */
 import { ReticleTool } from '../tools/tool-names.js';
-import { BugSource, ContradictionKind } from '@reticlehq/core';
+import { BugAttribution, BugSource, ContradictionKind, isAbsenceDerived, } from '@reticlehq/core';
 /** Cap per tool call — a pathological crawl must not turn one call into a thousand events. */
 const MAX_BUGS_PER_CALL = 25;
 function kindsOf(value) {
@@ -90,25 +90,35 @@ function couldNotRun(failure) {
         true === failure.couldNotRun);
 }
 /**
- * `bug.attribution` was REMOVED, deliberately, and this note is here so it is not re-added casually.
+ * WHOSE fault a contradiction was.
  *
- * It shipped twice and was wrong both times. First it stamped `app` on every contradiction, including
- * `request-never-settled` — which Reticle raises from the ABSENCE of a settle event, so a dev-overlay
- * poll manufactured it with the app doing nothing wrong. That was fixed, and a real drive then found
- * it still inverted: across two full runs, EVERY `attribution: 'app'` was a misattribution, while the
- * one defect that genuinely was a bad agent predicate carried none. One session would have published
- * "2 defects in the app" against a true count of 0.
+ * `attribution` shipped twice and was wrong both times. It stamped `app` on every contradiction,
+ * including `request-never-settled` — which Reticle raises from the ABSENCE of a settle event, so a
+ * dev-overlay poll manufactured it with the app doing nothing wrong. Across two full real drives
+ * EVERY `attribution: 'app'` was a misattribution, while the one defect that genuinely was a bad
+ * agent predicate carried none. A metric confidently wrong about whose fault a defect is, is worse
+ * than no metric: it is the number a founder steers on, and it points at the customer.
  *
- * A metric that is confidently wrong about WHOSE fault a defect is, is worse than no metric: it is
- * the number a founder steers on, and it points at the customer. Counting nothing is recoverable;
- * publishing a false accusation about somebody's product is not.
+ * The evidence that was missing then exists now, and it is already drawn in core for the verdict:
+ * `ABSENCE_DERIVED_CONTRADICTIONS` separates the kinds inferred from something NOT having happened
+ * inside a window Reticle chose the end of, from the kinds positively OBSERVED — a request that came
+ * back failed, a signal the app fired that disagrees with its own screen, a written field echoed
+ * back changed. Only the second class is evidence against the app, and it is the same line that
+ * decides whether a verdict may say `no`. Reusing it rather than inventing a second judgement beside
+ * it is the whole point: every historical misattribution was an absence-derived kind, so this rule
+ * produces zero of them on the data that broke the last two versions.
  *
- * Bringing it back needs evidence that actually separates the cases. It does not exist in the payload
- * today: `element.present` covers "the button is missing", "the API is down" and "the agent mistyped
- * a testid" identically, and `signal.absent` covers both a signal the app never fired and a ref
- * Reticle drove into nothing. Until a verdict carries the reason it came out that way, the honest
- * output is no owner at all.
+ * Everything else — a failed assertion, a replay regression, a crawl anomaly that is not a
+ * contradiction — is `unclassified`, which is a VALUE and not a gap. A failed `element.present`
+ * covers "the button is missing", "the API is down" and "the agent mistyped a testid" identically,
+ * and a console error can be the app, a browser extension or a framework dev overlay. Guessing there
+ * puts a guess into the one number we intend to publish. See issue #122.
  */
+function attributionOf(kind) {
+    return CONTRADICTION_KINDS.has(kind) && !isAbsenceDerived(kind)
+        ? BugAttribution.APP
+        : BugAttribution.UNCLASSIFIED;
+}
 export function bugsInResult(toolName, result) {
     // `reticle_run` is a WRAPPER: its handler calls runTool on the real tool, which already reported
     // that result's defects under the real tool's name — then the outer chokepoint reports the very
@@ -133,6 +143,7 @@ export function bugsInResult(toolName, result) {
             kind,
             falseGreen: passed,
             tool: toolName,
+            attribution: attributionOf(kind),
         });
     }
     // 2. Crawl anomalies — found autonomously, with nobody writing a test. Crawl reports its own
@@ -148,8 +159,9 @@ export function bugsInResult(toolName, result) {
             // — even though no assertion was made. See the definition on `falseGreen`.
             falseGreen: CONTRADICTION_KINDS.has(kind),
             tool: toolName,
-            // Nobody wrote a predicate here, so there is no bad request to blame: a crawl anomaly is a
-            // fault the app produced on its own.
+            // Same kind, same owner, wherever it arrives. A `request-never-settled` found by the crawler
+            // is no better evidence about whose fault it was than one found by an assertion.
+            attribution: attributionOf(kind),
         });
     }
     // 3. A failed assertion — the agent declared a consequence and it did not hold.
@@ -167,7 +179,9 @@ export function bugsInResult(toolName, result) {
             kind,
             falseGreen: false,
             tool: toolName,
-            // Omitted when the label cannot say whose fault it was — see ASSERTION_ATTRIBUTION.
+            // The assertion label cannot say whose fault it was: `element.present` covers a missing
+            // button, a downed API and a mistyped testid identically.
+            attribution: BugAttribution.UNCLASSIFIED,
         });
     }
     // 4. Replay failures — a saved flow that used to pass no longer does. That is a regression caught,
@@ -184,8 +198,11 @@ export function bugsInResult(toolName, result) {
                 kind: 'flow-regression',
                 falseGreen: false,
                 tool: toolName,
-                // A saved flow that used to pass and no longer does is a regression in the app. Rows that
-                // never RAN are skipped above precisely so Reticle's own failures do not land here.
+                // A flow that used to pass and no longer does is a regression SOMEWHERE, and the row does
+                // not say where: the app changed, or a selector strategy of ours did. Rows that never RAN
+                // are skipped above, which keeps Reticle's outright failures out of the count entirely, but
+                // that is a weaker fact than the positive evidence `app` requires.
+                attribution: BugAttribution.UNCLASSIFIED,
             });
         }
     }

package/dist/telemetry/cli-telemetry.js

@@ -8,6 +8,7 @@ import { TelemetryEventKind } from '@reticlehq/core';
 import { DAEMON_INNER_COMMAND, knownCommand } from '../cli/cli-parse.js';
 import { getTelemetry } from './telemetry.js';
 import { describeCliFlags } from './argument-shape.js';
+import { resolveInstallSource } from './install-source.js';
 /**
  * Report that a person ran a `reticle` subcommand.
  *
@@ -45,7 +46,12 @@ export function reportCliRun(argv) {
     // installed the SDK into nine apps — the top of every funnel, missing.
     // `detach` so a quick command (`version`/`gate`) exits immediately instead of waiting out the POST.
     if (telemetry.firstRun)
-        void telemetry.emit(TelemetryEventKind.RETICLE_INSTALLED, { detach: true });
+        void telemetry.emit(TelemetryEventKind.RETICLE_INSTALLED, {
+            detach: true,
+            // WHICH published route brought this machine in. Self-declared by the channel, never inferred
+            // — see install-source.ts for which of the four routes can actually carry the marker.
+            installSource: resolveInstallSource(),
+        });
     if (!isHumanCliCommand(command))
         return;
     void telemetry.emit(TelemetryEventKind.CLI_COMMAND_RUN, {

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

@@ -24,10 +24,10 @@ export declare const SESSION_FLUSH_MS: number;
  * tick — a closed laptop, OOM, `kill -9`, a force-quit editor — reaches no shutdown handler and has
  * emitted nothing, so the whole session is invisible.
  *
- * Measured 2026-08-10/11 (non-CI): **614 `daemon_started` against 499 `daemon_stopped` — 19% of
- * sessions never reported a summary at all.** Every "did anyone use Reticle" number is computed on
- * the 81% that did, and undercounts by an unknown amount, which is the one thing a funnel metric
- * must not do.
+ * In the field `daemon_started` outran `daemon_stopped` by a wide margin: **a meaningful share of
+ * sessions never reported a summary at all.** Every "did anyone use Reticle" number is computed only
+ * on the sessions that did, and undercounts by an unknown amount, which is the one thing a funnel
+ * metric must not do.
  *
  * Ninety seconds is chosen against what it protects: a session that did real work usually does it
  * early (snapshot -> act -> assert is seconds), so one early tick captures nearly all of it. It

package/dist/telemetry/daemon-telemetry.js

@@ -12,6 +12,7 @@ import { getSessionMetrics } from './session-metrics.js';
 import { profileProject } from './project-profile.js';
 import { startUpdateCheck } from '../update/update-nudge.js';
 import { markDaemonStart } from './mcp-connection.js';
+import { markInstrumentationClock } from './app-instrumented.js';
 /** Let the daemon finish coming up before walking the source tree for a profile. */
 const PROJECT_PROFILE_DELAY_MS = 5_000;
 /**
@@ -31,10 +32,10 @@ export const SESSION_FLUSH_MS = 5 * 60 * 1000;
  * tick — a closed laptop, OOM, `kill -9`, a force-quit editor — reaches no shutdown handler and has
  * emitted nothing, so the whole session is invisible.
  *
- * Measured 2026-08-10/11 (non-CI): **614 `daemon_started` against 499 `daemon_stopped` — 19% of
- * sessions never reported a summary at all.** Every "did anyone use Reticle" number is computed on
- * the 81% that did, and undercounts by an unknown amount, which is the one thing a funnel metric
- * must not do.
+ * In the field `daemon_started` outran `daemon_stopped` by a wide margin: **a meaningful share of
+ * sessions never reported a summary at all.** Every "did anyone use Reticle" number is computed only
+ * on the sessions that did, and undercounts by an unknown amount, which is the one thing a funnel
+ * metric must not do.
  *
  * Ninety seconds is chosen against what it protects: a session that did real work usually does it
  * early (snapshot -> act -> assert is seconds), so one early tick captures nearly all of it. It
@@ -53,6 +54,9 @@ export function installDaemonTelemetry(cwd, now = () => Date.now()) {
     // this, so a published fix was invisible until someone manually ran `reticle update`.
     startUpdateCheck(now);
     markDaemonStart(now());
+    // Same clock, different half of the install: one measures how long before an AGENT attached, this
+    // one how long before an APP did. The gap between them is the funnel.
+    markInstrumentationClock(now());
     // One profile per daemon start: what kind of project this is and how deeply Reticle is used in it.
     // Deferred off the boot path — it walks the source tree, and nothing about a daemon coming up
     // should wait on a filesystem scan.

package/dist/telemetry/feedback.js

@@ -147,7 +147,7 @@ export async function submitFeedback(input, opts = {}) {
             // Reticle SOURCE CHECKOUT disables telemetry by cwd, and that is exactly where release runs and
             // contributor sessions happen — so the reports most worth having were the ones silently lost.
             reason: isReticleSourceCheckout(opts.cwd ?? process.cwd())
-                ? 'this is a Reticle source checkout, where telemetry is disabled by design — so feedback has nowhere to go. Open an issue at https://github.com/reticlehq/reticle/issues instead, or run from the app you are verifying.'
+                ? 'this is a Reticle source checkout, where telemetry is disabled by design, so feedback has nowhere to go. Open an issue at https://github.com/reticlehq/reticle/issues instead, or run from the app you are verifying.'
                 : `telemetry is disabled on this machine, so feedback has nowhere to go. Re-enable with \`reticle telemetry enable\`, or open an issue at https://github.com/reticlehq/reticle/issues.`,
             redacted,
             context,

package/dist/telemetry/init-telemetry.js

@@ -12,6 +12,7 @@
  */
 import { TelemetryEventKind } from '@reticlehq/core';
 import { getTelemetry } from './telemetry.js';
+import { resolveInstallSource } from './install-source.js';
 /** Classified init failures — our own vocabulary, never a raw error or a path. */
 export const InitFailure = {
     /** Run outside a project root. The single most common first-run mistake. */
@@ -25,7 +26,14 @@ export const InitFailure = {
 /** Report one init outcome. Best-effort; setup must never fail because a metric did. */
 export function reportInitOutcome(init) {
     try {
-        void getTelemetry().emit(TelemetryEventKind.INIT_COMPLETED, { init, detach: true });
+        void getTelemetry().emit(TelemetryEventKind.INIT_COMPLETED, {
+            init,
+            detach: true,
+            // The other half of attribution: `reticle_installed` says a machine arrived, this says the
+            // setup on it finished, and only together do they say which route converts. Same self-declared
+            // marker, same refusal to infer — see install-source.ts.
+            installSource: resolveInstallSource(),
+        });
     }
     catch {
         /* a metric must never break `reticle init` */

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

@@ -0,0 +1,36 @@
+/**
+ * Which published route brought an install in.
+ *
+ * Four install routes ship at once and none of them could be told apart, so every question about
+ * where distribution effort is working had no data behind it at all.
+ *
+ * ONE mechanism: an environment variable a channel sets on itself. Everything else that looked like
+ * a signal turned out not to be one — see `InstallSource` in core for why `npm_config_user_agent`,
+ * a `.claude-plugin/` directory and an installed skill folder all fail to separate these routes.
+ *
+ * WHICH CHANNELS ARE GENUINELY DETECTABLE TODAY, so nobody later reads a small `unknown` as success:
+ *  - `plugin` — real. The Claude Code plugin registers the MCP server itself and can set the marker
+ *    in that server's `env`, so it is carried by the process without anybody typing anything.
+ *  - `skill_file` / `npx_skill` / `docs_site` / `readme` — real ONLY where that channel's own copy
+ *    of the install command carries the marker. Each is a separately published artifact, so a copy
+ *    that has not been updated is indistinguishable from no channel at all.
+ *  - `cli_direct` — NOT detectable. Nobody types a marker to say they typed a command. It exists so
+ *    a wrapper can declare it, and until something does, a direct install reports `unknown`.
+ *
+ * `unknown` is therefore expected to be the largest bucket for as long as the marker is spreading,
+ * and shrinking it is a distribution job, never a classifier job. A guessed attribution is worse
+ * than none: it is the number distribution decisions get steered on, and a guess and a measurement
+ * are indistinguishable once they are in the same column.
+ */
+import { InstallSource } from '@reticlehq/core';
+/** The one marker. Set by a channel on the process that runs the install. */
+export declare const INSTALL_SOURCE_ENV = "RETICLE_INSTALL_SOURCE";
+/**
+ * The declared install source, or `unknown`.
+ *
+ * Narrowed against the closed list rather than echoed: an echo would forward whatever somebody
+ * exported — a path, a URL, a campaign string — straight onto the wire, which is the rule this
+ * whole contract is built on. Trimmed and lowercased first, because the marker travels through
+ * shell snippets and copy-paste, and `Skill_File` is the same channel as `skill_file`.
+ */
+export declare function resolveInstallSource(env?: NodeJS.ProcessEnv): InstallSource;

package/dist/telemetry/install-source.js

@@ -0,0 +1,40 @@
+/**
+ * Which published route brought an install in.
+ *
+ * Four install routes ship at once and none of them could be told apart, so every question about
+ * where distribution effort is working had no data behind it at all.
+ *
+ * ONE mechanism: an environment variable a channel sets on itself. Everything else that looked like
+ * a signal turned out not to be one — see `InstallSource` in core for why `npm_config_user_agent`,
+ * a `.claude-plugin/` directory and an installed skill folder all fail to separate these routes.
+ *
+ * WHICH CHANNELS ARE GENUINELY DETECTABLE TODAY, so nobody later reads a small `unknown` as success:
+ *  - `plugin` — real. The Claude Code plugin registers the MCP server itself and can set the marker
+ *    in that server's `env`, so it is carried by the process without anybody typing anything.
+ *  - `skill_file` / `npx_skill` / `docs_site` / `readme` — real ONLY where that channel's own copy
+ *    of the install command carries the marker. Each is a separately published artifact, so a copy
+ *    that has not been updated is indistinguishable from no channel at all.
+ *  - `cli_direct` — NOT detectable. Nobody types a marker to say they typed a command. It exists so
+ *    a wrapper can declare it, and until something does, a direct install reports `unknown`.
+ *
+ * `unknown` is therefore expected to be the largest bucket for as long as the marker is spreading,
+ * and shrinking it is a distribution job, never a classifier job. A guessed attribution is worse
+ * than none: it is the number distribution decisions get steered on, and a guess and a measurement
+ * are indistinguishable once they are in the same column.
+ */
+import { InstallSource } from '@reticlehq/core';
+/** 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));
+/**
+ * The declared install source, or `unknown`.
+ *
+ * Narrowed against the closed list rather than echoed: an echo would forward whatever somebody
+ * exported — a path, a URL, a campaign string — straight onto the wire, which is the rule this
+ * whole contract is built on. Trimmed and lowercased first, because the marker travels through
+ * shell snippets and copy-paste, and `Skill_File` is the same channel as `skill_file`.
+ */
+export function resolveInstallSource(env = process.env) {
+    const declared = (env[INSTALL_SOURCE_ENV] ?? '').trim().toLowerCase();
+    return KNOWN.has(declared) ? declared : InstallSource.UNKNOWN;
+}

package/dist/telemetry/run-telemetry.js

@@ -10,7 +10,7 @@
  * finished, already-classified verdict, so this cannot double-count and does not need to understand
  * how a replay works.
  */
-import { BugSource, RunFlowStatus, TelemetryActor, TelemetryEventKind, VerdictStatus, } from '@reticlehq/core';
+import { BugAttribution, BugSource, RunFlowStatus, TelemetryActor, TelemetryEventKind, VerdictStatus, } from '@reticlehq/core';
 import { getSessionMetrics } from './session-metrics.js';
 import { getTelemetry } from './telemetry.js';
 /** The tool name reported for this path, so CI runs are distinguishable from agent-driven ones. */
@@ -52,6 +52,9 @@ export function reportRunTelemetry(run) {
                     falseGreen: false,
                     tool: VERIFY_SURFACE,
                     repeat: !first,
+                    // A regression SOMEWHERE, and the row does not say where — the app changed, or a selector
+                    // strategy of ours did. `app` needs positive evidence; see bug-found.ts.
+                    attribution: BugAttribution.UNCLASSIFIED,
                 },
             });
         }

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

@@ -73,10 +73,10 @@ export declare class SessionMetrics {
     /**
      * 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
+     * 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`, non-zero in 58 sessions); it was reported to US and never to the agent.
+     * (`abandonedActions`); 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

package/dist/telemetry/session-metrics.js

@@ -70,7 +70,7 @@ export class SessionMetrics {
      * 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
+     * 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
@@ -332,10 +332,10 @@ export class SessionMetrics {
     /**
      * 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
+     * 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`, non-zero in 58 sessions); it was reported to US and never to the agent.
+     * (`abandonedActions`); 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
@@ -515,6 +515,11 @@ export class SessionMetrics {
                 : {}),
             ...(this.#surface === undefined ? {} : { surface: this.#surface }),
             ...(final ? { endReason: this.#endReason() } : {}),
+            // The headline metric, as a FIELD. Read off the lifetime counter, because every other
+            // verification number in this payload is windowed and a reader who summed the wrong one got a
+            // different question's answer. `false` is sent, not omitted: a session that drove an app and
+            // never asked whether it worked is the whole finding.
+            ...(final ? { endedWithVerdict: this.#lifetimeVerifications > 0 } : {}),
             ...(this.#feedbackPrompted > 0 ? { feedbackPrompted: this.#feedbackPrompted } : {}),
             ...(this.#errorClasses.size > 0
                 ? { errorClasses: Object.fromEntries(this.#errorClasses) }

package/dist/telemetry/telemetry.d.ts

@@ -1,4 +1,4 @@
-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';
+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';
 /**
  * Feedback gets its own, much larger budget — and a retry.
  *
@@ -72,8 +72,14 @@ export interface TelemetryExtra {
     init?: InitOutcome;
     /** `bug_found`: one defect Reticle found in the app under test. */
     bug?: BugFound;
+    /** `tool_refused`: a call Reticle could not serve, and why. */
+    refusal?: ToolRefusal;
     /** `mcp_connection_lost`: the agent lost its tools — which stage, and why. */
     outage?: McpOutage;
+    /** `app_instrumented`: an app carrying the SDK reached this daemon for the first time. */
+    instrumentation?: AppInstrumentation;
+    /** `reticle_installed` / `init_completed`: which published route brought this install in. */
+    installSource?: InstallSource;
 }
 export interface Telemetry {
     /**

package/dist/telemetry/telemetry.js

@@ -71,6 +71,7 @@ const DETACHED_SEND_SCRIPT = "fetch(process.argv[1],{method:'POST',headers:{'con
 /** Env var names — mirror cloud-sync's `RETICLE_*` convention. */
 import { isReticleSourceCheckout } from './dev-repo.js';
 import { gitFacts } from './git-facts.js';
+import { currentAutomationHint } from './automation-hint.js';
 const Env = {
     DISABLE: 'RETICLE_TELEMETRY', // "0" / "false" / "off" → disabled
     DO_NOT_TRACK: 'DO_NOT_TRACK', // the cross-tool opt-out convention (any truthy value)
@@ -200,7 +201,7 @@ export const describeTelemetry = (env = process.env, dir = RETICLE_DIR, cwd = pr
     if (isReticleSourceCheckout(cwd)) {
         return {
             enabled: false,
-            reason: 'this is a Reticle source checkout — developing it is not using it',
+            reason: 'this is a Reticle source checkout; developing it is not using it',
             policyUrl: POLICY_URL,
         };
     }
@@ -259,6 +260,9 @@ export const createTelemetry = (opts) => {
     const doFetch = opts.fetchImpl ?? fetch;
     const url = `${(env[Env.URL] ?? DEFAULT_URL).replace(/\/+$/, '')}${TELEMETRY_PATH}`;
     const ci = env[Env.CI] !== undefined && env[Env.CI] !== '';
+    // Read once per process, next to `ci` and never instead of it: this is a second angle on the same
+    // question, and the rule that it can never filter a row lives in automation-hint.ts.
+    const automation = currentAutomationHint(env);
     const os = platform();
     // Negated so it reads the way people say it: UTC+2 is +120, not -120.
     const tzOffsetMin = -new Date().getTimezoneOffset();
@@ -300,6 +304,9 @@ export const createTelemetry = (opts) => {
             ts: now(),
             version: opts.version,
             ci,
+            // A SCALAR, so it needs the event build and the wire schema and no `blocks` entry — the same
+            // three-place trap `outage` fell into, and `installSource` documents below.
+            ...(automation !== undefined ? { automation } : {}),
             os,
             tzOffsetMin,
             projectIdSource,
@@ -316,14 +323,20 @@ export const createTelemetry = (opts) => {
             ...(extra?.connection !== undefined ? { connection: extra.connection } : {}),
             ...(extra?.init !== undefined ? { init: extra.init } : {}),
             ...(extra?.bug !== undefined ? { bug: extra.bug } : {}),
+            ...(extra?.refusal !== undefined ? { refusal: extra.refusal } : {}),
             ...(extra?.outage !== undefined ? { outage: extra.outage } : {}),
+            ...(extra?.instrumentation !== undefined ? { instrumentation: extra.instrumentation } : {}),
+            // A SCALAR, so it needs the event build and the wire schema but no entry in `blocks` below —
+            // there is nothing to flatten. It still needs both of those, which is the trap `outage` fell
+            // into: a field declared on TelemetryExtra and missing from either one is dropped in silence.
+            ...(extra?.installSource !== undefined ? { installSource: extra.installSource } : {}),
         };
         // Map the core contract onto PostHog's capture shape: id/name/time move up, the rest are properties.
         // The feedback body is FLATTENED into `feedback_*` properties rather than sent as a nested object:
         // 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, outage, ...rest } = event;
+        const { anonymousId: distinctId, event: name, ts, sessionId: eventSessionId, feedback, session, project, verification, versionChange, crash, identity, connection, init, 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
@@ -351,7 +364,9 @@ export const createTelemetry = (opts) => {
             connection,
             init,
             bug,
+            refusal,
             outage,
+            instrumentation,
         };
         for (const [prefix, block] of Object.entries(blocks)) {
             for (const [key, value] of Object.entries(block ?? {})) {

package/dist/telemetry/tool-refused.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Reporting the calls Reticle could not serve.
+ *
+ * The refusal path is the largest thing this product does and the least measured one. It computes a
+ * precise diagnosis — which of three no-session situations this is, that a ref went stale, that a
+ * predicate did not parse — hands it to the agent as prose, and throws it away. So a user who
+ * attaches an agent, hits a wall on the first call and never comes back emits nothing at all, and
+ * the whole cohort is visible only as the gap between two other numbers. See issue #172.
+ *
+ * Emitted from `runTool`, which is the one place both dispatch paths cross, so a tool added later is
+ * covered without anybody remembering to cover it.
+ */
+import { type RefusalReason } from '@reticlehq/core';
+/** A call that was served. Breaks the retry chain: what follows it is not a retry of anything. */
+export declare function noteToolServed(): void;
+/** One refused call, reported with its cause and whether it was itself a retry. */
+export declare function reportToolRefused(tool: string, reason: RefusalReason): void;
+/** Tests only — the counters are process-lifetime, so each case has to start from zero. */
+export declare function resetToolRefusals(): void;

package/dist/telemetry/tool-refused.js

@@ -0,0 +1,55 @@
+/**
+ * Reporting the calls Reticle could not serve.
+ *
+ * The refusal path is the largest thing this product does and the least measured one. It computes a
+ * precise diagnosis — which of three no-session situations this is, that a ref went stale, that a
+ * predicate did not parse — hands it to the agent as prose, and throws it away. So a user who
+ * attaches an agent, hits a wall on the first call and never comes back emits nothing at all, and
+ * the whole cohort is visible only as the gap between two other numbers. See issue #172.
+ *
+ * Emitted from `runTool`, which is the one place both dispatch paths cross, so a tool added later is
+ * covered without anybody remembering to cover it.
+ */
+import { TelemetryActor, TelemetryEventKind } from '@reticlehq/core';
+import { getTelemetry } from './telemetry.js';
+/**
+ * Refusal events one daemon run will send.
+ *
+ * Volume is part of this taxonomy's design — the per-tool-call event was removed for exactly this
+ * reason — and a stuck agent retrying one failing call is the shape most likely to produce hundreds.
+ * The cap means the bill cannot scale with the pathology while the SHAPE of it still arrives: the
+ * first fifty carry the tool, the cause and the retry flag, and `consecutiveRepeats` on the session
+ * summary already reports how long the loop ran.
+ */
+const MAX_REFUSALS_PER_SESSION = 50;
+let sent = 0;
+/**
+ * The tool whose call refused immediately before this one, if the last call refused at all.
+ *
+ * This is what `retried` is computed from, and it is why the event is sent at the moment of the
+ * refusal rather than held back until the next call reveals whether one came. Holding it back would
+ * lose the event entirely for an agent that gives up — which is precisely the agent this exists to
+ * describe — so the flag lands on the RETRY instead of on the first refusal.
+ */
+let lastRefusedTool;
+/** A call that was served. Breaks the retry chain: what follows it is not a retry of anything. */
+export function noteToolServed() {
+    lastRefusedTool = undefined;
+}
+/** One refused call, reported with its cause and whether it was itself a retry. */
+export function reportToolRefused(tool, reason) {
+    const retried = lastRefusedTool === tool;
+    lastRefusedTool = tool;
+    if (sent >= MAX_REFUSALS_PER_SESSION)
+        return;
+    sent += 1;
+    void getTelemetry().emit(TelemetryEventKind.TOOL_REFUSED, {
+        actor: TelemetryActor.AGENT,
+        refusal: { tool, reason, retried },
+    });
+}
+/** Tests only — the counters are process-lifetime, so each case has to start from zero. */
+export function resetToolRefusals() {
+    sent = 0;
+    lastRefusedTool = undefined;
+}