@reticlehq/server 2.11.0 → 2.13.0

package/dist/tools/tool-surface.js

@@ -70,6 +70,45 @@ export const TOOL_SURFACE = {
      * supplies the evidence the surface would otherwise have to go and find.
      */
     VERIFY: 'verify',
+    /**
+     * EXPERIMENTAL, opt-in, and UNDER MEASUREMENT. Not a recommendation, and not on a path to becoming
+     * the default until it has a number of its own.
+     *
+     * It exists because of the finding recorded on VERIFY above, read forwards instead of backwards.
+     * That surface cut the bill 37% and TRIPLED false alarms, and the five new false alarms were not
+     * scattered: every one of them was a defect whose evidence lives in `reticle_state`,
+     * `reticle_network` or `reticle_observe`. So the token saving and the accuracy loss came from two
+     * different cuts, and only one of them has to be paid for. `lean` keeps every observation tool and
+     * cuts the rest.
+     *
+     * What stays, and why each one is not a candidate for removal:
+     *   SNAPSHOT / QUERY   look. Without them the agent cannot name an element it did not already know.
+     *   STATE / NETWORK / CONSOLE / OBSERVE   the four evidence tools. Dropping these is the MEASURED
+     *                      cause of the tripled false-alarm rate. They are the point of the profile.
+     *   ACT_AND_WAIT       the only tool that acts AND returns a verdict. Omitting `until` makes it
+     *                      act-then-settle, which is what `reticle_act` does, so `act` is redundant here.
+     *   ASSERT             the only way to get a verdict WITHOUT acting. `act_and_wait` requires an
+     *                      `action`, so this is a capability it genuinely cannot express, not a synonym.
+     *
+     * What goes, and what it costs (one `reticle_run` hop each — `unadvertisedToolHelp` hands the agent
+     * the exact call, so a dropped name never comes back as "not found"):
+     *   ACT                subsumed: `act_and_wait` with `until` omitted is act-then-settle.
+     *   WAIT_FOR           subsumed: `act_and_wait { until }` takes the same PredicateSchema.
+     *   ACT_SEQUENCE       batching is a cost optimisation on top of a surface built to be cheap.
+     *   NAVIGATE           once per run, not once per turn — the wrong thing to pay for every turn.
+     *   SESSIONS           the CLI answers this (`reticle status`) without spending any turn budget.
+     *   INSPECT            fix-side, not verdict-side: it is called once a bug is FOUND, so its hop is
+     *                      paid once per finding rather than once per turn. Nothing else maps a node to
+     *                      a source file, which is why it is a hop and not a deletion.
+     *   SESSION            the lease block and the pause hint name it in prose, which is what made it
+     *                      load-bearing on the default surface. Under a trimmed surface the
+     *                      unadvertised-tool help turns that into a working `reticle_run` call.
+     *   FEEDBACK           the one drop with a KNOWN CEILING: an unadvertised feedback channel collects
+     *                      little to nothing, so a long-lived profile must not ship without it. Acceptable
+     *                      only because this profile is opt-in and short-lived by construction; if it
+     *                      ever stops being an experiment, feedback comes back first.
+     */
+    LEAN: 'lean',
 };
 /**
  * The switch that turns on the full, output-schema-carrying surface. A boolean, not a menu.
@@ -79,7 +118,7 @@ export const TOOL_SURFACE = {
  */
 export const ADVERTISE_ALL_ENV = 'RETICLE_ADVERTISE_ALL_TOOLS';
 /** Opt into the smallest verdict-capable surface. Read by the DAEMON at startup, like the others. */
