@reticlehq/server 2.6.0 → 2.7.0

package/dist/session/review-store.js

@@ -11,14 +11,31 @@ import { MarkStatus } from '@reticlehq/core';
  */
 /** Prefix on review-mark ids (m1, m2, …) — distinguishes them from command ids. */
 const MARK_ID_PREFIX = 'm';
+/**
+ * Shared by every store in the process, so an id is never reissued.
+ *
+ * The sequence used to live on the instance, which looked right and was not: a store is created per
+ * Session, and a Session is recreated on every page reload and socket reattach. Each new store began
+ * again at `m1`, so an id an agent was still holding silently came to denote a DIFFERENT mark — and
+ * `resolve` retired that one instead, reporting success. Reported from the field by an agent that
+ * closed a bug nobody had fixed while the two it had fixed vanished unrecorded.
+ *
+ * Process-wide is deliberately not "forever": a daemon restart resets it, but a restart also
+ * destroys every session, so any id from before it resolves to nothing and `resolve` correctly
+ * returns false. The identity echo below covers what remains.
+ */
+let nextMarkId = 0;
+/** Tests only — assertions on `m1` must not depend on which test ran first. */
+export function resetMarkIdsForTest() {
+    nextMarkId = 0;
+}
 export class ReviewStore {
     #marks = [];
-    #seq = 0;
     /** Store a new mark (status pending) stamped with the caller-supplied session-relative time. */
     add(data, at) {
-        this.#seq += 1;
+        nextMarkId += 1;
         const mark = {
-            id: `${MARK_ID_PREFIX}${String(this.#seq)}`,
+            id: `${MARK_ID_PREFIX}${String(nextMarkId)}`,
             note: data.note,
             anchor: data.anchor,
             strategy: data.strategy,
@@ -51,10 +68,22 @@ export class ReviewStore {
      * false for an unknown id or an already-resolved mark (so resolve is idempotent).
      */
     resolve(id) {
+        return this.resolveDetail(id).resolved;
+    }
+    /**
+     * Resolve, and say WHICH mark was retired.
+     *
+     * The bare boolean is what made the misattribution silent: `{"resolved":true}` is equally
+     * consistent with "I retired the bug you fixed" and "I retired somebody else's". Echoing the note
+     * lets a caller check the answer against what it believed it was resolving, which is exactly what
+     * the agent that hit this asked for — it had been re-reading the whole list after every resolve
+     * and hand-diffing the notes to get the same assurance.
+     */
+    resolveDetail(id) {
         const mark = this.#marks.find((m) => m.id === id);
         if (mark === undefined || mark.status === MarkStatus.RESOLVED)
-            return false;
+            return { resolved: false, id };
         mark.status = MarkStatus.RESOLVED;
-        return true;
+        return { resolved: true, id, note: mark.note };
     }
 }

package/dist/session/session-manager.d.ts

@@ -26,6 +26,15 @@ export declare class SessionManager {
     count(): number;
     /** Wire the diagnosis provider (daemon boot). Absent ⇒ the plain, static message. */
     setNoSessionHint(hint: (() => string | undefined) | undefined): void;
+    /**
+     * The same diagnosis, for a caller that is ASKING about sessions rather than failing to get one.
+     *
+     * `reticle_sessions` is the first thing an agent reaches for and it returned a bare empty array —
+     * confidently, with nothing to act on. An agent cannot tell an empty list apart from a daemon that
+     * is down, an app with no SDK, or a tab that was closed, so it stops there. The diagnosis was
+     * already computed for the error path; this exposes it to the read path too.
+     */
+    noSessionHint(): string | undefined;
     everConnected(): boolean;
     /** Record a bridge-initiated close so `resolve` can explain a session that vanished. */
     noteClosure(reason: string, at: number): void;

package/dist/session/session-manager.js

@@ -161,6 +161,17 @@ export class SessionManager {
     setNoSessionHint(hint) {
         this.#noSessionHint = hint;
     }
+    /**
+     * The same diagnosis, for a caller that is ASKING about sessions rather than failing to get one.
+     *
+     * `reticle_sessions` is the first thing an agent reaches for and it returned a bare empty array —
+     * confidently, with nothing to act on. An agent cannot tell an empty list apart from a daemon that
+     * is down, an app with no SDK, or a tab that was closed, so it stops there. The diagnosis was
+     * already computed for the error path; this exposes it to the read path too.
+     */
+    noSessionHint() {
+        return this.#noSessionHint?.();
+    }
     /** Whether any session has connected since this daemon booted — half the diagnosis. */
     #everConnected = false;
     everConnected() {

package/dist/session/session.d.ts

@@ -135,6 +135,12 @@ export declare class Session {
         total: number;
         dropped: number;
     };
+    /**
+     * Did the buffer lose scarce evidence from a window opened at `cursor`? The input to whether a
+     * verdict's capture was clean — see `RingBuffer.lostSince`, and never the raw drop counter, which
+     * moves for the age and churn evictions that every live page produces continuously.
+     */
+    lostSince(cursor: number): boolean;
     onEvent(listener: (event: ReticleEvent) => void): () => void;
     onDisconnect(listener: () => void): () => void;
     /** Send a command to the browser and await its reply (or time out). */
@@ -159,6 +165,8 @@ export declare class Session {
     drainInbox(): InboxMessage[];
     /** Diagnostic read of the inbox depth (does not clear). */
     inboxSize(): number;
+    /** Everything the human has said this session, delivered or not. Never clears. */
+    inboxHistory(): readonly InboxMessage[];
     /** Human marks still awaiting a fix (oldest first). Reading does not consume — resolveMark does. */
     pendingMarks(): ReviewMark[];
     /** Full mark history (pending + resolved), oldest first. */

package/dist/session/session.js

@@ -370,6 +370,14 @@ export class Session {
     bufferHealth() {
         return this.#buffer.bufferHealth();
     }
+    /**
+     * Did the buffer lose scarce evidence from a window opened at `cursor`? The input to whether a
+     * verdict's capture was clean — see `RingBuffer.lostSince`, and never the raw drop counter, which
+     * moves for the age and churn evictions that every live page produces continuously.
+     */
+    lostSince(cursor) {
+        return this.#buffer.lostSince(cursor);
+    }
     onEvent(listener) {
         this.#listeners.add(listener);
         return () => this.#listeners.delete(listener);
@@ -470,6 +478,10 @@ export class Session {
     inboxSize() {
         return this.#live.size();
     }
+    /** Everything the human has said this session, delivered or not. Never clears. */
+    inboxHistory() {
+        return this.#live.history();
+    }
     // ── Human review marks: the "annotate the bug where you see it" inbox (server-owned) ──────────
     /** Human marks still awaiting a fix (oldest first). Reading does not consume — resolveMark does. */
     pendingMarks() {

package/dist/status-payload.d.ts

@@ -14,6 +14,18 @@ interface StatusPayload {
     contract: string;
     sessionCount: number;
     sessions: SessionInfo[];
+    /**
+     * Why nothing is connected — present ONLY when `sessionCount` is 0.
+     *
+     * `reticle status` is the most-run command in the field, and with no sessions it answered
+     * `sessionCount: 0` and stopped. That is the same dead end `reticle_sessions` used to be for
+     * agents, at the same point in the funnel — the daemon is up, the agent is attached, and the app
+     * never arrived — and it is where most installs stop. Agents got the diagnosis in 2.7.0; a human
+     * running the command we tell them to run in `init`'s closing line deserves the same sentence.
+     */
+    why?: string;
 }
-export declare function statusPayload(sessionCount: number, sessions: SessionInfo[]): StatusPayload;
+export declare function statusPayload(sessionCount: number, sessions: SessionInfo[], 
+/** The no-session diagnosis, injected so this stays pure and the port probe stays off this path. */
+why?: string): StatusPayload;
 export {};

package/dist/status-payload.js

@@ -1,11 +1,16 @@
 import { CONTRACT_FINGERPRINT } from '@reticlehq/core';
 import { SERVER_VERSION } from './version/server-version.js';
-export function statusPayload(sessionCount, sessions) {
+export function statusPayload(sessionCount, sessions, 
+/** The no-session diagnosis, injected so this stays pure and the port probe stays off this path. */
+why) {
     return {
         running: true,
         version: SERVER_VERSION,
         contract: CONTRACT_FINGERPRINT,
         sessionCount,
         sessions,
+        // Only when there is nothing to explain away: a diagnosis printed beside a live session would
+        // contradict it.
+        ...(0 === sessionCount && why !== undefined ? { why } : {}),
     };
 }

package/dist/telemetry/app-instrumented.d.ts

@@ -0,0 +1,37 @@
+/**
+ * When an app carrying the SDK first reaches this daemon.
+ *
+ * This is the step the whole funnel turns on, and the one nothing could measure. Registering the MCP
+ * server and instrumenting an app are separate acts, done by different commands, and the data says
+ * almost everybody does the first and almost nobody does the second — but proving that required
+ * inferring it from a window counter that resets on every flush, and which therefore reported fewer
+ * instrumented users than there were users calling tools.
+ *
+ * Once per daemon run, on the FIRST app connect only. A page that reloads, or an app that opens five
+ * tabs, must not read as five instrumented installs — the question is "did this install ever get an
+ * app wired", and it has one answer per run.
+ *
+ * Names, never values: whether `init` had been run and whether an agent was attached — never the
+ * project path, the URL, or anything from the page. The stack is deliberately NOT repeated here;
+ * `project_profiled` already carries it on the same daemon run, so the two join on sessionId.
+ */
+export declare function markInstrumentationClock(now: number): void;
+export interface InstrumentationFacts {
+    /** Whether this project has a projectId stamped — i.e. `init` has run here. */
+    initialized: boolean;
+    /**
+     * Whether an MCP client was attached when the app arrived.
+     *
+     * Both halves present is the only state in which Reticle can do anything, and it is worth being
+     * able to see the two orders apart: an app that connects with no agent attached is a person
+     * setting up, while an agent that has been waiting is a session about to do work.
+     */
+    agentAttached: boolean;
+}
+/**
+ * Report the first instrumented app of this daemon run. Best-effort and idempotent — a metric must
+ * never be the reason a session fails to register.
+ */
+export declare function reportAppInstrumented(facts: InstrumentationFacts, now?: () => number): void;
+/** Tests only. */
+export declare function resetAppInstrumented(): void;

package/dist/telemetry/app-instrumented.js

@@ -0,0 +1,54 @@
+/**
+ * When an app carrying the SDK first reaches this daemon.
+ *
+ * This is the step the whole funnel turns on, and the one nothing could measure. Registering the MCP
+ * server and instrumenting an app are separate acts, done by different commands, and the data says
+ * almost everybody does the first and almost nobody does the second — but proving that required
+ * inferring it from a window counter that resets on every flush, and which therefore reported fewer
+ * instrumented users than there were users calling tools.
+ *
+ * Once per daemon run, on the FIRST app connect only. A page that reloads, or an app that opens five
+ * tabs, must not read as five instrumented installs — the question is "did this install ever get an
+ * app wired", and it has one answer per run.
+ *
+ * Names, never values: whether `init` had been run and whether an agent was attached — never the
+ * project path, the URL, or anything from the page. The stack is deliberately NOT repeated here;
+ * `project_profiled` already carries it on the same daemon run, so the two join on sessionId.
+ */
+import { TelemetryEventKind } from '@reticlehq/core';
+import { getTelemetry } from './telemetry.js';
+let reported = false;
+/** Set at daemon start so the first connect can report how long the install sat un-instrumented. */
+let daemonStartedAt;
+export function markInstrumentationClock(now) {
+    daemonStartedAt = now;
+    reported = false;
+}
+/**
+ * Report the first instrumented app of this daemon run. Best-effort and idempotent — a metric must
+ * never be the reason a session fails to register.
+ */
+export function reportAppInstrumented(facts, now = () => Date.now()) {
+    if (reported)
+        return;
+    reported = true;
+    try {
+        void getTelemetry().emit(TelemetryEventKind.APP_INSTRUMENTED, {
+            instrumentation: {
+                initialized: facts.initialized,
+                agentAttached: facts.agentAttached,
+                // How long the daemon ran before an app showed up. Large values are the interesting ones:
+                // Reticle was up, the agent had the tools, and nothing was wired for that whole time.
+                msToFirstApp: daemonStartedAt === undefined ? 0 : Math.max(0, now() - daemonStartedAt),
+            },
+        });
+    }
+    catch {
+        /* never let a metric interfere with a page connecting */
+    }
+}
+/** Tests only. */
+export function resetAppInstrumented() {
+    reported = false;
+    daemonStartedAt = undefined;
+}

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

@@ -24,10 +24,10 @@ export declare const SESSION_FLUSH_MS: number;
  * 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.
  *
- * Measured 2026-08-10/11 (non-CI): **614 `daemon_started` against 499 `daemon_stopped` — 19% of
- * sessions never reported a summary at all.** Every "did anyone use Reticle" number is computed on
- * the 81% that did, and undercounts by an unknown amount, which is the one thing a funnel metric
- * must not do.
+ * 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

package/dist/telemetry/daemon-telemetry.js

@@ -12,6 +12,7 @@ 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;
 /**
@@ -31,10 +32,10 @@ export const SESSION_FLUSH_MS = 5 * 60 * 1000;
  * 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.
  *
- * Measured 2026-08-10/11 (non-CI): **614 `daemon_started` against 499 `daemon_stopped` — 19% of
- * sessions never reported a summary at all.** Every "did anyone use Reticle" number is computed on
- * the 81% that did, and undercounts by an unknown amount, which is the one thing a funnel metric
- * must not do.
+ * 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
@@ -53,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.

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

@@ -73,10 +73,10 @@ export declare class SessionMetrics {
     /**
      * Ask the agent for a verdict, once, when it has driven the page without asking for one.
      *
-     * Measured 2026-08-10/11: of 170 sessions that made a tool call, 140 produced no verdict — and
-     * **137 of those never called a verdict-producing tool even once.** They drove the app 269 times
+     * 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`, non-zero in 58 sessions); it was reported to US and never to the agent.
+     * (`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

package/dist/telemetry/session-metrics.js

@@ -70,7 +70,7 @@ export class SessionMetrics {
      * 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.
      *
-     * Measured 2026-08-10/11: **496 of 499 `daemon_stopped` rows had `toolCalls: 0`**, at a median
+     * 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
@@ -332,10 +332,10 @@ export class SessionMetrics {
     /**
      * Ask the agent for a verdict, once, when it has driven the page without asking for one.
      *
-     * Measured 2026-08-10/11: of 170 sessions that made a tool call, 140 produced no verdict — and
-     * **137 of those never called a verdict-producing tool even once.** They drove the app 269 times
+     * 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`, non-zero in 58 sessions); it was reported to US and never to the agent.
+     * (`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

package/dist/telemetry/telemetry.d.ts

@@ -1,4 +1,4 @@
-import { TelemetryEventKind, ProjectIdSource, 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.
  *
@@ -74,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

@@ -317,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
@@ -352,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 }),
     };
 }

package/dist/tools/act-tools.js

@@ -6,7 +6,7 @@
 import { z } from 'zod';
 import { aliasParam } from './alias-args.js';
 import { captureAct, compileSequenceStep } from '../flows/replay.js';
-import { ActionType, ActionWarning, DEFAULT_ASSERT_TIMEOUT_MS, InputMode, ReticleCommand, Verified, PredicateKind, } from '@reticlehq/core';
+import { ActionType, ActionWarning, CaptureLoss, DEFAULT_ASSERT_TIMEOUT_MS, InputMode, ReticleCommand, Verified, PredicateKind, } from '@reticlehq/core';
 import { assertNativeInputSupported } from './act-danger.js';
 import { leanActResult, mutatedWithin } from './act-view.js';
 import { ReticleTool } from './tool-names.js';
@@ -55,7 +55,7 @@ export const ACT_TOOLS = [
     {
         name: ReticleTool.ACT,
         example: { ref: 'e42', action: 'fill', args: { value: 'hello' } },
-        description: 'Act WITHOUT checking the result — if the action is supposed to cause something, use reticle_act_and_wait { until } instead and get the verdict in the same call. This tool returns immediately with a `since` cursor; observe the reaction yourself with reticle_observe. Use it for actions with no observable consequence to assert (focus, hover, scrollIntoView, a fill you are about to submit). One action against a ref: click|dblclick|hover|focus|fill|type|clear|select|check|uncheck|submit|press|scrollIntoView. Carries effect:{dispatched,targetMatched,visible,enabled,focusMoved,valueChanged,domMutatedWithin,occluded,occludedBy,scrolledIntoView} to tell "action missed" from "app didn\'t react"; dispatched=landed, settled=a real frame flushed, and a settle timeout never fails the tool. Fields at their uninformative default are OMITTED so a clean action collapses to its consequence: an absent dispatched/targetMatched/visible/enabled means true, an absent occluded/scrolledIntoView/valueChanged/defaultPrevented means false, an absent focusMoved/occludedBy means null. occluded=true means the click point is covered by another element (a real user could not click it) — synthetic dispatch still delivered the event; scrolledIntoView=true means an off-viewport target was scrolled in first. inputMode is "real" (native CDP, no synthetic effect block) or "synthetic"; clicks default to the occlusion-honest synthetic path even when CDP is configured — pass args.native:true to force a trusted native click (file pickers, clipboard). args.holdMs keeps the pointer DOWN for that long between mousedown and mouseup — the only way to drive a hold-to-confirm control (hold-to-delete, hold-to-record, long-press); effect.heldMs reports the hold actually achieved, which a throttled background tab can stretch. args.confirmDangerous is a permission gate and NOT a duration: it allows a destructive control, it does not hold one. inputModeReason explains any real→synthetic choice so it is never silent. Full model (real-input, throttled tabs, `reticle drive`): docs/usage.md §18.',
+        description: 'Act WITHOUT checking the result — if the action is supposed to cause something, use reticle_act_and_wait { until } instead and get the verdict in the same call. This tool returns immediately with a `since` cursor; observe the reaction yourself with reticle_observe. Use it for actions with no observable consequence to assert (focus, hover, scrollIntoView, a fill you are about to submit). One action against a ref: click|dblclick|hover|focus|fill|type|clear|select|check|uncheck|submit|press|scrollIntoView. Carries effect:{dispatched,targetMatched,visible,enabled,focusMoved,valueChanged,domMutatedWithin,occluded,occludedBy,scrolledIntoView} to tell "action missed" from "app didn\'t react"; dispatched=landed, settled=a real frame flushed, and a settle timeout never fails the tool. Fields at their uninformative default are OMITTED so a clean action collapses to its consequence: an absent dispatched/targetMatched/visible/enabled means true, an absent occluded/scrolledIntoView/valueChanged/defaultPrevented means false, an absent focusMoved/occludedBy means null. occluded=true means the click point is covered by another element (a real user could not click it) — synthetic dispatch still delivered the event; scrolledIntoView=true means an off-viewport target was scrolled in first. inputMode is "real" (native CDP, no synthetic effect block) or "synthetic"; clicks default to the occlusion-honest synthetic path even when CDP is configured — pass args.native:true to force a trusted native click (file pickers, clipboard). args.holdMs keeps the pointer DOWN for that long between mousedown and mouseup — the only way to drive a hold-to-confirm control (hold-to-delete, hold-to-record, long-press); effect.heldMs reports the hold actually achieved, which a throttled background tab can stretch. args.confirmDangerous is a permission gate and NOT a duration: it allows a destructive control, it does not hold one. inputModeReason explains any real→synthetic choice so it is never silent. Full model (real-input, throttled tabs, `reticle drive`): node_modules/@reticlehq/server/docs/usage.md §18.',
         inputSchema: {
             ref: z
                 .string()
@@ -64,7 +64,7 @@ export const ACT_TOOLS = [
             args: z
                 .record(z.unknown())
                 .optional()
-                .describe('Action-specific arguments: { value } for fill/select, { text } for type/press, { native: true } to force a trusted native click, { holdMs: N } to keep the pointer DOWN for N ms (hold-to-confirm controls; effect.heldMs reports what was achieved), { confirmDangerous: true } to allow a potentially destructive control — a permission gate, NOT a duration.'),
+                .describe('Action-specific arguments: { value } for fill/select, { text } for type/press (the key NAME, e.g. Escape or Tab), { toRef } for drag (the ref to drop ON — without it the drag lands nowhere), { native: true } to force a trusted native click, { holdMs: N } to keep the pointer DOWN for N ms (hold-to-confirm controls; effect.heldMs reports what was achieved), { confirmDangerous: true } to allow a potentially destructive control — a permission gate, NOT a duration.'),
             refuseWhenThrottled: z
                 .boolean()
                 .optional()
@@ -255,7 +255,7 @@ export const ACT_TOOLS = [
             args: z
                 .record(z.unknown())
                 .optional()
-                .describe('Action-specific arguments: { value } for fill/select, { text } for type/press, { confirmDangerous: true } for a potentially destructive control.'),
+                .describe('Action-specific arguments: { value } for fill/select, { text } for type/press (the key NAME, e.g. Escape or Tab), { toRef } for drag (the ref to drop ON — without it the drag lands nowhere), { confirmDangerous: true } for a potentially destructive control.'),
             predicate: PredicateSchema.optional().describe('Alias for `until` (the name reticle_assert / reticle_wait_for use).'),
             until: PredicateSchema.optional().describe('Predicate to wait for after the action completes (same shape as reticle_assert). OMIT to wait for the page to SETTLE — network + DOM idle — the deterministic default instead of a sleep. To assert a consequence AND settle, allOf them: { kind: "allOf", predicates: [<your predicate>, { kind: "settled" }] }.'),
             timeout_ms: z
@@ -355,11 +355,6 @@ export const ACT_TOOLS = [
             // argument and ignoring it told the agent its trusted click had happened. See act-danger.
             assertNativeInputSupported(asRecord(args['args']));
             const since = session.elapsed();
-            // `dropped` is cumulative for the SESSION, so comparing against a pre-action reading is what
-            // asks "did the buffer lose anything while THIS action was observed?" — the question the
-            // honesty block means. Reading the raw total pinned every later verdict to `unknown` after a
-            // single early eviction (measured on the Next.js demo at dropped:51, windows intact).
-            const droppedBefore = session.bufferHealth().dropped;
             // The cursor + effect are marked after the act dispatches (below) — a refused act leaves none.
             // The attribution window stays open across the settle wait below, so post-dispatch async events
             // (the whole point of act_and_wait) attribute to this action. finishAction fires after the wait.
@@ -427,12 +422,28 @@ export const ACT_TOOLS = [
                 // whose own words were "over a clean capture".
                 const gapNote = transportGapNote(windowEvents);
                 const impeachingNotes = [impeaching.note, gapNote].filter((n) => n !== undefined);
+                const bufferLost = session.lostSince(since);
+                // Which loss, as an enum, beside the prose that describes it. Classified here because this is
+                // the only place that knows the three apart: our buffer, our transport, and the page's own
+                // boundaries. See `CaptureLoss`.
+                const losses = [
+                    ...(bufferLost ? [CaptureLoss.BUFFER_LOSS] : []),
+                    ...(gapNote === undefined ? [] : [CaptureLoss.TRANSPORT_GAP]),
+                    ...(impeaching.note === undefined ? [] : [CaptureLoss.BLIND_SPOT]),
+                ];
                 const honesty = buildHonestyBlock({
                     grade: gradeOf(gradedLinks),
                     attribution: 'window',
-                    truncated: session.bufferHealth().dropped > droppedBefore,
+                    // Did the buffer lose scarce evidence FROM THIS WINDOW — not "did it evict anything while
+                    // the action ran", which was the previous rule and which is true on essentially every live
+                    // page. Age eviction retires everything past 60s on every push, and the churn floor is
+                    // sacrificed on purpose; neither costs this verdict a single event it needed. In the
+                    // field this made `unclean_capture` the dominant cause of `unknown`, reported for
+                    // evictions that happened outside the window they impeached.
+                    truncated: bufferLost,
                     coveragePartial: Coverage.PARTIAL === coverage.coverage,
                     ...(0 === impeachingNotes.length ? {} : { blindSpots: impeachingNotes }),
+                    losses,
                 });
                 const capsuleSaved = await saveFailedAssertCapsule({
                     deps,
@@ -446,8 +457,19 @@ export const ACT_TOOLS = [
                 // Pass the action: an EMPTY window then reads as "the target does not react" rather than as a
                 // clean run — `settled` is satisfied by a page that did nothing, i.e. by a click that missed.
                 const acted = asString(args['action']);
+                // `prior` matters here for the same reason it matters on the assert path: a SCALE error
+                // disagrees with a value the API stated EARLIER in the session, which an action-scoped
+                // window can never contain. Without it `unit-mismatch` — the money false green, where a
+                // total renders 100x off — is structurally unreachable from `act_and_wait`, which is the
+                // tool the product tells agents to reach for first. Our best detector could not fire on our
+                // flagship path, and nothing said so: the finding was simply never produced.
+                //
+                // Learning material only. Attribution is unchanged — findings still come exclusively from
+                // `windowEvents`, exactly as on the assert path.
+                const prior = since > 0 ? (await session.queryEvents({ since: 0 })).filter((e) => e.t < since) : [];
                 const contradictions = findContradictions(windowEvents, {
                     action: acted,
+                    prior,
                     ...session.lastAct.effect(),
                 });
                 // The single field an agent reads. Everything below it is the evidence it was derived from;

package/dist/tools/assert-verdict.js

@@ -1,3 +1,4 @@
+import { CaptureLoss } from '@reticlehq/core';
 import { findContradictions } from '../events/contradictions.js';
 import { blindSpotsFromState, buildCoverageStatement, Coverage, impeachesCapture, transportGapNote, } from '../honesty/blind-spots.js';
 import { buildHonestyBlock } from '../honesty/honesty.js';
@@ -68,6 +69,12 @@ observationLost) {
             attribution: 'window',
             coveragePartial: Coverage.PARTIAL === statement.coverage,
             ...(0 === impeachingNotes.length ? {} : { blindSpots: impeachingNotes }),
+            // Which loss, as an enum, beside the prose. `assert` observes an already-open window and never
+            // consults the ring buffer's health, so `buffer_loss` is not one of its answers.
+            losses: [
+                ...(gap === undefined ? [] : [CaptureLoss.TRANSPORT_GAP]),
+                ...(impeaching.note === undefined ? [] : [CaptureLoss.BLIND_SPOT]),
+            ],
         }),
         contradictions,
         ...(outcomePending ? { outcomePending } : {}),

package/dist/tools/error-recovery.js

@@ -10,6 +10,7 @@
  */
 import { TRANSPORT_LIMITS } from '@reticlehq/core';
 import { SELF_RECOVERING_MARKER } from '../session/no-session-diagnosis.js';
+import { chromiumInstallCommand, bundledPlaywrightVersion } from '../cli/chromium-hint.js';
 /** Marks where an over-long message had its middle removed. Named so tests assert it by value. */
 const ELISION = '… [elided] …';
 /**
@@ -129,7 +130,11 @@ export const RECOVERY = {
         'where it actually is. This is app/flow drift, which is exactly what the flow exists to catch.',
     NO_POOL: 'Reticle cannot launch its own browser here: the daemon-managed pool is absent, or Playwright ' +
         'has no Chromium installed (the message above says which). Run Reticle via `reticle mcp`, and ' +
-        'ask the human for `npx playwright install chromium` if that is what is missing. Meanwhile drive ' +
+        // Pinned to the bundled playwright: the unpinned command installs a revision this daemon never
+        // looks at, so the human runs it, it succeeds, and nothing changes.
+        'ask the human for `' +
+        chromiumInstallCommand(bundledPlaywrightVersion()) +
+        '` if that is what is missing. Meanwhile drive ' +
         'a tab the human already has open — reticle_sessions lists them.',
 };
 /** Ordered match rules; the first hit wins. Substrings track the thrown messages they recover. */