@reticlehq/server 3.1.0 → 3.3.0

package/dist/surface/tools/tools.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { NoSessionAction, QueryBy, ReticleCommand, SnapshotMode } from '@reticlehq/core';
+import { DiscoveryInvite, AttrNamesSchema, EventType, NoSessionAction, 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';
@@ -109,7 +109,7 @@ export const RAW_TOOLS = [
                     lastOutage: z.object({ startedMs: z.number(), durationMs: z.number() }).optional(),
                 })
                     .optional()
-                    .describe('Present only when this tab has dropped and reconnected at least once: how long it has been attached in total, how many outages occurred, and when the last one started and how long it lasted. A verdict over this window spans a gap where nothing was observed.'),
+                    .describe('Continuity of the SDK-to-daemon LINK for this tab, present for any tab the daemon has a record of: how long this attachment has lasted, how many times it dropped and came back, and when the last gap started and how long it lasted. `outages > 0` means a verdict over this window spans a gap where nothing was observed. These are link counters, NOT app health: they say nothing about whether the page origin is still serving, so a tab whose dev server has died reports `outages: 0` with a growing `connectedSinceMs` and is not evidence the app is up.'),
             }))
                 .describe('Connected browser sessions with health state. `projectId` groups sessions by app (stable across port changes); `leased` marks a pool-managed headless context vs a human tab.'),
             why: z
@@ -125,6 +125,10 @@ export const RAW_TOOLS = [
             })
                 .optional()
                 .describe("Present ONLY when `sessions` is empty: the same answer as `why`, executable. `command` is the LITERAL command to run, sourced from this project's own package.json scripts and lockfile — it is absent, never guessed, when the project declares no dev script. `action` is one of daemon_split | start_dev_server | run_init | open_app | reopen_app. `daemon_split` outranks the rest and means the app IS running and instrumented, on a DIFFERENT daemon than the one you are attached to — do not start or re-init anything, read `reason`."),
