@reticlehq/server 3.8.2 → 3.10.0

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

@@ -10,8 +10,15 @@
  * 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 { DriftReason, EventType, NetInitiator, asRecord, asString, isDevToolingUrl, } from '@reticlehq/core';
+import { sdkBehindNote } from '../../../portal/session/session-info.js';
 import { awaitDocumentSuccessor, } from '../../../portal/session/session-successor.js';
+/** How long an act whose page navigated away waits for the lease's successor to connect. */
+export const NAVIGATION_FOLLOW_GRACE_MS = 8_000;
+const REAL_CLOCK = {
+    now: () => Date.now(),
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+};
 /**
  * Follow the unique same-origin successor and re-ask there, or leave the verdict untouched.
  *
@@ -22,18 +29,65 @@ import { awaitDocumentSuccessor, } from '../../../portal/session/session-success
  */
 export async function followLostObservation(input) {
     const { sessions, session, verdict, timeout, predicateStarted, reevaluate } = input;
-    if (true !== verdict.observationLost || 0 >= timeout)
+    const clock = input.clock ?? REAL_CLOCK;
+    const spent = session.elapsed() - predicateStarted;
+    const remaining = timeout - spent;
+    // Phase 1 — the wait was CUT OFF mid-predicate. The page re-announces on the new document;
+    // re-ask there with whatever budget is left.
+    if (true === verdict.observationLost && remaining > 0) {
+        const next = await awaitDocumentSuccessor(sessions, session, remaining);
+        if (null !== next) {
+            // Computed on the DEPARTED session, before the caller points at the successor: the new
+            // session's elapsed() starts at 0 and would silently refund the whole budget the caller had
+            // already spent.
+            const leftover = timeout - (session.elapsed() - predicateStarted);
+            if (leftover <= 0)
+                return { session: next, verdict, followed: true };
+            return { session: next, verdict: await reevaluate(next, leftover), followed: true };
+        }
+    }
+    // Phase 2 — gated on NAVIGATION EVIDENCE ALREADY IN THE WINDOW (#2009): a FAILURE graded while
+    // the action's own full-page navigation was still in flight reads "still on /login" for a
+    // sign-in that worked. The departure observer records the leaving as a NET_PENDING at dispatch
+    // time — while the old document's socket is still alive to deliver it — so the evidence is
+    // already in the buffer when the verdict is graded. Its presence unlocks the successor wait
+    // (bounded by the grace); its absence means the failure is about a document that never moved,
+    // and it stands UNCHANGED and AT ONCE — no wait, and the grace is never spent on it.
+    const grace = input.failedFollowGraceMs;
+    const registryCapable = 'function' === typeof sessions.get && 'function' === typeof sessions.all;
+    if (true === verdict.observationLost ||
+        true === verdict.pass ||
+        grace === undefined ||
+        input.since === undefined ||
+        !registryCapable) {
         return { session, verdict, followed: false };
-    const remaining = timeout - (session.elapsed() - predicateStarted);
-    const next = remaining > 0 ? await awaitDocumentSuccessor(sessions, session, remaining) : null;
-    if (null === next)
+    }
+    const departurePending = session
+        .eventsSince(input.since)
+        .some((e) => e.type === EventType.NET_PENDING && e.data['initiator'] === NetInitiator.NAVIGATION);
+    if (!departurePending) {
         return { session, verdict, followed: false };
-    // Computed on the DEPARTED session, before the caller points at the successor: the new session's
-    // elapsed() starts at 0 and would silently refund the whole budget the caller had already spent.
-    const leftover = timeout - (session.elapsed() - predicateStarted);
-    if (leftover <= 0)
-        return { session: next, verdict, followed: true };
-    return { session: next, verdict: await reevaluate(next, leftover), followed: true };
+    }
+    const next = await awaitDocumentSuccessor(sessions, session, grace, clock);
+    if (null !== next) {
+        return {
+            session: next,
+            verdict: await reevaluate(next, grace),
+            followed: true,
+            budgetExtendedMs: grace,
+        };
+    }
+    return {
+        session,
+        followed: false,
+        verdict: {
+            ...verdict,
+            observationLost: true,
+            failureReason: `the act's page left its document and no successor session connected within ` +
+                `${String(grace)} ms. If this action navigated, the outcome after the navigation was ` +
+                'never observed — re-run reticle_session { action: "list" } and re-drive on the live session.',
+        },
+    };
 }
 /** 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 ' +
@@ -52,7 +106,9 @@ export function disabledTargetNote(pass, actResult) {
 const UNREACHABLE = {
     covered: (by) => `a person could not have clicked the target: it is covered by ${by}. Dismiss or move what ` +
         'covers it, then act again',
-    NO_SIZE: 'a person could not have clicked the target: it has no size (0×0). Give it a size, or act on ' +
+    HIDDEN: 'a person could not have clicked the target: it is not visible (for example, it is inside a ' +
+        'closed <details> or has visibility: hidden). Show it the way a person would, then act again',
+    NO_SIZE: 'a person could not have clicked the target: it has no size (zero width or zero height). Give it a size, or act on ' +
         'the control a person actually clicks',
     OFF_VIEWPORT: 'a person could not have clicked the target: it is outside the viewport even after scrolling ' +
         'it into view. Bring it on screen, then act again',
@@ -68,6 +124,11 @@ const UNREACHABLE = {
 export function unreachableTargetNote(actResult) {
     const effect = asRecord(asRecord(actResult)['effect']);
     if (true === effect['occluded']) {
+        // A hidden target keeps its box, so the hit test finds whatever is under it. That element
+        // covers nothing: the target is not shown.
+        if (false === effect['visible']) {
+            return UNREACHABLE.HIDDEN;
+        }
         const by = asString(effect['occluderName']) ?? asString(effect['occludedBy']);
         return UNREACHABLE.covered(by ?? 'another element');
     }
@@ -77,10 +138,55 @@ export function unreachableTargetNote(actResult) {
         return UNREACHABLE.OFF_VIEWPORT;
     return undefined;
 }
+/**
+ * The drift for the first sub-step of an `ACT_SEQUENCE` result whose target no person could have
+ * clicked, or undefined. The page reports one effect for each sub-step it ran, in order. Synthetic
+ * dispatch reaches an unreachable target all the same, so a sequence is read sub-step by sub-step, as
+ * a single act is. `labelOf` names the sub-step, by its index in this result.
+ */
+export function unreachableSubStepDrift(sequenceResult, labelOf) {
+    const effects = asRecord(sequenceResult)['effects'];
+    const list = Array.isArray(effects) ? effects : [];
+    for (let at = 0; at < list.length; at += 1) {
+        const reason = unreachableTargetNote({ effect: list[at] });
+        if (reason !== undefined) {
+            return {
+                reasonKind: DriftReason.TARGET_UNREACHABLE,
+                reason,
+                anchor: labelOf(at),
+                nearest: null,
+            };
+        }
+    }
+    return undefined;
+}
 /** Why the acted target leaves the verdict undecided: no person could reach it, or it was disabled. */
 export function actTargetNote(pass, actResult) {
     return unreachableTargetNote(actResult) ?? disabledTargetNote(pass, actResult);
 }
