@reticlehq/server 2.13.1 → 2.14.0

package/dist/events/predicate-route.js

@@ -37,6 +37,49 @@ export function routePathOf(pathname, hash) {
     const query = withoutHash.indexOf('?');
     return -1 === query ? withoutHash : withoutHash.slice(0, query);
 }
+function asPayload(value) {
+    if (null === value || 'object' !== typeof value || Array.isArray(value))
+        return undefined;
+    return value;
+}
+function payloadOf(eventOrData) {
+    if (eventOrData['type'] === EventType.ROUTE_CHANGE)
+        return asPayload(eventOrData['data']);
+    // A different event: refuse rather than read whatever happened to sit in `data`.
+    if (undefined !== eventOrData['type'] && undefined !== eventOrData['data'])
+        return undefined;
+    return eventOrData;
+}
+function partsFromPayload(data) {
+    const docPath = str(data['pathname']) ?? str(data['to']);
+    if (docPath === undefined)
+        return undefined;
+    const hash = str(data['hash']) ?? '';
+    const search = str(data['search']) ?? '';
+    return {
+        routePath: routePathOf(docPath, hash),
+        docPath,
+        hash,
+        search,
+        full: `${docPath}${search}${hash}`,
+    };
+}
+/** A `ROUTE_CHANGE` event, or its `data` — one reading, so the sixth copy cannot drift. */
+export function routeOfEvent(eventOrData) {
+    const data = payloadOf(eventOrData);
+    return data === undefined ? undefined : partsFromPayload(data);
+}
+/** Same shape from a session URL (the fallback when the tab hard-loaded and emitted no route event). */
+export function routeOfUrl(url) {
+    if (!URL.canParse(url))
+        return undefined;
+    const parsed = new URL(url);
+    return partsFromPayload({
+        pathname: parsed.pathname,
+        search: parsed.search,
+        hash: parsed.hash,
+    });
+}
 /**
  * The session's live URL, split the way a route-change event already carries it.
  *
@@ -44,14 +87,14 @@ export function routePathOf(pathname, hash) {
  * away — an unreadable URL is not worth losing the fallback over.
  */
 function readCurrentRoute(url) {
-    const parsed = URL.canParse(url) ? new URL(url) : undefined;
-    const pathname = parsed?.pathname ?? url;
-    const search = parsed?.search ?? '';
-    const hash = parsed?.hash ?? '';
+    const parts = routeOfUrl(url);
+    const pathname = parts?.docPath ?? url;
+    const search = parts?.search ?? '';
+    const hash = parts?.hash ?? '';
     return {
         pathname,
-        routePath: routePathOf(pathname, hash),
-        full: `${pathname}${search}${hash}`,
+        routePath: parts?.routePath ?? routePathOf(pathname, hash),
+        full: parts?.full ?? `${pathname}${search}${hash}`,
         decidedBy: RouteDecidedBy.CURRENT,
         data: { pathname, search, hash, url, decidedBy: RouteDecidedBy.CURRENT },
     };
@@ -72,25 +115,41 @@ export function evalRoute(events, p,
  * `reticle_snapshot({ mode: 'status' }).route` one call later. Optional so a caller with no session
  * (a replayed window) keeps the old answer instead of inventing a route.
  */
-currentUrl) {
+currentUrl, 
+/** Event-time floor for the window, so a request already in flight before it is not counted. */
+since = 0) {
     const routes = events.filter((e) => e.type === EventType.ROUTE_CHANGE);
     const last = routes.at(-1);
-    const reading = last !== undefined
-        ? (() => {
-            const changedPath = str(last.data['pathname']) ?? str(last.data['to']) ?? '';
-            const changedHash = str(last.data['hash']) ?? '';
-            return {
-                pathname: changedPath,
-                routePath: routePathOf(changedPath, changedHash),
-                full: `${changedPath}${str(last.data['search']) ?? ''}${changedHash}`,
-                decidedBy: RouteDecidedBy.CHANGE,
-                data: { ...last.data, decidedBy: RouteDecidedBy.CHANGE },
-            };
-        })()
+    const changed = last === undefined ? undefined : routeOfEvent(last);
+    const reading = changed !== undefined && last !== undefined
+        ? {
+            pathname: changed.docPath,
+            routePath: changed.routePath,
+            full: changed.full,
+            decidedBy: RouteDecidedBy.CHANGE,
+            data: { ...last.data, decidedBy: RouteDecidedBy.CHANGE },
+        }
         : currentUrl === undefined || 0 === currentUrl.length
             ? undefined
             : readCurrentRoute(currentUrl);
     if (reading === undefined) {
+        // A navigation the SERVER never answered reads exactly like one the APP prevented, and only one
+        // of those is the user's bug. See unansweredIn.
+        const unanswered = unansweredIn(events, since);
+        if (unanswered !== undefined) {
+            const reason = `no route change, and ${unanswered.count} request(s) started in this window never ` +
+                `completed — first: ${unanswered.method} ${unanswered.url}. A navigation the server has ` +
+                'not answered is indistinguishable from one the app declined, so this is not evidence ' +
+                'against the app. Check the server directly (curl the route) before looking at components';
+            return {
+                pass: false,
+                failureReason: reason,
+                inconclusive: reason,
+                observed: `${unanswered.count} request(s) still in flight, no route change`,
+                expected: `a route change to ${p.pathname ?? p.contains ?? 'any route'}`,
+                assertion: 'route.server-pending',
+            };
+        }
         return {
             pass: false,
             failureReason: 'no route change observed',
@@ -99,7 +158,7 @@ currentUrl) {
             assertion: 'route.changed',
         };
     }
-    // The ROUTER's path, not the document's — see routePathOf.
+    // The ROUTER's path, not the document's — see routeOfEvent.
     const pathname = reading.routePath;
     if (p.pathname !== undefined && pathname !== p.pathname) {
         return {
@@ -126,5 +185,74 @@ currentUrl) {
             assertion: 'route.contains',
         };
     }
-    return { pass: true, evidence: reading.data };
+    return {
+        pass: true,
+        evidence: reading.decidedBy === RouteDecidedBy.CHANGE
+            ? { ...reading.data, viewSettled: sawActivityAfter(events, last?.t ?? 0) }
+            : reading.data,
+    };
+}
+/**
+ * Did the page do ANYTHING after the URL moved?
+ *
+ * A route predicate goes green the instant the URL commits, and on an async-loading page that is a
+ * verdict taken over a shell. The reporter's sequence is the whole argument: `allOf [route, console
+ * absent]` returned `verified: "yes"`, a snapshot of `main` came back with 9 nodes that read as an
+ * empty page, and re-snapshotting moments later showed 22 with the real content — one step from
+ * filing "this route renders nothing" against code that was fine.
+ *
+ * The grade is deliberately NOT changed. Requiring a settle would make every route assertion wait
+ * and would flip green suites red, and the report's own acceptance allows either that or evidence
+ * saying the view had not settled. This is the second, and it costs nothing that already worked.
+ *
+ * No clock is read: if the route change is the LAST thing in the window, nothing has been observed
+ * since the URL moved, which is exactly the trap. Activity BEFORE the change is ignored — a mutation
+ * that predates the navigation says nothing about what the new route rendered.
+ *
+ * Reported only for a CHANGE reading. A pass decided by "the app is already there" has no commit
+ * moment to be too close to, and a caveat there would describe a reading it is not about.
+ */
+function sawActivityAfter(events, routeAt) {
+    return events.some((e) => e.t > routeAt && ROUTE_SETTLE_ACTIVITY.has(e.type));
+}
+/**
+ * What counts as the view still moving. Same set the `settled` oracle uses, and deliberately the
+ * same one: two different answers to "did the page do something" is how a vocabulary rots.
+ */
+const ROUTE_SETTLE_ACTIVITY = new Set([
+    EventType.NET_REQUEST,
+    EventType.DOM_ADDED,
+    EventType.DOM_REMOVED,
+    EventType.DOM_ATTR,
+]);
+/**
+ * A request that STARTED in this window and never completed.
+ *
+ * The discriminator the route oracle was missing. `routeChanges: 0, network: 0` is reported the same
+ * way whether the app prevented the navigation or the server never answered the request the app
+ * made — and only the first is the user's bug. Reticle already saw the pending navigation; it just
+ * never said so, and attached a `source:` file:line that pointed at innocent code.
+ *
+ * Scoped to requests that started INSIDE the window, deliberately. A background poll that predates
+ * the action says nothing about this navigation, and counting it would make every route miss on a
+ * polling app inconclusive — softening away the finding this oracle exists to make. That is the same
+ * trap the duplicate-request and contradiction rules were each narrowed to avoid.
+ *
+ * Matched on the request id, the way `detectHungRequests` does: a NET_PENDING with no NET_REQUEST
+ * carrying the same id.
+ */
+function unansweredIn(events, since) {
+    const settled = new Set();
+    for (const e of events)
+        if (e.type === EventType.NET_REQUEST)
+            settled.add(e.data['id']);
+    const open = events.filter((e) => e.type === EventType.NET_PENDING && e.t >= since && !settled.has(e.data['id']));
+    const first = open[0];
+    if (first === undefined)
+        return undefined;
+    return {
+        count: open.length,
+        url: str(first.data['url']) ?? '(unknown url)',
+        method: str(first.data['method']) ?? 'GET',
+    };
 }

package/dist/events/predicate-schema.d.ts

@@ -19,6 +19,8 @@ export type Predicate = {
      * `act_and_wait` reports `already_true` for an action that did exactly the right thing.
      */
     scope?: string;
+    /** Match the scope root itself and check its combined subtree text. Requires `scope`. */
+    self?: boolean;
 } | {
     kind: typeof PredicateKind.NET;
     method?: string;
@@ -30,6 +32,10 @@ export type Predicate = {
     count?: number;
     /** A substring the RESPONSE body must contain — what the server answered, not what was sent. */
     bodyContains?: string;
+    /** A substring the REQUEST body must contain — what the UI sent, not what came back. */
+    requestBodyContains?: string;
+    /** Shallow JSON match over the REQUEST body, in the style of `signal.dataMatches`. */
+    requestBodyMatches?: Record<string, unknown>;
 } | {
     kind: typeof PredicateKind.ROUTE;
     pathname?: string;
@@ -80,7 +86,7 @@ export type Predicate = {
     kind: typeof PredicateKind.NOT;
     predicate: Predicate;
 };
-export interface ResidualQueryChecks {
+interface ResidualQueryChecks {
     /** Dropped fields this side CAN check, as [field, wanted value] pairs. */
     checks: [string, string][];
     /** Dropped fields with no descriptor to check them against — refuse rather than ignore. */
@@ -159,3 +165,4 @@ export declare function nestedKeysOf(schema: z.ZodTypeAny | undefined): readonly
  * list is worse than none, because the agent trusts it and retries into the same wall.
  */
 export declare function predicateNestedFieldsFor(kind: string): Readonly<Record<string, readonly string[]>>;
+export {};

package/dist/events/predicate-schema.js

@@ -82,6 +82,10 @@ const ELEMENT_QUERY_FIELDS = [
  */
 function usedQueryFields(query) {
     const used = new Set();
+    // The browser's `self` branch checks subtree text when supplied, but skips every other locator.
+    // Mark only text as consumed so role/name/etc. remain residual checks on the returned descriptor.
+    if (true === query.self)
+        return query.text === undefined ? used : used.add('text');
     if (query.by !== undefined && query.value !== undefined) {
         used.add('by').add('value');
         if (QueryBy.ROLE === query.by)
@@ -231,6 +235,7 @@ function predicateUnion() {
             visible: z.boolean().optional(),
             absent: z.boolean().optional(),
             scope: z.string().optional(),
+            self: z.boolean().optional(),
         })
             .strict(),
         z
@@ -260,6 +265,35 @@ function predicateUnion() {
              * was never recorded rather than reporting an ordinary mismatch.
              */
             bodyContains: z.string().min(1).optional(),
+            /**
+             * A substring the REQUEST body must contain — the other half of `bodyContains`.
+             *
+             * `bodyContains` deliberately searches only the response, and the comment above says why:
+             * searching the request too would let it pass on the very defect it exists to catch. That
+             * reasoning is sound and it leaves a real gap. For a filter, a search or a form, the thing
+             * under test IS the outgoing payload: "applying this filter actually sends it" had no
+             * verdict at all, only `reticle_network { bodies: true }` and a human reading `requestBody`
+             * by eye (#798).
+             *
+             * A separate field rather than a mode on `bodyContains`, so neither assertion can ever be
+             * satisfied by the wrong half of the exchange.
+             *
+             * Requires body capture, and says so when the request body was never recorded rather than
+             * reporting an ordinary mismatch.
+             */
+            requestBodyContains: z.string().min(1).optional(),
+            /**
+             * Shallow JSON match over the REQUEST body, keyed like `signal.dataMatches` and sharing its
+             * `matchValue` operators (`*`, `$gte`, `$contains`, …).
+             *
+             * `{ requestBodyMatches: { filter: "manual_review" } }` is the one-call verdict for "the UI
+             * put the selected value into the payload", and it does not care about key order,
+             * whitespace or how the client serialised the object — all of which a substring does.
+             *
+             * A field whose captured value was REDACTED cannot be matched, and the verdict says so
+             * instead of reporting a mismatch: a redacted field is unknown, not different.
+             */
+            requestBodyMatches: z.record(z.string(), z.unknown()).optional(),
         })
             .strict(),
         z

package/dist/events/predicate.d.ts

@@ -50,6 +50,8 @@ export interface PredicateSession {
      * Optional: a fake that never throttles simply omits it.
      */
     throttled?(): boolean;
+    /** Precondition failure reason (e.g. seedStorage), if any. */
+    preconditionFailure?(): string | undefined;
 }
 export declare function evaluatePredicate(session: PredicateSession, predicate: Predicate, since?: number, diagnose?: boolean): Promise<EvalResult>;
 /**

package/dist/events/predicate.js

@@ -2,13 +2,12 @@ import { ElementState, PredicateKind, ReticleCommand, THROTTLED_STARVED_NOTE, is
 import { log } from '../log.js';
 import { bindSpanContext } from '../trace.js';
 import { selectPath, capDepth } from '../session/state-select.js';
-import { describeTestidMiss } from './testid-near-miss.js';
-import { describeSplitTextMiss } from './split-text-miss.js';
 import { predicateToExpectedLinks } from '../capsule/predicate-to-links.js';
 import { isAmbient, ambientKeyOf } from '../journal/ambient.js';
 import { evalRoute } from './predicate-route.js';
 import { describeSuperseded } from './observed-in-window.js';
-import { PredicateSchema, matchValue, evalNet, evalConsole, evalAnimation, evalSignal, evalSettled, residualQueryChecks, satisfiesResiduals, describeResidual, } from './predicate-eval.js';
+import { evalElement } from './predicate-element.js';
+import { PredicateSchema, matchValue, evalNet, evalConsole, evalAnimation, evalSignal, evalSettled, } from './predicate-eval.js';
 export { PredicateSchema, PredicateKind };
 /**
  * A composite result that carries a child's "nobody could evaluate this" up to the verdict rule.
@@ -22,155 +21,6 @@ function unreadableComposite(child, evidence) {
     const reason = child.inconclusive ?? 'a sub-predicate could not be evaluated';
     return { pass: false, failureReason: reason, inconclusive: reason, evidence };
 }
-async function matchOnce(session, query, state) {
-    const res = await session.command(ReticleCommand.MATCH, { query, state });
-    if (!res.ok)
-        return { matched: false, count: 0, elements: [] };
-    return (res.result ?? { matched: false, count: 0, elements: [] });
-}
-async function evalElement(session, query, state, absent, diagnose) {
-    // Fields the browser's locator would have DROPPED, enforced back here — see residualQueryChecks.
-    // Checked before the round-trip when nothing can enforce them: a predicate that cannot be evaluated
-    // must say so rather than resolve to whatever the surviving half of it happened to match.
-    const residual = residualQueryChecks(query);
-    if (residual.unusable.length > 0) {
-        const reason = `the element locator ignores ${residual.unusable.map((f) => `\`${f}\``).join(', ')} ` +
-            `in ${JSON.stringify(query)} — it resolves by the first of by+value, component/source, role, ` +
-            'text, label, placeholder, testid, alt that is present, and nothing here can check the rest. ' +
-            'Assert them one locator at a time, or move the extra field into the locator';
-        return { pass: false, failureReason: reason, inconclusive: reason };
-    }
-    let match = await matchOnce(session, query, state);
-    const subject = JSON.stringify(query);
-    // A residual narrows the SET; `count` is every match while `elements` is only the described prefix,
-    // so a locator broad enough to be truncated cannot be narrowed honestly. Say so instead of guessing.
-    if (residual.checks.length > 0 && match.count > match.elements.length) {
-        const reason = `${String(match.count)} elements matched ${subject} and only ${String(match.elements.length)} were described, so ${residual.checks.map(([f]) => `\`${f}\``).join(', ')} could not be checked against all of them — narrow the locator`;
-        return { pass: false, failureReason: reason, inconclusive: reason };
-    }
-    const kept = match.elements.filter((element) => satisfiesResiduals(element, residual.checks));
-    // The locator found something and the dropped fields disagree with it. Reported separately from a
-    // plain miss because the fixes are opposite: the element IS there, its value is not what was claimed.
-    if (residual.checks.length > 0 && match.matched && 0 === kept.length && !absent) {
-        const wanted = residual.checks.map(([f, want]) => `${f}=${JSON.stringify(want)}`).join(', ');
-        return {
-            pass: false,
-            failureReason: `element matching ${subject} is present but ${wanted} does not hold`,
-            observed: match.elements
-                .map((element) => residual.checks.map(([f]) => describeResidual(element, f)).join(', '))
-                .join('; '),
-            expected: `an element matching ${subject} with ${wanted}`,
-            assertion: `element.${residual.checks[0]?.[0] ?? 'residual'}`,
-            evidence: match.elements,
-        };
-    }
-    if (residual.checks.length > 0) {
-        match = { ...match, matched: kept.length > 0, count: kept.length, elements: kept };
-    }
-    // A given-but-missing scope is handled ASYMMETRICALLY, because "absent" and "present" ask different
-    // questions of a scope that no longer exists:
-    //  - ABSENT: an element is trivially absent from a container that isn't there. This is also the
-    //    everyday "wait for the #overlay/#spinner/#modal to disappear" pattern (scope the wait to the
-    //    node being removed) — treating scopeMissing as a hard fail there burned the whole timeout and
-    //    flipped a correct green to red. So scopeMissing satisfies an absence check.
-    //  - PRESENT: you cannot confirm an element is present inside a scope that resolved to nothing, and
-    //    silently widening to the whole page is the original false green. So scopeMissing FAILS presence
-    //    (on the wait_for path this just keeps polling until the scope appears).
-    if (absent) {
-        if (true === match.scopeMissing) {
-            return { pass: true, evidence: { absent: true, scopeMissing: true } };
-        }
-        return match.matched
-            ? {
-                pass: false,
-                failureReason: `expected element to be absent but found ${String(match.count)}`,
-                observed: `${String(match.count)} element(s) matching ${subject}`,
-                expected: `no element matching ${subject}`,
-                assertion: 'element.absent',
-                evidence: match.elements,
-            }
-            : { pass: true, evidence: { absent: true } };
-    }
-    if (true === match.scopeMissing) {
-        return {
-            pass: false,
-            failureReason: `scope resolved to no element — cannot confirm ${subject} is present`,
-            observed: 'the requested scope is not on the page (unmounted or selector matched nothing)',
-            expected: `an element matching ${subject} within an existing scope`,
-            assertion: 'element.present',
-            evidence: { scopeMissing: true },
-        };
-    }
-    if (match.matched)
-        return { pass: true, evidence: match.elements };
-    // The near-miss diagnostic below costs one or two EXTRA MATCH round-trips. It only enriches a FAILED
-    // verdict, and a wait loop's interim rechecks read nothing but `pass` — so on the poll path (diagnose
-    // false) skip straight to the plain fail. Under an event flood a role+name element wait was firing
-    // two live-DOM scans per recheck for a diagnostic no interim eval ever reads; the final timeout eval
-    // still runs with diagnose=true and produces the full near-miss.
-    if (!diagnose) {
-        return {
-            pass: false,
-            failureReason: `no element matched ${subject}${state === undefined ? '' : ` in state '${state}'`}`,
-            observed: 'no matching element on the page',
-            expected: `an element matching ${subject}${state === undefined ? '' : ` in state '${state}'`}`,
-            assertion: 'element.present',
-        };
-    }
-    // Diagnostic near-miss: was it there but in the wrong state, or a similar element present?
-    if (state !== undefined) {
-        const relaxed = await matchOnce(session, query, undefined);
-        if (relaxed.matched) {
-            return {
-                pass: false,
-                failureReason: `element exists but not in state '${state}'`,
-                observed: `element matching ${subject} is present, states: ${relaxed.elements[0]?.states.join(', ') ?? 'unknown'}`,
-                expected: `element matching ${subject} in state '${state}'`,
-                assertion: 'element.state',
-                evidence: { nearMiss: relaxed.elements },
-            };
-        }
-    }
-    if (query.role !== undefined && query.name !== undefined) {
-        const roleOnly = await matchOnce(session, { role: query.role }, state);
-        if (roleOnly.matched) {
-            return {
-                pass: false,
-                failureReason: `no '${query.role}' named '${query.name}'; saw: ${roleOnly.elements
-                    .map((e) => e.name)
-                    .filter((n) => n.length > 0)
-                    .join(', ')}`,
-                observed: `${String(roleOnly.count)} '${query.role}' element(s), named: ${roleOnly.elements
-                    .map((e) => e.name)
-                    .filter((n) => n.length > 0)
-                    .join(', ')}`,
-                expected: `a '${query.role}' named '${query.name}'`,
-                assertion: 'element.role+name',
-                evidence: { nearMiss: roleOnly.elements },
-            };
-        }
-    }
-    // The testid near-miss: name what IS here, so a typo is one step from fixed rather than a dead
-    // end. reticle_query has always done this; the predicate path had no equivalent. See
-    // testid-near-miss.ts.
-    const present = match.hint?.presentTestids ?? [];
-    const alsoHere = query.testid === undefined ? undefined : describeTestidMiss(query.testid, present);
-    // A text miss where the string is on the page but split across children reads exactly like an
-    // element that never rendered. Naming the container is the difference between a retry and a bug
-    // report against working code. See split-text-miss.ts.
-    const splitText = describeSplitTextMiss(match.hint?.splitText);
-    const clause = splitText ?? (alsoHere === undefined || '' === alsoHere ? undefined : alsoHere);
-    const suffix = clause === undefined ? '' : ` — ${clause}`;
-    return {
-        pass: false,
-        failureReason: `no element matched ${subject}${state === undefined ? '' : ` in state '${state}'`}${suffix}`,
-        observed: `no matching element on the page${suffix}`,
-        expected: `an element matching ${subject}${state === undefined ? '' : ` in state '${state}'`}`,
-        assertion: 'element.present',
-        ...(present.length > 0 ? { evidence: { presentTestids: present } } : {}),
-    };
-}
-/** The single element of a list, or undefined when there is not exactly one. */
 function oneOf(names) {
     return 1 === names.length ? names[0] : undefined;
 }
@@ -439,17 +289,48 @@ function predicateSince(predicate) {
  * Idempotent, and a more specific `inconclusive` (unreadable locator, superseded window) is never
  * overwritten.
  */
-function annotateThrottledMiss(session, result) {
+function annotateThrottledMiss(session, predicate, result) {
     if (result.pass)
         return result;
+    if (result.inconclusive !== undefined)
+        return result;
+    const preconditionFailure = session.preconditionFailure?.();
+    if (preconditionFailure !== undefined) {
+        return { ...result, inconclusive: preconditionFailure };
+    }
     if (true !== session.throttled?.())
         return result;
-    if (result.inconclusive !== undefined)
+    if (failureRestsOnSeeing(predicate))
         return result;
     return { ...result, inconclusive: THROTTLED_STARVED_NOTE };
 }
+/**
+ * Does this predicate FAIL by having seen something, rather than by not having seen it?
+ *
+ * The starved-tab caveat only applies to a negative reading. Throttling can stop the tab rendering,
+ * so "I did not find it" may mean "I could not look" — but nothing about a starved tab conjures
+ * elements that were not there, so "I found 13 of them" is as true on a throttled tab as anywhere.
+ * An `absent: true` predicate inverts exactly that: its failure IS the positive observation.
+ *
+ * Getting this wrong understated real product failures. An absence assertion that matched a
+ * framework debug page's `ProgrammingError` heading came back `unknown`, and `unknown` is what an
+ * agent re-drives or walks away from — so the proof it was holding never reached anybody.
+ *
+ * `not` flips the polarity again, and nests, so this recurses rather than checking one level.
+ * Composites (`allOf` / `anyOf`) deliberately fall through to `false`: a composite fails for a
+ * reason this cannot name, and keeping the caveat is the conservative half of the trade — an
+ * over-cautious `unknown` costs a re-drive, a missing one costs a wrong verdict.
+ */
+function failureRestsOnSeeing(predicate) {
+    if (PredicateKind.NOT === predicate.kind)
+        return !failureRestsOnSeeing(predicate.predicate);
+    if ('absent' in predicate && true === predicate.absent)
+        return true;
+    // `count: 0` is absence written as arithmetic, and fails the same way: by matching something.
+    return 'count' in predicate && 0 === predicate.count;
+}
 export async function evaluatePredicate(session, predicate, since = 0, diagnose = true) {
-    return annotateThrottledMiss(session, await evaluatePredicateRaw(session, predicate, since, diagnose));
+    return annotateThrottledMiss(session, predicate, await evaluatePredicateRaw(session, predicate, since, diagnose));
 }
 async function evaluatePredicateRaw(session, predicate, since = 0, 
 // Compute the (extra-round-trip) near-miss diagnostics on element failures. Default true so a
@@ -492,11 +373,17 @@ diagnose = true) {
             // with only `text` filled in, so scoping it needs the field, not a second code path.
             undefined === predicate.scope
                 ? { text: predicate.contains }
-                : { text: predicate.contains, scope: predicate.scope }, true === predicate.visible ? ElementState.VISIBLE : undefined, predicate.absent ?? false, diagnose);
+                : {
+                    text: predicate.contains,
+                    scope: predicate.scope,
+                    ...(true === predicate.self ? { self: true } : {}),
+                }, true === predicate.visible ? ElementState.VISIBLE : undefined, predicate.absent ?? false, diagnose);
         case PredicateKind.NET:
             return evalNet(events, predicate);
         case PredicateKind.ROUTE:
-            return evalRoute(events, predicate, session.url);
+            // `since` so an unanswered request already in flight before this window is not counted
+            // against the app — see unansweredIn.
+            return evalRoute(events, predicate, session.url, Math.max(since, predicateSince(predicate)));
         case PredicateKind.CONSOLE:
             return evalConsole(events, predicate);
         case PredicateKind.ANIMATION:
@@ -605,7 +492,13 @@ function assertsExactCount(predicate) {
     }
     if (PredicateKind.NOT === predicate.kind)
         return assertsExactCount(predicate.predicate);
-    return PredicateKind.NET === predicate.kind && predicate.count !== undefined;
+    // `signal` carries `count` for the same reason `net` does, and for the same defect: its schema
+    // calls the double-fire "the defect no state-only oracle can see", because a handler wired twice
+    // leaves the store in the right shape and a presence check green on both. Reading `net` alone
+    // meant a signal count resolved on its first match, so `count: 1` silently meant "at least 1" on
+    // the one channel able to see the bug. `evalSignal` counts correctly; the wait stopped early.
+    return ((PredicateKind.NET === predicate.kind || PredicateKind.SIGNAL === predicate.kind) &&
+        predicate.count !== undefined);
 }
 /**
  * Evaluate now, else wait for it to become true (on each event + a poll) until timeout. `since` is
@@ -792,7 +685,7 @@ export function waitForPredicate(session, predicate, timeoutMs, since = 0) {
                 // `{ pass, evidence, failureReason }` construction DISCARDED them on every timed-out wait and
                 // assert. So the highest-value localization signal was computed and then thrown away exactly
                 // on the failure path where it matters, no matter what the schema declared.
-                finish(annotateThrottledMiss(session, {
+                finish(annotateThrottledMiss(session, predicate, {
                     ...r,
                     pass: false,
                     failureReason: r.failureReason ?? 'timed out waiting for predicate',

package/dist/events/split-text-miss.d.ts

@@ -12,11 +12,12 @@
  * only, so the channel an agent is most likely to copy from produces the one locator this query
  * cannot resolve.
  *
- * Naming the container ends it in one step: `ref` is a locator, and `self: true` returns the scope
- * element itself, so the recovery is a query the agent can paste rather than another guess.
+ * Naming the container ends it in one step: `ref` is a locator, and a scoped text predicate with
+ * `self: true` checks the container's combined subtree text. The recovery is a predicate the agent
+ * can paste rather than another guess, and it is serialized as JSON so the schema test can parse it.
  */
 /** The container descriptor the browser attaches to a missed text query. */
-export interface SplitTextOwner {
+interface SplitTextOwner {
     ref?: string;
     role?: string;
     name?: string;
@@ -27,4 +28,5 @@ export interface SplitTextOwner {
  * Undefined — not a vaguer sentence — when the browser found no container: an ordinary miss keeps the
  * short message it already had. A clause that fires on every failure stops carrying information.
  */
-export declare function describeSplitTextMiss(owner: SplitTextOwner | undefined): string | undefined;
+export declare function describeSplitTextMiss(owner: SplitTextOwner | undefined, searchedText?: string): string | undefined;
+export {};

package/dist/events/split-text-miss.js

@@ -12,9 +12,11 @@
  * only, so the channel an agent is most likely to copy from produces the one locator this query
  * cannot resolve.
  *
- * Naming the container ends it in one step: `ref` is a locator, and `self: true` returns the scope
- * element itself, so the recovery is a query the agent can paste rather than another guess.
+ * Naming the container ends it in one step: `ref` is a locator, and a scoped text predicate with
+ * `self: true` checks the container's combined subtree text. The recovery is a predicate the agent
+ * can paste rather than another guess, and it is serialized as JSON so the schema test can parse it.
  */
+import { PredicateKind } from '@reticlehq/core';
 /** Enough of the label to recognise it; the message is read in a tool result, not a log. */
 const MAX_TEXT = 60;
 /** What the container is, in the fewest words that still identify it on the page. */
@@ -32,13 +34,18 @@ function truncate(value) {
  * Undefined — not a vaguer sentence — when the browser found no container: an ordinary miss keeps the
  * short message it already had. A clause that fires on every failure stops carrying information.
  */
-export function describeSplitTextMiss(owner) {
+export function describeSplitTextMiss(owner, searchedText) {
     if (owner === undefined)
         return undefined;
     const where = nameOf(owner);
     const scope = owner.ref !== undefined && owner.ref.length > 0 ? owner.ref : undefined;
-    const recovery = scope === undefined
+    const recovery = scope === undefined || searchedText === undefined
         ? 'scope to that container and match it as a whole'
-        : `retry as { scope: '${scope}', self: true }`;
+        : `retry as ${JSON.stringify({
+            kind: PredicateKind.TEXT,
+            contains: searchedText,
+            scope,
+            self: true,
+        })}`;
     return `that text IS on the page, split across the children of ${where} — no single element's own text carries it, so no text query can match it; ${recovery}`;
 }