@reticlehq/server 2.13.1 → 2.14.0

package/dist/tools/resolve-target.d.ts

@@ -1,7 +1,10 @@
-/** What the resolution produced: a ref to act on, or the reason there isn't one. */
+/** What the resolution produced: a ref to act on, a document-key press, or the reason there isn't one. */
 export type TargetResolution = {
     readonly kind: 'ref';
     readonly ref: string;
+} | {
+    readonly kind: 'global';
+    readonly ref: '';
 } | {
     readonly kind: 'error';
     readonly message: string;
@@ -22,5 +25,8 @@ export type TargetResolution = {
  * Invisible matches are filtered before counting: a hidden duplicate is a common way for a
  * legitimately unambiguous query to look ambiguous, and refusing on it would push callers back to
  * the two-turn path for no gain.
+ *
+ * When several remain, they are ranked (in-viewport, then role) inside the refusal only — so the
+ * agent can pass the top ref on the next turn without a snapshot. Ranking is never acted on here.
  */
 export declare function resolveTargetRef(candidates: readonly unknown[]): TargetResolution;

package/dist/tools/resolve-target.js

@@ -1,4 +1,67 @@
+import { ElementState } from '@reticlehq/core';
 import { asRecord } from './tools-helpers.js';
+/**
+ * Roles that usually name the control an agent meant, ahead of a wrapping `generic` that
+ * happened to inherit the same accessible name (header CTA vs empty-state CTA).
+ */
+const ROLE_RANK = {
+    button: 0,
+    link: 1,
+    menuitem: 2,
+    tab: 3,
+    checkbox: 4,
+    radio: 5,
+    switch: 6,
+    option: 7,
+    combobox: 8,
+    textbox: 9,
+    searchbox: 10,
+};
+function roleRank(role) {
+    if ('string' !== typeof role)
+        return 100;
+    return ROLE_RANK[role] ?? 50;
+}
+function statesOf(c) {
+    return Array.isArray(c.states) ? c.states.filter((s) => 'string' === typeof s) : [];
+}
+function inViewport(c) {
+    return statesOf(c).includes(ElementState.IN_VIEWPORT);
+}
+/**
+ * Stable ranking for the refusal message only. Never used to pick — an action must not guess.
+ *
+ * Order: in-viewport over off-screen, then more-specific roles over `generic`. Visibility is
+ * already applied before this runs (hidden duplicates are filtered), so it is not a sort key here.
+ */
+function compareCandidates(a, b) {
+    const viewport = Number(inViewport(b)) - Number(inViewport(a));
+    if (0 !== viewport)
+        return viewport;
+    return roleRank(a.role) - roleRank(b.role);
+}
+/**
+ * Annotate where the candidate sits. `anyInViewport` is true when at least one sibling carried
+ * `inViewport` — only then is absence meaningful as off-screen. Without that signal, saying
+ * "off-screen" would invent a fact the descriptor never reported.
+ */
+function formatCandidate(c, anyInViewport) {
+    const role = 'string' === typeof c.role ? c.role : '?';
+    const name = 'string' === typeof c.name ? c.name : '';
+    const ref = 'string' === typeof c.ref ? c.ref : '?';
+    const visible = false !== c.visible;
+    let where;
+    if (!visible)
+        where = 'hidden';
+    else if (inViewport(c))
+        where = 'in-viewport';
+    else if (anyInViewport)
+        where = 'off-screen';
+    else
+        where = 'visible';
+    const head = name.length > 0 ? `${ref} (${role} "${name}"` : `${ref} (${role}`;
+    return `${head}; ${where})`;
+}
 /**
  * Turn a target QUERY into the single ref an action can be performed on.
  *
@@ -15,6 +78,9 @@ import { asRecord } from './tools-helpers.js';
  * Invisible matches are filtered before counting: a hidden duplicate is a common way for a
  * legitimately unambiguous query to look ambiguous, and refusing on it would push callers back to
  * the two-turn path for no gain.
+ *
+ * When several remain, they are ranked (in-viewport, then role) inside the refusal only — so the
+ * agent can pass the top ref on the next turn without a snapshot. Ranking is never acted on here.
  */
 export function resolveTargetRef(candidates) {
     const all = candidates.map((c) => asRecord(c));
@@ -28,20 +94,17 @@ export function resolveTargetRef(candidates) {
         };
     }
     if (usable.length > 1) {
-        const named = usable
+        const ranked = [...usable].sort(compareCandidates);
+        const anyInViewport = ranked.some(inViewport);
+        const named = ranked
             .slice(0, 5)
-            .map((c) => {
-            const role = 'string' === typeof c.role ? c.role : '?';
-            const name = 'string' === typeof c.name ? c.name : '';
-            const ref = 'string' === typeof c.ref ? c.ref : '?';
-            return name.length > 0 ? `${ref} (${role} "${name}")` : `${ref} (${role})`;
-        })
+            .map((c) => formatCandidate(c, anyInViewport))
             .join(', ');
         return {
             kind: 'error',
             message: `target matched ${String(usable.length)} elements and an action must not guess between ` +
-                `them: ${named}. Narrow the query (add role/name/testid or a scope), or pass an explicit ` +
-                '`ref` from reticle_query.',
+                `them (ranked: in-viewport, then role): ${named}. Narrow the query (add role/name/testid ` +
+                'or a scope), or pass an explicit `ref` from reticle_query.',
         };
     }
     const only = usable[0];

package/dist/tools/settle-in-flight.d.ts

@@ -77,7 +77,7 @@ export declare function repeatedRequestLabels(events: readonly {
     type: string;
     data: Record<string, unknown>;
 }[]): string[];
-export interface SettleResult {
+interface SettleResult {
     /** True when nothing this window started is still outstanding. */
     settled: boolean;
     /** What was still open when the wait ended — empty when `settled`. */

package/dist/tools/settle-in-flight.js

@@ -27,7 +27,7 @@
  *   - still in flight when the budget genuinely runs out → `unsettled`, as before, but now an honest
  *     limit instead of an early exit.
  */
-import { EventType, isDevToolingUrl } from '@reticlehq/core';
+import { EventType, NetInitiator, isDevToolingUrl } from '@reticlehq/core';
 /**
  * The dev toolchain talking about ITSELF is not the app finishing its work.
  *
@@ -37,6 +37,13 @@ import { EventType, isDevToolingUrl } from '@reticlehq/core';
  * was graded on the strength of a Next webpack hot-update the same payload printed as ignored.
  */
 const isDevTooling = (data) => isDevToolingUrl('string' === typeof data['url'] ? data['url'] : undefined);
+/**
+ * A departure records where the browser was SENT, not a request whose result we will see — the
+ * response is delivered to a document this session does not live into. It can never be matched by a
+ * NET_REQUEST, so counting it as outstanding would mean no page containing an outbound link or a
+ * download button ever settles again. See `NetInitiator.NAVIGATION`.
+ */
+const isDeparture = (data) => data['initiator'] === NetInitiator.NAVIGATION;
 /** How often to re-read the buffer. Short enough to return promptly, long enough not to spin. */
 const POLL_MS = 50;
 const idOf = (data) => 'string' === typeof data['id'] ? data['id'] : undefined;
@@ -58,7 +65,7 @@ export function inFlightRequestIds(events) {
     }
     const open = [];
     for (const e of events) {
-        if (e.type !== EventType.NET_PENDING || isDevTooling(e.data))
+        if (e.type !== EventType.NET_PENDING || isDevTooling(e.data) || isDeparture(e.data))
             continue;
         const id = idOf(e.data);
         if (id !== undefined && !settled.has(id) && !open.includes(id))

package/dist/tools/snapshot-delta.d.ts

@@ -12,6 +12,17 @@
  * invalidates the prior snapshot (a diff across pages would be meaningless), so the next snapshot
  * returns full — never a misleading cross-page delta.
  */
+/**
+ * Pure: was the prior snapshot of this scope both RECENT and SMALLER than this one? If so, the
+ * earlier reading was very likely taken mid-load — content arrived in the gap between the two calls
+ * — and any presence-grade conclusion drawn from that earlier snapshot ("this route renders
+ * nothing") is suspect. Silent otherwise: a stale prior or a page that shrank (or stayed the same
+ * size) is not this trap.
+ */
+export declare function snapshotGrowthNote(prior: {
+    tree: string;
+    atMs: number;
+} | undefined, nextTree: string, nowMs: number, windowMs?: number): string | undefined;
 export declare const SnapshotDeltaMode: {
     readonly FULL: "full";
     readonly DELTA: "delta";
@@ -45,11 +56,23 @@ export declare function snapshotDelta(prevTree: string | undefined, nextTree: st
 /** Per-(session,scope,mode) last-snapshot cache. Route-aware: a route change invalidates the entry. */
 export declare class SnapshotCache {
     #private;
-    constructor(max?: number);
+    constructor(max?: number, now?: () => number);
     /** True when an entry exists for this key (regardless of route match). */
     has(key: string): boolean;
+    /** The clock this cache was constructed with — callers compare against it so `remember`'s
+     * timestamp and a caller's "now" can never drift onto two different clocks. */
+    now(): number;
     /** Last tree for this key IF the route still matches; undefined when absent or route changed. */
     recall(key: string, route: string): string | undefined;
+    /**
+     * The last remembered tree for this key AND when it was remembered, IF the route still matches.
+     * Same route-gating as `recall` — a route change makes the prior entry meaningless for comparison,
+     * not just for diffing.
+     */
+    priorEntry(key: string, route: string): {
+        tree: string;
+        atMs: number;
+    } | undefined;
     remember(key: string, route: string, tree: string): void;
 }
 export declare function snapshotCacheKey(sessionId: string, scope: string, mode: string): string;

package/dist/tools/snapshot-delta.js

@@ -158,6 +158,37 @@ function focusedLine(tree) {
     const text = withoutFocus(focused).trim();
     return { id: REF_MARKER.exec(focused)?.[0]?.trim() ?? deltaKey(focused), text };
 }
+/**
+ * How recent a smaller prior snapshot has to be for its growth to be worth flagging (#787) — long
+ * enough to catch the "route committed, then hydrated" window the bug report describes (hundreds of
+ * ms up to a couple of seconds), short enough that an unrelated LATER snapshot of a page that simply
+ * grew through normal use (an infinite-scroll load, a live feed) doesn't get blamed on load timing.
+ */
+const GROWTH_NOTE_WINDOW_MS = 5000;
+/** Non-empty lines only — a blank line in the tree text is formatting, not a node. */
+function nodeCount(tree) {
+    return tree.split('\n').filter((line) => '' !== line.trim()).length;
+}
+/**
+ * Pure: was the prior snapshot of this scope both RECENT and SMALLER than this one? If so, the
+ * earlier reading was very likely taken mid-load — content arrived in the gap between the two calls
+ * — and any presence-grade conclusion drawn from that earlier snapshot ("this route renders
+ * nothing") is suspect. Silent otherwise: a stale prior or a page that shrank (or stayed the same
+ * size) is not this trap.
+ */
+export function snapshotGrowthNote(prior, nextTree, nowMs, windowMs = GROWTH_NOTE_WINDOW_MS) {
+    if (prior === undefined)
+        return undefined;
+    const elapsedMs = nowMs - prior.atMs;
+    if (elapsedMs < 0 || elapsedMs > windowMs)
+        return undefined;
+    const priorCount = nodeCount(prior.tree);
+    const nextCount = nodeCount(nextTree);
+    if (nextCount <= priorCount)
+        return undefined;
+    return (`this scope had ${String(priorCount)} nodes ${String(elapsedMs)}ms ago and has ${String(nextCount)} now — ` +
+        'content likely arrived after your last look; a presence conclusion drawn from that earlier snapshot may have been taken mid-load');
+}
 export const SnapshotDeltaMode = {
     FULL: 'full',
     DELTA: 'delta',
@@ -200,15 +231,30 @@ const DEFAULT_MAX_ENTRIES = 50;
 export class SnapshotCache {
     #map = new Map();
     #max;
-    constructor(max = DEFAULT_MAX_ENTRIES) {
+    #now;
+    constructor(max = DEFAULT_MAX_ENTRIES, now = Date.now) {
         this.#max = max;
+        this.#now = now;
     }
     /** True when an entry exists for this key (regardless of route match). */
     has(key) {
         return this.#map.has(key);
     }
+    /** The clock this cache was constructed with — callers compare against it so `remember`'s
+     * timestamp and a caller's "now" can never drift onto two different clocks. */
+    now() {
+        return this.#now();
+    }
     /** Last tree for this key IF the route still matches; undefined when absent or route changed. */
     recall(key, route) {
+        return this.priorEntry(key, route)?.tree;
+    }
+    /**
+     * The last remembered tree for this key AND when it was remembered, IF the route still matches.
+     * Same route-gating as `recall` — a route change makes the prior entry meaningless for comparison,
+     * not just for diffing.
+     */
+    priorEntry(key, route) {
         const entry = this.#map.get(key);
         if (entry === undefined || entry.route !== route)
             return undefined;
@@ -216,7 +262,7 @@ export class SnapshotCache {
         // (Map preserves insertion order; delete+set moves it to the most-recently-used end).
         this.#map.delete(key);
         this.#map.set(key, entry);
-        return entry.tree;
+        return { tree: entry.tree, atMs: entry.atMs };
     }
     remember(key, route, tree) {
         // Re-insert to move the key to the most-recently-used end (a plain set keeps its old position).
@@ -226,7 +272,7 @@ export class SnapshotCache {
             if (oldest !== undefined)
                 this.#map.delete(oldest);
         }
-        this.#map.set(key, { route, tree });
+        this.#map.set(key, { route, tree, atMs: this.#now() });
     }
 }
 /**
@@ -260,17 +306,23 @@ export function applySnapshotDelta(raw, opts, cache) {
         : {};
     const route = 'string' === typeof status['route'] ? status['route'] : '';
     const key = snapshotCacheKey(opts.sessionId, opts.scope, opts.mode);
+    // Read the growth signal BEFORE remember() overwrites the entry it compares against — needed on
+    // both branches below (#787), not only the diff:true path, since the reporter's own repro used a
+    // plain snapshot the second time.
+    const priorEntry = cache.priorEntry(key, route);
+    const growthNote = snapshotGrowthNote(priorEntry, tree, cache.now());
+    const growth = growthNote === undefined ? {} : { growthWarning: growthNote };
     if (!opts.diff) {
         cache.remember(key, route, tree);
-        return raw;
+        return { ...r, ...growth };
     }
-    const prev = cache.recall(key, route);
+    const prev = priorEntry?.tree;
     const hadEntry = cache.has(key);
     cache.remember(key, route, tree);
     const decision = snapshotDelta(prev, tree);
     if (decision.mode === SnapshotDeltaMode.FULL) {
         const reason = hadEntry ? 'route changed' : 'first snapshot for this route';
-        return { ...r, mode: SnapshotDeltaMode.FULL, reason };
+        return { ...r, mode: SnapshotDeltaMode.FULL, reason, ...growth };
     }
     // The walk stops at a node cap and returns a DOCUMENT-ORDER PREFIX, so two capped snapshots of a
     // large page are identical whenever the change happened past the cap — and "unchanged" is then a
@@ -282,7 +334,13 @@ export function applySnapshotDelta(raw, opts, cache) {
     // field is simply absent forever.
     const moved = decision.focusChanged === undefined ? {} : { focusChanged: decision.focusChanged };
     if (decision.mode === SnapshotDeltaMode.UNCHANGED) {
-        return { mode: SnapshotDeltaMode.UNCHANGED, status: r['status'], ...moved, ...capped };
+        return {
+            mode: SnapshotDeltaMode.UNCHANGED,
+            status: r['status'],
+            ...moved,
+            ...capped,
+            ...growth,
+        };
     }
     const { changed, ...structuralDelta } = decision.delta;
     const changedField = changed.length > 0 ? { changed, changedCount: changed.length } : {};
@@ -293,5 +351,6 @@ export function applySnapshotDelta(raw, opts, cache) {
         status: r['status'],
         ...moved,
         ...capped,
+        ...growth,
     };
 }

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

@@ -10,6 +10,7 @@ export declare const ReticleTool: {
     readonly ACT_SEQUENCE: "reticle_act_sequence";
     readonly ACT_AND_WAIT: "reticle_act_and_wait";
     readonly OBSERVE: "reticle_observe";
+    readonly LINEAGE: "reticle_lineage";
     readonly WAIT_FOR: "reticle_wait_for";
     readonly NETWORK: "reticle_network";
     readonly CONSOLE: "reticle_console";

package/dist/tools/tool-names.js

@@ -11,6 +11,7 @@ export const ReticleTool = {
     ACT_SEQUENCE: FlowStepTool.ACT_SEQUENCE,
     ACT_AND_WAIT: FlowStepTool.ACT_AND_WAIT,
     OBSERVE: 'reticle_observe',
+    LINEAGE: 'reticle_lineage',
     WAIT_FOR: 'reticle_wait_for',
     NETWORK: 'reticle_network',
     CONSOLE: 'reticle_console',

package/dist/tools/tool-surface.js

@@ -215,6 +215,26 @@ export const CORE_TOOL_NAMES = new Set([
     // deleting the instruction from the lease and the pause hint — deletes the handback protocol,
     // because there is nowhere else those two calls are ever named.
     ReticleTool.SESSION,
+    // VERIFY is the only advertised tool that can CONCLUDE, and its absence was measurably the most
+    // expensive thing on this surface.
+    //
+    // Measured on the Layer B agent loop (bench/raw/agent-loop-results.json, Haiku 4.5, 25-turn cap):
+    // on the no-regression control — a CLEAN app, where the right answer is "nothing is wrong" —
+    // Playwright MCP concluded in 7 turns and Reticle burned all 25 and never answered, at 333k tokens
+    // against Playwright's 54k. That one cell was a quarter of Reticle's total cost across five
+    // scenarios. Removing it, Reticle is at parity on the other four and wins two outright.
+    //
+    // The cause is compositional rather than behavioural: every other tool in this set answers "here
+    // is more to look at". None of them can say "there is nothing more". On a healthy app — which is
+    // most runs — that is a loop with no exit, and 25 was just where the cap fell.
+    //
+    // `reticle_verify` is the exit. { action: "crawl" } drives every reachable control itself and
+    // reports the whole fault set in ONE call, and { action: "flows" } replays the saved flows with no
+    // model in the loop at all — the path Layer C measures at 271 tokens, deterministic, 0% flake.
+    // Both were built and neither was reachable: the same "a tool an agent must already know about is
+    // a tool that never gets called" argument that put INSPECT and FEEDBACK here, applied to the one
+    // tool that ends the loop.
+    ReticleTool.VERIFY,
 ]);
 /**
  * The extended surface: what `all` advertises BEYOND the default set.
@@ -269,8 +289,6 @@ export const EXTENDED_TOOL_NAMES = new Set([
     ReticleTool.CLOCK,
     ReticleTool.NETWORK_MOCK,
     ReticleTool.STORAGE,
-    // Merged change/flows/affected/coverage/crawl — one name where three of these used to sit.
-    ReticleTool.VERIFY,
 ]);
 /**
  * The verify surface: one acting tool that returns a verdict, plus the two meta-tools that reach

package/dist/tools/tools.js

@@ -17,6 +17,8 @@ import { paginateQueryResult } from './query-paginate.js';
  */
 const QUERY_BY_VALUES = Object.values(QueryBy);
 const QUERY_BY_LIST = QUERY_BY_VALUES.join(' | ');
+/** Every `by`/`value` shorthand says the same thing; the parameter name carries the rest. */
+const QUERY_ALIAS = 'Predicate spelling of by/value.';
 const queryByEnum = z.enum(QUERY_BY_VALUES);
 import { CONTRACT_TOOLS } from './contract-tools.js';
 import { DOMAIN_TOOLS } from '../domain/domain-tools.js';
@@ -42,6 +44,7 @@ import { sessionIdShape, commandOrThrow } from './tool-kit.js';
 import { applyMerges } from './merge-tools.js';
 import { ACT_TOOLS } from './act-tools.js';
 import { OBSERVE_TOOLS } from './observe-tools.js';
+import { LINEAGE_TOOLS } from './lineage-tools.js';
 import { RECONCILE_TOOLS } from './reconcile-tools.js';
 import { READ_TOOLS } from './read-tools.js';
 import { LEASE_TOOLS } from './lease-tools.js';
@@ -117,6 +120,13 @@ export const RAW_TOOLS = [
             })
                 .optional()
                 .describe("Present ONLY when `sessions` is empty: the same answer as `why`, executable. `command` is the LITERAL command to run, sourced from this project's own package.json scripts and lockfile — it is absent, never guessed, when the project declares no dev script. `action` is one of daemon_split | start_dev_server | run_init | open_app | reopen_app. `daemon_split` outranks the rest and means the app IS running and instrumented, on a DIFFERENT daemon than the one you are attached to — do not start or re-init anything, read `reason`."),
+            lastKnown: z
+                .object({
+                sessionId: z.string(),
+                url: z.string(),
+            })
+                .optional()
+                .describe('Present ONLY when `sessions` is empty AND a tab was connected to this daemon earlier: the last sessionId and URL that tab was on when it disappeared. A route that 500s tears the page down and the SDK never reconnects — this is the last thing we knew, not a route-500 verdict. An empty list with no lastKnown is a tab that never arrived.'),
         },
         handler: async (deps) => {
             const provider = deps.realInput;
@@ -135,10 +145,14 @@ export const RAW_TOOLS = [
                 // The executable half. `why` is for the human reading the transcript; this is the one the
                 // agent acts on, so it never has to parse a paragraph to find a command inside it.
                 const next = deps.sessions.noSessionNextAction();
+                // The last tab, when one was here. Optional-call: test stubs of SessionManager predate it.
+                const known = deps.sessions.lastKnown?.();
+                const lastKnown = undefined === known ? undefined : { sessionId: known.id, url: known.url };
                 return {
                     sessions,
                     ...(why === undefined ? {} : { why }),
                     ...(next === undefined ? {} : { next_action: next }),
+                    ...(undefined === lastKnown ? {} : { lastKnown }),
                 };
             }
             return { sessions };
@@ -214,11 +228,15 @@ export const RAW_TOOLS = [
             note: z
                 .string()
                 .optional()
-                .describe('Present when a diff was computed over a capped tree — "unchanged" is then partial.'),
+                .describe('Why this result is not what it looks like. Four causes, all of which otherwise read as "the page is empty": a diff computed over a capped tree ("unchanged" is then partial); an interactive-mode tree emptied by leanness; a page whose elements all computed hidden; and an UNMOUNTED app, where the DOM under the scope holds almost nothing — that last one will not improve by waiting, so read reticle_console for an uncaught error instead.'),
             scopeMissing: z
                 .boolean()
                 .optional()
                 .describe('True when a scope was given but resolved to nothing — the tree is EMPTY on purpose, not because the page is empty. Do not read an absent element as absent from the page; re-check the scope.'),
+            growthWarning: z
+                .string()
+                .optional()
+                .describe('Present when this same scope was smaller moments ago — content likely arrived after your last look, and a presence/absence conclusion drawn from that earlier snapshot may have been taken mid-load. Re-check rather than trusting the earlier read.'),
         },
         // async so a synchronous resolve() failure (no session connected) surfaces as a REJECTED promise —
         // the handler contract every caller relies on — not a throw that escapes a direct invocation.
@@ -233,24 +251,24 @@ export const RAW_TOOLS = [
             return commandOrThrow(deps, resolved.id, ReticleCommand.SNAPSHOT, {
                 scope: args['scope'],
                 mode,
-            }).then((raw) => withSizeCost(noteEmptyLeanTree(applySnapshotDelta(raw, {
+            }).then((raw) => withSizeCost(noteUnmountedRoot(noteHiddenPage(noteEmptyLeanTree(applySnapshotDelta(raw, {
                 sessionId: resolved.id,
                 scope: asString(args['scope']) ?? '',
                 mode,
                 diff: true === args['diff'],
-            }, SNAPSHOT_CACHE), mode)));
+            }, SNAPSHOT_CACHE), mode), mode), mode)));
         },
     },
     {
         name: ReticleTool.QUERY,
         example: { by: 'testid', value: 'todo-list' },
-        description: `Find elements by Testing-Library semantics, INCLUDING open shadow roots — \`count_only:true\` gives just the count (~30x smaller); \`limit\` caps descriptors. Pass \`by\` (${QUERY_BY_LIST}) and \`value\` (the query string). Returns matching refs + descriptors + visibility. Pass \`attrs:["href"]\` to project attributes (link/image URLs) onto each match. Pass \`limit\` to cap descriptors (broad role queries can be large) or \`count_only:true\` for just the match count — both cut tokens. On zero matches, also returns hint:{ route, presentRegions[], knownEmptyState } so you can distinguish an empty state from a missing element WITHOUT taking a snapshot. ASKING SEVERAL QUESTIONS ABOUT THE PAGE? One reticle_snapshot answers them all at once — a run of queries costs a round trip each and returns what the snapshot already held.`,
+        description: `Find elements by Testing-Library semantics, INCLUDING open shadow roots — \`count_only:true\` gives just the count (~30x smaller); \`limit\` caps descriptors. Pass \`by\` (${QUERY_BY_LIST}) and \`value\` (the query string). Returns matching refs + descriptors + visibility. Pass \`attrs:["href"]\` to project attributes (link/image URLs) onto each match. Pass \`limit\` to cap descriptors (broad role queries can be large) or \`count_only:true\` for just the match count — both cut tokens. On zero matches, also returns hint:{ route, presentRegions[], knownEmptyState, nameNearMiss[] } so you can distinguish an empty state from a missing element WITHOUT taking a snapshot — nameNearMiss carries the labels that role really has when an exact role+name query just missed. ASKING SEVERAL QUESTIONS ABOUT THE PAGE? One reticle_snapshot answers them all at once — a run of queries costs a round trip each and returns what the snapshot already held.`,
         inputSchema: {
             // Constrained to the enum, NOT z.string(). A free string let `by:'css'` through to the
             // browser's `default: return []`, so an unsupported strategy answered "0 matches" — which
             // reads as "the element is not on the page". Measured on a live page: by:'css' value:'body'
             // returned count 0. A false negative is the one answer this product must never invent.
-            by: queryByEnum.optional().describe(`Query strategy: ${QUERY_BY_LIST}`),
+            by: queryByEnum.optional().describe('Query strategy.'),
             value: z
                 .string()
                 .optional()
@@ -280,12 +298,15 @@ export const RAW_TOOLS = [
                 .describe('Return just { count } (no element descriptors) — use when you only need "how many match?" and not their refs.'),
             // The predicate's spelling, accepted as an alias for by/value so the shape an agent learns from
             // act_and_wait/assert also works here. See query-shape.ts.
-            testid: z.string().optional().describe('Alias for by="testid" value=… (predicate spelling).'),
-            text: z.string().optional().describe('Alias for by="text" value=… (predicate spelling).'),
-            role: z.string().optional().describe('Alias for by="role" value=… (predicate spelling).'),
-            label: z.string().optional().describe('Alias for by="label" value=… (predicate spelling).'),
-            placeholder: z.string().optional().describe('Alias for by="placeholder" value=… .'),
-            alt: z.string().optional().describe('Alias for by="alt" value=… (predicate spelling).'),
+            // Six copies of one sentence, re-sent every turn. The parameter NAME already says which
+            // strategy it selects, and they sit in a block together, so each only has to say it is the
+            // predicate spelling of by/value.
+            testid: z.string().optional().describe(QUERY_ALIAS),
+            text: z.string().optional().describe(QUERY_ALIAS),
+            role: z.string().optional().describe(QUERY_ALIAS),
+            label: z.string().optional().describe(QUERY_ALIAS),
+            placeholder: z.string().optional().describe(QUERY_ALIAS),
+            alt: z.string().optional().describe(QUERY_ALIAS),
             ...sessionIdShape,
         },
         outputSchema: {
@@ -355,6 +376,12 @@ export const RAW_TOOLS = [
                     .passthrough()
                     .optional()
                     .describe("Present when a TEXT search missed but the string IS on the page, split across this container's children. Retry as { scope: <ref>, self: true } — no text query can match a string no single element owns."),
+                // Declared here for the same reason presentRegions had to be: the browser emits it, and an
+                // undeclared field is stripped from structuredContent without a word.
+                nameNearMiss: z
+                    .array(z.string())
+                    .optional()
+                    .describe('Present when a ROLE+NAME search missed and that role DOES carry a nearly-matching name — role+name is exact, so "Mesh" does not find "2 Mesh". Retry with one of these spellings; no snapshot needed.'),
             })
                 .optional()
                 .describe('Present only on zero matches — tells you what IS on the page so you can diagnose the miss.'),
@@ -516,6 +543,7 @@ export const RAW_TOOLS = [
     ...BROWSER_TOOLS,
     ...ACT_TOOLS,
     ...OBSERVE_TOOLS,
+    ...LINEAGE_TOOLS,
     ...READ_TOOLS,
     ...LEASE_TOOLS,
     // reticle_feedback — the agent reports that RETICLE failed (not that the app did). See feedback-tools.ts.
@@ -627,4 +655,85 @@ function noteEmptyLeanTree(result, mode) {
             `by testid rather than by role.`,
     };
 }
+/**
+ * An empty tree on a page full of elements is the same claim, from the other cause.
+ *
+ * `noteEmptyLeanTree` covers leanness and returns early for every other mode, so a `full` snapshot
+ * that comes back `{ tree: "", nodes: 0 }` says nothing at all — and that is the shape #672 was
+ * reported as: 44 buttons and 12 textboxes on the page, every one computing hidden, both modes
+ * empty. The reporter spent about six tool calls and a large console dump establishing the page was
+ * fine and the snapshot was wrong, then drove the flow off `reticle_query` refs, which is a
+ * workaround no tool description mentions.
+ *
+ * So the note names the count, says plainly that this is not an empty page, and hands over the path
+ * that does work. It does NOT diagnose why the page is hidden: the walk knows what it skipped and
+ * cannot know why, and a note that guessed would be the same kind of overconfident answer as the
+ * empty tree it replaces.
+ */
+/**
+ * How much DOM there is under the mount container, when the tree is empty and nothing was skipped.
+ *
+ * A handful of elements is a container with nothing in it. React's own root div counts as one, and a
+ * wrapper or two is ordinary, so this is deliberately not `=== 0`.
+ */
+const UNMOUNTED_ROOT_MAX_ELEMENTS = 3;
+/**
+ * The third cause of an empty tree, and the one the walk cannot see: the app is not mounted.
+ *
+ * Reported from the field with the react-three-fiber crash. The source-mapping stamp threw inside
+ * R3F's commit phase, React unmounted the entire tree, and the page went white — and the snapshot
+ * answered `{ tree: "", nodes: 0 }`, which is also what a page that has not rendered yet answers.
+ * The reporter spent a diagnosis pass separating the two, and said that detecting a dead root would
+ * have pointed straight at the cause.
+ *
+ * The other two notes here explain an empty tree by what the WALK passed over. This one cannot: a
+ * walk that visited nothing has nothing to have skipped. It reads the DOM count instead, which is
+ * why the browser now reports it, and it fires only when the skip counts are silent — a page whose
+ * elements were all hidden has plenty of DOM and belongs to `noteHiddenPage`.
+ *
+ * Like both of its neighbours it names a fact and hands over the next read, and does not diagnose:
+ * "not mounted" is certain from the count, WHY is not, and the console is where the answer is.
+ */
+function noteUnmountedRoot(result, mode) {
+    if (SnapshotMode.STATUS === mode)
+        return result;
+    const row = asRecord(result);
+    if (0 !== asNumber(row['nodes']))
+        return result;
+    if (row['note'] !== undefined)
+        return result;
+    const elements = asNumber(row['domElements']);
+    if (elements === undefined || elements > UNMOUNTED_ROOT_MAX_ELEMENTS)
+        return result;
+    return {
+        ...row,
+        note: `the tree is empty because there is almost nothing in the DOM: ${String(elements)} ` +
+            `element(s) under this scope. That is a mount container with nothing rendered into it, not a ` +
+            `page whose contents were skipped — so the app is UNMOUNTED rather than slow, and waiting ` +
+            `will not change it. An app that was rendering and then stopped has usually thrown: read ` +
+            `reticle_console for an uncaught error, and check anything that runs inside a framework ` +
+            `commit phase. If the app has genuinely not started yet, load it and snapshot again.`,
+    };
+}
+function noteHiddenPage(result, mode) {
+    if (SnapshotMode.STATUS === mode)
+        return result;
+    const row = asRecord(result);
+    if (0 !== asNumber(row['nodes']))
+        return result;
+    // A note already there is the more specific one (leanness), and two explanations for one empty
+    // tree is worse than the better of them alone.
+    if (row['note'] !== undefined)
+        return result;
+    const skipped = asNumber(row['hiddenSkipped']) ?? 0;
+    if (0 === skipped)
+        return result;
+    return {
+        ...row,
+        note: `this is NOT an empty page: ${String(skipped)} subtree(s) were skipped because their root ` +
+            `computed hidden (aria-hidden, the hidden attribute, or display:none), which is what left the ` +
+            `tree empty. If the page is plainly rendered, the visibility computation is the thing that is ` +
+            `wrong rather than the app — drive it by reticle_query refs, which do not depend on this walk.`,
+    };
+}
 export const TOOLS = applyMerges(RAW_TOOLS, MERGE_PLANS, RETIRED_FROM_SURFACE);

package/dist/tools/verify-next-baton.d.ts

@@ -29,7 +29,7 @@
 export declare const SUPPRESS_VERIFY_NEXT_ENV = "RETICLE_SUPPRESS_VERIFY_NEXT";
 /** What the agent must supply itself. Phrased as an instruction so it cannot be sent verbatim. */
 export declare const UNTIL_PLACEHOLDER = "<name the consequence this action causes>";
-export interface VerifyNextBaton {
+interface VerifyNextBaton {
     /** The fact that produced this, in the agent's own terms. */
     why: string;
     /** A call, ready to make once `until` is filled in. */
@@ -51,3 +51,4 @@ export declare function verifyNextBaton(prose: string, lastAct: {
     action?: string | undefined;
     ref?: string | undefined;
 }): VerifyNextBaton;
+export {};

package/dist/update/sdk-sync.d.ts

@@ -11,7 +11,7 @@
  * stale registry cache and reinstall the skew being fixed. Measured once as pnpm taking 2.2.1 while
  * npm took 2.3.0 in the next project over.
  */
-import { type PackageManager } from '../init/detect.js';
+import { type PackageManager } from '@reticlehq/init';
 export { reticleDepsOf } from './reticle-deps.js';
 /** The install to run, or null when this project has nothing of ours to sync. */
 export declare function sdkSyncCommand(pm: PackageManager, packages: readonly string[], version: string): {