@reticlehq/server 2.7.0 → 2.9.0

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

@@ -0,0 +1,56 @@
+/**
+ * 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;
+/**
+ * The install source declared by the environment, or undefined when nothing declared one.
+ *
+ * Distinct from `resolveInstallSource`, which answers `unknown` so an event always carries a value.
+ * A config file wants the opposite: writing `unknown` into `.reticle.json` is indistinguishable
+ * from a config written before this field existed, and those two are different facts.
+ */
+export declare function declaredInstallSource(env?: NodeJS.ProcessEnv): InstallSource | undefined;
+/**
+ * The install source for a project: what its config recorded, else what the environment declares.
+ *
+ * The config wins because it is the durable answer. The marker is an environment variable set by
+ * whichever channel ran the install, so it exists for exactly one command and is gone by the next
+ * one — which is why this field reached a handful of events and nothing else, and why the question
+ * it exists to answer could not be asked.
+ *
+ * Narrowed against the closed list on the way out, the same as the env path: a config file is user
+ * data, and a hand-edited one must not be able to put an arbitrary string on the wire.
+ */
+export declare function projectInstallSource(cwd: string, env?: NodeJS.ProcessEnv): InstallSource;

package/dist/telemetry/install-source.js

@@ -0,0 +1,74 @@
+/**
+ * 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';
+import { findProjectConfig } from '../cli/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));
+/**
+ * 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;
+}
+/**
+ * The install source declared by the environment, or undefined when nothing declared one.
+ *
+ * Distinct from `resolveInstallSource`, which answers `unknown` so an event always carries a value.
+ * A config file wants the opposite: writing `unknown` into `.reticle.json` is indistinguishable
+ * from a config written before this field existed, and those two are different facts.
+ */
+export function declaredInstallSource(env = process.env) {
+    const declared = (env[INSTALL_SOURCE_ENV] ?? '').trim().toLowerCase();
+    return KNOWN.has(declared) && InstallSource.UNKNOWN !== declared
+        ? declared
+        : undefined;
+}
+/**
+ * The install source for a project: what its config recorded, else what the environment declares.
+ *
+ * The config wins because it is the durable answer. The marker is an environment variable set by
+ * whichever channel ran the install, so it exists for exactly one command and is gone by the next
+ * one — which is why this field reached a handful of events and nothing else, and why the question
+ * it exists to answer could not be asked.
+ *
+ * Narrowed against the closed list on the way out, the same as the env path: a config file is user
+ * data, and a hand-edited one must not be able to put an arbitrary string on the wire.
+ */
+export function projectInstallSource(cwd, env = process.env) {
+    const recorded = findProjectConfig(cwd)?.['installSource'];
+    if ('string' === typeof recorded) {
+        const narrowed = recorded.trim().toLowerCase();
+        if (KNOWN.has(narrowed))
+            return narrowed;
+    }
+    return resolveInstallSource(env);
+}

package/dist/telemetry/instrumentation-stall.d.ts

@@ -0,0 +1,50 @@
+/**
+ * When a daemon has waited long enough that no app is coming.
+ *
+ * `app_instrumented` fires on success and only on success, so the population that matters most —
+ * daemons that never get an app wired at all — exists in the data only as an absence. An absence is
+ * the one thing telemetry cannot interpret: it cannot separate "nothing was ever wired" from "the
+ * process was killed before it could say so" from "we never sent the event". The funnel breaks at
+ * exactly this step and nowhere else, which makes it the one silence worth converting into a signal.
+ *
+ * Once per daemon run, and never after an app has connected. A daemon that takes a while and then
+ * works reports nothing at all: the question is "did this run ever get an app", and a run that did
+ * is not stalled no matter how long it took.
+ *
+ * The threshold is a judgement, not a measurement, and it is deliberately generous. Someone running
+ * `init` and then going to make coffee has not hit a defect, and calling that a stall would drown
+ * the real signal in ordinary human latency.
+ *
+ * Read the result against `agentAttached`, which is what makes it actionable: a stalled daemon with
+ * no agent is somebody who installed and walked away, and is not a defect. A stalled daemon WITH an
+ * agent attached is the failure the product actually has — the tools are loaded, something is asking
+ * for them, and there is nothing on the other end to drive.
+ */
+/**
+ * How long a daemon may sit with no app before it counts as stalled.
+ *
+ * Ten minutes sits well past setup latency — reading a doc, restarting a dev server, opening a tab —
+ * and well short of the half-hour idle windows that dominate the field, so a stall is reported while
+ * the session is still alive rather than inferred from its corpse.
+ */
+export declare const STALL_AFTER_MS: number;
+/** Start the clock. Called from the same place the instrumentation clock is marked. */
+export declare function markStallClock(now: number): void;
+export interface StallFacts {
+    /** Whether this project has a projectId stamped — i.e. `init` has run here. */
+    initialized: boolean;
+    /** Whether an MCP client is attached right now. */
+    agentAttached: boolean;
+}
+/**
+ * Report a stalled install, at most once per daemon run.
+ *
+ * Returns whether it emitted, so the caller's test can assert the once-only rule without reaching
+ * into the telemetry client. Best-effort like every other metric here: it must never be the reason
+ * a daemon misbehaves.
+ */
+export declare function reportInstrumentationStall(facts: StallFacts, now?: () => number, opts?: {
+    atShutdown?: boolean;
+}): boolean;
+/** Tests only. */
+export declare function resetInstrumentationStall(): void;

