@reticlehq/server 2.7.0 → 2.9.0

package/dist/flows/flow-tools.js

@@ -255,7 +255,9 @@ export const FLOW_TOOLS = [
             'stale ref. On an anchor MISS returns legible DRIFT { step, anchor, drift:{ reasonKind, reason, ' +
             'nearest } } (the closest surviving testid) and stops — the "whose fault is it" contract. ' +
             'Returns { name, status: ok|drift|error, steps:[...] }; missing/malformed files and action ' +
-            'failures are status:error with a structured code (distinct from contract-changed drift).',
+            'failures are status:error with a structured code (distinct from contract-changed drift). ' +
+            'An ok replay of a flow that asserts no consequence also carries unverifiable:{reason} — it ' +
+            'would read ok even if the feature were broken, so do NOT treat that ok as proof.',
         inputSchema: {
             flow: z
                 .string()
@@ -285,6 +287,12 @@ export const FLOW_TOOLS = [
                 .optional()
                 .describe('Push-default deviation report over the replay segments: ranked deviations vs the learned envelope + a nominal count, or a fall-back note below 3 runs.'),
             error: z.object({ code: z.string(), message: z.string() }).optional(),
+            // Declared here or a validating profile strips it -- the same way `name` was stripped once.
+            // A field the handler sets and the schema omits arrives as nothing, silently.
+            unverifiable: z
+                .object({ reason: z.string() })
+                .optional()
+                .describe('Set on an ok replay that cannot fail: the flow asserts no observable consequence, so it passes even when the feature is broken. Same reason reticle_flow_verify reports.'),
             decision: z
                 .object({
                 verdict: z.string(),
@@ -367,23 +375,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/flows/replay.js

@@ -247,6 +247,9 @@ export async function replayProgram(session, program, confirmDangerous = false)
                 session.beginAction(ReticleTool.REPLAY, { steps: liveSteps.length });
                 let r;
                 try {
+                    // DIVERGENCE: replay sends one batched ACT_SEQUENCE command to the browser;
+                    // live (tools/act-tools.ts) sends N individual ACT commands for per-step timeout +
+                    // progress. A bug in either is invisible from the other.
                     r = await session.command(ReticleCommand.ACT_SEQUENCE, { steps: liveSteps });
                 }
                 finally {

package/dist/honesty/accepted-write.d.ts

@@ -10,5 +10,8 @@ import { type ReticleEvent } from '@reticlehq/core';
  * optimistically rendered "dispatched", the page settled, every channel agreed — and the server
  * REVERTED it to `held` 1.2 s later. The verdict was not wrong about what it observed. It was early,
  * and nothing in the response said so except the status code nobody was reading.
+ *
+ * The DEV TOOLCHAIN's own traffic is excluded, on the same rule every other check applies: a verdict
+ * about the app must not be decided by a request the app did not make.
  */
 export declare function hasAcceptedWrite(events: readonly ReticleEvent[]): boolean;

package/dist/honesty/accepted-write.js

@@ -1,5 +1,5 @@
-import { EventType, HTTP_ACCEPTED } from '@reticlehq/core';
-import { asNumber } from '../tools/tools-helpers.js';
+import { EventType, HTTP_ACCEPTED, isDevToolingUrl } from '@reticlehq/core';
+import { asNumber, asString } from '../tools/tools-helpers.js';
 /**
  * Did a write in this window answer `202 Accepted`?
  *
@@ -11,7 +11,12 @@ import { asNumber } from '../tools/tools-helpers.js';
  * optimistically rendered "dispatched", the page settled, every channel agreed — and the server
  * REVERTED it to `held` 1.2 s later. The verdict was not wrong about what it observed. It was early,
  * and nothing in the response said so except the status code nobody was reading.
+ *
+ * The DEV TOOLCHAIN's own traffic is excluded, on the same rule every other check applies: a verdict
+ * about the app must not be decided by a request the app did not make.
  */
 export function hasAcceptedWrite(events) {
-    return events.some((e) => e.type === EventType.NET_REQUEST && asNumber(e.data['status']) === HTTP_ACCEPTED);
+    return events.some((e) => e.type === EventType.NET_REQUEST &&
+        asNumber(e.data['status']) === HTTP_ACCEPTED &&
+        !isDevToolingUrl(asString(e.data['url'])));
 }

package/dist/honesty/already-true.js

@@ -17,8 +17,23 @@
 import { PredicateKind } from '@reticlehq/core';
 export function readsDomState(predicate) {
     switch (predicate.kind) {
+        // ROUTE is here, and it did not used to be. It was purely event-based — satisfiable only by a
+        // navigation inside the act's window, and therefore unable to be answered by the past — so it
+        // sat with the floored kinds below.
+        //
+        // It gained a fallback to the CURRENT route for the case where the window holds no route change,
+        // which is what makes "did the session survive a reload?" answerable at all. Without a
+        // before-check that fallback is a guaranteed green: the app is already on /login, the click's
+        // handler is broken, nothing navigates, and an assertion that the action reached /login passes
+        // on the strength of it having been there all along. A bare `{ kind: 'route' }` becomes
+        // unconditionally true, because there is always a current route.
+        //
+        // One extra query on the act path buys `already_true`, reported as UNKNOWN with the reason
+        // rather than as a pass. The fallback removed a false red; this is what stops it becoming a
+        // false green, and that is the trade this codebase never makes.
         case PredicateKind.ELEMENT:
         case PredicateKind.TEXT:
+        case PredicateKind.ROUTE:
             return true;
         case PredicateKind.ALL_OF:
         case PredicateKind.ANY_OF:

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,13 +29,21 @@ 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:
     // nothing here was missed, there was simply never a verdict to observe, and no amount of extra
     // instrumentation would produce one.
     [BlindSpotKind.VERDICTLESS_SEND]: (n) => `${String(n)} one-way IPC send${1 === n ? '' : 's'} dispatched with NO verdict — the renderer never learns whether the main process handled ${1 === n ? 'it' : 'them'}, so this cannot be confirmed from the page`,
+    // Not a tally — a fact about the app's wiring, phrased as what the EMPTY state channel means. An
+    // agent reading `stateDiffs: []` otherwise reads "the app changed no state", which is a claim
+    // nothing here can support. Names the one-line fix, because the reader is the one who can apply it.
+    [BlindSpotKind.UNWATCHED_STATE]: () => 'no subscribable store is registered, so NO state change is observed — an empty stateDiffs here means unwatched, not unchanged (register the store itself in your reticle-dev module: registerStore(name, store), not a getter)',
     [BlindSpotKind.WRAPPED_NETWORK]: () => 'fetch was already wrapped before Reticle, so recorded requests may differ from what was sent',
     // A fact about the app's wiring, not a tally. Says what the empty network view MEANS, because an
     // empty one here is indistinguishable from "this app made no backend calls" — and that reading is

package/dist/honesty/honesty.d.ts

@@ -33,6 +33,15 @@ interface HonestyInputs {
      * knows whether a blind-spot note came from the browser transport or from a boundary in the page.
      */
     losses?: readonly CaptureLoss[];
+    /**
+     * Did the page go quiet inside the action's window? Omitted when nothing measured it.
+     *
+     * Settlement stopped being a veto over a declared consequence that held (see `verified.ts`), and a
+     * fact that no longer decides the verdict must not therefore disappear: a page that never goes
+     * idle is worth knowing about, and a caller who cares can still gate on it. Reported here rather
+     * than beside `verified`, where the answer belongs to the rule and not to its inputs.
+     */
+    settled?: boolean;
 }
 export interface HonestyBlock {
     grade: HonestyGrade;
@@ -52,6 +61,8 @@ export interface HonestyBlock {
         issues: string[];
         losses?: CaptureLoss[];
     };
+    /** Whether the page went quiet in this window — present only when it was measured. */
+    settled?: boolean;
 }
 export declare function buildHonestyBlock(inputs: HonestyInputs): HonestyBlock;
 interface HonestyBar {

package/dist/honesty/honesty.js

@@ -46,6 +46,7 @@ export function buildHonestyBlock(inputs) {
             ? {}
             : { envelope: { samples, sufficient: samples >= MIN_ENVELOPE_SAMPLES } }),
         coverage: { ...(pct === undefined ? {} : { pct }), partial },
+        ...(inputs.settled === undefined ? {} : { settled: inputs.settled }),
         integrity: {
             clean: 0 === issues.length,
             issues,

package/dist/honesty/uncaptured-bodies.d.ts

@@ -8,12 +8,14 @@
  * every other field in the record agrees is a clean 200.
  *
  * So an omission is declared rather than left to inference, with the one line that fixes it. Present
- * only when a body-bearing call was returned AND none of them carried a body, so an app that already
- * captures bodies pays nothing and the field's PRESENCE is the warning.
+ * only when a body-bearing call was returned AND no body — request or response — was recorded
+ * anywhere in the result, so an app that already captures bodies pays nothing and the field's
+ * PRESENCE is the warning.
  */
 export declare function bodiesNotCaptured(calls: {
     method?: string;
     requestBody?: string;
+    responseBody?: string;
 }[]): {
     bodiesNotCaptured?: string;
 };

package/dist/honesty/uncaptured-bodies.js

@@ -10,13 +10,20 @@ const BODY_BEARING_METHODS = new Set(['POST', 'PUT', 'PATCH']);
  * every other field in the record agrees is a clean 200.
  *
  * So an omission is declared rather than left to inference, with the one line that fixes it. Present
- * only when a body-bearing call was returned AND none of them carried a body, so an app that already
- * captures bodies pays nothing and the field's PRESENCE is the warning.
+ * only when a body-bearing call was returned AND no body — request or response — was recorded
+ * anywhere in the result, so an app that already captures bodies pays nothing and the field's
+ * PRESENCE is the warning.
  */
 export function bodiesNotCaptured(calls) {
     const bodyBearing = calls.filter((c) => BODY_BEARING_METHODS.has((c.method ?? '').toUpperCase()));
     if (0 === bodyBearing.length)
         return {};
+    // A recorded response body anywhere in the result proves capture is ON. An absent request body
+    // then means this payload was not stringified (a multipart upload, a body the SDK skipped), not
+    // that recording is off — and firing the note would contradict the body sitting in the same
+    // result, exactly on the question the note exists to answer. (#394)
+    if (calls.some((c) => c.responseBody !== undefined))
+        return {};
     if (bodyBearing.some((c) => c.requestBody !== undefined))
         return {};
     return {

package/dist/honesty/unread-outcome.d.ts

@@ -1,2 +1,10 @@
 import { type ReticleEvent } from '@reticlehq/core';
+/**
+ * The writes whose outcome went unread, as "METHOD url".
+ *
+ * Named rather than counted, because a caveat an agent cannot locate is a caveat it learns to skip.
+ * The sentence used to say "a write returned 2xx with a response body that was never recorded" and
+ * name no write, which is unactionable on any page that makes more than one call.
+ */
+export declare function unreadWriteLabels(events: readonly ReticleEvent[]): string[];
 export declare function hasUnreadWriteOutcome(events: readonly ReticleEvent[]): boolean;

package/dist/honesty/unread-outcome.js

@@ -1,4 +1,5 @@
-import { EventType, MUTATING_METHODS, NetInitiator } from '@reticlehq/core';
+import { EventType, MUTATING_METHODS, NetInitiator, isDevToolingUrl, } from '@reticlehq/core';
+import { asString } from '../tools/tools-helpers.js';
 const IPC_METHOD = NetInitiator.IPC.toUpperCase();
 /**
  * A write whose outcome is sitting in a payload nobody read.
@@ -29,22 +30,48 @@ const IPC_METHOD = NetInitiator.IPC.toUpperCase();
  *    The residual gap is real and narrower: a handler that RESOLVES with a failure inside its payload
  *    is invisible without body capture. That case is `findBodyFailures`, which reads the payload and
  *    catches it precisely — with capture on, where it belongs.
+ *
+ *  - **the app's own traffic only.** The DEV TOOLCHAIN writes too: Next's overlay answers
+ *    `POST /__nextjs_original-stack-frames` with a JSON body the moment the app logs one React
+ *    warning, and nothing captures it. Judged as the app's write, that made every verdict in a Next
+ *    dev app `unknown` — decided by a channel the caller never asked about, on a request the app did
+ *    not make. `findContradictions` has split this traffic out for the same reason since the overlay
+ *    turned correct navigations red; this rule was reading the unsplit window.
  */
 const OK_MIN = 200;
 const OK_MAX = 300;
-export function hasUnreadWriteOutcome(events) {
-    return events.some((event) => {
+/**
+ * The writes whose outcome went unread, as "METHOD url".
+ *
+ * Named rather than counted, because a caveat an agent cannot locate is a caveat it learns to skip.
+ * The sentence used to say "a write returned 2xx with a response body that was never recorded" and
+ * name no write, which is unactionable on any page that makes more than one call.
+ */
+export function unreadWriteLabels(events) {
+    const labels = [];
+    for (const event of events) {
         if (event.type !== EventType.NET_REQUEST)
-            return false;
+            continue;
         const method = ('string' === typeof event.data['method'] ? event.data['method'] : '').toUpperCase();
         if (method === IPC_METHOD || !MUTATING_METHODS.includes(method))
-            return false;
+            continue;
+        const url = asString(event.data['url']);
+        if (isDevToolingUrl(url))
+            continue;
         const status = event.data['status'];
         if (typeof status !== 'number' || status < OK_MIN || status >= OK_MAX)
-            return false;
+            continue;
         if (event.data['responseBody'] !== undefined)
-            return false; // read — findBodyFailures judged it
+            continue; // read — findBodyFailures judged it
         const size = event.data['responseSize'];
-        return 'number' === typeof size && size > 0;
-    });
+        if ('number' !== typeof size || size <= 0)
+            continue;
+        const label = `${method} ${url ?? ''}`.trim();
+        if (!labels.includes(label))
+            labels.push(label);
+    }
+    return labels;
+}
+export function hasUnreadWriteOutcome(events) {
+    return unreadWriteLabels(events).length > 0;
 }

package/dist/honesty/unsettled.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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[];
+    /**
+     * Endpoints called more than once in this window, as "METHOD url ×N" — see `repeatedRequestLabels`.
+     *
+     * The case `stillInFlight` structurally cannot see: a retry loop against a dead backend completes
+     * every attempt, so nothing is ever outstanding, and the verdict fell through to a sentence that
+     * blamed unnamed churn on an app whose whole problem was one endpoint being hammered. Optional —
+     * a caller that does not supply it gets exactly the sentence that shipped before.
+     */
+    repeated?: 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,82 @@
+/**
+ * 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) {
+        const repeated = window.repeated ?? [];
+        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 ' +
+            (0 === repeated.length
+                ? '(a poll, a timer, an animation)'
+                : `(these fired repeatedly: ${repeated.join(', ')} — a poll or a retrying query)`) +
+            ', 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.
  *
@@ -41,16 +42,48 @@ interface VerifiedInputs {
     }[];
     /** Did a real frame flush before the wait gave up? */
     settled?: boolean;
+    /**
+     * The caller NAMED the expected consequence before acting — an `until`/`predicate` of its own,
+     * rather than the default "wait for the page to go idle".
+     *
+     * This is the epistemic core of the tool: a declaration made before the action cannot be
+     * rationalised after it. When such a declaration HOLDS, settlement is corroboration, not a veto —
+     * so the two clauses that answer "the app had not gone quiet" step aside for it. Measured in the
+     * field on three different apps: the expected text was on screen, the write returned 204, the
+     * nested verdict passed with evidence, and the verdict was `unknown` because the SPA polls, or
+     * because the tab was hidden and a hidden tab never fires the animation frame `settled` is read
+     * from. A hidden tab is the NORMAL state for agent-driven verification, so a signal that is always
+     * false there cannot be a precondition for a verdict.
+     *
+     * Narrow on purpose. It steps aside for settlement ONLY: an absence-derived finding about what the
+     * action DID — a duplicate write, a dead control, a route that rendered nothing, a response
+     * nothing consumed — still downgrades, and every positively OBSERVED contradiction still wins
+     * outright. Fixing a false negative must not open a path to a false positive.
+     */
+    declaredConsequence?: boolean;
     /**
      * A write in this window answered `202 Accepted` — the server took the request and has NOT
      * finished processing it.
      */
     outcomePending?: boolean;
     /**
-     * A write in this window returned 2xx with a payload that was never recorded, so its outcome was
-     * never read. See `hasUnreadWriteOutcome` — the status line describes the transport, not the result.
+     * Writes in this window that returned 2xx with a payload that was never recorded, as "METHOD url",
+     * so their outcome was never read. See `unreadWriteLabels` — the status line describes the
+     * transport, not the result.
+     *
+     * The LABELS rather than a flag: every other clause names the evidence that decided it, and this
+     * one named nothing, so an agent holding the caveat could not tell which call it was about.
+     * Empty means nothing went unread.
+     */
+    outcomeUnread?: readonly string[];
+    /**
+     * 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.
      */
-    outcomeUnread?: boolean;
+    unsettled?: UnsettledWindow;
+    /** A passing absence assertion targeted a region that the current capture could not observe. */
+    absenceBlindSpot?: string;
 }
 interface VerifiedVerdict {
     verified: Verified;

package/dist/honesty/verified.js

@@ -1,7 +1,10 @@
-import { Verified, VerifiedReason, isAbsenceDerived } from '@reticlehq/core';
+import { ContradictionKind, MUTATING_METHODS, 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;
+    /** The caller named a consequence before acting and it held — see `declaredConsequence`. */
+    const declaredHeld = true === inputs.declaredConsequence && true === pass;
     // Ahead of the failure clause, because a failure is only the most actionable fact when there WAS
     // one. An assertion nobody could evaluate is not a defect in the app, and calling it one was
     // putting the agent's own malformed calls into the bug count.
@@ -63,13 +66,40 @@ export function decideVerified(inputs) {
     // Absence-derived only: report it, do not assert failure. UNKNOWN is the honest answer — Reticle
     // drove the app and could not yet tell. The finding still rides out in `contradictions`, so an
     // agent that wants to wait and re-check has everything it needs.
-    if (contradictions.length > 0) {
+    //
+    // ...except when the only finding is that a READ had not come back AND the caller declared the
+    // consequence that did. `request-never-settled` is a statement about when we stopped looking; the
+    // declaration is a statement about what was supposed to happen, made before it could. On a page
+    // that polls, the first is permanently true and vetoed every verdict the second earned.
+    //
+    // An open WRITE is the exception to the exception, and it is where the false-green defence lives:
+    // "the toast said Saved while the POST was still open" is the archetype this product exists to
+    // catch, and its outcome genuinely does not exist yet. A poll or a prefetch left hanging says
+    // nothing about the action; an unfinished mutation says the answer is not in yet. Read off the
+    // labels the window already carries — and when there are no labels to read, nothing is softened.
+    const openWrite = (inputs.unsettled?.stillInFlight ?? []).some((label) => MUTATING_METHODS.includes((label.split(' ')[0] ?? '').toUpperCase()));
+    const settlementOnly = declaredHeld &&
+        inputs.unsettled !== undefined &&
+        !openWrite &&
+        contradictions.every((c) => c.kind === ContradictionKind.REQUEST_NEVER_SETTLED);
+    if (contradictions.length > 0 && !settlementOnly) {
         const kinds = contradictions.map((c) => c.kind).join(', ');
         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`,
+            // NOT `unsettled`: this clause fires whether or not the page went idle, and naming it after
+            // idle produced verdicts that read `unsettled` beside `settled: true`.
+            verifiedReason: VerifiedReason.EVIDENCE_INCOMPLETE,
+            because: unsettledBecause(`the assertion held, but this window closed before the app finished (${kinds})`, inputs.unsettled),
+        };
+    }
+    // An absence assertion over a region Reticle cannot observe is not disproved, but it is not proved
+    // either. This is narrower than general partial coverage: the target itself is scoped to the blind
+    // region, so the DOM result cannot answer the question the caller asked.
+    if (inputs.absenceBlindSpot !== undefined) {
+        return {
+            verified: Verified.UNKNOWN,
+            verifiedReason: VerifiedReason.ABSENCE_BLIND_SPOT,
+            because: inputs.absenceBlindSpot,
         };
     }
     // Below the contradiction clause, and for the same reason a contradiction outranks a dirty
@@ -132,19 +162,26 @@ export function decideVerified(inputs) {
     //
     // UNKNOWN, not NO: nothing is known to have failed. The remedy is in the sentence, because an
     // agent that cannot act on a caveat will learn to skip it.
-    if (true === outcomeUnread) {
+    if (outcomeUnread !== undefined && outcomeUnread.length > 0) {
         return {
             verified: Verified.UNKNOWN,
             verifiedReason: VerifiedReason.OUTCOME_UNREAD,
-            because: 'a write returned 2xx with a response body that was never recorded, so its outcome is unread — a 200 describes the transport, not the result (a batch reports per-item failures in the body, and every GraphQL error is a 200). Enable it where your app calls connect(): `reticle.connect({ captureNetworkBodies: true })`, then re-run',
+            because: `a write returned 2xx with a response body that was never recorded (${outcomeUnread.join('; ')}), so its outcome is unread` +
+                ' — a 200 describes the transport, not the result (a batch reports per-item failures in the body, and every GraphQL error is a 200). Enable it where your app calls connect(): `reticle.connect({ captureNetworkBodies: true })`, then re-run',
         };
     }
     // Never settled: the page may still be moving, so the observation window may have closed early.
-    if (false === settled) {
+    //
+    // Skipped when the caller DECLARED the consequence and it held. `settled` here is "a real
+    // animation frame fired within the budget", which a hidden or throttled tab never does — and a
+    // hidden tab is the ordinary case for agent-driven verification. It is corroboration; it is not
+    // the claim. It is still reported: `honesty.settled` carries the fact, and the sentence below says
+    // so in words.
+    if (false === settled && !declaredHeld) {
         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
@@ -155,11 +192,17 @@ export function decideVerified(inputs) {
     // partial` — the prose contradicting the evidence block next to it. Whichever a reader believes,
     // one of them lied, and the whole point of this layer is that the sentence can be trusted on its
     // own. Seen on a one-way IPC send: coverage said the outcome was unobservable, `because` said clean.
+    // A green that rests on the declaration rather than on idle says so. The page not going quiet is a
+    // real fact about the app — a poll, a timer, a throttled tab — and a caller who cares must be able
+    // to see it without re-deriving it, so it is stated here and carried in `honesty.settled`.
+    const notIdle = false === settled
+        ? ', though the page never went idle — this rests on the consequence you declared, not on the page going quiet'
+        : '';
     return {
         verified: Verified.YES,
         verifiedReason: VerifiedReason.PROVED,
         because: true === honesty.coverage?.partial
-            ? `assertion held at ${honesty.grade} grade with no channel disagreeing, but coverage was PARTIAL — see \`coverage\` for what went unobserved`
-            : `assertion held at ${honesty.grade} grade over a clean capture with no channel disagreeing`,
+            ? `assertion held at ${honesty.grade} grade with no channel disagreeing, but coverage was PARTIAL — see \`coverage\` for what went unobserved${notIdle}`
+            : `assertion held at ${honesty.grade} grade over a clean capture with no channel disagreeing${notIdle}`,
     };
 }