@reticlehq/server 2.6.0 → 2.7.0

package/dist/tools/invoke-tool.js

@@ -8,6 +8,7 @@ import { noteToolCall } from '../daemon/daemon-usefulness.js';
 import { bugsInResult } from '../telemetry/bug-found.js';
 import { verificationOf } from '../telemetry/verification-of.js';
 import { asString } from './tools-helpers.js';
+import { EnvelopeKey } from './tool-kit.js';
 import { ReticleTool } from './tool-names.js';
 import { takeFeedbackPrompt } from './feedback-tools.js';
 import { takeFeedbackUndelivered } from '../telemetry/feedback-delivery.js';
@@ -262,12 +263,12 @@ export async function runTool(tool, deps, args) {
         ? raw
         : {
             ...raw,
-            ...(prompt !== undefined ? { feedback_prompt: prompt } : {}),
-            ...(update !== undefined ? { update_available: update } : {}),
-            ...(skew !== undefined ? { version_skew: skew } : {}),
+            ...(prompt !== undefined ? { [EnvelopeKey.FEEDBACK_PROMPT]: prompt } : {}),
+            ...(update !== undefined ? { [EnvelopeKey.UPDATE_AVAILABLE]: update } : {}),
+            ...(skew !== undefined ? { [EnvelopeKey.VERSION_SKEW]: skew } : {}),
             ...(undelivered !== undefined
                 ? {
-                    feedback_undelivered: `your earlier report did NOT send: ${undelivered}. Tell the human what you found so it is not lost.`,
+                    [EnvelopeKey.FEEDBACK_UNDELIVERED]: `your earlier report did NOT send: ${undelivered}. Tell the human what you found so it is not lost.`,
                 }
                 : {}),
         };
@@ -286,17 +287,17 @@ export async function runTool(tool, deps, args) {
     // one-time pool-lease reminder or the age cleanup nudge. Splice them regardless.
     const lease = resolved.takeSessionLease();
     if (lease !== undefined)
-        envelope['session_lease'] = lease;
+        envelope[EnvelopeKey.SESSION_LEASE] = lease;
     const warning = resolved.ageWarning();
     if (warning !== undefined)
-        envelope['session_age_warning'] = warning;
-    // Ask for a verdict when the agent has driven the page and not asked for one. 137 of the 140
-    // verdict-less sessions measured over 2026-08-10/11 never called a verdict-producing tool ONCE;
+        envelope[EnvelopeKey.SESSION_AGE_WARNING] = warning;
+    // Ask for a verdict when the agent has driven the page and not asked for one. Almost every
+    // verdict-less session in the field never called a verdict-producing tool ONCE;
     // the counter behind this already existed and was reported only to us. One-shot per abandoned
     // run, same discipline as the pool lease — a hint on every call is noise that gets tuned out.
     const unverified = getSessionMetrics().takeUnverifiedNudge();
     if (unverified !== undefined)
-        envelope['verify_next'] = unverified;
+        envelope[EnvelopeKey.VERIFY_NEXT] = unverified;
     // Invite feedback at the moment of friction, worded for what just happened. Feedback produced
     // ~11 of this release's fixes from 14 reports; the handshake instruction is what got those 14,
     // and this closes the gap it leaves — the agent mid-problem, not thinking about feedback tooling.
@@ -311,7 +312,7 @@ export async function runTool(tool, deps, args) {
         producedVerdict: 'verified' in result,
     });
     if (friction !== undefined) {
-        envelope['feedback_invite'] = inviteFor(friction);
+        envelope[EnvelopeKey.FEEDBACK_INVITE] = inviteFor(friction);
         getSessionMetrics().recordFeedbackPrompt();
     }
     return Object.keys(envelope).length > 0 ? { ...result, ...envelope } : result;

package/dist/tools/tool-kit.d.ts

@@ -84,11 +84,58 @@ export declare const sessionIdShape: {
     sessionId: z.ZodOptional<z.ZodString>;
 };
 /**
- * Fields that `runTool` / `withControl` splice onto EVERY session-bound tool result at runtime
- * (health, pool lease reminder, age cleanup nudge, and the delivered-once human-control envelope).
- * They are declared here and merged into each session-bound tool's outputSchema so a schema-strict
- * client (structuredContent validation) keeps them instead of silently dropping them — the `control`
- * envelope is the human-in-the-loop guidance channel, so losing it is a safety failure, not cosmetic.
+ * Every key `runTool` splices onto a session-bound result, as a closed list.
+ *
+ * These are wire strings and were inlined at the splice sites, which is exactly how four of them
+ * came to be spliced and never declared. `sessionEnvelopeShape` is derived from this object and
+ * `envelope-keys-declared.test.ts` fails if a member is missing from it, so the two cannot drift.
+ *
+ * Each of these is a channel that exists BECAUSE the agent had no other way to learn the fact.
+ * Undeclared, a schema-strict client validating `structuredContent` drops it, and the channel is
+ * indistinguishable from never having been built.
+ */
+export declare const EnvelopeKey: {
+    /** Session health — which tab, how fresh. */
+    readonly SESSION: "session";
+    /** One-shot pool-lease reminder. */
+    readonly SESSION_LEASE: "session_lease";
+    /** One-shot "these sessions are old, clean them up". */
+    readonly SESSION_AGE_WARNING: "session_age_warning";
+    /** The delivered-once human-in-the-loop guidance envelope. Losing it is a safety failure. */
+    readonly CONTROL: "control";
+    /**
+     * Rides alongside `session` whenever the tab is THROTTLED. It was declared on `reticle_act`'s
+     * schema and nowhere else, so on a validating profile every other session-bound tool silently
+     * dropped it — a throttled tab, where drives can no-op, returned a healthy-looking result.
+     */
+    readonly WARNING: "warning";
+    /** One-shot "ask the human how this went". */
+    readonly FEEDBACK_PROMPT: "feedback_prompt";
+    /** One-shot "a newer Reticle exists". */
+    readonly UPDATE_AVAILABLE: "update_available";
+    /**
+     * "You have driven this page N times without asking for a verdict."
+     *
+     * The largest known lever on the metric this product is judged by: verdict-less sessions
+     * overwhelmingly never call a verdict-producing tool at all. It was spliced undeclared, so on a
+     * validating client the nudge was built, fired, and thrown away before any agent saw it.
+     */
+    readonly VERIFY_NEXT: "verify_next";
+    /** The contextual "tell us what just went wrong" invitation. Same story, same release. */
+    readonly FEEDBACK_INVITE: "feedback_invite";
+    /** SDK/daemon version skew — often the one fact that explains everything else in the session. */
+    readonly VERSION_SKEW: "version_skew";
+    /** A feedback report that was accepted and then failed to send. Only the reporter can act on it. */
+    readonly FEEDBACK_UNDELIVERED: "feedback_undelivered";
+};
+export type EnvelopeKey = (typeof EnvelopeKey)[keyof typeof EnvelopeKey];
+/**
+ * Fields that `runTool` / `withControl` splice onto EVERY session-bound tool result at runtime.
+ * Merged into each session-bound tool's outputSchema so a schema-strict client (structuredContent
+ * validation) keeps them instead of silently dropping them.
+ *
+ * Derived from `EnvelopeKey` rather than re-listed: this shape and the splice sites disagreed for a
+ * whole release, and every key that went missing was a channel nobody could see was missing.
  */
 export declare const sessionEnvelopeShape: z.ZodRawShape;
 /** Unwrap a browser command result or throw its error so the agent sees a clean failure. */

package/dist/tools/tool-kit.js

@@ -14,32 +14,63 @@ export const sessionIdShape = {
         .describe('OMIT THIS unless you mean a specific tab — Reticle scopes to your project, prefers the active one, and refuses rather than guesses when ambiguous. Pass an id from reticle_sessions only to target a particular tab. The previous wording ("omit when only ONE session is open") was wrong and cost real turns: with three sessions connected — an app plus two pool leases — resolution is still unambiguous, but that sentence sent the agent off to list and filter sessions by hand before every single call.'),
 };
 /**
- * Fields that `runTool` / `withControl` splice onto EVERY session-bound tool result at runtime
- * (health, pool lease reminder, age cleanup nudge, and the delivered-once human-control envelope).
- * They are declared here and merged into each session-bound tool's outputSchema so a schema-strict
- * client (structuredContent validation) keeps them instead of silently dropping them — the `control`
- * envelope is the human-in-the-loop guidance channel, so losing it is a safety failure, not cosmetic.
+ * Every key `runTool` splices onto a session-bound result, as a closed list.
+ *
+ * These are wire strings and were inlined at the splice sites, which is exactly how four of them
+ * came to be spliced and never declared. `sessionEnvelopeShape` is derived from this object and
+ * `envelope-keys-declared.test.ts` fails if a member is missing from it, so the two cannot drift.
+ *
+ * Each of these is a channel that exists BECAUSE the agent had no other way to learn the fact.
+ * Undeclared, a schema-strict client validating `structuredContent` drops it, and the channel is
+ * indistinguishable from never having been built.
  */
-export const sessionEnvelopeShape = {
-    session: z.unknown().optional(),
-    session_lease: z.unknown().optional(),
-    session_age_warning: z.unknown().optional(),
-    control: z.unknown().optional(),
-    // `warning` rides alongside `session` whenever the tab is THROTTLED (healthEnvelope splices both).
-    // It was declared on reticle_act's schema but nowhere else, so on a validating profile every other
-    // session-bound tool (observe, assert, wait_for, act_sequence, act_and_wait, snapshot, query, …)
-    // silently dropped it — a throttled tab, where drives can no-op, returned a healthy-looking result.
-    // That is exactly what invoke-tool.ts's health splice exists to prevent, so it belongs in the shared
-    // envelope, not per-tool.
-    warning: z.string().optional(),
-    // The one-shot "ask the human how this went" envelope. Undeclared, a validating profile would strip
-    // it — and a feedback prompt that never reaches the agent is a feedback prompt that never reaches
-    // the person, which is the entire failure mode this channel exists to fix.
-    feedback_prompt: z.unknown().optional(),
-    // One-shot "a newer Reticle exists" notice. Undeclared, a validating profile would strip it and the
-    // agent would never learn an update was waiting.
-    update_available: z.unknown().optional(),
+export const EnvelopeKey = {
+    /** Session health — which tab, how fresh. */
+    SESSION: 'session',
+    /** One-shot pool-lease reminder. */
+    SESSION_LEASE: 'session_lease',
+    /** One-shot "these sessions are old, clean them up". */
+    SESSION_AGE_WARNING: 'session_age_warning',
+    /** The delivered-once human-in-the-loop guidance envelope. Losing it is a safety failure. */
+    CONTROL: 'control',
+    /**
+     * Rides alongside `session` whenever the tab is THROTTLED. It was declared on `reticle_act`'s
+     * schema and nowhere else, so on a validating profile every other session-bound tool silently
+     * dropped it — a throttled tab, where drives can no-op, returned a healthy-looking result.
+     */
+    WARNING: 'warning',
+    /** One-shot "ask the human how this went". */
+    FEEDBACK_PROMPT: 'feedback_prompt',
+    /** One-shot "a newer Reticle exists". */
+    UPDATE_AVAILABLE: 'update_available',
+    /**
+     * "You have driven this page N times without asking for a verdict."
+     *
+     * The largest known lever on the metric this product is judged by: verdict-less sessions
+     * overwhelmingly never call a verdict-producing tool at all. It was spliced undeclared, so on a
+     * validating client the nudge was built, fired, and thrown away before any agent saw it.
+     */
+    VERIFY_NEXT: 'verify_next',
+    /** The contextual "tell us what just went wrong" invitation. Same story, same release. */
+    FEEDBACK_INVITE: 'feedback_invite',
+    /** SDK/daemon version skew — often the one fact that explains everything else in the session. */
+    VERSION_SKEW: 'version_skew',
+    /** A feedback report that was accepted and then failed to send. Only the reporter can act on it. */
+    FEEDBACK_UNDELIVERED: 'feedback_undelivered',
 };
+/**
+ * Fields that `runTool` / `withControl` splice onto EVERY session-bound tool result at runtime.
+ * Merged into each session-bound tool's outputSchema so a schema-strict client (structuredContent
+ * validation) keeps them instead of silently dropping them.
+ *
+ * Derived from `EnvelopeKey` rather than re-listed: this shape and the splice sites disagreed for a
+ * whole release, and every key that went missing was a channel nobody could see was missing.
+ */
+export const sessionEnvelopeShape = Object.fromEntries(Object.values(EnvelopeKey).map((key) => [
+    key,
+    // `warning` is the one with a narrower type; the rest are opaque envelopes the client forwards.
+    EnvelopeKey.WARNING === key ? z.string().optional() : z.unknown().optional(),
+]));
 /** Unwrap a browser command result or throw its error so the agent sees a clean failure. */
 export async function commandOrThrow(deps, sessionId, 
 // ReticleCommand, not string: the union already exists and every caller passes a member. Typed as

package/dist/tools/tool-surface.js

@@ -100,16 +100,16 @@ export const CORE_TOOL_NAMES = new Set([
     ReticleTool.ACT_AND_WAIT,
     // ACT_SEQUENCE is here because its absence was measurably CAUSING the biggest loop in the data.
     //
-    // Measured 2026-08-10/11 (non-CI): `reticle_act` 319 calls, `reticle_act_sequence` **7**. `act`
-    // also leads the repeat table at 110 consecutive-repeat runs, and inside those sessions the
-    // repeated calls are 98 clicks and 21 fills — a login form driven one round trip at a time, which
-    // is exactly the antipattern SKILL.md warns about and exactly what this tool exists to collapse.
+    // In the field `reticle_act` is called overwhelmingly more often than `reticle_act_sequence`, and
+    // `act` leads the repeat table by a wide margin — inside those sessions the repeated calls are
+    // clicks and fills, a login form driven one round trip at a time, which is exactly the antipattern
+    // SKILL.md warns about and exactly what this tool exists to collapse.
     //
-    // The repeats are NOT retries: looping sessions have a lower error rate (0.051) than non-looping
-    // ones (0.078). The calls succeed and get repeated, because the batching tool was reachable only
-    // through `reticle_run` — so an agent had to already know it existed to use it, and 7-vs-319 says
-    // essentially nobody did. A tool an agent must already know about is a tool that never gets
-    // called; the same argument that put INSPECT and FEEDBACK here.
+    // The repeats are NOT retries: looping sessions have a LOWER error rate than non-looping ones. The
+    // calls succeed and get repeated, because the batching tool was reachable only through
+    // `reticle_run` — so an agent had to already know it existed to use it, and essentially nobody
+    // did. A tool an agent must already know about is a tool that never gets called; the same argument
+    // that put INSPECT and FEEDBACK here.
     ReticleTool.ACT_SEQUENCE,
     ReticleTool.OBSERVE,
     ReticleTool.NETWORK,

package/dist/tools/tools.js

@@ -78,6 +78,10 @@ const RAW_TOOLS = [
                 recommendation: z.string().optional(),
             }))
                 .describe('Connected browser sessions with health state. `projectId` groups sessions by app (stable across port changes); `leased` marks a pool-managed headless context vs a human tab.'),
+            why: z
+                .string()
+                .optional()
+                .describe('Present ONLY when `sessions` is empty: why nothing is connected, and the next action that fixes it. An empty list is never the end of the road — read this before concluding the app cannot be driven.'),
         },
         handler: async (deps) => {
             const provider = deps.realInput;
@@ -87,6 +91,14 @@ const RAW_TOOLS = [
                 realInputAvailable: provider !== undefined ? await provider.isAvailableFor(s.url) : false,
                 leased: leasedIds.has(s.sessionId),
             })));