package/dist/telemetry/instrumentation-stall.js

@@ -0,0 +1,90 @@
+/**
+ * When a daemon has waited long enough that no app is coming.
+ *
+ * `app_instrumented` fires on success and only on success, so the population that matters most —
+ * daemons that never get an app wired at all — exists in the data only as an absence. An absence is
+ * the one thing telemetry cannot interpret: it cannot separate "nothing was ever wired" from "the
+ * process was killed before it could say so" from "we never sent the event". The funnel breaks at
+ * exactly this step and nowhere else, which makes it the one silence worth converting into a signal.
+ *
+ * Once per daemon run, and never after an app has connected. A daemon that takes a while and then
+ * works reports nothing at all: the question is "did this run ever get an app", and a run that did
+ * is not stalled no matter how long it took.
+ *
+ * The threshold is a judgement, not a measurement, and it is deliberately generous. Someone running
+ * `init` and then going to make coffee has not hit a defect, and calling that a stall would drown
+ * the real signal in ordinary human latency.
+ *
+ * Read the result against `agentAttached`, which is what makes it actionable: a stalled daemon with
+ * no agent is somebody who installed and walked away, and is not a defect. A stalled daemon WITH an
+ * agent attached is the failure the product actually has — the tools are loaded, something is asking
+ * for them, and there is nothing on the other end to drive.
+ */
+import { TelemetryEventKind } from '@reticlehq/core';
+import { getTelemetry } from './telemetry.js';
+import { appEverConnected } from './app-instrumented.js';
+/**
+ * How long a daemon may sit with no app before it counts as stalled.
+ *
+ * Ten minutes sits well past setup latency — reading a doc, restarting a dev server, opening a tab —
+ * and well short of the half-hour idle windows that dominate the field, so a stall is reported while
+ * the session is still alive rather than inferred from its corpse.
+ */
+export const STALL_AFTER_MS = 10 * 60 * 1000;
+let reported = false;
+let daemonStartedAt;
+/** Start the clock. Called from the same place the instrumentation clock is marked. */
+export function markStallClock(now) {
+    daemonStartedAt = now;
+    reported = false;
+}
+/**
+ * Report a stalled install, at most once per daemon run.
+ *
+ * Returns whether it emitted, so the caller's test can assert the once-only rule without reaching
+ * into the telemetry client. Best-effort like every other metric here: it must never be the reason
+ * a daemon misbehaves.
+ */
+export function reportInstrumentationStall(facts, now = () => Date.now(), opts = {}) {
+    if (reported)
+        return false;
+    // An app arrived. Whatever this run was, it was not stalled.
+    if (appEverConnected())
+        return false;
+    if (daemonStartedAt === undefined)
+        return false;
+    const waited = now() - daemonStartedAt;
+    // The threshold is a guard against crying stall seconds after boot. At SHUTDOWN there is nothing
+    // left to wait for: this daemon ran, no app ever connected, and it is now gone. That is a fact
+    // rather than an inference, and it does not become truer at ten minutes than at five.
+    //
+    // Skipping it here is what makes the event able to see anything at all. An UNATTENDED daemon
+    // idle-exits at DAEMON_IDLE_SHUTDOWN_MS (5 min), well short of STALL_AFTER_MS (10) — only an
+    // attached one gets the six-times grace that reaches the threshold. So on the periodic path alone
+    // `agentAttached` was forced to true on every row, and the bucket this event exists for —
+    // installed it, walked away, never wired the app — could not appear in the data at all.
+    //
+    // `msWaited` still carries the duration, so a consumer that wants to exclude short runs can do it
+    // on the data instead of being unable to see them.
+    if (true !== opts.atShutdown && waited < STALL_AFTER_MS)
+        return false;
+    reported = true;
+    try {
+        void getTelemetry().emit(TelemetryEventKind.INSTRUMENTATION_STALLED, {
+            stall: {
+                initialized: facts.initialized,
+                agentAttached: facts.agentAttached,
+                msWaited: Math.max(0, waited),
+            },
+        });
+    }
+    catch {
+        /* never let a metric interfere with a running daemon */
+    }
+    return true;
+}
+/** Tests only. */
+export function resetInstrumentationStall() {
+    reported = false;
+    daemonStartedAt = undefined;
+}

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