+            talk_to_us: z
+                .string()
+                .optional()
+                .describe('Present ONLY when `sessions` is empty: a call with the founder for the person you are working with. Offer it; never act on it.'),
             lastKnown: z
                 .object({
                 sessionId: z.string(),
@@ -158,6 +162,8 @@ export const RAW_TOOLS = [
                     ...(why === undefined ? {} : { why }),
                     ...(next === undefined ? {} : { next_action: next }),
                     ...(undefined === lastKnown ? {} : { lastKnown }),
+                    // Setup that never connects is where most people give up; it is the talk worth having.
+                    talk_to_us: DiscoveryInvite.AGENT,
                 };
             }
             return { sessions };
@@ -261,7 +267,7 @@ export const RAW_TOOLS = [
                 scope: asString(args['scope']) ?? '',
                 mode,
                 diff: true === args['diff'],
-            }, deps.snapshots ?? SNAPSHOT_CACHE), mode), mode), mode)));
+            }, deps.snapshots ?? SNAPSHOT_CACHE), mode), mode), mode, resolved)));
         },
     },
     {
@@ -290,10 +296,7 @@ export const RAW_TOOLS = [
                 .boolean()
                 .optional()
                 .describe('Return the `scope` element ITSELF instead of searching inside it. Use when the target is a plain layout container with no role, name, testid or text of its own — which is routinely the element that carries the handler, and is otherwise unreachable because every query excludes its own scope root. Requires `scope`.'),
-            attrs: z
-                .array(z.string())
-                .optional()
-                .describe("Attribute names to return per match, e.g. ['href'] to inventory links or ['src'] for images. Absent attributes are omitted; credential-bearing names are redacted."),
+            attrs: AttrNamesSchema.optional().describe("Attribute NAMES to return per match, e.g. ['href'] for links, ['src'] for images. Projects, never filters: 'name=value' is refused. Absent omitted; credentials redacted."),
             limit: countSchema
                 .optional()
                 .describe('Cap the returned descriptors to the first N (cuts tokens on broad queries). If more matched, the result carries total + truncated:true so the trim is never silent — narrow with name/scope.'),
@@ -371,6 +374,12 @@ export const RAW_TOOLS = [
                     .optional()
                     .describe('Structural clusters on the page — what IS here, to diagnose the miss.'),
                 presentTestids: z.array(z.string()).optional(),
+                // Declared for the same reason presentRegions had to be: undeclared here, it is stripped
+                // from structuredContent without a word — and this field exists precisely to say a word.
+                presentTestidsTotal: z
+                    .number()
+                    .optional()
+                    .describe('Present only when presentTestids was cut at its cap: how many there were. The list is document order, so a region low on the page is what got dropped — absence from the list proves nothing.'),
                 knownEmptyState: z.boolean(),
                 splitText: z
                     .object({
@@ -504,7 +513,12 @@ export const MERGE_PLANS = [
     },
     {
         name: ReticleTool.SESSION,
-        description: 'Session lifecycle and the human channel, by action: "tune" adjusts the presenter session (e.g. idle-end window); "yield" hands control back to the human between turns (mode: waiting|ask) and is MANDATORY before you stop driving; "end" terminates the session for good; "resume" clears a human pause; "messages" drains the human→agent inbox; "review" lists/resolves the mistakes a human pinned to elements; "narrate" states your intent on the presenter HUD.',
+        description: 
+        // `yield` leads, and that is not a style choice. A catalogue prints ONE line per tool, so
+        // whatever comes first is what an agent discovers; when this sentence opened with `tune` the
+        // MANDATORY handback sat past the cut and no agent reading the catalogue ever learned it
+        // existed. The rule is: if a tool has an obligation, the obligation goes first.
+        'Session lifecycle and the human channel, by action: "yield" hands control back to the human and is MANDATORY before you stop driving (mode: waiting|ask, between turns); "tune" adjusts the presenter session (e.g. idle-end window); "end" terminates the session for good; "resume" clears a human pause; "messages" drains the human→agent inbox; "review" lists/resolves the mistakes a human pinned to elements; "narrate" states your intent on the presenter HUD.',
         members: {
             tune: ReticleTool.SESSION_TUNE,
             yield: ReticleTool.YIELD,
@@ -609,24 +623,31 @@ function noteEmptyLeanTree(result, mode) {
  * wrapper or two is ordinary, so this is deliberately not `=== 0`.
  */
 const UNMOUNTED_ROOT_MAX_ELEMENTS = 3;
-/**
- * The third cause of an empty tree, and the one the walk cannot see: the app is not mounted.
- *
- * Reported from the field with the react-three-fiber crash. The source-mapping stamp threw inside
- * R3F's commit phase, React unmounted the entire tree, and the page went white — and the snapshot
- * answered `{ tree: "", nodes: 0 }`, which is also what a page that has not rendered yet answers.
- * The reporter spent a diagnosis pass separating the two, and said that detecting a dead root would
- * have pointed straight at the cause.
- *
- * The other two notes here explain an empty tree by what the WALK passed over. This one cannot: a
- * walk that visited nothing has nothing to have skipped. It reads the DOM count instead, which is
- * why the browser now reports it, and it fires only when the skip counts are silent — a page whose
- * elements were all hidden has plenty of DOM and belongs to `noteHiddenPage`.
- *
- * Like both of its neighbours it names a fact and hands over the next read, and does not diagnose:
- * "not mounted" is certain from the count, WHY is not, and the console is where the answer is.
- */
-function noteUnmountedRoot(result, mode) {
+function crashEvidence(session) {
+    const since = asRecord(session)['eventsSince'];
+    if ('function' !== typeof since)
+        return undefined;
+    let events;
+    try {
+        events = since.call(session, 0);
+    }
+    catch {
+        return undefined;
+    }
+    if (!Array.isArray(events))
+        return undefined;
+    const errors = events.filter((e) => {
+        const type = asString(asRecord(e)['type']);
+        return EventType.CONSOLE_ERROR === type || EventType.ERROR_UNCAUGHT === type;
+    });
+    if (0 === errors.length)
+        return undefined;
+    const first = errors
+        .map((e) => asString(asRecord(asRecord(e)['data'])['message']))
+        .find((m) => undefined !== m && '' !== m);
+    return { count: errors.length, first: first ?? '' };
+}
+function noteUnmountedRoot(result, mode, session) {
     if (SnapshotMode.STATUS === mode)
         return result;
     const row = asRecord(result);
@@ -637,12 +658,31 @@ function noteUnmountedRoot(result, mode) {
     const elements = asNumber(row['domElements']);
     if (elements === undefined || elements > UNMOUNTED_ROOT_MAX_ELEMENTS)
         return result;
+    const mount = `the tree is empty because there is almost nothing in the DOM: ${String(elements)} ` +
+        `element(s) under this scope. That is a mount container with nothing rendered into it, not a ` +
+        `page whose contents were skipped — so the app is UNMOUNTED rather than slow, and waiting ` +
+        `will not change it. `;
+    // An uncaught error beside an empty mount container is the difference between "has not started"
+    // and "started and died", which are the two readings of this count and want opposite next moves.
+    // Nothing here is framework-specific, and deliberately so: the condition is a known mount
+    // container that holds nothing with an uncaught error beside it, which is as true of a Vue or
+    // Svelte root as a React one.
+    const crash = crashEvidence(session);
+    if (crash !== undefined) {
+        return {
+            ...row,
+            note: mount +
+                `The app did not merely fail to start — it CRASHED: ${String(crash.count)} uncaught ` +
+                `error(s) were logged in this session` +
+                ('' === crash.first ? '' : `, the first: "${crash.first}"`) +
+                `. Read reticle_console for the rest, and check anything that runs inside a framework ` +
+                `commit phase. Loading the app again will reproduce it rather than fix it.`,
+        };
+    }
     return {
         ...row,
-        note: `the tree is empty because there is almost nothing in the DOM: ${String(elements)} ` +
-            `element(s) under this scope. That is a mount container with nothing rendered into it, not a ` +
-            `page whose contents were skipped — so the app is UNMOUNTED rather than slow, and waiting ` +
-            `will not change it. An app that was rendering and then stopped has usually thrown: read ` +
+        note: mount +
+            `An app that was rendering and then stopped has usually thrown: read ` +
             `reticle_console for an uncaught error, and check anything that runs inside a framework ` +
             `commit phase. If the app has genuinely not started yet, load it and snapshot again.`,
     };

package/dist/telemetry/bug-found.js

@@ -18,6 +18,12 @@ import { ReticleTool } from '@reticlehq/core';
 import { BugAttribution, BugSource, ContradictionKind, isAbsenceDerived, } from '@reticlehq/core';
 /** Cap per tool call — a pathological crawl must not turn one call into a thousand events. */
 const MAX_BUGS_PER_CALL = 25;
+/** The kinds in a replay's `regressed` list — bare strings, not the `{ kind }` objects above. */
+function regressedKinds(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((kind) => 'string' === typeof kind && kind.length > 0);
+}
 function kindsOf(value) {
     if (!Array.isArray(value))
         return [];
@@ -127,7 +133,12 @@ export function bugsInResult(toolName, result) {
     const verdict = verdictOf(result);
     const passed = true === verdict;
     // 1. Contradictions — channels disagreeing. Invisible to a human watching the screen.
-    for (const kind of kindsOf(result['contradictions'])) {
+    //
+    // `crossStep` is read alongside `contradictions` because a flow replay spells them that way: a
+    // step's window closes when the step ends, so a request fired at step 2 and still unanswered at
+    // step 5 sits outside every per-step window and is exactly the shape a long journey produces.
+    // Every whole-span contradiction a replay found was unreportable for want of this one name.
+    for (const kind of [...kindsOf(result['contradictions']), ...kindsOf(result['crossStep'])]) {
         // A contradiction is two of the APP's own channels disagreeing — never the agent's phrasing.
         // Omitted for the one kind Reticle can produce on its own: see contradictionAttribution.
         bugs.push({
@@ -176,7 +187,26 @@ export function bugsInResult(toolName, result) {
             attribution: BugAttribution.UNCLASSIFIED,
         });
     }
-    // 4. Replay failures — a saved flow that used to pass no longer does. That is a regression caught,
+    // 4. A guarded defect that came BACK. The flow observed it, then observed it gone, and the app
+    //    has now reacquired it — a claim no other detector in this file can make, because only a saved
+    //    flow carries what it has already seen. It is the replay feature's stated payoff and it was
+    //    counted nowhere: `regressed` is a list of KINDS, not of anomaly objects, so neither of the
+    //    array readers above could see it.
+    for (const kind of regressedKinds(result['regressed'])) {
+        bugs.push({
+            source: BugSource.REPLAY,
+            kind,
+            // The replay carries no assertion of its own, so there is no green for this to have hidden
+            // behind. Whether it was a false green is a question about the run that reacquired the defect,
+            // not about the run that noticed.
+            falseGreen: passed,
+            tool: toolName,
+            // Same kind, same owner, wherever it arrives — the line `attributionOf` draws is the one the
+            // verdict already uses, and a defect does not change whose fault it was by coming back.
+            attribution: attributionOf(kind),
+        });
+    }
+    // 5. 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 ('fail' === result['status'] && Array.isArray(result['failures'])) {
         for (const failure of result['failures'].slice(0, MAX_BUGS_PER_CALL)) {

package/dist/telemetry/feedback-context.js

@@ -78,9 +78,9 @@ export function detectStack(cwd, read = readFile) {
     }
     // Otherwise look for the app. The daemon's cwd is wherever the agent's client happened to launch,
     // which for a real repo is the ROOT while the app sits in `frontend/`, `web/`, or a declared
-    // workspace. Reading one directory and giving up is why this returned nothing for every project
-    // that actually had Reticle set up: 0 of 77 instrumented projects, and 0 of 166 `size: huge` ones.
-    // The bigger the repo, the more certainly we failed.
+    // workspace. Reading one directory and giving up is why this returned nothing for essentially
+    // every project that actually had Reticle set up, and why the bigger the repo, the more certainly
+    // we failed. (The measurement that established that came from the field and stays in `plan/`.)
     //
     // `findWorkspaceApps` is init's discovery, reused rather than reimplemented: it already reads
     // declared workspaces (pnpm-workspace.yaml, package.json `workspaces`) AND scans top-level

package/dist/telemetry/feedback-local.d.ts

@@ -1,4 +1,5 @@
 import type { Feedback } from '@reticlehq/core/telemetry';
+/** Reports live beside the rest of the workspace, not in a temp dir somebody has to be told about. */
 interface SavedFeedback {
     path: string;
     /** A ready-to-run command that turns the file into an issue. */

package/dist/telemetry/feedback-local.js

@@ -13,8 +13,6 @@
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { ReticleDir } from '@reticlehq/core';
-/** Reports live beside the rest of the workspace, not in a temp dir somebody has to be told about. */
-const FEEDBACK_SUBDIR = 'feedback';
 /** Filesystem-safe, sortable, and unique enough for one report per second per kind. */
 const stamp = (now) => new Date(now).toISOString().replace(/[:.]/g, '-').replace('Z', '');
 const asMarkdown = (input, text, context) => {
@@ -39,7 +37,7 @@ const asMarkdown = (input, text, context) => {
  */
 export function saveFeedbackLocally(cwd, input, text, context, now = Date.now()) {
     try {
-        const dir = join(cwd, ReticleDir.ROOT, FEEDBACK_SUBDIR);
+        const dir = join(cwd, ReticleDir.ROOT, ReticleDir.FEEDBACK_SUBDIR);
         mkdirSync(dir, { recursive: true });
         const path = join(dir, `${stamp(now)}-${input.kind ?? 'note'}.md`);
         writeFileSync(path, asMarkdown(input, text, context), 'utf8');

package/dist/telemetry/feedback.d.ts

@@ -27,7 +27,7 @@ import { type SessionFacts } from './feedback-context.js';
 export declare const FEEDBACK_ENV = "RETICLE_FEEDBACK";
 /** What replaces a redacted match. Visible on purpose: a reader must see that something was removed. */
 export declare const REDACTED = "[redacted]";
-export interface Redaction {
+interface Redaction {
     text: string;
     /** Which rules fired, deduped. Surfaced back to the author so a redaction is never silent. */
     removed: string[];

package/dist/telemetry/harness-drive.d.ts

@@ -0,0 +1,6 @@
+/** Run `drive` with every verdict underneath it attributed to the harness. */
+export declare function withHarnessDrive<T>(drive: () => Promise<T>): Promise<T>;
+/** True while a harness drive is in progress. */
+export declare function harnessDriving(): boolean;
+/** Tests only — a leaked span would mis-attribute every verdict after it. */
+export declare function resetHarnessDrive(): void;

package/dist/telemetry/harness-drive.js

@@ -0,0 +1,39 @@
+/**
+ * Whether the tool call running right now belongs to one of OUR drives.
+ *
+ * `reticle_verify { action: "explore" }` hands the app to a model inside the daemon, which drives
+ * through the same dispatch chokepoint every agent uses. That is the right design — the inner
+ * `act_and_wait` and `assert` calls are real verifications and must be counted — but it left every
+ * verdict a drive produced indistinguishable from one the user's own agent earned, under the same
+ * session and the same `actor: agent`. So "did this install ever verify anything by itself" had no
+ * answer, and any per-session rate read high by however much we drove.
+ *
+ * Module state, one flag, set for the span of the drive. The same one-hop pattern `tool-refused.ts`
+ * already uses for its pending reason, and for the same reason: the fact is produced in one place
+ * and needed in another, with a chokepoint in between that has no business taking an extra argument
+ * for a metric.
+ *
+ * A COUNTER rather than a boolean, so a drive nested inside a drive cannot clear the flag on its way
+ * out and leave the outer one unmarked.
+ */
+let depth = 0;
+/** Run `drive` with every verdict underneath it attributed to the harness. */
+export async function withHarnessDrive(drive) {
+    depth += 1;
+    try {
+        return await drive();
+    }
+    finally {
+        // In a `finally` because a drive that THREW still drove: leaving the flag raised would attribute
+        // the user's own next verdict to a harness that is no longer running.
+        depth -= 1;
+    }
+}
+/** True while a harness drive is in progress. */
+export function harnessDriving() {
+    return depth > 0;
+}
+/** Tests only — a leaked span would mis-attribute every verdict after it. */
+export function resetHarnessDrive() {
+    depth = 0;
+}

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

@@ -0,0 +1,32 @@
+import { HudPanel, HudView, type HudUseData } from '@reticlehq/core';
+/**
+ * How people use the in-page HUD, rolled into the session summary.
+ *
+ * Windowed like the tool histograms beside it: a periodic flush reports what happened since the
+ * last one, so a dashboard sums across a session's events. Names only — every key is a control id
+ * the wire schema already checked against core's closed list.
+ */
+/** How many steps of the journey one window keeps. A journey longer than this is cut, and says so. */
+export declare const HUD_JOURNEY_MAX = 60;
+export interface HudSummary {
+    /** Presses per control; a toggle counts under `id:on` / `id:off` so a switch reads both ways. */
+    hudControls?: Record<string, number>;
+    /** Milliseconds the HUD spent in each view during the window. */
+    hudViewMs?: Partial<Record<HudView, number>>;
+    /** Milliseconds each panel was showing during the window. */
+    hudPanelMs?: Partial<Record<HudPanel, number>>;
+    /** The window's presses and view changes, in order, cut at HUD_JOURNEY_MAX. */
+    hudJourney?: string[];
+    /** Present, and true, only when the journey was cut. */
+    hudJourneyCut?: true;
+}
+export declare class HudMetrics {
+    #private;
+    constructor(now: () => number);
+    record(use: HudUseData): void;
+    get empty(): boolean;
+    /** The window so far. Open view and panel are counted up to now, and keep running after. */
+    summarize(): HudSummary;
+    /** Start the next window. The current view and panel carry over, timed from now. */
+    reset(): void;
+}

package/dist/telemetry/hud-metrics.js

@@ -0,0 +1,95 @@
+import { isHudControl } from '@reticlehq/core/hud';
+import { HudPanel, HudView } from '@reticlehq/core';
+/**
+ * How people use the in-page HUD, rolled into the session summary.
+ *
+ * Windowed like the tool histograms beside it: a periodic flush reports what happened since the
+ * last one, so a dashboard sums across a session's events. Names only — every key is a control id
+ * the wire schema already checked against core's closed list.
+ */
+/** How many steps of the journey one window keeps. A journey longer than this is cut, and says so. */
+export const HUD_JOURNEY_MAX = 60;
+export class HudMetrics {
+    #now;
+    #controls = new Map();
+    #viewMs = new Map();
+    #panelMs = new Map();
+    #journey = [];
+    #cut = false;
+    /** Did anything happen this window. A HUD merely sitting open is not worth a flush of its own. */
+    #changed = false;
+    #view;
+    #panel;
+    constructor(now) {
+        this.#now = now;
+    }
+    record(use) {
+        // A control the HUD never rendered is dropped here, the one place HUD use is counted, so free
+        // text cannot ride in on the id.
+        const control = use.control !== undefined && isHudControl(use.control) ? use.control : undefined;
+        if (control === undefined && use.view === undefined && use.panel === undefined)
+            return;
+        this.#changed = true;
+        if (control !== undefined) {
+            const key = use.toggle === undefined ? control : `${control}:${use.toggle}`;
+            this.#controls.set(key, (this.#controls.get(key) ?? 0) + 1);
+            this.#step(key);
+        }
+        if (use.view !== undefined && use.view !== this.#view?.value) {
+            this.#close(this.#view, this.#viewMs);
+            this.#view = { value: use.view, since: this.#now() };
+            this.#step(`view:${use.view}`);
+        }
+        if (use.panel !== undefined && use.panel !== this.#panel?.value) {
+            this.#close(this.#panel, this.#panelMs);
+            this.#panel = { value: use.panel, since: this.#now() };
+            if (use.panel !== HudPanel.NONE)
+                this.#step(`panel:${use.panel}`);
+        }
+    }
+    get empty() {
+        return !this.#changed;
+    }
+    /** The window so far. Open view and panel are counted up to now, and keep running after. */
+    summarize() {
+        const viewMs = this.#withOpen(this.#view, this.#viewMs);
+        const panelMs = this.#withOpen(this.#panel, this.#panelMs);
+        return {
+            ...(this.#controls.size > 0 ? { hudControls: Object.fromEntries(this.#controls) } : {}),
+            ...(viewMs.size > 0 ? { hudViewMs: Object.fromEntries(viewMs) } : {}),
+            ...(panelMs.size > 0 ? { hudPanelMs: Object.fromEntries(panelMs) } : {}),
+            ...(this.#journey.length > 0 ? { hudJourney: [...this.#journey] } : {}),
+            ...(this.#cut ? { hudJourneyCut: true } : {}),
+        };
+    }
+    /** Start the next window. The current view and panel carry over, timed from now. */
+    reset() {
+        const at = this.#now();
+        this.#controls.clear();
+        this.#viewMs.clear();
+        this.#panelMs.clear();
+        this.#journey.length = 0;
+        this.#cut = false;
+        this.#changed = false;
+        if (this.#view !== undefined)
+            this.#view = { ...this.#view, since: at };
+        if (this.#panel !== undefined)
+            this.#panel = { ...this.#panel, since: at };
+    }
+    #step(entry) {
+        if (this.#journey.length < HUD_JOURNEY_MAX)
+            this.#journey.push(entry);
+        else
+            this.#cut = true;
+    }
+    #close(open, into) {
+        if (open === undefined)
+            return;
+        into.set(open.value, (into.get(open.value) ?? 0) + Math.max(0, this.#now() - open.since));
+    }
+    #withOpen(open, closed) {
+        const out = new Map(closed);
+        this.#close(open, out);
+        return out;
+    }
+}

package/dist/telemetry/mcp-connection.d.ts

@@ -1,5 +1,18 @@
 export declare function markDaemonStart(now: number): void;
-/** Report one client attaching. Best-effort; a metric must never affect whether a client connects. */
+/**
+ * Report one client attaching, BY NAME. Best-effort; a metric must never affect whether a client
+ * connects.
+ *
+ * The name is required in practice, and that is the fix rather than a restriction. `connection.client`
+ * was defined and documented and never once populated: the only caller reported from
+ * `transport.connect().then(...)`, which resolves when the SSE stream opens — before the client has
+ * said who it is. `clientInfo` first exists at `oninitialized`, so the event carried every fact about
+ * the connection except the one that makes "which agent client converts best" answerable at all.
+ *
+ * An unnamed call reports NOTHING. A stream that opens and never completes a handshake is a probe,
+ * not a client attaching, and counting it was what put an unattributable row exactly where the name
+ * belonged.
+ */
 export declare function reportMcpConnected(client?: string, now?: () => number): void;
 /** Tests only. */
 export declare function resetMcpConnections(): void;

package/dist/telemetry/mcp-connection.js

@@ -19,8 +19,23 @@ export function markDaemonStart(now) {
     daemonStartedAt = now;
     connectsSeen = 0;
 }
-/** Report one client attaching. Best-effort; a metric must never affect whether a client connects. */
+/**
+ * Report one client attaching, BY NAME. Best-effort; a metric must never affect whether a client
+ * connects.
+ *
+ * The name is required in practice, and that is the fix rather than a restriction. `connection.client`
+ * was defined and documented and never once populated: the only caller reported from
+ * `transport.connect().then(...)`, which resolves when the SSE stream opens — before the client has
+ * said who it is. `clientInfo` first exists at `oninitialized`, so the event carried every fact about
+ * the connection except the one that makes "which agent client converts best" answerable at all.
+ *
+ * An unnamed call reports NOTHING. A stream that opens and never completes a handshake is a probe,
+ * not a client attaching, and counting it was what put an unattributable row exactly where the name
+ * belonged.
+ */
 export function reportMcpConnected(client, now = () => Date.now()) {
+    if (client === undefined)
+        return;
     try {
         const reconnect = connectsSeen > 0;
         connectsSeen += 1;
@@ -30,7 +45,7 @@ export function reportMcpConnected(client, now = () => Date.now()) {
                 // A large value on the FIRST connect is the interesting case: Reticle was started and then
                 // sat there. On a reconnect it is just how long the daemon has been up.
                 daemonAgeMs: daemonStartedAt === undefined ? 0 : Math.max(0, now() - daemonStartedAt),
-                ...(client !== undefined ? { client } : {}),
+                client,
                 // WHAT THE AGENT HAD TO LOOK AT. Most clients that attach never call a tool, and that cohort
                 // emits nothing at all — an agent that reads the instructions, learns nothing is wired and
                 // stops has refused nothing, so `tool_refused` cannot see it either. Read off the same flag

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

@@ -1,5 +1,21 @@
 /** A tool call the daemon just ran. Called from the dispatch chokepoint, which sees every one. */
-export declare function noteOnboardingFirst(toolName: string, args: Record<string, unknown>): void;
+export declare function noteOnboardingFirst(toolName: string): void;
+/**
+ * The first ACTION of this run, and the fact that this install has been driven at all.
+ *
+ * Called from the dispatch chokepoint's own action branch rather than matched on a tool name here.
+ * The name test was `toolName === ReticleTool.ACT`, on the worry that `act_and_wait` would report
+ * one call as two different firsts — and the worry was backwards: this server's instructions tell
+ * every agent to PREFER `act_and_wait`, so the step measured the tool we ask agents not to use and
+ * the ONBOARD phase read as "looked, never acted, then produced a verdict from nowhere". A call that
+ * both acts and proves genuinely did both, and `first_act` and `first_verdict` are different steps
+ * in different positions of the same funnel.
+ *
+ * Taking the decision from the caller is what keeps it from happening again: the dispatcher already
+ * owns the set of tools that drive the page, and a second copy of that set here is a second thing to
+ * update when a fourth driving tool arrives.
+ */
+export declare function noteActed(args: Record<string, unknown>): void;
 /**
  * The first verdict of this run.
  *
@@ -7,5 +23,18 @@ export declare function noteOnboardingFirst(toolName: string, args: Record<strin
  * and only the site that already decided "this was a verification" can say so. Reported from there.
  */
 export declare function noteFirstVerdict(): void;
+/**
+ * Something was driven on the user's own project — the FIRST_RUN rung between "the install worked"
+ * and "they used it".
+ *
+ * Declared in the closed step list from the day the funnel was written and emitted by no code at
+ * all, so any chart rendered over the declared order showed a 100% cliff in the middle of the
+ * conversion story. It reads as catastrophe and was an unwired emit.
+ *
+ * Reported from `noteActed`, so the one place that knows a tool drove the page is the one place that
+ * says so. That includes a drive we run on the user's behalf, whose own actions cross the same
+ * chokepoint — a drive that is refused before its first action drove nothing and says nothing.
+ */
+export declare function noteDriven(): void;
 /** Arm again for the next daemon run — the tests' seam, mirroring resetAppInstrumented. */
 export declare function resetOnboardingFirsts(): void;

package/dist/telemetry/onboarding-firsts.js

@@ -14,9 +14,9 @@ import { reportOnboardingStep } from './onboarding-funnel.js';
  * The flags are module state rather than per-session, because a person who tours in one tab and
  * drives in another has still only crossed each of these once.
  */
-const seen = { look: false, act: false, verdict: false };
+const seen = { look: false, act: false, verdict: false, driven: false };
 /** A tool call the daemon just ran. Called from the dispatch chokepoint, which sees every one. */
-export function noteOnboardingFirst(toolName, args) {
+export function noteOnboardingFirst(toolName) {
     if (!seen.look && LOOK_TOOLS.has(toolName)) {
         seen.look = true;
         void reportOnboardingStep({
@@ -25,16 +25,35 @@ export function noteOnboardingFirst(toolName, args) {
             status: OnboardingStepStatus.COMPLETED,
         });
     }
-    // An ACT, not a verdict tool that happens to act: `act_and_wait` is counted below as the verdict
-    // it produces, and counting it here too would report one call as two different firsts.
-    if (!seen.act && toolName === ReticleTool.ACT && args['action'] !== ActionType.HOVER) {
-        seen.act = true;
-        void reportOnboardingStep({
-            phase: OnboardingPhase.ONBOARD,
-            step: 'first_act',
-            status: OnboardingStepStatus.COMPLETED,
-        });
-    }
+}
+/**
+ * The first ACTION of this run, and the fact that this install has been driven at all.
+ *
+ * Called from the dispatch chokepoint's own action branch rather than matched on a tool name here.
+ * The name test was `toolName === ReticleTool.ACT`, on the worry that `act_and_wait` would report
+ * one call as two different firsts — and the worry was backwards: this server's instructions tell
+ * every agent to PREFER `act_and_wait`, so the step measured the tool we ask agents not to use and
+ * the ONBOARD phase read as "looked, never acted, then produced a verdict from nowhere". A call that
+ * both acts and proves genuinely did both, and `first_act` and `first_verdict` are different steps
+ * in different positions of the same funnel.
+ *
+ * Taking the decision from the caller is what keeps it from happening again: the dispatcher already
+ * owns the set of tools that drive the page, and a second copy of that set here is a second thing to
+ * update when a fourth driving tool arrives.
+ */
+export function noteActed(args) {
+    // A hover changes nothing and is not an action anybody drove.
+    if (args['action'] === ActionType.HOVER)
+        return;
+    noteDriven();
+    if (seen.act)
+        return;
+    seen.act = true;
+    void reportOnboardingStep({
+        phase: OnboardingPhase.ONBOARD,
+        step: 'first_act',
+        status: OnboardingStepStatus.COMPLETED,
+    });
 }
 /**
  * The first verdict of this run.
@@ -52,6 +71,28 @@ export function noteFirstVerdict() {
         status: OnboardingStepStatus.COMPLETED,
     });
 }
+/**
+ * Something was driven on the user's own project — the FIRST_RUN rung between "the install worked"
+ * and "they used it".
+ *
+ * Declared in the closed step list from the day the funnel was written and emitted by no code at
+ * all, so any chart rendered over the declared order showed a 100% cliff in the middle of the
+ * conversion story. It reads as catastrophe and was an unwired emit.
+ *
+ * Reported from `noteActed`, so the one place that knows a tool drove the page is the one place that
+ * says so. That includes a drive we run on the user's behalf, whose own actions cross the same
+ * chokepoint — a drive that is refused before its first action drove nothing and says nothing.
+ */
+export function noteDriven() {
+    if (seen.driven)
+        return;
+    seen.driven = true;
+    void reportOnboardingStep({
+        phase: OnboardingPhase.FIRST_RUN,
+        step: 'driven',
+        status: OnboardingStepStatus.COMPLETED,
+    });
+}
 /** Looking: the tools that read the page without changing it. */
 const LOOK_TOOLS = new Set([
     ReticleTool.SNAPSHOT,
@@ -64,4 +105,5 @@ export function resetOnboardingFirsts() {
     seen.look = false;
     seen.act = false;
     seen.verdict = false;
+    seen.driven = false;
 }