@reticlehq/server 2.11.0 → 2.13.0

package/dist/tools/coverage-tools.js

@@ -1,5 +1,8 @@
 import { z } from 'zod';
 import { coverageRegressed, observabilityOf } from '../honesty/observability.js';
+import { foldFeatureCapture } from '../honesty/feature-capture.js';
+import { foldToolHitRate } from '../honesty/tool-hit-rate.js';
+import { allSessionIntents } from '../intent/open-intents.js';
 import { ReticleCommand, SnapshotMode } from '@reticlehq/core';
 import { ReticleTool } from './tool-names.js';
 import { asString } from './tools-helpers.js';
@@ -49,73 +52,124 @@ export function parseControls(tree) {
     }
     return controls;
 }
-export const COVERAGE_TOOLS = [
-    {
-        name: ReticleTool.COVERAGE,
-        description: 'Which interactive controls you have driven this session, and which you have NOT. Returns { total, exercised, untouched:[{ref,label}], alsoDroveGone? } over the controls currently on the page. Use it to decide whether verification is finished: an untouched list that still holds the controls your change affects means you are not done. This is about what you did not TOUCH — distinct from the `coverage` field on an action result, which reports what the layer could not SEE.',
-        example: {},
-        inputSchema: { ...sessionIdShape },
-        outputSchema: {
-            total: z.number(),
-            exercised: z.number(),
-            untouched: z.array(z.object({ ref: z.string(), label: z.string() })),
-            alsoDroveGone: z
-                .number()
-                .optional()
-                .describe('Controls you drove that are no longer on the page — usually because the action SUCCEEDED and removed them (archive/delete/submit/navigate). Counted separately so `exercised: 0` never appears immediately after real work.'),
-            instrumentationGaps: z
-                .array(z.unknown())
-                .optional()
-                .describe('What this app still cannot tell Reticle, as of your most recent verdict — each entry is { kind, missing, cost, fix, source?, ref? }. These are not controls you skipped; they are checks this app CANNOT answer until it is instrumented, so driving the untouched list will not close them. Apply each `fix` and re-verify: the gap disappears from this list when the app can answer, and every later verdict on this app gets stronger. OMITTED when nothing is missing.'),
-            unproven: z
-                .boolean()
-                .optional()
-                .describe('True when verification is NOT finished for a reason driving more controls cannot fix — instrumentationGaps is non-empty. Present only when true, so its absence is not a claim.'),
-            observability: z
-                .object({ driven: z.number(), observable: z.number(), percent: z.number().optional() })
-                .optional()
-                .describe('Of the controls you DROVE, how many Reticle could fully observe. `untouched` above is work left for you; this is work left in the APP, and driving more controls does not move it. `percent` is OMITTED when nothing was driven, because 0/0 is not 100%.'),
-            observabilityRegressed: z
-                .object({ was: z.number(), now: z.number() })
-                .optional()
-                .describe('This project has previously reached a HIGHER observability than this run did. Usually means an assertion or an instrumented path was removed — the cheapest way to stop a gap firing is to stop asserting the thing that revealed it. Present only when a drop is real and the run was large enough to compare.'),
-        },
-        handler: async (deps, args) => {
-            const sessionId = asString(args['sessionId']);
-            const session = deps.sessions.resolve(sessionId);
-            // INTERACTIVE mode is already the "controls only" view, so the denominator is the page's own
-            // notion of what can be driven rather than a second, drifting definition maintained here.
-            const result = await commandOrThrow(deps, sessionId, ReticleCommand.SNAPSHOT, {
-                mode: SnapshotMode.INTERACTIVE,
-            });
-            const tree = asString(result['tree']) ?? '';
-            // Matched by ref AND by label — see coverage-identity. A ref dies with the next re-render, so
-            // on a framework that replaces nodes this reported `exercised: 0` however much work was done.
-            // `droveGone` keeps the other honesty: archive/delete/submit remove their own control, so a
-            // drive that WORKED must not read as no coverage at all.
-            const { exercised, droveGone, untouched } = exercisedCount(parseControls(tree), session.actedRefs(), session.actedLabels());
-            // The other half of "am I done?". `untouched` answers what you did not DRIVE; this answers
-            // what this app cannot ANSWER, which no amount of further driving will change. Reporting the
-            // first without the second is how an agent finishes a pass believing it verified something the
-            // app was never able to confirm.
-            const gaps = session.gaps?.open() ?? [];
-            // The number, and the floor under it, together. A coverage figure that can only ever be
-            // reported and never contradicted is one an agent learns to satisfy rather than to earn.
-            const observability = observabilityOf(session.actedRefs(), gaps);
-            const best = await deps.project.bestObservability();
-            const regressed = coverageRegressed(best, observability);
-            if (observability.percent !== undefined) {
-                await deps.project.raiseObservability(observability.percent);
-            }
-            return {
-                total: parseControls(tree).length,
-                exercised,
-                untouched,
-                ...(droveGone > 0 ? { alsoDroveGone: droveGone } : {}),
-                ...(gaps.length > 0 ? { instrumentationGaps: gaps, unproven: true } : {}),
-                observability,
-                ...(regressed === undefined ? {} : { observabilityRegressed: regressed }),
-            };
+/**
+ * Build the coverage tool over the dispatchable tool table.
+ *
+ * The table arrives as a thunk rather than an import: `tools.ts` assembles it FROM this module, so
+ * importing it back would close a cycle whose failure mode is a load-order-dependent crash rather
+ * than an error anyone sees while writing it. The thunk is called inside the handler, long after the
+ * table exists. It carries the merged names — the ones `reticle_run` will actually accept — because
+ * a tool that merged into a parent is not something an agent can call or a maintainer can cut.
+ */
+export function buildCoverageTools(toolNames) {
+    return [
+        {
+            name: ReticleTool.COVERAGE,
+            description: 'Which interactive controls you have driven this session, and which you have NOT. Returns { total, exercised, untouched:[{ref,label}], alsoDroveGone? } over the controls currently on the page. Use it to decide whether verification is finished: an untouched list that still holds the controls your change affects means you are not done. This is about what you did not TOUCH — distinct from the `coverage` field on an action result, which reports what the layer could not SEE.',
+            example: {},
+            inputSchema: { ...sessionIdShape },
+            outputSchema: {
+                total: z.number(),
+                exercised: z.number(),
+                untouched: z.array(z.object({ ref: z.string(), label: z.string() })),
+                alsoDroveGone: z
+                    .number()
+                    .optional()
+                    .describe('Controls you drove that are no longer on the page — usually because the action SUCCEEDED and removed them (archive/delete/submit/navigate). Counted separately so `exercised: 0` never appears immediately after real work.'),
+                instrumentationGaps: z
+                    .array(z.unknown())
+                    .optional()
+                    .describe('What this app still cannot tell Reticle, as of your most recent verdict — each entry is { kind, missing, cost, fix, source?, ref? }. These are not controls you skipped; they are checks this app CANNOT answer until it is instrumented, so driving the untouched list will not close them. Apply each `fix` and re-verify: the gap disappears from this list when the app can answer, and every later verdict on this app gets stronger. OMITTED when nothing is missing.'),
+                unproven: z
+                    .boolean()
+                    .optional()
+                    .describe('True when verification is NOT finished for a reason driving more controls cannot fix — instrumentationGaps is non-empty. Present only when true, so its absence is not a claim.'),
+                observability: z
+                    .object({ driven: z.number(), observable: z.number(), percent: z.number().optional() })
+                    .optional()
+                    .describe('Of the controls you DROVE, how many Reticle could fully observe. `untouched` above is work left for you; this is work left in the APP, and driving more controls does not move it. `percent` is OMITTED when nothing was driven, because 0/0 is not 100%.'),
+                featureUse: z
+                    .object({
+                    observed: z.boolean(),
+                    truncated: z.boolean().optional(),
+                    context: z.unknown().optional(),
+                    intents: z.unknown().optional(),
+                    missed: z.unknown().optional(),
+                })
+                    .optional()
+                    .describe('Whether this session used `reticle_context` and `reticle_intent` at all, and what it cost when it did not: `context` counts the calls and what followed each one, `intents` the ledger, `missed` the verdicts drawn against an empty ledger and the reads that re-fetched a fact already established. `observed:false` means nothing was recorded for this session — NOT that nothing was used. An instrument for deciding whether those two features earn their place; nothing here is a fault of yours.'),
+                toolHitRate: z
+                    .object({
+                    observed: z.boolean(),
+                    cells: z.unknown().optional(),
+                    called: z.unknown().optional(),
+                    neverCalled: z.unknown().optional(),
+                })
+                    .optional()
+                    .describe('Which Reticle tools THIS session called, and how reachable each one was: `called` lists every tool with its call count, `neverCalled` the rest of the table, and both carry a `tier` — `default` (advertised to every agent), `extended` (advertised only on the full surface) or `run-only` (reachable solely by naming it to reticle_run). `cells` counts each tier on both sides. `observed:false` means nothing was recorded for this session, NOT that nothing was called. THREE LIMITS, all load-bearing: this is ONE session, so it is evidence about this run and is not a hit rate — a hit rate is a distribution over many sessions. A never-called tool is not a useless tool; one used once a month in an emergency looks identical here to one nobody has ever called, so frequency alone cannot decide a cut. And the counts describe how this run went, never how it should have gone — nothing here is a fault of yours.'),
+                observabilityRegressed: z
+                    .object({ was: z.number(), now: z.number() })
+                    .optional()
+                    .describe('This project has previously reached a HIGHER observability than this run did. Usually means an assertion or an instrumented path was removed — the cheapest way to stop a gap firing is to stop asserting the thing that revealed it. Present only when a drop is real and the run was large enough to compare.'),
+            },
+            handler: async (deps, args) => {
+                const sessionId = asString(args['sessionId']);
+                const session = deps.sessions.resolve(sessionId);
+                // INTERACTIVE mode is already the "controls only" view, so the denominator is the page's own
+                // notion of what can be driven rather than a second, drifting definition maintained here.
+                const result = await commandOrThrow(deps, sessionId, ReticleCommand.SNAPSHOT, {
+                    mode: SnapshotMode.INTERACTIVE,
+                });
+                const tree = asString(result['tree']) ?? '';
+                // Matched by ref AND by label — see coverage-identity. A ref dies with the next re-render, so
+                // on a framework that replaces nodes this reported `exercised: 0` however much work was done.
+                // `droveGone` keeps the other honesty: archive/delete/submit remove their own control, so a
+                // drive that WORKED must not read as no coverage at all.
+                const { exercised, droveGone, untouched } = exercisedCount(parseControls(tree), session.actedRefs(), session.actedLabels());
+                // The other half of "am I done?". `untouched` answers what you did not DRIVE; this answers
+                // what this app cannot ANSWER, which no amount of further driving will change. Reporting the
+                // first without the second is how an agent finishes a pass believing it verified something the
+                // app was never able to confirm.
+                const gaps = session.gaps?.open() ?? [];
+                // Folded here rather than given a tool of its own: this is already the "am I done, and what is
+                // this verdict worth" read, and a number nobody has a reason to ask for separately is one
+                // nobody ever sees. It is a fold over the journal and the intent ledger plus the one thing
+                // neither records — see honesty/feature-capture.ts.
+                const featureUse = foldFeatureCapture({
+                    calls: session.capture.calls(),
+                    dropped: session.capture.dropped,
+                    actions: await session.readJournalActions(),
+                    intents: await allSessionIntents(deps, sessionId),
+                    finalActions: session.actionCount,
+                });
+                // Same fold, same reason, one level out: which of the whole tool table this session reached
+                // for, crossed with how reachable each name was. See honesty/tool-hit-rate.ts for what it can
+                // and cannot establish — the limits matter more than usual, because this is the number a
+                // decision to DELETE tools would be made on.
+                const toolHitRate = foldToolHitRate({
+                    calls: session.capture?.toolCalls(),
+                    allTools: toolNames(),
+                });
+                // The number, and the floor under it, together. A coverage figure that can only ever be
+                // reported and never contradicted is one an agent learns to satisfy rather than to earn.
+                const observability = observabilityOf(session.actedRefs(), gaps);
+                const best = await deps.project.bestObservability();
+                const regressed = coverageRegressed(best, observability);
+                if (observability.percent !== undefined) {
+                    await deps.project.raiseObservability(observability.percent);
+                }
+                return {
+                    total: parseControls(tree).length,
+                    exercised,
+                    untouched,
+                    ...(droveGone > 0 ? { alsoDroveGone: droveGone } : {}),
+                    ...(gaps.length > 0 ? { instrumentationGaps: gaps, unproven: true } : {}),
+                    observability,
+                    ...(regressed === undefined ? {} : { observabilityRegressed: regressed }),
+                    featureUse,
+                    toolHitRate,
+                };
+            },
         },
-    },
-];
+    ];
+}

package/dist/tools/dynamic-tools.js

@@ -1,10 +1,12 @@
 import { z } from 'zod';
 import { runTool } from './invoke-tool.js';
 import { buildErrorPayload } from './error-recovery.js';
-import { mergedNameRedirect, mergedNameMessage } from './merged-name-redirect.js';
+import { mergedNameRedirect, mergedNameMessage, retiredToolNames } from './merged-name-redirect.js';
+import { takeVersionSkewOnto } from '../version/version-nudge.js';
 import { ReticleTool } from './tool-names.js';
-import { TOOL_PROFILE_ENV } from './tool-surface.js';
+import { ADVERTISE_ALL_ENV } from './tool-surface.js';
 import { getSessionMetrics } from '../telemetry/session-metrics.js';
+import { isPredicateParam, predicateGrammar } from '../events/predicate-eval.js';
 /**
  * On-demand tool loading for MCP — the answer to the per-turn tool-definition tax.
  *
@@ -47,6 +49,8 @@ function paramInfo(shape) {
 function unknownParamsError(toolName, unknown) {
     return `unknown ${1 === unknown.length ? 'parameter' : 'parameters'} for ${toolName}: ${unknown.join(', ')} — NOT applied, so any result would be an answer to a different question`;
 }
+/** What to write instead — the one parameter reticle_tools declares, and the no-argument form. */
+const TOOLS_ARG_HINT = 'name the tools you want in `names`: reticle_tools { names: ["reticle_act_and_wait"] } — or call it with no arguments for the full catalog';
 /** The keys not declared by `shape`, in call order. */
 function unknownKeys(args, shape) {
     const declared = new Set(Object.keys(shape));
@@ -70,19 +74,32 @@ export function buildDynamicTools(allTools, profile) {
                 // advertises the whole registry any more, so BOTH meta-tools are on every surface and
                 // reticle_run is always the way to the tail. The old wording would now send an agent
                 // away from the only tool that can reach half the registry.
-                note: `The surface is read once at daemon startup: change ${TOOL_PROFILE_ENV} and restart the daemon, or it has no effect. No surface advertises every tool — the advertised count is capped because editors budget tools across all connected MCP servers. Every tool listed here is callable through reticle_run { tool, args } whether or not it is advertised.`,
+                note: `The surface is read once at daemon startup: set ${ADVERTISE_ALL_ENV}=1 and restart the daemon, or it has no effect. No surface advertises every tool: the advertised count is capped because editors budget tools across all connected MCP servers. Every tool listed here is callable through reticle_run { tool, args } whether or not it is advertised.`,
             },
         };
+    const toolsShape = {
+        names: z
+            .array(z.string())
+            .optional()
+            .describe('Tool names to load full params for. Omit to list all tools with summaries.'),
+    };
     const reticleTools = {
         name: ReticleTool.TOOLS,
         description: 'Discover Reticle tools on demand. Call with no arguments to list every tool (name + one-line summary); call with names:["reticle_network", …] to load full descriptions and parameters for specific tools. Then invoke them with reticle_run. This avoids paying for every tool definition on every turn. To make a verification REUSABLE (record once, replay free forever), the flow workflow lives here: reticle_record{action:"start"} → act → reticle_flow_save → reticle_verify{action:"flows"} (and reticle_flow_heal on drift). Load those names when you want to save or re-run a flow.',
-        inputSchema: {
-            names: z
-                .array(z.string())
-                .optional()
-                .describe('Tool names to load full params for. Omit to list all tools with summaries.'),
-        },
+        inputSchema: toolsShape,
         handler: (_deps, args) => {
+            // The discovery tool declared one parameter and checked none, so a call that misnamed it had
+            // the key dropped and came back with the WHOLE catalogue — a well-formed answer to a question
+            // nobody asked, and one the caller cannot tell from the answer it wanted. Same check and same
+            // wording as reticle_run's, because two spellings of one refusal is how one of them rots.
+            const stray = unknownKeys(args, toolsShape);
+            if (stray.length > 0) {
+                return Promise.resolve({
+                    error: unknownParamsError(ReticleTool.TOOLS, stray),
+                    params: paramInfo(toolsShape),
+                    hint: TOOLS_ARG_HINT,
+                });
+            }
             const names = Array.isArray(args['names'])
                 ? args['names'].filter((n) => 'string' === typeof n)
                 : undefined;
@@ -94,20 +111,43 @@ export function buildDynamicTools(allTools, profile) {
                     name: t.name,
                     summary: firstSentence(t.description),
                 }));
+                // Names that USED to be tools, against the call that replaces each. Instructions written
+                // against an earlier release are a permanent fact of the product — `reticle_crawl` is still
+                // named by guidance in the wild — and without this the catalogue is silent about them: the
+                // old name is simply absent, which reads as "no such capability" rather than "renamed".
+                // Reaching the new name then costs an error string, or never happens.
+                const retired = retiredToolNames();
                 return Promise.resolve({
                     total: catalog.length,
                     tools: catalog,
+                    retired,
                     ...profileBlock,
-                    next: `All ${catalog.length} tools above are callable, advertised or not. Load full params with reticle_tools { names:[…] }, then call reticle_run { tool, args }.`,
+                    next: `All ${catalog.length} tools above are callable, advertised or not. Load full params with reticle_tools { names:[…] }, then call reticle_run { tool, args }. \`retired\` maps names that are no longer tools to the call that replaced each.`,
                 });
             }
