@reticlehq/server 3.9.0 → 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

@@ -169,7 +169,7 @@ export function assertSequenceSteps(steps) {
         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.');
     });
 }

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/after-match.d.ts

@@ -9,9 +9,12 @@
  * nothing on its own.
  */
 import type { Predicate } from '@reticlehq/core';
-import { evaluatePredicate, type EvalResult } from '@reticlehq/engine/question/predicate/predicate.js';
+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>;

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

@@ -9,10 +9,17 @@
  * nothing on its own.
  */
 import { hiddenMatchNote } from '@reticlehq/engine/evidence/already-true.js';
-import { evaluatePredicate, } from '@reticlehq/engine/question/predicate/predicate.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)) };

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,16 @@ 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: ";
 /**
@@ -26,7 +38,9 @@ export declare const NEAREST_TARGETS_LEAD = " The nearest targets on the page, m
  *
  * 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.

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

@@ -83,6 +83,23 @@ function nearNamesClause(hint) {
         '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).');
 }
+/**
+ * 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 function hiddenTargetNote(ref) {
+    return (`every element that matched the target is hidden, so the action used the hidden match ${ref}. ` +
+        'If a person reaches it through a visible label, this is correct. If not, target the control ' +
+        'a person can see.');
+}
+/** The `hiddenTarget` field for a tool result, or nothing when the action used a visible match. */
+export function hiddenTargetField(resolution) {
+    if ('ref' !== resolution.kind || resolution.hiddenTarget === undefined) {
+        return {};
+    }
+    return { hiddenTarget: resolution.hiddenTarget };
+}
 const NearestTargetsSchema = z.array(NearestTargetSchema).min(1);
 /** The words before the nearest-target list in a no_match refusal. The repeat hint reads after it. */
 export const NEAREST_TARGETS_LEAD = ' The nearest targets on the page, most similar first: ';
