@reticlehq/server 2.4.0 → 2.5.0

package/dist/events/predicate-eval.js

@@ -1,84 +1,147 @@
-import { ElementQuerySchema, ElementState, EventType, } from '@reticlehq/core';
+import { ElementQuerySchema, ElementState, EventType, PredicateKind, StreamDirection, isDevToolingUrl, } from '@reticlehq/core';
 import { z } from 'zod';
-export const PredicateSchema = z.lazy(() => z.discriminatedUnion('kind', [
-    z.object({
-        kind: z.literal('element'),
+import { describeObserved } from './observed-in-window.js';
+/**
+ * Spellings an agent plausibly reaches for, mapped to the real field.
+ *
+ * `route` spells its field `pathname` while `state`, in the same union, spells its `path`. Every one
+ * of these was silently DROPPED before, and because these kinds have all-optional fields, dropping
+ * the only key supplied left a predicate that asserts nothing and passes on anything.
+ */
+const PREDICATE_ALIASES = {
+    [PredicateKind.ROUTE]: { path: 'pathname' },
+    [PredicateKind.NET]: { url: 'urlContains' },
+    [PredicateKind.SIGNAL]: { data: 'dataMatches' },
+};
+/** Rename known aliases before parse; an explicit canonical key always wins. */
+function applyPredicateAliases(input) {
+    if (typeof input !== 'object' || null === input || Array.isArray(input))
+        return input;
+    const obj = input;
+    const aliases = PREDICATE_ALIASES['string' === typeof obj['kind'] ? obj['kind'] : ''];
+    if (aliases === undefined)
+        return input;
+    const out = { ...obj };
+    for (const [from, to] of Object.entries(aliases)) {
+        if (out[from] === undefined)
+            continue;
+        if (out[to] === undefined)
+            out[to] = out[from];
+        delete out[from];
+    }
+    return out;
+}
+/**
+ * Strict on every branch. A key that is nobody's spelling is now a schema error naming it, instead of
+ * a stripped field and a green — see predicate-strict.test.ts for the MCP session that found this.
+ */
+export const PredicateSchema = z.lazy(() => z.preprocess(applyPredicateAliases, z.discriminatedUnion('kind', [
+    z
+        .object({
+        kind: z.literal(PredicateKind.ELEMENT),
         query: ElementQuerySchema,
         state: z.nativeEnum(ElementState).optional(),
         absent: z.boolean().optional(),
-    }),
-    z.object({
-        kind: z.literal('text'),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal(PredicateKind.TEXT),
         contains: z.string(),
         visible: z.boolean().optional(),
         absent: z.boolean().optional(),
-    }),
-    z.object({
-        kind: z.literal('net'),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal(PredicateKind.NET),
         method: z.string().optional(),
         urlContains: z.string().optional(),
         status: z.number().optional(),
         ok: z.boolean().optional(),
         since: z.number().optional(),
         count: z.number().int().nonnegative().optional(),
-    }),
-    z.object({
-        kind: z.literal('route'),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal(PredicateKind.ROUTE),
         pathname: z.string().optional(),
         contains: z.string().optional(),
-    }),
-    z.object({
-        kind: z.literal('console'),
+        since: z.number().optional(),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal(PredicateKind.CONSOLE),
         level: z.string().optional(),
         absent: z.boolean().optional(),
         since: z.number().optional(),
-    }),
-    z.object({
-        kind: z.literal('animation'),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal(PredicateKind.ANIMATION),
         name: z.string().optional(),
         target: z.string().optional(),
         completed: z.boolean().optional(),
-    }),
-    z.object({
-        kind: z.literal('signal'),
+        since: z.number().optional(),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal(PredicateKind.SIGNAL),
         name: z.string().optional(),
         dataMatches: z.record(z.unknown()).optional(),
-    }),
-    z.object({
-        kind: z.literal('state'),
+        since: z.number().optional(),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal(PredicateKind.STATE),
         store: z.string().optional(),
         path: z.string(),
         equals: z.unknown().optional(),
-    }),
-    z.object({ kind: z.literal('settled'), quietMs: z.number().positive().optional() }),
-    z.object({ kind: z.literal('allOf'), predicates: z.array(PredicateSchema) }),
-    z.object({ kind: z.literal('anyOf'), predicates: z.array(PredicateSchema) }),
-    z.object({ kind: z.literal('not'), predicate: PredicateSchema }),
-]));
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal(PredicateKind.SETTLED),
+        quietMs: z.number().positive().optional(),
+    })
+        .strict(),
+    z
+        .object({ kind: z.literal(PredicateKind.ALL_OF), predicates: z.array(PredicateSchema) })
+        .strict(),
+    z
+        .object({ kind: z.literal(PredicateKind.ANY_OF), predicates: z.array(PredicateSchema) })
+        .strict(),
+    z.object({ kind: z.literal(PredicateKind.NOT), predicate: PredicateSchema }).strict(),
+])));
 function str(value) {
-    return typeof value === 'string' ? value : undefined;
+    return 'string' === typeof value ? value : undefined;
 }
 function num(value) {
-    return typeof value === 'number' ? value : undefined;
+    return 'number' === typeof value ? value : undefined;
 }
 /**
  * Match one value against a pattern. Supports `*` (present), strict equality, and operators:
  * `{$gte,$lte,$gt,$lt}` (numbers), `{$contains}` (array membership or substring), `{$length}`.
  */
 export function matchValue(got, want) {
-    if (want === '*')
+    if ('*' === want)
         return got !== undefined;
     // An object is an OPERATOR container only if it actually carries a `$`-prefixed operator. An empty
     // `{}` (or an object with no `$` key) used to enter this branch, iterate zero recognized operators,
     // and `return true` — so `equals: {}` / `dataMatches: {status: {}}` was a green assertion that
     // passed against ANYTHING, undefined included: the exact false green the oracle exists to catch.
     // Without an operator it is a literal to compare, and falls through to strict equality below.
-    const ops = typeof want === 'object' && want !== null && !Array.isArray(want)
+    const ops = 'object' === typeof want && want !== null && !Array.isArray(want)
         ? Object.entries(want)
         : undefined;
     if (ops !== undefined && ops.some(([op]) => op.startsWith('$'))) {
         for (const [op, val] of ops) {
-            const n = typeof got === 'number' ? got : NaN;
+            const n = 'number' === typeof got ? got : NaN;
             switch (op) {
                 case '$gte':
                     if (!(n >= val))
@@ -101,7 +164,7 @@ export function matchValue(got, want) {
                         if (!got.includes(val))
                             return false;
                     }
-                    else if (typeof got === 'string') {
+                    else if ('string' === typeof got) {
                         if (!got.includes(String(val)))
                             return false;
                     }
@@ -110,7 +173,7 @@ export function matchValue(got, want) {
                     }
                     break;
                 case '$length':
-                    if (!((Array.isArray(got) || typeof got === 'string') && got.length === val)) {
+                    if (!((Array.isArray(got) || 'string' === typeof got) && got.length === val)) {
                         return false;
                     }
                     break;
@@ -140,7 +203,7 @@ function dataMatches(actual, pattern) {
  * This exists so an agent can assert on the OUTCOME rather than on a number Reticle invented.
  */
 function callSucceeded(data) {
-    if (typeof data['ok'] === 'boolean')
+    if ('boolean' === typeof data['ok'])
         return data['ok'];
     const status = num(data['status']);
     return status === undefined || status < 400;
@@ -183,7 +246,11 @@ export function evalNet(events, p) {
         : {
             pass: false,
             failureReason: `no network call matched ${JSON.stringify(p)}`,
-            observed: 'no matching network call in the window',
+            // Same reasoning as the signal miss: "no matching call" cannot be told apart from "the app
+            // made no calls at all", and those need different fixes.
+            observed: describeObserved('calls', events
+                .filter((e) => e.type === EventType.NET_REQUEST)
+                .map((e) => `${str(e.data['method']) ?? 'GET'} ${str(e.data['url']) ?? ''}`)),
             expected: `at least one call matching ${JSON.stringify(p)}`,
             assertion: 'net.present',
         };
@@ -257,17 +324,17 @@ export function evalConsole(events, p) {
                 e.type === EventType.CONSOLE_ERROR ||
                 e.type === EventType.ERROR_UNCAUGHT);
         }
-        if (p.level === 'error')
+        if ('error' === p.level)
             return isErr;
         return e.type === CONSOLE_LEVEL_TYPE[p.level];
     });
-    if (p.absent === true) {
-        return matches.length === 0
+    if (true === p.absent) {
+        return 0 === matches.length
             ? { pass: true, evidence: { absent: true } }
             : {
                 pass: false,
                 failureReason: `expected no ${p.level ?? 'console'} entries but found ${String(matches.length)}`,
-                observed: `${String(matches.length)} ${p.level ?? 'console'} entr${matches.length === 1 ? 'y' : 'ies'}`,
+                observed: `${String(matches.length)} ${p.level ?? 'console'} entr${1 === matches.length ? 'y' : 'ies'}`,
                 expected: `no ${p.level ?? 'console'} entries`,
                 assertion: 'console.absent',
                 evidence: matches.map((e) => e.data),
@@ -284,7 +351,7 @@ export function evalConsole(events, p) {
         };
 }
 export function evalAnimation(events, p) {
-    const wantType = p.completed === true ? EventType.ANIM_END : EventType.ANIM_START;
+    const wantType = true === p.completed ? EventType.ANIM_END : EventType.ANIM_START;
     const hit = events.find((e) => {
         if (e.type !== wantType)
             return false;
@@ -330,7 +397,9 @@ export function evalSignal(events, p) {
             : `no signal matched ${JSON.stringify(p)}`,
         observed: sameName.length > 0
             ? `signal '${p.name ?? '(any)'}' fired ${String(sameName.length)}x, payload: ${JSON.stringify(sameName[0])}`
-            : `signal '${p.name ?? '(any)'}' never fired in the window`,
+            : // Name what DID fire: a typo'd signal name and a genuinely dead action produce the same
+                // sentence otherwise, and the agent cannot tell them apart. See observed-in-window.ts.
+                `signal '${p.name ?? '(any)'}' never fired — ${describeObserved('signals', events.filter((e) => e.type === EventType.SIGNAL).map((e) => str(e.data['name']) ?? ''))}`,
         expected: p.dataMatches === undefined
             ? `signal '${p.name ?? '(any)'}' to fire`
             : `signal '${p.name ?? '(any)'}' with payload matching ${JSON.stringify(p.dataMatches)}`,
@@ -364,6 +433,12 @@ const SETTLE_ACTIVITY = new Set([
     EventType.DOM_REMOVED,
     EventType.DOM_ATTR,
 ]);
+/** The three net-shaped event types a URL can be read off — the only ones dev tooling can produce. */
+const NET_TYPES = new Set([
+    EventType.NET_PENDING,
+    EventType.NET_REQUEST,
+    EventType.NET_STREAM,
+]);
 /** Default quiet window — enough to absorb a render+xhr settle without waiting on slow polls. */
 const DEFAULT_QUIET_MS = 500;
 /**
@@ -372,8 +447,24 @@ const DEFAULT_QUIET_MS = 500;
  * now, not to any buffered event — so `now` is injected (CLAUDE.md rule 7), and the wait loop's
  * poll interval is what eventually flips this to pass once activity stops.
  */
-export function evalSettled(events, p, now) {
+export function evalSettled(allEvents, p, now) {
     const quietMs = p.quietMs ?? DEFAULT_QUIET_MS;
+    // Dev-tooling traffic is the framework talking about ITSELF (see DevToolingChannel) and says
+    // nothing about whether the app finished its work — but it was holding settle open. Dropped from
+    // both halves of the calculation below (in-flight AND the quiet timer) and DISCLOSED on the
+    // evidence, never silently swallowed.
+    const ignoredDevTooling = [];
+    const events = allEvents.filter((e) => {
+        if (!NET_TYPES.has(e.type))
+            return true;
+        const url = str(e.data['url']);
+        if (!isDevToolingUrl(url))
+            return true;
+        if (url !== undefined && !ignoredDevTooling.includes(url))
+            ignoredDevTooling.push(url);
+        return false;
+    });
+    const disclosure = 0 === ignoredDevTooling.length ? {} : { ignoredDevTooling };
     // A request that STARTED (NET_PENDING) but never completed (NET_REQUEST with the same id) is
     // still in flight — the page is NOT settled no matter how quiet the DOM has gone. Without this,
     // a slow save reads as "settled" the instant its spinner stops mutating the DOM: the exact
@@ -417,16 +508,16 @@ export function evalSettled(events, p, now) {
         if (id === undefined)
             continue;
         const direction = str(e.data['direction']);
-        if (direction === 'open')
+        if (StreamDirection.OPEN === direction)
             openStreams.add(id);
-        else if (direction === 'close')
+        else if (StreamDirection.CLOSE === direction)
             openStreams.delete(id);
     }
     const streaming = openStreams.size;
     if (inFlight + streaming > 0) {
-        const what = streaming === 0
+        const what = 0 === streaming
             ? `${String(inFlight)} request(s) still in flight`
-            : inFlight === 0
+            : 0 === inFlight
                 ? `${String(streaming)} response body(ies) still streaming`
                 : `${String(inFlight)} request(s) in flight and ${String(streaming)} response body(ies) still streaming`;
         return {
@@ -435,7 +526,12 @@ export function evalSettled(events, p, now) {
             observed: what,
             expected: 'no requests in flight and no response bodies still streaming',
             assertion: 'settled.in-flight',
-            evidence: { settled: false, inFlight, ...(streaming > 0 ? { streaming } : {}) },
+            evidence: {
+                settled: false,
+                inFlight,
+                ...(streaming > 0 ? { streaming } : {}),
+                ...disclosure,
+            },
         };
     }
     let lastT = -1;
@@ -449,12 +545,15 @@ export function evalSettled(events, p, now) {
     if (lastT < 0) {
         return {
             pass: true,
-            evidence: { settled: true, quietForMs: null, note: 'no activity to settle' },
+            evidence: { settled: true, quietForMs: null, note: 'no activity to settle', ...disclosure },
         };
     }
     const quietForMs = now - lastT;
     if (quietForMs >= quietMs) {
-        return { pass: true, evidence: { settled: true, quietForMs, lastActivity: lastType } };
+        return {
+            pass: true,
+            evidence: { settled: true, quietForMs, lastActivity: lastType, ...disclosure },
+        };
     }
     return {
         pass: false,
@@ -462,6 +561,11 @@ export function evalSettled(events, p, now) {
         observed: `last activity was ${String(lastType)}, ${String(quietForMs)}ms ago`,
         expected: `${String(quietMs)}ms of quiet`,
         assertion: 'settled.quiet',
-        evidence: { quietForMs, lastActivity: lastType },
+        evidence: { quietForMs, lastActivity: lastType, ...disclosure },
+        // The one failure in this file that knows exactly when it could stop being one: if nothing else
+        // happens, the window closes in this many ms. A waiter that re-checks THEN instead of on its next
+        // blind tick stops paying up to a full poll interval on the hottest call in the product. Only a
+        // hint — the predicate is still evaluated at that moment, and can still fail.
+        retryAfterMs: quietMs - quietForMs,
     };
 }

package/dist/events/predicate.d.ts

@@ -1,8 +1,8 @@
-import { type CommandResult, type ReticleEvent } from '@reticlehq/core';
+import { PredicateKind, type CommandResult, type ReticleEvent } from '@reticlehq/core';
 import type { ExpectedLink } from '../capsule/divergence.js';
 import { type AmbientCounts } from '../journal/ambient.js';
 import { PredicateSchema, type Predicate, type EvalResult } from './predicate-eval.js';
-export { PredicateSchema };
+export { PredicateSchema, PredicateKind };
 export type { Predicate, EvalResult };
 /** The subset of Session the predicate engine needs — keeps it testable with a fake. */
 export interface PredicateSession {

package/dist/events/predicate.js

@@ -1,9 +1,12 @@
-import { ElementState, ReticleCommand, } from '@reticlehq/core';
+import { ElementState, PredicateKind, ReticleCommand, } from '@reticlehq/core';
+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 { predicateToExpectedLinks } from '../capsule/predicate-to-links.js';
 import { isAmbient, ambientKeyOf } from '../journal/ambient.js';
 import { PredicateSchema, matchValue, evalNet, evalRoute, evalConsole, evalAnimation, evalSignal, evalSettled, } from './predicate-eval.js';
-export { PredicateSchema };
+export { PredicateSchema, PredicateKind };
 async function matchOnce(session, query, state) {
     const res = await session.command(ReticleCommand.MATCH, { query, state });
     if (!res.ok)
@@ -23,7 +26,7 @@ async function evalElement(session, query, state, absent, diagnose) {
     //    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 (match.scopeMissing === true) {
+        if (true === match.scopeMissing) {
             return { pass: true, evidence: { absent: true, scopeMissing: true } };
         }
         return match.matched
@@ -37,7 +40,7 @@ async function evalElement(session, query, state, absent, diagnose) {
             }
             : { pass: true, evidence: { absent: true } };
     }
-    if (match.scopeMissing === true) {
+    if (true === match.scopeMissing) {
         return {
             pass: false,
             failureReason: `scope resolved to no element — cannot confirm ${subject} is present`,
@@ -96,12 +99,19 @@ async function evalElement(session, query, state, absent, diagnose) {
             };
         }
     }
+    // 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);
+    const suffix = alsoHere === undefined || '' === alsoHere ? '' : ` — ${alsoHere}`;
     return {
         pass: false,
-        failureReason: `no element matched ${subject}${state === undefined ? '' : ` in state '${state}'`}`,
-        observed: 'no matching element on the page',
+        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 } } : {}),
     };
 }
 async function evalState(session, p) {
@@ -117,14 +127,15 @@ async function evalState(session, p) {
     }
     const stores = (res.result ?? {}).stores ?? {};
     const names = Object.keys(stores);
-    const storeName = p.store ?? (names.length === 1 ? names[0] : undefined);
+    const storeName = p.store ?? (1 === names.length ? names[0] : undefined);
     if (storeName === undefined) {
-        return {
-            pass: false,
-            failureReason: names.length === 0
-                ? 'no registered store to read state from'
-                : `multiple stores (${names.join(', ')}); name one with \`store\``,
-        };
+        // Neither of these is a finding about the app. With several stores registered the call simply did
+        // not say which one to read; with none, there is nothing to read at all. No assertion was
+        // evaluated either way, so this is inconclusive rather than failed — see honesty/inconclusive.
+        const reason = 0 === names.length
+            ? 'no registered store to read state from'
+            : `multiple stores (${names.join(', ')}); name one with \`store\``;
+        return { pass: false, failureReason: reason, inconclusive: reason };
     }
     const selection = selectPath(stores[storeName], p.path);
     if (!selection.found) {
@@ -153,31 +164,39 @@ async function evalState(session, p) {
         evidence: { store: storeName, path: p.path, value: capDepth(selection.value, 1) },
     };
 }
+/** The predicate's own event-time floor, if its kind carries one. */
+function predicateSince(predicate) {
+    return 'since' in predicate && 'number' === typeof predicate.since ? predicate.since : 0;
+}
 export async function evaluatePredicate(session, predicate, since = 0, 
 // Compute the (extra-round-trip) near-miss diagnostics on element failures. Default true so a
 // one-shot assert is fully diagnostic; the wait loop passes false on its interim polls (which read
 // only `pass`) and true on the final timeout eval, so a flood no longer pays for a diagnostic nobody
 // reads. Only element/text failures have a near-miss; everything else ignores this.
 diagnose = true) {
-    const events = session.eventsSince(since);
+    // A predicate's own `since` is a TIGHTER event-time floor than the caller's — an agent that took
+    // `since` from the act it just performed is scoping the assertion to that action's aftermath. It is
+    // applied here, once, rather than in each eval: the floor means the same thing for every kind that
+    // reads the event stream, and net/console re-applying it is a no-op.
+    const events = session.eventsSince(Math.max(since, predicateSince(predicate)));
     switch (predicate.kind) {
-        case 'element':
+        case PredicateKind.ELEMENT:
             return evalElement(session, predicate.query, predicate.state, predicate.absent ?? false, diagnose);
-        case 'text':
-            return evalElement(session, { text: predicate.contains }, predicate.visible === true ? ElementState.VISIBLE : undefined, predicate.absent ?? false, diagnose);
-        case 'net':
+        case PredicateKind.TEXT:
+            return evalElement(session, { text: predicate.contains }, true === predicate.visible ? ElementState.VISIBLE : undefined, predicate.absent ?? false, diagnose);
+        case PredicateKind.NET:
             return evalNet(events, predicate);
-        case 'route':
+        case PredicateKind.ROUTE:
             return evalRoute(events, predicate);
-        case 'console':
+        case PredicateKind.CONSOLE:
             return evalConsole(events, predicate);
-        case 'animation':
+        case PredicateKind.ANIMATION:
             return evalAnimation(events, predicate);
-        case 'signal':
+        case PredicateKind.SIGNAL:
             return evalSignal(events, predicate);
-        case 'state':
+        case PredicateKind.STATE:
             return evalState(session, predicate);
-        case 'settled': {
+        case PredicateKind.SETTLED: {
             // Drop events on learned-ambient regions (chat/ticker churn) before the settle check — by ref
             // alone, NOT by attribution: window-attribution ("happened during the action window") is a time
             // heuristic, never causation, so a chat message arriving mid-window must not hold settle open.
@@ -185,7 +204,7 @@ diagnose = true) {
             const settleEvents = counts === undefined ? events : events.filter((e) => !isAmbient(counts, ambientKeyOf(e)));
             return evalSettled(settleEvents, predicate, session.elapsed());
         }
-        case 'allOf': {
+        case PredicateKind.ALL_OF: {
             const results = await Promise.all(predicate.predicates.map((p) => evaluatePredicate(session, p, since, diagnose)));
             const failed = results.find((r) => !r.pass);
             return failed === undefined
@@ -196,14 +215,14 @@ diagnose = true) {
                     evidence: results,
                 };
         }
-        case 'anyOf': {
+        case PredicateKind.ANY_OF: {
             const results = await Promise.all(predicate.predicates.map((p) => evaluatePredicate(session, p, since, diagnose)));
             const passed = results.find((r) => r.pass);
             return passed !== undefined
                 ? { pass: true, evidence: passed.evidence }
                 : { pass: false, failureReason: 'no sub-predicate of anyOf matched', evidence: results };
         }
-        case 'not': {
+        case PredicateKind.NOT: {
             const inner = await evaluatePredicate(session, predicate.predicate, since, diagnose);
             return inner.pass
                 ? { pass: false, failureReason: 'negated predicate unexpectedly held', evidence: inner }
@@ -244,12 +263,12 @@ const COUNT_CONFIRM_MS = 300;
  * must stay that way, or every ordinary wait pays the confirmation delay for nothing.
  */
 function assertsExactCount(predicate) {
-    if (predicate.kind === 'allOf' || predicate.kind === 'anyOf') {
+    if (PredicateKind.ALL_OF === predicate.kind || PredicateKind.ANY_OF === predicate.kind) {
         return predicate.predicates.some(assertsExactCount);
     }
-    if (predicate.kind === 'not')
+    if (PredicateKind.NOT === predicate.kind)
         return assertsExactCount(predicate.predicate);
-    return predicate.kind === 'net' && predicate.count !== undefined;
+    return PredicateKind.NET === predicate.kind && predicate.count !== undefined;
 }
 /**
  * Evaluate now, else wait for it to become true (on each event + a poll) until timeout. `since` is
@@ -263,10 +282,24 @@ export function waitForPredicate(session, predicate, timeoutMs, since = 0) {
             failureReason: error instanceof Error ? error.message : String(error),
         });
         let cooldownTimer;
+        /** One-shot re-check timed to when a time-based predicate could first pass. See retryAfterMs. */
+        let hintTimer;
         // An exact-count wait keeps watching after it first reads true — see COUNT_CONFIRM_MS.
         const holdsForCount = assertsExactCount(predicate);
         let confirming = false;
         let confirmTimer;
+        /** Report a wait that could not run, and END it — see guardedCheck. */
+        const failWait = (error) => {
+            log('reticle_wait_failed', {
+                predicate: predicate.kind,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            finish({
+                ...failed(error),
+                failureReason: 'the wait could not be evaluated and was ended rather than left pending: ' +
+                    (error instanceof Error ? error.message : String(error)),
+            });
+        };
         const finish = (result) => {
             if (done)
                 return;
@@ -276,6 +309,8 @@ export function waitForPredicate(session, predicate, timeoutMs, since = 0) {
             clearTimeout(timer);
             if (cooldownTimer !== undefined)
                 clearTimeout(cooldownTimer);
+            if (hintTimer !== undefined)
+                clearTimeout(hintTimer);
             if (confirmTimer !== undefined)
                 clearTimeout(confirmTimer);
             resolve(result);
@@ -305,8 +340,19 @@ export function waitForPredicate(session, predicate, timeoutMs, since = 0) {
             // final timeout eval below runs with full diagnostics.
             void evaluatePredicate(session, predicate, since, false)
                 .then((r) => {
-                if (!r.pass)
+                if (!r.pass) {
+                    // A time-based failure knows when it could stop being one — re-check THEN rather than on
+                    // the next blind tick. Without this, every `settled` wait paid up to a full poll interval
+                    // of dead time after the quiet window had already closed: measured at 566–627ms across
+                    // the fleet for a 500ms window, on the call an agent makes after almost every action.
+                    // Additive — the backstop interval below still runs, so a missed hint costs nothing.
+                    const hint = r.retryAfterMs;
+                    if ('number' === typeof hint && hint > 0 && hint < POLL_INTERVAL_MS) {
+                        clearTimeout(hintTimer);
+                        hintTimer = setTimeout(check, hint);
+                    }
                     return;
+                }
                 // "Exactly N" cannot be concluded from a passing sample — the count can still rise. Hold,
                 // re-evaluate WITH diagnostics, and let that second read be the verdict: if an N+1th
                 // arrived in the meantime it now fails, carrying observed/expected rather than a bare no.
@@ -344,10 +390,41 @@ export function waitForPredicate(session, predicate, timeoutMs, since = 0) {
                 }, MIN_RECHECK_GAP_MS);
             });
         };
+        /**
+         * Run a re-check so that NOTHING can leave this promise pending.
+         *
+         * `check` is fired from an event listener and an interval, neither of which is inside the
+         * awaited chain. A synchronous throw there reached the process as an uncaughtException; a
+         * rejection reached it as an unhandledRejection. Either way the wait never resolved and the tool
+         * handler never returned — the agent sees a call that simply never comes back.
+         *
+         * That is the exact shape reported from a Plane (Next 14 + MobX) session, which tears the page
+         * session down and rebuilds it on EVERY navigation, so a `{kind:"route"}` predicate always races
+         * a teardown of the very session it is watching: `browser.command ok:true` for the click, and
+         * then no `tool.handler` for that callId, ever.
+         *
+         * A wait that cannot evaluate is a FAILED wait, not an eternal one. It now says so and finishes.
+         */
+        const guardedCheck = () => {
+            try {
+                const pending = check();
+                if (pending instanceof Promise)
+                    pending.catch(failWait);
+            }
+            catch (error) {
+                failWait(error);
+            }
+        };
+        // Bound to the CALL that started this wait. The listener fires from the WebSocket message
+        // handler and the interval from the timer queue — neither is in the awaited chain, so without
+        // this every re-check opened a new call at depth 0 and emitted a `browser.command` with no
+        // `tool.handler`. Measured on one healthy run: 23 such orphans, which is precisely the
+        // documented signature of a HUNG call. A diagnostic that fires on healthy runs is not one.
+        const boundCheck = bindSpanContext(guardedCheck);
         const unsub = session.onEvent(() => {
-            check();
+            boundCheck();
         });
-        const interval = setInterval(check, POLL_INTERVAL_MS);
+        const interval = setInterval(boundCheck, POLL_INTERVAL_MS);
         const timer = setTimeout(() => {
             void evaluatePredicate(session, predicate, since)
                 .then((r) => {
@@ -382,11 +459,11 @@ export function waitForPredicate(session, predicate, timeoutMs, since = 0) {
  * green ⇏ this-branch-held, re-checks each branch and keeps the winners.
  */
 export async function provenExpectedLinks(session, predicate, since = 0) {
-    if (predicate.kind === 'allOf') {
+    if (PredicateKind.ALL_OF === predicate.kind) {
         const per = await Promise.all(predicate.predicates.map((p) => provenExpectedLinks(session, p, since)));
         return per.flat();
     }
-    if (predicate.kind === 'anyOf') {
+    if (PredicateKind.ANY_OF === predicate.kind) {
         const per = await Promise.all(predicate.predicates.map(async (p) => (await evaluatePredicate(session, p, since)).pass
             ? provenExpectedLinks(session, p, since)
             : []));