+            // An empty list is the most common thing this tool ever returns, and on its own it is a dead
+            // end: the agent asked the one question it knows to ask, got a confident-looking answer with
+            // no next step, and stopped. The daemon already knows WHY nothing is connected — say it here
+            // rather than only when a later tool fails for want of a session.
+            if (0 === sessions.length) {
+                const why = deps.sessions.noSessionHint();
+                return { sessions, ...(why === undefined ? {} : { why }) };
+            }
             return { sessions };
         },
     },
@@ -193,6 +205,10 @@ const RAW_TOOLS = [
                 .string()
                 .optional()
                 .describe('CSS selector or element ref to restrict the search to a subtree.'),
+            self: z
+                .boolean()
+                .optional()
+                .describe('Return the `scope` element ITSELF instead of searching inside it. Use when the target is a plain layout container with no role, name, testid or text of its own — which is routinely the element that carries the handler, and is otherwise unreachable because every query excludes its own scope root. Requires `scope`.'),
             attrs: z
                 .array(z.string())
                 .optional()
@@ -297,7 +313,13 @@ const RAW_TOOLS = [
                 // The handler forwards an explicit allowlist, so a new input is silently dropped unless it is
                 // added here — the browser saw no `attrs` and returned undefined while the unit tests, which
                 // call matchQuery directly, passed. Schema plus implementation is not the whole wire.
+                //
+                // It happened again with `self`, in the same session that wrote this comment: declared on the
+                // tool, implemented in the browser, verified by unit tests that call `runQuery` directly, and
+                // dropped here — so the live call returned zero matches with no error. `query-forwarding.test.ts`
+                // now asserts the payload, because a comment is not a guard.
                 attrs: args['attrs'],
+                self: args['self'],
             }).then((result) => withSizeCost(paginateQueryResult(result, asNumber(args['limit']), true === args['count_only'])));
         },
     },

