@reticlehq/server 3.8.2 → 3.10.0

package/dist/surface/tools/tools.js

@@ -1,7 +1,7 @@
 import { TESTID_FOUND_UNDER_SCHEMA } from './query-hint-schema.js';
 import { z } from 'zod';
-import { EMPTY_SESSION_LIST_OUTPUT, emptySessionList, nextStepBesideLiveSessions, } from './empty-session-list.js';
-import { AttrNamesSchema, QueryBy, ReticleCommand, SnapshotMode } from '@reticlehq/core';
+import { EMPTY_SESSION_LIST_OUTPUT, emptySessionList, NEXT_STEP_FIELD, nextStepBesideLiveSessions, } from './empty-session-list.js';
+import { AttrNamesSchema, NearestTargetSchema, QueryBy, ReticleCommand, SnapshotMode, } from '@reticlehq/core';
 import { ReticleTool } from '@reticlehq/core';
 import { withSizeCost } from '../../portal/session/output-budget.js';
 import { applySnapshotDelta, SnapshotCache } from './read/snapshot-delta.js';
@@ -40,6 +40,7 @@ import { buildCoverageTools } from './coverage-tools.js';
 import { VERIFY_CHANGE_TOOLS } from '../../language/flows/verify-change-tools.js';
 import { CRAWL_TOOLS } from '../../features/crawl/crawl-tools.js';
 import { EXPLORE_TOOLS } from './explore-tools.js';
+import { COMPARE_TOOLS } from './compare-tools.js';
 import { SCROLL_TOOLS } from '../../portal/input/scroll-tools.js';
 import { NETWORK_MOCK_TOOLS } from '../../portal/input/network-mock-tools.js';
 import { VIEWPORT_TOOLS } from '../../portal/input/viewport-tools.js';
@@ -145,11 +146,12 @@ export const RAW_TOOLS = withCompactEnvelope([
             })));
             const sessions = await list();
             // An empty list is a dead end on its own; see empty-session-list.ts for what it carries.
-            if (0 === sessions.length)
+            if (0 === sessions.length) {
                 return emptySessionList(deps, sessions);
+            }
             // Another project's tab is up. This caller's project may still never have been wired.
             const nextStep = nextStepBesideLiveSessions(deps, sessions);