-export const VERIFY_SURFACE_ENV = 'RETICLE_VERIFY_SURFACE';
+const VERIFY_SURFACE_ENV = 'RETICLE_VERIFY_SURFACE';
 /**
  * The retired setting, still read so nobody's shell profile breaks.
  *
@@ -185,6 +224,17 @@ export const CORE_TOOL_NAMES = new Set([
  * 48 by itself can push a user's other servers out or be dropped wholesale. The budget is a count,
  * so no amount of trimming parameter prose buys anything back — only advertising fewer names does.
  *
+ * That is true of the COUNT cap and false of everything else, which is worth separating here before
+ * somebody reads it as "prose is free". Measured against two competitor MCP servers on the same
+ * agent loop: this server advertises the FEWEST tools of the three and ships the HEAVIEST schema
+ * block, and 83% of that weight is parameter descriptions, not tool descriptions. The block is
+ * re-sent every turn, so it is multiplied by turn count before one byte of evidence is counted, and
+ * it was most of the gap in that run.
+ *
+ * Which does NOT license trimming by eye. Those descriptions are what make a tool get called
+ * correctly, and one malformed call costs a whole extra turn — more than the bytes saved. The
+ * outcome to measure is turn count and error rate, not size.
+ *
  * Everything omitted stays in the registry, stays catalogued by `reticle_tools`, and stays callable
  * by name through `reticle_run { tool, args }`. The cost is one discovery hop on the cold tail, which
  * is the same trade the default surface has always made, applied one level further out.
@@ -206,6 +256,13 @@ export const EXTENDED_TOOL_NAMES = new Set([
     ReticleTool.CAPABILITIES,
     ReticleTool.FLOW_SAVE,
     ReticleTool.FLOW_REPLAY,
+    // New and unproven, so it does not take a default-surface slot under the cap. Same terms the
+    // capabilities demotion set: reachable in one reticle_run hop by any agent that wants it.
+    ReticleTool.INTENT,
+    // Same terms again, plus one argument specific to it: its caller is BY CONSTRUCTION an agent that
+    // just lost its context and is re-reading the tool list, so the discovery hop it costs is a call
+    // that caller was already going to make. See context-tools.ts for the full argument.
+    ReticleTool.CONTEXT,
     ReticleTool.RECORD,
     ReticleTool.SCREENSHOT,
     ReticleTool.VISUAL_DIFF,
@@ -220,7 +277,53 @@ export const EXTENDED_TOOL_NAMES = new Set([
  * everything else. `act_and_wait` can resolve its own target, so no query tool is needed to name an
  * element — that round trip was half the token cost of a verification.
  */
