@reticlehq/server 2.13.1 → 2.14.0

package/dist/tools/act-tools.js

@@ -10,6 +10,7 @@ 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 { bodyClauseRefusal } from '../honesty/body-capture-remedy.js';
 import { causalSummary } from '../capsule/causal-summary.js';
 import { findContradictions } from '../events/contradictions.js';
 import { gapsForAction } from '../honesty/instrumentation-gaps.js';
@@ -24,8 +25,8 @@ import { waitForReaction } from './react-grace.js';
 import { decideVerified } from '../honesty/verified.js';
 import { honestyForVerdict } from '../honesty/honesty.js';
 import { declaredExpectations, declaresBodyIndependentChannel } from '../events/declared.js';
-import { readsDomState } from '../honesty/already-true.js';
-import { describeWaitTarget } from '../honesty/unsettled.js';
+import { readsDomState, alreadyTrueHiddenMatch as alreadyTrueHiddenMatchOf, } from '../honesty/already-true.js';
+import { describeWaitTarget, namedNetIsInFlight } from '../honesty/unsettled.js';
 import { saveFailedAssertCapsule } from './act-capsule.js';
 import { buildDivergenceCapsule } from '../capsule/capsule.js';
 import { predicateToExpectedLinks } from '../capsule/predicate-to-links.js';
