@reticlehq/server 2.7.0 → 2.8.0

package/dist/events/predicate-eval.js

@@ -1,4 +1,4 @@
-import { ElementQuerySchema, ElementState, EventType, PredicateKind, StreamDirection, isDevToolingUrl, } from '@reticlehq/core';
+import { ElementQuerySchema, ElementState, EventType, PredicateKind, QueryBy, StreamDirection, isDevToolingUrl, } from '@reticlehq/core';
 import { z } from 'zod';
 import { describeObserved } from './observed-in-window.js';
 /**
@@ -43,6 +43,98 @@ const ELEMENT_QUERY_FIELDS = [
     'alt',
     'component',
 ];
+/**
+ * The locator fields the browser actually CONSUMES for a given query — mirrors the precedence in
+ * `findIn` (packages/browser/src/dom/query.ts).
+ *
+ * An element query is not a conjunction. It is a first-match dispatch: `by`+`value` wins, then the
+ * component/source anchor, then `role` (which alone also consumes `name`), then the first of
+ * text/label/placeholder/testid/alt that is present. Every OTHER field the caller wrote is dropped on
+ * the floor, silently, and the match reported as if the whole query had been honoured.
+ *
+ * Duplicated here on purpose. The alternative is to send the question to the browser, and the browser
+ * cannot answer it: by the time a match comes back, the fields it ignored are indistinguishable from
+ * the fields it used.
+ */
+function usedQueryFields(query) {
+    const used = new Set();
+    if (query.by !== undefined && query.value !== undefined) {
+        used.add('by').add('value');
+        if (QueryBy.ROLE === query.by)
+            used.add('name');
+        if (QueryBy.COMPONENT === query.by)
+            used.add('component');
+        return used;
+    }
+    if (query.component !== undefined || query.source !== undefined)
+        return used.add('component');
+    if (query.role !== undefined)
+        return used.add('role').add('name');
+    for (const field of ['text', 'label', 'placeholder', 'testid', 'alt']) {
+        if (query[field] !== undefined)
+            return used.add(field);
+    }
+    return used;
+}
+/**
+ * How a dropped field is checked back on the server, against the descriptor the match returned.
+ *
+ * `value` is the field this exists for: `{ role: "textbox", name: "GST amount", value: "274.58" }`
+ * read as a locator has no `by`, so the value half was discarded and the predicate collapsed to "a
+ * textbox named GST amount exists" — trivially true against an EMPTY field. Comparison is TRIMMED and
+ * exact: an input's value is a value, not prose, and a trailing space in either the app or the
+ * predicate is not a finding anybody wants. `""` asserts the field is empty, which describe() reports
+ * by omitting the field entirely.
+ *
+ * `role`/`name`/`value` compare against exactly what `reticle_query` REPORTS, so the words an agent
+ * copies out of a query result are the words that match here. `text` is a substring match, matching
+ * Testing Library's `exact: false`, and falls back to the name because describe() omits `text` when it
+ * equals the accessible name.
+ */
+const RESIDUAL_CHECKS = {
+    value: (element, want) => (element.value ?? '').trim() === want.trim(),
+    role: (element, want) => element.role === want,
+    name: (element, want) => element.name.trim() === want.trim(),
+    text: (element, want) => (element.text ?? element.name).includes(want),
+};
+/**
+ * Split a query's dropped fields into the ones the server can still enforce and the ones it cannot.
+ *
+ * The alternative — refuse every dropped field — breaks calls that work today and that our own
+ * cheatsheet advertises (`{ role: "button", text: "Save" }`), and breaks them into no verdict at all.
+ * Enforcing what we can and refusing only the rest keeps those calls working AS WRITTEN, which is the
+ * outcome the caller was already assuming.
+ */
+export function residualQueryChecks(query) {
+    const used = usedQueryFields(query);
+    const checks = [];
+    const unusable = [];
+    for (const field of ELEMENT_QUERY_FIELDS) {
+        const want = query[field];
+        if (want === undefined || used.has(field))
+            continue;
+        if ('string' === typeof want && RESIDUAL_CHECKS[field] !== undefined)
+            checks.push([field, want]);
+        else
+            unusable.push(field);
+    }
+    return { checks, unusable };
+}
+/** Does this element satisfy every field the locator dropped? */
+export function satisfiesResiduals(element, checks) {
+    return checks.every(([field, want]) => true === RESIDUAL_CHECKS[field]?.(element, want));
+}
+/** How the element's own reading of a dropped field should be REPORTED back on a failure. */
+export function describeResidual(element, field) {
+    const reading = 'value' === field
+        ? (element.value ?? '')
+        : 'text' === field
+            ? (element.text ?? element.name)
+            : 'role' === field
+                ? element.role
+                : element.name;
+    return `${element.role} "${element.name}" ${field}=${JSON.stringify(reading)}`;
+}
 /** Rename known aliases before parse; an explicit canonical key always wins. */
 function applyPredicateAliases(input) {
     if (typeof input !== 'object' || null === input || Array.isArray(input))
@@ -256,7 +348,37 @@ export function matchValue(got, want) {
         }
         return true;
     }
