@reticlehq/server 2.2.0 → 2.3.0

package/dist/session/session.js

@@ -1,12 +1,18 @@
-import { EventType, HumanControlDataSchema, HumanControlKind, HumanMarkDataSchema, ReticleCommand, MessageKind, PresenterTone, SESSION_HEALTH, SESSION_LEASE, SESSION_LIFECYCLE, SessionState, } from '@reticlehq/core';
+import { LastAct } from './last-act.js';
+import { commandTimeoutMessage } from './command-timeout.js';
+import { readHealthEvent } from './session-health.js';
+import { PendingCommands } from './pending-commands.js';
+import { EventType, HumanControlDataSchema, HumanControlKind, HumanMarkDataSchema, ReticleCommand, MessageKind, parseEventPayload, PresenterTone, SESSION_HEALTH, SESSION_LEASE, SESSION_LIFECYCLE, SessionState, } from '@reticlehq/core';
 import { RingBuffer } from '../events/ring-buffer.js';
 import { filterEvents, mergeEventsBySeq, } from '../journal/journal-query.js';
 import {} from '../journal/ambient.js';
 import { ObservedState } from './observed-state.js';
+import { recordBrowserLatency, recordSdkFailure } from '../telemetry/session-metrics.js';
 import { LiveControl } from './live-control.js';
 import { ReviewStore } from './review-store.js';
 import { buildSessionRecommendation } from './session-recommendation.js';
 import { buildPresenterArgs } from './presenter-args.js';
+import { buildSessionLease } from './session-lease.js';
 const DEFAULT_COMMAND_TIMEOUT_MS = 8000;
 /** Prefix on correlated command ids (c1, c2, …) — distinguishes them from mark ids. */
 const COMMAND_ID_PREFIX = 'c';