@@ -117,7 +134,9 @@ function nearestClause(hint) {
  *
  * 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.
@@ -153,5 +172,9 @@ export function resolveTargetRef(candidates, hint) {
     if ('string' !== typeof ref || 0 === ref.length) {
         return { kind: 'error', message: 'target matched an element with no usable ref.' };
     }
+    // Every match was hidden, so the action uses a hidden one. Rule 11: say so, never silently.
+    if (0 === visible.length) {
+        return { kind: 'ref', ref, hiddenTarget: hiddenTargetNote(ref) };
+    }
     return { kind: 'ref', ref };
 }

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

@@ -46,6 +46,16 @@ export interface StepExpectation {
      * step is undecided, never a miss — `unknown`, as act_and_wait says.
      */
     undecided?: string;
+    /** The step's action (`click`, `fill`), so a plan that could not judge a step can name it. */
+    action?: string;
+    /** A real frame flushed after this step's action, as `settled` on its act result says. */
+    settled?: boolean;
+    /**
+     * Absence-derived contradiction kinds seen in this step's window (a request that never settled,
+     * for example). They do not decide a miss, but they stop a plan from claiming no channel saw a
+     * problem.
+     */
+    doubted?: readonly string[];
 }
 export interface SequenceGrade {
     verified: Verified;
@@ -69,6 +79,8 @@ interface SequencePlan {
     readonly planned: number;
     /** Whether anything actually reached the page. */
     readonly dispatched: boolean;
+    /** The capture lost events inside the plan's window, so no channel saw all of it. */
+    readonly captureLost?: boolean;
 }
 export declare function gradeSequence(steps: readonly StepExpectation[], plan?: SequencePlan): SequenceGrade;
 /**

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

@@ -23,6 +23,23 @@ import { Verified, VerifiedReason } from '@reticlehq/core';
  * sweep of independent controls, where stopping at the first would hide the other thirteen.
  */
 export const DeviationMode = { HALT: 'halt', CONTINUE: 'continue' };
+/** The sentence for a plan whose steps declared nothing. */
+function undeclaredBecause(total, dispatched) {
+    if (0 === total) {
+        return 'the plan had no steps, so nothing was driven and nothing was proved';
+    }
+    // A step refused before dispatch is a malformed call: telling its author to add an `expect`
+    // sends them to the wrong thing.
+    if (!dispatched) {
+        return `nothing was dispatched, so none of the ${String(total)} step(s) ran — read the per-step \`error\` for the one that was refused, and fix that before adding an \`expect\``;
+    }
+    return `all ${String(total)} step(s) declared nothing, so the app was driven but not verified — give each step an \`expect\` naming the consequence it causes`;
+}
+/** A step as a sentence names it: its number, counted from 1, and its action when it has one. */
+function stepName(index, action) {
+    const number = `step ${String(index + 1)}`;
+    return action === undefined ? number : `${number} (${action})`;
+}
 export function gradeSequence(steps, plan = { planned: steps.length, dispatched: true }) {
     const total = Math.max(plan.planned, steps.length);
     const declaring = steps.filter((step) => step.declared);
@@ -54,44 +71,37 @@ 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)
+    // Nothing failed that was seen: a step nobody could judge leaves the plan undecided. The sentence
+    // names the step and what was missing, so the agent knows which step to change (#2204).
+    const unjudgedAt = steps.findIndex((step) => step.undecided !== undefined);
+    if (unjudgedAt >= 0) {
+        const unjudged = steps[unjudgedAt];
         return {
             verified: Verified.UNKNOWN,
             reason: VerifiedReason.INCONCLUSIVE,
             declared,
             total,
-            because: `a step could not be judged — ${unjudged.undecided ?? ''}`,
+            because: `${stepName(unjudgedAt, unjudged?.action)} could not be judged: ${unjudged?.undecided ?? ''}`,
         };
+    }
     /*
-     * `unknown` rather than `no-fault`, and the distinction is load-bearing.
-     *
-     * "Nothing was declared" is what `no-fault` means for a single action -- but the engine only says
-     * it over a SETTLED window, because no-fault claims the whole window was observed. Nothing on
-     * this path observes settledness: the caller tracks dispatch and stalls, never settle. Saying
-     * `no-fault` here would claim evidence nobody collected, in the one place this product cannot
-     * afford to overclaim.
-     *
-     * So the enum stays conservative and the SENTENCE carries the whole answer: it names declaring a
-     * consequence as the next move, which is what an agent reading `no-fault` would have done.
-     * Upgrading means plumbing `settled` from the act results through `SequencePlan`.
+     * Nothing declared is `no-fault` over a quiet plan and `unknown` otherwise. This is the rule a
+     * single action follows (`engine/src/evidence/verified.ts`): no-fault claims the whole window was
+     * observed, so every step must report a settled frame, no step may carry an absence-derived
+     * finding, and the capture must be whole. `unknown` sends an agent to look again with better
+     * coverage. When the plan was quiet, that cannot help: the fix is to declare a consequence.
      */
     if (0 === declared) {
+        const quiet = plan.dispatched &&
+            true !== plan.captureLost &&
+            steps.length > 0 &&
+            steps.every((step) => true === step.settled && 0 === (step.doubted ?? []).length);
         return {
-            verified: Verified.UNKNOWN,
+            verified: quiet ? Verified.NO_FAULT : Verified.UNKNOWN,
             reason: VerifiedReason.NOTHING_DECLARED,
             declared,
             total,
-            because: 0 === total
-                ? 'the plan had no steps, so nothing was driven and nothing was proved'
-                : // "the app was driven" was said unconditionally, including on a call whose own
-                    // `dispatched` was false in the same object. A step refused before dispatch is a
-                    // malformed call, and telling its author to add an `expect` sends them at the wrong
-                    // thing entirely.
-                    plan.dispatched
-                        ? `all ${String(total)} step(s) declared nothing, so the app was driven but not verified — give each step an \`expect\` naming the consequence it causes`
-                        : `nothing was dispatched, so none of the ${String(total)} step(s) ran — read the per-step \`error\` for the one that was refused, and fix that before adding an \`expect\``,
+            because: undeclaredBecause(total, plan.dispatched),
         };
     }
     // A journey is proved at its END. Declaring only early steps checks that it started, and a yes
@@ -144,8 +154,9 @@ export function gradeSequence(steps, plan = { planned: steps.length, dispatched:
 /** 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)
+    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 { flowName: "${JOURNEY_RECORDING}", saveAs: "<name>" }, and the steps that declared nothing will replay ` +