+// Unanchored: the engine prefixes the reason with "the page did not answer:".
+const COMMAND_TIMEOUT = /command '[^']*' timed out after (\d+)ms/;
+/**
+ * The cause and the one fix for a read that came back `unknown`, in place of a bare fact (#1990).
+ * A page whose SDK is behind this daemon may not serve `match` at all, so the fix is the same
+ * SDK-behind sentence the listing shows. On a current page the read ran out of the assertion's own
+ * budget, and the fix is more of it. Any reason that is not a command timeout is returned as it came.
+ */
+export function diagnoseTimeout(reason, session) {
+    const granted = reason === undefined ? undefined : COMMAND_TIMEOUT.exec(reason)?.[1];
+    if (reason === undefined || granted === undefined) {
+        return reason;
+    }
+    const behind = sdkBehindNote(session);
+    if (behind !== undefined) {
+        return `${reason} ${behind}`;
+    }
+    return (`${reason} This read was bounded by what the assertion's budget had left ` +
+        `(${granted}ms): the budget ran out while the page was still working. ` +
+        'Give the assertion more time with `timeout_ms`.');
+}
+/** Why an act's verdict is `unknown`: a read that timed out, else an unreachable or disabled target. */
+export const actInconclusive = (verdict, actResult, session) => diagnoseTimeout(verdict.inconclusive, session) ?? actTargetNote(verdict.pass, actResult);
 /** Calls quoted on a failed check, and how much of each response body. */
 const MAX_NET_CALLS = 5;
 const MAX_BODY_CHARS = 300;

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