@@ -130,6 +130,14 @@ export declare class SessionMetrics {
      * false so a session killed before it can exit is not lost entirely (see the flush note in cli.ts).
      */
     summarize(final: boolean, exit?: SessionSummary['exit']): SessionSummary;
+    /**
+     * Has an agent ever attached to this daemon?
+     *
+     * Read by the instrumentation-stall check, which needs to tell two very different silences apart:
+     * a daemon nobody is using, and a daemon with an agent sitting on it that has no app to drive.
+     * The second is the funnel's failure case and the first is not a problem at all.
+     */
+    get agentEverAttached(): boolean;
     /** True when nothing at all happened — a flush of an idle daemon is not worth an event. */
     get empty(): boolean;
     /** Zero the counters after a non-final flush so the next flush reports the NEXT window, not a total. */

package/dist/telemetry/session-metrics.js

@@ -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) }
@@ -567,6 +572,16 @@ export class SessionMetrics {
             return 'verified';
         return 'explored';
     }
+    /**
+     * Has an agent ever attached to this daemon?
+     *
+     * Read by the instrumentation-stall check, which needs to tell two very different silences apart:
+     * a daemon nobody is using, and a daemon with an agent sitting on it that has no app to drive.
+     * The second is the funnel's failure case and the first is not a problem at all.
+     */
+    get agentEverAttached() {
+        return this.#clients.size > 0;
+    }
     /** True when nothing at all happened — a flush of an idle daemon is not worth an event. */
     get empty() {
         return (0 === this.#toolCalls &&

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 AppInstrumentation, 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 InstrumentationStall, type ProjectProfile, type SessionSummary, type TelemetryActor, type Verification, type VersionChange } from '@reticlehq/core';
 /**
  * Feedback gets its own, much larger budget — and a retry.
  *
@@ -72,10 +72,16 @@ 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;
+    /** `instrumentation_stalled`: the daemon waited and no app ever arrived. */
+    stall?: InstrumentationStall;
+    /** `reticle_installed` / `init_completed`: which published route brought this install in. */
+    installSource?: InstallSource;
 }
 export interface Telemetry {
     /**

package/dist/telemetry/telemetry.js

@@ -70,7 +70,9 @@ const DETACHED_SEND_SCRIPT = "fetch(process.argv[1],{method:'POST',headers:{'con
     '.catch(()=>{}).finally(()=>process.exit(0))';
 /** Env var names — mirror cloud-sync's `RETICLE_*` convention. */
 import { isReticleSourceCheckout } from './dev-repo.js';
+import { projectInstallSource } from './install-source.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 +202,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 +261,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();
@@ -270,6 +275,12 @@ export const createTelemetry = (opts) => {
      */
     const sessionId = randomUUID();
     const { projectId, source: projectIdSource } = projectFingerprint(opts.cwd ?? process.cwd());
+    // Resolved ONCE, beside projectId, and for the same reason: it is a property of this install, not
+    // of any one event. It used to be passed per-call and therefore rode only `reticle_installed` and
+    // `init_completed` — two of the rarest events there are — so the channel that brought a user in
+    // was unknown for every event that could show whether they got anywhere. Reading it here puts it
+    // on all of them, which is the only shape in which the question can be asked.
+    const installSource = projectInstallSource(opts.cwd ?? process.cwd());
     showNoticeOnce();
     const spawnDetached = opts.spawnImpl ??
         ((command, args) => {
@@ -300,6 +311,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,15 +330,23 @@ 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 } : {}),
+            ...(extra?.stall !== undefined ? { stall: extra.stall } : {}),
+            // 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.
+            // Always present now, rather than only when a caller remembered to pass it. A per-call
+            // override still wins so a command that genuinely knows better can say so.
+            installSource: extra?.installSource ?? 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, instrumentation, ...rest } = event;
+        const { anonymousId: distinctId, event: name, ts, sessionId: eventSessionId, feedback, session, project, verification, versionChange, crash, identity, connection, init, bug, refusal, outage, instrumentation, stall, ...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
@@ -352,8 +374,10 @@ export const createTelemetry = (opts) => {
             connection,
             init,
             bug,
+            refusal,
             outage,
             instrumentation,
+            stall,
         };
         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;
+}

package/dist/telemetry/verification-of.js

@@ -53,6 +53,38 @@ const SuiteStatus = {
     PASS: 'pass',
     FAIL: 'fail',
 };
+/**
+ * Did the assertion itself pass, across three tool shapes that spell it three ways.
+ *
+ * `reticle_assert` spreads its verdict at the top level, so `pass` is right there. `flow_verify`
+ * reports a suite `status`. **`reticle_act_and_wait` nests it under `verdict`**, and that omission is
+ * why `falseGreenCaught` had never once been true in the field: `passed` came back `undefined` for
+ * every act_and_wait, so `true === passed` was false whatever the app did, on the one tool the
+ * product tells agents to reach for first.
+ *
+ * The metric it feeds is the product's central claim reduced to a boolean, and it was structurally
+ * unable to fire on the flagship path. Worse, the test file pinned that: one case used the real
+ * nested shape and asserted `falseGreenCaught: false`, directly beneath a comment calling this case
+ * "the thesis", while the case that asserted `true` used a flat shape act_and_wait never emits.
+ *
+ * A permanently-zero metric is indistinguishable from a working one that has nothing to report, so
+ * nobody could have noticed this from the data. It took reading the emit path.
+ */
+function passedOf(result, status) {
+    if ('boolean' === typeof result['pass'])
+        return result['pass'];
+    const verdict = result['verdict'];
+    if (null !== verdict && 'object' === typeof verdict) {
+        const nested = verdict['pass'];
+        if ('boolean' === typeof nested)
+            return nested;
+    }
+    if (status === SuiteStatus.PASS)
+        return true;
+    if (status === SuiteStatus.FAIL)
+        return false;
+    return undefined;
+}
 /**
  * The verification payload for a result, or undefined when nothing was verified.
  *
@@ -73,13 +105,7 @@ export function verificationOf(toolName, result, durationMs, brand) {
     // metric's convenience — but a status that is neither pass nor fail is NOT a verdict, and an empty
     // suite reports exactly that.
     const status = result['status'];
-    const passed = 'boolean' === typeof result['pass']
-        ? result['pass']
-        : status === SuiteStatus.PASS
-            ? true
-            : status === SuiteStatus.FAIL
-                ? false
-                : undefined;
+    const passed = passedOf(result, status);
     if (verified === undefined && passed === undefined)
         return undefined;
     const reason = reasonOf(result);
@@ -88,6 +114,19 @@ export function verificationOf(toolName, result, durationMs, brand) {
         via: toolName,
         verified: verified ?? (true === passed ? 'yes' : 'no'),
         passed: passed ?? 'yes' === verified,
+        // The assertion passed and Reticle answered `no` anyway: a green actively refuted.
+        //
+        // Deliberately NOT widened to every refusal of a passing assertion, though several of them are
+        // arguably false greens caught too. `decideVerified` refuses a green seven ways and only
+        // `contradicted` answers `no`; the rest answer `unknown` on purpose, because UNKNOWN must never
+        // collapse into NO. `already_true` is the tempting one: a green that proved nothing because the
+        // condition already held before the action, found by a check built for exactly that.
+        //
+        // It stays out because `reason` is on this same payload. Anyone who wants the wider number can
+        // count it without a definition change, and a definition that shifts underneath a metric is
+        // worse than one that is narrow, because the old and new series look comparable and are not.
+        // Widening it would also have landed in the same release as the fix above, making it impossible
+        // to tell how much of any rise was the bug and how much was the redefinition.
         falseGreenCaught: true === passed && 'no' === verified,
         durationMs,
         // Headless CI, a human watching, or somebody's own dev server — three different products behind

package/dist/temp-dir.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Removing a temp directory on Windows, without inventing a product failure.
+ *
+ * `rm(dir, { recursive: true, force: true })` is the obvious teardown and it is not enough on
+ * Windows. Deletion there is not immediate: a handle the OS, the indexer or a virus scanner still
+ * holds keeps the entry alive for a moment after the last close, so the directory is observed
+ * non-empty at the instant `rmdir` runs and Node throws `ENOTEMPTY`. `force` does not cover it —
+ * that suppresses "missing", not "busy".
+ *
+ * The failure lands in `afterEach`, so it is reported against the test that just PASSED, and the
+ * leftover directory then bleeds state into what runs next. On CI this presented as five failures in
+ * one file, four of them consequential and one of them the wonderfully misleading "expected length 1
+ * but got 2" — a fake production bug manufactured entirely by teardown. This repo already has that
+ * exact story written up in `project-store.test.ts` about a timed-out test's stray writes; this is the
+ * same failure arriving through the filesystem instead of through the clock.
+ *
+ * `maxRetries`/`retryDelay` exist in Node for precisely this, and are documented as Windows-oriented.
+ * They are a no-op on POSIX, where the first attempt already succeeds.
+ */
+/**
+ * Delete a temp directory tree, tolerating Windows' delayed handle release.
+ *
+ * Never throws: a temp directory that outlives the test is the operating system's problem, not a
+ * reason to fail a run or to report a defect the product does not have. What must not happen is the
+ * opposite — a red that says nothing about the code under test.
+ */
+export declare function removeTempDir(dir: string): Promise<void>;