-export const VERIFY_TOOL_NAMES = new Set([ReticleTool.ACT_AND_WAIT]);
+const VERIFY_TOOL_NAMES = new Set([ReticleTool.ACT_AND_WAIT]);
+/**
+ * The lean surface: look, observe, act-with-a-verdict, assert. Pinned by lean-surface.test.ts,
+ * because an experiment whose independent variable drifts mid-flight measures nothing. Every
+ * inclusion and every exclusion is argued at TOOL_SURFACE.LEAN.
+ *
+ * ## MEASURED: it is cheaper and less correct. Do not promote it to the default.
+ *
+ * Run as its own arm of the fix-and-verify benchmark — same five bugs, same model, same budget, the
+ * full surface as its control:
+ *
+ * | | full surface | lean |
+ * |---|---|---|
+ * | bugs fixed | **5/5** | **3/5** |
+ * | FALSE GREENS | **0** | **1** |
+ *
+ * The false green is the finding, and it is the first this benchmark has ever produced. On
+ * `broken-form-validation` the lean agent finished in SIX turns and 62k tokens — the cheapest cell
+ * of the whole run, a fifth of what the full surface spent — edited the file, took one snapshot,
+ * and ended with a hypothetical walkthrough: "Enter spaces + valid name -> spaces are trimmed,
+ * valid part is used. VERDICT: FIXED". The submit button was still enabled for a whitespace-only
+ * service. It reasoned about what its own code would now do instead of driving it, which is exactly
+ * the failure this product exists to catch, produced by our own surface.
+ *
+ * The other loss has the same root from the other side. On `cross-component-regression` the agent
+ * called `reticle_tools` three times and `reticle_run` eight, saying "since Reticle isn't
+ * connecting, let me see what reticle_tools offers" — it spent the run hunting for capabilities
+ * this surface does not advertise instead of using them, and never fixed the bug.
+ *
+ * That is the same result the `verify` surface already recorded — dropping the observation tools
+ * TRIPLED false alarms — arriving from the other direction: strip the surface and the agent stops
+ * verifying, then claims anyway. The known ceiling written here was that `reticle_feedback` goes
+ * uncollected. This is a bigger one and it was not predicted.
+ *
+ * It stays opt-in and it stays measured. The one thing it genuinely bought — the ceiling-bound cell
+ * halved, 30 turns to 14 — is not worth a verdict that lies, because the product is the verdict.
+ */
+export const LEAN_TOOL_NAMES = new Set([
+    ReticleTool.SNAPSHOT,
+    ReticleTool.QUERY,
+    ReticleTool.ACT_AND_WAIT,
+    ReticleTool.ASSERT,
+    ReticleTool.OBSERVE,
+    ReticleTool.NETWORK,
+    ReticleTool.CONSOLE,
+    ReticleTool.STATE,
+]);
 /** Is the truthy form of a boolean env var set? `1`, `true`, `yes` — anything else is off. */
 function envFlagOn(raw) {
     if (raw === undefined)
@@ -235,6 +338,8 @@ function envFlagOn(raw) {
  * switch decides, and the retired setting is honoured last so an old shell profile still works.
  */
 export function resolveToolSurface(explicit) {
+    if (explicit === TOOL_SURFACE.LEAN)
+        return TOOL_SURFACE.LEAN;
     if (explicit === TOOL_SURFACE.VERIFY)
         return TOOL_SURFACE.VERIFY;
     if (explicit === TOOL_SURFACE.ALL)
@@ -244,6 +349,11 @@ export function resolveToolSurface(explicit) {
     const retiredExplicit = explicit === undefined ? undefined : RETIRED_PROFILE_VALUES[explicit];
     if (retiredExplicit !== undefined)
         return retiredExplicit;
+    // The one LIVE value of the otherwise-retired setting. It rides there rather than on a switch of
+    // its own because the experiment is an A/B between two surfaces, and a boolean cannot name an arm.
+    if (TOOL_SURFACE.LEAN === process.env[TOOL_PROFILE_ENV]?.trim().toLowerCase()) {
+        return TOOL_SURFACE.LEAN;
+    }
     if (envFlagOn(process.env[VERIFY_SURFACE_ENV]))
         return TOOL_SURFACE.VERIFY;
     if (envFlagOn(process.env[ADVERTISE_ALL_ENV]))
@@ -262,6 +372,14 @@ export function resolveToolSurface(explicit) {
  */
 export function describeToolSurface(active, requested) {
     const retired = requested ?? process.env[TOOL_PROFILE_ENV];
+    // `lean` is the one value of this setting that is NOT retired. Reporting it as retired would tell
+    // an agent its arm did not take, which on an A/B is worse than saying nothing.
+    if (TOOL_SURFACE.LEAN === active) {
+        return {
+            active,
+            source: `${TOOL_PROFILE_ENV}=${TOOL_SURFACE.LEAN} — an EXPERIMENTAL surface under measurement; unadvertised tools stay callable via ${ReticleTool.RUN}`,
+        };
+    }
     if (retired !== undefined && retired in RETIRED_PROFILE_VALUES) {
         return {
             active,
@@ -293,6 +411,8 @@ export function filterTools(tools, surface) {
     // interesting thing about the `core` PROFILE, whose only distinction was a second name for this.
     if (surface === TOOL_SURFACE.VERIFY)
         return tools.filter((t) => VERIFY_TOOL_NAMES.has(t.name));
+    if (surface === TOOL_SURFACE.LEAN)
+        return tools.filter((t) => LEAN_TOOL_NAMES.has(t.name));
     if (surface === TOOL_SURFACE.DEFAULT)
         return tools.filter((t) => CORE_TOOL_NAMES.has(t.name));
     // `all` is the extended surface, not the whole registry — the cap is a hard budget shared with

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

@@ -8,6 +8,25 @@ export declare function parseInteractive(tree: string): InteractiveItem[];
 export declare function asString(value: unknown): string | undefined;
 export declare function asNumber(value: unknown): number | undefined;
 export declare function asRecord(value: unknown): Record<string, unknown>;
+/**
+ * The session this call is aimed at: a top-level `sessionId`, or the same key on sequence steps.
+ *
+ * `reticle_act_sequence` describes each step as equivalent to one `reticle_act`, so an agent that
+ * learned the escape hatch on the single-action tool puts `sessionId` on the step. Reading only the
+ * top-level key then auto-selects a different tab, the step refs miss, and the refusal reads as a
+ * stale ref — a confident diagnosis of the wrong thing. Top-level still wins when both are given.
+ *
+ * Mixed step ids refuse rather than pick: two named tabs is a guess we will not make.
+ */
+export declare function sessionIdFromArgs(args: Record<string, unknown>): string | undefined;
+/**
+ * The ref this call is about to spend: a top-level `ref`, or the first sequence step's.
+ *
+ * Wrong-tab refusal keys off this. A sequence that only carries refs inside `steps` used to look
+ * like a call with no ref, so auto-selection could pick a different tab and the miss was blamed
+ * on the DOM.
+ */
+export declare function spentRefFromArgs(args: Record<string, unknown>): string | undefined;
 /**
  * A `{ file, line }` source location off an untrusted result payload, or undefined.
  *

package/dist/tools/tools-helpers.js

@@ -19,6 +19,52 @@ export function asNumber(value) {
 export function asRecord(value) {
     return 'object' === typeof value && value !== null ? value : {};
 }
+/**
+ * The session this call is aimed at: a top-level `sessionId`, or the same key on sequence steps.
+ *
+ * `reticle_act_sequence` describes each step as equivalent to one `reticle_act`, so an agent that
+ * learned the escape hatch on the single-action tool puts `sessionId` on the step. Reading only the
+ * top-level key then auto-selects a different tab, the step refs miss, and the refusal reads as a
+ * stale ref — a confident diagnosis of the wrong thing. Top-level still wins when both are given.
+ *
+ * Mixed step ids refuse rather than pick: two named tabs is a guess we will not make.
+ */
+export function sessionIdFromArgs(args) {
+    const top = asString(args['sessionId']);
+    if (top !== undefined)
+        return top;
+    const steps = args['steps'];
+    if (!Array.isArray(steps))
+        return undefined;
+    let found;
+    for (const raw of steps) {
+        const id = asString(asRecord(raw)['sessionId']);
+        if (id === undefined)
+            continue;
+        if (found !== undefined && found !== id) {
+            throw new Error(`reticle_act_sequence steps name different sessionIds ('${found}' and '${id}'). ` +
+                'Pass one sessionId at the top level to target a tab. Nothing was acted on.');
+        }
+        found = id;
+    }
+    return found;
+}
+/**
+ * The ref this call is about to spend: a top-level `ref`, or the first sequence step's.
+ *
+ * Wrong-tab refusal keys off this. A sequence that only carries refs inside `steps` used to look
+ * like a call with no ref, so auto-selection could pick a different tab and the miss was blamed
+ * on the DOM.
+ */
+export function spentRefFromArgs(args) {
+    const top = asString(args['ref']);
+    if (top !== undefined)
+        return top;
+    const steps = args['steps'];
+    if (!Array.isArray(steps) || 0 === steps.length)
+        return undefined;
+    return asString(asRecord(steps[0])['ref']);
+}
 /**
  * A `{ file, line }` source location off an untrusted result payload, or undefined.
  *

package/dist/tools/tools.d.ts

@@ -1,6 +1,8 @@
 import { type ToolDef } from './tool-kit.js';
 import { type MergePlan } from './merge-tools.js';
 export type { ToolDef, ToolDeps } from './tool-kit.js';
+/** Every handler, including tools retired from the advertised MCP surface. */
+export declare const RAW_TOOLS: ToolDef[];
 /**
  * surface consolidation. Tool defs are re-sent EVERY turn, so the advertised count is a per-turn
  * tax multiplied by loop length. Sibling families collapse into one action-dispatched tool; the member

package/dist/tools/tools.js

@@ -3,7 +3,8 @@ import { NoSessionAction, QueryBy, ReticleCommand, SnapshotMode } from '@reticle
 import { ReticleTool } from './tool-names.js';
 import { withSizeCost } from '../session/output-budget.js';
 import { applySnapshotDelta, SnapshotCache } from './snapshot-delta.js';
-import { asString, asNumber } from './tools-helpers.js';
+import { asRecord, asString, asNumber } from './tools-helpers.js';
+import { countSchema } from './numeric-bounds.js';
 import { normalizeQueryArgs } from './query-shape.js';
 import { paginateQueryResult } from './query-paginate.js';
 /**
@@ -21,11 +22,14 @@ import { CONTRACT_TOOLS } from './contract-tools.js';
 import { DOMAIN_TOOLS } from '../domain/domain-tools.js';
 import { BROWSER_TOOLS } from './browser-tools.js';
 import { FLOW_TOOLS } from '../flows/flow-tools.js';
+import { INTENT_TOOLS } from '../intent/intent-tools.js';
+import { CONTEXT_TOOLS } from '../runs/context-tools.js';
 import { PROJECT_TOOLS } from '../project/project-tools.js';
+import { MEMORY_TOOLS } from '../memory/memory-tools.js';
 import { RUN_TOOLS } from '../runs/run-tools.js';
 import { VISUAL_TOOLS } from '../visual/visual-tools.js';
 import { AFFECTED_TOOLS } from '../flows/affected-tools.js';
-import { COVERAGE_TOOLS } from './coverage-tools.js';
+import { buildCoverageTools } from './coverage-tools.js';
 import { VERIFY_CHANGE_TOOLS } from '../flows/verify-change-tools.js';
 import { CRAWL_TOOLS } from '../crawl/crawl-tools.js';
 import { SCROLL_TOOLS } from '../input/scroll-tools.js';
@@ -44,10 +48,11 @@ import { LEASE_TOOLS } from './lease-tools.js';
 import { FEEDBACK_TOOLS } from './feedback-tools.js';
 /** Per-server last-snapshot cache backing reticle_snapshot's diff:true delta mode (route-invalidated). */
 const SNAPSHOT_CACHE = new SnapshotCache();
-const RAW_TOOLS = [
+/** Every handler, including tools retired from the advertised MCP surface. */
+export const RAW_TOOLS = [
     {
         name: ReticleTool.SESSIONS,
-        description: 'List connected browser sessions (tab url/title, sessionId, last-seen, health: hidden/focused/throttled, and `realInputAvailable` — true when native CDP/launched real input is driving this tab), plus a `recommendation` pointing to `reticle drive` when a tab is hidden/throttled and may be un-scriptable from here.',
+        description: 'List connected browser sessions (tab url/title, sessionId, last-seen, health: hidden/focused/throttled, and `realInputAvailable` — true when native CDP/launched real input is driving this tab), plus a `recommendation` naming the in-protocol escape hatch (`reticle_run { tool: "reticle_lease" }`, with `reticle drive` as the human-side equivalent) when a tab is hidden/throttled and may be un-scriptable from here.',
         inputSchema: {},
         outputSchema: {
             sessions: z
@@ -61,6 +66,10 @@ const RAW_TOOLS = [
                 title: z.string().optional(),
                 adapters: z.array(z.string()),
                 hasCapabilities: z.boolean(),
+                runtime: z
+                    .string()
+                    .optional()
+                    .describe("Which shell answered: web, electron or tauri. Absent on an SDK too old to report one — never defaulted, because a browser tab and a desktop window on the same url are otherwise indistinguishable and only one of them has the app's IPC."),
                 versionSkew: z
                     .string()
                     .optional()
@@ -73,9 +82,26 @@ const RAW_TOOLS = [
                 leased: z.boolean().optional(),
                 stale: z.boolean().optional(),
                 cleanup_suggestion: z.string().optional(),
+                unresponsive: z
+                    .literal(true)
+                    .optional()
+                    .describe('Present only when this tab is attached but has stopped answering commands: every call against it will time out. The other health fields still look fine, which is what makes this state invisible without the flag.'),
+                unresponsive_suggestion: z.string().optional(),
                 pendingMarks: z.number().optional(),
                 review_suggestion: z.string().optional(),
                 recommendation: z.string().optional(),
+                // Attached by SessionManager.list() (#117): whether this tab ever dropped and came back,
+                // how often, and how long the last drop lasted. Undeclared here, a validating client
+                // stripped the outage history while the row still looked complete — a verdict over a
+                // window with a four-second blind gap read as trustworthy.
+                attachment: z
+                    .object({
+                    connectedSinceMs: z.number(),
+                    outages: z.number(),
+                    lastOutage: z.object({ startedMs: z.number(), durationMs: z.number() }).optional(),
+                })
+                    .optional()
+                    .describe('Present only when this tab has dropped and reconnected at least once: how long it has been attached in total, how many outages occurred, and when the last one started and how long it lasted. A verdict over this window spans a gap where nothing was observed.'),
             }))
                 .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
@@ -90,7 +116,7 @@ const RAW_TOOLS = [
                 reason: z.string(),
             })
                 .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 start_dev_server | run_init | open_app | reopen_app."),
+                .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`."),
         },
         handler: async (deps) => {
             const provider = deps.realInput;
@@ -207,18 +233,18 @@ const RAW_TOOLS = [
             return commandOrThrow(deps, resolved.id, ReticleCommand.SNAPSHOT, {
                 scope: args['scope'],
                 mode,
-            }).then((raw) => withSizeCost(applySnapshotDelta(raw, {
+            }).then((raw) => withSizeCost(noteEmptyLeanTree(applySnapshotDelta(raw, {
                 sessionId: resolved.id,
                 scope: asString(args['scope']) ?? '',
                 mode,
                 diff: true === args['diff'],
-            }, SNAPSHOT_CACHE)));
+            }, SNAPSHOT_CACHE), 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.`,
+        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.`,
         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
@@ -245,9 +271,7 @@ const RAW_TOOLS = [
                 .array(z.string())
                 .optional()
                 .describe("Attribute names to return per match, e.g. ['href'] to inventory links or ['src'] for images. Absent attributes are omitted; credential-bearing names are redacted."),
-            limit: z
-                .number()
-                .nonnegative()
+            limit: countSchema
                 .optional()
                 .describe('Cap the returned descriptors to the first N (cuts tokens on broad queries). If more matched, the result carries total + truncated:true so the trim is never silent — narrow with name/scope.'),
             count_only: z
@@ -322,6 +346,15 @@ const RAW_TOOLS = [
                     .describe('Structural clusters on the page — what IS here, to diagnose the miss.'),
                 presentTestids: z.array(z.string()).optional(),
                 knownEmptyState: z.boolean(),
+                splitText: z
+                    .object({
+                    ref: z.string().optional(),
+                    role: z.string().optional(),
+                    name: z.string().optional(),
+                })
+                    .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."),
             })
                 .optional()
                 .describe('Present only on zero matches — tells you what IS on the page so you can diagnose the miss.'),
@@ -446,11 +479,14 @@ const RAW_TOOLS = [
     // reticle_capabilities (live | fromDisk) + reticle_contract_save. See contract-tools.ts.
     ...RECONCILE_TOOLS,
     ...CONTRACT_TOOLS,
+    ...INTENT_TOOLS,
+    ...CONTEXT_TOOLS,
     ...DOMAIN_TOOLS,
     // reticle_flow_save / reticle_flow_list / reticle_flow_load. See flow-tools.ts.
     ...FLOW_TOOLS,
     // reticle_project (read history + diff-vs-last) / reticle_run_record. See project-tools.ts.
     ...PROJECT_TOOLS,
+    ...MEMORY_TOOLS,
     // reticle_run_export — export the verification-run verdict artifact (.reticle/runs/). See run-tools.ts.
     ...RUN_TOOLS,
     // reticle_screenshot / reticle_visual_diff — opt-in, CDP-driven. See visual-tools.ts.
@@ -469,7 +505,9 @@ const RAW_TOOLS = [
     // reachable through reticle_run. See affected-tools.ts.
     ...AFFECTED_TOOLS,
     // reticle_coverage — which controls were driven vs never touched. Unadvertised; via reticle_run.
-    ...COVERAGE_TOOLS,
+    // The table is passed as a thunk so the coverage tool can report which of it was called without
+    // importing it back — see buildCoverageTools. Called from the handler, long after TOOLS exists.
+    ...buildCoverageTools(() => TOOLS.map((t) => t.name)),
     // reticle_verify_change — "did my change break anything" in one call. See verify-change-tools.ts.
     ...VERIFY_CHANGE_TOOLS,
     // Live-control: reticle_end_session / reticle_resume / reticle_messages. See live-control-tools.ts.
@@ -561,4 +599,32 @@ export const RETIRED_FROM_SURFACE = [
     ReticleTool.REFRESH, // absorbed into reticle_navigate { reload: true }
     ReticleTool.WAIT_READY, // server-internal: the first live call already blocks for the session
 ];
+/**
+ * An empty `interactive` tree is a claim, and it is usually the wrong one.
+ *
+ * `mode:"interactive"` filters on ARIA role, and a large share of production UI carries none. On
+ * MarkText — a shipped Electron editor — it returns NOTHING while `mode:"full"` returns 47 nodes,
+ * because its whole block picker is `<div>`s with no role, no testid and no pointer cursor. This
+ * tool's own description recommends the lean mode, so an agent takes the cheap look, is handed `""`,
+ * and reads it as an empty page. It is the one shape of answer this product must never invent.
+ *
+ * The browser counts what leanness passed over, so the tool can say which of the two it is.
+ */
+function noteEmptyLeanTree(result, mode) {
+    if (SnapshotMode.INTERACTIVE !== mode)
+        return result;
+    const row = asRecord(result);
+    if (0 !== asNumber(row['nodes']))
+        return result;
+    const skipped = asNumber(row['leanSkipped']) ?? 0;
+    if (0 === skipped)
+        return result;
+    return {
+        ...row,
+        note: `no element on this page carries an interactive ARIA role, so this mode found nothing — ` +
+            `${String(skipped)} element(s) were passed over for leanness and this is NOT an empty page. ` +
+            `Take reticle_snapshot { mode: "full" } instead; the controls here are addressed by text or ` +
+            `by testid rather than by role.`,
+    };
+}
 export const TOOLS = applyMerges(RAW_TOOLS, MERGE_PLANS, RETIRED_FROM_SURFACE);

package/dist/tools/unadvertised-help.js

@@ -1,10 +1,10 @@
 /**
  * What to say when an agent calls a real Reticle tool that this profile does not advertise.
  *
- * The default surface advertises 18 of 48 tools, and the extended one 30. That is deliberate — every
- * advertised tool's schema is re-sent on every turn, and editors budget MCP tools as a COUNT shared
- * across every connected server — and everything omitted stays fully callable through `reticle_run`,
- * which `surface-reachability.test.ts` guards.
+ * The default surface is the verify loop plus the two meta-tools; the extended one is larger but
+ * still capped. Counts live in `surface-sizes.test.ts` — restating them here is how they drift.
+ * Everything omitted stays fully callable through `reticle_run`, which `surface-reachability.test.ts`
+ * guards.
  *
  * The gap was in the ERROR. The MCP SDK answers `Tool <name> not found`, which is indistinguishable
  * from "this tool does not exist", so an agent that trusts it stops trying. Reported from a real

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

@@ -0,0 +1,53 @@
+/**
+ * The verdict nudge, as a call the agent can make rather than a sentence it has to translate.
+ *
+ * `verify_next` already fires when an agent has driven the page several times and asked for no
+ * verdict, which is the commonest shape of a wasted session: almost every verdict-less session in
+ * the field never called a verdict-producing tool once. What it carried was prose. Prose has to be
+ * turned back into a call, and the translation is exactly where the agent was already going wrong —
+ * `until` omitted, arguments flat instead of nested under `args`, a predicate written as a bare
+ * array.
+ *
+ * So it carries the call. `ref` and `action` come from the act that actually dispatched, so the
+ * suggestion is about the element the agent really touched rather than a worked example from a
+ * document. `until` is deliberately left as a placeholder the agent must replace: naming the
+ * consequence is the one part nothing but the agent can know, and filling it in with a guess would
+ * be Reticle inventing the assertion — the failure `no-fault` exists to prevent.
+ *
+ * Emitted only when there is a real call to suggest. A baton with nothing behind it is the router
+ * failure in miniature: an agent that follows a fabricated next step follows it confidently.
+ */
+/**
+ * Set to `1` to withhold the baton from tool results — the control arm of its A/B, and nothing else.
+ *
+ * A measurement flag, not a product setting: it is read at one call site, documented here, and named
+ * loudly enough that nobody sets it by accident. It exists because this feature has shipped, been
+ * declared the largest lever on whether a session verifies at all, and never been measured — and a
+ * control arm is the only way to tell "agents that see it verify" from "agents that were going to
+ * verify anyway also saw it".
+ */
+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 {
+    /** The fact that produced this, in the agent's own terms. */
+    why: string;
+    /** A call, ready to make once `until` is filled in. */
+    call?: {
+        tool: string;
+        args: Record<string, unknown>;
+    };
+    /** Where the argument shapes are stated, on disk and version-exact rather than on the web. */
+    docs?: string;
+}
+/**
+ * Build the baton from what the session actually did.
+ *
+ * `ref` absent means no act dispatched under a ref this session — a navigation, or a run that only
+ * read. There is then no honest call to name, so the prose stands alone rather than pointing at an
+ * element nobody touched.
+ */
+export declare function verifyNextBaton(prose: string, lastAct: {
+    action?: string | undefined;
+    ref?: string | undefined;
+}): VerifyNextBaton;

package/dist/tools/verify-next-baton.js

@@ -0,0 +1,52 @@
+/**
+ * The verdict nudge, as a call the agent can make rather than a sentence it has to translate.
+ *
+ * `verify_next` already fires when an agent has driven the page several times and asked for no
+ * verdict, which is the commonest shape of a wasted session: almost every verdict-less session in
+ * the field never called a verdict-producing tool once. What it carried was prose. Prose has to be
+ * turned back into a call, and the translation is exactly where the agent was already going wrong —
+ * `until` omitted, arguments flat instead of nested under `args`, a predicate written as a bare
+ * array.
+ *
+ * So it carries the call. `ref` and `action` come from the act that actually dispatched, so the
+ * suggestion is about the element the agent really touched rather than a worked example from a
+ * document. `until` is deliberately left as a placeholder the agent must replace: naming the
+ * consequence is the one part nothing but the agent can know, and filling it in with a guess would
+ * be Reticle inventing the assertion — the failure `no-fault` exists to prevent.
+ *
+ * Emitted only when there is a real call to suggest. A baton with nothing behind it is the router
+ * failure in miniature: an agent that follows a fabricated next step follows it confidently.
+ */
+import { ReticleTool } from './tool-names.js';
+/**
+ * Set to `1` to withhold the baton from tool results — the control arm of its A/B, and nothing else.
+ *
+ * A measurement flag, not a product setting: it is read at one call site, documented here, and named
+ * loudly enough that nobody sets it by accident. It exists because this feature has shipped, been
+ * declared the largest lever on whether a session verifies at all, and never been measured — and a
+ * control arm is the only way to tell "agents that see it verify" from "agents that were going to
+ * verify anyway also saw it".
+ */
+export 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 const UNTIL_PLACEHOLDER = '<name the consequence this action causes>';
+/**
+ * Build the baton from what the session actually did.
+ *
+ * `ref` absent means no act dispatched under a ref this session — a navigation, or a run that only
+ * read. There is then no honest call to name, so the prose stands alone rather than pointing at an
+ * element nobody touched.
+ */
+export function verifyNextBaton(prose, lastAct) {
+    const { ref, action } = lastAct;
+    if (ref === undefined || action === undefined)
+        return { why: prose };
+    return {
+        why: prose,
+        call: {
+            tool: ReticleTool.ACT_AND_WAIT,
+            args: { ref, action, until: { kind: 'text', value: UNTIL_PLACEHOLDER } },
+        },
+        docs: `reticle_tools { names: ["${ReticleTool.ACT_AND_WAIT}"] }`,
+    };
+}

package/dist/update/reticle-deps.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The `@reticlehq/*` packages a project actually declares.
+ *
+ * Shared by `reticle update` (which syncs them) and the version-skew remedy (which names them).
+ * Lives here, not in `init/`, so the daemon library path can read a package.json without pulling
+ * the installer in behind it.
+ */
+/** The Reticle packages this project declares, from either dependency section. */
+export declare function reticleDepsOf(pkgJson: unknown): string[];

package/dist/update/reticle-deps.js

@@ -0,0 +1,27 @@
+/**
+ * The `@reticlehq/*` packages a project actually declares.
+ *
+ * Shared by `reticle update` (which syncs them) and the version-skew remedy (which names them).
+ * Lives here, not in `init/`, so the daemon library path can read a package.json without pulling
+ * the installer in behind it.
+ */
+/** Everything we publish is scoped here. */
+const RETICLE_SCOPE = '@reticlehq/';
+/**
+ * The CLI. Never an app dependency: it carries the Node MCP server and `ws`, and putting it in a
+ * browser app's tree is what the retired `@reticlehq/core` umbrella got wrong.
+ */
+const SERVER_PACKAGE = '@reticlehq/server';
+function namesIn(section) {
+    if ('object' !== typeof section || null === section)
+        return [];
+    return Object.keys(section);
+}
+/** The Reticle packages this project declares, from either dependency section. */
+export function reticleDepsOf(pkgJson) {
+    if ('object' !== typeof pkgJson || null === pkgJson)
+        return [];
+    const manifest = pkgJson;
+    const declared = [...namesIn(manifest['dependencies']), ...namesIn(manifest['devDependencies'])];
+    return [...new Set(declared)].filter((name) => name.startsWith(RETICLE_SCOPE) && name !== SERVER_PACKAGE);
+}

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

@@ -12,8 +12,7 @@
  * npm took 2.3.0 in the next project over.
  */
 import { type PackageManager } from '../init/detect.js';
-/** The Reticle packages this project declares, from either dependency section. */
-export declare function reticleDepsOf(pkgJson: unknown): string[];
+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): {
     command: string;