+            // The grammar rides ONLY on a `names:[…]` reply that asked for a tool taking a predicate, so
+            // no turn pays for it in the catalog or in the advertised schema. The lean tool surface says
+            // "call reticle_tools for the full field grammar of a kind"; this is where that lands.
+            const carriesPredicate = names.some((n) => Object.values(byName.get(n)?.inputSchema ?? {}).some((schema) => isPredicateParam(schema)));
             return Promise.resolve({
                 tools: names.map((n) => {
                     const t = byName.get(n);
-                    return t === undefined
+                    if (t !== undefined)
+                        return { name: n, description: t.description, params: paramInfo(t.inputSchema) };
+                    // `reticle_run` has answered a merged name with its replacement for a while; the tool
+                    // asked to DISCOVER tools still said "unknown tool", which is the wrong answer in the one
+                    // place an agent goes to resolve a name it is unsure of. Same redirect, same derivation.
+                    const moved = mergedNameRedirect(n);
+                    return moved === undefined
                         ? { name: n, error: 'unknown tool' }
-                        : { name: n, description: t.description, params: paramInfo(t.inputSchema) };
+                        : {
+                            name: n,
+                            error: mergedNameMessage(n, moved),
+                            tool: moved.tool,
+                            ...(moved.action === undefined ? {} : { action: moved.action }),
+                        };
                 }),
+                ...(carriesPredicate ? { predicateGrammar: predicateGrammar() } : {}),
             });
         },
     };
