@reticlehq/server 2.5.0 → 2.7.0

package/dist/telemetry/daemon-telemetry.js

@@ -12,17 +12,9 @@ import { getSessionMetrics } from './session-metrics.js';
 import { profileProject } from './project-profile.js';
 import { startUpdateCheck } from '../update/update-nudge.js';
 import { markDaemonStart } from './mcp-connection.js';
+import { markInstrumentationClock } from './app-instrumented.js';
 /** Let the daemon finish coming up before walking the source tree for a profile. */
 const PROJECT_PROFILE_DELAY_MS = 5_000;
-/**
- * How often a long-lived daemon flushes its counters.
- *
- * ponytail: coarse on purpose. A daemon that is SIGKILLed — OOM, a closed laptop, `kill -9` — never
- * reaches its shutdown handler, so without this the whole session's counters die with it. Thirty
- * minutes bounds that loss to one window while keeping the event volume near zero for the common case
- * (most daemons stop cleanly and send exactly one summary). If the lost windows ever show up as a
- * real gap, the upgrade is a small on-disk journal replayed at the next start, not a shorter timer.
- */
 /**
  * How often a running daemon rolls up its window.
  *
@@ -33,6 +25,24 @@ const PROJECT_PROFILE_DELAY_MS = 5_000;
  * serve a tool.
  */
 export const SESSION_FLUSH_MS = 5 * 60 * 1000;
+/**
+ * When a session first rolls up, independent of the periodic interval.
+ *
+ * The interval alone leaves a hole exactly the width of itself: a daemon SIGKILLed before its first
+ * tick — a closed laptop, OOM, `kill -9`, a force-quit editor — reaches no shutdown handler and has
+ * emitted nothing, so the whole session is invisible.
+ *
+ * In the field `daemon_started` outran `daemon_stopped` by a wide margin: **a meaningful share of
+ * sessions never reported a summary at all.** Every "did anyone use Reticle" number is computed only
+ * on the sessions that did, and undercounts by an unknown amount, which is the one thing a funnel
+ * metric must not do.
+ *
+ * Ninety seconds is chosen against what it protects: a session that did real work usually does it
+ * early (snapshot -> act -> assert is seconds), so one early tick captures nearly all of it. It
+ * costs nothing on the daemons that dominate the population, because only a NON-EMPTY window emits
+ * and 74% of daemons never serve a tool at all.
+ */
+export const FIRST_FLUSH_MS = 90 * 1000;
 /**
  * Report the daemon as started, profile the project once, and keep the session counters flushing.
  * Every timer is `unref`'d so telemetry can never be the reason a daemon refuses to exit.
@@ -44,6 +54,9 @@ export function installDaemonTelemetry(cwd, now = () => Date.now()) {
     // this, so a published fix was invisible until someone manually ran `reticle update`.
     startUpdateCheck(now);
     markDaemonStart(now());
+    // Same clock, different half of the install: one measures how long before an AGENT attached, this
+    // one how long before an APP did. The gap between them is the funnel.
+    markInstrumentationClock(now());
     // One profile per daemon start: what kind of project this is and how deeply Reticle is used in it.
     // Deferred off the boot path — it walks the source tree, and nothing about a daemon coming up
     // should wait on a filesystem scan.
@@ -57,7 +70,7 @@ export function installDaemonTelemetry(cwd, now = () => Date.now()) {
             /* a profile is a nice-to-have; it must never touch the daemon */
         }
     }, PROJECT_PROFILE_DELAY_MS).unref();