@@ -97,8 +98,7 @@ export async function actCommand(deps, session, actArgs, timeoutMs) {
  * one layer earlier, before any session is resolved or any work is done.
  */
 const ACTION_TYPE_VALUES = Object.values(ActionType);
-const ACTION_TYPE_LIST = ACTION_TYPE_VALUES.join(' | ');
-export const actionTypeEnum = z.enum(ACTION_TYPE_VALUES);
+const actionTypeEnum = z.enum(ACTION_TYPE_VALUES);
 export const ACT_TOOLS = [
     {
         name: ReticleTool.ACT,
@@ -108,12 +108,12 @@ export const ACT_TOOLS = [
             ref: z
                 .string()
                 .optional()
-                .describe(`Element ref (e.g. 'e42') from reticle_snapshot/reticle_query — stable until the element leaves the DOM, so no re-snapshot between actions. Give this OR \`target\`.`),
+                .describe(`Element ref (e.g. 'e42') from reticle_snapshot/reticle_query — stable until the element leaves the DOM, so no re-snapshot between actions. Give this OR \`target\`. A press of Escape, Tab, or a modifier shortcut (Cmd+K) is a document key and needs neither.`),
             target: z
                 .record(z.unknown())
                 .optional()
                 .describe('Find the element and act on it in ONE call, instead of a reticle_query round trip first: { testid } | { text } | { role, name } | { label }. Refuses if it matches more than one, rather than guessing.'),
-            action: actionTypeEnum.describe(`Action to perform: ${ACTION_TYPE_LIST}`),
+            action: actionTypeEnum.describe('Action to perform.'),
             args: z
                 .record(z.unknown())
                 .optional()
@@ -248,12 +248,12 @@ export const ACT_TOOLS = [
             ref: z
                 .string()
                 .optional()
-                .describe(`Element ref (e.g. 'e42') from reticle_snapshot/reticle_query — stable until the element leaves the DOM, so no re-snapshot between actions. Give this OR \`target\`.`),
+                .describe(`Element ref (e.g. 'e42') from reticle_snapshot/reticle_query — stable until the element leaves the DOM, so no re-snapshot between actions. Give this OR \`target\`. A press of Escape, Tab, or a modifier shortcut (Cmd+K) is a document key and needs neither.`),
             target: z
                 .record(z.unknown())
                 .optional()
                 .describe('Find the element and act on it in ONE call, instead of a reticle_query round trip first: { testid } | { text } | { role, name } | { label }. Refuses if it matches more than one, rather than guessing.'),
-            action: actionTypeEnum.describe(`Action to perform: ${ACTION_TYPE_LIST}`),
+            action: actionTypeEnum.describe('Action to perform.'),
             args: z
                 .record(z.unknown())
                 .optional()
@@ -369,6 +369,11 @@ export const ACT_TOOLS = [
             const until = withUntil['until'] !== undefined
                 ? parsePredicate(withUntil['until'])
                 : { kind: PredicateKind.SETTLED };
+            // BEFORE the action. A body clause this session cannot answer would fail whatever the app
+            // did, and on a drive that mutates state the action is not always repeatable. See #801(C).
+            const bodyRefusal = bodyClauseRefusal(until, session);
+            if (bodyRefusal !== undefined)
+                throw new Error(bodyRefusal);
             const timeout = asNumber(args['timeout_ms']) ?? DEFAULT_ASSERT_TIMEOUT_MS;
             // An intent declared here lands in the ledger BEFORE the verdict is drawn, which is what makes
             // the undeclared-change gap silent on THIS verdict rather than the next one: it reads the
@@ -396,8 +401,15 @@ export const ACT_TOOLS = [
             // state — event-based ones are floored at this act's cursor and cannot be satisfied by the
             // past, so they need no pre-check and pay nothing. One extra query, on the path where a green
             // is otherwise unfalsifiable. See honesty/already-true.
-            const alreadyTrue = until !== undefined && readsDomState(until)
-                ? (await evaluatePredicate(session, until, since, false)).pass
+            const alreadyTruePrecheck = until !== undefined && readsDomState(until)
+                ? await evaluatePredicate(session, until, since, false)
+                : undefined;
+            const alreadyTrue = alreadyTruePrecheck?.pass ?? false;
+            // #889: the pre-check evidence is already in hand — cheap to also ask whether that match was
+            // against something hidden, so the already_true message can name it instead of leaving the
+            // agent to re-derive "was this actually showing?" from nothing.
+            const alreadyTrueHiddenMatch = alreadyTrue && until !== undefined
+                ? alreadyTrueHiddenMatchOf(until, alreadyTruePrecheck?.evidence)
                 : false;
             try {
                 // actCommand is the single interception point for upload+path rewrite.
@@ -488,7 +500,12 @@ export const ACT_TOOLS = [
                 // On RED only, attach the Tier-2 divergence capsule (first-divergence + blast radius). Red-only,
                 // so the common green path — what the loop optimizes — is unchanged; on red, diagnosis is the point.
                 const links = predicateToExpectedLinks(until);
-                const capsule = verdict.pass ? undefined : buildDivergenceCapsule(links, windowEvents);
+                // Read before the capsule, which needs it: a window the buffer trimmed cannot state an
+                // absolute about what did NOT happen. See CausalSummary.truncated.
+                const bufferLost = session.lostSince(since);
+                const capsule = verdict.pass
+                    ? undefined
+                    : buildDivergenceCapsule(links, windowEvents, bufferLost);
                 // Grade from what the verdict PROVED, not what it declared. A green anyOf holds on one branch, so
                 // grading off `links` (every branch) would let a presence-only OR report grade `signal` — a false
                 // green in the gate itself. `provenExpectedLinks` narrows a green to the branch that actually held;
@@ -515,7 +532,6 @@ export const ACT_TOOLS = [
                 // whose own words were "over a clean capture".
                 const gapNote = transportGapNote(windowEvents);
                 const impeachingNotes = [impeaching.note, gapNote].filter((n) => n !== undefined);
-                const bufferLost = session.lostSince(since);
                 // Which loss, as an enum, beside the prose that describes it. Classified here because this is
                 // the only place that knows the three apart: our buffer, our transport, and the page's own
                 // boundaries. See `CaptureLoss`.
@@ -594,8 +610,12 @@ export const ACT_TOOLS = [
                 // this is the only one that has to be interpreted, and now it interprets itself.
                 const outcomePending = hasAcceptedWrite(windowEvents);
                 const outcomeUnread = unreadWriteLabels(windowEvents);
+                const stillInFlight = inFlightRequestLabels(windowEvents);
                 const decision = decideVerified({
                     pass: verdict.pass,
+                    // So the unread-body remedy can check it applies to THIS page. Threaded rather than
+                    // looked up inside decideVerified, which is pure and has no session.
+                    ...(session.sdkVersion === undefined ? {} : { sdkVersion: session.sdkVersion }),
                     // The caller NAMED the consequence rather than defaulting to "wait for idle". A
                     // declaration made before the action is what this tool sells, and idle-settlement was
                     // overriding it — see `declaredConsequence`. An explicit `{ kind: "settled" }` is not a
@@ -605,12 +625,15 @@ export const ACT_TOOLS = [
                     // Omit when false: a net-only `until` must still hit `outcome_unread`.
                     ...(declaresBodyIndependentChannel(until) ? { independentOfBody: true } : {}),
                     ...(alreadyTrue ? { alreadyTrue } : {}),
+                    ...(alreadyTrueHiddenMatch ? { alreadyTrueHiddenMatch } : {}),
                     // 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 } : {}),
+                    ...(true === verdict.observationLost
+                        ? { observationLost: true, lastUrl: session.url }
+                        : {}),
                     ...(absenceBlindSpot === undefined ? {} : { absenceBlindSpot }),
                     honesty,
                     contradictions,
@@ -624,14 +647,18 @@ export const ACT_TOOLS = [
                     // window is already in hand.
                     unsettled: {
                         waitedFor: describeWaitTarget(until),
-                        stillInFlight: inFlightRequestLabels(windowEvents),
+                        stillInFlight,
                         // The retry loop that leaves nothing outstanding — see repeatedRequestLabels.
                         repeated: repeatedRequestLabels(windowEvents),
                     },
+                    ...(namedNetIsInFlight(until, stillInFlight) ? { namedRequestInFlight: true } : {}),
                 });
                 // Computed once: the verdict block reports it, and the instrumentation gaps are a second
                 // reading of the same evidence rather than a new observation.
-                const actionSummary = causalSummary(windowEvents, { stateUnwatched });
+                const actionSummary = causalSummary(windowEvents, {
+                    stateUnwatched,
+                    truncated: bufferLost,
+                });
                 // Asked of every verdict drawn after an observed edit, not once per edit — see
                 // isChangeUndeclared for why repeating it is disclosure rather than nagging.
                 // Read ONCE and used twice: `changeUndeclared` asks whether the ledger is empty, and the
@@ -649,6 +676,9 @@ export const ACT_TOOLS = [
                     stateUnwatched,
                     // What the app DECLARED, so an under-instrumented one is told without having to be asked.
                     hasCapabilities: session.hasCapabilities,
+                    // Whether the build TURNED the source stamp off, so a red with no file:line prescribes the
+                    // right fix. `false` from the page is the only value that means anything; absent is unknown.
+                    ...(false === session.sourceMapping ? { sourceMappingDisabled: true } : {}),
                     // What the run still owes. A green that leaves this above zero is not the same as done.
                     // MINUS the one this verdict is about to discharge.
                     //

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

@@ -1,4 +1,5 @@
 import type { Predicate } from '../events/predicate-schema.js';
+import type { Session } from '../session/session.js';
 /**
  * The `file:line` an ASSERTION is entitled to report — its own evidence, or nothing.
  *
@@ -19,4 +20,33 @@ export declare function assertSource(facts: {
     evidence: unknown;
     pass: boolean;
     lastActSource: string | undefined;
+    /**
+     * Set when the verdict could not be EVALUATED rather than evaluated and found false.
+     *
+     * A file:line reads as a precise, well-attributed finding about that file. Attaching one to a
+     * reading that proved nothing sends the investigation into correct code: reported against a
+     * wedged Next.js dev server, where a route verdict named `components/.../header.tsx:53` and the
+     * reporter nearly filed "the header Sign Up link is broken" — the server was answering nothing at
+     * all, on every route.
+     *
+     * Gated here rather than in the route oracle, because every producer of an inconclusive verdict
+     * has the same problem: a throttled tab, a superseded window, an unreadable locator. One guard
+     * where all of them route through.
+     */
+    inconclusive?: string | undefined;
 }): string | undefined;
+/**
+ * The file:line an assertion may report — see `assertSource`.
+ *
+ * Neither `reticle_assert` nor `reticle_wait_for` drives anything, so the last act's source is about
+ * some earlier action and not about this verdict. The pointer comes from the assertion's own matched
+ * evidence; the last driven control is borrowed only for a RED whose predicate has no DOM clause at
+ * all, which is the failure that genuinely has no element to point at.
+ */
+export declare function assertionSource(session: Session, predicate: Predicate, verdict: {
+    pass: boolean;
+    evidence?: unknown;
+    inconclusive?: string;
+}): {
+    source?: string;
+};

package/dist/tools/assert-source.js

@@ -49,5 +49,26 @@ export function assertSource(facts) {
         return own;
     if (facts.pass || declaresDom(facts.predicate))
         return undefined;
+    // Nothing was proven and nobody could have proven it — so there is nothing to point at.
+    if (facts.inconclusive !== undefined)
+        return undefined;
     return facts.lastActSource;
 }
+/**
+ * The file:line an assertion may report — see `assertSource`.
+ *
+ * Neither `reticle_assert` nor `reticle_wait_for` drives anything, so the last act's source is about
+ * some earlier action and not about this verdict. The pointer comes from the assertion's own matched
+ * evidence; the last driven control is borrowed only for a RED whose predicate has no DOM clause at
+ * all, which is the failure that genuinely has no element to point at.
+ */
+export function assertionSource(session, predicate, verdict) {
+    const source = assertSource({
+        predicate,
+        evidence: verdict.evidence,
+        pass: verdict.pass,
+        lastActSource: session.lastAct.source(),
+        ...(verdict.inconclusive === undefined ? {} : { inconclusive: verdict.inconclusive }),
+    });
+    return source === undefined ? {} : { source };
+}

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

@@ -1,4 +1,4 @@
-import type { InstrumentationGap, JournalVerdictEffect } from '@reticlehq/core';
+import type { InstrumentationGap, JournalVerdictEffect } from '@reticlehq/core/artifacts';
 import type { Predicate } from '../events/predicate.js';
 import type { Session } from '../session/session.js';
 import { type Contradiction } from '../events/contradictions.js';

package/dist/tools/assert-verdict.js

@@ -10,7 +10,7 @@ import { buildHonestyBlock } from '../honesty/honesty.js';
 import { hasAcceptedWrite } from '../honesty/accepted-write.js';
 import { unreadWriteLabels } from '../honesty/unread-outcome.js';
 import { decideVerified } from '../honesty/verified.js';
-import { describeWaitTarget } from '../honesty/unsettled.js';
+import { describeWaitTarget, namedNetIsInFlight } from '../honesty/unsettled.js';
 import { inFlightRequestLabels, repeatedRequestLabels } from './settle-in-flight.js';
 import { gradeOfPredicate } from './assert-grade.js';
 import { assertSource } from './assert-source.js';
@@ -85,6 +85,7 @@ changeUndeclared) {
         currentEditEpoch: session.currentEditEpoch,
         appOrigin: session.url,
         expectedFailures: declared.netFailures,
+        namedNetUrls: declared.netUrls,
         renderProved: pass && declared.rendersContent,
         ...(actCursor !== undefined && actCursor >= since ? { actionSince: actCursor } : {}),
     });
@@ -98,16 +99,22 @@ changeUndeclared) {
     const impeachingNotes = [impeaching.note, gap].filter((n) => n !== undefined);
     const outcomePending = hasAcceptedWrite(windowEvents);
     const outcomeUnread = unreadWriteLabels(windowEvents);
+    const stillInFlight = inFlightRequestLabels(windowEvents);
+    const effectiveInconclusive = inconclusive ?? (!pass ? session.preconditionFailure?.() : undefined);
     const decision = decideVerified({
         pass,
+        // So the unread-body remedy can check it applies to THIS page. Threaded rather than
+        // looked up inside decideVerified, which is pure and has no session.
+        ...(session.sdkVersion === undefined ? {} : { sdkVersion: session.sdkVersion }),
         // Same rule as the act path: the caller named a consequence, so a settlement-only finding must
         // not override it. A fix that lived on one half of the verdict surface would leave the other
         // half broken, and this is the tool agents call most.
         declaredConsequence: predicate.kind !== PredicateKind.SETTLED,
         ...(declaresBodyIndependentChannel(predicate) ? { independentOfBody: true } : {}),
-        ...(inconclusive === undefined ? {} : { inconclusive }),
-        ...(true === observationLost ? { observationLost: true } : {}),
+        ...(effectiveInconclusive === undefined ? {} : { inconclusive: effectiveInconclusive }),
+        ...(true === observationLost ? { observationLost: true, lastUrl: session.url } : {}),
         ...(absenceBlindSpot === undefined ? {} : { absenceBlindSpot }),
+        ...(namedNetIsInFlight(predicate, stillInFlight) ? { namedRequestInFlight: true } : {}),
         honesty: buildHonestyBlock({
             grade: gradeOfPredicate(predicate),
             attribution: 'window',
@@ -143,7 +150,7 @@ changeUndeclared) {
         // contradiction, and "the window closed before the app finished" is no more actionable here.
         unsettled: {
             waitedFor: describeWaitTarget(predicate),
-            stillInFlight: inFlightRequestLabels(windowEvents),
+            stillInFlight,
             repeated: repeatedRequestLabels(windowEvents),
         },
     });
@@ -158,6 +165,9 @@ changeUndeclared) {
         stateUnwatched: isStateUnwatched(spots),
         // What the app DECLARED, so an under-instrumented one is told without having to be asked.
         hasCapabilities: session.hasCapabilities,
+        // Whether the build TURNED the source stamp off, so a red with no file:line prescribes the
+        // right fix. `false` from the page is the only value that means anything; absent is unknown.
+        ...(false === session.sourceMapping ? { sourceMappingDisabled: true } : {}),
         domMutated: false,
         signalsFired: 0,
         routeChanged: false,

package/dist/tools/browser-tools.js

@@ -1,18 +1,19 @@
 import { carryReticleIdentity } from './lease-tools.js';
 import { z } from 'zod';
 import { navigateResult } from './navigate-result.js';
-import { awaitArrival } from './navigate-arrival.js';
+import { awaitArrival, idsAtTarget, ARRIVAL_TIMEOUT_MS } 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';
 import { ReticleTool } from './tool-names.js';
-import { asString } from './tools-helpers.js';
+import { asNumber, asString } from './tools-helpers.js';
 import { sessionIdShape, commandOrThrow } from './tool-kit.js';
+import { timeoutMsSchema } from './numeric-bounds.js';
 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 — 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.',
+        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 up to `timeout_ms` (default 5000) 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 that window (reported as `waitedMs`) — the page may be slow, uninstrumented, or not there. A slow SPA can take 30-60s to reattach: raise `timeout_ms` rather than polling reticle_sessions.',
         inputSchema: {
             url: z.string().optional().describe('The URL to navigate to. Omit when using reload.'),
             reload: z
@@ -23,6 +24,9 @@ export const BROWSER_TOOLS = [
                 .boolean()
                 .optional()
                 .describe('With reload:true, bypass the browser cache (Cmd+Shift+R). Default: false.'),
+            timeout_ms: timeoutMsSchema
+                .optional()
+                .describe('How long to wait for the page to come back (the SDK reconnecting at the new URL, or under the same id on a reload) before answering confirmed:false. Default 5000. 0 looks once without waiting. An SPA reattaching under HMR has been measured at 30-60s — say so here instead of polling reticle_sessions.'),
             ...sessionIdShape,
         },
         outputSchema: {
@@ -34,11 +38,19 @@ export const BROWSER_TOOLS = [
             confirmed: z.boolean().optional(),
             /** The session the SDK reconnected as, when arrival was confirmed — it is a NEW id. */
             sessionId: z.string().optional(),
+            /**
+             * On confirmed:false — the budget (ms) that expired without the page coming back. Says which
+             * of "Reticle stopped waiting" and "the page never came back" you are looking at.
+             */
+            waitedMs: z.number().optional(),
             note: z.string().optional(),
         },
         handler: async (deps, args) => {
             // reload:true is the absorbed reticle_refresh — same command, one fewer advertised tool.
             if (true === args['reload']) {
+                // The reload branch has its own default, sized for a cold dev-server rebuild; the caller's
+                // budget overrides it for the same reason it overrides the arrival wait below.
+                const timeoutMs = asNumber(args['timeout_ms']) ?? RELOAD_RECONNECT_TIMEOUT_MS;
                 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 —
@@ -56,14 +68,14 @@ export const BROWSER_TOOLS = [
                 const back = await waitForReconnect({
                     current: () => deps.sessions.get(before.id),
                     previous: before,
-                    timeoutMs: RELOAD_RECONNECT_TIMEOUT_MS,
+                    timeoutMs,
                     now: deps.now,
                     sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
                 });
                 // Not a bare `{ ok: true }`. The URL branch below already discloses that `ok` means
                 // DISPATCHED — the reload branch had identical semantics and said nothing, on the path most
                 // likely to need it. See reload-result.
-                return reloadResult(back);
+                return reloadResult(back, timeoutMs);
             }
             const requested = asString(args['url']);
             if (requested === undefined || 0 === requested.length)
@@ -74,6 +86,10 @@ export const BROWSER_TOOLS = [
             // A leased tab is addressed by a URL param, so navigating away from it used to strand the
             // lease — see carryReticleIdentity. A tab that claims no identity is untouched.
             const url = carryReticleIdentity(session.url, requested);
+            // Sampled BEFORE dispatch, because that is the only moment it can be known. A session already
+            // sitting on the target is not evidence that THIS navigation arrived — and the arrival scan,
+            // which reads whatever is at the target afterwards, cannot tell the two apart on its own.
+            const priorIds = idsAtTarget(deps.sessions, url);
             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
@@ -83,9 +99,13 @@ export const BROWSER_TOOLS = [
                 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.
                 // 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);
+                // for as long as the caller said to, instead of telling the agent to go poll
+                // reticle_sessions itself. A refusal skips the wait: there is nothing to wait FOR.
+                const timeoutMs = asNumber(args['timeout_ms']) ?? ARRIVAL_TIMEOUT_MS;
+                const arrival = true === result.ok
+                    ? await awaitArrival(deps.sessions, url, { navigatedId: session.id, priorIds }, timeoutMs)
+                    : null;
+                return navigateResult(result, arrival, timeoutMs);
             }
             finally {
                 session.finishAction();

package/dist/tools/complete-snapshot.d.ts

@@ -35,8 +35,8 @@ export declare const MAX_COMPLETION_READS = 12;
  */
 export declare const MAX_COMPLETION_DEPTH = 4;
 /** Reads one snapshot — whole page when `scope` is undefined, that branch when it is not. */
-export type SnapshotReader = (scope: string | undefined) => Promise<unknown>;
-export interface CompletedRead {
+type SnapshotReader = (scope: string | undefined) => Promise<unknown>;
+interface CompletedRead {
     /** The union of every subtree that was read. Never a lie about what it contains — only about how much. */
     tree: string;
     /** True only when every branch the page cut was read back. A negative conclusion needs this. */
@@ -46,3 +46,4 @@ export interface CompletedRead {
     incompleteBecause?: string;
 }
 export declare function readCompleteTree(read: SnapshotReader): Promise<CompletedRead>;
+export {};

package/dist/tools/dynamic-tools.js

@@ -245,5 +245,13 @@ export function buildDynamicTools(allTools, profile) {
             }
         },
     };
+    // The server instructions say, verbatim, "reticle_tools lists it, reticle_run calls it" — naming
+    // these two meta-tools as reachable through EACH OTHER, same as everything else on the surface.
+    // `byName` was built from `allTools` before either was constructed, so it never held them:
+    // `reticle_run { tool: "reticle_tools" }` — the exact discovery path the instructions document —
+    // answered "unknown tool 'reticle_tools'" (#876). Registered here, after both exist, so the
+    // dispatch this closure reads from (`byName.get`, evaluated lazily on each call) can find them.
+    byName.set(ReticleTool.TOOLS, reticleTools);
+    byName.set(ReticleTool.RUN, reticleRun);
     return [reticleTools, reticleRun];
 }

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

@@ -29,6 +29,16 @@ export declare const RECOVERY: {
      * carry: which of them to reach for, and that nothing was acted on.
      */
     readonly TARGET_MISSED: string;
+    /**
+     * The selector was underspecified, which is the caller's to fix and the same class as a miss.
+     *
+     * It reached the feedback ask for a punctuation reason: the text ends "pass an explicit `ref` from
+     * reticle_query.", and the catch-all excludes a `reticle_*` name followed by `.` so a module path
+     * in a stack trace stays an unanticipated crash. A tool named at the END of a sentence is
+     * indistinguishable from one under that rule, so the whole message fell through and told the
+     * caller their own ambiguous query might be a defect worth a root-cause report.
+     */
+    readonly AMBIGUOUS_TARGET: string;
     readonly NO_SUCH_OPTION: string;
     readonly BAD_ARGUMENTS: string;
     readonly WRONG_TARGET: string;

package/dist/tools/error-recovery.js

@@ -103,6 +103,20 @@ export const RECOVERY = {
         'acted on. Take a reticle_snapshot to see what is actually there (a view may still be ' +
         'rendering, or the control may be named differently), then retry with what it shows. This is ' +
         'a miss, not a Reticle defect: there is nothing to report.',
+    /**
+     * The selector was underspecified, which is the caller's to fix and the same class as a miss.
+     *
+     * It reached the feedback ask for a punctuation reason: the text ends "pass an explicit `ref` from
+     * reticle_query.", and the catch-all excludes a `reticle_*` name followed by `.` so a module path
+     * in a stack trace stays an unanticipated crash. A tool named at the END of a sentence is
+     * indistinguishable from one under that rule, so the whole message fell through and told the
+     * caller their own ambiguous query might be a defect worth a root-cause report.
+     */
+    AMBIGUOUS_TARGET: 'The call was valid and the selector matched SEVERAL elements, so nothing was acted on. Acting ' +
+        'on one of them would report a verdict about an element you did not choose, which is the false ' +
+        'green Reticle refuses to produce. The message above names each match: narrow the query with a ' +
+        'role, name, testid or scope, or pass an explicit `ref` from reticle_query. This is an ' +
+        'underspecified selector, 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. ' +
@@ -206,6 +220,9 @@ const REASON_OF = {
     STALE_REF_AFTER_EDIT: RefusalReason.NO_MATCH,
     NO_SUCH_OPTION: RefusalReason.NO_MATCH,
     TARGET_MISSED: RefusalReason.NO_MATCH,
+    // Target resolution failed to name one element. NO_MATCH rather than BAD_ARGS: the arguments were
+    // well-formed and the query simply did not identify a single node, same as a miss.
+    AMBIGUOUS_TARGET: RefusalReason.NO_MATCH,
     FLOW_STEP_MISSING: RefusalReason.NO_MATCH,
     UNSUPPORTED_SURFACE: RefusalReason.UNSUPPORTED,
     HOVER_NEEDS_POINTER: RefusalReason.UNSUPPORTED,
@@ -279,6 +296,12 @@ const RULES = [
     // agent to re-read arguments that were already correct costs it a turn, and this is the commonest
     // refusal there is.
     { match: /target matched no element/i, hint: RECOVERY.TARGET_MISSED },
+    // Also BEFORE the catch-all, and for the same reason the line above is: the caller's query is the
+    // thing to fix, so the answer must not be "re-read the tool's parameters" or a bug-report nudge.
+    {
+        match: /target matched \d+ elements and an action must not guess/i,
+        hint: RECOVERY.AMBIGUOUS_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 },

package/dist/tools/feedback-tools.js

@@ -12,7 +12,7 @@
  * tokens on that and not on politeness.
  */
 import { z } from 'zod';
-import { FeedbackKind, FeedbackSource, FEEDBACK_RATING_MAX, FEEDBACK_RATING_MIN, } from '@reticlehq/core';
+import { FeedbackKind, FeedbackSource, FEEDBACK_RATING_MAX, FEEDBACK_RATING_MIN, } from '@reticlehq/core/telemetry';
 import { ReticleTool } from './tool-names.js';
 import { asNumber, asString } from './tools-helpers.js';
 import { submitFeedback, feedbackDisabled } from '../telemetry/feedback.js';

package/dist/tools/invoke-tool.js

@@ -69,6 +69,8 @@ const REF_MINTING_TOOLS = new Set([
     ReticleTool.VERIFY,
 ]);
 export const SESSION_BOUND_TOOLS = new Set([
+    // Resolves a session and reads its event window (`session.eventsSince`), exactly as OBSERVE and
+    // NETWORK do. Without this it runs with no session and answers from nothing.
     ReticleTool.SNAPSHOT,
     ReticleTool.QUERY,
     ReticleTool.INSPECT,

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

@@ -9,6 +9,7 @@
  *
  * Attach-only: the pool drives a browser against an already-running dev server — it never starts one.
  */
+import { type SeedStorage } from '@reticlehq/core';
 import type { ToolDef } from './tool-kit.js';
 /** The origin of a URL, or undefined when it does not parse. */
 export declare function originOf(url: string): string | undefined;
@@ -17,12 +18,28 @@ export declare function originOf(url: string): string | undefined;
  * adopts them on connect. Pure; falls back to plain concatenation if the URL can't be parsed.
  */
 export declare function appendReticleParams(url: string, session: string, projectId?: string): string;
+/**
+ * Scrub known secret shapes and raw seedStorage values (cookies, localStorage, sessionStorage)
+ * from an error string before it reaches daemon logs, metrics, or MCP error responses.
+ */
+export declare function scrubSeedFromError(text: string, seed?: unknown): string;
 /**
  * Turn a raw navigation failure (Playwright's `page.goto: net::ERR_… at <url>\nCall log:…`, often
  * with ANSI codes) into a short, clean reason — so the agent/user sees "is the app running?" instead
  * of an internals-leaking wall of text.
  */
-export declare function cleanNavError(err: unknown): string;
+export declare function cleanNavError(err: unknown, seed?: SeedStorage): string;
+/**
+ * Determine if a required seedStorage application precondition failed.
+ *
+ * Checks strong signals:
+ * 1. HTTP 401/403 status on the initial navigation.
+ * 2. Cross-origin redirect when localStorage or sessionStorage was requested (skipped by origin-scoping).
+ * 3. Clear redirect to an authentication/login endpoint when the requested URL was not a login page.
+ *
+ * Normal app redirects (e.g. / → /dashboard) are valid and return undefined.
+ */
+export declare function evaluateSeedPrecondition(requestedUrl: string, actualUrl: string | undefined, seed: SeedStorage, navStatus?: number): string | undefined;
 /**
  * The session a lease's tab actually registered as, or undefined while nothing has.
  *
@@ -57,6 +74,31 @@ export declare function resolveLeasedSessionId(sessions: {
  * a human's own URL.
  */
 export declare function carryReticleIdentity(fromUrl: string | undefined, toUrl: string): string;
+/** The narrow slice of a session the probe needs. Anything that quacks like this works. */
+interface ProbeableSession {
+    command?: (name: string, args: Record<string, unknown>, timeoutMs: number) => Promise<unknown>;
+}
+/**
+ * Does this tab still answer?
+ *
+ * `ready: true` used to mean "a row is in the sessions map", which is how a lease came back ready
+ * and was then rejected by `snapshot`, `state` and `console`. Presence is not liveness: the map
+ * still holds a tab that is attached, streaming events, and answering nothing (#692).
+ *
+ * ANY reply counts, including one that reports the command failed. The question is whether the SDK
+ * answers at all, not what it says — so an SDK too old to know the command replies
+ * `unknown command '…'`, and that is proof. Only the absence of a reply is evidence of absence:
+ * `PendingCommands.track` REJECTS on timeout and on a dropped socket, and resolves on every real
+ * answer, so the two cases are already separated for us.
+ *
+ * `CAPABILITIES` is the probe because it takes no arguments and returns a small fixed list. No new
+ * wire command is introduced: this rides an existing round trip.
+ *
+ * Fails OPEN. A registry entry with no `command` is a shape this code did not put there, and
+ * turning a lease that works into a refusal over a probe that could not run would be a worse
+ * failure than the one being fixed.
+ */
+export declare function probeLeaseAlive(session: ProbeableSession | undefined, timeoutMs?: number): Promise<boolean>;
 /**
  * Poll until the leased tab's SDK has actually registered on the bridge, so the sessionId we return
  * is immediately usable (the page navigates first, then connects a moment later — without this wait
@@ -71,9 +113,11 @@ export declare function carryReticleIdentity(fromUrl: string | undefined, toUrl:
 export declare function acquireLeasedSession(pool: {
     acquire: (url: string, opts: {
         sessionId: string;
+        seedStorage?: SeedStorage;
     }) => Promise<{
         sessionId: string;
         release: () => Promise<void>;
+        navStatus?: number;
     }>;
     /**
      * The address this lease's page said it could not reach. Optional so a test double need not
@@ -88,28 +132,12 @@ export declare function acquireLeasedSession(pool: {
         id: string;
         url?: string;
     }[];
-}, url: string, projectId?: string): Promise<{
+}, url: string, projectId?: string, seedStorage?: SeedStorage): Promise<{
     sessionId: string;
     release: () => Promise<void>;
 }>;
 export declare function waitForLeasedSession(isConnected: () => boolean, sleeper?: (ms: number) => Promise<void>, attempts?: number, pollMs?: number): Promise<boolean>;
-/**
- * Named on its own because `reticle drive <url>` runs it too.
- *
- * When a daemon already owns the bridge port, `drive` asks that daemon for a browser instead of
- * competing for the port (see cli/drive-attach.ts), and the browser it should get is exactly the one
- * an agent gets: same pool, same isolation, same reporting. Sharing the ToolDef rather than the
- * handler keeps that literal — the drive route dispatches through `runTool`, so it is counted like
- * any other call instead of being a second, invisible dispatch path.
- */
+export declare function hasOriginLock(origin: string): boolean;
 export declare const LEASE_ACQUIRE_TOOL: ToolDef;
-/**
- * What to say when a lease was taken while a real tab was already open.
- *
- * Not a refusal. Leases are the highest-value path for autonomous work and an agent that genuinely
- * needs isolation must still get one — but a human watching their own tab cannot see a lease, so
- * when both exist the visible one is the better default and the agent should hear that here, where
- * it is choosing, rather than discover it when somebody asks why nothing is happening.
- */
-export declare const PREFER_EXISTING_NOTE = "a non-leased tab for this app was already connected \u2014 that is the one a human can see, and this lease is not. Unless you need an isolated context (a second identity, a clean profile, parallel flows), release this lease and drive that sessionId instead.";
 export declare const LEASE_TOOLS: ToolDef[];
+export {};