@reticlehq/server 2.5.0 → 2.6.0

package/dist/telemetry/telemetry.js

@@ -18,7 +18,7 @@ import { spawn } from 'node:child_process';
 import { randomUUID, createHash } from 'node:crypto';
 import { appendFileSync, readFileSync, writeFileSync, mkdirSync, existsSync, rmSync, } from 'node:fs';
 import { homedir, platform } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { TelemetryEventKind, TELEMETRY_EVENT_VERSION, ProjectIdSource, isSessionScoped, } from '@reticlehq/core';
 import { SERVER_VERSION } from '../version/server-version.js';
 const RETICLE_DIR = join(homedir(), '.reticle');
@@ -144,17 +144,40 @@ const resolveIdentity = () => {
  * credentials, `.git` suffix and case removed) so `git@github.com:acme/web.git` and
  * `https://github.com/Acme/web` are recognized as the same project rather than two.
  */
-const projectFingerprint = (cwd) => {
-    const { origin } = gitFacts(cwd);
+export const projectFingerprint = (cwd) => {
+    const { origin, root } = gitFacts(cwd);
+    // Ordered by stability, not by preference: an origin is comparable across machines, a repo root is
+    // stable across every directory inside one machine's checkout, a package.json root is the same for
+    // a non-git project — and the raw cwd is stable across nothing, which is why it is last. See
+    // `project-identity.test.ts` for what a wrong order costs.
+    const { key, source } = origin !== undefined
+        ? { key: origin, source: ProjectIdSource.GIT_ORIGIN }
+        : root !== undefined
+            ? { key: root, source: ProjectIdSource.GIT_ROOT }
+            : packageRoot(cwd) !== null
+                ? { key: packageRoot(cwd) ?? cwd, source: ProjectIdSource.PACKAGE_ROOT }
+                : { key: cwd, source: ProjectIdSource.CWD };
     return {
-        projectId: createHash('sha256')
-            .update(origin ?? cwd)
-            .digest('hex')
-            .slice(0, 32),
+        projectId: createHash('sha256').update(key).digest('hex').slice(0, 32),
         // Reported alongside so the analytics knows whether this id is comparable to another machine's.
-        source: origin !== undefined ? ProjectIdSource.GIT_ORIGIN : ProjectIdSource.CWD,
+        source,
     };
 };
+/** Nearest ancestor holding a package.json — the project boundary when there is no git. */
+const packageRoot = (cwd) => {
+    let dir = cwd;
+    // Same bound as the git walk: deep monorepos are well inside 20, and an unbounded loop on a
+    // pathological path would hang the CLI's startup.
+    for (let depth = 0; depth < 20; depth += 1) {
+        if (existsSync(join(dir, 'package.json')))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+    return null;
+};
 /** Print the opt-out notice exactly once per machine (honest disclosure, the OSS-trust bar). */
 const showNoticeOnce = () => {
     try {

package/dist/tools/act-tools.js

@@ -11,6 +11,7 @@ import { assertNativeInputSupported } from './act-danger.js';
 import { leanActResult, mutatedWithin } from './act-view.js';
 import { ReticleTool } from './tool-names.js';
 import { buildReactionReport, summarizeReaction } from '../events/reaction.js';
+import { parsePredicate } from '../events/predicate-parse.js';
 import { causalSummary } from '../capsule/causal-summary.js';
 import { findContradictions } from '../events/contradictions.js';
 import { decideVerified } from '../honesty/verified.js';
@@ -19,7 +20,7 @@ import { saveFailedAssertCapsule } from './act-capsule.js';
 import { buildDivergenceCapsule } from '../capsule/capsule.js';
 import { predicateToExpectedLinks } from '../capsule/predicate-to-links.js';
 import { buildHonestyBlock } from '../honesty/honesty.js';
-import { buildCoverageStatement, blindSpotsFromState, Coverage, impeachesCapture, } from '../honesty/blind-spots.js';
+import { buildCoverageStatement, blindSpotsFromState, transportGapNote, Coverage, impeachesCapture, } from '../honesty/blind-spots.js';
 import { hasAcceptedWrite } from '../honesty/accepted-write.js';
 import { hasUnreadWriteOutcome } from '../honesty/unread-outcome.js';
 import { evaluatePredicate, waitForPredicate, provenExpectedLinks, PredicateSchema, } from '../events/predicate.js';
@@ -54,7 +55,7 @@ export const ACT_TOOLS = [
     {
         name: ReticleTool.ACT,
         example: { ref: 'e42', action: 'fill', args: { value: 'hello' } },
-        description: 'Execute one action against a ref: click|dblclick|hover|focus|fill|type|clear|select|check|uncheck|submit|press|scrollIntoView. Returns immediately with a `since` cursor — observe the reaction with reticle_observe. For a VERDICT instead of a cursor use reticle_act_and_wait { until } — the same action plus the assertion, in one call; prefer it whenever the action is supposed to cause something. Carries effect:{dispatched,targetMatched,visible,enabled,focusMoved,valueChanged,domMutatedWithin,occluded,occludedBy,scrolledIntoView} to tell "action missed" from "app didn\'t react"; dispatched=landed, settled=a real frame flushed, and a settle timeout never fails the tool. Fields at their uninformative default are OMITTED so a clean action collapses to its consequence: an absent dispatched/targetMatched/visible/enabled means true, an absent occluded/scrolledIntoView/valueChanged/defaultPrevented means false, an absent focusMoved/occludedBy means null. occluded=true means the click point is covered by another element (a real user could not click it) — synthetic dispatch still delivered the event; scrolledIntoView=true means an off-viewport target was scrolled in first. inputMode is "real" (native CDP, no synthetic effect block) or "synthetic"; clicks default to the occlusion-honest synthetic path even when CDP is configured — pass args.native:true to force a trusted native click (file pickers, clipboard). inputModeReason explains any real→synthetic choice so it is never silent. Full model (real-input, throttled tabs, `reticle drive`): docs/usage.md §18.',
+        description: 'Act WITHOUT checking the result — if the action is supposed to cause something, use reticle_act_and_wait { until } instead and get the verdict in the same call. This tool returns immediately with a `since` cursor; observe the reaction yourself with reticle_observe. Use it for actions with no observable consequence to assert (focus, hover, scrollIntoView, a fill you are about to submit). One action against a ref: click|dblclick|hover|focus|fill|type|clear|select|check|uncheck|submit|press|scrollIntoView. Carries effect:{dispatched,targetMatched,visible,enabled,focusMoved,valueChanged,domMutatedWithin,occluded,occludedBy,scrolledIntoView} to tell "action missed" from "app didn\'t react"; dispatched=landed, settled=a real frame flushed, and a settle timeout never fails the tool. Fields at their uninformative default are OMITTED so a clean action collapses to its consequence: an absent dispatched/targetMatched/visible/enabled means true, an absent occluded/scrolledIntoView/valueChanged/defaultPrevented means false, an absent focusMoved/occludedBy means null. occluded=true means the click point is covered by another element (a real user could not click it) — synthetic dispatch still delivered the event; scrolledIntoView=true means an off-viewport target was scrolled in first. inputMode is "real" (native CDP, no synthetic effect block) or "synthetic"; clicks default to the occlusion-honest synthetic path even when CDP is configured — pass args.native:true to force a trusted native click (file pickers, clipboard). args.holdMs keeps the pointer DOWN for that long between mousedown and mouseup — the only way to drive a hold-to-confirm control (hold-to-delete, hold-to-record, long-press); effect.heldMs reports the hold actually achieved, which a throttled background tab can stretch. args.confirmDangerous is a permission gate and NOT a duration: it allows a destructive control, it does not hold one. inputModeReason explains any real→synthetic choice so it is never silent. Full model (real-input, throttled tabs, `reticle drive`): docs/usage.md §18.',
         inputSchema: {
             ref: z
                 .string()
@@ -63,7 +64,7 @@ export const ACT_TOOLS = [
             args: z
                 .record(z.unknown())
                 .optional()
-                .describe('Action-specific arguments: { value } for fill/select, { text } for type/press, { native: true } to force a trusted native click, { confirmDangerous: true } to allow a potentially destructive control.'),
+                .describe('Action-specific arguments: { value } for fill/select, { text } for type/press, { native: true } to force a trusted native click, { holdMs: N } to keep the pointer DOWN for N ms (hold-to-confirm controls; effect.heldMs reports what was achieved), { confirmDangerous: true } to allow a potentially destructive control — a permission gate, NOT a duration.'),
             refuseWhenThrottled: z
                 .boolean()
                 .optional()
@@ -172,7 +173,18 @@ export const ACT_TOOLS = [
     },
     {
         name: ReticleTool.ACT_SEQUENCE,
-        description: 'Run multiple actions in order (fill -> fill -> submit) in one round-trip. Returns per-step effects[] (see reticle_act).',
+        // The example is required for a core tool, and this one carries weight: the measured loop it
+        // replaces is literally a login form driven as three separate reticle_act calls (98 clicks and
+        // 21 fills inside looping sessions, 2026-08-10/11). Showing fill -> fill -> click is showing the
+        // exact shape an agent otherwise spends three round trips on.
+        example: {
+            steps: [
+                { ref: 'e12', action: 'fill', args: { value: 'a@b.com' } },
+                { ref: 'e13', action: 'fill', args: { value: 'hunter2' } },
+                { ref: 'e14', action: 'click' },
+            ],
+        },
+        description: 'Run multiple actions in order (fill -> fill -> submit) in ONE round-trip. Prefer this over repeating reticle_act for a multi-step journey, then assert its consequence once. Returns per-step effects[] (see reticle_act).',
         inputSchema: {
             steps: z
                 .array(z.record(z.unknown()))
@@ -264,6 +276,10 @@ export const ACT_TOOLS = [
                 pass: z.boolean(),
                 evidence: z.unknown().optional(),
                 failureReason: z.string().optional(),
+                observationLost: z
+                    .boolean()
+                    .optional()
+                    .describe('The tab disconnected mid-wait, so this was never observed — the verdict is UNKNOWN, not a failure of the app.'),
                 // The STRUCTURED cause — observed / expected / assertion — is what the repair literature ranks
                 // above the prose failureReason (structured feedback beat narrative by 10.5pp) and above a bare
                 // pointer. `verdict` is `await waitForPredicate(...)`, whose EvalResult carries these on a
@@ -332,7 +348,7 @@ export const ACT_TOOLS = [
             // `predicate` is what reticle_assert / reticle_wait_for call this — see alias-args.ts.
             const withUntil = aliasParam(args, 'until', ['predicate']);
             const until = withUntil['until'] !== undefined
-                ? PredicateSchema.parse(withUntil['until'])
+                ? parsePredicate(withUntil['until'])
                 : { kind: PredicateKind.SETTLED };
             const timeout = asNumber(args['timeout_ms']) ?? DEFAULT_ASSERT_TIMEOUT_MS;
             // Before anything is driven: this path cannot honour a native-input request, and taking the
@@ -404,12 +420,19 @@ export const ACT_TOOLS = [
                 // structural boundary (virtualized rows, a cross-origin frame) is reported as coverage and
                 // must not downgrade a verdict about what WAS observed.
                 const impeaching = buildCoverageStatement(spots.filter((s) => impeachesCapture(s.kind)));
+                // Same rule as reticle_assert: a browser-side transport gap means part of this window was
+                // never seen, which is what `blindSpots` exists to say. `truncated` above covers the SERVER
+                // ring buffer evicting; this covers the BROWSER queue overflowing, and they are not the same
+                // loss — an act_and_wait that graded `proved` over 34 dropped events said so in a sentence
+                // whose own words were "over a clean capture".
+                const gapNote = transportGapNote(windowEvents);
+                const impeachingNotes = [impeaching.note, gapNote].filter((n) => n !== undefined);
                 const honesty = buildHonestyBlock({
                     grade: gradeOf(gradedLinks),
                     attribution: 'window',
                     truncated: session.bufferHealth().dropped > droppedBefore,
                     coveragePartial: Coverage.PARTIAL === coverage.coverage,
-                    ...(impeaching.note === undefined ? {} : { blindSpots: [impeaching.note] }),
+                    ...(0 === impeachingNotes.length ? {} : { blindSpots: impeachingNotes }),
                 });
                 const capsuleSaved = await saveFailedAssertCapsule({
                     deps,
@@ -436,6 +459,10 @@ export const ACT_TOOLS = [
                     ...(alreadyTrue ? { alreadyTrue } : {}),
                     // An assertion nobody could evaluate must not be reported as one the app failed.
                     ...(verdict.inconclusive === undefined ? {} : { inconclusive: verdict.inconclusive }),
+                    // Nor must one nobody could OBSERVE. This is the act path, so it is the one that produced
+                    // the measured false red: a reload mid-wait, graded assertion_failed at the clicked
+                    // component's own file and line.
+                    ...(true === verdict.observationLost ? { observationLost: true } : {}),
                     honesty,
                     contradictions,
                     ...(outcomePending ? { outcomePending } : {}),

package/dist/tools/assert-verdict.d.ts

@@ -16,7 +16,13 @@ import { type Contradiction } from '../events/contradictions.js';
  */
 export declare function assertVerdict(session: Session, predicate: Predicate, pass: boolean, since: number, 
 /** Set when the assertion was never evaluated — see honesty/verified.ts. */
-inconclusive?: string): Promise<{
+inconclusive?: string, 
+/**
+ * Set when the tab went away mid-wait, so the assertion was never OBSERVED. `reticle_assert` and
+ * `reticle_wait_for` reach the same disconnect path as the act tools, and a verdict that blames
+ * the app for a lost connection is no more honest on this route than on that one.
+ */
+observationLost?: boolean): Promise<{
     decision: Record<string, unknown>;
     contradictions: Contradiction[];
     coverage: Record<string, unknown>;

package/dist/tools/assert-verdict.js

@@ -1,5 +1,5 @@
 import { findContradictions } from '../events/contradictions.js';
-import { blindSpotsFromState, buildCoverageStatement, Coverage, impeachesCapture, } from '../honesty/blind-spots.js';
+import { blindSpotsFromState, buildCoverageStatement, Coverage, impeachesCapture, transportGapNote, } from '../honesty/blind-spots.js';
 import { buildHonestyBlock } from '../honesty/honesty.js';
 import { hasAcceptedWrite } from '../honesty/accepted-write.js';
 import { hasUnreadWriteOutcome } from '../honesty/unread-outcome.js';
@@ -20,7 +20,13 @@ import { gradeOfPredicate } from './assert-grade.js';
  */
 export async function assertVerdict(session, predicate, pass, since, 
 /** Set when the assertion was never evaluated — see honesty/verified.ts. */
-inconclusive) {
+inconclusive, 
+/**
+ * Set when the tab went away mid-wait, so the assertion was never OBSERVED. `reticle_assert` and
+ * `reticle_wait_for` reach the same disconnect path as the act tools, and a verdict that blames
+ * the app for a lost connection is no more honest on this route than on that one.
+ */
+observationLost) {
     // Scope caveat, stated because it is a real limitation and not a bug: blind spots are tracked per
     // SESSION, not per assertion window, so a cross-origin iframe seen once marks every later verdict
     // in that session partial — including ones about a region it cannot affect. That errs toward
@@ -46,16 +52,22 @@ inconclusive) {
     // Only a spot that IMPEACHES the capture downgrades a verdict. A structural boundary (virtualized
     // rows, a cross-origin frame) is reported as coverage and must not impugn what WAS observed.
     const impeaching = buildCoverageStatement(spots.filter((sp) => impeachesCapture(sp.kind)));
+    // A gap in the WINDOW, as opposed to a standing limit of the page. Both mean the same thing to the
+    // rule — part of what happened was not seen — so both belong in `blindSpots`, which is the only
+    // input `decideVerified` reads for that.
+    const gap = transportGapNote(windowEvents);
+    const impeachingNotes = [impeaching.note, gap].filter((n) => n !== undefined);
     const outcomePending = hasAcceptedWrite(windowEvents);
     const outcomeUnread = hasUnreadWriteOutcome(windowEvents);
     const decision = decideVerified({
         pass,
         ...(inconclusive === undefined ? {} : { inconclusive }),
+        ...(true === observationLost ? { observationLost: true } : {}),
         honesty: buildHonestyBlock({
             grade: gradeOfPredicate(predicate),
             attribution: 'window',
             coveragePartial: Coverage.PARTIAL === statement.coverage,
-            ...(impeaching.note === undefined ? {} : { blindSpots: [impeaching.note] }),
+            ...(0 === impeachingNotes.length ? {} : { blindSpots: impeachingNotes }),
         }),
         contradictions,
         ...(outcomePending ? { outcomePending } : {}),

package/dist/tools/browser-tools.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { navigateResult } from './navigate-result.js';
+import { awaitArrival } from './navigate-arrival.js';
 import { reloadResult } from './reload-result.js';
 import { waitForReconnect, RELOAD_RECONNECT_TIMEOUT_MS } from '../session/session-reconnect.js';
 import { ReticleCommand } from '@reticlehq/core';
@@ -10,7 +11,7 @@ export const BROWSER_TOOLS = [
     {
         name: ReticleTool.NAVIGATE,
         example: { url: '/settings' },
-        description: 'Navigate the connected browser tab to a URL, or reload it in place with { reload: true } (add { hard: true } to bypass the cache). `ok` means the navigation was DISPATCHED, not that the page arrived — the SDK is torn down by the navigation, so nothing can observe the new document. Call reticle_sessions to confirm a session reconnected at the new URL before acting.',
+        description: 'Navigate the connected browser tab to a URL, or reload it in place with { reload: true } (add { hard: true } to bypass the cache). `ok` means the navigation was DISPATCHED — the SDK is torn down by the navigation, so the page itself cannot report on it. The daemon then waits briefly for the SDK to reconnect: `confirmed:true` with a new `sessionId` means the page arrived and you can act immediately. `confirmed:false` means it did not arrive within the window — the page may be slow, uninstrumented, or not there; check reticle_sessions before acting.',
         inputSchema: {
             url: z.string().optional().describe('The URL to navigate to. Omit when using reload.'),
             reload: z
@@ -30,6 +31,8 @@ export const BROWSER_TOOLS = [
             // Present on a dispatched navigation: nothing here can see the new document, so arrival is
             // reported as unconfirmed rather than implied by `ok`. See navigate-result.ts.
             confirmed: z.boolean().optional(),
+            /** The session the SDK reconnected as, when arrival was confirmed — it is a NEW id. */
+            sessionId: z.string().optional(),
             note: z.string().optional(),
         },
         handler: async (deps, args) => {
@@ -65,7 +68,10 @@ export const BROWSER_TOOLS = [
             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.
-                return navigateResult(result);
+                // The daemon is the only party that CAN see arrival (the SDK reconnects to it), so it looks,
+                // briefly, instead of telling the agent to go poll reticle_sessions itself.
+                const arrival = true === result.ok ? await awaitArrival(deps.sessions, url) : null;
+                return navigateResult(result, arrival);
             }
             finally {
                 session.finishAction();

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

@@ -1,7 +1,2 @@
 import type { ToolDef } from './tools.js';
-/**
- * The capability-contract tools. `reticle_capabilities` reads the live session, or the
- * git-checked `.reticle/contract.json` when `{ fromDisk:true }`; `reticle_contract_save` persists the
- * live registry to that file (pretty-printed, stable key order — diffable in PRs).
- */
 export declare const CONTRACT_TOOLS: ToolDef[];

package/dist/tools/contract-tools.js

@@ -9,6 +9,31 @@ import { reticleDirPaths, readContract, writeContract } from '../project/reticle
  * git-checked `.reticle/contract.json` when `{ fromDisk:true }`; `reticle_contract_save` persists the
  * live registry to that file (pretty-printed, stable key order — diffable in PRs).
  */
+/**
+ * Refuse to persist one project's surface into another project's repo.
+ *
+ * `writeContract` writes to the DAEMON's `.reticle/`, which is the directory the daemon was started
+ * in — not the session's project. A daemon started above several apps therefore saves app A's
+ * testids into app B's checkout, reports `saved: true`, and hands back a path that looks right. A
+ * contract is git-checked and diffable, so that is a change somebody commits.
+ *
+ * Refuse rather than redirect: a session advertises a projectId, not a project DIRECTORY, so there
+ * is no honest way to work out where the correct `.reticle/` lives. Naming both ids and stopping is
+ * the whole of what can be said truthfully.
+ *
+ * Silence is not a mismatch. An unstamped build carries no projectId, and a daemon above an
+ * uninitialised directory has none either; neither is evidence of two projects.
+ */
+function assertSameProject(deps, sessionId) {
+    const mine = deps.projectId;
+    const theirs = deps.sessions.resolve(sessionId).projectId;
+    if (mine === undefined || theirs === undefined || mine === theirs)
+        return;
+    throw new Error(`refusing to save: this session belongs to project '${theirs}', but this daemon writes to ` +
+        `project '${mine}' (.reticle/ in the directory it was started in). Saving would put one ` +
+        "app's testable surface into another app's git-checked contract. Run a daemon from " +
+        `'${theirs}'s own directory and save there.`);
+}
 export const CONTRACT_TOOLS = [
     {
         name: ReticleTool.CAPABILITIES,
@@ -54,6 +79,7 @@ export const CONTRACT_TOOLS = [
         handler: async (deps, args) => {
             const res = await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.CAPABILITIES, {});
             const caps = CapabilitiesSchema.parse(res);
+            assertSameProject(deps, asString(args['sessionId']));
             await writeContract(deps.fs, deps.reticleRoot, caps, deps.now);
             return {
                 saved: true,

package/dist/tools/dynamic-tools.js

@@ -141,7 +141,12 @@ export function buildDynamicTools(allTools, profile) {
             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();
+                //
+                // The NAME goes with it: the count says the surface confused someone, the name says which
+                // capability they expected. It was already in hand here and thrown away, so the one place
+                // the product could learn what agents want was discarding it. Safe — a name from our own
+                // tool namespace, never app data.
+                getSessionMetrics().recordUnknownTool(name);
                 // ...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);

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

@@ -40,6 +40,20 @@ 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;
+/**
+ * A serialized zod issue array, rendered as a sentence. Anything else is returned untouched.
+ *
+ * This is the one boundary every agent-visible tool failure crosses, which is why the rewrite lives
+ * here rather than in each tool. `parsePredicate` solved this for the three predicate tools by never
+ * producing the array; it cannot help anywhere else, because the MCP SDK validates a tool's schema
+ * BEFORE our handler runs. So `reticle_session` with no action — the commonest mistake there is —
+ * never reaches the friendly "unknown action … expected: [tune, yield, …]" its handler already
+ * builds, and the agent gets the raw array instead. Driven live against the shipped daemon.
+ *
+ * Conservative by construction: it only rewrites a JSON ARRAY whose every element carries both
+ * `code` and `message`. A tool that legitimately returns JSON is left alone.
+ */
+export declare function zodArrayAsSentence(message: string): string;
 /**
  * The ask attached to errors we do NOT recognize. An unrecognized error is, by definition, the case
  * where Reticle failed in a way nobody anticipated — the single highest-value moment to hear from the

package/dist/tools/error-recovery.js

@@ -40,7 +40,13 @@ function capMessage(message) {
  * 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];
+const SELF_RECOVERING = [
+    /cannot drive native input/i,
+    // 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,
+];
 /** A message that already carries its own concrete next action, so nothing should be appended. */
 function isSelfRecovering(message) {
     if (message.includes(SELF_RECOVERING_MARKER))
@@ -167,8 +173,13 @@ const RULES = [
         match: /potentially destructive (?:\w+ )*(?:action|tool) blocked/i,
         hint: RECOVERY.CONFIRM_DANGEROUS,
     },
+    // Split in two because `^` binds to the FIRST alternative only. As one pattern this read as though
+    // the anchor governed all four spellings; it never did, and the next person to add a fifth would
+    // have had a coin-flip's chance of getting the behaviour they intended. The anchored spelling is
+    // one Reticle authors at the start of its own message; the other three appear mid-message.
+    { match: /^cannot [\w()]+ (?:a|an|into a|on a) </i, hint: RECOVERY.WRONG_TARGET },
     {
-        match: /^cannot [\w()]+ (?:a|an|into a|on a) <|no form to submit|upload target must be|is not an HTMLElement/i,
+        match: /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.
@@ -205,8 +216,74 @@ export function recoveryFor(message) {
  *
  * 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.
+ *
+ * `did not parse` is the shape `parsePredicate` produces. It was added because removing the raw zod
+ * array from that path ALSO removed the codes this pattern keys on — so a malformed predicate
+ * stopped being recognised as the agent's mistake and started being blamed on Reticle, complete with
+ * a request for a bug report. The e2e battery caught it (`no bad argument is blamed on Reticle`);
+ * no unit test could, which is why one now exists below.
+ */
+/** Max issues rendered — a union rejection can emit one per member, which is how the array became unreadable. */
+const MAX_RENDERED_ISSUES = 3;
+function isZodIssue(value) {
+    if (typeof value !== 'object' || null === value)
+        return false;
+    const v = value;
+    return 'string' === typeof v['code'] && 'string' === typeof v['message'];
+}
+/** `["net","urlContains"]` → `net.urlContains`; an empty path means the object itself. */
+function issueClause(issue) {
+    if ('unrecognized_keys' === issue.code && Array.isArray(issue.keys)) {
+        return `unknown field ${issue.keys.map(String).join(', ')}`;
+    }
+    const path = issue.path ?? [];
+    return `${0 === path.length ? 'the arguments' : path.map(String).join('.')}: ${issue.message}`;
+}
+/**
+ * A serialized zod issue array, rendered as a sentence. Anything else is returned untouched.
+ *
+ * This is the one boundary every agent-visible tool failure crosses, which is why the rewrite lives
+ * here rather than in each tool. `parsePredicate` solved this for the three predicate tools by never
+ * producing the array; it cannot help anywhere else, because the MCP SDK validates a tool's schema
+ * BEFORE our handler runs. So `reticle_session` with no action — the commonest mistake there is —
+ * never reaches the friendly "unknown action … expected: [tune, yield, …]" its handler already
+ * builds, and the agent gets the raw array instead. Driven live against the shipped daemon.
+ *
+ * Conservative by construction: it only rewrites a JSON ARRAY whose every element carries both
+ * `code` and `message`. A tool that legitimately returns JSON is left alone.
+ */
+export function zodArrayAsSentence(message) {
+    const text = message.trim();
+    if (!text.startsWith('['))
+        return message;
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return message; // not JSON at all — e.g. prose that happens to open with a bracket
+    }
+    if (!Array.isArray(parsed) || 0 === parsed.length || !parsed.every(isZodIssue))
+        return message;
+    const shown = parsed.slice(0, MAX_RENDERED_ISSUES).map(issueClause).join('; ');
+    const rest = parsed.length - MAX_RENDERED_ISSUES;
+    return rest > 0 ? `${shown} (and ${String(rest)} more)` : shown;
+}
+/**
+ * `unknown field` and `<path>: Required` are the shapes `zodArrayAsSentence` produces.
+ *
+ * Added for the same reason `did not parse` was: rendering the array as a sentence REMOVES the very
+ * codes (`invalid_type`, `unrecognized_keys`) this pattern matched on, so a schema rejection fell
+ * through to the generic branch and came back as "may be a defect in Reticle" — worse than the dump
+ * it replaced, because it also asks for a bug report about the agent's own malformed call. This repo
+ * has now made that mistake twice; the second time a test caught it before CI did.
+ *
+ * Widened a THIRD time for PR #182, which formats the MCP SDK's validation error at the argument
+ * boundary — "Missing required parameter for reticle_session: action (one of: …)". That is better
+ * prose than the field-level sentence below (it names the TOOL and the allowed VALUES) and it was
+ * authored before this formatter existed, so it must not be punished for arriving first.
  */
-const ARGUMENT_REJECTION = /Unrecognized key|unrecognized_keys|invalid_type|Invalid arguments for tool|Unknown parameters? for|^Required |Expected \w+, received/i;
+const ARGUMENT_REJECTION = /Unrecognized key|unrecognized_keys|invalid_type|did not parse|unknown field|: Required\b|Missing required parameter|Invalid parameter for|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.
@@ -237,10 +314,9 @@ export const FEEDBACK_ASK = 'This error is not one Reticle recognizes, which mea
  * agent always gets exactly one next move.
  */
 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);
+    // Render the zod array BEFORE capping: the cap would otherwise truncate the JSON mid-issue and
+    // leave an unparseable fragment as the agent's error text — the worst of both shapes.
+    const message = capMessage(zodArrayAsSentence(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.

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

@@ -0,0 +1,48 @@
+/**
+ * The one line that tells an agent it can push back — worded for what just happened.
+ *
+ * Feedback is the highest-yield channel this product has: **14 reports over two days produced
+ * roughly 11 of the fixes in 2.6.0**, against ~6,100 numeric events that produced a funnel which
+ * turned out to be broken. Prose from an agent at the moment of friction beats any structured field
+ * we could add.
+ *
+ * It reached those 14 through a standing instruction in the MCP handshake — paid once at connect.
+ * The gap that leaves is the agent who hits something mid-task and is concentrating on the problem
+ * rather than on remembering that a feedback tool exists.
+ *
+ * So: invite at the moment of friction, and vary the wording. A fixed string repeated forty times
+ * is invisible by call five; a line that names what just went wrong is read because it is about the
+ * thing the agent is already looking at. ~12 tokens against a ~4,546 tok/turn surface.
+ *
+ * Every invite is counted (`feedbackPrompted`). If `feedback_submitted ÷ feedbackPrompted` stays
+ * flat, this is decoration and should be deleted — instrumenting our own nudge is the difference
+ * between a designed system and a hope.
+ */
+/** What just happened, as far as the chokepoint can tell. Ordered most specific first. */
+export declare const FrictionKind: {
+    /** A tool that does not exist — the agent named a capability it expected us to have. */
+    readonly UNKNOWN_TOOL: "unknown_tool";
+    /** A verdict came back `unknown`: we drove the app and could not tell what happened. */
+    readonly UNKNOWN_VERDICT: "unknown_verdict";
+    /** The same tool, several times in a row. */
+    readonly REPEATING: "repeating";
+    /** The tool refused or errored. */
+    readonly REFUSED: "refused";
+};
+export type FrictionKind = (typeof FrictionKind)[keyof typeof FrictionKind];
+/**
+ * Which friction, if any, this result represents.
+ *
+ * Deliberately reads only what the chokepoint already has: no handler changes, and nothing here can
+ * see app data.
+ */
+export declare function frictionOf(facts: {
+    unknownTool: boolean;
+    verifiedUnknown: boolean;
+    repeatRun: number;
+    errored: boolean;
+    /** Did this call produce a verdict? A verdict is progress, and progress is not being stuck. */
+    producedVerdict: boolean;
+}): FrictionKind | undefined;
+/** The line for a friction kind. */
+export declare function inviteFor(kind: FrictionKind): string;

package/dist/tools/feedback-invite.js

@@ -0,0 +1,71 @@
+/**
+ * The one line that tells an agent it can push back — worded for what just happened.
+ *
+ * Feedback is the highest-yield channel this product has: **14 reports over two days produced
+ * roughly 11 of the fixes in 2.6.0**, against ~6,100 numeric events that produced a funnel which
+ * turned out to be broken. Prose from an agent at the moment of friction beats any structured field
+ * we could add.
+ *
+ * It reached those 14 through a standing instruction in the MCP handshake — paid once at connect.
+ * The gap that leaves is the agent who hits something mid-task and is concentrating on the problem
+ * rather than on remembering that a feedback tool exists.
+ *
+ * So: invite at the moment of friction, and vary the wording. A fixed string repeated forty times
+ * is invisible by call five; a line that names what just went wrong is read because it is about the
+ * thing the agent is already looking at. ~12 tokens against a ~4,546 tok/turn surface.
+ *
+ * Every invite is counted (`feedbackPrompted`). If `feedback_submitted ÷ feedbackPrompted` stays
+ * flat, this is decoration and should be deleted — instrumenting our own nudge is the difference
+ * between a designed system and a hope.
+ */
+/** What just happened, as far as the chokepoint can tell. Ordered most specific first. */
+export const FrictionKind = {
+    /** A tool that does not exist — the agent named a capability it expected us to have. */
+    UNKNOWN_TOOL: 'unknown_tool',
+    /** A verdict came back `unknown`: we drove the app and could not tell what happened. */
+    UNKNOWN_VERDICT: 'unknown_verdict',
+    /** The same tool, several times in a row. */
+    REPEATING: 'repeating',
+    /** The tool refused or errored. */
+    REFUSED: 'refused',
+};
+/**
+ * Runs of one tool before it counts as being stuck.
+ *
+ * Three, matching the verdict nudge: `reticle_act` led the field data at 110 consecutive-repeat
+ * runs, and a run of three is where a deliberate retry becomes a loop.
+ */
+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 ' +
+        '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 ' +
+        'surface and we fix the ones that fail',
+};
+/**
+ * Which friction, if any, this result represents.
+ *
+ * Deliberately reads only what the chokepoint already has: no handler changes, and nothing here can
+ * see app data.
+ */
+export function frictionOf(facts) {
+    if (facts.unknownTool)
+        return FrictionKind.UNKNOWN_TOOL;
+    if (facts.verifiedUnknown)
+        return FrictionKind.UNKNOWN_VERDICT;
+    // Repetition is only friction when it is repetition WITHOUT PROGRESS. Found by driving the Tauri
+    // smoke app: three consecutive SUCCESSFUL act_and_wait calls, each producing a verdict, were
+    // answered with "stuck on the same call?" — nagging the exact loop this release exists to
+    // encourage. A verdict is progress.
+    if (facts.repeatRun >= REPEAT_INVITE_AT && !facts.producedVerdict)
+        return FrictionKind.REPEATING;
+    if (facts.errored)
+        return FrictionKind.REFUSED;
+    return undefined;
+}
+/** The line for a friction kind. */
+export function inviteFor(kind) {
+    return LINES[kind];
+}

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

@@ -7,10 +7,4 @@ export declare const SESSION_BOUND_TOOLS: ReadonlySet<string>;
  * `sessionId`-bearing tool to be classified into exactly one set (bound XOR exempt).
  */
 export declare const SESSION_EXEMPT_TOOLS: ReadonlySet<string>;
-/**
- * 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
- * object that did not already include `session` — splices the health envelope on. Idempotent
- * (handlers that already add health are left untouched) and never alters non-object results.
- */
 export declare function runTool(tool: ToolDef, deps: ToolDeps, args: Record<string, unknown>): Promise<unknown>;