package/dist/visual/capture-cleanup.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Remember the private parent of a capture after the daemon has read it.
+ *
+ * Legacy captures live directly in `tmpdir()` and therefore have no directory to reclaim. The
+ * caller has already applied the capture-path trust-boundary check; this second exact parent check
+ * keeps the cleanup set limited to the one-level private layout.
+ */
+export declare function trackCaptureDirectory(path: string): void;
+/**
+ * Remove empty private capture directories during the daemon's existing awaited shutdown path.
+ *
+ * Deliberately `rmdir`, never recursive removal: captures are unlinked after reading, so a genuine
+ * directory is empty by shutdown. If anything unexpected remains, refusing to remove the directory
+ * is safer than widening a renderer-supplied path into a recursive delete.
+ */
+export declare function cleanupCaptureDirectories(): Promise<void>;

package/dist/visual/capture-cleanup.js

@@ -0,0 +1,39 @@
+import { rmdir } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, dirname } from 'node:path';
+import { RETICLE_CAPTURE_FILE_PREFIX } from '@reticlehq/core';
+/** Private shell directories whose captures this daemon has successfully consumed. */
+const captureDirectories = new Set();
+/**
+ * Remember the private parent of a capture after the daemon has read it.
+ *
+ * Legacy captures live directly in `tmpdir()` and therefore have no directory to reclaim. The
+ * caller has already applied the capture-path trust-boundary check; this second exact parent check
+ * keeps the cleanup set limited to the one-level private layout.
+ */
+export function trackCaptureDirectory(path) {
+    const parent = dirname(path);
+    if (dirname(parent) === tmpdir() && basename(parent).startsWith(RETICLE_CAPTURE_FILE_PREFIX)) {
+        captureDirectories.add(parent);
+    }
+}
+/**
+ * Remove empty private capture directories during the daemon's existing awaited shutdown path.
+ *
+ * Deliberately `rmdir`, never recursive removal: captures are unlinked after reading, so a genuine
+ * directory is empty by shutdown. If anything unexpected remains, refusing to remove the directory
+ * is safer than widening a renderer-supplied path into a recursive delete.
+ */
+export async function cleanupCaptureDirectories() {
+    await Promise.all([...captureDirectories].map(async (dir) => {
+        try {
+            await rmdir(dir);
+        }
+        catch {
+            // Best-effort shutdown housekeeping. A non-empty or already-removed directory is harmless.
+        }
+        finally {
+            captureDirectories.delete(dir);
+        }
+    }));
+}