@@ -30,15 +36,15 @@ export class Session {
     #clock;
     #startedAt;
     #buffer = new RingBuffer();
-    #pending = new Map();
+    #pending = new PendingCommands();
     #listeners = new Set();
-    #seq = 0;
     #actionSeq = 0;
     #lastSeenAt;
     #hidden = false;
+    /** Which shell the page reported (PAGE_HEALTH). Undefined until the first report lands. */
+    #runtime;
+    #engine;
     #focused = true;
-    #lastActCursor;
-    #lastActSource;
     /** Liveness: wall-clock of the last AGENT command (distinct from browser chatter / lastSeen). */
     #lastAgentActivityAt;
     /** Server-side mirror of the agent-tuned idle window, so the reaper honors reticle_session. */
@@ -82,10 +88,27 @@ export class Session {
     lastSeenMs() {
         return this.#clock() - this.#lastSeenAt;
     }
-    /** Record the latest page visibility/focus state from a PAGE_HEALTH event. */
-    applyHealth(hidden, focused) {
+    /**
+     * Record the latest page visibility/focus state from a PAGE_HEALTH event.
+     *
+     * `runtime` is optional so an older SDK (which does not report it) still works — it simply loses
+     * the desktop-specific timeout diagnosis rather than breaking.
+     */
+    applyHealth(hidden, focused, runtime, engine) {
         this.#hidden = hidden;
         this.#focused = focused;
+        if (runtime === 'electron' || runtime === 'tauri' || runtime === 'web') {
+            this.#runtime = runtime;
+        }
+        if (engine !== undefined)
+            this.#engine = engine;
+    }
+    /** The shell (web/electron/tauri) and rendering engine the SDK reported. Undefined on an older SDK. */
+    get runtime() {
+        return this.#runtime;
+    }
+    get engine() {
+        return this.#engine;
     }
     /** Throttled if the tab is hidden OR we have not heard from it recently. */
     throttled() {
@@ -120,14 +143,14 @@ export class Session {
         if (this.staleMs() > SESSION_LEASE.STALE_AFTER_MS) {
             base.stale = true;
             base.cleanup_suggestion =
-                'Call reticle_end_session to free this session before starting new work.';
+                'Call reticle_session{action:"end"} to free this session before starting new work.';
         }
         // Surface human bug reports in reticle_sessions (only when > 0, so a clean session adds nothing).
         const marks = this.#review.pendingCount();
         if (marks > 0) {
             base.pendingMarks = marks;
             const s = marks === 1 ? '' : 's';
-            base.review_suggestion = `The human flagged ${String(marks)} issue${s} on this tab — call reticle_review to see and fix ${marks === 1 ? 'it' : 'them'}.`;
+            base.review_suggestion = `The human flagged ${String(marks)} issue${s} on this tab — call reticle_session{action:"review"} to see and fix ${marks === 1 ? 'it' : 'them'}.`;
         }
         return base;
     }
@@ -138,10 +161,15 @@ export class Session {
     /** Re-stamp an incoming event with server-relative time, buffer it, and fan out. */
     pushEvent(event, byteSize) {
         if (event.type === EventType.PAGE_HEALTH) {
-            const data = event.data;
-            const hidden = typeof data['hidden'] === 'boolean' ? data['hidden'] : this.#hidden;
-            const focused = typeof data['focused'] === 'boolean' ? data['focused'] : this.#focused;
-            this.applyHealth(hidden, focused);
+            const r = readHealthEvent(event.data);
+            this.applyHealth(r.hidden ?? this.#hidden, r.focused ?? this.#focused, r.runtime, r.engine);
+        }
+        // The in-page half of Reticle reporting its own failure — recorded like a tool error
+        // (fingerprinted, variables stripped) so a broken observer is as visible as a broken tool.
+        if (event.type === EventType.SDK_FAILED) {
+            const sdk = parseEventPayload(EventType.SDK_FAILED, event.data);
+            if (sdk.success)
+                recordSdkFailure(sdk.data);
         }
         if (event.type === EventType.HUMAN_CONTROL) {
             // Narrow unknown at the boundary; an invalid/unknown control is ignored (never thrown).
@@ -178,7 +206,17 @@ export class Session {
         for (const listener of this.#listeners)
             listener(attributed);
     }
-    /** Latest count per blind-spot kind; survives buffer eviction. See ObservedState for why. */
+    // Passthroughs to ObservedState, which owns the per-session facts that must SURVIVE buffer
+    // eviction: refs the agent drove, and what the layer could not see. See observed-state.ts.
+    recordActedRef(ref) {
+        this.#observed.recordActedRef(ref);
+    }
+    actedRefs() {
+        return this.#observed.actedRefs();
+    }
+    noteRateLimited(dropped) {
+        this.#observed.noteRateLimited(dropped);
+    }
     blindSpots() {
         return this.#observed.blindSpots();
     }
@@ -241,24 +279,12 @@ export class Session {
         return this.#buffer.since(cursor);
     }
     /**
-     * Honesty: remember the event cursor of the most recent act so wait_for/assert can default their
-     * evaluation floor to it — a signal buffered before this act can never fake a later pass.
+     * What the most recent act was: its cursor, its source, and what it changed inside its target.
+     *
+     * Exposed as the object rather than six pass-through methods — act writes to it and observe reads
+     * from it, and the split between those two tool calls is the whole reason it exists.
      */
-    markActCursor(cursor) {
-        this.#lastActCursor = cursor;
-    }
-    /** The cursor of the last act, or undefined if nothing has acted yet. */
-    lastActCursor() {
-        return this.#lastActCursor;
-    }
-    /** Remember where the last acted control is written (`file:line`), for failures with no element. */
-    markActSource(source) {
-        this.#lastActSource = source;
-    }
-    /** Where the last acted control is written, or undefined if nothing has acted yet. */
-    lastActSource() {
-        return this.#lastActSource;
-    }
+    lastAct = new LastAct();
     // ── Server-authoritative liveness (immune to browser-tab throttling) ──────────────
     /**
      * Stamp the wall-clock of the latest AGENT command (called whenever a tool resolves this session).
@@ -309,8 +335,16 @@ export class Session {
     }
     /** Send a command to the browser and await its reply (or time out). */
     command(name, args = {}, timeoutMs = DEFAULT_COMMAND_TIMEOUT_MS) {
-        this.#seq += 1;
-        const id = `${COMMAND_ID_PREFIX}${String(this.#seq)}`;
+        // Recorded HERE rather than at the tool call sites: this is the one place every driven action
+        // passes through, so act_sequence and flow replay count too. Doing it per-tool missed both, and
+        // an under-counted "exercised" reports worse coverage than reality — the safe direction, but
+        // still wrong, and it made the number depend on which tool the agent happened to use.
+        if (name === ReticleCommand.ACT) {
+            const ref = args['ref'];
+            if (typeof ref === 'string')
+                this.recordActedRef(ref);
+        }
+        const id = this.#pending.nextId(COMMAND_ID_PREFIX);
         const payload = JSON.stringify({
             kind: MessageKind.COMMAND,
             id,
@@ -318,30 +352,24 @@ export class Session {
             name,
             args,
         });
-        return new Promise((resolve, reject) => {
-            const timer = setTimeout(() => {
-                this.#pending.delete(id);
-                reject(new Error(`command '${name}' timed out after ${String(timeoutMs)}ms`));
-            }, timeoutMs);
-            this.#pending.set(id, { resolve, reject, timer });
-            this.#socket.send(payload);
-        });
+        // The timeout message is built LAZILY: health can change while a command is in flight, and the
+        // diagnosis should describe the page as it was when the command actually gave up.
+        const awaited = this.#pending.track(id, timeoutMs, () => commandTimeoutMessage(name, timeoutMs, {
+            url: this.url,
+            hidden: this.#hidden,
+            lastSeenMs: this.lastSeenMs(),
+            ...(this.#runtime === undefined ? {} : { runtime: this.#runtime }),
+        }));
+        this.#socket.send(payload);
+        const sentAt = Date.now(); // browser-leg timing; see recordBrowserLatency for why it is split out
+        return awaited.finally(() => recordBrowserLatency(Date.now() - sentAt));
     }
     handleResult(result) {
-        const pending = this.#pending.get(result.id);
-        if (pending === undefined)
-            return;
-        clearTimeout(pending.timer);
-        this.#pending.delete(result.id);
-        pending.resolve(result);
+        this.#pending.settle(result);
     }
     /** Reject everything still in flight — used on disconnect. */
     rejectAll(reason) {
-        for (const [id, pending] of this.#pending) {
-            clearTimeout(pending.timer);
-            pending.reject(new Error(reason));
-            this.#pending.delete(id);
-        }
+        this.#pending.rejectAll(reason);
     }
     /** End this transport without letting a stale socket remove its replacement session. */
     disconnect(reason) {
@@ -424,20 +452,12 @@ export class Session {
     pushNarration(text) {
         this.#post(ReticleCommand.NARRATE, { text, level: 'info' });
     }
-    /**
-     * Returns the one-time session lease block on the very first agent command, then undefined
-     * forever after. The lease carries an IMPORTANT reminder to call reticle_end_session. Coding agents
-     * (Claude Code, Codex) read tool results — they will see this and remember to clean up.
-     */
+    /** The one-time lease block on the first agent command, then undefined forever after. */
     takeSessionLease() {
         if (this.#firstCommandDone)
             return undefined;
         this.#firstCommandDone = true;
-        return {
-            sessionId: this.id,
-            opened_at: this.#startedAt,
-            IMPORTANT: 'MANDATORY: the moment you stop driving — finishing a reply or waiting on the human — call reticle_session {action:"yield", mode:"waiting"} (or mode:"ask" with your question) so the panel never falsely reads "live". Call reticle_session {action:"end"} only when the whole task is done. The session revives on your next action.',
-        };
+        return buildSessionLease(this.id, this.#startedAt);
     }
     /**
      * Returns a human-readable age warning after SESSION_LEASE.WARN_AFTER_MS (10 min), else undefined.
@@ -449,14 +469,24 @@ export class Session {
         if (ageMs < SESSION_LEASE.WARN_AFTER_MS)
             return undefined;
         const minutes = Math.floor(ageMs / 60_000);
-        return `Session ${this.id} has been open for ${String(minutes)} minutes. If your task is complete, call reticle_end_session now.`;
+        return `Session ${this.id} has been open for ${String(minutes)} minutes. If your task is complete, call reticle_session{action:"end"} now.`;
     }
     /** Fire-and-forget command send — NOT registered in #pending (no correlated result expected). */
     #post(name, args) {
         if (this.#socket.readyState !== WS_OPEN)
             return;
-        this.#seq += 1;
-        const id = `${COMMAND_ID_PREFIX}${String(this.#seq)}`;
+        // Shares the same counter as tracked commands, so a fire-and-forget id can never collide with
+        // one that IS awaiting a reply.
+        // Recorded HERE rather than at the tool call sites: this is the one place every driven action
+        // passes through, so act_sequence and flow replay count too. Doing it per-tool missed both, and
+        // an under-counted "exercised" reports worse coverage than reality — the safe direction, but
+        // still wrong, and it made the number depend on which tool the agent happened to use.
+        if (name === ReticleCommand.ACT) {
+            const ref = args['ref'];
+            if (typeof ref === 'string')
+                this.recordActedRef(ref);
+        }
+        const id = this.#pending.nextId(COMMAND_ID_PREFIX);
         const payload = JSON.stringify({
             kind: MessageKind.COMMAND,
             id,
@@ -478,4 +508,3 @@ export class Session {
  * units under the file-size cap.
  */
 export { SessionManager } from './session-manager.js';
-//# sourceMappingURL=session.js.map

package/dist/session/state-select.d.ts

@@ -5,4 +5,3 @@
  * (an older browser that returns the whole store) and for the predicate engine's `state` assertion.
  */
 export { selectPath, capDepth, type PathSelection } from '@reticlehq/core';
-//# sourceMappingURL=state-select.d.ts.map

package/dist/session/state-select.js

@@ -5,4 +5,3 @@
  * (an older browser that returns the whole store) and for the predicate engine's `state` assertion.
  */
 export { selectPath, capDepth } from '@reticlehq/core';
-//# sourceMappingURL=state-select.js.map

package/dist/telemetry/argument-shape.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Which flags and parameters people actually use — WITHOUT ever sending what they set them to.
+ *
+ * This is the most dangerous data in the product to collect, and the split that makes it safe is
+ * NAMES versus VALUES:
+ *
+ *   - A flag or parameter NAME comes from a closed vocabulary we wrote ourselves. `--headed`,
+ *     `--port`, `ref`, `timeout_ms` — there are a few dozen, none of them describe the user, and
+ *     knowing which ones get used is the whole product question ("is anyone passing `fullPage`?
+ *     does anybody use `--storage-state`?").
+ *   - A VALUE is the user's. `--http-token` holds a secret. `--drive` holds a URL. `reticle_act`'s
+ *     `args` holds the text being typed into the app, which on a login form is a password. A rule
+ *     like "send short values, they're probably enums" would leak all three.
+ *
+ * So values are never sent, with one narrow exception: a handful of parameters whose values ARE our
+ * own enums, listed explicitly below. `action: "click"` is our vocabulary, not the user's, and it
+ * answers a real question. Membership in that list is opt-in per parameter and each entry names the
+ * exact values allowed — anything outside the list is reported as `other`, so a schema change can
+ * never quietly start forwarding free text.
+ */
+export declare const OTHER_VALUE = "other";
+/** True for anything we are willing to report a value for. */
+export declare function isSafeEnumParam(name: string): boolean;
+/**
+ * The reportable form of one parameter: `name` on its own, or `name:value` when the parameter is a
+ * known enum. Never the raw value of anything else.
+ */
+export declare function describeParam(name: string, value: unknown): string;
+/** Every parameter an agent actually passed to one tool call, reduced to names (+ safe enums). */
+export declare function describeToolParams(args: Record<string, unknown>): string[];
+/**
+ * The flags PRESENT on a CLI invocation, by name only.
+ *
+ * Values are dropped without exception here — no enum allowlist — because the CLI's flag values are
+ * uniformly the user's: a port, a URL, a file path, a pairing token. `--http-token` alone is reason
+ * enough to make this rule absolute rather than case-by-case.
+ *
+ * Anything not starting with `--` is an argument, not a flag, and is dropped entirely: that is where
+ * the URL, the file list, and the feedback message live.
+ */
+export declare function describeCliFlags(argv: readonly string[]): string[];

package/dist/telemetry/argument-shape.js

@@ -0,0 +1,87 @@
+/**
+ * Which flags and parameters people actually use — WITHOUT ever sending what they set them to.
+ *
+ * This is the most dangerous data in the product to collect, and the split that makes it safe is
+ * NAMES versus VALUES:
+ *
+ *   - A flag or parameter NAME comes from a closed vocabulary we wrote ourselves. `--headed`,
+ *     `--port`, `ref`, `timeout_ms` — there are a few dozen, none of them describe the user, and
+ *     knowing which ones get used is the whole product question ("is anyone passing `fullPage`?
+ *     does anybody use `--storage-state`?").
+ *   - A VALUE is the user's. `--http-token` holds a secret. `--drive` holds a URL. `reticle_act`'s
+ *     `args` holds the text being typed into the app, which on a login form is a password. A rule
+ *     like "send short values, they're probably enums" would leak all three.
+ *
+ * So values are never sent, with one narrow exception: a handful of parameters whose values ARE our
+ * own enums, listed explicitly below. `action: "click"` is our vocabulary, not the user's, and it
+ * answers a real question. Membership in that list is opt-in per parameter and each entry names the
+ * exact values allowed — anything outside the list is reported as `other`, so a schema change can
+ * never quietly start forwarding free text.
+ */
+import { ActionType, FeedbackKind, QueryBy, SnapshotMode } from '@reticlehq/core';
+/**
+ * Parameters whose values are enums WE define, and the exact values allowed on the wire. An
+ * unrecognized value reports `other` rather than itself; that fallback is what makes this safe
+ * against a future where one of these params starts accepting free text.
+ */
+const SAFE_ENUM_PARAMS = new Map([
+    // Every entry DERIVED from the enum core already owns, never hand-listed. The first version listed
+    // them literally and was wrong on the day it shipped, not merely at risk: `action` was missing
+    // `fill`, `dblclick`, `submit`, `scrollIntoView`, `drag` and `webmcp` — so `fill`, one of the most
+    // common actions there is, silently reported as `other` — while carrying a `scroll` that
+    // `ActionType` does not define. `mode` mixed SnapshotMode with unrelated session-lifecycle values.
+    // Deriving is not tidiness here; it is the difference between the data being right and being wrong.
+    ['action', new Set(Object.values(ActionType))],
+    ['by', new Set(Object.values(QueryBy))],
+    ['mode', new Set(Object.values(SnapshotMode))],
+    ['kind', new Set(Object.values(FeedbackKind))],
+    // `level` has no core enum — console levels come from the DOM console API, not from us. Listed
+    // literally BECAUSE there is nothing to derive from, which is a different situation from the four
+    // above and the reason it is called out rather than left looking like an oversight.
+    ['level', new Set(['error', 'warn', 'info', 'log', 'debug'])],
+]);
+export const OTHER_VALUE = 'other';
+/** True for anything we are willing to report a value for. */
+export function isSafeEnumParam(name) {
+    return SAFE_ENUM_PARAMS.has(name);
+}
+/**
+ * The reportable form of one parameter: `name` on its own, or `name:value` when the parameter is a
+ * known enum. Never the raw value of anything else.
+ */
+export function describeParam(name, value) {
+    const allowed = SAFE_ENUM_PARAMS.get(name);
+    if (allowed === undefined)
+        return name;
+    if (typeof value !== 'string')
+        return name;
+    return `${name}:${allowed.has(value) ? value : OTHER_VALUE}`;
+}
+/** Every parameter an agent actually passed to one tool call, reduced to names (+ safe enums). */
+export function describeToolParams(args) {
+    return Object.keys(args)
+        .filter((key) => args[key] !== undefined)
+        .map((key) => describeParam(key, args[key]))
+        .sort();
+}
+/**
+ * The flags PRESENT on a CLI invocation, by name only.
+ *
+ * Values are dropped without exception here — no enum allowlist — because the CLI's flag values are
+ * uniformly the user's: a port, a URL, a file path, a pairing token. `--http-token` alone is reason
+ * enough to make this rule absolute rather than case-by-case.
+ *
+ * Anything not starting with `--` is an argument, not a flag, and is dropped entirely: that is where
+ * the URL, the file list, and the feedback message live.
+ */
+export function describeCliFlags(argv) {
+    const flags = new Set();
+    for (const arg of argv) {
+        if (!arg.startsWith('--'))
+            continue;
+        // `--port=9000` — split so the NAME is reported and the value is discarded with everything else.
+        const name = arg.split('=')[0] ?? arg;
+        flags.add(name);
+    }
+    return [...flags].sort();
+}

package/dist/telemetry/bug-found.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Counting the defects Reticle actually finds.
+ *
+ * Every other metric in this product measures whether Reticle is USED. This one measures whether it
+ * WORKS — and it is the only number that can honestly be put in front of an investor or published,
+ * because it counts outcomes for users rather than activity by them.
+ *
+ * It is read off tool RESULTS at the single chokepoint every tool already crosses, rather than
+ * emitted from the four places that produce findings. That is deliberate: the detectors are pure
+ * functions and should stay that way, and reading results means a fifth source of findings is covered
+ * the day it starts returning one of these shapes, instead of the day someone remembers to instrument
+ * it.
+ *
+ * What is sent is the KIND from Reticle's own findings vocabulary — `signal-contradicted`,
+ * `console-error`, `duplicate-request`. Never a selector, a URL, an element, or a description of
+ * anyone's app: that a class of defect was found, never what it was found in.
+ */
+import { type BugFound } from '@reticlehq/core';
+/**
+ * A defect as the CLASSIFIER sees it — everything except `repeat`.
+ *
+ * Whether a kind is new belongs to the session, and these detectors are pure functions that know
+ * nothing about sessions and should stay that way. The emission site owns the dedup flag.
+ */
+export type BugCandidate = Omit<BugFound, 'repeat'>;
+/**
+ * The defects in one tool result.
+ *
+ * Ordering matters for the false-green flag: a contradiction found alongside a PASSING assertion is
+ * the case the product exists for — the screen looked right, the write failed, and every other tool
+ * on the market would have called it green. That pairing is what `falseGreen` marks.
+ */
+export declare function bugsInResult(toolName: string, result: Record<string, unknown>): BugCandidate[];

package/dist/telemetry/bug-found.js

@@ -0,0 +1,95 @@
+/**
+ * Counting the defects Reticle actually finds.
+ *
+ * Every other metric in this product measures whether Reticle is USED. This one measures whether it
+ * WORKS — and it is the only number that can honestly be put in front of an investor or published,
+ * because it counts outcomes for users rather than activity by them.
+ *
+ * It is read off tool RESULTS at the single chokepoint every tool already crosses, rather than
+ * emitted from the four places that produce findings. That is deliberate: the detectors are pure
+ * functions and should stay that way, and reading results means a fifth source of findings is covered
+ * the day it starts returning one of these shapes, instead of the day someone remembers to instrument
+ * it.
+ *
+ * What is sent is the KIND from Reticle's own findings vocabulary — `signal-contradicted`,
+ * `console-error`, `duplicate-request`. Never a selector, a URL, an element, or a description of
+ * anyone's app: that a class of defect was found, never what it was found in.
+ */
+import { BugSource, ContradictionKind } 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) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map((entry) => {
+        const kind = entry?.kind;
+        return typeof kind === 'string' ? kind : undefined;
+    })
+        .filter((kind) => kind !== undefined);
+}
+/**
+ * The defects in one tool result.
+ *
+ * Ordering matters for the false-green flag: a contradiction found alongside a PASSING assertion is
+ * the case the product exists for — the screen looked right, the write failed, and every other tool
+ * on the market would have called it green. That pairing is what `falseGreen` marks.
+ */
+export function bugsInResult(toolName, result) {
+    const bugs = [];
+    const passed = result['pass'] === true;
+    // 1. Contradictions — channels disagreeing. Invisible to a human watching the screen.
+    for (const kind of kindsOf(result['contradictions'])) {
+        bugs.push({ source: BugSource.CONTRADICTION, kind, falseGreen: passed, tool: toolName });
+    }
+    // 2. Crawl anomalies — found autonomously, with nobody writing a test. Crawl reports its own
+    //    contradictions inside `anomalies` too, so classify by kind rather than by which array it sat in.
+    for (const kind of kindsOf(result['anomalies'])) {
+        bugs.push({
+            source: BugSource.CRAWL,
+            kind,
+            // A crawl contradiction presents as success too — the click looked fine and its write did not
+            // — even though no assertion was made. See the definition on `falseGreen`.
+            falseGreen: CONTRADICTION_KINDS.has(kind),
+            tool: toolName,
+        });
+    }
+    // 3. A failed assertion — the agent declared a consequence and it did not hold.
+    //    Only when nothing above already explained it, or one defect would be counted twice.
+    if (result['pass'] === false && bugs.length === 0) {
+        const reason = result['assertion'];
+        bugs.push({
+            source: BugSource.ASSERTION,
+            kind: typeof reason === 'string' && reason.length > 0 ? reason.slice(0, 64) : 'assertion-failed',
+            falseGreen: false,
+            tool: toolName,
+        });
+    }
+    // 4. Replay failures — a saved flow that used to pass no longer does. That is a regression caught,
+    //    which is a different and stronger claim than "a check failed".
+    if (result['status'] === 'fail' && Array.isArray(result['failures'])) {
+        for (const _failure of result['failures'].slice(0, MAX_BUGS_PER_CALL)) {
+            bugs.push({
+                source: BugSource.REPLAY,
+                kind: 'flow-regression',
+                falseGreen: false,
+                tool: toolName,
+            });
+        }
+    }
+    return bugs.slice(0, MAX_BUGS_PER_CALL);
+}
+/**
+ * Crawl anomaly kinds that are CONTRADICTIONS rather than single-channel faults.
+ *
+ * `reticle_crawl` returns both classes in one `anomalies` array — a console error is one channel
+ * complaining, while a UI that advanced over a failed write is two channels disagreeing. Only the
+ * second presents as success, and collapsing them would inflate the one claim that has to be exact.
+ *
+ * DERIVED from core's `ContradictionKind`, never hand-listed. The first version copied the twelve
+ * strings into a literal here, which matched on the day it was written and would have silently
+ * misclassified the thirteenth: a new contradiction kind would have been counted as an ordinary
+ * fault, quietly deflating the exact number we intend to publish. A copied enum is a drift hazard
+ * wherever it appears; it is a correctness hazard when the thing that drifts is a public claim.
+ */
+const CONTRADICTION_KINDS = new Set(Object.values(ContradictionKind));

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

@@ -0,0 +1,13 @@
+/**
+ * Report that a person ran a `reticle` subcommand.
+ *
+ * `_daemon` is EXCLUDED, and that exclusion is the whole point of this function. `reticle mcp` and
+ * `reticle serve` start the daemon by re-running this very binary, so the child re-entered the CLI
+ * entry point and emitted a second event for what a person experienced as ONE action. The old
+ * `invoke` metric was therefore inflated ~2x — and inflated worst on the agent-driven sessions that
+ * matter most, while one-shot commands like `version` counted once. That skewed the RATIO between
+ * commands, not merely the scale, which is the kind of error you cannot correct for after the fact.
+ * The daemon\'s own lifecycle is already reported by `daemon_started` / `daemon_stopped`; a spawned
+ * daemon is not a CLI run.
+ */
+export declare function reportCliRun(argv: readonly string[]): void;

package/dist/telemetry/cli-telemetry.js

@@ -0,0 +1,43 @@
+/**
+ * The one telemetry event a human directly causes: they typed a `reticle` command.
+ *
+ * Lives in its own module so `cli.ts` stays a dispatcher, and so the `_daemon` exclusion below sits
+ * next to the explanation of why it exists rather than buried in a startup function.
+ */
+import { TelemetryActor, TelemetryEventKind } from '@reticlehq/core';
+import { DAEMON_INNER_COMMAND, knownCommand } from '../cli-parse.js';
+import { getTelemetry } from './telemetry.js';
+import { describeCliFlags } from './argument-shape.js';
+/**
+ * Report that a person ran a `reticle` subcommand.
+ *
+ * `_daemon` is EXCLUDED, and that exclusion is the whole point of this function. `reticle mcp` and
+ * `reticle serve` start the daemon by re-running this very binary, so the child re-entered the CLI
+ * entry point and emitted a second event for what a person experienced as ONE action. The old
+ * `invoke` metric was therefore inflated ~2x — and inflated worst on the agent-driven sessions that
+ * matter most, while one-shot commands like `version` counted once. That skewed the RATIO between
+ * commands, not merely the scale, which is the kind of error you cannot correct for after the fact.
+ * The daemon\'s own lifecycle is already reported by `daemon_started` / `daemon_stopped`; a spawned
+ * daemon is not a CLI run.
+ */
+export function reportCliRun(argv) {
+    const firstArg = argv[0];
+    if (firstArg === DAEMON_INNER_COMMAND)
+        return;
+    const telemetry = getTelemetry();
+    // `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.CLI_COMMAND_RUN, {
+        detach: true,
+        actor: TelemetryActor.HUMAN,
+        // A fixed, low-cardinality vocabulary WE define, so it is safe to send whole and it is the closest
+        // honest read we have on intent: `verify` and `gate` mean something very different from `status`.
+        // An unrecognized first arg reports as `unknown` rather than being echoed — an echo would put
+        // whatever someone mistyped, including a path or a URL, straight onto the wire.
+        command: knownCommand(firstArg),
+        // Which flags were PRESENT, by name only — never their values. `--http-token` alone makes that
+        // rule absolute rather than case-by-case; `--drive` and `--storage-state` carry a URL and a path.
+        flags: describeCliFlags(argv),
+    });
+}

package/dist/telemetry/connect-failure.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Classifying WHY a browser connection failed, into causes that each have a different fix.
+ *
+ * A raw error message cannot be sent — it carries CDP URLs, executable paths, and home directories —
+ * and would be useless if it could, because the same cause arrives worded five different ways from
+ * Playwright, Node and the OS. What we need is the small set of THINGS THAT ACTUALLY GO WRONG:
+ * a missing browser binary is a docs problem, a refused CDP endpoint is a configuration problem, a
+ * pool timeout is a capacity problem. Three very different responses from us.
+ *
+ * `OTHER` is the bucket to watch. A large `OTHER` count means the classifier has a blind spot and
+ * this list needs another entry — which is a signal in itself, and the reason it is never merged
+ * into one of the known causes.
+ */
+import { ConnectFailure } from '@reticlehq/core';
+/** The cause behind a connection error, or `OTHER` when we do not recognize it. */
+export declare function classifyConnectFailure(error: unknown): ConnectFailure;