@@ -201,7 +241,7 @@ export function buildDynamicTools(allTools, profile) {
                 // is reached through here: a stale ref, a paused session, a missing pairing token all came
                 // back as the agent's arguments being wrong, which is advice that spends the retry.
                 const message = error instanceof Error ? error.message : String(error);
-                return { ...buildErrorPayload(message), tool: name };
+                return { ...takeVersionSkewOnto(buildErrorPayload(message)), tool: name };
             }
         },
     };

package/dist/tools/error-recovery.d.ts

@@ -18,13 +18,38 @@ export declare const RECOVERY: {
     readonly MISSING_BASELINE: string;
     readonly MISSING_RECORDING: string;
     readonly STALE_REF: string;
+    readonly STALE_REF_AFTER_EDIT: string;
     readonly INVALID_NAME: string;
+    /**
+     * The call was well-formed and the SELECTOR missed. Nothing about the arguments was wrong, so the
+     * BAD_ARGUMENTS answer ("re-read that tool's parameters") sends the reader to the one place that
+     * holds no answer — measured live on a `target: { testid }` that simply was not on the page yet.
+     *
+     * The error text already names the two moves that work, so this adds the fact the text cannot
+     * carry: which of them to reach for, and that nothing was acted on.
+     */
+    readonly TARGET_MISSED: string;
     readonly NO_SUCH_OPTION: string;
     readonly BAD_ARGUMENTS: string;
     readonly WRONG_TARGET: string;
     readonly NOT_EDITABLE: string;
+    /**
+     * Written as the ARGUMENT OBJECT the caller has to send, not as a dotted path.
+     *
+     * Measured on a benchmark run that spent its entire budget here: the refusal said "retry with
+     * args.confirmDangerous=true", and the agent went looking for a parameter by that name, could not
+     * find one at the top level of the schema, and re-read the tool list rather than retrying. The
+     * flag IS documented — inside the `args` object's own description — so a dotted path pointing at
+     * something that is not a top-level parameter is the whole distance between a one-line retry and
+     * a lost budget.
+     *
+     * The classifier is also wider than "destructive": it matches `deploy` and `publish`, so an
+     * ordinary "New deploy" button trips it. Naming a real trigger word here keeps that from reading
+     * as a malfunction on an app where nothing is being deleted.
+     */
     readonly CONFIRM_DANGEROUS: string;
     readonly UNSUPPORTED_SURFACE: string;
+    readonly HOVER_NEEDS_POINTER: string;
     readonly TOKEN_REQUIRED: string;
     readonly SCOPE_MISMATCH: string;
     readonly SESSION_GONE: string;
@@ -50,20 +75,6 @@ export declare function recoveryFor(message: string): string | undefined;
  * this table rather than about anybody's app.
  */
 export declare function refusalReasonFor(rawMessage: string): RefusalReason;
-/**
- * A serialized zod issue array, rendered as a sentence. Anything else is returned untouched.
- *
- * This is the one boundary every agent-visible tool failure crosses, which is why the rewrite lives
- * here rather than in each tool. `parsePredicate` solved this for the three predicate tools by never
- * producing the array; it cannot help anywhere else, because the MCP SDK validates a tool's schema
- * BEFORE our handler runs. So `reticle_session` with no action — the commonest mistake there is —
- * never reaches the friendly "unknown action … expected: [tune, yield, …]" its handler already
- * builds, and the agent gets the raw array instead. Driven live against the shipped daemon.
- *
- * Conservative by construction: it only rewrites a JSON ARRAY whose every element carries both
- * `code` and `message`. A tool that legitimately returns JSON is left alone.
- */
-export declare function zodArrayAsSentence(message: string): string;
 /**
  * The ask attached to errors we do NOT recognize. An unrecognized error is, by definition, the case
  * where Reticle failed in a way nobody anticipated — the single highest-value moment to hear from the

package/dist/tools/error-recovery.js

@@ -66,7 +66,9 @@ export const RECOVERY = {
         'target the one you mean.',
     UNKNOWN_SESSION: 'That sessionId is not connected. Call reticle_sessions for the current ids and retry with a valid one.',
     THROTTLED: 'The target tab is backgrounded/throttled, so actions may silently no-op. Ask the human to bring ' +
-        'the tab to the front, or run `reticle drive <url>` for a guaranteed scriptable context.',
+        'the tab to the front, or acquire a guaranteed scriptable context yourself with ' +
+        '`reticle_run { tool: "reticle_lease", action: "acquire", url }` (a human can equivalently run ' +
+        '`reticle drive <url>`).',
     MISSING_BASELINE: 'That baseline does not exist yet. Call reticle_baseline { action: "list" } to see saved names, or ' +
         'reticle_baseline { action: "save", name } to capture one before diffing against it.',
     MISSING_RECORDING: 
@@ -79,11 +81,28 @@ export const RECOVERY = {
         'before it. Reticle refuses here rather than clicking whatever now occupies that slot. Call ' +
         'reticle_query again for a fresh ref and retry the action — and prefer reticle_act_and_wait ' +
         '{ until } when an action changes the page, so the next ref is taken after it settles.',
+    STALE_REF_AFTER_EDIT: 'That ref went stale because YOUR OWN EDIT landed: the dev server hot-updated the module named ' +
+        'in the message above and the framework re-rendered, so the node the ref pointed at was ' +
+        'replaced. Nothing is wrong with the app and nothing is wrong with Reticle — this is the ' +
+        'build-and-verify loop working. Call reticle_query for a fresh ref and drive again, and treat ' +
+        'anything you observed before the update as describing the previous version of the code.',
     INVALID_NAME: 'That name is not a usable one. A flow, baseline or recording name must be a single safe path ' +
         'segment — letters, digits, dash and underscore only, starting with a letter or digit, at most ' +
         '64 characters. No slashes, no "..", no leading dot: the name becomes a filename under ' +
         '.reticle/, so anything that could escape that directory is refused. Retry with a slug like ' +
         '"checkout-happy-path". This is an invalid call, not a Reticle defect: there is nothing to report.',
+    /**
+     * The call was well-formed and the SELECTOR missed. Nothing about the arguments was wrong, so the
+     * BAD_ARGUMENTS answer ("re-read that tool's parameters") sends the reader to the one place that
+     * holds no answer — measured live on a `target: { testid }` that simply was not on the page yet.
+     *
+     * The error text already names the two moves that work, so this adds the fact the text cannot
+     * carry: which of them to reach for, and that nothing was acted on.
+     */
+    TARGET_MISSED: 'The call was valid — the selector matched nothing on the page RIGHT NOW, and nothing was ' +
+        'acted on. Take a reticle_snapshot to see what is actually there (a view may still be ' +
+        'rendering, or the control may be named differently), then retry with what it shows. This is ' +
+        'a miss, not a Reticle defect: there is nothing to report.',
     NO_SUCH_OPTION: 'That <select> has no option with the value you asked for, and the message above lists the ones ' +
         'it does have. Reticle refuses rather than assigning it: an unmatched value deselects everything, ' +
         'and the change event that follows has been observed persisting an empty setting into the app. ' +
@@ -102,13 +121,34 @@ export const RECOVERY = {
         'telling you something: drive whatever ENABLES the field (open the editor, satisfy the ' +
         'precondition) and act again. If the field should have been editable, that is a bug in the app, ' +
         'not in Reticle.',
-    CONFIRM_DANGEROUS: 'Reticle blocked a potentially destructive control (delete, remove, revoke…) on purpose. If you ' +
-        'mean it, retry the same action with args.confirmDangerous set to true. This is a deliberate ' +
-        'refusal, not a defect: there is nothing to report.',
+    /**
+     * Written as the ARGUMENT OBJECT the caller has to send, not as a dotted path.
+     *
+     * Measured on a benchmark run that spent its entire budget here: the refusal said "retry with
+     * args.confirmDangerous=true", and the agent went looking for a parameter by that name, could not
+     * find one at the top level of the schema, and re-read the tool list rather than retrying. The
+     * flag IS documented — inside the `args` object's own description — so a dotted path pointing at
+     * something that is not a top-level parameter is the whole distance between a one-line retry and
+     * a lost budget.
+     *
+     * The classifier is also wider than "destructive": it matches `deploy` and `publish`, so an
+     * ordinary "New deploy" button trips it. Naming a real trigger word here keeps that from reading
+     * as a malfunction on an app where nothing is being deleted.
+     */
+    CONFIRM_DANGEROUS: 'Reticle blocked a control whose label reads as consequential (delete, remove, revoke, deploy, ' +
+        'publish, pay…) on purpose. If you mean it, send the SAME call again with ' +
+        '`args: { confirmDangerous: true }` — it goes inside the `args` object, not beside it. This is ' +
+        'a deliberate refusal, not a defect: there is nothing to report.',
     UNSUPPORTED_SURFACE: 'That surface is not supported yet, and Reticle refuses rather than pretending — a rich-text ' +
         'editor keeps its own document model, so writing to the DOM would look right and submit the old ' +
         'content. Drive the same outcome another way (a plain input, a command, a keyboard action) or ' +
         'assert on the result instead of typing it. Known gap, already reported: no need to file it.',
+    HOVER_NEEDS_POINTER: 'Hover needs a real pointer: a synthetic mouseover does not apply CSS :hover, and Reticle ' +
+        'refuses rather than reporting the styles as applied. Acquire a tab with ' +
+        'reticle_run { tool: "reticle_lease", action: "acquire", url } — reticle_lease is not ' +
+        'advertised under the default profile, so it is reached through reticle_run, not called ' +
+        'directly — or ask the human to drive with `reticle drive` / RETICLE_CDP_URL. This is a ' +
+        'deliberate refusal, not a defect: there is nothing to report.',
     TOKEN_REQUIRED: 'The bridge binds beyond localhost and requires a pairing token. Set the same token in the SDK ' +
         'init (@reticlehq/core) and the Reticle server config, then reconnect.',
     SCOPE_MISMATCH: 'A tab IS connected — it just belongs to a different project than the daemon is scoped to, so ' +
@@ -163,9 +203,12 @@ const REASON_OF = {
     MISSING_BASELINE: RefusalReason.NO_MATCH,
     MISSING_RECORDING: RefusalReason.NO_MATCH,
     STALE_REF: RefusalReason.NO_MATCH,
+    STALE_REF_AFTER_EDIT: RefusalReason.NO_MATCH,
     NO_SUCH_OPTION: RefusalReason.NO_MATCH,
+    TARGET_MISSED: RefusalReason.NO_MATCH,
     FLOW_STEP_MISSING: RefusalReason.NO_MATCH,
     UNSUPPORTED_SURFACE: RefusalReason.UNSUPPORTED,
+    HOVER_NEEDS_POINTER: RefusalReason.UNSUPPORTED,
     NOT_EDITABLE: RefusalReason.UNSUPPORTED,
     CONFIRM_DANGEROUS: RefusalReason.UNSUPPORTED,
     WRONG_TARGET: RefusalReason.UNSUPPORTED,
@@ -200,6 +243,9 @@ const RULES = [
     },
     // The commonest post-action condition there is. Unmatched, it fell through to FEEDBACK_ASK and
     // told the agent a successful click's aftermath might be a bug in Reticle.
+    // Before the general rule: the edit-aware refusal contains the general one's substring too, and
+    // the first hit wins. "Your edit landed" is a next step; "the ref is stale" is a dead end.
+    { match: /the code changed underneath it/i, hint: RECOVERY.STALE_REF_AFTER_EDIT },
     { match: /no longer resolves to an element/i, hint: RECOVERY.STALE_REF },
     { match: /no <option> with value/i, hint: RECOVERY.NO_SUCH_OPTION },
     // Every guard in the browser's executeAction. These are Reticle-authored refusals of an invalid
@@ -208,6 +254,7 @@ const RULES = [
     // broken. Order matters: contenteditable and disabled/readonly are `cannot <verb> …` messages too,
     // so they must be tested before the general wrong-target rule.
     { match: /contenteditable/i, hint: RECOVERY.UNSUPPORTED_SURFACE },
+    { match: /cannot hover without a real pointer/i, hint: RECOVERY.HOVER_NEEDS_POINTER },
     { match: /cannot \w+ a (disabled|readonly) </i, hint: RECOVERY.NOT_EDITABLE },
     // Three spellings ship — "action", "native action", "WebMCP tool" — and the rule matched one, so
     // two thirds of the same deliberate refusal still read as a possible defect.
@@ -224,15 +271,37 @@ const RULES = [
         match: /no form to submit|upload target must be|is not an HTMLElement/i,
         hint: RECOVERY.WRONG_TARGET,
     },
+    // BEFORE the catch-all, which would otherwise claim this one.
+    //
+    // "target matched no element ... take a reticle_snapshot" names a `reticle_*` tool in its own
+    // advice, so the catch-all below matched it and answered "That call did not match the tool's
+    // schema". The call matched the schema perfectly; the element was not on the page. Sending an
+    // agent to re-read arguments that were already correct costs it a turn, and this is the commonest
+    // refusal there is.
+    { match: /target matched no element/i, hint: RECOVERY.TARGET_MISSED },
     // Authored by Reticle, about the caller's arguments: the message already names the valid answers.
     { match: /^unknown action '/i, hint: RECOVERY.BAD_ARGUMENTS },
     { match: /^unsupported query strategy '/i, hint: RECOVERY.BAD_ARGUMENTS },
     { match: /^\w+ requires a string `\w+`/i, hint: RECOVERY.BAD_ARGUMENTS },
-    // A message naming a `reticle_*` tool is one WE authored about our own API — an invalid call, not
-    // an unanticipated failure. Left unmatched it collected the feedback ask, which pushed agents to
-    // file reports about their own bad arguments. Kept LAST so a specific rule above always wins.
+    // A message naming a `reticle_*` tool or an `args.*` parameter is one WE authored about our own
+    // API — an invalid call, not an unanticipated failure. Left unmatched it collected the feedback
+    // ask, which pushed agents to file reports about their own bad arguments. Kept LAST so a specific
+    // rule above always wins.
+    //
+    // Keyed on the tool/parameter NAME rather than on a sentence shape. The previous form wanted
+    // `reticle_x { ... }` with braces AND requires/must/expected, which is one phrasing out of many;
+    // measured live, a drag refusal reading "pass a ref from reticle_snapshot or reticle_query as
+    // args.toRef" fell straight through and told the agent its own malformed call might be a Reticle
+    // defect worth a root-cause report. That is the FOURTH patch to this same default, after the
+    // executeAction guards, the destructive-action block, and two of the three spellings of
+    // "potentially destructive ... blocked" — each one added a phrasing instead of changing the key.
+    //
+    // A path is deliberately excluded: `@reticlehq/server/dist/...` in a stack trace is a crash we did
+    // NOT anticipate, and silencing the feedback ask there would lose the reports worth having. Hence
+    // a word boundary before `reticle_` and a required space-or-punctuation after the name, so a tool
+    // named in prose matches and a module path does not.
     {
-        match: /reticle_[a-z_]+\s*\{[^}]*\}.*\b(requires|must|expected)\b/i,
+        match: /(?:^|[\s'"`(])reticle_[a-z_]+(?![\w/.-])|(?:^|[\s'"`(])args\.[a-z][\w]*/i,
         hint: RECOVERY.BAD_ARGUMENTS,
     },
 ];
@@ -321,7 +390,7 @@ function issueClause(issue) {
  * Conservative by construction: it only rewrites a JSON ARRAY whose every element carries both
  * `code` and `message`. A tool that legitimately returns JSON is left alone.
  */
-export function zodArrayAsSentence(message) {
+function zodArrayAsSentence(message) {
     const text = message.trim();
     if (!text.startsWith('['))
         return message;

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

@@ -24,7 +24,7 @@ export declare const FEEDBACK_PROMPT: {
  * calls, assert ZERO, verification_completed 2. Agents were verifying the entire time and the metric
  * could not see it. The contract test now checks the SHAPE instead.
  */
-export declare const VERIFICATION_TOOLS: ReadonlySet<string>;
+export declare const VERDICT_TOOLS: ReadonlySet<string>;
 /**
  * The human prompt, when one is due. Resettable for tests.
  *

package/dist/tools/feedback-tools.js

@@ -173,7 +173,7 @@ export const FEEDBACK_PROMPT = {
  * calls, assert ZERO, verification_completed 2. Agents were verifying the entire time and the metric
  * could not see it. The contract test now checks the SHAPE instead.
  */
-export const VERIFICATION_TOOLS = new Set([
+export const VERDICT_TOOLS = new Set([
     ReticleTool.ACT_AND_WAIT,
     ReticleTool.ASSERT,
     // Merged: `flow_verify` and `verify_change` are actions on this tool now. Naming the merged tool
@@ -206,7 +206,7 @@ let verificationsSincePrompt = 0;
  * collect is worse than not asking: it spends their attention on a message with nowhere to go.
  */
 export function takeFeedbackPrompt(toolName) {
-    if (!VERIFICATION_TOOLS.has(toolName))
+    if (!VERDICT_TOOLS.has(toolName))
         return undefined;
     if (feedbackDisabled() || !getTelemetry().enabled)
         return undefined;