package/dist/visual/visual-tools.d.ts

@@ -1,4 +1,22 @@
 import type { ToolDef } from '../tools/tools.js';
+/**
+ * Only read a capture the shell wrote. The path arrives from the PAGE, and the daemon must not
+ * become a file-read oracle for whatever a compromised renderer names.
+ *
+ * Two layouts are accepted, and the pair is the whole subtlety:
+ *
+ * - `<tmp>/<prefix><dir>/<prefix><n>.png` — the shell's own PRIVATE capture directory, created 0700
+ *   so no other local user can read the screenshot or pre-place a symlink at the path we write.
+ * - `<tmp>/<prefix><pid>-<n>.png` — the legacy flat layout. Kept because the shell ships as a
+ *   SEPARATE package on the user's own upgrade schedule: an app still on the older
+ *   `@reticlehq/electron` talking to a newer daemon must keep getting screenshots, not silently
+ *   start returning no image. It grants the daemon nothing it did not already have.
+ *
+ * Every comparison is an exact match against an UNRESOLVED path, which is what refuses traversal:
+ * `<tmp>/<prefix>x/../../etc/<prefix>passwd.png` has a grandparent of `<tmp>/<prefix>x/..`, not
+ * `<tmp>`. Exactly one directory level is allowed, so a deeper nesting is refused too.
+ */
+export declare function isCapturePath(path: string): boolean;
 /**
  * The opt-in pixel layer. Both tools require a DRIVEN browser (reticle drive /
  * RETICLE_CDP_URL) — the always-on SDK ships no screenshotter — and return a structured NO_PROVIDER

package/dist/visual/visual-tools.js

@@ -5,6 +5,7 @@ import { sessionIdShape } from '../tools/tool-kit.js';
 import { asNumber, asRecord, asString } from '../tools/tools-helpers.js';
 import { diffPng } from './visual-diff.js';
 import { VisualStore } from './visual-store.js';
+import { trackCaptureDirectory } from './capture-cleanup.js';
 import { readFile, unlink } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { basename, dirname } from 'node:path';
@@ -87,6 +88,7 @@ async function desktopCapture(deps, sessionId, fullPage) {
     try {
         const bytes = await readFile(path);
         await unlink(path).catch(() => undefined);
+        trackCaptureDirectory(path);
         return isCompletePng(bytes) ? { png: new Uint8Array(bytes) } : {};
     }
     catch {
@@ -94,12 +96,29 @@ async function desktopCapture(deps, sessionId, fullPage) {
     }
 }
 /**
- * Only read a capture the shell wrote: inside the OS temp dir, with Reticle's own filename prefix.
- * The path arrives from the PAGE, and the daemon must not become a file-read oracle for whatever a
- * compromised renderer names.
+ * Only read a capture the shell wrote. The path arrives from the PAGE, and the daemon must not
+ * become a file-read oracle for whatever a compromised renderer names.
+ *
+ * Two layouts are accepted, and the pair is the whole subtlety:
+ *
+ * - `<tmp>/<prefix><dir>/<prefix><n>.png` — the shell's own PRIVATE capture directory, created 0700
+ *   so no other local user can read the screenshot or pre-place a symlink at the path we write.
+ * - `<tmp>/<prefix><pid>-<n>.png` — the legacy flat layout. Kept because the shell ships as a
+ *   SEPARATE package on the user's own upgrade schedule: an app still on the older
+ *   `@reticlehq/electron` talking to a newer daemon must keep getting screenshots, not silently
+ *   start returning no image. It grants the daemon nothing it did not already have.
+ *
+ * Every comparison is an exact match against an UNRESOLVED path, which is what refuses traversal:
+ * `<tmp>/<prefix>x/../../etc/<prefix>passwd.png` has a grandparent of `<tmp>/<prefix>x/..`, not
+ * `<tmp>`. Exactly one directory level is allowed, so a deeper nesting is refused too.
  */