@@ -11,6 +11,7 @@
  * outcome than "unknown".
  */
 import { PredicateSchema } from '@reticlehq/engine/question/predicate/predicate-schema.js';
+import { parsePredicate } from '@reticlehq/engine/question/predicate/predicate-parse.js';
 import { SESSION_REF, isGlobalPressCall, unissuedRefRefusal } from '@reticlehq/core';
 import { isDocumentGoneError } from '../../../portal/session/facts/session-replaced.js';
 import { SessionReplacedError } from '../../../portal/session/page-commands/pending-commands.js';
@@ -77,8 +78,9 @@ const STEP_STRUCTURE_KEYS = new Set([
 export function sequenceStepArgs(step) {
     const flat = {};
     for (const [key, value] of Object.entries(step)) {
-        if (!STEP_STRUCTURE_KEYS.has(key))
+        if (!STEP_STRUCTURE_KEYS.has(key)) {
             flat[key] = value;
+        }
     }
     const nested = step['args'];
     if ('string' === typeof nested) {
@@ -96,6 +98,22 @@ export function sequenceStepArgs(step) {
     }
     return { ...flat, ...(null !== nested && 'object' === typeof nested ? nested : {}) };
 }
+/**
+ * Why `parsePredicate` refuses this `expect`, as the sentence `reticle_assert` gives.
+ *
+ * Called only after `PredicateSchema` has refused the value, so the parse throws. The schema stays
+ * the test for refusal: `parsePredicate` also refuses a value that the schema accepts, and this
+ * check must not refuse more than it did before.
+ */
+function expectParseIssue(value) {
+    try {
+        parsePredicate(value);
+        return '';
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+}
 export function assertSequenceSteps(steps) {
     if (0 === steps.length) {
         throw new Error('reticle_act_sequence was given no steps. Pass steps: [{ ref, action, args? }] or [{ target, action, args? }] — nothing was acted on.');
@@ -118,18 +136,15 @@ export function assertSequenceSteps(steps) {
          * declared; nothing told it the declaration was discarded, and that sentence invites it to add
          * the very thing it just wrote. Same false green as an unreadable key, through a key this tool
          * does read.
+         *
+         * The reason is the sentence `reticle_assert` gives for the same predicate: the field that failed
+         * and the fields that work. A fixed sentence with generic examples did not say that `css` is not a
+         * `query` field, so the caller had to guess again. That sentence also carries the schema's own
+         * words, such as the keys it saw when it could not tell the kind.
          */
-        const parsed = step['expect'] === undefined ? undefined : PredicateSchema.safeParse(step['expect']);
-        if (parsed !== undefined && !parsed.success) {
-            // The schema's own words, such as the keys it saw when it could not tell the kind.
-            const said = parsed.error.issues
-                .filter((issue) => 'custom' === issue.code)
-                .map((issue) => ` ${issue.message}.`)
-                .join('');
-            throw new Error(`step ${String(i)} carries an \`expect\` this tool cannot parse.${said} ` +
-                'A consequence is a predicate object with a `kind` — e.g. { kind: "signal", name: ' +
-                '"order:placed" }, { kind: "element", by: "testid", value: "receipt" }, or ' +
-                '{ kind: "settled" } — the same shape reticle_act_and_wait takes as `until`. ' +
+        if (step['expect'] !== undefined && !PredicateSchema.safeParse(step['expect']).success) {
+            throw new Error(`step ${String(i)} carries an \`expect\` this tool cannot parse: ` +
+                `${expectParseIssue(step['expect'])} ` +
                 'Refused rather than dropped, because a step whose declaration was discarded reports ' +
                 'as a step that declared nothing. Nothing was acted on.');
         }
@@ -145,14 +160,16 @@ export function assertSequenceSteps(steps) {
             }
             return;
         }
-        if (step['target'] !== undefined)
+        if (step['target'] !== undefined) {
             return;
-        if (isGlobalPressCall(step))
+        }
+        if (isGlobalPressCall(step)) {
             return;
+        }
         throw new Error(`step ${String(i)} has no \`ref\` or \`target\`. ` +
             'Sequence steps take `ref` (from reticle_query/reticle_snapshot) or `target` ' +
             '(e.g. { testid } or { label }), the same locator reticle_act accepts. ' +
-            'A press of Escape, Tab, or a modifier shortcut is a document key and needs neither. ' +
+            'A press of Escape, Tab, an arrow key or a modifier shortcut, or any press with `document: true`, is a document key and needs neither. ' +
             'Nothing was acted on — the whole sequence is refused so a bad step cannot leave the earlier ones half-applied.');
     });
 }
@@ -165,13 +182,15 @@ export function preflightAct(actArgs, until) {
     // the agent its trusted click had happened. See act-danger.
     assertNativeInputSupported(actArgs);
     const unevaluable = unevaluablePredicateReason(until);
-    if (unevaluable !== undefined)
+    if (unevaluable !== undefined) {
         throw new Error(unevaluable);
+    }
     // A predicate that was already true when it was written answered `no-fault` / `already_true` —
     // verdict-shaped, and carrying no proof of anything the action did. See vacuousPredicateReason.
     const vacuous = vacuousPredicateReason(until);
-    if (vacuous !== undefined)
+    if (vacuous !== undefined) {
         throw new Error(vacuous);
+    }
 }
 /**
  * Dispatch a write, or report that its outcome went unobserved.
@@ -191,8 +210,9 @@ export async function dispatchAct(send) {
         return await send();
     }
     catch (error) {
-        if (error instanceof SessionReplacedError || isDocumentGoneError(error))
+        if (error instanceof SessionReplacedError || isDocumentGoneError(error)) {
             return null;
+        }
         throw error;
     }
 }

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

@@ -1,6 +1,6 @@
 /**
- * The two things a sequence step needs beyond a plain act: a retry when the ref goes stale under a
- * re-render, and a result shaped for the per-step report.
+ * The things a sequence step needs beyond a plain act: a retry when the ref goes stale under a
+ * re-render, a result shaped for the per-step report, and the `burst` pace (at the end).
  *
  * ── THE RETRY ─────────────────────────────────────────────────────────────────────────────────
  *
@@ -42,4 +42,25 @@ export declare function runStepWithStaleRetry(attempt: () => Promise<StepOutcome
  * nothing to look for".
  */
 export declare function describeStepResult(step: Record<string, unknown>, result: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Ceiling for a burst gap. Past this it is not a burst, it is a paced walk.
+ *
+ * HOW TO PICK A GAP, because both edges are real and neither is guessable. It must outlast the
+ * handler committing and dispatching its request, and undercut the response it is racing.
+ * Measured against a superseded-filter race (the superseded query 700ms, the one replacing it 90ms):
+ * at 0ms the first request was never issued at all, and at the ordinary settle (~500ms in a
+ * throttled tab, where rAF never fires and the frame budget always times out) the two clicks
+ * serialised and never overlapped. 50ms sat in the window. A different app needs a different
+ * number: read its own slow endpoint.
+ */
+export declare const BURST_MAX_GAP_MS = 500;
+/** A recorded gap as the live tool would apply it: clamped, or absent. */
+export declare function burstGap(burstMs: number | undefined): number | undefined;
+/** A burst step returns as soon as it is dispatched: the gap, not the settle, paces the sequence. */
+export declare function pacedArgs(args: Record<string, unknown>, gap: number | undefined): Record<string, unknown>;
+/**
+ * Wait out the rest of the gap that began when the previous step was dispatched, if there is one. The gap is between
+ * ACTIONS, as live, so time the previous step already took counts towards it.
+ */
+export declare function holdGap(elapsed: () => number, since: number | undefined, gap: number | undefined, sleep: (ms: number) => Promise<void>): Promise<void>;
 export {};

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

@@ -1,6 +1,6 @@
 /**
- * The two things a sequence step needs beyond a plain act: a retry when the ref goes stale under a
- * re-render, and a result shaped for the per-step report.
+ * The things a sequence step needs beyond a plain act: a retry when the ref goes stale under a
+ * re-render, a result shaped for the per-step report, and the `burst` pace (at the end).
  *
  * ── THE RETRY ─────────────────────────────────────────────────────────────────────────────────
  *
@@ -30,8 +30,9 @@ const realSleep = {
  */
 export async function runStepWithStaleRetry(attempt, session, since, budgetMs, opts = realSleep) {
     const first = await attempt();
-    if (first.ok || !isStaleRefError(first.error))
+    if (first.ok || !isStaleRefError(first.error)) {
         return first;
+    }
     await waitForReaction(session, since, budgetMs, opts);
     return attempt();
 }
@@ -51,9 +52,64 @@ export function describeStepResult(step, result) {
         settleReason: result['settleReason'] ?? null,
     };
     // `reticleUi`: the step hit Reticle's own HUD, so the recorder leaves it out of the app's flow.
-    for (const key of ['testid', 'component', 'role', 'name', 'source', 'warning', 'reticleUi']) {
-        if (result[key] !== undefined)
+    // `secret`: the SDK says the target holds a secret. Without it a sequence saved a password in clear.
+    // `nth`/`of`/`testidOf`: the control's position among namesakes, which the recorder anchors on.
+    // `componentNth`/`componentOf`: its position among the elements of its component anchor.
+    for (const key of [
+        'testid',
+        'testidOf',
+        'testidNth',
+        'nth',
+        'of',
+        'component',
+        'componentNth',
+        'componentOf',
+        'ownText',
+        'role',
+        'name',
+        'within',
+        'source',
+        'warning',
+        'reticleUi',
+        'secret',
+    ]) {
+        if (result[key] !== undefined) {
             out[key] = result[key];
+        }
     }
     return out;
 }
+// ── THE BURST PACE ── shared by the live tool and the replay of a saved sequence (#2130). ──────
+/**
+ * Ceiling for a burst gap. Past this it is not a burst, it is a paced walk.
+ *
+ * HOW TO PICK A GAP, because both edges are real and neither is guessable. It must outlast the
+ * handler committing and dispatching its request, and undercut the response it is racing.
+ * Measured against a superseded-filter race (the superseded query 700ms, the one replacing it 90ms):
+ * at 0ms the first request was never issued at all, and at the ordinary settle (~500ms in a
+ * throttled tab, where rAF never fires and the frame budget always times out) the two clicks
+ * serialised and never overlapped. 50ms sat in the window. A different app needs a different
+ * number: read its own slow endpoint.
+ */
+export const BURST_MAX_GAP_MS = 500;
+/** A recorded gap as the live tool would apply it: clamped, or absent. */
+export function burstGap(burstMs) {
+    return burstMs === undefined ? undefined : Math.max(0, Math.min(burstMs, BURST_MAX_GAP_MS));
+}
+/** A burst step returns as soon as it is dispatched: the gap, not the settle, paces the sequence. */
+export function pacedArgs(args, gap) {
+    return gap === undefined ? args : { ...args, settleMs: 0 };
+}
+/**
+ * Wait out the rest of the gap that began when the previous step was dispatched, if there is one. The gap is between
+ * ACTIONS, as live, so time the previous step already took counts towards it.
+ */
+export async function holdGap(elapsed, since, gap, sleep) {
+    if (since === undefined || gap === undefined) {
+        return;
+    }
+    const remaining = gap - (elapsed() - since);
+    if (remaining > 0) {
+        await sleep(remaining);
+    }
+}

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

@@ -48,7 +48,9 @@ export async function resolveActTarget(session, args,
  * was ignored.
  */
 appearanceMs) {
-    const ref = asString(args['ref']);
+    // A ref inside the target object (`target: { ref }`) is the same instruction as a top-level ref.
+    // Read as a query it named nothing, and the step failed with "Nothing was searched".
+    const ref = asString(args['ref']) ?? asString(asRecord(args['target'])['ref']);
     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.

package/dist/surface/tools/act/after-match.d.ts

@@ -9,9 +9,19 @@
  * nothing on its own.
  */
 import type { Predicate } from '@reticlehq/core';
+import { evaluatePredicate, waitForPredicate, type EvalResult } from '@reticlehq/engine/question/predicate/predicate.js';
 import { waitForInFlight } from './settle-in-flight.js';
 import { revertedAfterMatch } from './durable.js';
+type WaitArgs = Parameters<typeof waitForPredicate>;
+/** Wait for the predicate inside the budget, or read it once when there is no budget. */
+export declare function evaluateAfterAct(session: WaitArgs[0], until: Predicate, timeout: number, since: number, baselines: WaitArgs[4]): Promise<EvalResult>;
 type Waited = Parameters<typeof waitForInFlight>[0] & Parameters<typeof revertedAfterMatch>[0];
 /** Returns the sentence to fail with when the consequence reverted, else undefined. */
 export declare function finishAfterMatch(session: Waited, until: Predicate, since: number, baselines: Parameters<typeof revertedAfterMatch>[3], remaining: () => number): Promise<string | undefined>;
+/**
+ * A green that rests only on hidden matches, read again until a match shows, for at most
+ * SHOWN_GRACE_MS. Returns the reading that shows one, or `verdict` unchanged. Nothing is predicted:
+ * the verdict is judged on what the page painted, and a node that stays hidden stays `hidden_match`.
+ */
+export declare function awaitShownMatch(session: Parameters<typeof evaluatePredicate>[0], until: Predicate, since: number, baselines: Parameters<typeof evaluatePredicate>[4], verdict: EvalResult, remaining: () => number): Promise<EvalResult>;
 export {};

package/dist/surface/tools/act/after-match.js

@@ -8,9 +8,18 @@
  * rest of the budget the caller already granted is spent here, in three steps, each deciding
  * nothing on its own.
  */
+import { hiddenMatchNote } from '@reticlehq/engine/evidence/already-true.js';
+import { evaluatePredicate, waitForPredicate, } from '@reticlehq/engine/question/predicate/predicate.js';
 import { waitForInFlight } from './settle-in-flight.js';
 import { waitForReaction } from './react-grace.js';
 import { revertedAfterMatch } from './durable.js';
+/** Wait for the predicate inside the budget, or read it once when there is no budget. */
+export function evaluateAfterAct(session, until, timeout, since, baselines) {
+    if (timeout > 0) {
+        return waitForPredicate(session, until, timeout, since, baselines);
+    }
+    return evaluatePredicate(session, until, since, true, baselines);
+}
 /** Returns the sentence to fail with when the consequence reverted, else undefined. */
 export async function finishAfterMatch(session, until, since, baselines, remaining) {
     const sleep = { sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)) };
@@ -28,3 +37,34 @@ export async function finishAfterMatch(session, until, since, baselines, remaini
     // 3. Then ask whether what held still holds — see revertedAfterMatch.
     return revertedAfterMatch(session, until, since, baselines);
 }
+/**
+ * How long a match that holds only on hidden nodes gets to show. An entrance fade or a toast mounted
+ * at opacity 0 reads hidden for its first frame, and the wait matched on that frame. A node hidden
+ * by design pays this once, on a verdict that is `unknown` either way.
+ */
+const SHOWN_GRACE_MS = 1000;
+/** Poll cadence — the same as the reaction grace. */
+const SHOWN_POLL_MS = 50;
+/**
+ * A green that rests only on hidden matches, read again until a match shows, for at most
+ * SHOWN_GRACE_MS. Returns the reading that shows one, or `verdict` unchanged. Nothing is predicted:
+ * the verdict is judged on what the page painted, and a node that stays hidden stays `hidden_match`.
+ */
+export async function awaitShownMatch(session, until, since, baselines, verdict, remaining) {
+    if (!verdict.pass || hiddenMatchNote(until, verdict.evidence) === undefined) {
+        return verdict;
+    }
+    // Counted in reads, not read off the session clock, so a clock that does not move still ends it.
+    const reads = Math.floor(Math.min(SHOWN_GRACE_MS, remaining()) / SHOWN_POLL_MS);
+    for (let read = 0; read < reads; read += 1) {
+        await new Promise((resolve) => setTimeout(resolve, SHOWN_POLL_MS));
+        const now = await evaluatePredicate(session, until, since, true, baselines);
+        if (!now.pass) {
+            return verdict;
+        }
+        if (hiddenMatchNote(until, now.evidence) === undefined) {
+            return now;
+        }
+    }
+    return verdict;
+}

package/dist/surface/tools/act/already-true.js

@@ -18,7 +18,7 @@ export async function readAlreadyTrue(session, until, since) {
     // baseline yet would report `inconclusive` — reading the app twice to answer a question we had
     // not taken the reading for.
     const baselines = await captureBaselines(session, until);
-    const precheck = until !== undefined && readsDomState(until)
+    const precheck = until !== undefined && readsDomState(until, since)
         ? await evaluatePredicate(session, until, since, false, baselines)
         : undefined;
     const alreadyTrue = precheck?.pass ?? false;

package/dist/surface/tools/act/navigation/reload-result.d.ts

@@ -16,4 +16,15 @@
  * branch reports it (navigate-result.ts): so "Reticle stopped waiting" is distinguishable from "the
  * page never came back", and the fix — a larger `timeout_ms` — is visible in the result.
  */
-export declare function reloadResult(reconnected: boolean, waitedMs: number): Record<string, unknown>;
+export declare function reloadResult(reconnected: boolean, waitedMs: number, hard?: HardReload): Record<string, unknown>;
+/**
+ * How a `hard` reload reached the page (#1785). A leased tab reloads through the browser with the
+ * cache ignored. Any other tab can only fetch its document again, so its modules can be stale.
+ */
+export declare const HardReload: {
+    readonly CACHE_IGNORED: "cache_ignored";
+    readonly DOCUMENT_ONLY: "document_only";
+};
+export type HardReload = (typeof HardReload)[keyof typeof HardReload];
+/** The `hardReload` field for a reload, or nothing when the call did not ask for `hard`. */
+export declare function hardReloadOf(hard: boolean, throughBrowser: boolean): HardReload | undefined;

package/dist/surface/tools/act/navigation/reload-result.js

@@ -27,8 +27,31 @@ const RELOAD_RECONNECTED_NOTE = 'the page came back and re-announced itself unde
  * branch reports it (navigate-result.ts): so "Reticle stopped waiting" is distinguishable from "the
  * page never came back", and the fix — a larger `timeout_ms` — is visible in the result.
  */
-export function reloadResult(reconnected, waitedMs) {
-    return reconnected
+export function reloadResult(reconnected, waitedMs, hard) {
+    const base = reconnected
         ? { ok: true, confirmed: true, note: RELOAD_RECONNECTED_NOTE }
         : { ok: true, confirmed: false, waitedMs, note: RELOAD_NOTE };
+    if (hard === undefined) {
+        return base;
+    }
+    return { ...base, hardReload: hard, note: `${base.note} ${HARD_RELOAD_NOTE[hard]}` };
+}
+/**
+ * How a `hard` reload reached the page (#1785). A leased tab reloads through the browser with the
+ * cache ignored. Any other tab can only fetch its document again, so its modules can be stale.
+ */
+export const HardReload = {
+    CACHE_IGNORED: 'cache_ignored',
+    DOCUMENT_ONLY: 'document_only',
+};
+const HARD_RELOAD_NOTE = {
+    [HardReload.CACHE_IGNORED]: 'The browser reloaded with its cache ignored, so every script and module was fetched again.',
+    [HardReload.DOCUMENT_ONLY]: 'This tab is not a lease, so only the document was fetched again. Scripts and modules can still come from the browser cache. To fetch them again, reload the tab in the browser with Cmd+Shift+R, or take a lease with reticle_lease.',
+};
+/** The `hardReload` field for a reload, or nothing when the call did not ask for `hard`. */
+export function hardReloadOf(hard, throughBrowser) {
+    if (!hard) {
+        return undefined;
+    }
+    return throughBrowser ? HardReload.CACHE_IGNORED : HardReload.DOCUMENT_ONLY;
 }

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

@@ -2,6 +2,8 @@
 export type TargetResolution = {
     readonly kind: 'ref';
     readonly ref: string;
+    /** Set when every match was hidden and the action uses the hidden one. Says so to the caller. */
+    readonly hiddenTarget?: string;
 } | {
     readonly kind: 'global';
     readonly ref: '';
@@ -9,6 +11,18 @@ export type TargetResolution = {
     readonly kind: 'error';
     readonly message: string;
 };
+/**
+ * What a result says when every match was hidden and the action used the hidden one. It does not
+ * say that a person could not reach it: a hidden input with a visible label is reached through the
+ * label, and the reach check after the action decides that.
+ */
+export declare function hiddenTargetNote(ref: string): string;
+/** The `hiddenTarget` field for a tool result, or nothing when the action used a visible match. */
+export declare function hiddenTargetField(resolution: TargetResolution): {
+    hiddenTarget?: string;
+};
+/** The words before the nearest-target list in a no_match refusal. The repeat hint reads after it. */
+export declare const NEAREST_TARGETS_LEAD = " The nearest targets on the page, most similar first: ";
 /**
  * Turn a target QUERY into the single ref an action can be performed on.
  *
@@ -24,7 +38,9 @@ export type TargetResolution = {
  *
  * Invisible matches are filtered before counting: a hidden duplicate is a common way for a
  * legitimately unambiguous query to look ambiguous, and refusing on it would push callers back to
- * the two-turn path for no gain.
+ * the two-turn path for no gain. When every match is hidden, the one hidden match is used and the
+ * resolution names it in `hiddenTarget`. It is not refused: a hidden input is often clicked through
+ * its visible label.
  *
  * 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.