@reticlehq/server 2.4.0 → 2.5.0

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.

package/dist/tools/feedback-tools.js

@@ -30,6 +30,9 @@ function sessionFacts(deps, sessionId) {
         return {
             ...(session.runtime !== undefined ? { runtime: session.runtime } : {}),
             ...(session.engine !== undefined ? { engine: session.engine } : {}),
+            // The app's own account of what it is. Without this the reported stack came from the daemon's
+            // working directory, so feedback from one app was filed against another's framework.
+            ...(0 < session.adapters.length ? { adapters: session.adapters } : {}),
             driven,
         };
     }
@@ -83,7 +86,10 @@ export const FEEDBACK_TOOLS = [
                 .describe('Only to attach a specific tab s runtime/engine context. Omit it — a report about a session that never connected is still worth filing.'),
         },
         outputSchema: {
+            /** Confirmed delivery. Always false here: the agent path queues and returns. */
             sent: z.boolean(),
+            /** Validated, redacted and queued. This is the one to read. */
+            accepted: z.boolean(),
             reason: z.string().optional(),
             redacted: z.array(z.string()),
             context: z.unknown(),
@@ -106,12 +112,17 @@ export const FEEDBACK_TOOLS = [
                 ...optionalText(args, 'impact'),
                 ...optionalText(args, 'currentApproach'),
                 ...optionalText(args, 'model'),
-            }, { session: sessionFacts(deps, asString(args['sessionId'])) });
+            }, {
+                session: sessionFacts(deps, asString(args['sessionId'])),
+                // The AGENT does not wait for the network. `reticle feedback` (a human, at a terminal,
+                // watching for an answer) still does — see submitFeedback's `background`.
+                background: true,
+            });
             return {
                 ...receipt,
-                note: receipt.sent
-                    ? 'Filed — thank you. Continue your task; do not retry a failing call just to re-report it.'
-                    : 'NOT sent (see reason). Tell the human what you found so it is not lost.',
+                note: receipt.accepted
+                    ? 'Accepted — thank you. It sends in the background so you are not kept waiting; if it fails you will be told on a later tool result. Continue your task; do not retry a failing call just to re-report it.'
+                    : 'NOT accepted (see reason). Tell the human what you found so it is not lost.',
             };
         },
     },