-    return got === want;
+    return structurallyEqual(got, want);
+}
+/**
+ * Value equality for the leaf comparison, because `===` could never match a literal.
+ *
+ * The expected side of a predicate is parsed out of the agent's JSON, so it is a fresh object every
+ * time — reference equality made `equals: ["a", "b"]` false against a store holding exactly
+ * `["a", "b"]`, and there was no value of the app's state that could have made it true. The mirror of
+ * a false green: an assertion nobody could satisfy, on the commonest thing there is to assert about.
+ *
+ * Deliberately strict about shape. An array is not an object, an extra key is a difference, and order
+ * is part of a list's value — `equals` means equals; `dataMatches` is the field-by-field one.
+ */
+function structurallyEqual(got, want) {
+    if (got === want)
+        return true;
+    if (null === got || null === want)
+        return false;
+    if ('object' !== typeof got || 'object' !== typeof want)
+        return false;
+    if (Array.isArray(got) !== Array.isArray(want))
+        return false;
+    if (Array.isArray(got) && Array.isArray(want)) {
+        return got.length === want.length && got.every((v, i) => structurallyEqual(v, want[i]));
+    }
+    const a = got;
+    const b = want;
+    const keys = Object.keys(a);
+    if (keys.length !== Object.keys(b).length)
+        return false;
+    return keys.every((k) => k in b && structurallyEqual(a[k], b[k]));
 }
 /** Shallow JSON pattern match: each key in `pattern` must match (see matchValue). */
 function dataMatches(actual, pattern) {
@@ -486,7 +608,7 @@ export function evalSignal(events, p) {
             ? `signal '${p.name ?? '(any)'}' fired ${String(sameName.length)}x, payload: ${JSON.stringify(sameName[0])}`
             : // 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']) ?? ''))}`,
+                `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)}`,

package/dist/events/predicate.js

@@ -5,8 +5,20 @@ 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';
+import { PredicateSchema, matchValue, evalNet, evalRoute, evalConsole, evalAnimation, evalSignal, evalSettled, residualQueryChecks, satisfiesResiduals, describeResidual, } from './predicate-eval.js';
 export { PredicateSchema, PredicateKind };
+/**
+ * A composite result that carries a child's "nobody could evaluate this" up to the verdict rule.
+ *
+ * `decideVerified` already treats `inconclusive` correctly and does it ahead of the failure clause,
+ * so all a composite has to do is stop dropping the field on its way out. `pass` stays false because
+ * nothing was proven; what changes is that the verdict reads UNKNOWN rather than blaming the app for
+ * a clause the CALL under-specified.
+ */
+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)
@@ -14,8 +26,44 @@ async function matchOnce(session, query, state) {
     return (res.result ?? { matched: false, count: 0, elements: [] });
 }
 async function evalElement(session, query, state, absent, diagnose) {
-    const match = await matchOnce(session, query, state);
+    // 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
@@ -114,6 +162,33 @@ async function evalElement(session, query, state, absent, diagnose) {
         ...(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;
+}
+/**
+ * `readState`'s truncation report, when the caps actually fired.
+ *
+ * Its PRESENCE is the warning — the field is omitted entirely on an intact read, which is what lets
+ * "the list is short" stay distinguishable from "I shortened the list".
+ */
+function truncationOf(result) {
+    if ('object' !== typeof result || null === result)
+        return undefined;
+    const report = result.truncation;
+    return 'object' === typeof report && null !== report
+        ? report
+        : undefined;
+}
+/** A scoped `readState` reply, narrowed to the shape `selectPath` would have produced. */
+function asSelection(result) {
+    if ('object' !== typeof result || null === result)
+        return undefined;
+    const record = result;
+    return 'boolean' === typeof record.found
+        ? { found: record.found, value: record.value }
+        : undefined;
+}
 async function evalState(session, p) {
     const res = await session.command(ReticleCommand.STATE_READ, p.store !== undefined ? { store: p.store } : {});
     if (!res.ok) {
@@ -127,17 +202,75 @@ async function evalState(session, p) {
     }
     const stores = (res.result ?? {}).stores ?? {};
     const names = Object.keys(stores);
-    const storeName = p.store ?? (1 === names.length ? names[0] : undefined);
+    // Ambiguity is about the PATH, not the store count.
+    //
+    // Registering more than one store is normal — an app store, a query cache, and the render meter
+    // Reticle registers itself — and asking "which of these three?" when only one of them HAS the
+    // path is a question with one possible answer. It was costing a real verdict: a bench-app drive
+    // asserting `{path:'view'}` returned `unknown` while the same response body carried the matching
+    // `view` state diff. `unknown` is not a pass, so that is a verification that did not happen.
+    //
+    // So narrow to the stores that actually carry the path, and refuse only when THOSE collide.
+    const candidates = p.store === undefined ? names.filter((n) => selectPath(stores[n], p.path).found) : [];
+    const storeName = p.store ?? (1 === names.length ? names[0] : oneOf(candidates));
     if (storeName === undefined) {
-        // 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 };
+        // With no store registered there is nothing to read, and with two stores that both carry the
+        // path there is no way to pick — neither is a finding about the app, no assertion was evaluated,
+        // so both are inconclusive rather than failed. See honesty/inconclusive.
+        //
+        // Zero candidates is the one case that is NOT a question: every registered store was searched
+        // and none exposes the path, so the assertion cannot hold anywhere. That is the same verdict a
+        // named store has always produced for a missing path, and it falls through to it below.
+        if (0 === names.length) {
+            const reason = 'no registered store to read state from';
+            return { pass: false, failureReason: reason, inconclusive: reason };
+        }
+        if (candidates.length > 1) {
+            // Names the stores that actually collide. Listing all of them made the reader weigh
+            // candidates that could never have matched.
+            const reason = `multiple stores (${candidates.join(', ')}) expose '${p.path}'; name one with \`store\``;
+            return { pass: false, failureReason: reason, inconclusive: reason };
+        }
+        return {
+            pass: false,
+            failureReason: `state path '${p.path}' not found in any registered store (${names.join(', ')})`,
+            observed: `no path '${p.path}' in ${names.join(', ')}`,
+            expected: `some registered store to expose '${p.path}'`,
+            assertion: 'state.path-missing',
+            evidence: { searchedStores: names },
+        };
+    }
+    let selection = selectPath(stores[storeName], p.path);
+    // The whole-store read walks into a value the transport caps may already have mangled.
+    //
+    // `readState` has a SCOPED mode that selects the path out of the RAW store before sanitising, added
+    // precisely so a large or deep path still resolves. This path was not using it, so a store with one
+    // big collection in it truncated the small value sitting beside it, and the comparison then ran
+    // against the literal string "[TRUNCATED]" and returned a confident `no`. Measured on the Atlas
+    // fixture: a one-element array reported as a failed assertion while the same payload's state diffs
+    // showed the assertion holding.
+    //
+    // Re-read only when a cap actually fired, so an intact read costs exactly what it did before.
+    if (truncationOf(res.result) !== undefined) {
+        const scoped = await session.command(ReticleCommand.STATE_READ, {
+            store: storeName,
+            path: p.path,
+        });
+        const result = scoped.ok ? scoped.result : undefined;
+        const scopedTruncation = truncationOf(result);
+        if (scopedTruncation !== undefined) {
+            // Even the raw sub-tree was too big. Nothing here knows what the value IS, so nothing here can
+            // say the assertion failed — that would be an accusation the evidence does not support.
+            const reason = `state '${p.path}' could not be read intact — the transport caps truncated it, so the ` +
+                'value was never compared. Assert a narrower path, or a smaller field inside it';
+            return { pass: false, failureReason: reason, inconclusive: reason };
+        }
+        if (result !== undefined) {
+            const scopedSelection = asSelection(result);
+            if (scopedSelection !== undefined)
+                selection = scopedSelection;
+        }
     }
-    const selection = selectPath(stores[storeName], p.path);
     if (!selection.found) {
         return {
             pass: false,
@@ -206,24 +339,43 @@ diagnose = true) {
         }
         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
-                ? { pass: true, evidence: results.map((r) => r.evidence) }
-                : {
+            // A clause that genuinely failed OUTRANKS one nobody could read. Softening a real failure to
+            // UNKNOWN would hide the defect the agent came for, which is the more expensive of the two
+            // mistakes; the reverse — grading an unreadable clause as a defect in the app — is the one
+            // that was happening.
+            const failed = results.find((r) => !r.pass && r.inconclusive === undefined);
+            if (failed !== undefined) {
+                return {
                     pass: false,
                     failureReason: failed.failureReason ?? 'a sub-predicate of allOf failed',
                     evidence: results,
                 };
+            }
+            const unreadable = results.find((r) => r.inconclusive !== undefined);
+            if (unreadable !== undefined)
+                return unreadableComposite(unreadable, results);
+            return { pass: true, evidence: results.map((r) => r.evidence) };
         }
         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 };
+            if (passed !== undefined)
+                return { pass: true, evidence: passed.evidence };
+            // "No sub-predicate matched" is a claim anyOf is not entitled to make while one of them was
+            // never read: the unreadable clause might have been the one that would have matched.
+            const unreadable = results.find((r) => r.inconclusive !== undefined);
+            if (unreadable !== undefined)
+                return unreadableComposite(unreadable, results);
+            return { pass: false, failureReason: 'no sub-predicate of anyOf matched', evidence: results };
         }
         case PredicateKind.NOT: {
             const inner = await evaluatePredicate(session, predicate.predicate, since, diagnose);
+            // The sharpest case of the three, and the only one that produced a GREEN. `not` read the
+            // child's `pass: false` as "the inner predicate did not hold" and passed — so an assertion
+            // nobody could evaluate became a verdict of verified, manufactured out of a missing reading.
+            // You cannot negate an answer nobody had.
+            if (inner.inconclusive !== undefined)
+                return unreadableComposite(inner, inner);
             return inner.pass
                 ? { pass: false, failureReason: 'negated predicate unexpectedly held', evidence: inner }
                 : { pass: true };

package/dist/flows/flow-classify.js

@@ -27,7 +27,7 @@ export const FlowAssertionGrade = {
     /** Performs actions but asserts nothing observable — passes even if the feature is broken. */
     ASSERTION_FREE: 'assertion-free',
 };
-const ASSERTION_FREE_WARNING = 'This flow performs actions but asserts no observable consequence — it will pass even if the feature is broken. Add a consequence assertion with reticle_annotate (assert-signal / assert-net) or a success-state.';
+const ASSERTION_FREE_WARNING = 'This flow performs actions but asserts no observable consequence, so it will pass even if the feature is broken. Add a consequence assertion with reticle_annotate (assert-signal / assert-net) or a success-state.';
 const PRESENCE_ONLY_WARNING = 'This flow only checks element presence, not an observable consequence (signal/network). A locator healed to the wrong element can still pass it. Add a consequence assertion (assert-signal / assert-net / success-state).';
 const INTENT_WITHOUT_OUTCOME_WARNING = 'This flow declares a business intent but asserts no observable outcome (signal/network) — it claims to verify a goal it cannot actually check. Add a success-state consequence so the flow fails when the goal stops being met.';
 // Consequence vs presence-only classification lives in @reticlehq/core (one source for all graders).

package/dist/flows/flow-tools.js

@@ -367,23 +367,31 @@ export const FLOW_TOOLS = [
                 requested.length > 0) {
                 const concurrency = resolveConcurrency(requested.length, pool.capacity(), parallelArg);
                 const outcomes = await mapWithConcurrency(requested, concurrency, async (flowName) => {
-                    const lease = await acquireLeasedSession(pool, (id) => deps.sessions.get(id) !== undefined, appUrl);
+                    const start = deps.now();
+                    const lease = await acquireLeasedSession(pool, deps.sessions, appUrl, projectId);
                     try {
-                        return await replayNamedFlow(deps, { flowName, sessionId: lease.sessionId });
+                        const replay = await replayNamedFlow(deps, { flowName, sessionId: lease.sessionId });
+                        return { replay, durationMs: deps.now() - start };
                     }
                     finally {
-                        // Always release: a crashed flow must never leak a slot and starve the rest of the suite.
                         await lease.release().catch(() => undefined);
                     }
                 });
                 const parallelRuns = await Promise.all(outcomes.map(async (o, i) => {
                     const name = requested[i] ?? '';
-                    const replay = o.ok && o.value !== undefined ? o.value : leaseFailureReplay(name, o.error);
+                    const replay = o.ok && o.value !== undefined ? o.value.replay : leaseFailureReplay(name, o.error);
                     const loaded = await deps.flows.load(name, projectId).catch(() => null);
                     const flow = loaded !== null && loaded.ok ? loaded.value : undefined;
                     return flow === undefined ? { replay } : { replay, flow };
                 }));
+                const timed = outcomes.map((o, i) => ({
+                    replay: o.ok && o.value !== undefined
+                        ? o.value.replay
+                        : leaseFailureReplay(requested[i] ?? '', o.error),
+                    durationMs: o.ok && o.value !== undefined ? o.value.durationMs : 0,
+                }));
                 const flaky = await recordSuiteFlakes(deps.fs, deps.reticleRoot, parallelRuns);
+                await persistAndSyncVerificationRun(deps, timed, projectId);
                 const verdict = buildSuiteVerdict(parallelRuns);
                 return flaky.length > 0 ? { ...verdict, flaky: [...flaky] } : verdict;
             }

package/dist/flows/heal-run.js

@@ -16,7 +16,7 @@ const HEAL_MESSAGES = {
     NOTHING: 'nothing to heal — every anchor resolved on replay',
     HEALED: "rewrote drifted testid anchors to their nearest surviving match and re-verified the flow's success consequence still fires",
     DRIFT_DRY: 'confident rebind(s) proposed — re-run with apply:true to write them to disk',
-    UNHEALABLE: `drift found, but no nearest match cleared the confidence floor (HEAL_CONFIDENCE_MIN=${HEAL_CONFIDENCE_MIN}); file left untouched — add a data-testid or fix the flow by hand`,
+    UNHEALABLE: `drift found, but no nearest match cleared the confidence floor (HEAL_CONFIDENCE_MIN=${HEAL_CONFIDENCE_MIN}); file left untouched; add a data-testid or fix the flow by hand`,
     HEALED_UNVERIFIED: 'rewrote drifted testid anchors — but this flow declares no success consequence, so the rebind resolves a locator without proving the intent still holds. Add a success-state assertion (reticle_annotate) so future heals can be verified.',
     CONSEQUENCE_BROKEN: 'rebind resolves the drifted locator to a surviving element, but the healed flow no longer satisfies its success consequence — refusing to write (a heal that loses the intent would ship a green-but-dead test). Fix by hand and verify',
 };

package/dist/honesty/blind-spots.js

@@ -7,7 +7,7 @@
 // The kind enum lives in core (it crosses the wire in a BLIND_SPOT event); re-exported here so existing
 // honesty-side imports keep working.
 export { BlindSpotKind } from '@reticlehq/core';
-import { BlindSpotKind, EventType } from '@reticlehq/core';
+import { BlindSpotKind, EventType, ReticleEnv, TRANSPORT_LIMITS, } from '@reticlehq/core';
 /**
  * Whether the observation window saw everything it was asked about.
  *
@@ -29,7 +29,11 @@ const LABEL = {
     [BlindSpotKind.VIRTUALIZED_UNMOUNTED]: (n) => `${String(n)} virtualized unmounted row${1 === n ? '' : 's'} unobserved`,
     // Not "some rows we could not see" — the events never reached the observer, so this window is a
     // SAMPLE of what the app did. Phrased as a caveat on what the whole result MEANS.
-    [BlindSpotKind.RATE_LIMITED]: (n) => `${String(n)} event${1 === n ? '' : 's'} dropped by the bridge rate cap, so this window is SAMPLED — raise RETICLE_MAX_MESSAGES_PER_SECOND for a busy app`,
+    // Names a NUMBER, not a variable. "Raise it for a busy app" leaves the reader to invent a value,
+    // and the one who reported this had to guess before finding one that worked. The default was
+    // raised in the same change, so a page still hitting the cap after that is genuinely unusual and
+    // deserves a concrete next value rather than an adjective.
+    [BlindSpotKind.RATE_LIMITED]: (n) => `${String(n)} event${1 === n ? '' : 's'} dropped by the bridge rate cap, so this window is SAMPLED. Set ${ReticleEnv.MAX_MESSAGES_PER_SECOND}=${String(TRANSPORT_LIMITS.MAX_MESSAGES_PER_SECOND * 5)} and restart the daemon, then re-run this drive`,
     // Not a count of things — a single fact about the page. Phrased so the coverage line reads as a
     // caveat on what the network view MEANS, not as a tally.
     // A count of unverifiable ACTIONS, not of things we failed to look at. The distinction matters:

package/dist/honesty/unsettled.d.ts

@@ -0,0 +1,40 @@
+/**
+ * What an `unsettled` verdict was waiting for, and what its window held instead.
+ *
+ * `unsettled` is the commonest reason a verdict comes back `unknown`, and all it said was that the
+ * page "never settled" — a sentence equally true of a page that polls, a page that animates, and a
+ * page whose write is still open. Those need three different next moves, and an agent handed the
+ * sentence cannot tell which it is holding, so the drive stops there. An `unknown` that explains
+ * itself is a retry; one that does not is a dead end.
+ *
+ * Two releases already tuned this window and neither is undone here. The budget is still spent in
+ * full before anything is called unsettled (settle-in-flight.ts), and the app is still given its
+ * reaction window before any accusation (waitForReaction). This only describes what was true at the
+ * moment the budget genuinely ran out.
+ *
+ * It rides in `because`, beside `verifiedReason`, rather than in a field of its own: the verdict has
+ * one sentence an agent is known to read, and a caveat parked anywhere else is a caveat nobody reads.
+ */
+import type { Predicate } from '../events/predicate.js';
+export interface UnsettledWindow {
+    /** What the wait was for, in the caller's own terms — see `describeWaitTarget`. */
+    waitedFor: string;
+    /** Requests that started in this window and had not come back, as "METHOD url". */
+    stillInFlight: readonly string[];
+}
+/**
+ * The wait, in one phrase.
+ *
+ * The default matters most: a call that declares no `until` waits for the page to go IDLE, and an
+ * agent that never chose that wait cannot be expected to recognise it in a timeout about it.
+ */
+export declare function describeWaitTarget(predicate: Predicate): string;
+/**
+ * The `because` sentence for an unsettled verdict: the wait, the observation, the next move.
+ *
+ * The two branches are the point. An outstanding write is worth waiting for and worth asserting
+ * directly; page churn is neither, and telling an agent to raise its timeout on churn sells it a
+ * slower dead end. Without the detail the sentence is the one that shipped before, so a caller that
+ * cannot supply the facts loses nothing.
+ */
+export declare function unsettledBecause(base: string, window: UnsettledWindow | undefined): string;

package/dist/honesty/unsettled.js

@@ -0,0 +1,78 @@
+/**
+ * What an `unsettled` verdict was waiting for, and what its window held instead.
+ *
+ * `unsettled` is the commonest reason a verdict comes back `unknown`, and all it said was that the
+ * page "never settled" — a sentence equally true of a page that polls, a page that animates, and a
+ * page whose write is still open. Those need three different next moves, and an agent handed the
+ * sentence cannot tell which it is holding, so the drive stops there. An `unknown` that explains
+ * itself is a retry; one that does not is a dead end.
+ *
+ * Two releases already tuned this window and neither is undone here. The budget is still spent in
+ * full before anything is called unsettled (settle-in-flight.ts), and the app is still given its
+ * reaction window before any accusation (waitForReaction). This only describes what was true at the
+ * moment the budget genuinely ran out.
+ *
+ * It rides in `because`, beside `verifiedReason`, rather than in a field of its own: the verdict has
+ * one sentence an agent is known to read, and a caveat parked anywhere else is a caveat nobody reads.
+ */
+import { PredicateKind } from '@reticlehq/core';
+/** Enough to recognise the one that is stuck; not so many that a chatty window eats the verdict. */
+const MAX_LISTED_REQUESTS = 3;
+/**
+ * The wait, in one phrase.
+ *
+ * The default matters most: a call that declares no `until` waits for the page to go IDLE, and an
+ * agent that never chose that wait cannot be expected to recognise it in a timeout about it.
+ */
+export function describeWaitTarget(predicate) {
+    switch (predicate.kind) {
+        case PredicateKind.SETTLED:
+            return 'the page to go idle';
+        case PredicateKind.SIGNAL:
+            return predicate.name === undefined ? 'any signal' : `signal '${predicate.name}'`;
+        case PredicateKind.NET:
+            return `a request${predicate.method === undefined ? '' : ` ${predicate.method}`}${predicate.urlContains === undefined ? '' : ` matching '${predicate.urlContains}'`}`;
+        case PredicateKind.ROUTE:
+            return `a route change${predicate.pathname === undefined ? '' : ` to '${predicate.pathname}'`}${predicate.contains === undefined ? '' : ` containing '${predicate.contains}'`}`;
+        case PredicateKind.STATE:
+            return `state at '${predicate.path}'`;
+        case PredicateKind.TEXT:
+            return `text containing '${predicate.contains}'`;
+        case PredicateKind.ELEMENT:
+            return `an element matching ${JSON.stringify(predicate.query)}`;
+        case PredicateKind.CONSOLE:
+            return 'a console message';
+        case PredicateKind.ANIMATION:
+            return predicate.name === undefined ? 'an animation' : `animation '${predicate.name}'`;
+        case PredicateKind.ALL_OF:
+            return `all of (${predicate.predicates.map(describeWaitTarget).join('; ')})`;
+        case PredicateKind.ANY_OF:
+            return `any of (${predicate.predicates.map(describeWaitTarget).join('; ')})`;
+        case PredicateKind.NOT:
+            return `the absence of ${describeWaitTarget(predicate.predicate)}`;
+    }
+}
+/**
+ * The `because` sentence for an unsettled verdict: the wait, the observation, the next move.
+ *
+ * The two branches are the point. An outstanding write is worth waiting for and worth asserting
+ * directly; page churn is neither, and telling an agent to raise its timeout on churn sells it a
+ * slower dead end. Without the detail the sentence is the one that shipped before, so a caller that
+ * cannot supply the facts loses nothing.
+ */
+export function unsettledBecause(base, window) {
+    if (window === undefined)
+        return `${base} — re-check, or assert a consequence that settles`;
+    if (0 === window.stillInFlight.length) {
+        return (`${base}. It waited for ${window.waitedFor}, and no request started in this window was left ` +
+            'open — what kept the page busy was its own churn (a poll, a timer, an animation), so waiting ' +
+            'longer will not help. Assert the consequence you care about (a signal, a route change, or ' +
+            'store state) instead of waiting for idle, and re-check if the app is genuinely slow');
+    }
+    const shown = window.stillInFlight.slice(0, MAX_LISTED_REQUESTS);
+    const rest = window.stillInFlight.length - shown.length;
+    return (`${base}. It waited for ${window.waitedFor}, and ${String(window.stillInFlight.length)} ` +
+        `request(s) started in this window had not come back: ${shown.join(', ')}` +
+        `${rest > 0 ? `, and ${String(rest)} more` : ''} — re-check once they land, raise timeout_ms, ` +
+        'or assert the request itself so the wait ends on the response rather than on idle');
+}

package/dist/honesty/verified.d.ts

@@ -1,5 +1,6 @@
 import { Verified, VerifiedReason } from '@reticlehq/core';
 import { type HonestyBlock } from './honesty.js';
+import { type UnsettledWindow } from './unsettled.js';
 /**
  * The decision rule: eight trust dimensions in, one answer out.
  *
@@ -51,6 +52,12 @@ interface VerifiedInputs {
      * never read. See `hasUnreadWriteOutcome` — the status line describes the transport, not the result.
      */
     outcomeUnread?: boolean;
+    /**
+     * What the wait was for and what the window held when it ended — read ONLY by the two clauses that
+     * answer UNSETTLED, which is the commonest reason a verdict comes back `unknown` and was also the
+     * least actionable. Optional: without it those clauses say exactly what they said before.
+     */
+    unsettled?: UnsettledWindow;
 }
 interface VerifiedVerdict {
     verified: Verified;

package/dist/honesty/verified.js

@@ -1,5 +1,6 @@
 import { Verified, VerifiedReason, isAbsenceDerived } from '@reticlehq/core';
 import { HonestyGrade } from './honesty.js';
+import { unsettledBecause } from './unsettled.js';
 export function decideVerified(inputs) {
     const { pass, honesty, contradictions = [], settled, outcomePending, outcomeUnread } = inputs;
     // Ahead of the failure clause, because a failure is only the most actionable fact when there WAS
@@ -68,8 +69,7 @@ export function decideVerified(inputs) {
         return {
             verified: Verified.UNKNOWN,
             verifiedReason: VerifiedReason.UNSETTLED,
-            because: `the assertion held, but this window closed before the app finished (${kinds}) — ` +
-                `re-check, or assert a consequence that settles`,
+            because: unsettledBecause(`the assertion held, but this window closed before the app finished (${kinds})`, inputs.unsettled),
         };
     }
     // Below the contradiction clause, and for the same reason a contradiction outranks a dirty
@@ -144,7 +144,7 @@ export function decideVerified(inputs) {
         return {
             verified: Verified.UNKNOWN,
             verifiedReason: VerifiedReason.UNSETTLED,
-            because: 'the page never settled, so the reaction window may have closed before the app finished',
+            because: unsettledBecause('the page never settled, so the reaction window may have closed before the app finished', inputs.unsettled),
         };
     }
     // Partial coverage is a real caveat but not a blocker — it is reported in `honesty.coverage` and