@reticlehq/server 3.5.0 → 3.7.0

package/dist/surface/tools/act/act-danger.js

@@ -1,4 +1,5 @@
-import { ActionType, DANGEROUS_ACTION_CONFIRM_ARG, NATIVE_INPUT_ARG, isDangerousActionText, } from '@reticlehq/core';
+import { ActionType, DANGEROUS_ACTION_CONFIRM_ARG, NATIVE_INPUT_ARG, isDangerousActionText, outwardActionOf, outwardRefusal, } from '@reticlehq/core';
+import { currentDrivenBy, harnessOutwardAllowed } from '../../../hooks/driven-by.js';
 import { asRecord, asString } from '@reticlehq/core';
 /**
  * Refuse to drive a money-moving or destructive control by accident.
@@ -29,9 +30,21 @@ function descriptorRole(value) {
 function isDestructiveDescriptor(value) {
     return isDangerousActionText(descriptorText(value), descriptorRole(value));
 }
+/** A Harness call presses an outward control only when its journey asked (`harnessOutwardAllowed`). */
+function assertOutwardAllowed(...descriptors) {
+    const allowed = harnessOutwardAllowed();
+    if (allowed === undefined)
+        return;
+    for (const descriptor of descriptors) {
+        const kind = outwardActionOf(descriptorText(descriptor), descriptorRole(descriptor));
+        if (kind !== undefined && !allowed.includes(kind))
+            throw new Error(outwardRefusal(kind));
+    }
+}
 export function assertNotDestructive(action, innerArgs, inspected) {
     if (action !== ActionType.CLICK && action !== ActionType.DBLCLICK)
         return;
+    assertOutwardAllowed(inspected);
     if (true === innerArgs[DANGEROUS_ACTION_CONFIRM_ARG])
         return;
     if (!isDestructiveDescriptor(inspected))
@@ -44,6 +57,7 @@ export function assertNotDestructive(action, innerArgs, inspected) {
  * option dragged onto Save is not a payment.
  */
 export function assertDragNotDestructive(innerArgs, from, to) {
+    assertOutwardAllowed(from, to);
     if (true === innerArgs[DANGEROUS_ACTION_CONFIRM_ARG])
         return;
     if (!isDestructiveDescriptor(from) && !isDestructiveDescriptor(to))
@@ -67,3 +81,26 @@ export function assertNativeInputSupported(innerArgs) {
     if (true === innerArgs[NATIVE_INPUT_ARG])
         throw new Error(NATIVE_INPUT_UNSUPPORTED);
 }
+/**
+ * The agent's own declaration counts as the confirmation, for that one control.
+ *
+ * `reticle_act_and_wait { target: { role: "button", name: "Place order" }, until }` names the
+ * control by the very words the guard flags AND names the consequence before acting: asking again
+ * for `confirmDangerous` cost a round trip per step on a shop's ordinary path and protected nothing.
+ * A `ref` or `testid` does not count — neither says what the control does, and a stale ref is
+ * exactly how the wrong button gets pressed. A Harness call never takes this path: its outward
+ * guard decides alone.
+ */
+export function confirmedByDeclaration(innerArgs, target, declared) {
+    if (!declared || true === innerArgs[DANGEROUS_ACTION_CONFIRM_ARG])
+        return innerArgs;
+    if (currentDrivenBy() !== undefined)
+        return innerArgs;
+    const named = asRecord(target);
+    // The words must themselves be the dangerous ones: naming "Continue" on a button whose form posts
+    // to /delete-account consents to nothing, and the guard still reads the whole control.
+    const words = ['name', 'text', 'label'].map((key) => asString(named[key]) ?? '').join(' ');
+    return isDangerousActionText(words, asString(named['role']))
+        ? { ...innerArgs, [DANGEROUS_ACTION_CONFIRM_ARG]: true }
+        : innerArgs;
+}

package/dist/surface/tools/act/act-observation.d.ts

@@ -10,6 +10,7 @@
  * used from the two points where observation can be lost: a write rejected at dispatch, and a wait
  * cut off mid-predicate.
  */
+import { type ReticleEvent } from '@reticlehq/core';
 import type { Session } from '../../../portal/session/session.js';
 import { type SuccessorRegistry } from '../../../portal/session/session-successor.js';
 import type { EvalResult } from '@reticlehq/engine/question/predicate/predicate-eval.js';
@@ -39,4 +40,36 @@ interface FollowedOutcome {
  * `awaitDocumentSuccessor` refuses to guess — a wrong follow drives somebody else's app.
  */
 export declare function followLostObservation(input: FollowSuccessor): Promise<FollowedOutcome>;
+/** Why a consequence that did not follow a click on a disabled control is not the app's failure. */
+export declare const DISABLED_TARGET_NOTE: string;
+/**
+ * The page reports `enabled: false` on an act whose target was disabled at dispatch. A missed
+ * consequence then says nothing about the app, so the verdict is undecided rather than "no".
+ */
+export declare function disabledTargetNote(pass: boolean, actResult: unknown): string | undefined;
+/**
+ * The requests of a failed check's window, as its record carries them: method, url, status and the
+ * start of the response body (redacted in the page before it was ever sent). Dev tooling is left out.
+ */
+/**
+ * The requests a check keeps: on a miss, the window's calls that explain it; on a held network check,
+ * the request that answered it, so a share page can name "a POST to /api/…", not "a request was seen".
+ */
+export declare function checkNet(verdict: {
+    pass: boolean;
+    evidence?: unknown;
+}, events: readonly ReticleEvent[]): {
+    net?: {
+        method: string;
+        url: string;
+        status?: number;
+        body?: string;
+    }[];
+};
+export declare function windowNet(events: readonly ReticleEvent[]): {
+    method: string;
+    url: string;
+    status?: number;
+    body?: string;
+}[];
 export {};

package/dist/surface/tools/act/act-observation.js

@@ -10,6 +10,7 @@
  * used from the two points where observation can be lost: a write rejected at dispatch, and a wait
  * cut off mid-predicate.
  */
+import { EventType, asRecord, asString, isDevToolingUrl } from '@reticlehq/core';
 import { awaitDocumentSuccessor, } from '../../../portal/session/session-successor.js';
 /**
  * Follow the unique same-origin successor and re-ask there, or leave the verdict untouched.
@@ -34,3 +35,59 @@ export async function followLostObservation(input) {
         return { session: next, verdict, followed: true };
     return { session: next, verdict: await reevaluate(next, leftover), followed: true };
 }
+/** Why a consequence that did not follow a click on a disabled control is not the app's failure. */
+export const DISABLED_TARGET_NOTE = 'the control was disabled when it was acted on, so nothing a user could do there would have ' +
+    'caused the declared consequence. Check why it was disabled (an empty required field, a save ' +
+    'that already happened) before calling this a defect.';
+/**
+ * The page reports `enabled: false` on an act whose target was disabled at dispatch. A missed
+ * consequence then says nothing about the app, so the verdict is undecided rather than "no".
+ */
+export function disabledTargetNote(pass, actResult) {
+    if (pass)
+        return undefined;
+    return false === asRecord(actResult)['enabled'] ? DISABLED_TARGET_NOTE : undefined;
+}
+/** Calls quoted on a failed check, and how much of each response body. */
+const MAX_NET_CALLS = 5;
+const MAX_BODY_CHARS = 300;
+/**
+ * The requests of a failed check's window, as its record carries them: method, url, status and the
+ * start of the response body (redacted in the page before it was ever sent). Dev tooling is left out.
+ */
+/**
+ * The requests a check keeps: on a miss, the window's calls that explain it; on a held network check,
+ * the request that answered it, so a share page can name "a POST to /api/…", not "a request was seen".
+ */
+export function checkNet(verdict, events) {
+    if (!verdict.pass)
+        return { net: windowNet(events) };
+    const seen = asRecord(verdict.evidence);
+    const method = asString(seen['method']);
+    const url = asString(seen['url']);
+    if (method === undefined || url === undefined)
+        return {};
+    const status = seen['status'];
+    return { net: [{ method, url, ...('number' === typeof status ? { status } : {}) }] };
+}
+export function windowNet(events) {
+    const out = [];
+    for (const event of events) {
+        if (EventType.NET_REQUEST !== event.type)
+            continue;
+        const url = asString(event.data['url']);
+        if (url === undefined || isDevToolingUrl(url))
+            continue;
+        const status = event.data['status'];
+        const body = asString(event.data['responseBody']);
+        out.push({
+            method: (asString(event.data['method']) ?? 'GET').toUpperCase(),
+            url,
+            ...('number' === typeof status ? { status } : {}),
+            ...(body === undefined ? {} : { body: body.slice(0, MAX_BODY_CHARS) }),
+        });
+        if (MAX_NET_CALLS <= out.length)
+            break;
+    }
+    return out;
+}

package/dist/surface/tools/act/act-preflight.js

@@ -11,7 +11,7 @@
  * outcome than "unknown".
  */
 import { PredicateSchema } from '@reticlehq/engine/question/predicate/predicate-schema.js';
-import { isGlobalPressCall } from '@reticlehq/core';
+import { SESSION_REF, isGlobalPressCall, unissuedRefRefusal } from '@reticlehq/core';
 import { SessionReplacedError } from '../../../portal/session/page-commands/pending-commands.js';
 import { assertNativeInputSupported } from './act-danger.js';
 import { unevaluablePredicateReason, vacuousPredicateReason, } from '@reticlehq/engine/question/predicate/predicate-precheck.js';
@@ -80,6 +80,19 @@ export function sequenceStepArgs(step) {
             flat[key] = value;
     }
     const nested = step['args'];
+    if ('string' === typeof nested) {
+        let parsed;
+        try {
+            parsed = JSON.parse(nested);
+        }
+        catch {
+            throw new Error(`step.args is a string that is not valid JSON — pass an object, not a string. Got: ${nested.slice(0, 120)}`);
+        }
+        if (null === parsed || 'object' !== typeof parsed || Array.isArray(parsed)) {
+            throw new Error(`step.args is a JSON string but not an object — pass an object, not ${null === parsed ? 'null' : typeof parsed}. Got: ${nested.slice(0, 120)}`);
+        }
+        return { ...flat, ...parsed };
+    }
     return { ...flat, ...(null !== nested && 'object' === typeof nested ? nested : {}) };
 }
 export function assertSequenceSteps(steps) {
@@ -113,8 +126,18 @@ export function assertSequenceSteps(steps) {
                 'Refused rather than dropped, because a step whose declaration was discarded reports ' +
                 'as a step that declared nothing. Nothing was acted on.');
         }
-        if ('string' === typeof step['ref'] && step['ref'].length > 0)
+        if ('string' === typeof step['args']) {
+            sequenceStepArgs(step);
+        }
+        if ('string' === typeof step['ref'] && step['ref'].length > 0) {
+            // The same shape check `resolveActTarget` makes, moved ahead of the first step: left there, a
+            // malformed ref in step three is only found after steps one and two have already acted.
+            if (!SESSION_REF.test(step['ref'])) {
+                throw new Error(`step ${String(i)}: ${unissuedRefRefusal(step['ref'])} ` +
+                    'Nothing was acted on — the whole sequence is refused so a bad step cannot leave the earlier ones half-applied.');
+            }
             return;
+        }
         if (step['target'] !== undefined)
             return;
         if (isGlobalPressCall(step))

package/dist/surface/tools/act/act-target.js

@@ -7,7 +7,7 @@
  * dispatch out of the file that opens the window would have weakened a real invariant to satisfy a
  * line count. This resolves a TARGET and dispatches only QUERY, so that guard is untouched.
  */
-import { ReticleCommand, isGlobalPressCall } from '@reticlehq/core';
+import { ReticleCommand, SESSION_REF, isGlobalPressCall, unissuedRefRefusal, } from '@reticlehq/core';
 import { normalizeQueryArgs } from '../read/query-shape.js';
 import { resolveTargetRef } from './resolve-target.js';
 import { asRecord, asString, asNumber } from '@reticlehq/core';
@@ -49,8 +49,13 @@ export async function resolveActTarget(session, args,
  */
 appearanceMs) {
     const ref = asString(args['ref']);
-    if (ref !== undefined && ref.length > 0)
+    if (ref !== undefined && ref.length > 0) {
+        // Refused here, at the boundary, and never re-read as a `target`: guessing what an arbitrary
+        // string meant is the silent re-resolution the stale-ref refusal exists to prevent.
+        if (!SESSION_REF.test(ref))
+            return { kind: 'error', message: unissuedRefRefusal(ref) };
         return { kind: 'ref', ref };
+    }
     const target = args['target'];
     if (target === undefined) {
         if (isGlobalPressCall(args))
@@ -94,7 +99,7 @@ appearanceMs) {
         // One match, or an ambiguity: both are answered by the existing resolver, which already ranks
         // candidates inside its refusal so the next turn needs no snapshot.
         if ('wait' !== decision.do)
-            return resolveTargetRef(found);
+            return resolveTargetRef(found, asRecord(out.result)['hint']);
         await new Promise((resolve) => setTimeout(resolve, decision.waitMs));
     }
 }

package/dist/surface/tools/act/navigation/navigate-arrival.d.ts

@@ -59,6 +59,14 @@ export interface ArrivalScope {
      * "the app redirected the newly arrived document somewhere else."
      */
     navigatedFrom: string;
+    /**
+     * The DOCUMENT the session was on when the navigation was dispatched.
+     *
+     * A navigation to the page already shown replaces the document without changing the URL, so the
+     * old document is still the connected one until the replacement reports (#1320). Only a different
+     * document identity proves the replacement; `undefined` on both sides proves nothing and waits.
+     */
+    navigatedFromDocumentId?: string;
     /** Sessions already on the target before dispatch cannot prove this navigation arrived. */
     priorIds: ReadonlySet<string>;
 }

package/dist/surface/tools/act/navigation/navigate-arrival.js

@@ -42,6 +42,21 @@ function samePage(a, b) {
         return false;
     }
 }
+/**
+ * Same origin and path, different fragment: the browser changes the URL WITHOUT replacing the
+ * document. There is no replacement to wait for on this path, so it must not be treated as a
+ * same-page navigation (#1320).
+ */
+function sameDocumentFragmentChange(a, b) {
+    if (!samePage(a, b))
+        return false;
+    try {
+        return new URL(a).hash !== new URL(b).hash;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * The navigation target as an absolute URL, resolved against the tab being navigated — the same
  * resolution the browser applies. An agent passes a path (`/orders?id=4`) as often as a full URL,
@@ -70,13 +85,39 @@ export function idsAtTarget(sessions, target) {
     }
     return ids;
 }
+/**
+ * Whether `current` is a different document from the one the navigation was dispatched on.
+ *
+ * A new Session object under the same id is not enough: the SDK also reopens its socket in place,
+ * and that replaces the Session while the page stays exactly where it was. What a real unload
+ * changes is the document id — the one sampled before dispatch (`navigatedFromDocumentId`) against
+ * the one the live session is reporting (`currentDocumentId`). Either side not having reported one
+ * yet is "cannot tell", which is never reported as a new document.
+ */
+function documentUnloaded(scope, current) {
+    const before = scope.navigatedFromDocumentId;
+    const after = current.currentDocumentId;
+    return before !== undefined && after !== undefined && before !== after;
+}
 function findArrival(sessions, target, scope, currentSession) {
     let arrived = null;
-    for (const s of sessions.all()) {
+    // One snapshot for the whole look, so "is the driven session still connected?" and "has a
+    // replacement reported?" are answered from the same moment.
+    const snapshot = sessions.all();
+    const drivenPresent = snapshot.some((s) => s.id === currentSession.id);
+    // Navigating to the page already shown replaces its document without moving the URL, so the
+    // OLD document is still the connected one at the first looks; its presence there is not
+    // arrival until the replacement reports a different document identity (#1320). A fragment-only
+    // change keeps the document, so it is an arrival as soon as the URL matches.
+    const replacesDocument = samePage(scope.navigatedFrom, target) &&
+        !sameDocumentFragmentChange(scope.navigatedFrom, target);
+    for (const s of snapshot) {
         // The currently tracked document gets priority because it is the strongest
         // evidence of where this navigation went.
         if (s.id === currentSession.id) {
             if (samePage(s.url, target)) {
+                if (replacesDocument && s.currentDocumentId === scope.navigatedFromDocumentId)
+                    continue;
                 return { sessionId: s.id };
             }
             // Intermediate routes are not necessarily redirects. Keep polling so
@@ -87,6 +128,12 @@ function findArrival(sessions, target, scope, currentSession) {
         // navigation arrived.
         if (scope.priorIds.has(s.id))
             continue;
+        // While the replaced document is still connected, a DIFFERENT session at the target is an
+        // unrelated arrival (a second tab, a neighbour app): the replacement this navigation waits
+        // for has not reported yet, and letting the newcomer stand in would confirm too early and
+        // name the wrong session (#1320).
+        if (replacesDocument && drivenPresent)
+            continue;
         if (samePage(s.url, target)) {
             if (null === arrived)
                 arrived = { sessionId: s.id };
@@ -122,7 +169,11 @@ export async function awaitArrival(sessions, target, scope, timeoutMs = ARRIVAL_
     // landed when the target was never observed.
     const current = sessions.get(scope.navigatedSession.id);
     if (current !== undefined) {
-        if (!samePage(current.url, scope.navigatedFrom) && !samePage(current.url, target)) {
+        // Sitting on `navigatedFrom` means two different things: a tab that has not moved, or a page
+        // that unloaded and came back here (an auth guard bouncing `/checkout` to `/login` while the
+        // tab started on `/login`). Only a document that is provably new tells them apart.
+        if (!samePage(current.url, target) &&
+            (!samePage(current.url, scope.navigatedFrom) || documentUnloaded(scope, current))) {
             return {
                 sessionId: current.id,
                 landedOn: current.url,
@@ -131,6 +182,9 @@ export async function awaitArrival(sessions, target, scope, timeoutMs = ARRIVAL_
         return null;
     }
     const successor = await awaitDocumentSuccessor(sessions, scope.navigatedSession, 0, clock);
+    // A successor under another id is only "unique at the origin", which a tab opened by someone else
+    // after the driven one went away satisfies equally. On the starting page that guess cannot be told
+    // from a redirect, so it is not reported as one.
     if (successor !== null &&
         !samePage(successor.url, target) &&
         !samePage(successor.url, scope.navigatedFrom)) {

package/dist/surface/tools/act/resolve-target.d.ts

@@ -29,4 +29,4 @@ export type TargetResolution = {
  * When several remain, they are ranked (in-viewport, then role) inside the refusal only — so the
  * agent can pass the top ref on the next turn without a snapshot. Ranking is never acted on here.
  */
-export declare function resolveTargetRef(candidates: readonly unknown[]): TargetResolution;
+export declare function resolveTargetRef(candidates: readonly unknown[], hint?: unknown): TargetResolution;

package/dist/surface/tools/act/resolve-target.js

@@ -61,6 +61,21 @@ function formatCandidate(c, anyInViewport) {
     const head = name.length > 0 ? `${ref} (${role} "${name}"` : `${ref} (${role}`;
     return `${head}; ${where})`;
 }
+/**
+ * The names that role really has, when an exact role + name query just missed (the browser's
+ * `nameNearMiss` hint). Names are matched exactly, so one that carries a changing part — "billing
+ * Last run 1 minute ago" — is unreachable by name; `testid` or a `text` match is the durable way.
+ */
+function nearNamesClause(hint) {
+    const near = asRecord(hint)['nameNearMiss'];
+    const names = Array.isArray(near) ? near.filter((n) => 'string' === typeof n) : [];
+    if (0 === names.length) {
+        return 'widen the query, or take a reticle_snapshot to see what is actually on the page.';
+    }
+    return (`names are matched exactly, and that role is called ${names.map((n) => `"${n}"`).join(', ')}. ` +
+        'Use that name, or — when the name carries a part that changes, like a time — target it by ' +
+        '`testid` or by `text` (a contained match).');
+}
 /**
  * Turn a target QUERY into the single ref an action can be performed on.
  *
@@ -81,15 +96,15 @@ function formatCandidate(c, anyInViewport) {
  * When several remain, they are ranked (in-viewport, then role) inside the refusal only — so the
  * agent can pass the top ref on the next turn without a snapshot. Ranking is never acted on here.
  */
-export function resolveTargetRef(candidates) {
+export function resolveTargetRef(candidates, hint) {
     const all = candidates.map((c) => asRecord(c));
     const visible = all.filter((c) => c.visible !== false);
     const usable = visible.length > 0 ? visible : all;
     if (0 === usable.length) {
         return {
             kind: 'error',
-            message: 'target matched no element. Nothing was acted on and no verdict is possible — widen the ' +
-                'query, or take a reticle_snapshot to see what is actually on the page.',
+            message: 'target matched no element. Nothing was acted on and no verdict is possible — ' +
+                nearNamesClause(hint),
         };
     }
     if (usable.length > 1) {

package/dist/surface/tools/act/screen-request.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The opt-in screen/request check, wired: after an act_and_wait, compare what the window's write
+ * requests carried with the values the page's form controls show (engine: screen-request.ts).
+ *
+ * OPT-IN (`RETICLE_SCREEN_REQUEST_CHECK=1`) and ADVISORY. It ships behind the flag until its
+ * false-alarm rate is measured at zero on the e2e battery, the benchmark and the persona fixtures;
+ * until then it must cost nothing for anyone who did not ask. It runs AFTER the verdict is decided
+ * and is appended to `contradictions` as an advisory kind, so it can never move a verdict.
+ */
+import { type Contradiction, type ReticleEvent } from '@reticlehq/core';
+import type { Session } from '../../../portal/session/session.js';
+export declare const SCREEN_REQUEST_CHECK_ENV = "RETICLE_SCREEN_REQUEST_CHECK";
+export interface SentBody {
+    method: string;
+    url: string;
+    /** The request body as sent (JSON text). */
+    body: string;
+}
+export interface ShownControl {
+    /** `name` or `id` attribute — the only link from a control to a field. */
+    field: string;
+    /** The control's current value (a select's selected option value, an input's text). */
+    value: string;
+    /** What the user sees, when it differs from the value (a select's option label). */
+    label?: string | undefined;
+    ref?: string | undefined;
+}
+export declare function screenRequestMismatches(sent: readonly SentBody[], controls: readonly ShownControl[]): Contradiction[];
+/** Advisory findings for this window, or none when the check is off or nothing was written. */
+export declare function screenRequestFindings(session: Session, windowEvents: readonly ReticleEvent[]): Promise<Contradiction[]>;
+/** The `contradictions` field: the verdict's own, then any advisory ones; omitted when both are empty. */
+export declare function withAdvisories(decided: readonly Contradiction[], advisory: readonly Contradiction[]): {
+    contradictions?: Contradiction[];
+};

package/dist/surface/tools/act/screen-request.js

@@ -0,0 +1,113 @@
+/**
+ * The opt-in screen/request check, wired: after an act_and_wait, compare what the window's write
+ * requests carried with the values the page's form controls show (engine: screen-request.ts).
+ *
+ * OPT-IN (`RETICLE_SCREEN_REQUEST_CHECK=1`) and ADVISORY. It ships behind the flag until its
+ * false-alarm rate is measured at zero on the e2e battery, the benchmark and the persona fixtures;
+ * until then it must cost nothing for anyone who did not ask. It runs AFTER the verdict is decided
+ * and is appended to `contradictions` as an advisory kind, so it can never move a verdict.
+ */
+import { ContradictionKind, EventType, REDACTED_VALUE, ReticleCommand, } from '@reticlehq/core';
+export const SCREEN_REQUEST_CHECK_ENV = 'RETICLE_SCREEN_REQUEST_CHECK';
+const READ_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+/** The form controls whose value a request can carry. */
+const CONTROL_ROLES = ['combobox', 'listbox', 'textbox', 'spinbutton'];
+function primitiveFields(body) {
+    const out = new Map();
+    try {
+        const parsed = JSON.parse(body);
+        if ('object' !== typeof parsed || null === parsed || Array.isArray(parsed))
+            return out;
+        for (const [key, value] of Object.entries(parsed)) {
+            if ('string' === typeof value || 'number' === typeof value || 'boolean' === typeof value) {
+                out.set(key.toLowerCase(), String(value));
+            }
+        }
+    }
+    catch {
+        // Not JSON: nothing comparable, so nothing reported.
+    }
+    return out;
+}
+function pathOf(url) {
+    try {
+        return new URL(url, 'http://local.invalid').pathname;
+    }
+    catch {
+        return url;
+    }
+}
+export function screenRequestMismatches(sent, controls) {
+    const out = [];
+    for (const request of sent) {
+        const fields = primitiveFields(request.body);
+        if (0 === fields.size)
+            continue;
+        for (const control of controls) {
+            const key = control.field.toLowerCase();
+            const carried = fields.get(key);
+            if (carried === undefined || carried === control.value)
+                continue;
+            const shown = control.label !== undefined && control.label !== control.value
+                ? `"${control.label}" (value "${control.value}")`
+                : `"${control.value}"`;
+            out.push({
+                kind: ContradictionKind.SCREEN_REQUEST_MISMATCH,
+                claim: `the screen's "${control.field}" control shows ${shown}`,
+                counter: `${request.method.toUpperCase()} ${pathOf(request.url)} sent ${control.field}=${JSON.stringify(carried)}`,
+                detail: `${control.ref === undefined ? '' : `${control.ref} `}${control.field}: shown ${shown}, sent ${JSON.stringify(carried)}`,
+            });
+        }
+    }
+    return out;
+}
+function sentBodies(events) {
+    return events.flatMap((event) => {
+        if (EventType.NET_REQUEST !== event.type)
+            return [];
+        const raw = event.data['method'];
+        const method = ('string' === typeof raw ? raw : 'GET').toUpperCase();
+        const body = event.data['requestBody'];
+        const url = event.data['url'];
+        if (READ_METHODS.has(method) || 'string' !== typeof body || 'string' !== typeof url)
+            return [];
+        return [{ method, url, body }];
+    });
+}
+async function shownControls(session) {
+    const out = [];
+    for (const role of CONTROL_ROLES) {
+        const res = await session.command(ReticleCommand.MATCH, {
+            query: { role, attrs: ['name', 'id'] },
+        });
+        if (!res.ok)
+            continue;
+        for (const el of res.result?.elements ?? []) {
+            const field = el.attrs?.['name'] ?? el.attrs?.['id'];
+            // No value read, or a redacted one: nothing to compare, so nothing is guessed.
+            if (field === undefined || el.value === undefined || REDACTED_VALUE === el.value)
+                continue;
+            out.push({ field, value: el.value, ref: el.ref });
+        }
+    }
+    return out;
+}
+/** Advisory findings for this window, or none when the check is off or nothing was written. */
+export async function screenRequestFindings(session, windowEvents) {
+    if ('1' !== process.env[SCREEN_REQUEST_CHECK_ENV])
+        return [];
+    const sent = sentBodies(windowEvents);
+    if (0 === sent.length)
+        return [];
+    try {
+        return screenRequestMismatches(sent, await shownControls(session));
+    }
+    catch {
+        return [];
+    }
+}
+/** The `contradictions` field: the verdict's own, then any advisory ones; omitted when both are empty. */
+export function withAdvisories(decided, advisory) {
+    const all = [...decided, ...advisory];
+    return 0 === all.length ? {} : { contradictions: all };
+}

package/dist/surface/tools/act/sequence-grade.d.ts

@@ -40,6 +40,12 @@ export interface StepExpectation {
      * filter act_and_wait applies. A held step with one is a UI that advanced over a failed write.
      */
     contradicted?: readonly string[];
+    /**
+     * Why this step could not be judged at all: its target was missing (nothing was acted on), the
+     * page left the app and the observation went with it, or the predicate could not be read. Such a
+     * step is undecided, never a miss — `unknown`, as act_and_wait says.
+     */
+    undecided?: string;
 }
 export interface SequenceGrade {
     verified: Verified;
@@ -80,5 +86,7 @@ export declare function gradeSequence(steps: readonly StepExpectation[], plan?:
  * two-of-twelve plan as a regression flow is a reasonable thing to do and a bad thing to do without
  * knowing it.
  */
+/** The stopped recording a proved journey is held under, so the `keep` offer can be taken. */
+export declare const JOURNEY_RECORDING = "last-journey";
 export declare function offerToKeep(grade: SequenceGrade): string | undefined;
 export {};

package/dist/surface/tools/act/sequence-grade.js

@@ -29,7 +29,7 @@ export function gradeSequence(steps, plan = { planned: steps.length, dispatched:
     const declared = declaring.length;
     // `held: false` on an undeclared step means it could not be performed at all — the journey broke
     // there whether or not anything was declared about it.
-    const missed = steps.find((step) => (step.declared ? true !== step.held : false === step.held));
+    const missed = steps.find((step) => step.undecided === undefined && (step.declared ? true !== step.held : false === step.held));
     // A miss decides the grade before coverage does. How much of the plan declared nothing is
     // context on a red, never a softening of it.
     if (missed !== undefined) {
@@ -52,6 +52,15 @@ export function gradeSequence(steps, plan = { planned: steps.length, dispatched:
             because: `step ${String(contradictedAt + 1)}: channels disagree about this action (${kinds}) even though it went on`,
         };
     }
+    // Nothing failed that was seen: a step nobody could judge leaves the plan undecided, saying why.
+    const unjudged = steps.find((step) => step.undecided !== undefined);
+    if (unjudged !== undefined)
+        return {
+            verified: Verified.UNKNOWN,
+            declared,
+            total,
+            because: `a step could not be judged — ${unjudged.undecided ?? ''}`,
+        };
     /*
      * `unknown` rather than `no-fault`, and the distinction is load-bearing.
      *
@@ -125,11 +134,13 @@ export function gradeSequence(steps, plan = { planned: steps.length, dispatched:
  * two-of-twelve plan as a regression flow is a reasonable thing to do and a bad thing to do without
  * knowing it.
  */
+/** The stopped recording a proved journey is held under, so the `keep` offer can be taken. */
+export const JOURNEY_RECORDING = 'last-journey';
 export function offerToKeep(grade) {
     if (grade.verified !== Verified.YES || 0 === grade.declared)
         return undefined;
     return (`this plan proved something (${String(grade.declared)} of ${String(grade.total)} steps declared a ` +
         'consequence and every one held) — keep it as a regression flow with ' +
-        'reticle_flow_save { saveAs: "<name>" }, and the steps that declared nothing will replay ' +
+        `reticle_flow_save { flowName: "${JOURNEY_RECORDING}", saveAs: "<name>" }, and the steps that declared nothing will replay ` +
         'without proving anything, exactly as they did here');
 }