@@ -128,8 +139,20 @@ export const FEEDBACK_PROMPT = {
     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.',
     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 const VERIFICATION_TOOLS = new Set([
+    ReticleTool.ACT_AND_WAIT,
     ReticleTool.ASSERT,
     ReticleTool.FLOW_VERIFY,
     ReticleTool.VERIFY_CHANGE,

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

@@ -1,10 +1,4 @@
 import type { ToolDef, ToolDeps } from './tools.js';
-/**
- * The live-session tools whose result MUST carry the
- * session-health envelope. Owned in ONE place — not retrofitted per handler — so a throttled tab
- * can never return a healthy-looking result from any of these. `runTool` is the single choke point
- * (mcp.ts + tool-invoker.ts) that splices health on; the guard test asserts the set is exhaustive.
- */
 export declare const SESSION_BOUND_TOOLS: ReadonlySet<string>;
 /**
  * Tools that carry a `sessionId` arg but are NOT live-session-health tools — they read/write

package/dist/tools/invoke-tool.js

@@ -2,18 +2,32 @@ import { healthEnvelope } from '../session/session-health.js';
 import { TelemetryActor, TelemetryEventKind } from '@reticlehq/core';
 import { getSessionMetrics } from '../telemetry/session-metrics.js';
 import { getTelemetry } from '../telemetry/telemetry.js';
-import { VERIFICATION_TOOLS } from './feedback-tools.js';
 import { takeUpdateNudge } from '../update/update-nudge.js';
+import { takeVersionSkew } from '../version/version-nudge.js';
+import { noteToolCall } from '../daemon/daemon-usefulness.js';
 import { bugsInResult } from '../telemetry/bug-found.js';
+import { verificationOf } from '../telemetry/verification-of.js';
 import { asString } from './tools-helpers.js';
 import { ReticleTool } from './tool-names.js';
 import { takeFeedbackPrompt } from './feedback-tools.js';
+import { takeFeedbackUndelivered } from '../telemetry/feedback-delivery.js';
+import { span } from '../trace.js';
 /**
  * The live-session tools whose result MUST carry the
  * session-health envelope. Owned in ONE place — not retrofitted per handler — so a throttled tab
  * can never return a healthy-looking result from any of these. `runTool` is the single choke point
  * (mcp.ts + tool-invoker.ts) that splices health on; the guard test asserts the set is exhaustive.
  */
+/**
+ * Tools that DRIVE the page. An action with no verdict after it is the signature of the loop
+ * breaking mid-task — see `abandonedActions`. `act_and_wait` is one of these AND a verification, so
+ * it settles its own action, which is exactly right: it is the tool that does both.
+ */
+const ACTION_TOOLS = new Set([
+    ReticleTool.ACT,
+    ReticleTool.ACT_SEQUENCE,
+    ReticleTool.ACT_AND_WAIT,
+]);
 export const SESSION_BOUND_TOOLS = new Set([
     ReticleTool.SNAPSHOT,
     ReticleTool.QUERY,
@@ -72,44 +86,27 @@ export const SESSION_EXEMPT_TOOLS = new Set([
     ReticleTool.FEEDBACK,
 ]);
 function isPlainObject(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
+    return 'object' === typeof value && value !== null && !Array.isArray(value);
 }
 /**
  * Emit `verification_completed` when a verification tool produced a verdict.
  *
  * Read off the RESULT here rather than emitted from `decideVerified`, which is where the verdict is
  * actually decided: that function is pure, and the repo's rules keep clocks, IO and side effects out
- * of pure logic for good reason. Reading the result also means all four verification tools are covered
- * by one site instead of four handler edits, and a fifth is covered the moment it joins the set.
+ * of pure logic for good reason. Reading the result also means all the verification tools are covered
+ * by one site instead of N handler edits, and the next one is covered the moment it joins the set.
  *
- * `falseGreenCaught` is the one that matters: the assertion PASSED and Reticle still refused to call
- * it verified. That is the product's entire thesis reduced to a boolean, and it is the number worth
- * putting in front of an investor — not "tools were called" but "this many greens were caught lying".
+ * The RULE itself lives in verification-of.ts, because getting it wrong is silent and it feeds the
+ * one number shown to investors — see that file for the two ways it was wrong.
  */
-function recordVerification(toolName, result, durationMs) {
-    if (!VERIFICATION_TOOLS.has(toolName))
+function recordVerification(toolName, result, durationMs, brand) {
+    const verification = verificationOf(toolName, result, durationMs, brand);
+    if (verification === undefined)
         return;
-    const verified = typeof result['verified'] === 'string' ? result['verified'] : undefined;
-    // flow_verify reports `status: pass|fail`; assert reports a boolean `pass`. Accept either shape so
-    // the whole family is covered without normalizing four tools' contracts for a metric's convenience.
-    const passed = typeof result['pass'] === 'boolean'
-        ? result['pass']
-        : result['status'] === 'pass'
-            ? true
-            : undefined;
-    if (verified === undefined && passed === undefined)
-        return; // not a verdict-bearing result
-    const metrics = getSessionMetrics();
-    metrics.recordVerification();
+    getSessionMetrics().recordVerification();
     void getTelemetry().emit(TelemetryEventKind.VERIFICATION_COMPLETED, {
         actor: TelemetryActor.AGENT,
-        verification: {
-            via: toolName,
-            verified: verified ?? (passed === true ? 'yes' : 'no'),
-            passed: passed ?? verified === 'yes',
-            falseGreenCaught: passed === true && verified === 'no',
-            durationMs,
-        },
+        verification,
     });
 }
 /**
@@ -121,7 +118,7 @@ function recordVerification(toolName, result, durationMs) {
  */
 function reportBugsFound(toolName, result) {
     const bugs = bugsInResult(toolName, result);
-    if (bugs.length === 0)
+    if (0 === bugs.length)
         return;
     const metrics = getSessionMetrics();
     for (const bug of bugs) {
@@ -151,6 +148,12 @@ export async function runTool(tool, deps, args) {
     // Started/settled as a pair rather than a bare counter: several agents can be inside runTool at
     // once, so a single "last start" field would attribute one tool's duration to another. The returned
     // closure carries this call's own identity, which is also what makes peak-concurrency measurable.
+    // A daemon that has served even one tool call is doing a job for somebody; see daemon-usefulness.
+    noteToolCall();
+    // An ACTION is what gets abandoned. Counted here, against verifications, so "the agent drove the
+    // page and then wandered off" becomes a number instead of an impression.
+    if (ACTION_TOOLS.has(tool.name))
+        getSessionMetrics().recordAction();
     const settleTiming = getSessionMetrics().startToolCall(tool.name, args);
     const startedAt = Date.now();
     const rawSessionId = asString(args['sessionId']);
@@ -175,7 +178,10 @@ export async function runTool(tool, deps, args) {
         deps.pool?.touch(leaseId);
     let raw;
     try {
-        raw = await tool.handler(deps, args);
+        // The one dispatch point every tool call passes through, so it is where the trace's root span
+        // belongs: with RETICLE_TRACE on, every stage that runs underneath inherits this call's id and
+        // nests under it. Free when off — see trace.ts.
+        raw = await span('tool.handler', { tool: tool.name, session: session?.id }, () => tool.handler(deps, args));
     }
     finally {
         // In a `finally` so a THROWN call still settles: otherwise every failing tool would leak a
@@ -187,7 +193,10 @@ export async function runTool(tool, deps, args) {
     // session-bound early return, because two of the four verification tools (flow_verify,
     // verify_change) are session-EXEMPT and would otherwise never carry it.
     if (isPlainObject(raw)) {
-        recordVerification(tool.name, raw, Date.now() - startedAt);
+        // The brand comes from the session's own PAGE_HEALTH report, so it is present for the four
+        // session-bound verification tools and absent for flow_verify (session-exempt) — which replays
+        // into a browser Reticle launched, where `browser` already says what happened.
+        recordVerification(tool.name, raw, Date.now() - startedAt, session?.brand);
         reportBugsFound(tool.name, raw);
     }
     const prompt = isPlainObject(raw) ? takeFeedbackPrompt(tool.name) : undefined;
@@ -195,12 +204,28 @@ export async function runTool(tool, deps, args) {
     // and ASK for is something it will never ask for. Spliced on ANY tool result, not just a
     // verification, because an out-of-date install is worth mentioning whatever the agent is doing.
     const update = isPlainObject(raw) ? takeUpdateNudge() : undefined;
-    const result = prompt === undefined && update === undefined
+    // Same one-shot channel, for the same reason. Skew was only ever reported in
+    // reticle_sessions.versionSkew and a CLI log line — two places an agent driving a flow never
+    // looks — so it could work a whole session against a mismatched pair and never learn the one fact
+    // that explains the behaviour. It rides out here on whatever tool it happens to be calling.
+    const skew = isPlainObject(raw) ? takeVersionSkew() : undefined;
+    // A feedback report that was accepted and then failed to send. Same one-shot channel, because the
+    // reporter is the only person who can act on it and they are not reading the daemon log — and a
+    // report announced as accepted and then silently lost is the failure the awaited send existed to
+    // prevent. See feedback-delivery.ts.
+    const undelivered = isPlainObject(raw) ? takeFeedbackUndelivered() : undefined;
+    const result = prompt === undefined && update === undefined && skew === undefined && undelivered === undefined
         ? raw
         : {
             ...raw,
             ...(prompt !== undefined ? { feedback_prompt: prompt } : {}),
             ...(update !== undefined ? { update_available: update } : {}),
+            ...(skew !== undefined ? { version_skew: skew } : {}),
+            ...(undelivered !== undefined
+                ? {
+                    feedback_undelivered: `your earlier report did NOT send: ${undelivered}. Tell the human what you found so it is not lost.`,
+                }
+                : {}),
         };
     if (!bound || !isPlainObject(result))
         return result;

package/dist/tools/lease-hint.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Why a leased tab did not dial in.
+ *
+ * The lease pool opens the app itself, which is what makes it the highest-value path in the product
+ * — it does not wait for the human's tab. Measured over a day: lease sessions had a median of 30
+ * tool calls and produced 46% of all bugs found, against a median of 1 call for everything else.
+ *
+ * When it fails it is almost always a PORT MISMATCH: the tab loads, and the app's SDK dials the port
+ * it was BUILT with, which need not be the daemon that issued the lease. Verified by driving it —
+ * against a matching daemon `acquire` returns ready:true and the session is driveable immediately;
+ * against a different one the tab connects to the OTHER daemon instead.
+ *
+ * The old hint asked "is <url> running with @reticlehq/core enabled?", which is the one thing that
+ * cannot be in doubt: the pool just navigated a real browser to it. Naming the true cause first is
+ * the difference between a two-minute fix and abandoning the best path Reticle has.
+ */
+export declare function leaseNotConnectedHint(url: string, port: number): string;

package/dist/tools/lease-hint.js

@@ -0,0 +1,24 @@
+/**
+ * Why a leased tab did not dial in.
+ *
+ * The lease pool opens the app itself, which is what makes it the highest-value path in the product
+ * — it does not wait for the human's tab. Measured over a day: lease sessions had a median of 30
+ * tool calls and produced 46% of all bugs found, against a median of 1 call for everything else.
+ *
+ * When it fails it is almost always a PORT MISMATCH: the tab loads, and the app's SDK dials the port
+ * it was BUILT with, which need not be the daemon that issued the lease. Verified by driving it —
+ * against a matching daemon `acquire` returns ready:true and the session is driveable immediately;
+ * against a different one the tab connects to the OTHER daemon instead.
+ *
+ * The old hint asked "is <url> running with @reticlehq/core enabled?", which is the one thing that
+ * cannot be in doubt: the pool just navigated a real browser to it. Naming the true cause first is
+ * the difference between a two-minute fix and abandoning the best path Reticle has.
+ */
+export function leaseNotConnectedHint(url, port) {
+    return (`the leased tab loaded ${url} but never dialled this daemon (port ${String(port)}). The usual ` +
+        `cause is a PORT MISMATCH: the app's SDK connects to the port it was BUILT with, so a daemon on ` +
+        `a different port never hears from it — check the app's reticle port (\`.reticle.json\`, ` +
+        `RETICLE_PORT, or the build plugin's \`port\`) matches ${String(port)}, or start the daemon on ` +
+        `the port the app expects. If the app carries no Reticle SDK at all, run \`reticle init\` in it ` +
+        `first. The tab stays leased either way — release it with reticle_lease{action:"release"}.`);
+}

package/dist/tools/lease-tools.js

@@ -9,7 +9,8 @@
  * Attach-only: the pool drives a browser against an already-running dev server — it never starts one.
  */
 import { z } from 'zod';
-import { RETICLE_URL_PARAM } from '@reticlehq/core';
+import { leaseNotConnectedHint } from './lease-hint.js';
+import { RETICLE_URL_PARAM, RETICLE_DEFAULT_PORT } from '@reticlehq/core';
 import { ReticleTool } from './tool-names.js';
 import { asString } from './tools-helpers.js';
 const POOL_UNAVAILABLE = 'browser pool unavailable — the lease tools need the daemon-managed pool (start Reticle via `reticle mcp`).';
@@ -58,7 +59,7 @@ export function cleanNavError(err) {
 }
 /** A fresh, collision-resistant lease id. Uses crypto at the I/O boundary (not pure logic). */
 function newLeaseId() {
-    const uuid = typeof globalThis.crypto?.randomUUID === 'function'
+    const uuid = 'function' === typeof globalThis.crypto?.randomUUID
         ? globalThis.crypto.randomUUID()
         : `${String(Date.now())}-${String(performance.now())}`;
     return `lease-${uuid}`;
@@ -119,7 +120,7 @@ export const LEASE_TOOLS = [
             if (pool === undefined)
                 throw new Error(POOL_UNAVAILABLE);
             const url = asString(args['url']);
-            if (url === undefined || url.length === 0)
+            if (url === undefined || 0 === url.length)
                 throw new Error('reticle_lease{action:"acquire"} requires a url');
             const projectId = asString(args['projectId']);
             const sessionId = newLeaseId();
@@ -144,7 +145,7 @@ export const LEASE_TOOLS = [
                 ...(ready
                     ? {}
                     : {
-                        hint: `leased tab did not connect — is ${url} running with @reticlehq/core enabled?`,
+                        hint: leaseNotConnectedHint(url, deps.bridgePort ?? RETICLE_DEFAULT_PORT),
                     }),
             };
         },
@@ -166,7 +167,7 @@ export const LEASE_TOOLS = [
             if (pool === undefined)
                 throw new Error(POOL_UNAVAILABLE);
             const sessionId = asString(args['sessionId']);
-            if (sessionId === undefined || sessionId.length === 0) {
+            if (sessionId === undefined || 0 === sessionId.length) {
                 throw new Error('reticle_lease{action:"release"} requires a sessionId');
             }
             await pool.release(sessionId);

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

@@ -16,11 +16,13 @@ import type { ToolDef } from './tool-kit.js';
  * like flow_replay/flow_verify/flow_heal that return their own documented verdict shapes — are NOT
  * merged. Only sibling families whose value is the capability, not the contract, are consolidated.
  */
-export interface MergeSpec {
+interface MergeSpec {
     name: string;
     description: string;
     /** action value → the original tool whose handler serves it. */
     actions: Record<string, ToolDef>;
+    /** A concrete call, carried through to the merged def (see ToolDef.example). */
+    example?: Record<string, unknown>;
 }
 /** A merge declared by member NAME, resolved against the assembled tool list. */
 export interface MergePlan {
@@ -28,6 +30,12 @@ export interface MergePlan {
     description: string;
     /** action value → the existing tool name whose handler serves it. */
     members: Record<string, string>;
+    /**
+     * A concrete call for the merged tool. Merging discards the members' own examples — the schema is
+     * a union and theirs are per-member — so a merged tool that reaches the core surface has no
+     * example at all unless the plan states one.
+     */
+    example?: Record<string, unknown>;
 }
 /**
  * Apply the consolidation to an assembled tool list: drop each plan's members and each retired name from
@@ -40,3 +48,4 @@ export interface MergePlan {
  */
 export declare function applyMerges(tools: readonly ToolDef[], plans: readonly MergePlan[], retired?: readonly string[]): ToolDef[];
 export declare function mergeTools(spec: MergeSpec): ToolDef;
+export {};