-function isCapturePath(path) {
-    return dirname(path) === tmpdir() && basename(path).startsWith(RETICLE_CAPTURE_FILE_PREFIX);
+export function isCapturePath(path) {
+    if (!basename(path).startsWith(RETICLE_CAPTURE_FILE_PREFIX))
+        return false;
+    const parent = dirname(path);
+    if (parent === tmpdir())
+        return true;
+    return dirname(parent) === tmpdir() && basename(parent).startsWith(RETICLE_CAPTURE_FILE_PREFIX);
 }
 /**
  * A PNG is complete only if it ends with IEND. This check exists because a truncated image once

package/docs/agent-cheatsheet.md

@@ -7,10 +7,12 @@ One screen to get fluent. Reticle is the **proof layer for AI agents** — no sc
 | Verb | Tool | One-liner |
 | --- | --- | --- |
 | **look** | `reticle_snapshot` / `reticle_query` | See the page (semantic tree) / find one specific element. |
-| **act** | `reticle_act` / `reticle_act_sequence` / `reticle_act_and_wait` | Click/fill a `ref` / **batch a whole journey in one hop** / act + wait for a predicate in one hop. |
+| **act** | **`reticle_act_and_wait`** / `reticle_act_sequence` / `reticle_act` | **Act + name the consequence, one hop — reach for this first.** / batch a whole journey in one hop / move the app and prove nothing. |
 | **observe** | `reticle_observe` / `reticle_wait_for` | Everything the app did after `since` / block until true. |
 | **assert** | `reticle_assert` | Evaluate a predicate → `{ pass, evidence, failureReason? }`. The end of every loop. |
 
+> **Only `reticle_act_and_wait` and `reticle_assert` produce a verdict.** Everything else moves or reads the app and proves nothing, so a drive ending without one of those two has no result however many tools it used. `reticle_act` is the tool agents reach for by habit and it catches nothing; `act_and_wait` is where defects actually surface. And `verified: "unknown"` is not a pass — it means Reticle drove the app and could not tell what happened. Report it as unknown.
+
 `reticle_act` returns a `since` cursor — pass it to `reticle_observe({ since })` to scope the window. Elements are addressed by stable refs (`e7`) from `snapshot`/`query`; they re-resolve across re-renders.
 
 **`assert`/`wait_for` are auto-scoped to your last act.** By default they only count events buffered _since_ the most recent act, so a stale signal from a previous step can't fake a pass — pass an explicit `since` to override. **Clicks run the code, not pixels:** `reticle_act` click fires the full pointer sequence on the element (no coordinate gesture for the HUD to intercept), reports `occluded:true` when something covers the target, and stays synthetic even with CDP configured (use `args:{ native:true }` for a trusted native click).
@@ -21,6 +23,16 @@ One screen to get fluent. Reticle is the **proof layer for AI agents** — no sc
 - Need to wait without acting? `reticle_wait_for({ predicate: { kind: "settled", quietMs } })`.
 - Waiting for a specific outcome? Pass that consequence as the predicate (`{ signal }` / `{ net }`), or `allOf` it with `{ kind: "settled" }` to wait for both the event _and_ the page going quiet.
 
+**A predicate that does not parse produces NO verdict — not a failing one.** Nothing runs, so the drive ends with no result at all, which is strictly worse than a failure. The shapes below are the ones agents reach for most; the first column now works, but knowing the second saves you the round trip:
+
+| You may write | It means |
+| --- | --- |
+| `{ kind: "text", text: "Saved" }` | `{ kind: "text", contains: "Saved" }` |
+| `{ kind: "element", role: "button", text: "Save" }` | `{ kind: "element", query: { role, text } }` |
+| `{ kind: "route", url: "/checkout" }` | `{ kind: "route", contains: "/checkout" }` |
+
+If a predicate is still rejected, the error names the fields **that kind** accepts — read it rather than guessing again, and note `state` spells its selector `path` while `route` spells its `pathname`.
+
 **Assert a consequence, not just presence.** `{ signal }` / `{ net }` prove the feature actually did something; `{ element }` / `{ text }` only prove something is on screen — which a stale render or a locator healed to the wrong element can fake. A _passing_ presence-only `reticle_assert` returns `advice` nudging you to a consequence; heed it on anything that matters.
 
 ## The 4-layer cross-check — never trust a green the state contradicts
@@ -71,7 +83,7 @@ Frequently useful but NOT core, so reach them through `reticle_run({ tool, args
 ## Start here
 
 0. Just ran `reticle init` / started the dev server? Poll `reticle_sessions()` until your tab appears — readiness is server-internal now, so the first live call already blocks until the SDK connects.
-1. `reticle_sessions` — find the connected tab (omit `sessionId` if there's only one).
+1. `reticle_sessions` — find the connected tab (omit `sessionId` if there's only one). **An empty list is not a dead end: read the `why` field.** It names which case this is — no app running, an app running that has never dialled this daemon, a project that never went through `init`, or a tab that closed — and the fix for each. Do not fall back to static reasoning until you have read it.
 2. `reticle_domain` — learn the app BEFORE testing: the saved flows, what each asserts, and the **gaps** (declared signals/testids that no flow verifies — untested intent). Tells you what to test and where the real risk is without crawling the whole app. Falls back to `reticle_capabilities` for the raw testable surface (`testids`, `signals`, `stores`, `flows`).
 3. Run the loop: **look → act → observe → assert**, cross-checking the 4 layers on anything that matters.
 

package/docs/gate-plan.md

@@ -77,7 +77,7 @@ Nothing below is trustworthy until a gate result can be distinguished from a gat
 - [x] **`init` support per client** — `init/mcp-clients.ts` registers Reticle with **seven** clients, not two. Every path and shape was read from that client's own documentation rather than recalled: Cursor/Windsurf/Gemini share `mcpServers`, VS Code uses `servers`, OpenCode uses `mcp` with the command as an **array**, Codex is TOML. A single "write mcp.json" assuming the Cursor shape produces a file three of them ignore — an install that reports success and registers nothing.
   - Detection is conservative and one-directional: we write into a config a client **already has**, never creating `~/.gemini` or `~/.codeium` for somebody who does not use them.
   - Codex is deliberately not auto-written. Editing TOML without a parser risks every _other_ server in the user's file; it returns MANUAL with an exact block.
-- [x] **Per-client compat script** — `apps/e2e/client-compat.mjs`. Extracts the command from the config **exactly the way that client would**, runs it, and speaks MCP to it. 7/7 clients, 23 assertions, each advertising 17 tools.
+- [x] **Per-client compat script** — `apps/e2e/client-compat.mjs`. Extracts the command from the config **exactly the way that client would**, runs it, and speaks MCP to it. 7/7 clients, 23 assertions, each advertising 18 tools.
   - It proves only the half a machine can prove, and the verdict is named `runnable-unverified` so the distinction survives into the matrix. Whether the client _reads_ that path needs the real client, which is the submitted half.
 - [x] **Submission flow** — `apps/e2e/matrix.mjs --validate`, run by CI's `matrix-records` job on every PR. The validator refuses what cannot be acted on: `works` without `checks.toolsVisible` (the self-report the flow exists to replace), `broken` without the client's verbatim error, or any record with no host or version. Its self-check runs first, because a validator that has never refused anything is not a validator. Contributor guide in [`docs/matrix/README.md`](./matrix/README.md).
 - [x] **Generated `MATRIX.md`** — from submitted records, prettier-ignored because a generated file that fails `format:check` teaches people to skip the gate. **The current honest state is seven clients and ZERO ticks**: `◐` means a runnable entry was written where the client documents it and _nobody has run that client_, and the generated legend says so rather than rounding `◐` up to `✅`.

package/docs/gates.md

@@ -8,7 +8,7 @@
 
 ## 0. Last verified
 
-Every gate below was executed end to end against `main` on **2026-08-11** (macOS, M-series, `v2.5.0`). A green row means somebody watched it go green, not that it is supposed to be green.
+Every gate below was executed end to end against `main` on **2026-08-12** (macOS, M-series, `v2.6.0`). A green row means somebody watched it go green, not that it is supposed to be green.
 
 | Gate | Result | Wall clock |
 | --- | --- | --- |

package/docs/telemetry-contract.md

@@ -33,7 +33,7 @@ Do **not** add telemetry inside a tool handler. If you find yourself wanting to,
 
 `bug_found` fires once per OCCURRENCE. A defect hit five times in a session is five events, which is the right raw signal — frequency is what says which classes of defect actually cost anybody anything. But it means a naive count answers "how often were defects hit", not "how many defects were found", while looking like it answers the second.
 
-So every `bug_found` carries **`repeat`**: false the first time a KIND is seen in a session, true after. Count `repeat: false` for **distinct defects**; count everything for **instances**. Measured on a real app: 7 events, 3 defects, 4 repeats. Publishing the 7 as defects would have inflated the claim by more than double.
+So every `bug_found` carries **`repeat`**: false the first time a KIND is seen in a session, true after. Count `repeat: false` for **distinct defects**; count everything for **instances**. Measured on a real app, the instance count was more than double the defect count. Publishing instances as defects inflates the claim accordingly.
 
 The denominator is **`verification_completed`**, which fires per verdict with `via`, `verified`, `passed` and `falseGreenCaught`. Defects per verification is the honest rate; raw defect counts grow with usage and say nothing on their own.
 
@@ -98,10 +98,21 @@ The single exception is `daemon_stopped`, which is **awaited** — because the p
 | `feedback_submitted` | `reticle feedback`, or an agent's report | the qualitative channel |
 | `identified` | `reticle identify` | joins anonymous machine ids to a person who volunteered one |
 | `mcp_client_connected` | an MCP client attached | how many sessions are agent-driven at all |
+| `app_instrumented` | the first app carrying the SDK reached this daemon | **the funnel step everything turns on** — see below |
 | `mcp_connection_lost` | the proxy lost its daemon | **the transport-stability metric.** The disconnect that makes a user reopen `/mcp` is invisible without it |
 | `init_completed` | `reticle init` finished | does install actually work, outside the fixtures gate |
 | `bug_found` | a defect was detected in the app under test | the value delivered, as opposed to the work done |
 
+## The install has two halves — `app_instrumented`
+
+Reticle is only usable when both halves are done: the MCP server is registered so the agent has the tools, and the SDK is loaded by a running page so there is something for those tools to look at. They are done by different commands, at different times, often in different directories. Almost everyone completes the first. The second is where the users go.
+
+Nothing measured the second. `daemon_started` and `mcp_client_connected` describe the agent half. `session_appConnects` describes the app half but is a **window counter** — it resets on every flush, so a user whose app connected in one window reads zero in every other. The population it under-counts is precisely the population being measured, and a funnel built on it reported fewer instrumented users than there were users calling tools, which is impossible on its face.
+
+`app_instrumented` fires **once per daemon run**, on the first session-ready only, so `daemon_started` → `app_instrumented` is a rate rather than an inference and a reloading page cannot inflate it. It carries `initialized` (had `init` run here), `agentAttached` (was an agent already waiting), and `msToFirstApp` (how long the daemon sat with nothing wired). It deliberately carries no stack and no framework: `project_profiled` already reports both for the same run, and the two join on `sessionId`.
+
+What it still cannot see is **why** an app never connected — every cause for that is page-side (the non-localhost gate, a port mismatch, a stale build, a dev server never restarted), where the daemon has no visibility. That needs the SDK to report its own refusals, and it is the next thing to build.
+
 ## Sessions: `daemon_stopped` vs `session_progress`
 
 Count sessions with **`daemon_stopped`** (`final: true`). It fires once, at a clean exit.
@@ -124,6 +135,7 @@ Four counters and one flag were added because the data could not answer question
 | `verification.browser` | `verification_completed` | `headless` \| `headed` \| `attached` — who DROVE the browser. `attached` (Reticle launched nothing, the SDK connected from a browser somebody else opened) is the common case in production, so on its own this is mostly "somebody's own browser". |
 | `verification.brand` | `verification_completed` | WHICH browser it was: `chrome` \| `edge` \| `arc` \| `dia` \| `brave` \| `opera` \| `firefox` \| `safari` \| `other` — the closed `BrowserBrand` list in core. The axis `engine` cannot answer, since Chrome, Edge, Arc, Dia and Brave are all `blink`. The SDK reads `navigator.userAgentData.brands` (and the UA string on Firefox/Safari, which expose no `userAgentData`) and normalises IN THE PAGE: a raw brand or UA string is unbounded and fingerprintable and never leaves. Anything unrecognised is `other`. **Omitted rather than `"unknown"`** when the page did not say — a desktop webview has no brand and an older SDK does not report one, and a guess is indistinguishable from a measurement on a dashboard. |
 | `verification.reason` | `verification_completed` | WHICH clause of `decideVerified` produced the verdict, from core's closed `VerifiedReason`: `inconclusive` \| `observation_lost` \| `assertion_failed` \| `contradicted` \| `already_true` \| `unclean_capture` \| `vacuous_grade` \| `outcome_pending` \| `outcome_unread` \| `unsettled` \| `proved`. See below. |
+| `verification.uncleanLoss` | `verification_completed` | WHAT was lost when `reason` is `unclean_capture`, from core's closed `CaptureLoss`: `buffer_loss` (our server ring buffer evicted evidence from the window) \| `transport_gap` (our browser queue overflowed) \| `blind_spot` (a boundary in the page — a cross-origin frame, a closed shadow root) \| `other`. Three owners, three fixes, and one bar on a dashboard until this existed. ONE value, not a list — a multi-value property is not something a breakdown can group by, so the first is sent, ours before the page's. **Absent whenever the capture was clean**, so its presence is itself the signal. Reported as `other` rather than omitted when the block says dirty and names nothing: a gap there would read as "no unclean verdicts happened". |
 | `bug.attribution` | `bug_found` | `app` \| `request` \| `reticle` — whose fault the defect was. **Absent means unclassified**, never `app`. See below. |
 | `outage.stage` / `outage.reason` / `outage.attempts` | `mcp_connection_lost` | which stage of the outage, why the stream went away (closed `OutageReason`, `other` for anything unnamed), and how many reconnects had been tried. See below. |
 | `tzOffsetMin` | every event | minutes offset from UTC. One integer, no location. |

package/docs/telemetry.md

@@ -25,7 +25,7 @@ Thirteen kinds of events, each a single small JSON object:
 | `cli_command_run` | You run a `reticle` command | Which subcommand (`verify`, `status`, …) and which flags were present, by name |
 | `daemon_started` | The local daemon starts | — |
 | `daemon_stopped` | The local daemon stops | A summary of the session — see below |
-| `verification_completed` | A verification produces a verdict | Whether it passed, and whether Reticle refused to call a passing check verified |
+| `verification_completed` | A verification produces a verdict | Whether it passed, whether Reticle refused to call a passing check verified, and **why** the verdict came out that way — see below |
 | `project_profiled` | Once per daemon start | The shape of the project — see below |
 | `version_changed` | You update or roll back | The two version numbers, and which direction |
 | `runtime_crashed` | The daemon hits an uncaught error | The error's type, **Reticle's own** stack frames, and the message with variables stripped — see below |
@@ -44,6 +44,14 @@ Thirteen kinds of events, each a single small JSON object:
 
 It also carries a snapshot of the **machine's** state — our own process's memory, free and total system RAM, load average and CPU count — taken at shutdown and again on any crash. This is what separates "your machine ran out of memory" from "Reticle has a bug", which otherwise produce identical-looking failures. No hostname, no username, no paths, no process list.
 
+### Why a verdict came out that way
+
+`verification_completed` carries the **clause** that decided the verdict, from a fixed list we define: `proved`, `contradicted`, `assertion_failed`, `already_true`, `unclean_capture`, `vacuous_grade`, `outcome_pending`, `outcome_unread`, `unsettled`, `observation_lost`, `inconclusive`.
+
+It exists because `verified: "unknown"` covered seven different situations belonging to three different owners — your app, your agent, and Reticle's own blind spots — and they arrived as one value. It is a **name from our own vocabulary**, never a description of your app: `contradicted` says two channels disagreed, not which ones, about what, or on which page.
+
+When the clause is `unclean_capture`, one further name says which of our three losses caused it — `buffer_loss` (our server's event buffer), `transport_gap` (our browser-side queue), `blind_spot` (a boundary in the page, such as a cross-origin frame), or `other`. All four are facts about **Reticle's** ability to observe, not about what it observed. This field is how we found that Reticle was refusing to answer over windows that were completely intact.
+
 ### Bugs Reticle finds
 
 When Reticle catches a defect in the app it is verifying, it records **that a class of defect was found** — never what it was found in. The event carries the kind (`signal-contradicted`, `duplicate-request`, `console-error`, …) and how it surfaced, and nothing else: no selector, no URL, no element, no description of your app or its behaviour.

package/docs/token-efficiency.md

@@ -44,10 +44,10 @@ Measured live, all servers in one run, same tokenizer (`bench/harness/schema-tax
 
 | MCP server                                | tools | schema tokens |
 | ----------------------------------------- | ----: | ------------: |
-| **Reticle — the tool surface**            |    17 |    **~4,500** |
+| **Reticle — the tool surface**            |    18 |    **~4,930** |
 | Playwright MCP                            |    23 |         3,725 |
 | Chrome DevTools MCP                       |    29 |         5,116 |
-| Reticle — `RETICLE_ADVERTISE_ALL_TOOLS=1` |    48 |       ~32,000 |
+| Reticle — `RETICLE_ADVERTISE_ALL_TOOLS=1` |    48 |       ~30,200 |
 
 There is one tool surface: the verify loop advertised directly, plus two meta-tools (`reticle_tools`, `reticle_run`) that reach every other tool on demand. Nothing is unreachable; the cold tail simply is not re-sent every turn.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/server",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "description": "Reticle bridge + MCP server. Hosts the browser WS endpoint and exposes MCP tools to the coding agent.",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,7 +22,7 @@
     "@modelcontextprotocol/sdk": "^1.13.0",
     "ws": "^8.18.0",
     "zod": "^3.24.1",
-    "@reticlehq/core": "2.6.0"
+    "@reticlehq/core": "2.7.0"
   },
   "devDependencies": {
     "@types/pngjs": "^6.0.5",