@reticlehq/server 2.3.0 → 2.5.0

package/dist/tools/contract-tools.js

@@ -29,7 +29,7 @@ export const CONTRACT_TOOLS = [
             governance: z.unknown().optional(),
         },
         handler: async (deps, args) => {
-            if (args[FROM_DISK_ARG] === true) {
+            if (true === args[FROM_DISK_ARG]) {
                 const r = await readContract(deps.fs, deps.reticleRoot);
                 if (!r.ok)
                     throw new Error(r.reason === ContractReadError.MISSING

package/dist/tools/coverage-identity.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Which controls has the agent actually driven — across re-renders.
+ *
+ * Coverage was counted by REF, and a ref is invalidated whenever the DOM changes. Reported from a
+ * sweep of a Next app-router project: `total: 34, exercised: 0` after four successful acts. App
+ * router replaces a whole route segment on navigation, so every control the agent drove is a new
+ * element by the time coverage is asked. The number is then 0 forever on any framework that replaces
+ * nodes rather than reconciling in place — and an agent told it has exercised none of 34 controls
+ * re-drives ground it already covered, which is the exact opposite of what this tool is for.
+ *
+ * Bench-app hid it: it reconciles in place, so refs survive there and the number looked right.
+ *
+ * The LABEL is the identity that survives a re-render — `button "Deploy"` names the same control
+ * before and after — and it is already parsed for the untouched list.
+ *
+ * One caveat, stated because it is a real limitation: two controls sharing a label are
+ * indistinguishable here, so driving one marks both. That errs toward "covered", which is the
+ * unsafe direction for a coverage number — but it is bounded to same-labelled controls, and the
+ * alternative it replaces reported ZERO coverage on entire frameworks.
+ */
+interface CoverageControl {
+    ref: string;
+    label: string;
+}
+interface CoverageTally {
+    /** Controls on the page the agent has driven, by ref or by surviving label. */
+    exercised: number;
+    /** Controls the agent drove that are on the page no longer, and no label explains. */
+    droveGone: number;
+    /** The controls still untouched, in document order. */
+    untouched: CoverageControl[];
+}
+export declare function exercisedCount(controls: readonly CoverageControl[], actedRefs: ReadonlySet<string>, actedLabels: ReadonlySet<string>): CoverageTally;
+export {};

package/dist/tools/coverage-identity.js

@@ -0,0 +1,46 @@
+/**
+ * Which controls has the agent actually driven — across re-renders.
+ *
+ * Coverage was counted by REF, and a ref is invalidated whenever the DOM changes. Reported from a
+ * sweep of a Next app-router project: `total: 34, exercised: 0` after four successful acts. App
+ * router replaces a whole route segment on navigation, so every control the agent drove is a new
+ * element by the time coverage is asked. The number is then 0 forever on any framework that replaces
+ * nodes rather than reconciling in place — and an agent told it has exercised none of 34 controls
+ * re-drives ground it already covered, which is the exact opposite of what this tool is for.
+ *
+ * Bench-app hid it: it reconciles in place, so refs survive there and the number looked right.
+ *
+ * The LABEL is the identity that survives a re-render — `button "Deploy"` names the same control
+ * before and after — and it is already parsed for the untouched list.
+ *
+ * One caveat, stated because it is a real limitation: two controls sharing a label are
+ * indistinguishable here, so driving one marks both. That errs toward "covered", which is the
+ * unsafe direction for a coverage number — but it is bounded to same-labelled controls, and the
+ * alternative it replaces reported ZERO coverage on entire frameworks.
+ */
+export function exercisedCount(controls, actedRefs, actedLabels) {
+    // An empty label is not an identity — anonymous controls would otherwise collapse into one bucket
+    // and a single act would mark every one of them driven.
+    // Matched on the whole label (`button "Save"`) OR on a testid the label contains. The snapshot
+    // renders a control's testid inside its label, and a testid is the identity most likely to survive
+    // a re-render — matching only the full label meant a control with a testid but no accessible name
+    // was never recognised, and coverage read `exercised: 0` after real work.
+    const droveLabel = (label) => {
+        if (0 === label.length)
+            return false;
+        if (actedLabels.has(label))
+            return true;
+        for (const acted of actedLabels) {
+            if (acted.length > 0 && !acted.includes('"') && label.includes(acted))
+                return true;
+        }
+        return false;
+    };
+    const untouched = controls.filter((control) => !actedRefs.has(control.ref) && !droveLabel(control.label));
+    // A driven ref that is not on the page is only "gone" if no present control carries its label —
+    // otherwise it is the same control after a re-render, which is the case this exists to fix.
+    const presentRefs = new Set(controls.map((control) => control.ref));
+    const explainedByLabel = new Set(controls.filter((control) => droveLabel(control.label)).map((control) => control.label));
+    const droveGone = [...actedRefs].filter((ref) => !presentRefs.has(ref) && 0 === explainedByLabel.size).length;
+    return { exercised: controls.length - untouched.length, droveGone, untouched };
+}

package/dist/tools/coverage-tools.js

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { ReticleCommand, SnapshotMode } from '@reticlehq/core';
 import { ReticleTool } from './tool-names.js';
 import { asString } from './tools-helpers.js';
+import { exercisedCount } from './coverage-identity.js';
 import { commandOrThrow, sessionIdShape } from './tool-kit.js';
 /**
  * `reticle_coverage` — which interactive controls this session has driven, and which it has not.
@@ -28,7 +29,7 @@ export function parseControls(tree) {
     const seen = new Set();
     for (const line of tree.split('\n')) {
         const match = LINE_WITH_REF.exec(line);
-        if (match === null)
+        if (null === match)
             continue;
         const [, label, ref] = match;
         if (label === undefined || ref === undefined || seen.has(ref))
@@ -71,21 +72,16 @@ export const COVERAGE_TOOLS = [
                 mode: SnapshotMode.INTERACTIVE,
             });
             const tree = asString(result['tree']) ?? '';
-            const acted = session.actedRefs();
-            const controls = parseControls(tree);
-            const present = new Set(controls.map((control) => control.ref));
-            const untouched = controls.filter((control) => !acted.has(control.ref));
-            // Drives that landed on controls no longer in the DOM. Without this the number is biased
-            // against the actions that WORKED: archive, delete, submit and navigate all remove their own
-            // control, so clicking one and asking again reported `exercised: 0` — measured on the Electron
-            // demo right after a successful archive. An agent reading "0" concludes it has done nothing
-            // and re-drives ground it already covered.
-            const drovenGone = [...acted].filter((ref) => !present.has(ref)).length;
+            // 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());
             return {
-                total: controls.length,
-                exercised: controls.length - untouched.length,
+                total: parseControls(tree).length,
+                exercised,
                 untouched,
-                ...(drovenGone > 0 ? { alsoDroveGone: drovenGone } : {}),
+                ...(droveGone > 0 ? { alsoDroveGone: droveGone } : {}),
             };
         },
     },

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

@@ -1,6 +1,7 @@
 import type { ToolDef } from './tools.js';
+import { type ToolSurfaceOrigin } from './tool-surface.js';
 /**
  * Build the two dynamic meta-tools over the full tool table. `reticle_run` dispatches through the same
  * `runTool` chokepoint as a direct call, so session-health splicing and every other invariant hold.
  */
-export declare function buildDynamicTools(allTools: ToolDef[]): ToolDef[];
+export declare function buildDynamicTools(allTools: ToolDef[], profile?: ToolSurfaceOrigin): ToolDef[];

package/dist/tools/dynamic-tools.js

@@ -1,6 +1,9 @@
 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 { ReticleTool } from './tool-names.js';
+import { TOOL_PROFILE_ENV } from './tool-surface.js';
 import { getSessionMetrics } from '../telemetry/session-metrics.js';
 /**
  * On-demand tool loading for MCP — the answer to the per-turn tool-definition tax.
@@ -36,12 +39,39 @@ function paramInfo(shape) {
         description: schema.description ?? '',
     }));
 }
+/**
+ * The one wording for "you named a parameter that does not exist", shared by both checks in
+ * `reticle_run` — the one over the WRAPPED tool's `args`, and the one over reticle_run's own
+ * top-level keys. Two spellings of the same refusal is how one of them ends up not existing.
+ */
+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`;
+}
+/** The keys not declared by `shape`, in call order. */
+function unknownKeys(args, shape) {
+    const declared = new Set(Object.keys(shape));
+    return Object.keys(args).filter((key) => !declared.has(key));
+}
 /**
  * Build the two dynamic meta-tools over the full tool table. `reticle_run` dispatches through the same
  * `runTool` chokepoint as a direct call, so session-health splicing and every other invariant hold.
  */
-export function buildDynamicTools(allTools) {
+export function buildDynamicTools(allTools, profile) {
     const byName = new Map(allTools.map((t) => [t.name, t]));
+    // The profile is a DAEMON-startup decision, so an agent that exported RETICLE_TOOL_PROFILE into its
+    // own environment sees no change and has, until now, no way to tell. Reported with the catalog.
+    const profileBlock = profile === undefined
+        ? {}
+        : {
+            profile: {
+                ...profile,
+                // NOT "every tool is reachable via reticle_run under any profile" — measured false:
+                // `full` advertises all 46 tools DIRECTLY and carries no meta-tools at all, so
+                // reticle_run does not exist there. Saying otherwise sends the agent to a tool the
+                // profile does not have.
+                note: `The profile is read once at daemon startup — change ${TOOL_PROFILE_ENV} and restart the daemon, or it has no effect. Under this profile every unadvertised tool is reachable through reticle_run; under \`full\` there are no meta-tools because every tool is advertised directly.`,
+            },
+        };
     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_flow_verify (and reticle_flow_heal on drift). Load those names when you want to save or re-run a flow.',
@@ -53,11 +83,12 @@ export function buildDynamicTools(allTools) {
         },
         handler: (_deps, args) => {
             const names = Array.isArray(args['names'])
-                ? args['names'].filter((n) => typeof n === 'string')
+                ? args['names'].filter((n) => 'string' === typeof n)
                 : undefined;
-            if (names === undefined || names.length === 0) {
+            if (names === undefined || 0 === names.length) {
                 return Promise.resolve({
                     tools: allTools.map((t) => ({ name: t.name, summary: firstSentence(t.description) })),
+                    ...profileBlock,
                     next: 'Load params with reticle_tools { names:[…] }, then call reticle_run { tool, args }.',
                 });
             }
@@ -71,35 +102,76 @@ export function buildDynamicTools(allTools) {
             });
         },
     };
+    const runShape = {
+        tool: z.string().describe('Tool name to invoke, e.g. reticle_network.'),
+        args: z.record(z.unknown()).optional().describe('Arguments object for that tool.'),
+        // Accepted AND FORWARDED, not merely tolerated. reticle_run is the only way to reach an
+        // unadvertised tool, so on a machine running several projects it has to be aimable — and
+        // `sessionId` is the shape an agent already uses on every other tool. Reported across 6 of 6
+        // apps: it took this key, dropped it, resolved by the daemon's cwd project, and failed with
+        // "no browser session for project X" while naming the very session it had been given.
+        sessionId: z
+            .string()
+            .optional()
+            .describe('Target tab for the invoked tool. Forwarded to it — an explicit args.sessionId wins.'),
+    };
     const reticleRun = {
         name: ReticleTool.RUN,
         description: "Invoke any Reticle tool by name (discover names/params first with reticle_tools). On an unknown tool or bad arguments it returns the available names or the tool's params, so you can correct and retry.",
-        inputSchema: {
-            tool: z.string().describe('Tool name to invoke, e.g. reticle_network.'),
-            args: z.record(z.unknown()).optional().describe('Arguments object for that tool.'),
-        },
+        inputSchema: runShape,
         handler: async (deps, args) => {
-            const name = typeof args['tool'] === 'string' ? args['tool'] : '';
-            const callArgs = typeof args['args'] === 'object' && args['args'] !== null
+            // reticle_run's OWN parameters, checked first and with the same wording as the inner check.
+            // It refused an unknown key inside `args` and silently dropped one beside them: an agent that
+            // wrote `reticle_run { tool, args, sessionId }` — the shape it uses on every other tool — had
+            // its sessionId ignored and got a confident answer about whichever session auto-selection
+            // picked. Every other tool on the surface refuses this; the escape hatch has to as well.
+            const strayTop = unknownKeys(args, runShape);
+            if (strayTop.length > 0) {
+                return {
+                    error: unknownParamsError(ReticleTool.RUN, strayTop),
+                    hint: `pass them inside args: reticle_run { tool, args: { ${strayTop.join(', ')}: … } } if the target tool declares them`,
+                };
+            }
+            const name = 'string' === typeof args['tool'] ? args['tool'] : '';
+            const given = 'object' === typeof args['args'] && args['args'] !== null
                 ? args['args']
                 : {};
+            const aimed = args['sessionId'];
             const target = byName.get(name);
             if (target === undefined) {
                 // A non-zero count here means our advertised surface is confusing the agent — it reached for
                 // something it believed existed. That is a docs/naming defect, and it was invisible.
                 getSessionMetrics().recordUnknownTool();
+                // ...and for 22 of those names the capability DOES exist, it just moved when tools merged.
+                // Answering "unknown tool" there is simply wrong; see merged-name-redirect.
+                const moved = mergedNameRedirect(name);
+                if (moved !== undefined) {
+                    return {
+                        error: mergedNameMessage(name, moved),
+                        tool: moved.tool,
+                        ...(moved.action === undefined ? {} : { action: moved.action }),
+                    };
+                }
                 return { error: `unknown tool '${name}'`, available: allTools.map((t) => t.name) };
             }
+            // The outer aim, forwarded ONLY to a tool that declares a session — injecting it into one that
+            // does not would trip the unknown-key check below and refuse a call the caller got right. An
+            // inner args.sessionId wins as the more specific instruction, and an absent aim stays absent so
+            // auto-selection still applies.
+            const callArgs = 'string' === typeof aimed &&
+                given['sessionId'] === undefined &&
+                undefined !== target.inputSchema['sessionId']
+                ? { ...given, sessionId: aimed }
+                : given;
             // The escape hatch is where a typo is MOST likely, because an unadvertised tool's parameters
             // are not in front of the agent at all — and it is the one path the SDK's own validation never
             // sees, since `reticle_run`'s own args (`tool`, `args`) are perfectly valid. Left unchecked,
             // `reticle_run { tool: "reticle_clock", args: { action: "freeze" } }` returned
             // `{"frozen":false}`: a well-formed answer to a question nobody asked.
-            const declared = new Set(Object.keys(target.inputSchema));
-            const unknown = Object.keys(callArgs).filter((key) => !declared.has(key));
+            const unknown = unknownKeys(callArgs, target.inputSchema);
             if (unknown.length > 0) {
                 return {
-                    error: `unknown ${unknown.length === 1 ? 'parameter' : 'parameters'} for ${name}: ${unknown.join(', ')} — NOT applied, so any result would be an answer to a different question`,
+                    error: unknownParamsError(name, unknown),
                     tool: name,
                     params: paramInfo(target.inputSchema),
                     ...(target.example === undefined ? {} : { example: target.example }),
@@ -110,12 +182,12 @@ export function buildDynamicTools(allTools) {
                 return await runTool(target, deps, callArgs);
             }
             catch (error) {
-                return {
-                    error: error instanceof Error ? error.message : String(error),
-                    tool: name,
-                    params: paramInfo(target.inputSchema),
-                    hint: 'fix the arguments and call reticle_run again',
-                };
+                // The SAME payload the direct tool path builds — recovery included. Answering every failure
+                // with "fix the arguments" threw that away, and under the default profile nearly every tool
+                // 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 };
             }
         },
     };

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

@@ -17,10 +17,28 @@ export declare const RECOVERY: {
     readonly MISSING_BASELINE: string;
     readonly MISSING_RECORDING: string;
     readonly STALE_REF: string;
+    readonly INVALID_NAME: string;
+    readonly NO_SUCH_OPTION: string;
     readonly BAD_ARGUMENTS: string;
+    readonly WRONG_TARGET: string;
+    readonly NOT_EDITABLE: string;
+    readonly CONFIRM_DANGEROUS: string;
+    readonly UNSUPPORTED_SURFACE: string;
     readonly TOKEN_REQUIRED: string;
+    readonly SCOPE_MISMATCH: string;
+    readonly SESSION_GONE: string;
+    readonly COMMAND_TIMEOUT: string;
+    readonly FLOW_STEP_MISSING: string;
+    readonly NO_POOL: string;
 };
-/** The actionable next move for a known error message, or undefined when none is recognized. */
+/**
+ * The actionable next move for a known error message, or undefined when none is recognized.
+ *
+ * A message that already carries its own next action gets NO second one. The no-session diagnosis
+ * inspects the machine and says which of three causes this actually is; pairing that with the
+ * generic "ask the human to start their app" produced a result that contradicted itself — the error
+ * saying a server is running and the recovery saying to go start one.
+ */
 export declare function recoveryFor(message: string): string | undefined;
 /**
  * The ask attached to errors we do NOT recognize. An unrecognized error is, by definition, the case
@@ -43,5 +61,5 @@ interface ErrorPayload {
  * known; the feedback ask is added when it is NOT — the two are mutually exclusive by design, so the
  * agent always gets exactly one next move.
  */
-export declare function buildErrorPayload(message: string): ErrorPayload;
+export declare function buildErrorPayload(rawMessage: string): ErrorPayload;
 export {};

package/dist/tools/error-recovery.js

@@ -8,6 +8,45 @@
  * on stable, human-authored substrings of the thrown messages (see session-manager.ts, the flow/
  * baseline stores). No clock, no IO — unit-testable in isolation.
  */
+import { TRANSPORT_LIMITS } from '@reticlehq/core';
+import { SELF_RECOVERING_MARKER } from '../session/no-session-diagnosis.js';
+/** Marks where an over-long message had its middle removed. Named so tests assert it by value. */
+const ELISION = '… [elided] …';
+/**
+ * Bound a message before the agent ever sees it, keeping BOTH ends.
+ *
+ * Error messages interpolate caller-supplied values — a ref, a baseline name, a selector — and
+ * nothing upstream bounds them, so a 100KB argument came back as a 100KB tool result. Capping here
+ * rather than at each throw site is deliberate: this is the single funnel every tool error passes
+ * through, so it also covers the tools nobody has written yet.
+ *
+ * The middle is what goes. Head-truncation would be simpler and wrong: the recovery table keys off
+ * substrings that sit at the END of the message ("… no longer resolves to an element"), so cutting
+ * the tail severs the part that makes an error recognizable and re-labels a known condition as a
+ * possible Reticle defect.
+ */
+function capMessage(message) {
+    const max = TRANSPORT_LIMITS.MAX_ERROR_LENGTH;
+    if (max >= message.length)
+        return message;
+    const keep = Math.floor((max - ELISION.length) / 2);
+    return `${message.slice(0, keep)}${ELISION}${message.slice(message.length - keep)}`;
+}
+/**
+ * Messages that already spell out the exact retry, so any hint we add can only argue with them.
+ *
+ * The no-session diagnosis is one (it inspected the machine and named the cause). The native-input
+ * refusal is the other: it names the tool, the argument and the follow-up call to make instead — and
+ * it was still collecting the defect ask, inviting a bug report about a refusal that had just told
+ * the agent precisely what to do.
+ */
+const SELF_RECOVERING = [/cannot drive native input/i];
+/** A message that already carries its own concrete next action, so nothing should be appended. */
+function isSelfRecovering(message) {
+    if (message.includes(SELF_RECOVERING_MARKER))
+        return true;
+    return SELF_RECOVERING.some((pattern) => pattern.test(message));
+}
 /** The recovery hints, named so they are not free strings and can be asserted in tests. */
 export const RECOVERY = {
     NO_SESSION: 'No app is connected to Reticle. Ask the human to start their app in dev with @reticlehq/browser ' +
@@ -21,18 +60,71 @@ export const RECOVERY = {
         'the tab to the front, or run `reticle drive <url>` for a guaranteed scriptable context.',
     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: 'No recording by that name is in progress. Start one with reticle_record { action: "start", name } ' +
-        'before annotating, stopping, or saving it.',
+    MISSING_RECORDING: 
+    // `recordingName`, not `name`. The hint said `name`, so an agent that followed it exactly got
+    // InvalidParams — a recovery that fails is worse than none, because it spends the retry.
+    'No recording by that name is in progress. Start one with ' +
+        'reticle_record { action: "start", recordingName } before annotating, stopping, or saving it.',
     STALE_REF: 'That ref is stale: refs are invalidated whenever the DOM re-renders, so any action that ' +
         'navigated, opened a modal, re-sorted a list or changed the page invalidates every ref taken ' +
         '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.',
+    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.',
+    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. ' +
+        'Retry with one of the listed values — note they are option VALUES, which often differ from the ' +
+        'visible labels shown in brackets. This is an invalid call, not a Reticle defect.',
     BAD_ARGUMENTS: "That call did not match the tool's schema — the message above names the tool and the exact " +
         "argument it wanted. Re-read that tool's parameters and retry with the missing or corrected " +
         'argument. This is an invalid call, not a Reticle defect: there is nothing to report.',
+    WRONG_TARGET: 'That action does not apply to this element — the ref resolved, the element just cannot take it ' +
+        '(you cannot fill a <button>, submit outside a form, or upload to anything but <input ' +
+        'type="file">). Call reticle_snapshot or reticle_query to find the control that does, or ' +
+        'reticle_inspect on this ref to see what it actually is. This is an invalid call, not a Reticle ' +
+        'defect: there is nothing to report.',
+    NOT_EDITABLE: 'The field is disabled or readonly, so a user could not edit it either — forcing the value would ' +
+        'put the app in a state nobody can reach, which is why Reticle refuses. This is usually the app ' +
+        '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.',
+    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.',
     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 ' +
+        'nothing is wrong with the app and there is nothing to report. The message above lists each ' +
+        'connected session with its sessionId: pass that sessionId to this tool to target it, or ' +
+        "restart the daemon from that app's directory so it becomes the default. Call reticle_sessions " +
+        'for the same list at any time.',
+    SESSION_GONE: 'The tab this call was targeting disconnected while the command was in flight, so the command ' +
+        'never completed — do not assume it applied or that it did not. Call reticle_sessions: a tab ' +
+        'that reloaded comes back under a NEW sessionId (every ref taken before it is gone — re-query), ' +
+        'and an empty list means the page was closed and the human has to reopen it.',
+    COMMAND_TIMEOUT: 'The page did not answer within the command window. That is a fact about the page, not a Reticle ' +
+        'failure: check reticle_sessions for `throttled`/`stale` on this session — a backgrounded tab is ' +
+        'throttled and may never answer, so ask the human to bring it to the front or drive your own ' +
+        'browser with reticle_lease. If the tab is in front, the page is busy or blocked (a long ' +
+        'synchronous task, an alert/confirm dialog); reticle_console usually shows what it hit. Retry ' +
+        'once the cause is addressed.',
+    FLOW_STEP_MISSING: 'A recorded step points at an element that is not on the page now. Either the app changed under ' +
+        'the flow — run reticle_flow_heal to re-anchor it, then reticle_flow_verify — or an earlier step ' +
+        'did not do what it used to, leaving the run on the wrong page: check reticle_snapshot to see ' +
+        'where it actually is. This is app/flow drift, which is exactly what the flow exists to catch.',
+    NO_POOL: 'Reticle cannot launch its own browser here: the daemon-managed pool is absent, or Playwright ' +
+        'has no Chromium installed (the message above says which). Run Reticle via `reticle mcp`, and ' +
+        'ask the human for `npx playwright install chromium` if that is what is missing. Meanwhile drive ' +
+        'a tab the human already has open — reticle_sessions lists them.',
 };
 /** Ordered match rules; the first hit wins. Substrings track the thrown messages they recover. */
 const RULES = [
@@ -43,9 +135,46 @@ const RULES = [
     { match: /no baseline named/i, hint: RECOVERY.MISSING_BASELINE },
     { match: /no (?:active|compiled) recording named/i, hint: RECOVERY.MISSING_RECORDING },
     { match: /pairing token is required/i, hint: RECOVERY.TOKEN_REQUIRED },
+    // Three conditions the daemon understands perfectly and still asked for a bug report about. Each
+    // needs its own rule: none of them contains "no browser session connected" (the scope miss is
+    // "no browser session FOR project 'x'", which is the opposite claim — sessions exist).
+    {
+        match: /scope mismatch|session\(s\) ARE connected under a different project/i,
+        hint: RECOVERY.SCOPE_MISMATCH,
+    },
+    { match: /^session disconnected$|session .* never connected/i, hint: RECOVERY.SESSION_GONE },
+    { match: /^command '[^']*' timed out after/i, hint: RECOVERY.COMMAND_TIMEOUT },
+    // Flow replay: the recorded anchor is gone. Ordinary drift, and the tool that fixes it exists.
+    { match: /did not resolve in current page/i, hint: RECOVERY.FLOW_STEP_MISSING },
+    {
+        match: /browser pool (?:unavailable|is shut down)|Chromium is not installed/i,
+        hint: RECOVERY.NO_POOL,
+    },
     // 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.
     { 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
+    // call, and ALL of them used to fall through to the feedback ask — including the destructive-action
+    // block, which carries its own retry instruction and was still telling the agent Reticle might be
+    // 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 \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.
+    {
+        match: /potentially destructive (?:\w+ )*(?:action|tool) blocked/i,
+        hint: RECOVERY.CONFIRM_DANGEROUS,
+    },
+    {
+        match: /^cannot [\w()]+ (?:a|an|into a|on a) <|no form to submit|upload target must be|is not an HTMLElement/i,
+        hint: RECOVERY.WRONG_TARGET,
+    },
+    // 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.
@@ -54,14 +183,42 @@ const RULES = [
         hint: RECOVERY.BAD_ARGUMENTS,
     },
 ];
-/** The actionable next move for a known error message, or undefined when none is recognized. */
+/**
+ * The actionable next move for a known error message, or undefined when none is recognized.
+ *
+ * A message that already carries its own next action gets NO second one. The no-session diagnosis
+ * inspects the machine and says which of three causes this actually is; pairing that with the
+ * generic "ask the human to start their app" produced a result that contradicted itself — the error
+ * saying a server is running and the recovery saying to go start one.
+ */
 export function recoveryFor(message) {
+    if (isSelfRecovering(message))
+        return undefined;
     for (const rule of RULES) {
         if (rule.match.test(message))
             return rule.hint;
     }
     return undefined;
 }
+/**
+ * A schema rejection: the call named a parameter that does not exist, or gave one the wrong type.
+ *
+ * Matched by the SHAPES the validators actually produce (zod's codes, and the MCP layer's wrapper),
+ * because these are our own machinery talking, not the app.
+ */
+const ARGUMENT_REJECTION = /Unrecognized key|unrecognized_keys|invalid_type|Invalid arguments for tool|Unknown parameters? for|^Required |Expected \w+, received/i;
+/**
+ * What to say instead of asking for a bug report. The schema already stated the problem precisely;
+ * this only says who can fix it and where to look.
+ */
+const ARGUMENT_RECOVERY = "That call did not match the tool's schema — the message above names the parameter. Nothing ran, " +
+    'so no result is affected. Call reticle_tools { names: ["<tool>"] } for its exact parameters and ' +
+    'retry.';
+/**
+ * `invalid <thing> name: <value>` — the shape every name validator in the server throws. Matched on
+ * the phrasing rather than per-caller so a new store that validates a name is covered by default.
+ */
+const INVALID_NAME_REJECTION = /^invalid (?:[a-z]+ )*name: /i;
 /**
  * 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
@@ -79,7 +236,25 @@ export const FEEDBACK_ASK = 'This error is not one Reticle recognizes, which mea
  * known; the feedback ask is added when it is NOT — the two are mutually exclusive by design, so the
  * agent always gets exactly one next move.
  */
-export function buildErrorPayload(message) {
+export function buildErrorPayload(rawMessage) {
+    // Cap FIRST, then classify on the capped text — so what the classifier reads is exactly what the
+    // agent reads. Classifying the full message and emitting a shorter one would let a recovery hint
+    // reference a phrase that is no longer there.
+    const message = capMessage(rawMessage);
+    // A self-diagnosing message gets NEITHER a generic recovery nor the feedback ask. It already
+    // inspected the machine and named the cause; a second, contradictory hint is noise, and inviting a
+    // bug report about a condition Reticle diagnosed itself is exactly backwards.
+    if (isSelfRecovering(message))
+        return { error: message };
+    // An argument rejection is the agent's to fix, not a Reticle defect. Reported from the field: a
+    // clean `unrecognized_keys: ["value"]` came back wrapped in "may be a defect in Reticle", which
+    // spends the agent's turn and fills the feedback channel with reports about malformed calls.
+    if (ARGUMENT_REJECTION.test(message))
+        return { error: message, recovery: ARGUMENT_RECOVERY };
+    // Reticle's own name validators rejecting a caller's value: an argument rejection that the schema
+    // cannot express (the shape is a runtime pattern, not a type), so it needs its own arm.
+    if (INVALID_NAME_REJECTION.test(message))
+        return { error: message, recovery: RECOVERY.INVALID_NAME };
     const recovery = recoveryFor(message);
     return recovery !== undefined
         ? { error: message, recovery }

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

@@ -12,7 +12,18 @@ export declare const FEEDBACK_PROMPT: {
     readonly ask: "Ask the human, in your own words and only once: how did this verification go, and what would have made Reticle more useful? If they answer, file it with `reticle feedback` (they run it) or relay it yourself.";
     readonly command: "reticle feedback";
 };
-/** Tools whose completion means "a verification just happened" — the only moment worth asking at. */
+/**
+ * Tools whose completion means "a verification just happened" — the only moment worth asking at,
+ * and the set that decides what `verification_completed` counts.
+ *
+ * ACT_AND_WAIT belongs here and was missing for a long time. It declares `verified` in its
+ * outputSchema, returns the whole verdict block, and its own description calls it "one hop for the
+ * act->observe->assert loop" — it IS the verification path most agents take. The guard that should
+ * have caught the omission keyed on the tool NAME (/assert|verify/), which act_and_wait does not
+ * match, so it slipped through in silence. Measured over a day of real telemetry: act_and_wait 14
+ * 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>;
 /**
  * The human prompt, when one is due. Resettable for tests.