@reticlehq/server 2.7.0 → 2.9.0

package/dist/tools/browser-tools.js

@@ -39,6 +39,12 @@ export const BROWSER_TOOLS = [
             // reload:true is the absorbed reticle_refresh — same command, one fewer advertised tool.
             if (true === args['reload']) {
                 const before = deps.sessions.resolve(asString(args['sessionId']));
+                // The verdict floor moves HERE, before the page goes away. A reload destroys the document,
+                // so every request that failed under the old one belongs to a page that no longer exists —
+                // and a later assert defaulting its window to "the last thing that happened" must not reach
+                // back past this point. Reported from the field as an assertion whose clauses all passed
+                // coming back `contradicted` by hundreds of 500s against resources that were already gone.
+                before.lastAct.markNavigated(before.elapsed());
                 await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.REFRESH, {
                     hard: true === args['hard'],
                 });
@@ -65,6 +71,10 @@ export const BROWSER_TOOLS = [
             // reconnects), but the action record itself — "navigated to X" — is the causal fact worth keeping.
             const session = deps.sessions.resolve(asString(args['sessionId']));
             session.beginAction(ReticleTool.NAVIGATE, { url });
+            // Same floor as the reload path above, for the same reason: going to a new URL replaces the
+            // document just as thoroughly. `beginAction` attributes events to this action; it does not move
+            // the window a later assert judges over, and those are two different jobs.
+            session.lastAct.markNavigated(session.elapsed());
             try {
                 const result = (await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.NAVIGATE, { url }));
                 // `ok` is the browser accepting the instruction, not the page arriving — see navigate-result.

package/dist/tools/contract-tools.js

@@ -38,6 +38,10 @@ export const CONTRACT_TOOLS = [
     {
         name: ReticleTool.CAPABILITIES,
         description: 'The app-advertised testable surface (reticle.describe): testids, signals, stores, and named flows. Call this first to learn what to assert on without reading source. Pass { fromDisk:true } to read the git-checked .reticle/contract.json instead of the live session (a fresh agent can learn the surface with no browser attached).',
+        // Every core tool carries one, so an agent reading the surface never has to guess the shape.
+        // `fromDisk` is the example deliberately: it is the call that works with nothing attached, which
+        // is the state a fresh agent is actually in when it first reads this list.
+        example: { [FROM_DISK_ARG]: true },
         inputSchema: { [FROM_DISK_ARG]: z.boolean().optional(), ...sessionIdShape },
         outputSchema: {
             testids: z.array(z.string()),

package/dist/tools/dynamic-tools.js

@@ -65,11 +65,12 @@ export function buildDynamicTools(allTools, profile) {
         : {
             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.`,
+                // This used to say `full` carries no meta-tools because it advertised everything
+                // directly. That stopped being true when the advertised surface was capped: no surface
+                // 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.`,
             },
         };
     const reticleTools = {
@@ -86,10 +87,18 @@ export function buildDynamicTools(allTools, profile) {
                 ? args['names'].filter((n) => 'string' === typeof n)
                 : undefined;
             if (names === undefined || 0 === names.length) {
+                // The COUNT is stated, not just implied by the array length. An agent that can see 18 tools
+                // has no way to know whether that is all of them; being told the registry holds more is what
+                // turns "these are the tools" into "these are the tools I was shown".
+                const catalog = allTools.map((t) => ({
+                    name: t.name,
+                    summary: firstSentence(t.description),
+                }));
                 return Promise.resolve({
-                    tools: allTools.map((t) => ({ name: t.name, summary: firstSentence(t.description) })),
+                    total: catalog.length,
+                    tools: catalog,
                     ...profileBlock,
-                    next: 'Load 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 }.`,
                 });
             }
             return Promise.resolve({

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

@@ -8,6 +8,7 @@
  * 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 { RefusalReason } from '@reticlehq/core';
 /** The recovery hints, named so they are not free strings and can be asserted in tests. */
 export declare const RECOVERY: {
     readonly NO_SESSION: string;
@@ -40,6 +41,15 @@ export declare const RECOVERY: {
  * saying a server is running and the recovery saying to go start one.
  */
 export declare function recoveryFor(message: string): string | undefined;
+/**
+ * WHY a tool refused, as one of the six buckets in core's `RefusalReason`.
+ *
+ * Reads the SAME rules `buildErrorPayload` reads, in the same order, so the reason we report and the
+ * advice the agent got can never describe different things. Anything unrecognised is `other`, which
+ * is the bucket that says the classifier has a blind spot — and a growing `other` is a finding about
+ * 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.
  *

package/dist/tools/error-recovery.js

@@ -8,7 +8,7 @@
  * 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 { RefusalReason, TRANSPORT_LIMITS } from '@reticlehq/core';
 import { SELF_RECOVERING_MARKER } from '../session/no-session-diagnosis.js';
 import { chromiumInstallCommand, bundledPlaywrightVersion } from '../cli/chromium-hint.js';
 /** Marks where an over-long message had its middle removed. Named so tests assert it by value. */
@@ -42,24 +42,26 @@ function capMessage(message) {
  * the agent precisely what to do.
  */
 const SELF_RECOVERING = [
-    /cannot drive native input/i,
+    { match: /cannot drive native input/i, reason: RefusalReason.UNSUPPORTED },
     // The unknown-session refusal now lists the live ids inline. Appending "call reticle_sessions for
     // the current ids" to a message that just named them contradicts the shorter path it offers, and
     // a contradicted instruction is how one agent came to retry a dead id twelve times.
-    /Connected right now:/i,
+    { match: /Connected right now:/i, reason: RefusalReason.NO_SESSION },
 ];
 /** 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));
+    return SELF_RECOVERING.some((rule) => rule.match.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 ' +
-        'enabled, then run `reticle status` to confirm a session appears. If the app is running but no ' +
-        'session shows, the SDK is not reaching the bridge — check the dev server is up and using the ' +
-        'configured Reticle port.',
+    NO_SESSION: "No app is connected to Reticle. If nothing is serving the app, start the project's own dev " +
+        'script (from its package.json) in the BACKGROUND yourself and tell the human in one line that ' +
+        'it is running and how to stop it — never a second server, never a guessed command, never kill ' +
+        'anything. Then run `reticle status` to confirm a session appears. If the app IS running and no ' +
+        'session shows, the SDK is not reaching the bridge — check @reticlehq/browser is loaded in the ' +
+        'page and that both sides use the configured Reticle port.',
     MULTIPLE_SESSIONS: 'Several tabs are connected. Call reticle_sessions to list them, then pass an explicit sessionId to ' +
         '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.',
@@ -121,7 +123,9 @@ export const RECOVERY = {
     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 ' +
+        'browser 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. 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 ' +
@@ -137,6 +141,39 @@ export const RECOVERY = {
         '` if that is what is missing. Meanwhile drive ' +
         'a tab the human already has open — reticle_sessions lists them.',
 };
+/**
+ * Which OWNER each recovery belongs to, for `tool_refused`.
+ *
+ * A `Record` over the recovery keys rather than a second table of patterns, and that is the point:
+ * adding a recovery without classifying it does not compile. A parallel regex list would have been
+ * correct on the day it was written and silently wrong at the next addition — the drift that has
+ * already cost this repo a published number twice, and telemetry drift is not recoverable after the
+ * fact.
+ */
+const REASON_OF = {
+    NO_SESSION: RefusalReason.NO_SESSION,
+    MULTIPLE_SESSIONS: RefusalReason.NO_SESSION,
+    UNKNOWN_SESSION: RefusalReason.NO_SESSION,
+    SCOPE_MISMATCH: RefusalReason.NO_SESSION,
+    SESSION_GONE: RefusalReason.NO_SESSION,
+    THROTTLED: RefusalReason.NOT_READY,
+    COMMAND_TIMEOUT: RefusalReason.NOT_READY,
+    NO_POOL: RefusalReason.NOT_READY,
+    TOKEN_REQUIRED: RefusalReason.NOT_READY,
+    MISSING_BASELINE: RefusalReason.NO_MATCH,
+    MISSING_RECORDING: RefusalReason.NO_MATCH,
+    STALE_REF: RefusalReason.NO_MATCH,
+    NO_SUCH_OPTION: RefusalReason.NO_MATCH,
+    FLOW_STEP_MISSING: RefusalReason.NO_MATCH,
+    UNSUPPORTED_SURFACE: RefusalReason.UNSUPPORTED,
+    NOT_EDITABLE: RefusalReason.UNSUPPORTED,
+    CONFIRM_DANGEROUS: RefusalReason.UNSUPPORTED,
+    WRONG_TARGET: RefusalReason.UNSUPPORTED,
+    BAD_ARGUMENTS: RefusalReason.BAD_ARGS,
+    INVALID_NAME: RefusalReason.BAD_ARGS,
+};
+/** Hint text back to its reason. The hints are distinct strings, so this inverts cleanly. */
+const REASON_BY_HINT = new Map(Object.entries(RECOVERY).map(([key, hint]) => [hint, REASON_OF[key]]));
 /** Ordered match rules; the first hit wins. Substrings track the thrown messages they recover. */
 const RULES = [
     { match: /no browser session connected/i, hint: RECOVERY.NO_SESSION },
@@ -216,6 +253,33 @@ export function recoveryFor(message) {
     }
     return undefined;
 }
+/**
+ * WHY a tool refused, as one of the six buckets in core's `RefusalReason`.
+ *
+ * Reads the SAME rules `buildErrorPayload` reads, in the same order, so the reason we report and the
+ * advice the agent got can never describe different things. Anything unrecognised is `other`, which
+ * is the bucket that says the classifier has a blind spot — and a growing `other` is a finding about
+ * this table rather than about anybody's app.
+ */
+export function refusalReasonFor(rawMessage) {
+    const message = zodArrayAsSentence(rawMessage);
+    // The no-session diagnosis inspected the machine and named the cause itself, so it never reaches
+    // the recovery table. It is the single largest refusal there is; missing it would gut the metric.
+    if (message.includes(SELF_RECOVERING_MARKER))
+        return RefusalReason.NO_SESSION;
+    for (const rule of SELF_RECOVERING) {
+        if (rule.match.test(message))
+            return rule.reason;
+    }
+    // Same order as buildErrorPayload: a schema rejection is the agent's own call, whatever else in
+    // the message might also match.
+    if (ARGUMENT_REJECTION.test(message))
+        return RefusalReason.BAD_ARGS;
+    if (INVALID_NAME_REJECTION.test(message))
+        return RefusalReason.BAD_ARGS;
+    const hint = recoveryFor(message);
+    return (hint === undefined ? undefined : REASON_BY_HINT.get(hint)) ?? RefusalReason.OTHER;
+}
 /**
  * A schema rejection: the call named a parameter that does not exist, or gave one the wrong type.
  *

package/dist/tools/feedback-invite.js

@@ -38,7 +38,7 @@ export const FrictionKind = {
 const REPEAT_INVITE_AT = 3;
 const LINES = {
     [FrictionKind.UNKNOWN_TOOL]: 'no such tool — reticle_feedback tells us what you expected it to do, which is how it gets built',
-    [FrictionKind.UNKNOWN_VERDICT]: 'Reticle could not tell what happened here. If you expected otherwise, reticle_feedback — an ' +
+    [FrictionKind.UNKNOWN_VERDICT]: 'Reticle could not tell what happened here. If you expected otherwise, reticle_feedback. An ' +
         'unknown verdict is our defect, not yours',
     [FrictionKind.REPEATING]: 'stuck on the same call? reticle_feedback — say what you were trying to do and it gets fixed',
     [FrictionKind.REFUSED]: 'if that diagnosis was wrong or unhelpful, reticle_feedback — error messages are a product ' +

package/dist/tools/invoke-tool.js

@@ -1,18 +1,23 @@
 import { healthEnvelope } from '../session/session-health.js';
-import { TelemetryActor, TelemetryEventKind, TRANSPORT_LIMITS, } from '@reticlehq/core';
+import { TelemetryActor, TelemetryEventKind, TRANSPORT_LIMITS, fingerprintFinding, } from '@reticlehq/core';
 import { getSessionMetrics } from '../telemetry/session-metrics.js';
 import { getTelemetry } from '../telemetry/telemetry.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 { bugsInResult, routeOf } from '../telemetry/bug-found.js';
+import { noteToolServed, reportToolRefused } from '../telemetry/tool-refused.js';
+import { buildErrorPayload, refusalReasonFor } from './error-recovery.js';
+import { resultIsError } from '../mcp/mcp-is-error.js';
 import { verificationOf } from '../telemetry/verification-of.js';
 import { asString } from './tools-helpers.js';
 import { EnvelopeKey } from './tool-kit.js';
 import { ReticleTool } from './tool-names.js';
 import { takeFeedbackPrompt } from './feedback-tools.js';
 import { takeFeedbackUndelivered } from '../telemetry/feedback-delivery.js';
+import { noteRefsMinted, wrongTabRefusal } from '../session/ref-provenance.js';
 import { span } from '../trace.js';
+import { deltaForToolResult, impactSnapshot, initImpact, recordImpact, } from '../impact/impact-recorder.js';
 import { frictionOf, inviteFor } from './feedback-invite.js';
 /**
  * The live-session tools whose result MUST carry the
@@ -30,6 +35,20 @@ const ACTION_TOOLS = new Set([
     ReticleTool.ACT_SEQUENCE,
     ReticleTool.ACT_AND_WAIT,
 ]);
+/**
+ * Tools whose result hands the agent refs. The tab they were minted in is remembered, so the call
+ * that spends one cannot be routed to a different tab without saying so — see ref-provenance.ts.
+ *
+ * Over-inclusion is the safe direction here and under-inclusion is not dangerous either: both ends
+ * produce a REFUSAL naming the two tabs, never a silent drive against the wrong one.
+ */
+const REF_MINTING_TOOLS = new Set([
+    ReticleTool.SNAPSHOT,
+    ReticleTool.QUERY,
+    ReticleTool.INSPECT,
+    ReticleTool.EXPLORE,
+    ReticleTool.CRAWL,
+]);
 export const SESSION_BOUND_TOOLS = new Set([
     ReticleTool.SNAPSHOT,
     ReticleTool.QUERY,
@@ -123,17 +142,70 @@ function reportBugsFound(toolName, result) {
     if (0 === bugs.length)
         return;
     const metrics = getSessionMetrics();
+    const route = routeOf(result);
     for (const bug of bugs) {
         // `recordBug` answers whether this kind is new to the session, which is the only thing that
         // separates "another defect" from "the same defect again". Counting instances as defects is how
         // a published number inflates itself.
         const first = metrics.recordBug(bug.kind);
+        const identity = route !== undefined
+            ? { kind: bug.kind, source: bug.source, route }
+            : { kind: bug.kind, source: bug.source };
+        const fingerprint = fingerprintFinding(identity);
         void getTelemetry().emit(TelemetryEventKind.BUG_FOUND, {
             actor: TelemetryActor.AGENT,
-            bug: { ...bug, repeat: !first },
+            bug: { ...bug, repeat: !first, fingerprint },
         });
     }
 }
+/**
+ * Report a refused call, at the one place both dispatch paths cross.
+ *
+ * A refusal arrives two ways and they are the same event: the handler THROWS (the common case — no
+ * session, a stale ref, a schema rejection), or it RETURNS `{ error }`, which is this codebase's
+ * refusal convention and just as much a refusal. Both are classified by the same table the agent's
+ * recovery advice comes from, so the reason we record and the advice it got cannot describe
+ * different things.
+ *
+ * `reticle_run` is skipped for the same reason `bugsInResult` skips it: it is a WRAPPER whose
+ * handler calls `runTool` on the real tool, which already reported that refusal under the real
+ * tool's name, and then hands the same failure back out to be reported a second time as
+ * `reticle_run`. A count that doubles because of HOW a tool was reached is not a measurement.
+ */
+function reportRefusal(toolName, message) {
+    if (toolName === ReticleTool.RUN)
+        return;
+    reportToolRefused(toolName, refusalReasonFor(message));
+}
+/**
+ * Which friction this result represents, counting the invitation if there is one.
+ *
+ * Feedback is the highest-yield channel this product has, and `feedbackPrompted` is the denominator
+ * that says whether inviting mid-task works or is decoration. It read as near-empty because the
+ * count sat behind the session-bound early return, so a session-EXEMPT tool never invited and a tool
+ * that THREW never got there — and a throw is the commonest refusal there is.
+ *
+ * `reticle_run` is skipped for the same reason it is skipped for refusals and defects: the wrapper's
+ * handler calls `runTool` on the real tool, which already invited under the real tool's name, and
+ * the failure is then handed back out to be counted a second time. A doubled denominator makes the
+ * feedback rate read half.
+ */
+function frictionInviteFor(toolName, raw) {
+    if (!isPlainObject(raw) || toolName === ReticleTool.RUN)
+        return undefined;
+    const friction = frictionOf({
+        unknownTool: false,
+        verifiedUnknown: 'unknown' === raw['verified'],
+        repeatRun: getSessionMetrics().currentRun,
+        errored: resultIsError(raw),
+        // A verdict is progress. Without this, three successful act_and_wait calls in a row — the exact
+        // loop this release exists to encourage — get told they are stuck.
+        producedVerdict: 'verified' in raw,
+    });
+    if (friction !== undefined)
+        getSessionMetrics().recordFeedbackPrompt();
+    return friction;
+}
 /**
  * The single entry point both the MCP server and the programmatic invoker call instead of
  * `tool.handler` directly. Runs the handler, then — for a live-session tool returning a plain
@@ -173,6 +245,9 @@ export async function runTool(tool, deps, args) {
     // 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();
+    // The impact record needs the project's own `.reticle` root, and this is the first place every
+    // call knows it. Idempotent: the first root wins for the daemon's lifetime.
+    initImpact({ reticleRoot: deps.reticleRoot });
     // An oversized argument is refused BEFORE the handler deserialises it.
     //
     // tool-fuzz failed CI on the invariant that matters most — `every tool answers every hostile call`
@@ -189,11 +264,13 @@ export async function runTool(tool, deps, args) {
     // prevents: the agent learns its argument was too big, which is something it can fix.
     const oversized = firstOversizedArg(args);
     if (oversized !== undefined) {
-        return {
-            error: `argument '${oversized}' is larger than ${String(TRANSPORT_LIMITS.MAX_STRING_LENGTH)} ` +
-                'characters, which is the most Reticle moves in one call. Nothing ran. Send a smaller ' +
-                'value — a selector or an id rather than a document, or a slice of the text you need.',
-        };
+        const error = `argument '${oversized}' is larger than ${String(TRANSPORT_LIMITS.MAX_STRING_LENGTH)} ` +
+            'characters, which is the most Reticle moves in one call. Nothing ran. Send a smaller ' +
+            'value — a selector or an id rather than a document, or a slice of the text you need.';
+        // Refused before the handler was ever entered, and still a refusal the agent has to recover
+        // from. Reported here rather than at the return below, which this branch never reaches.
+        reportRefusal(tool.name, error);
+        return { error };
     }
     // 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.
@@ -218,6 +295,25 @@ export async function runTool(tool, deps, args) {
             session = undefined;
         }
     }
+    // A ref that was handed out by a DIFFERENT tab, on a call that named no session. Refused here, at
+    // the one point that knows both the ref and the tab resolution picked — the handler only learns
+    // that the ref missed, and answers that with "the DOM re-rendered", which is a confident diagnosis
+    // of the wrong thing. The other half is worse: the same ref can resolve to a different element in
+    // the guessed tab and return a green about a page nobody asked about.
+    if (session !== undefined) {
+        const wrongTab = wrongTabRefusal({
+            ref: asString(args['ref']),
+            explicitSessionId: rawSessionId,
+            chosenSessionId: session.id,
+            connected: () => deps.sessions.list(),
+        });
+        if (wrongTab !== undefined) {
+            // Refused before the handler was entered, so it is reported here — the same shape as the
+            // oversized-argument refusal above.
+            reportRefusal(tool.name, wrongTab);
+            return { error: wrongTab };
+        }
+    }
     const leaseId = session?.id ?? rawSessionId;
     if (leaseId !== undefined)
         deps.pool?.touch(leaseId);
@@ -228,6 +324,22 @@ export async function runTool(tool, deps, args) {
         // nests under it. Free when off — see trace.ts.
         raw = await span('tool.handler', { tool: tool.name, session: session?.id }, () => tool.handler(deps, args));
     }
+    catch (error) {
+        // The commonest refusal shape by far, and the one nothing could see: the message is built, handed
+        // to the agent by the MCP boundary, and discarded. Reported here rather than at that boundary
+        // because there are two of them (mcp.ts and the reticle_run hatch) and this is the one place both
+        // go through — a third would otherwise be invisible from the day it was added.
+        const message = error instanceof Error ? error.message : String(error);
+        reportRefusal(tool.name, message);
+        // The invitation on THIS path is the one `buildErrorPayload` attaches when it does not recognise
+        // the error, and it was never counted — so the denominator excluded the commonest friction there
+        // is. Gated on the payload actually carrying the ask, because a recognised error gets a recovery
+        // instead and counting an invitation nobody was shown breaks the ratio in the other direction.
+        if (tool.name !== ReticleTool.RUN && buildErrorPayload(message).feedback !== undefined) {
+            getSessionMetrics().recordFeedbackPrompt();
+        }
+        throw error;
+    }
     finally {
         // In a `finally` so a THROWN call still settles: otherwise every failing tool would leak a
         // concurrency slot and peakConcurrentTools would climb forever on an unhealthy session.
@@ -244,6 +356,28 @@ export async function runTool(tool, deps, args) {
         recordVerification(tool.name, raw, Date.now() - startedAt, session?.brand);
         reportBugsFound(tool.name, raw);
     }
+    // The other half of the refusal surface. A top-level `error` string IS this codebase's refusal
+    // convention, so half the tools refuse by RETURNING one rather than throwing — and reading only the
+    // throw path would have measured half the wall and called it the whole of it, the same way `isError`
+    // once did. A call that was served clears the retry chain, so the next refusal after it is a first
+    // refusal rather than a retry of something unrelated.
+    // The user's own record of what Reticle did for them. Same chokepoint as everything else that
+    // counts, for the same reason: a second recording site is a second thing to forget. Separate
+    // store from telemetry - this one never leaves the machine.
+    recordImpact(deltaForToolResult(raw, Date.now() - startedAt, resultIsError(raw)));
+    // ...and the tab being driven is told, so the report is live rather than a thing you reload.
+    // Optional-call, not optional-chain-on-the-object: a test double is a partial Session, and a
+    // courtesy push must never be the reason a tool call throws.
+    session?.pushImpact?.(impactSnapshot);
+    if (resultIsError(raw))
+        reportRefusal(tool.name, raw.error);
+    else {
+        noteToolServed();
+        // Which tab these refs belong to. Recorded on the way OUT, so the next call that spends one is
+        // measured against the tab that actually produced it.
+        if (session !== undefined && REF_MINTING_TOOLS.has(tool.name))
+            noteRefsMinted(session.id);
+    }
     const prompt = isPlainObject(raw) ? takeFeedbackPrompt(tool.name) : undefined;
     // Same one-shot channel as the feedback ask: the agent is mid-task, so anything it would have to go
     // and ASK for is something it will never ask for. Spliced on ANY tool result, not just a
@@ -259,10 +393,26 @@ export async function runTool(tool, deps, args) {
     // 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
+    // Invite feedback at the moment of friction, worded for what just happened. Counted, because
+    // `feedback_submitted / feedbackPrompted` is the only thing that says whether the invitation works
+    // at all rather than being decoration.
+    //
+    // This used to sit below the session-bound early return, which put it behind two conditions that
+    // exclude most friction there is. A session-EXEMPT tool never reached it, and neither did a tool
+    // that THREW — and throwing is the commonest refusal shape by a wide margin, i.e. exactly the
+    // `refused` friction the line is written for. `errored` could only ever see the handlers that
+    // RETURN an error. So the denominator was counting a small, unrepresentative slice of the
+    // invitations and reading near-empty, which looks identical to a nudge that never fires.
+    const friction = frictionInviteFor(tool.name, raw);
+    const result = prompt === undefined &&
+        update === undefined &&
+        skew === undefined &&
+        undelivered === undefined &&
+        friction === undefined
         ? raw
         : {
             ...raw,
+            ...(friction !== undefined ? { [EnvelopeKey.FEEDBACK_INVITE]: inviteFor(friction) } : {}),
             ...(prompt !== undefined ? { [EnvelopeKey.FEEDBACK_PROMPT]: prompt } : {}),
             ...(update !== undefined ? { [EnvelopeKey.UPDATE_AVAILABLE]: update } : {}),
             ...(skew !== undefined ? { [EnvelopeKey.VERSION_SKEW]: skew } : {}),
@@ -298,22 +448,5 @@ export async function runTool(tool, deps, args) {
     const unverified = getSessionMetrics().takeUnverifiedNudge();
     if (unverified !== undefined)
         envelope[EnvelopeKey.VERIFY_NEXT] = unverified;
-    // Invite feedback at the moment of friction, worded for what just happened. Feedback produced
-    // ~11 of this release's fixes from 14 reports; the handshake instruction is what got those 14,
-    // and this closes the gap it leaves — the agent mid-problem, not thinking about feedback tooling.
-    // Counted so `feedback_submitted / feedbackPrompted` can tell us whether it works at all.
-    const friction = frictionOf({
-        unknownTool: false,
-        verifiedUnknown: 'unknown' === result.verified,
-        repeatRun: getSessionMetrics().currentRun,
-        errored: 'error' in result,
-        // A verdict is progress. Without this, three successful act_and_wait calls in a row — the exact
-        // loop this release exists to encourage — get told they are stuck.
-        producedVerdict: 'verified' in result,
-    });
-    if (friction !== undefined) {
-        envelope[EnvelopeKey.FEEDBACK_INVITE] = inviteFor(friction);
-        getSessionMetrics().recordFeedbackPrompt();
-    }
     return Object.keys(envelope).length > 0 ? { ...result, ...envelope } : result;
 }

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

@@ -5,13 +5,35 @@
  * — 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.
+ * cannot be in doubt: the pool just navigated a real browser to it. Its replacement then swung to
+ * the other confident-but-unevidenced claim — "the usual cause is a PORT MISMATCH" — and the daemon
+ * ended up contradicting ITSELF inside one response, saying in `reticle_sessions` that a session had
+ * connected earlier "so the wiring is correct" and here that the port was probably wrong. Across a
+ * batch of field reports on four apps the port was correct every single time, and `reticle init`
+ * would have been the wrong action every single time.
+ *
+ * So: rank by what the daemon actually knows, and fall back to the differential only when it knows
+ * nothing. A cause we hold positive evidence against is not printed at all.
  */
-export declare function leaseNotConnectedHint(url: string, port: number): string;
+/** What the daemon can say for certain at the moment a lease comes back unconnected. */
+export interface LeaseEvidence {
+    /** A dial WAS made and turned away, with the reason. The only certain cause there is. */
+    refusal?: string;
+    /** An app for this project has connected on this port before (durable, survives a restart). */
+    previouslyConnected?: boolean;
+    /** The project has been through `init` — so recommending it again cannot help. */
+    initialized?: boolean;
+    /** The framework `.reticle.json` declares, used to rank rather than to decorate. */
+    framework?: string;
+    /**
+     * Whether any Reticle marker was found in the page the lease loaded.
+     *
+     * The single bit that separates the two commonest cases — "this app ships no SDK" and "the SDK
+     * loaded but could not reach the daemon" — which today produce identical messages. Absent means
+     * NOT CHECKED, and an absent bit prints nothing: a marker check that could not run must not be
+     * reported as a marker that was not found.
+     */
+    sdkMarker?: boolean;
+}
+export declare function leaseNotConnectedHint(url: string, port: number, evidence?: LeaseEvidence): string;