-    const flush = setInterval(() => {
+    const flushWindow = () => {
         if (metrics.empty)
             return; // an idle window is not worth an event
         // NOT daemon_stopped: the daemon is still running. See SESSION_PROGRESS.
@@ -65,19 +78,25 @@ export function installDaemonTelemetry(cwd, now = () => Date.now()) {
             session: metrics.summarize(false),
         });
         metrics.reset();
-    }, SESSION_FLUSH_MS);
+    };
+    // The early one closes the hole the interval cannot: a session killed before its first tick had
+    // emitted nothing at all. See FIRST_FLUSH_MS.
+    const firstFlush = setTimeout(flushWindow, FIRST_FLUSH_MS);
+    firstFlush.unref();
+    const flush = setInterval(flushWindow, SESSION_FLUSH_MS);
     flush.unref();
     let stopped;
     return {
-        shutdown() {
+        shutdown(exit) {
             // Both SIGTERM and the idle-shutdown path can call this; the second caller awaits the first
             // send rather than emitting a duplicate summary.
             stopped ??= (async () => {
                 clearInterval(flush);
+                clearTimeout(firstFlush);
                 // The rich one: the whole session in a single event — duration, the tool histogram, error
                 // shapes, verifications, browser launches. This is what replaced the per-tool-call event.
                 await getTelemetry().emit(TelemetryEventKind.DAEMON_STOPPED, {
-                    session: metrics.summarize(true),
+                    session: metrics.summarize(true, exit),
                 });
             })();
             return stopped;

package/dist/telemetry/error-class.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Whose defect was that tool error?
+ *
+ * `toolErrors` was one number covering three failures with three different fixes, so the top-line
+ * count could be acted on only by unpacking `errors[]` by hand and reading the prose. Measured over
+ * 2026-08-10/11: 60 `state`, 22 `refusal`, 20 `schema` (serialized zod arrays) and 20 stale refs.
+ * Read as "126 tool errors" that hides the sixth of them where OUR schema failed to explain itself —
+ * which is the only bucket we can fix by writing better descriptions.
+ *
+ * Classified from the message SHAPE, never stored raw: this returns a bucket, and the caller keeps
+ * counts. The full message is already fingerprinted and skeletonised elsewhere.
+ */
+/** Whose defect. Ordered by which fix it implies. */
+export declare const ErrorClass: {
+    /** Missing/unknown parameter, wrong type, unparseable predicate. **Our schema is unclear.** */
+    readonly SCHEMA: "schema";
+    /** No session, stale ref, disconnected. The world moved under the agent; not a schema problem. */
+    readonly STATE: "state";
+    /** We said no on purpose — a destructive block, an unsupported capability. Working as intended. */
+    readonly REFUSAL: "refusal";
+    /** Unrecognised. The bucket to watch: a large one is a blind spot, not a long tail. */
+    readonly OTHER: "other";
+};
+export type ErrorClass = (typeof ErrorClass)[keyof typeof ErrorClass];
+/** Which bucket this message belongs to. Never throws — a classifier must not break a tool path. */
+export declare function classifyError(message: string): ErrorClass;

package/dist/telemetry/error-class.js

@@ -0,0 +1,52 @@
+/**
+ * Whose defect was that tool error?
+ *
+ * `toolErrors` was one number covering three failures with three different fixes, so the top-line
+ * count could be acted on only by unpacking `errors[]` by hand and reading the prose. Measured over
+ * 2026-08-10/11: 60 `state`, 22 `refusal`, 20 `schema` (serialized zod arrays) and 20 stale refs.
+ * Read as "126 tool errors" that hides the sixth of them where OUR schema failed to explain itself —
+ * which is the only bucket we can fix by writing better descriptions.
+ *
+ * Classified from the message SHAPE, never stored raw: this returns a bucket, and the caller keeps
+ * counts. The full message is already fingerprinted and skeletonised elsewhere.
+ */
+/** Whose defect. Ordered by which fix it implies. */
+export const ErrorClass = {
+    /** Missing/unknown parameter, wrong type, unparseable predicate. **Our schema is unclear.** */
+    SCHEMA: 'schema',
+    /** No session, stale ref, disconnected. The world moved under the agent; not a schema problem. */
+    STATE: 'state',
+    /** We said no on purpose — a destructive block, an unsupported capability. Working as intended. */
+    REFUSAL: 'refusal',
+    /** Unrecognised. The bucket to watch: a large one is a blind spot, not a long tail. */
+    OTHER: 'other',
+};
+/**
+ * Patterns, most specific first.
+ *
+ * REFUSAL is tested before STATE because a destructive block often names a session too, and
+ * "we refused on purpose" is the more useful reading of that event.
+ */
+const PATTERNS = [
+    [/confirmdangerous|destructive action blocked/i, ErrorClass.REFUSAL],
+    [
+        /\brefus(e|ed|es|ing)\b|not supported|unsupported|cannot .* a <|contenteditable/i,
+        ErrorClass.REFUSAL,
+    ],
+    [
+        /did not parse|unknown field|unrecognized_keys|missing required|requires a (string|number)|invalid parameter|expected .* received|is larger than/i,
+        ErrorClass.SCHEMA,
+    ],
+    [
+        /no browser session connected|no connected session|multiple sessions connected|session disconnected|no longer resolves|no such session|not connected/i,
+        ErrorClass.STATE,
+    ],
+];
+/** Which bucket this message belongs to. Never throws — a classifier must not break a tool path. */
+export function classifyError(message) {
+    for (const [pattern, cls] of PATTERNS) {
+        if (pattern.test(message))
+            return cls;
+    }
+    return ErrorClass.OTHER;
+}

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

@@ -1,15 +1,20 @@
 import { TelemetryAction } from '../cli/cli-parse.js';
 /**
- * `reticle feedback [--rating 1-5] [--bug] "what happened"` — the human half of the feedback channel.
+ * `reticle feedback [--rating 1-5] [--bug] "what happened"` — the feedback channel as a command.
  *
  * Kept to a single command with no prompts, no editor, and no account: the cost of telling us
  * something has to be lower than the cost of shrugging and moving on, or we only ever hear from people
  * angry enough to open an issue. A bare rating is a valid report; the words are optional garnish.
  *
+ * `--agent --kind <…>` is the same channel for an AGENT that cannot reach `reticle_feedback` — during
+ * `init`, while instrumentation is half-wired, or when the daemon will not start. Those are the
+ * reports we are least likely to hear and most need: every other path we have requires the tool
+ * surface to already work, so a Reticle that fails before it is running fails silently by design.
+ *
  * What is sent is PRINTED before it goes, every time. A channel that carries free text and does not
  * show you the payload is asking for trust it has not earned.
  */
-export declare function handleFeedback(text: string, rating: number | undefined, bug: boolean): Promise<void>;
+export declare function handleFeedback(text: string, rating: number | undefined, bug: boolean, feedbackKind?: string, agent?: boolean): Promise<void>;
 /**
  * `reticle identify` — opt-in, and it shows the consent notice before it sends anything.
  *

package/dist/telemetry/feedback-cli.js

@@ -1,32 +1,43 @@
 import { FeedbackKind, FeedbackSource } from '@reticlehq/core';
-import { BUG_FLAG, RATING_FLAG } from '../cli/cli-parse.js';
+import { AGENT_FLAG, BUG_FLAG, FEEDBACK_KINDS, KIND_FLAG, RATING_FLAG } from '../cli/cli-parse.js';
 import { describeFeedbackPayload, submitFeedback } from './feedback.js';
 import { describeTelemetry, setTelemetryEnabled } from './telemetry.js';
 import { TelemetryAction } from '../cli/cli-parse.js';
 import { clearIdentity, IDENTIFY_NOTICE, readIdentity, saveIdentity, submitIdentity, UsageContextKind, } from './identify.js';
 /**
- * `reticle feedback [--rating 1-5] [--bug] "what happened"` — the human half of the feedback channel.
+ * `reticle feedback [--rating 1-5] [--bug] "what happened"` — the feedback channel as a command.
  *
  * Kept to a single command with no prompts, no editor, and no account: the cost of telling us
  * something has to be lower than the cost of shrugging and moving on, or we only ever hear from people
  * angry enough to open an issue. A bare rating is a valid report; the words are optional garnish.
  *
+ * `--agent --kind <…>` is the same channel for an AGENT that cannot reach `reticle_feedback` — during
+ * `init`, while instrumentation is half-wired, or when the daemon will not start. Those are the
+ * reports we are least likely to hear and most need: every other path we have requires the tool
+ * surface to already work, so a Reticle that fails before it is running fails silently by design.
+ *
  * What is sent is PRINTED before it goes, every time. A channel that carries free text and does not
  * show you the payload is asking for trust it has not earned.
  */
-export async function handleFeedback(text, rating, bug) {
+export async function handleFeedback(text, rating, bug, feedbackKind, agent = false) {
     const line = (s) => {
         process.stdout.write(`${s}\n`);
     };
     if ('' === text && rating === undefined) {
         line(`usage: reticle feedback [${RATING_FLAG} 1-5] [${BUG_FLAG}] "what worked, what didn't"`);
+        line(`       agents: reticle feedback ${AGENT_FLAG} ${KIND_FLAG} <${FEEDBACK_KINDS.join('|')}> "what happened"`);
         line('       your words go to the maintainers; nothing from your app is ever included.');
         process.exitCode = 1;
         return;
     }
     const receipt = await submitFeedback({
-        source: FeedbackSource.HUMAN,
-        kind: bug ? FeedbackKind.BUG : FeedbackKind.EXPERIENCE,
+        // An agent filing through the CLI must not land in the HUMAN bucket: that bucket carries the
+        // ratings and the experience reports, and a few hundred agent reports mixed into it would make
+        // the one number that says whether people like Reticle mean nothing.
+        source: agent ? FeedbackSource.AGENT : FeedbackSource.HUMAN,
+        // `--kind` wins when given; `--bug` stays the shorthand it always was.
+        kind: feedbackKind ??
+            (bug ? FeedbackKind.BUG : FeedbackKind.EXPERIENCE),
         // A rating with no words is a real report, but the schema wants text — say what the rating means.
         text: '' === text ? `rated ${String(rating)}/5 with no comment` : text,
         ...(rating !== undefined ? { rating } : {}),
@@ -38,6 +49,39 @@ export async function handleFeedback(text, rating, bug) {
     line(receipt.sent
         ? 'thanks       your feedback is in. it genuinely changes what gets built next.'
         : `not sent     ${receipt.reason ?? 'unknown reason'}`);
+    for (const extra of identifyInvite(agent))
+        line(extra);
+}
+/**
+ * Offer a HUMAN a way to be replied to — printed after the receipt, never as a prompt.
+ *
+ * Feedback is anonymous by design and stays that way: the report has already been sent by the time
+ * this prints, so nothing here gates or delays it. This is an offer, not a question.
+ *
+ * It routes through `reticle identify`, which already does consented identity properly — it prints
+ * what it will send, states that identifying links this machine's prior anonymous history to that
+ * identity, and has `--forget`. Capturing an address inline on `feedback_submitted` instead would
+ * put PII on the anonymous event stream and break what `docs/telemetry.md` promises in public:
+ * "no domain sniffing, no email inference" and "no personal data is collected".
+ *
+ * Only for humans (an agent has no email), and only when nobody has identified yet — so somebody
+ * who declined is never asked twice.
+ */
+function identifyInvite(agent) {
+    if (agent)
+        return [];
+    try {
+        if (readIdentity() !== undefined)
+            return [];
+    }
+    catch {
+        return []; // unreadable identity file: say nothing rather than risk asking twice
+    }
+    return [
+        '',
+        'want a reply? `reticle identify --context <company|side_project|oss|learning> --email you@example.com`',
+        '             optional, and it tells you exactly what it sends before sending it.',
+    ];
 }
 /**
  * `reticle identify` — opt-in, and it shows the consent notice before it sends anything.

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

@@ -1,15 +1,10 @@
 import { McpScope, type Feedback } from '@reticlehq/core';
 /** The context fields — the whole `Feedback` shape minus what the author supplies. */
 export type FeedbackContext = Pick<Feedback, 'stack' | 'stackMajor' | 'runtime' | 'engine' | 'driver' | 'client' | 'clientVersion' | 'mcpScope'>;
-/**
- * The project's framework and its MAJOR version, or `{}` when package.json is absent, unreadable, or
- * names nothing we recognize. The major comes from `parseMajor` — the same range parser `reticle init`
- * uses to decide React 19 source mapping — so a range like `^15.0.0-canary.3` narrows the same way in
- * both places instead of via a second, subtly different reader.
- */
 export declare function detectStack(cwd: string, read?: (path: string) => string): {
     stack?: string;
     stackMajor?: number;
+    stackSource?: 'cwd' | 'workspace';
 };
 /**
  * User scope unless the project checks in its own MCP registration. `reticle init` deliberately

package/dist/telemetry/feedback-context.js

@@ -9,10 +9,11 @@
  * holds to. Detection is entirely best-effort: an unreadable package.json or an SDK too old to report
  * its runtime yields `undefined`, never a throw and never a guess.
  */
-import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
 import { AppRuntime, McpScope, PageDriver } from '@reticlehq/core';
 import { parseMajor } from '../init/detect.js';
+import { findWorkspaceApps } from '../init/run.js';
 /**
  * Dependency → reported stack, in resolution order. Meta-frameworks come FIRST: a Next app also
  * depends on react, and reporting `react` for it would collapse the single most important segment
@@ -44,10 +45,10 @@ const PROJECT_MCP_FILES = ['.mcp.json', join('.cursor', 'mcp.json'), join('.vsco
  * uses to decide React 19 source mapping — so a range like `^15.0.0-canary.3` narrows the same way in
  * both places instead of via a second, subtly different reader.
  */
-export function detectStack(cwd, read = readFile) {
+function stackOfManifest(dir, read) {
     let pkg;
     try {
-        pkg = JSON.parse(read(join(cwd, PACKAGE_JSON)));
+        pkg = JSON.parse(read(join(dir, PACKAGE_JSON)));
     }
     catch {
         return {};
@@ -62,6 +63,65 @@ export function detectStack(cwd, read = readFile) {
     }
     return {};
 }
+export function detectStack(cwd, read = readFile) {
+    // The cwd wins when it IS an app — never redirect away from the real answer.
+    const here = stackOfManifest(cwd, read);
+    if (here.stack !== undefined)
+        return { ...here, stackSource: 'cwd' };
+    // 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.
+    //
+    // `findWorkspaceApps` is init's discovery, reused rather than reimplemented: it already reads
+    // declared workspaces (pnpm-workspace.yaml, package.json `workspaces`) AND scans top-level
+    // directories, and it was widened once already for a repo shape a user hit twice. A second
+    // detector here would drift from it the first time either changed.
+    try {
+        for (const app of findWorkspaceApps(profileIo(cwd))) {
+            const found = stackOfManifest(join(cwd, app), read);
+            // Reported as `workspace` so the share of projects needing discovery is measurable — that
+            // number is what says whether our inference needs an agent to correct it.
+            if (found.stack !== undefined)
+                return { ...found, stackSource: 'workspace' };
+        }
+    }
+    catch {
+        // Discovery touches the filesystem; a permission error must never cost us the profile event.
+    }
+    return {};
+}
+/**
+ * The three filesystem methods `findWorkspaceApps` needs, rooted at `cwd`.
+ *
+ * Deliberately not the whole `InitIo`: this path must not be able to write, exec or print. What it
+ * cannot do is a stronger guarantee than a rule saying it shouldn't.
+ */
+function profileIo(cwd) {
+    const abs = (rel) => (isAbsolute(rel) ? rel : join(cwd, rel));
+    return {
+        readFile: (rel) => {
+            try {
+                return readFileSync(abs(rel), 'utf8');
+            }
+            catch {
+                return null;
+            }
+        },
+        exists: (rel) => existsSync(abs(rel)),
+        listDirs: (rel) => {
+            try {
+                return readdirSync(abs(rel), { withFileTypes: true })
+                    .filter((e) => e.isDirectory() && !e.name.startsWith('.') && 'node_modules' !== e.name)
+                    .map((e) => e.name);
+            }
+            catch {
+                return [];
+            }
+        },
+    };
+}
 /**
  * User scope unless the project checks in its own MCP registration. `reticle init` deliberately
  * registers ONCE at user scope, so `project` here means the team wired it up by hand — which is

package/dist/telemetry/git-facts.d.ts

@@ -6,6 +6,13 @@ export interface GitFacts {
     origin?: string;
     /** Which forge hosts it, bucketed. Absent unless state is `remote`. */
     forge?: RepoForge;
+    /**
+     * The directory holding `.git` — the repo boundary. Absent only when state is `none`.
+     *
+     * Never sent: it is a local path. It exists so an UNPUSHED repo can still key its projectId to
+     * something stable across every directory inside it, which a raw cwd is not.
+     */
+    root?: string;
 }
 /** `git@github.com:Acme/Web.git` / `https://u:p@github.com/Acme/Web` → `github.com/acme/web`. */
 export declare const normalizeGitOrigin: (url: string) => string;

package/dist/telemetry/git-facts.js

@@ -88,17 +88,17 @@ export function gitFacts(cwd, read = defaultRead, exists = defaultExists) {
             }
             catch {
                 // A `.git` with no readable config is still a repo — report it as one rather than as absent.
-                return { state: GitState.LOCAL_ONLY };
+                return { state: GitState.LOCAL_ONLY, root: dir };
             }
             // The url line inside the [remote "origin"] section — the first url after that header wins.
             const section = config.split(/\[remote\s+"origin"\]/)[1];
             const url = section?.match(/^\s*url\s*=\s*(.+)$/m)?.[1];
             if (url === undefined)
-                return { state: GitState.LOCAL_ONLY };
+                return { state: GitState.LOCAL_ONLY, root: dir };
             const origin = normalizeGitOrigin(url);
             if ('' === origin)
-                return { state: GitState.LOCAL_ONLY };
-            return { state: GitState.REMOTE, origin, forge: forgeOf(origin) };
+                return { state: GitState.LOCAL_ONLY, root: dir };
+            return { state: GitState.REMOTE, origin, forge: forgeOf(origin), root: dir };
         }
         const parent = dirname(dir);
         if (parent === dir)

package/dist/telemetry/project-profile.js

@@ -180,13 +180,14 @@ export function profileProject(cwd, now) {
         featuresUsed.push(FeatureFamily.BUG_CAPSULES);
     if (hasHistory)
         featuresUsed.push(FeatureFamily.CROSS_RUN_HISTORY);
-    const { stack, stackMajor } = detectStack(cwd);
+    const { stack, stackMajor, stackSource } = detectStack(cwd);
     const ageWeeks = projectAgeWeeks(cwd, now);
     const git = gitFacts(cwd);
     return {
         git: git.state,
         ...(git.forge !== undefined ? { forge: git.forge } : {}),
         ...(stack !== undefined ? { stack } : {}),
+        ...(stackSource !== undefined ? { stackSource } : {}),
         ...(stackMajor !== undefined ? { stackMajor } : {}),
         size: sizeBucket(countSourceFiles(cwd)),
         monorepo: isMonorepo(cwd),

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

@@ -41,7 +41,15 @@ export declare class SessionMetrics {
      */
     recordBrowserLatency(ms: number): void;
     /** A call for a tool that does not exist. Non-zero means our surface is confusing the agent. */
-    recordUnknownTool(): void;
+    /**
+     * An agent reached for a tool that does not exist — and WHAT it reached for.
+     *
+     * The name is the point. A count says the surface confused someone; the name says which
+     * capability they expected us to have, in their own vocabulary. Safe to keep: it is a name from
+     * our own namespace, never app data. Bounded and truncated, because a guess is a short
+     * identifier and anything longer is not one.
+     */
+    recordUnknownTool(name?: string): void;
     recordToolCall(tool: string, args?: Record<string, unknown>): void;
     /**
      * One failed tool call. Grouped by fingerprint, but stored WITH its skeleton message and the tool
@@ -62,6 +70,26 @@ export declare class SessionMetrics {
         breadcrumb: string[];
         inFlight: string | undefined;
     };
+    /**
+     * Ask the agent for a verdict, once, when it has driven the page without asking for one.
+     *
+     * In the field most sessions that made a tool call produced no verdict — and
+     * **almost all of those never called a verdict-producing tool even once.** They drove the app
+     * with `reticle_act` and never asked whether it worked. This counter already existed
+     * (`abandonedActions`); it was reported to US and never to the agent.
+     *
+     * Three is the threshold because the median verdict-less session made four tool calls: any higher
+     * and it never fires for the sessions that need it. Re-arms after a verdict, so a second
+     * abandoned run is caught — the loop can break more than once in a long session.
+     */
+    takeUnverifiedNudge(): string | undefined;
+    /**
+     * An app's SDK dialled this daemon.
+     *
+     * Zero of these at shutdown means the daemon ran and no app ever connected — a broken install.
+     * Non-zero with no tool calls is the opposite problem. See SessionSummary.appConnects.
+     */
+    recordAppConnected(): void;
     /** One action driven at the page. Settled by the next verdict; see #unsettledActions. */
     recordAction(): void;
     recordVerification(): void;
@@ -82,12 +110,26 @@ export declare class SessionMetrics {
      * express failure misses the only question worth asking: how often can people not get a browser?
      */
     recordConnectAttempt(kind: BrowserLaunchKind): (failure?: ConnectFailure) => void;
-    recordClient(name: string): void;
+    recordClient(name: string, version?: string): void;
+    /**
+     * The agent's client went away.
+     *
+     * This is the only part of `endReason` that a query cannot derive from the counters: "the client
+     * detached" and "the agent stopped asking" produce identical numbers and are different findings —
+     * one is the task ending, the other is us losing them.
+     */
+    recordClientLeft(): void;
+    /** How many times in a row the current tool has been called. Read by the friction invite. */
+    get currentRun(): number;
+    /** Reticle invited the agent to send feedback. The denominator for feedback_submitted. */
+    recordFeedbackPrompt(): void;
+    /** Which tool surface was advertised to agents this session. */
+    recordSurface(surface: string): void;
     /**
      * Roll the counters into the event payload. `final` marks a clean shutdown; a periodic flush passes
      * false so a session killed before it can exit is not lost entirely (see the flush note in cli.ts).
      */
-    summarize(final: boolean): SessionSummary;
+    summarize(final: boolean, exit?: SessionSummary['exit']): SessionSummary;
     /** True when nothing at all happened — a flush of an idle daemon is not worth an event. */
     get empty(): boolean;
     /** Zero the counters after a non-final flush so the next flush reports the NEXT window, not a total. */