@reticlehq/server 2.5.0 → 2.7.0

package/dist/telemetry/session-metrics.js

@@ -19,6 +19,7 @@ import { BrowserLaunchKind, } from '@reticlehq/core';
 import { errorSkeleton, fingerprintError } from './error-fingerprint.js';
 import { describeToolParams } from './argument-shape.js';
 import { machineSnapshot } from './machine-snapshot.js';
+import { classifyError } from './error-class.js';
 /** Cap the distinct error shapes held in memory — a pathological loop must not grow unbounded. */
 const MAX_ERROR_KINDS = 40;
 /** Distinct tool names whose repeat-runs are tracked. Its own cap: the tool surface, not error shapes. */
@@ -46,6 +47,13 @@ const MAX_PARAMS_PER_TOOL = 24;
  * strings and costs nothing to hold.
  */
 const BREADCRUMB_LENGTH = 12;
+/**
+ * Actions driven with no verdict before Reticle asks for one.
+ *
+ * Three, because the median verdict-less session made FOUR tool calls (2026-08-10/11). A higher
+ * threshold never fires for the sessions that need it most.
+ */
+const UNVERIFIED_ACTION_NUDGE_AT = 3;
 /**
  * Mutable counters for one daemon lifetime. A plain class, not a store: it is process-local, it never
  * persists, and it dies with the daemon.
@@ -54,6 +62,27 @@ export class SessionMetrics {
     #toolCalls = 0;
     #toolErrors = 0;
     #verifications = 0;
+    /**
+     * Session-LIFETIME totals for the four numbers the funnel is computed from.
+     *
+     * `reset()` zeroes every window counter on each periodic flush, but `durationMs` is measured from
+     * `#startedAt` and is never reset. So the FINAL summary — the one whose docstring promises "the
+     * whole session in a single event" — reported a 30-minute session containing zero tool calls,
+     * because it only ever carried the residue since the last flush.
+     *
+     * In the field almost every `daemon_stopped` row had `toolCalls: 0`, at a median
+     * duration of 30.5 minutes, while `session_progress` for the same daemons carried real tool
+     * histograms. Anyone computing "did this session use Reticle" off the event named for the end of
+     * the session got `no` essentially always. That is not a small skew — it is the funnel reading
+     * zero at the exact step this release exists to raise.
+     *
+     * Window semantics are unchanged: `session_progress` still reports its own window, so nothing that
+     * already sums those events double-counts. Only `final: true` swaps in the lifetime numbers.
+     */
+    #lifetimeToolCalls = 0;
+    #lifetimeToolErrors = 0;
+    #lifetimeVerifications = 0;
+    #lifetimeBugsFound = 0;
     #toolCounts = new Map();
     #toolParams = new Map();
     /** Ring of the most recent tool NAMES — the agent's approach run, for a crash report. */