-            return nextStep === undefined ? { sessions } : { sessions, next_step: nextStep };
+            return nextStep === undefined ? { sessions } : { sessions, [NEXT_STEP_FIELD]: nextStep };
         },
     },
     {
@@ -177,6 +179,10 @@ export const RAW_TOOLS = withCompactEnvelope([
                 .boolean()
                 .optional()
                 .describe('Also measure the page for what a person would see broken: text cut off with no ellipsis, controls drawn over each other, text under WCAG contrast. Returns `audit: [{ kind, ref, what, detail }]`. Off by default; it forces layout.'),
+            charts: z
+                .boolean()
+                .optional()
+                .describe('Also read each SVG chart as geometry: every bar, dot, line and slice as its box in percent of the chart box, with no colour. A wrong value moves a shape; a chart drawn larger or in other colours reads the same. Returns `charts: [{ label, shapes, cut? }]`. Off by default; it forces layout.'),
             ...sessionIdShape,
         },
         outputSchema: {
@@ -259,6 +265,7 @@ export const RAW_TOOLS = withCompactEnvelope([
                 mode,
                 ...(true === args['ids'] ? { ids: true } : {}),
                 ...(true === args['audit'] ? { audit: true } : {}),
+                ...(true === args['charts'] ? { charts: true } : {}),
             }).then((raw) => withSizeCost(noteUnmountedRoot(noteHiddenPage(noteEmptyLeanTree(applySnapshotDelta(raw, {
                 sessionId: resolved.id,
                 scope: asString(args['scope']) ?? '',
@@ -284,7 +291,7 @@ export const RAW_TOOLS = withCompactEnvelope([
             name: z
                 .string()
                 .optional()
-                .describe('Accessible name filter — narrows results when `by` is role and the page has many elements of that role.'),
+                .describe('Exact accessible-name filter - narrows results when `by` is role and the page has many elements of that role. Matches the whole name; use `text` for a partial match.'),
             scope: z
                 .string()
                 .optional()
@@ -398,6 +405,10 @@ export const RAW_TOOLS = withCompactEnvelope([
                     .optional()
                     .describe('Present when a ROLE+NAME search missed and that role DOES carry a nearly-matching name — role+name is exact, so "Mesh" does not find "2 Mesh". Retry with one of these spellings; no snapshot needed.'),
                 testidFoundUnder: TESTID_FOUND_UNDER_SCHEMA,
+                nearest: z
+                    .array(NearestTargetSchema)
+                    .optional()
+                    .describe('Present when a search missed and the page has visible targets like the one asked for: up to 3, the asked role first, then by name similarity. Each has a ref to retry with. nameTruncated is true when the name was cut. Advice only, never a match.'),
             })
                 .optional()
                 .describe('Present only on zero matches — tells you what IS on the page so you can diagnose the miss.'),
@@ -417,13 +428,18 @@ export const RAW_TOOLS = withCompactEnvelope([
                 .boolean()
                 .optional()
                 .describe('True when a `scope` was given but resolved to nothing — zero matches then means the scope is gone, NOT that the element is absent. The search did not widen to the whole page. Re-check the scope before concluding anything.'),
+            scopeMatches: z
+                .number()
+                .optional()
+                .describe('Present when a CSS `scope` matched more than one element: how many it matched. The search covered all of them. To read one item, scope to its ref.'),
         },
         handler: (deps, rawArgs) => {
             // Accept the predicate's named-field spelling too — see query-shape.ts.
             const args = normalizeQueryArgs(rawArgs);
             const empty = emptyQueryRefusal(args);
-            if (empty !== undefined)
+            if (empty !== undefined) {
                 return Promise.reject(empty);
+            }
             const session = deps.sessions.resolve(asString(args['sessionId']));
             return commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.QUERY, {
                 by: args['by'],
@@ -466,6 +482,7 @@ export const RAW_TOOLS = withCompactEnvelope([
     // reticle_crawl — autonomous click-everything + anomaly report. See crawl-tools.ts.
     ...CRAWL_TOOLS,
     ...EXPLORE_TOOLS,
+    ...COMPARE_TOOLS,
     // reticle_scroll_to — reveal a virtualized off-screen row. See scroll-tools.ts.
     ...SCROLL_TOOLS,
     // Session lifecycle: reticle_session — tune the presenter session (idle-end). See session-tools.ts.
@@ -513,8 +530,12 @@ export const MERGE_PLANS = [
     },
     {
         name: ReticleTool.RECORD,
-        description: 'Timeline recording: { action: "start" } begins recording under a name, "stop" ends it and returns the reaction report plus a compiled replayable program.',
-        members: { start: ReticleTool.RECORD_START, stop: ReticleTool.RECORD_STOP },
+        description: 'Timeline recording: { action: "start" } begins recording under a name, "stop" ends it and returns the reaction report plus a compiled replayable program, "replay" runs that program again by recordingName (destructive controls need confirmDangerous:true on each replay).',
+        members: {
+            start: ReticleTool.RECORD_START,
+            stop: ReticleTool.RECORD_STOP,
+            replay: ReticleTool.REPLAY,
+        },
     },
     {
         name: ReticleTool.FLOW,
@@ -552,7 +573,7 @@ export const MERGE_PLANS = [
     },
     {
         name: ReticleTool.VERIFY,
-        description: 'The Reticle Harness is { action: "explore" }: when the user asks for the Harness, or asks Reticle to drive and verify the app for you, call it and do not drive the app yourself. Every other action says what is proved, and what is not. Start from a change: { action: "affected" } names which saved flows must re-verify for the files you edited (pass `files`, and/or `since` for a git ref), and "change" goes further and actually replays them, answering with one `verified` plus `because`. `unknown` there is the honest answer when NO saved flow covers the change: nothing ran, so nothing was proved, and it is never reported as green. Without a change to start from: "flows" replays every saved flow for one consolidated suite verdict (deterministic, no LLM per flow), and "coverage" lists the interactive controls you have and have NOT driven this session — an untouched list still holding the controls your change affects means you are not done. "crawl" is the no-script option: it drives every reachable control itself and reports single-channel faults (console errors, failed requests, dead controls) and CONTRADICTIONS, two channels disagreeing about the same click — the false greens a human cannot see, because a human watches the screen and the screen looks correct. "explore" is the Reticle Harness: it drives the app for you on the platform — pass a `persona` and it completes that whole journey — and RECORDS what it drove, so the next run replays it with no model in the loop and none of the driving costs your context. "mutate" grades the FLOW rather than the app: it breaks the endpoint a saved flow declared it depends on and replays it, and a flow that stays GREEN through a broken subject is a click sequence, not a test. "heal" repairs a flow whose LOCATOR drifted (a renamed testid), re-asserting the saved consequence before it writes and refusing when that stops firing — it heals a locator, never an intent. DESTRUCTIVE: crawl and explore really click, and may navigate or mutate state; "mutate" really fails a request on a driven page, and always puts it back.',
+        description: 'The Reticle Harness is { action: "explore" }: when the user asks for the Harness, or asks Reticle to drive and verify the app for you, call it and do not drive the app yourself. Every other action says what is proved, and what is not. Start from a change: { action: "affected" } names which saved flows must re-verify for the files you edited (pass `files`, and/or `since` for a git ref), and "change" goes further and actually replays them, answering with one `verified` plus `because`. `unknown` there is the honest answer when NO saved flow covers the change: nothing ran, so nothing was proved, and it is never reported as green. Without a change to start from: "flows" replays every saved flow for one consolidated suite verdict (deterministic, no LLM per flow), and "coverage" lists the interactive controls you have and have NOT driven this session — an untouched list still holding the controls your change affects means you are not done. "crawl" is the no-script option: it drives every reachable control itself and reports single-channel faults (console errors, failed requests, dead controls) and CONTRADICTIONS, two channels disagreeing about the same click — the false greens a human cannot see, because a human watches the screen and the screen looks correct. "explore" is the Reticle Harness: it drives the app for you on the platform — pass a `persona` and it completes that whole journey — and RECORDS what it drove, so the next run replays it with no model in the loop and none of the driving costs your context. "mutate" grades the FLOW rather than the app: it breaks the endpoint a saved flow declared it depends on and replays it, and a flow that stays GREEN through a broken subject is a click sequence, not a test. "heal" repairs a flow whose LOCATOR drifted (a renamed testid), re-asserting the saved consequence before it writes and refusing when that stops firing — it heals a locator, never an intent. "compare" drives two running builds (`reference`, `candidate`, optional `base`) the same way and lists what users would see differ and what the app sent; poll with `runId`. DESTRUCTIVE: crawl, explore and compare really click, and may navigate or mutate state; "mutate" really fails a request on a driven page, and always puts it back.',
         members: {
             change: ReticleTool.VERIFY_CHANGE,
             flows: ReticleTool.FLOW_VERIFY,
@@ -570,6 +591,9 @@ export const MERGE_PLANS = [
             // An action rather than a tenth tool, and safe to fold in because heal only rebinds a LOCATOR:
             // it re-asserts the saved consequence before writing and refuses when that stops firing.
             heal: ReticleTool.FLOW_HEAL,
+            // Two running builds, driven the same way from outside the app: what differs. The same run
+            // and JSON as `reticle compare --json`.
+            compare: ReticleTool.VERIFY_COMPARE,
         },
         // No default action ON PURPOSE. The name implies no single member, and one of them really
         // clicks: a fallthrough that guessed wrong would drive the app rather than read it. Every action
@@ -578,8 +602,12 @@ export const MERGE_PLANS = [
     },
     {
         name: ReticleTool.LEASE,
-        description: 'Isolated headless contexts from the shared pool: { action: "acquire" } leases one and navigates it to the app URL, "release" closes it and frees the slot.',
-        members: { acquire: ReticleTool.LEASE_ACQUIRE, release: ReticleTool.LEASE_RELEASE },
+        description: 'Isolated headless contexts from the shared pool: { action: "acquire" } leases one and navigates it to the app URL, "release" closes it and frees the slot, "coverage" starts or takes JS coverage of the leased page (which code ran).',
+        members: {
+            acquire: ReticleTool.LEASE_ACQUIRE,
+            release: ReticleTool.LEASE_RELEASE,
+            coverage: ReticleTool.LEASE_COVERAGE,
+        },
     },
 ];
 /**
@@ -590,6 +618,7 @@ export const RETIRED_FROM_SURFACE = [
     ReticleTool.RUN_RECORD, // auto-recording on flow_replay already persists run outcomes
     ReticleTool.REFRESH, // absorbed into reticle_navigate { reload: true }
     ReticleTool.WAIT_READY, // server-internal: the first live call already blocks for the session
+    ReticleTool.EXPLORE, // the interactive snapshot plus the console give the same answer
 ];
 /**
  * An empty `interactive` tree is a claim, and it is usually the wrong one.
@@ -603,14 +632,17 @@ export const RETIRED_FROM_SURFACE = [
  * The browser counts what leanness passed over, so the tool can say which of the two it is.
  */
 function noteEmptyLeanTree(result, mode) {
-    if (SnapshotMode.INTERACTIVE !== mode)
+    if (SnapshotMode.INTERACTIVE !== mode) {
         return result;
+    }
     const row = asRecord(result);
-    if (0 !== asNumber(row['nodes']))
+    if (0 !== asNumber(row['nodes'])) {
         return result;
+    }
     const skipped = asNumber(row['leanSkipped']) ?? 0;
-    if (0 === skipped)
+    if (0 === skipped) {
         return result;
+    }
     return {
         ...row,
         note: `no element on this page carries an interactive ARIA role, so this mode found nothing — ` +
@@ -635,18 +667,22 @@ function noteEmptyLeanTree(result, mode) {
  * empty tree it replaces.
  */
 function noteHiddenPage(result, mode) {
-    if (SnapshotMode.STATUS === mode)
+    if (SnapshotMode.STATUS === mode) {
         return result;
+    }
     const row = asRecord(result);
-    if (0 !== asNumber(row['nodes']))
+    if (0 !== asNumber(row['nodes'])) {
         return result;
+    }
     // A note already there is the more specific one (leanness), and two explanations for one empty
     // tree is worse than the better of them alone.
-    if (row['note'] !== undefined)
+    if (row['note'] !== undefined) {
         return result;
+    }
     const skipped = asNumber(row['hiddenSkipped']) ?? 0;
-    if (0 === skipped)
+    if (0 === skipped) {
         return result;
+    }
     return {
         ...row,
         note: `this is NOT an empty page: ${String(skipped)} subtree(s) were skipped because their root ` +

package/dist/surface/tools/type-spelling.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The `fill` spelling mapped onto the `type` action.
+ *
+ * The tool documents `{ text }` for type and `{ value }` for fill/select, and agents mix them up
+ * constantly — `reticle_act` with `{ action: "type", value: "…" }` then fails at run time with
+ * "type requires a string `text`", after the action window opened (reticlehq/reticle#2126, second
+ * item). When `text` is absent and `value` is a string, `value` becomes `text`, in the flat args
+ * and in the nested `args` object. A non-string `value` is left alone so the browser's own
+ * refusal keeps its accurate message.
+ *
+ * Shared by the dispatch point (act-command.ts) and the tests.
+ */
+export declare function normalizeTypeSpelling(actArgs: Record<string, unknown>): Record<string, unknown>;

package/dist/surface/tools/type-spelling.js

@@ -0,0 +1,36 @@
+/**
+ * The `fill` spelling mapped onto the `type` action.
+ *
+ * The tool documents `{ text }` for type and `{ value }` for fill/select, and agents mix them up
+ * constantly — `reticle_act` with `{ action: "type", value: "…" }` then fails at run time with
+ * "type requires a string `text`", after the action window opened (reticlehq/reticle#2126, second
+ * item). When `text` is absent and `value` is a string, `value` becomes `text`, in the flat args
+ * and in the nested `args` object. A non-string `value` is left alone so the browser's own
+ * refusal keeps its accurate message.
+ *
+ * Shared by the dispatch point (act-command.ts) and the tests.
+ */
+import { ActionType } from '@reticlehq/core';
+export function normalizeTypeSpelling(actArgs) {
+    if (ActionType.TYPE !== actArgs['action']) {
+        return actArgs;
+    }
+    const out = { ...actArgs };
+    const mapValueToText = (record) => {
+        if (record['text'] !== undefined || 'string' !== typeof record['value']) {
+            return false;
+        }
+        record['text'] = record['value'];
+        delete record['value'];
+        return true;
+    };
+    mapValueToText(out);
+    const nested = out['args'];
+    if (null !== nested && 'object' === typeof nested && !Array.isArray(nested)) {
+        const nestedCopy = { ...nested };
+        if (mapValueToText(nestedCopy)) {
+            out['args'] = nestedCopy;
+        }
+    }
+    return out;
+}

package/dist/telemetry/agent-client.d.ts

@@ -11,5 +11,11 @@ import { AgentClient, LaunchMethod } from '@reticlehq/core/telemetry';
 export declare function envAgentClient(env: NodeJS.ProcessEnv): AgentClient | undefined;
 /** The client for an event being built now. */
 export declare function currentAgentClient(env: NodeJS.ProcessEnv): AgentClient | undefined;
+/**
+ * The folder in `${CLAUDE_PLUGIN_DATA}` that holds the Claude Code plugin's pinned server copies.
+ * `plugins/reticle/scripts/mcp-server.mjs` cannot import this file, so it keeps a copy of the name.
+ * `plugin-mcp-launch.test.ts` fails when the two differ.
+ */
+export declare const PLUGIN_SERVER_DIR = "reticle-plugin-server";
 /** How the process was launched, from the path of its entry script. Only the bucket leaves. */
 export declare function launchMethodOf(entry: string | undefined): LaunchMethod;

package/dist/telemetry/agent-client.js

@@ -28,6 +28,12 @@ export function envAgentClient(env) {
 export function currentAgentClient(env) {
     return agentClientOf(callingClientName()) ?? envAgentClient(env);
 }
+/**
+ * The folder in `${CLAUDE_PLUGIN_DATA}` that holds the Claude Code plugin's pinned server copies.
+ * `plugins/reticle/scripts/mcp-server.mjs` cannot import this file, so it keeps a copy of the name.
+ * `plugin-mcp-launch.test.ts` fails when the two differ.
+ */
+export const PLUGIN_SERVER_DIR = 'reticle-plugin-server';
 /**
  * Where a global install puts packages, by package manager. A path that matches none of these but
  * still sits in a `node_modules` is a project's own dependency.
@@ -49,6 +55,10 @@ export function launchMethodOf(entry) {
     const path = entry.replace(/\\/g, '/').toLowerCase();
     if (path.includes('/_npx/') || path.includes('/dlx-'))
         return LaunchMethod.NPX;
+    // The Claude Code plugin's own pinned copy: in a `node_modules`, but not the user's project.
+    if (path.includes(`/${PLUGIN_SERVER_DIR}/`)) {
+        return LaunchMethod.OTHER;
+    }
     if (GLOBAL_DIRS.some((dir) => path.includes(dir)))
         return LaunchMethod.GLOBAL;
     if (path.includes('/node_modules/'))

package/dist/telemetry/argument-shape.js

@@ -18,7 +18,7 @@
  * 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';
+import { ActionType, FeedbackKind, QueryBy, ReticleTool, 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
@@ -35,6 +35,9 @@ const SAFE_ENUM_PARAMS = new Map([
     ['by', new Set(Object.values(QueryBy))],
     ['mode', new Set(Object.values(SnapshotMode))],
     ['kind', new Set(Object.values(FeedbackKind))],
+    // `reticle_run { tool }` names the tool it calls. Our own tool names, so the session summary can
+    // say which tools agents reach through it. A name that is not a Reticle tool reports `other`.
+    ['tool', new Set(Object.values(ReticleTool))],
     // `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.
@@ -49,10 +52,12 @@ export const OTHER_VALUE = 'other';
  */
 export function allowParamValues(name, values) {
     const allowed = SAFE_ENUM_PARAMS.get(name);
-    if (allowed === undefined)
+    if (allowed === undefined) {
         return;
-    for (const value of values)
+    }
+    for (const value of values) {
         allowed.add(value);
+    }
 }
 /**
  * The reportable form of one parameter: `name` on its own, or `name:value` when the parameter is a
@@ -60,10 +65,12 @@ export function allowParamValues(name, values) {
  */
 export function describeParam(name, value) {
     const allowed = SAFE_ENUM_PARAMS.get(name);
-    if (allowed === undefined)
+    if (allowed === undefined) {
         return name;
-    if (typeof value !== 'string')
+    }
+    if (typeof value !== 'string') {
         return name;
+    }
     return `${name}:${allowed.has(value) ? value : OTHER_VALUE}`;
 }
 /**
@@ -96,10 +103,12 @@ export function describeCliFlags(argv) {
     const flags = new Set();
     for (const arg of argv) {
         // A bare `--` ends the options: everything after it is passed through to something else.
-        if (END_OF_OPTIONS === arg)
+        if (END_OF_OPTIONS === arg) {
             break;
-        if (!arg.startsWith('--'))
+        }
+        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(KNOWN_CLI_FLAGS.has(name) ? name : OTHER_VALUE);
@@ -117,6 +126,7 @@ const KNOWN_CLI_FLAGS = new Set([
     '--accept-coverage',
     '--agent',
     '--app',
+    '--base',
     '--bug',
     '--capture-bodies',
     '--confirm-dangerous',

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

@@ -4,7 +4,8 @@
  * 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 } from '@reticlehq/core/telemetry';
+import { TelemetryActor, type GateCompleted } from '@reticlehq/core/telemetry';
+import { type Telemetry } from './telemetry.js';
 /** True when this command represents a person typing something. Exported for the gate. */
 export declare function isHumanCliCommand(command: string): boolean;
 /**
@@ -23,3 +24,11 @@ export declare function cliActorOf(env: NodeJS.ProcessEnv): TelemetryActor;
  */
 export declare function claimInstallReport(command: string, firstRun: boolean, stateDir: string): boolean;
 export declare function reportCliRun(argv: readonly string[]): void;
+/**
+ * `gate_completed`: how one `reticle gate` run ended.
+ *
+ * `cli_command_run` says that the gate ran. Only this event says whether it passed. The gate is a
+ * one-shot command that exits immediately, so the send is DETACHED, like `init_completed`.
+ * Best-effort: a metric never changes what the gate decides.
+ */
+export declare function reportGateCompleted(gate: GateCompleted, telemetry?: Pick<Telemetry, 'emit'>): void;

package/dist/telemetry/cli-telemetry.js

@@ -161,3 +161,18 @@ export function reportCliRun(argv) {
         flags: describeCliFlags(argv),
     });
 }
+/**
+ * `gate_completed`: how one `reticle gate` run ended.
+ *
+ * `cli_command_run` says that the gate ran. Only this event says whether it passed. The gate is a
+ * one-shot command that exits immediately, so the send is DETACHED, like `init_completed`.
+ * Best-effort: a metric never changes what the gate decides.
+ */
+export function reportGateCompleted(gate, telemetry = getTelemetry()) {
+    try {
+        void telemetry.emit(TelemetryEventKind.GATE_COMPLETED, { gate, detach: true });
+    }
+    catch {
+        /* a metric never fails the gate */
+    }
+}

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

@@ -11,6 +11,7 @@
  * event loop alive and tax the command by most of a second.
  */
 import { type InitOutcome } from '@reticlehq/core/telemetry';
-export { InitFailure } from '@reticlehq/init';
+import { InitFailure } from '@reticlehq/init';
+export { InitFailure };
 /** Report one init outcome. Best-effort; setup must never fail because a metric did. */
 export declare function reportInitOutcome(init: InitOutcome): void;

package/dist/telemetry/init-telemetry.js

@@ -10,12 +10,56 @@
  * same treatment `cli_command_run` gets, for the same reason: an in-process fetch would keep the
  * event loop alive and tax the command by most of a second.
  */
-import { TelemetryEventKind } from '@reticlehq/core/telemetry';
+import { OnboardingPhase, OnboardingStop, TelemetryEventKind, } from '@reticlehq/core/telemetry';
+import { InitFailure } from '@reticlehq/init';
 import { getTelemetry } from './telemetry.js';
 import { INSTALL_STATE_DIR, resolveInstallSource } from './install-source.js';
+import { reportOnboardingStop } from './onboarding-funnel.js';
 // The failure vocabulary lives in `@reticlehq/init`, which is what classifies a failed run.
 // Re-exported so every consumer here is unchanged.
-export { InitFailure } from '@reticlehq/init';
+export { InitFailure };
+const PROJECT_DETECTED = 'project_detected';
+const INSTRUMENTED = 'instrumented';
+const APP_CONNECTED = 'app_connected';
+/**
+ * Each init failure as one stop, with the first-run step it blocked. A `Record` over the whole
+ * enum, so a new `InitFailure` does not compile until it names its stop.
+ */
+const INIT_STOP = {
+    [InitFailure.NO_PACKAGE_JSON]: { step: PROJECT_DETECTED, stop: OnboardingStop.NO_WEB_APP },
+    [InitFailure.MALFORMED_PACKAGE_JSON]: {
+        step: PROJECT_DETECTED,
+        stop: OnboardingStop.SETUP_FAILED,
+    },
+    [InitFailure.PREFLIGHT]: { step: PROJECT_DETECTED, stop: OnboardingStop.SETUP_FAILED },
+    [InitFailure.DEPENDENCY_INSTALL]: { step: INSTRUMENTED, stop: OnboardingStop.SETUP_FAILED },
+    [InitFailure.MCP_REGISTRATION]: { step: INSTRUMENTED, stop: OnboardingStop.MCP_NOT_REGISTERED },
+    [InitFailure.OTHER]: { step: INSTRUMENTED, stop: OnboardingStop.UNCLASSIFIED },
+    [InitFailure.BRIDGE_OCCUPIED]: { step: APP_CONNECTED, stop: OnboardingStop.SETUP_FAILED },
+    [InitFailure.DEV_SERVER]: { step: APP_CONNECTED, stop: OnboardingStop.DEV_SERVER_FAILED },
+    [InitFailure.APP_CONNECTION]: { step: APP_CONNECTED, stop: OnboardingStop.APP_NOT_CONNECTED },
+    [InitFailure.RUNTIME_ERROR]: { step: APP_CONNECTED, stop: OnboardingStop.UNCLASSIFIED },
+    [InitFailure.INTERRUPTED]: { step: APP_CONNECTED, stop: OnboardingStop.INTERRUPTED },
+};
+const INIT_STOP_UNKNOWN = INIT_STOP[InitFailure.OTHER];
+function initStop(reason) {
+    if (reason !== undefined && Object.hasOwn(INIT_STOP, reason)) {
+        return INIT_STOP[reason];
+    }
+    return INIT_STOP_UNKNOWN;
+}
+/** The stop row of a failed init, or nothing for a run that worked. */
+function reportInitStop(init) {
+    if (init.ok) {
+        return;
+    }
+    reportOnboardingStop({
+        phase: OnboardingPhase.FIRST_RUN,
+        ...initStop(init.reason),
+        ...(init.reason === undefined ? {} : { reason: init.reason }),
+        ...(init.stack === undefined ? {} : { stack: init.stack }),
+    }, { detach: true });
+}
 /** Report one init outcome. Best-effort; setup must never fail because a metric did. */
 export function reportInitOutcome(init) {
     try {
@@ -27,6 +71,7 @@ export function reportInitOutcome(init) {
             // marker, same refusal to infer — see install-source.ts.
             installSource: resolveInstallSource(process.env, INSTALL_STATE_DIR),
         });
+        reportInitStop(init);
     }
     catch {
         /* a metric must never break `reticle init` */

package/dist/telemetry/install-trace.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
-import { OnboardingStepSchema } from '@reticlehq/core/telemetry';
+import { OnboardingStepSchema, OnboardingStop } from '@reticlehq/core/telemetry';
 import { reportOnboardingStep } from './onboarding-funnel.js';
 /**
  * What the one-line installer could not report itself.
@@ -27,6 +27,22 @@ const TRACE_FILE = 'install-trace.jsonl';
  * file must not turn into thousands of events. Far above any real install, which writes three.
  */
 const MAX_LINES = 32;
+/**
+ * The stop that each installer failure reason names. The keys are the reasons that `install.sh`
+ * and `install.ps1` write. A reason not in this table gets no stop.
+ */
+const INSTALLER_STOP = {
+    no_node: OnboardingStop.NO_NODE,
+    node_too_old: OnboardingStop.NODE_TOO_OLD,
+    no_npm: OnboardingStop.CLI_INSTALL_FAILED,
+    npm_install: OnboardingStop.CLI_INSTALL_FAILED,
+    not_on_path: OnboardingStop.CLI_INSTALL_FAILED,
+};
+function installerStop(reason) {
+    return reason !== undefined && Object.hasOwn(INSTALLER_STOP, reason)
+        ? INSTALLER_STOP[reason]
+        : undefined;
+}
 /**
  * Drain the installer's breadcrumbs, once.
  *
@@ -36,8 +52,9 @@ const MAX_LINES = 32;
  */
 export function drainInstallTrace(stateDir) {
     const path = join(stateDir, TRACE_FILE);
-    if (!existsSync(path))
+    if (!existsSync(path)) {
         return 0;
+    }
     let drained = 0;
     try {
         const lines = readFileSync(path, 'utf8')
@@ -55,9 +72,11 @@ export function drainInstallTrace(stateDir) {
             // deliberate belt-and-braces: this is the one path where the payload is a file a person can
             // edit, and rule 3 is that unvalidated text never reaches the wire.
             const step = OnboardingStepSchema.safeParse(parsed);
-            if (!step.success)
+            if (!step.success) {
                 continue;
-            void reportOnboardingStep(step.data);
+            }
+            const stop = installerStop(step.data.reason);
+            void reportOnboardingStep({ ...step.data, ...(stop === undefined ? {} : { stop }) });
             drained += 1;
         }
     }

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

@@ -1,4 +1,4 @@
-import { OnboardingPhase, type OnboardingStep } from '@reticlehq/core/telemetry';
+import { OnboardingPhase, type OnboardingStep, type OnboardingStop } from '@reticlehq/core/telemetry';
 /**
  * The one place an onboarding step is reported.
  *
@@ -11,7 +11,24 @@ import { OnboardingPhase, type OnboardingStep } from '@reticlehq/core/telemetry'
  * arriving as a step name would be a rule-3 leak that no reader would ever notice, because a funnel
  * with one weird row still renders.
  */
-export declare function reportOnboardingStep(step: OnboardingStep): Promise<boolean>;
+export declare function reportOnboardingStep(step: OnboardingStep, opts?: {
+    detach?: boolean;
+}): Promise<boolean>;
+/** One stop: the rung it blocked and its name. The status is always `failed`. */
+export type StopRow = Omit<OnboardingStep, 'status' | 'stop'> & {
+    stop: OnboardingStop;
+};
+/**
+ * Report one stop on the path to a first verdict, once for each process and stop name.
+ *
+ * A daemon can fail to launch Chromium on every lease. One row says the stop happened here; more
+ * rows count retries, not people. Use `detach` from a CLI that exits next, or the row is lost.
+ */
+export declare function reportOnboardingStop(row: StopRow, opts?: {
+    detach?: boolean;
+}): void;
+/** Tests only: forget the stops this process sent. */
+export declare function resetOnboardingStops(): void;
 /**
  * Time a step and report it, whatever happens to it.
  *

package/dist/telemetry/onboarding-funnel.js

@@ -12,13 +12,35 @@ import { getTelemetry } from './telemetry.js';
  * arriving as a step name would be a rule-3 leak that no reader would ever notice, because a funnel
  * with one weird row still renders.
  */
-export async function reportOnboardingStep(step) {
+export async function reportOnboardingStep(step, opts = {}) {
     const parsed = OnboardingStepSchema.safeParse(step);
     // A malformed step is DROPPED rather than sent or thrown. Sending it would put unvalidated text on
     // the wire; throwing would let a metric change what the user's install does, which rule 5 forbids.
-    if (!parsed.success)
+    if (!parsed.success) {
         return false;
-    return getTelemetry().emit(TelemetryEventKind.ONBOARDING_STEP, { onboarding: parsed.data });
+    }
+    return getTelemetry().emit(TelemetryEventKind.ONBOARDING_STEP, {
+        onboarding: parsed.data,
+        ...(true === opts.detach ? { detach: true } : {}),
+    });
+}
+const stopsSent = new Set();
+/**
+ * Report one stop on the path to a first verdict, once for each process and stop name.
+ *
+ * A daemon can fail to launch Chromium on every lease. One row says the stop happened here; more
+ * rows count retries, not people. Use `detach` from a CLI that exits next, or the row is lost.
+ */
+export function reportOnboardingStop(row, opts = {}) {
+    if (stopsSent.has(row.stop)) {
+        return;
+    }
+    stopsSent.add(row.stop);
+    void reportOnboardingStep({ ...row, status: OnboardingStepStatus.FAILED }, opts);
+}
+/** Tests only: forget the stops this process sent. */
+export function resetOnboardingStops() {
+    stopsSent.clear();
 }
 /**
  * Time a step and report it, whatever happens to it.

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

@@ -10,6 +10,7 @@
  * never arrived: the POST was killed every time and nothing threw.
  */
 import { type ProxyExitReason, type WakeRefusalPresence } from '@reticlehq/core/telemetry';
+import type { DaemonDeath } from '@reticlehq/core';
 import { type SessionMetrics } from './session-metrics.js';
 import { type Telemetry } from './telemetry.js';
 export declare function flushProxySessionMetrics(telemetry?: Telemetry, metrics?: SessionMetrics): Promise<void>;
@@ -37,7 +38,7 @@ export declare function reportProxyExited(reason: ProxyExitReason, telemetry?: T
 /** Everything the proxy sends on its way out. Awaited, then the caller exits. */
 export declare function flushProxyExit(reason: ProxyExitReason): Promise<void>;
 /** Send `daemon_died_unclean`. Fire-and-forget is fine for callers: the process lives on. */
-export declare function reportDaemonDiedUnclean(ageMs: number, telemetry?: Telemetry): Promise<void>;
+export declare function reportDaemonDiedUnclean(ageMs: number, cause?: Omit<DaemonDeath, 'ageMs'>, telemetry?: Telemetry): Promise<void>;
 /**
  * Send `wake_refused`, once per process. A dormant proxy refuses again on every client request, and
  * one event per request would count the client's retries, not the refusal.

package/dist/telemetry/proxy-telemetry.js

@@ -73,9 +73,9 @@ export async function flushProxyExit(reason) {
     await Promise.allSettled([flushProxySessionMetrics(), reportProxyExited(reason)]);
 }
 /** Send `daemon_died_unclean`. Fire-and-forget is fine for callers: the process lives on. */
-export async function reportDaemonDiedUnclean(ageMs, telemetry = getTelemetry()) {
+export async function reportDaemonDiedUnclean(ageMs, cause, telemetry = getTelemetry()) {
     await telemetry.emit(TelemetryEventKind.DAEMON_DIED_UNCLEAN, {
-        daemonDeath: { ageMs: Math.max(0, Math.round(ageMs)) },
+        daemonDeath: { ...cause, ageMs: Math.max(0, Math.round(ageMs)) },
     });
 }
 /**