@@ -69,6 +98,12 @@ export class SessionMetrics {
     #concurrent = 0;
     #peakConcurrent = 0;
     #unknownToolCalls = 0;
+    /**
+     * Names the agent guessed at, session-LIFETIME — a guess made early must still be reported at
+     * the end, so this is deliberately not cleared by a flush.
+     */
+    #unknownTools = new Map();
+    #lifetimeUnknownToolCalls = 0;
     #bugsFound = 0;
     #browserMs = 0;
     #browserCommands = 0;
@@ -101,7 +136,33 @@ export class SessionMetrics {
      * run, which is exactly what the field claims to mean.
      */
     #unsettledActions = 0;
+    /** One-shot latch for the verdict nudge — see takeUnverifiedNudge. */
+    #nudgedUnverified = false;
+    /** The agent detached. The one part of `endReason` a query cannot derive. */
+    #clientLeft = false;
+    /** Feedback invitations shown, session-lifetime — the denominator for feedback_submitted. */
+    #feedbackPrompted = 0;
+    /** Error buckets by whose defect. Session-lifetime: the mix is a fact about the session. */
+    #errorClasses = new Map();
+    /**
+     * The recovery hinge. A call's outcome is only known once the NEXT one starts, so the verdict for
+     * call N-1 is resolved at the start of call N (and for the last call, at summarize).
+     */
+    #currentCallErrored = false;
+    #priorCallErrored = false;
+    #errorsRecovered = 0;
+    #errorsRepeated = 0;
+    /**
+     * App SDK connections, session-lifetime. NOT reset by a flush: "did an app ever connect" is a
+     * fact about the session, and a page reload after a flush must not erase it.
+     */
+    #appConnects = 0;
+    #firstAppAt;
     #clients = new Set();
+    /** Client name -> version, session-lifetime. Never cleared: who drove is a fact about the session. */
+    #clientVersions = new Map();
+    /** Which tool surface the daemon advertised. */
+    #surface;
     #startedAt;
     #now;
     /** Clock injected — this file must stay testable without a real one, per the repo's clock rule. */
@@ -146,10 +207,36 @@ export class SessionMetrics {
         this.#browserCommands += 1;
     }
     /** A call for a tool that does not exist. Non-zero means our surface is confusing the agent. */
-    recordUnknownTool() {
+    /**
+     * 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) {
         this.#unknownToolCalls += 1;
+        this.#lifetimeUnknownToolCalls += 1;
+        if (name === undefined || 0 === name.length)
+            return;
+        const key = name.slice(0, 64);
+        const seen = this.#unknownTools.get(key);
+        if (seen !== undefined) {
+            this.#unknownTools.set(key, seen + 1);
+            return;
+        }
+        // Stop growing once full: a pathological loop must not balloon the payload. The head is what
+        // gets built; the tail is noise.
+        if (this.#unknownTools.size >= MAX_ERROR_KINDS)
+            return;
+        this.#unknownTools.set(key, 1);
     }
     recordToolCall(tool, args) {
+        // `recordToolCall` runs BEFORE a handler and `recordToolError` after it fails, so a call's
+        // outcome is only known once the NEXT call starts. Resolve the one before it here; the final
+        // call is resolved in summarize.
+        this.#resolveRecovery();
         // A run of the same tool back to back. Five calls to reticle_act is engagement; five in a row
         // after four failures is an agent stuck, and toolCounts reports both as "5".
         this.#currentRun = tool === this.#lastTool ? this.#currentRun + 1 : 1;
@@ -161,6 +248,7 @@ export class SessionMetrics {
                 this.#repeatRuns.set(tool, this.#currentRun);
         }
         this.#toolCalls += 1;
+        this.#lifetimeToolCalls += 1;
         bump(this.#toolCounts, tool);
         this.#inFlight = tool;
         this.#breadcrumb.push(tool);
@@ -190,6 +278,11 @@ export class SessionMetrics {
      */
     recordToolError(message, tool) {
         this.#toolErrors += 1;
+        this.#lifetimeToolErrors += 1;
+        // Whose defect. Only the `schema` bucket is fixable by writing better descriptions, and it was
+        // indistinguishable from the rest inside one `toolErrors` count.
+        bump(this.#errorClasses, classifyError(message));
+        this.#currentCallErrored = true;
         if (NO_SESSION_ERROR.test(message))
             this.#noSessionErrors += 1;
         const fingerprint = fingerprintError(message);
@@ -236,14 +329,51 @@ export class SessionMetrics {
     get trail() {
         return { breadcrumb: [...this.#breadcrumb], inFlight: this.#inFlight };
     }
+    /**
+     * 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() {
+        if (this.#unsettledActions < UNVERIFIED_ACTION_NUDGE_AT || this.#nudgedUnverified) {
+            return undefined;
+        }
+        this.#nudgedUnverified = true;
+        return (`you have driven this page ${String(this.#unsettledActions)} times without asking for a ` +
+            'verdict. Only reticle_act_and_wait and reticle_assert produce one — everything else moves ' +
+            'or reads the app and proves nothing. Name the consequence you expect and check it: ' +
+            'reticle_assert({ sessionId, since, predicate }), or use reticle_act_and_wait({ ref, ' +
+            'action, until }) for the next step so the action and its check are one call.');
+    }
+    /**
+     * 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() {
+        this.#appConnects += 1;
+        this.#firstAppAt ??= this.#now();
+    }
     /** One action driven at the page. Settled by the next verdict; see #unsettledActions. */
     recordAction() {
         this.#unsettledActions += 1;
     }
     recordVerification() {
         this.#verifications += 1;
+        this.#lifetimeVerifications += 1;
         // A verdict settles whatever was outstanding, however many actions it took to get there.
         this.#unsettledActions = 0;
+        // Re-arm the nudge: the loop can break more than once in an 11-hour session, and an agent that
+        // complied once and then drifted again is exactly the case worth catching.
+        this.#nudgedUnverified = false;
     }
     /**
      * One defect found in the app under test — the outcome number, kept broken down by kind.
@@ -254,6 +384,7 @@ export class SessionMetrics {
      */
     recordBug(kind) {
         this.#bugsFound += 1;
+        this.#lifetimeBugsFound += 1;
         if (this.#bugKinds.size < MAX_ERROR_KINDS || this.#bugKinds.has(kind))
             bump(this.#bugKinds, kind);
         const first = !this.#seenBugKinds.has(kind);
@@ -285,26 +416,76 @@ export class SessionMetrics {
             stats.failures[failure] = (stats.failures[failure] ?? 0) + 1;
         };
     }
-    recordClient(name) {
+    recordClient(name, version) {
+        const key = name.slice(0, 64);
         if (this.#clients.size < MAX_CLIENTS)
-            this.#clients.add(name.slice(0, 64));
+            this.#clients.add(key);
+        // The version was already in the handshake and was being dropped. A regression in agent
+        // behaviour is usually a client version, and without this it is unattributable.
+        if (version !== undefined && '' !== version && this.#clientVersions.size < MAX_CLIENTS) {
+            this.#clientVersions.set(key, version.slice(0, 32));
+        }
+    }
+    /**
+     * 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() {
+        this.#clientLeft = true;
+    }
+    /** How many times in a row the current tool has been called. Read by the friction invite. */
+    get currentRun() {
+        return this.#currentRun;
+    }
+    /** Reticle invited the agent to send feedback. The denominator for feedback_submitted. */
+    recordFeedbackPrompt() {
+        this.#feedbackPrompted += 1;
+    }
+    /** Which tool surface was advertised to agents this session. */
+    recordSurface(surface) {
+        this.#surface = surface.slice(0, 32);
     }
     /**
      * 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) {
+    summarize(final, exit) {
+        // The last call has no successor to resolve it, so resolve it here. Only on a FINAL summary:
+        // a periodic flush is not the end of anything and would resolve a call still in flight.
+        if (final)
+            this.#resolveRecovery();
         const machine = machineSnapshot();
+        // A FINAL summary reports the session; a periodic flush reports its window. `durationMs` was
+        // always session-lifetime, so a windowed count next to it described a 30-minute session that
+        // made no calls. The histograms below stay windowed by design — summing them across a session's
+        // events is correct, and duplicating every map to make them lifetime would double the memory
+        // this class exists to keep small.
+        const scalars = final
+            ? {
+                toolCalls: this.#lifetimeToolCalls,
+                toolErrors: this.#lifetimeToolErrors,
+                verifications: this.#lifetimeVerifications,
+                bugsFound: this.#lifetimeBugsFound,
+            }
+            : {
+                toolCalls: this.#toolCalls,
+                toolErrors: this.#toolErrors,
+                verifications: this.#verifications,
+                bugsFound: this.#bugsFound,
+            };
         return {
             durationMs: Math.max(0, this.#now() - this.#startedAt),
-            toolCalls: this.#toolCalls,
+            toolCalls: scalars.toolCalls,
             toolCounts: Object.fromEntries(this.#toolCounts),
-            toolErrors: this.#toolErrors,
+            toolErrors: scalars.toolErrors,
             ...(this.#errorKinds.size > 0 ? { errors: [...this.#errorKinds.values()] } : {}),
             sdkFailures: this.#sdkFailures,
             ...(this.#sdkFailureKinds.size > 0 ? { sdkErrors: [...this.#sdkFailureKinds.values()] } : {}),
-            verifications: this.#verifications,
-            bugsFound: this.#bugsFound,
+            verifications: scalars.verifications,
+            bugsFound: scalars.bugsFound,
             ...(this.#bugKinds.size > 0 ? { bugKinds: Object.fromEntries(this.#bugKinds) } : {}),
             ...(this.#noSessionErrors > 0 ? { noSessionErrors: this.#noSessionErrors } : {}),
             ...(this.#repeatRuns.size > 0
@@ -323,12 +504,69 @@ export class SessionMetrics {
             browserMs: this.#browserMs,
             browserCommands: this.#browserCommands,
             peakConcurrentTools: this.#peakConcurrent,
-            unknownToolCalls: this.#unknownToolCalls,
+            unknownToolCalls: final ? this.#lifetimeUnknownToolCalls : this.#unknownToolCalls,
+            ...(this.#unknownTools.size > 0
+                ? { unknownTools: Object.fromEntries(this.#unknownTools) }
+                : {}),
             ...(machine !== undefined ? { machine } : {}),
             ...(this.#clients.size > 0 ? { clients: [...this.#clients] } : {}),
+            ...(this.#clientVersions.size > 0
+                ? { clientVersions: Object.fromEntries(this.#clientVersions) }
+                : {}),
+            ...(this.#surface === undefined ? {} : { surface: this.#surface }),
+            ...(final ? { endReason: this.#endReason() } : {}),
+            ...(this.#feedbackPrompted > 0 ? { feedbackPrompted: this.#feedbackPrompted } : {}),
+            ...(this.#errorClasses.size > 0
+                ? { errorClasses: Object.fromEntries(this.#errorClasses) }
+                : {}),
+            ...(this.#errorsRecovered > 0 ? { errorsRecovered: this.#errorsRecovered } : {}),
+            ...(this.#errorsRepeated > 0 ? { errorsRepeated: this.#errorsRepeated } : {}),
+            // Always present, including zero: absence and "no app ever connected" must not look alike,
+            // because zero IS the finding here.
+            appConnects: this.#appConnects,
+            ...(this.#firstAppAt === undefined
+                ? {}
+                : { msToFirstApp: Math.max(0, this.#firstAppAt - this.#startedAt) }),
             final,
+            // Only on a real exit. A periodic flush carrying `exit: "unknown"` would read as a daemon that
+            // died without a shutdown path, which is the one thing this field exists to make visible.
+            ...(final && exit !== undefined ? { exit } : {}),
         };
     }
+    /**
+     * Decide whether the error before the previous call was recovered from or repeated.
+     *
+     * Called at the start of each new call (resolving the one before it) and once at summarize (for
+     * the last call). Shifting rather than counting on the spot is what makes "the agent tried
+     * something else and it worked" distinguishable from "it failed the same way again" — an earlier
+     * version counted a recovery the moment a call STARTED, so a call that then failed was recorded
+     * as a success.
+     */
+    #resolveRecovery() {
+        if (this.#priorCallErrored) {
+            if (this.#currentCallErrored)
+                this.#errorsRepeated += 1;
+            else
+                this.#errorsRecovered += 1;
+        }
+        this.#priorCallErrored = this.#currentCallErrored;
+        this.#currentCallErrored = false;
+    }
+    /**
+     * What state the agent's work was in at the end. Ordered by which fact outranks which: a client
+     * that left explains everything after it, and a verdict settles whatever preceded it.
+     */
+    #endReason() {
+        if (0 === this.#lifetimeToolCalls)
+            return 'never_used';
+        if (this.#clientLeft)
+            return 'client_left';
+        if (this.#unsettledActions > 0)
+            return 'abandoned';
+        if (this.#lifetimeVerifications > 0)
+            return 'verified';
+        return 'explored';
+    }
     /** True when nothing at all happened — a flush of an idle daemon is not worth an event. */
     get empty() {
         return (0 === this.#toolCalls &&

package/dist/telemetry/telemetry.d.ts

@@ -1,4 +1,4 @@
-import { TelemetryEventKind, type Crash, type Feedback, type Identity, type BugFound, type InitOutcome, type McpConnection, type McpOutage, type ProjectProfile, type SessionSummary, type TelemetryActor, type Verification, type VersionChange } from '@reticlehq/core';
+import { TelemetryEventKind, ProjectIdSource, type Crash, type Feedback, type Identity, type BugFound, type InitOutcome, type McpConnection, type McpOutage, type AppInstrumentation, type ProjectProfile, type SessionSummary, type TelemetryActor, type Verification, type VersionChange } from '@reticlehq/core';
 /**
  * Feedback gets its own, much larger budget — and a retry.
  *
@@ -15,6 +15,24 @@ import { TelemetryEventKind, type Crash, type Feedback, type Identity, type BugF
 export declare const FEEDBACK_TIMEOUT_MS = 15000;
 export declare const FEEDBACK_RETRIES = 1;
 export declare const FEEDBACK_RETRY_BACKOFF_MS = 750;
+/**
+ * One-way project fingerprint: distinct-count of this = "projects Reticle is used in", reveals nothing.
+ *
+ * Prefers a hash of the git ORIGIN over a hash of the cwd. The contract in `@reticlehq/core` always
+ * said "one-way hash of the git remote (or cwd)", but the implementation only ever hashed the path —
+ * which meant the same repo cloned by four teammates, or checked out twice on one machine, counted as
+ * four separate projects. That inflates the project count and, worse, makes team adoption look like
+ * unrelated individuals. Hashing the origin dedupes a real project down to one id across every clone.
+ *
+ * Still one-way, still non-reversible, and still exactly what the published policy describes: the
+ * remote URL itself never leaves the machine, only its SHA-256. The URL is normalized first (scheme,
+ * credentials, `.git` suffix and case removed) so `git@github.com:acme/web.git` and
+ * `https://github.com/Acme/web` are recognized as the same project rather than two.
+ */
+export declare const projectFingerprint: (cwd: string) => {
+    projectId: string;
+    source: ProjectIdSource;
+};
 /** The current telemetry state and which control set it — what `reticle telemetry status` prints. */
 export declare const describeTelemetry: (env?: NodeJS.ProcessEnv, dir?: string, cwd?: string) => {
     enabled: boolean;
@@ -56,6 +74,8 @@ export interface TelemetryExtra {
     bug?: BugFound;
     /** `mcp_connection_lost`: the agent lost its tools — which stage, and why. */
     outage?: McpOutage;
+    /** `app_instrumented`: an app carrying the SDK reached this daemon for the first time. */
+    instrumentation?: AppInstrumentation;
 }
 export interface Telemetry {
     /**

package/dist/telemetry/telemetry.js

@@ -18,7 +18,7 @@ import { spawn } from 'node:child_process';
 import { randomUUID, createHash } from 'node:crypto';
 import { appendFileSync, readFileSync, writeFileSync, mkdirSync, existsSync, rmSync, } from 'node:fs';
 import { homedir, platform } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { TelemetryEventKind, TELEMETRY_EVENT_VERSION, ProjectIdSource, isSessionScoped, } from '@reticlehq/core';
 import { SERVER_VERSION } from '../version/server-version.js';
 const RETICLE_DIR = join(homedir(), '.reticle');
@@ -144,17 +144,40 @@ const resolveIdentity = () => {
  * credentials, `.git` suffix and case removed) so `git@github.com:acme/web.git` and
  * `https://github.com/Acme/web` are recognized as the same project rather than two.
  */
-const projectFingerprint = (cwd) => {
-    const { origin } = gitFacts(cwd);
+export const projectFingerprint = (cwd) => {
+    const { origin, root } = gitFacts(cwd);
+    // Ordered by stability, not by preference: an origin is comparable across machines, a repo root is
+    // stable across every directory inside one machine's checkout, a package.json root is the same for
+    // a non-git project — and the raw cwd is stable across nothing, which is why it is last. See
+    // `project-identity.test.ts` for what a wrong order costs.
+    const { key, source } = origin !== undefined
+        ? { key: origin, source: ProjectIdSource.GIT_ORIGIN }
+        : root !== undefined
+            ? { key: root, source: ProjectIdSource.GIT_ROOT }
+            : packageRoot(cwd) !== null
+                ? { key: packageRoot(cwd) ?? cwd, source: ProjectIdSource.PACKAGE_ROOT }
+                : { key: cwd, source: ProjectIdSource.CWD };
     return {
-        projectId: createHash('sha256')
-            .update(origin ?? cwd)
-            .digest('hex')
-            .slice(0, 32),
+        projectId: createHash('sha256').update(key).digest('hex').slice(0, 32),
         // Reported alongside so the analytics knows whether this id is comparable to another machine's.
-        source: origin !== undefined ? ProjectIdSource.GIT_ORIGIN : ProjectIdSource.CWD,
+        source,
     };
 };
+/** Nearest ancestor holding a package.json — the project boundary when there is no git. */
+const packageRoot = (cwd) => {
+    let dir = cwd;
+    // Same bound as the git walk: deep monorepos are well inside 20, and an unbounded loop on a
+    // pathological path would hang the CLI's startup.
+    for (let depth = 0; depth < 20; depth += 1) {
+        if (existsSync(join(dir, 'package.json')))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+    return null;
+};
 /** Print the opt-out notice exactly once per machine (honest disclosure, the OSS-trust bar). */
 const showNoticeOnce = () => {
     try {
@@ -294,13 +317,14 @@ export const createTelemetry = (opts) => {
             ...(extra?.init !== undefined ? { init: extra.init } : {}),
             ...(extra?.bug !== undefined ? { bug: extra.bug } : {}),
             ...(extra?.outage !== undefined ? { outage: extra.outage } : {}),
+            ...(extra?.instrumentation !== undefined ? { instrumentation: extra.instrumentation } : {}),
         };
         // Map the core contract onto PostHog's capture shape: id/name/time move up, the rest are properties.
         // The feedback body is FLATTENED into `feedback_*` properties rather than sent as a nested object:
         // PostHog filters and breakdowns operate on top-level properties, so a nested `feedback.stack`
         // would be invisible to the exact "which stacks report the most bugs" question this exists to
         // answer. One prefix keeps them grouped in the UI without a nested path.
-        const { anonymousId: distinctId, event: name, ts, sessionId: eventSessionId, feedback, session, project, verification, versionChange, crash, identity, connection, init, bug, outage, ...rest } = event;
+        const { anonymousId: distinctId, event: name, ts, sessionId: eventSessionId, feedback, session, project, verification, versionChange, crash, identity, connection, init, bug, outage, instrumentation, ...rest } = event;
         // `$session_id` is PostHog's OWN session property, so sending ours under that name lights up
         // its built-in session views and funnels for free rather than requiring custom HogQL everywhere.
         // `sessionId` rides only on events that happened inside a daemon run. A one-shot CLI command
@@ -329,6 +353,7 @@ export const createTelemetry = (opts) => {
             init,
             bug,
             outage,
+            instrumentation,
         };
         for (const [prefix, block] of Object.entries(blocks)) {
             for (const [key, value] of Object.entries(block ?? {})) {

package/dist/telemetry/verification-of.js

@@ -12,7 +12,7 @@
  * Extracted because a rule this easy to get wrong, feeding the one number shown to investors, should
  * be readable and testable on its own rather than inferred from a ternary inside a dispatcher.
  */
-import { VerifiedReason } from '@reticlehq/core';
+import { CaptureLoss, VerifiedReason } from '@reticlehq/core';
 import { VERIFICATION_TOOLS } from '../tools/feedback-tools.js';
 import { getBrowserMode } from './browser-mode.js';
 /**
@@ -27,6 +27,27 @@ function reasonOf(result) {
     const raw = result['verifiedReason'];
     return 'string' === typeof raw && REASONS.has(raw) ? raw : undefined;
 }
+/**
+ * WHICH loss made the capture unclean, read off the honesty block the verdict already carries.
+ *
+ * Narrowed against core's own list for the same reason `reasonOf` is: a value that is not a member
+ * is not an answer. Reported as `OTHER` rather than dropped when the block says the capture was
+ * dirty and names no kind — the loss is real either way, and a silent absence there would read as
+ * "no unclean verdicts happened", which is the opposite of the truth.
+ */
+const LOSSES = new Set(Object.values(CaptureLoss));
+function uncleanLossOf(result, reason) {
+    if (VerifiedReason.UNCLEAN_CAPTURE !== reason)
+        return undefined;
+    const honesty = result['honesty'];
+    const integrity = null !== honesty && 'object' === typeof honesty
+        ? honesty.integrity
+        : undefined;
+    const first = Array.isArray(integrity?.losses) ? integrity.losses[0] : undefined;
+    return 'string' === typeof first && LOSSES.has(first)
+        ? first
+        : CaptureLoss.OTHER;
+}
 /** Suite statuses. `unverifiable` is a suite that ran but proved nothing — including an empty one. */
 const SuiteStatus = {
     PASS: 'pass',
@@ -62,6 +83,7 @@ export function verificationOf(toolName, result, durationMs, brand) {
     if (verified === undefined && passed === undefined)
         return undefined;
     const reason = reasonOf(result);
+    const uncleanLoss = uncleanLossOf(result, reason);
     return {
         via: toolName,
         verified: verified ?? (true === passed ? 'yes' : 'no'),
@@ -80,5 +102,8 @@ export function verificationOf(toolName, result, durationMs, brand) {
         // belonging to three different owners — the agent, the app, and Reticle's own blind spots — and
         // they need opposite responses. A suite verdict has no clause behind it and reports none.
         ...(reason === undefined ? {} : { reason }),
+        // WHAT was lost, when the reason was that something was. Three owners, three fixes, one bar
+        // until now.
+        ...(uncleanLoss === undefined ? {} : { uncleanLoss }),
     };
 }