@reticlehq/server 3.9.0 → 3.10.0

package/dist/surface/tools/observe-tools.js

@@ -4,6 +4,7 @@
  */
 import { checkWords, runIdOfCall } from '../../judgement/runs/drive-run.js';
 import { noteEmptyRead } from './gaps/observed-nothing.js';
+import { withPreAttach } from './read/console-pre-attach.js';
 import { z } from 'zod';
 import { aliasParam } from './args/alias-args.js';
 import { CONSOLE_ATTACH_NOTE, CONSOLE_LEVELS, ReticleCommand, DEFAULT_ASSERT_TIMEOUT_MS, PredicateKind, Verified, checkIntent, } from '@reticlehq/core';
@@ -450,13 +451,15 @@ export const OBSERVE_TOOLS = [
             // Two nudges, both only on a GREEN verdict (a failing one is moot): a presence-only assertion
             // a wrong element can fake, and an assertion pinned to a status Reticle derived rather than one
             // a server sent. Neither blocks — the assertion still passes; they steer the next one.
-            const advice = !verdict.pass
-                ? {}
-                : isPresenceOnlyAssertion(predicate)
-                    ? { advice: PRESENCE_ONLY_ADVICE }
-                    : assertsDerivedIpcStatus(predicate)
-                        ? { advice: DERIVED_IPC_STATUS_ADVICE }
-                        : {};
+            let advice = {};
+            if (verdict.pass) {
+                if (isPresenceOnlyAssertion(predicate)) {
+                    advice = { advice: PRESENCE_ONLY_ADVICE };
+                }
+                else if (assertsDerivedIpcStatus(predicate)) {
+                    advice = { advice: DERIVED_IPC_STATUS_ADVICE };
+                }
+            }
             // Asked of every verdict drawn after an observed edit, not once per edit — see
             // isChangeUndeclared for why repeating it is disclosure rather than nagging.
             // Read once: the undeclared-change check and the engine's claim reading share it.
@@ -609,7 +612,10 @@ export const OBSERVE_TOOLS = [
              * `true` and `false` keep their exact old meanings, so a caller that already passes one is
              * unaffected. Only the omitted case moves.
              */
-            const bodyMode = 'boolean' === typeof args['bodies'] ? (args['bodies'] ? 'all' : 'none') : 'auto';
+            let bodyMode = 'auto';
+            if ('boolean' === typeof args['bodies']) {
+                bodyMode = args['bodies'] ? 'all' : 'none';
+            }
             // A filter names specific calls, so under `auto` their bodies are the thing being asked about.
             const named = method !== undefined || urlContains !== undefined || status !== undefined;
             const buffer = bufferEnvelope(session);
@@ -729,7 +735,7 @@ export const OBSERVE_TOOLS = [
             }
             // Default the cap so an omitted `limit` can't dump a whole flooded session (since defaults to 0).
             const { events: budgeted, droppedOldest } = applyEventBudget(matched, limit ?? DEFAULT_QUERY_LIMIT);
-            const logs = budgeted.map(projectConsoleLog);
+            const logs = budgeted.map((e) => withPreAttach(projectConsoleLog(e), e));
             // Say the look HAPPENED when it found nothing. A quiet page and a dead console observer both
             // produced `{ logs: [] }`, and "no console errors" is the claim agents lean on most — see
             // observed-nothing.ts, whose own header names this exact case and which every other array-

package/dist/surface/tools/read/console-pre-attach.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Say on a console line that the page raised it before the SDK attached (#1540).
+ *
+ * The build plugin's inline buffer holds what an app raised while nothing listened: an entry module
+ * that 404'd or threw, a rejection, a `console.error` during start-up. The SDK reports it when it
+ * attaches, marked `preAttach`. Without the mark on the line the agent reads, a reported error looks
+ * like one the last action caused, and the reason a page is blank is not read as a load failure.
+ *
+ * Here and not in the engine's `projectConsoleLog`: the engine does not take new names from core.
+ */
+import { type ReticleEvent } from '@reticlehq/core';
+export interface PreAttachMark {
+    /** The page raised it before the SDK attached. */
+    preAttach?: true;
+    /** How many more pre-attach errors the full buffer did not keep — loss, declared. */
+    droppedPreAttach?: number;
+}
+/** The console line, with the pre-attach mark and the declared loss when the event carries them. */
+export declare function withPreAttach<T extends object>(view: T, e: ReticleEvent): T & PreAttachMark;

package/dist/surface/tools/read/console-pre-attach.js

@@ -0,0 +1,23 @@
+/**
+ * Say on a console line that the page raised it before the SDK attached (#1540).
+ *
+ * The build plugin's inline buffer holds what an app raised while nothing listened: an entry module
+ * that 404'd or threw, a rejection, a `console.error` during start-up. The SDK reports it when it
+ * attaches, marked `preAttach`. Without the mark on the line the agent reads, a reported error looks
+ * like one the last action caused, and the reason a page is blank is not read as a load failure.
+ *
+ * Here and not in the engine's `projectConsoleLog`: the engine does not take new names from core.
+ */
+import { CONSOLE_EVENT, asNumber } from '@reticlehq/core';
+/** The console line, with the pre-attach mark and the declared loss when the event carries them. */
+export function withPreAttach(view, e) {
+    const mark = {};
+    if (true === e.data[CONSOLE_EVENT.PRE_ATTACH]) {
+        mark.preAttach = true;
+    }
+    const dropped = asNumber(e.data[CONSOLE_EVENT.DROPPED_PRE_ATTACH]);
+    if (dropped !== undefined && dropped > 0) {
+        mark.droppedPreAttach = dropped;
+    }
+    return { ...view, ...mark };
+}

package/dist/surface/tools/read-tools.js

@@ -2,12 +2,14 @@
  * Read / record / replay tools — baselines + diff, recordings + replay, narrate, clock, state,
  * explore. Split out of tools.ts; assembled back via...READ_TOOLS.
  */
-import { UNKEPT_EXPECT } from '../../language/flows/replay.js';
+import { UNKEPT_EXPECT, pageOf } from '../../language/flows/replay.js';
 import { resolveAnnotateTarget } from '../../language/flows/annotate-notes/annotate-target.js';
 import { z } from 'zod';
 import { EventType, ReticleCommand, REPLAY_PROGRAM_VERSION, SnapshotMode, StorageArea, } from '@reticlehq/core';
 import { ReticleTool } from '@reticlehq/core';
 import { advanceMsSchema, depthSchema } from './args/numeric-bounds.js';
+import { StepFramesSchema } from '../../portal/pool/determinism.js';
+const NOT_DETERMINISTIC = 'stepFrames needs a deterministic lease. Acquire one with reticle_lease { action: "acquire", url, deterministic: {} }, then pass its sessionId.';
 import { aliasParam, aliasUsed } from './args/alias-args.js';
 /** `name` for `recordingName`: the spelling every other naming argument uses. */
 const RECORDING_NAME_ALIAS = z.string().optional().describe('Alias for `recordingName`.');
@@ -22,25 +24,6 @@ import { buildReactionReport, summarizeReaction } from '@reticlehq/engine/questi
 import { asNumber, asString, parseInteractive } from '@reticlehq/core';
 import { sessionIdShape, commandOrThrow, snapshotTree } from './tool-kit.js';
 import { bufferEnvelope } from '../../portal/session/session-health.js';
-import { navigablePath, routeOfUrl } from '@reticlehq/engine/question/predicate/predicate-route.js';
-/** The route part of a session URL. A host belongs to the machine, not to the journey. */
-/**
- * The page a recording started on, as a NAVIGABLE path: pathname + query + hash.
- *
- * The hash matters and the pathname alone is not enough. Under a hash router every page has the
- * document pathname `/`, so a recording made on `#/posts/12` stored `/`, the replay's start-path
- * comparison saw `/` on both sides and never warned about drift, and the navigate it suggests
- * pointed at the default route rather than the recorded one.
- */
-function pathnameOf(url) {
-    if (url === undefined)
-        return undefined;
-    const parts = routeOfUrl(url);
-    // The query too, minus Reticle's own params: `/products?scope=TOPWEAR` and `/products` are different
-    // pages, and replay compares the query when the flow recorded one (#1059), so dropping it here
-    // started the replay on the unfiltered page (#1411).
-    return parts === undefined ? undefined : navigablePath(parts);
-}
 /** What record-stop says when the span crossed a full-page load (#1411). */
 const RECORDING_CROSSED_RELOAD = 'The recording crossed a full-page load: the page it started on unloaded, so the reaction report and the proposed consequences cover only the page that loaded after it.';
 /**
@@ -161,7 +144,7 @@ export const READ_TOOLS = [
             recordingName: z
                 .string()
                 .optional()
-                .describe('Identifier for this recording. Pass the same name to reticle_record{action:"stop"} and reticle_replay.'),
+                .describe('Identifier for this recording. Pass the same name to reticle_record{action:"stop"} and reticle_record{action:"replay"}.'),
             name: RECORDING_NAME_ALIAS,
             ...sessionIdShape,
         },
@@ -176,9 +159,9 @@ export const READ_TOOLS = [
             const name = asString(aliasParam(args, 'recordingName', ['name'])['recordingName']) ?? 'default';
             const cursor = session.elapsed();
             // Where the journey begins, so a saved flow can navigate here before step 1 instead of
-            // replaying from wherever the page happens to be. Pathname only: a host or port belongs to
-            // the machine that recorded it, not to the journey.
-            deps.recordings.start(name, cursor, pathnameOf(session.url), session.id, session.currentDocumentId);
+            // replaying from wherever the page happens to be. No host or port: they belong to the machine
+            // that recorded it, not to the journey. The app's query and hash stay (see pageOf).
+            deps.recordings.start(name, cursor, pageOf(session.url), session.id, session.currentDocumentId);
             return Promise.resolve({
                 recordingName: name,
                 since: cursor,
@@ -339,7 +322,7 @@ export const READ_TOOLS = [
     },
     {
         name: ReticleTool.CLOCK,
-        description: 'Control a fake clock: { freeze:true } to freeze time, { advanceMs:N } to fast-forward timers (toasts, debounces, auto-dismiss), { reset:true } to restore. Lets you test time-gated UI deterministically.',
+        description: 'Control a fake clock: { freeze:true } to freeze time, { advanceMs:N } to fast-forward timers (toasts, debounces, auto-dismiss), { reset:true } to restore. Lets you test time-gated UI deterministically. On a lease acquired with `deterministic`, { stepFrames:N } moves its clock N frames of 16.67 ms: due timers run, then the requestAnimationFrame callbacks, once each frame.',
         inputSchema: {
             freeze: z
                 .boolean()
@@ -349,6 +332,7 @@ export const READ_TOOLS = [
                 .optional()
                 .describe('Fast-forward time by this many milliseconds — triggers debounces, toasts, auto-dismiss timers.'),
             reset: z.boolean().optional().describe('Restore the real clock.'),
+            stepFrames: StepFramesSchema.optional().describe('Step a deterministic lease by this many frames (60 each second). Only for a lease acquired with `deterministic`.'),
             ...sessionIdShape,
         },
         // The command returns `{ frozen }`. It used to declare `{ ok, elapsed }` — neither of which any
@@ -356,12 +340,31 @@ export const READ_TOOLS = [
         // successful freeze and a failed one both validated to `{}` and became indistinguishable.
         outputSchema: {
             frozen: z.boolean().optional(),
+            frame: z
+                .number()
+                .optional()
+                .describe('After stepFrames: the frames stepped since the page loaded.'),
+            nowMs: z
+                .number()
+                .optional()
+                .describe("After stepFrames: the page's performance.now(), in virtual milliseconds."),
+        },
+        handler: async (deps, args) => {
+            if (args['stepFrames'] !== undefined) {
+                const session = deps.sessions.resolve(asString(args['sessionId']));
+                const frames = StepFramesSchema.parse(args['stepFrames']);
+                const stepped = await deps.pool?.stepLease(session.id, frames);
+                if (stepped === undefined) {
+                    throw new Error(NOT_DETERMINISTIC);
+                }
+                return { frozen: true, ...stepped };
+            }
+            return commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.CLOCK, {
+                freeze: args['freeze'],
+                advanceMs: args['advanceMs'],
+                reset: args['reset'],
+            });
         },
-        handler: (deps, args) => commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.CLOCK, {
-            freeze: args['freeze'],
-            advanceMs: args['advanceMs'],
-            reset: args['reset'],
-        }),
     },
     {
         name: ReticleTool.STATE,

package/dist/surface/tools/real-input-attempt.d.ts

@@ -62,13 +62,5 @@ export declare const HOVER_OFF_VIEWPORT_MSG = "cannot hover: the target is outsi
  * or throws.
  */
 export declare function tryRealInput(deps: ToolDeps, session: Session, ref: string, action: ActionType, args: Record<string, unknown>): Promise<RealActResult>;
-/**
- * The session a flow replay runs on, with a press sent to the lease's real keyboard.
- *
- * Replay dispatches its steps itself, not through `reticle_act`, so a recorded Tab replayed as a
- * synthetic keydown that moves no focus, and a keyboard flow that passed live drifted on replay.
- * Every other command, and a press this lease cannot drive for real, goes to the page as before.
- * A Proxy, not a copy: the session keeps private state its own methods read.
- */
 export declare function withLeaseKeyboard(deps: ToolDeps, session: Session): Session;
 export {};

package/dist/surface/tools/real-input-attempt.js

@@ -19,14 +19,15 @@
  * the base64 4/3 inflation factor applied, so the encoded payload always fits in one WebSocket
  * frame.
  */
-import { ActionType, clickInputProblem, DriveErrorCode, ElementState, INSPECT_IN_VIEWPORT_FIELD, INSPECT_REVEAL_ARG, InputMode, InputModeReason, ReticleCommand, TRANSPORT_LIMITS, } from '@reticlehq/core';
-import { boxCenter, DriveError, isRealInputAction, unspellablePressReason, } from '../../portal/input/real-input.js';
+import { ACT_POINT_ARG, ActionType, actPointProblem, boxFractionFromArgs, clickInputProblem, DRAG_TO_POINT_ARG, DriveErrorCode, ElementState, INSPECT_IN_VIEWPORT_FIELD, INSPECT_REVEAL_ARG, InputMode, InputModeReason, ReticleCommand, TRANSPORT_LIMITS, } from '@reticlehq/core';
+import { boxPoint, DriveError, isRealInputAction, unspellablePressReason, } from '../../portal/input/real-input.js';
 import { assertDragNotDestructive, assertNotDestructive } from './act/act-danger.js';
 import { assertNativeAllowed } from '../../portal/production/production-drive.js';
 import { NATIVE_INPUT_ARG } from '@reticlehq/core';
 import { asNumber, asRecord, asString } from '@reticlehq/core';
 import { commandOrThrow } from './tool-kit.js';
 import { asBox } from './act/act-helpers.js';
+import { isStaleRefError } from './act/act-sequence-retry.js';
 import { isAbsolute, join, relative, extname, basename, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { RETICLE_CONFIG_BASENAME } from '../../command/cli/ports/resolve/cli-port.js';
@@ -269,6 +270,15 @@ function performArgsOf(inner) {
     if (holdMs !== undefined) {
         performArgs.holdMs = holdMs;
     }
+    // A point inside the target: a canvas has no child elements, so its centre is not enough.
+    const at = boxFractionFromArgs(inner, ACT_POINT_ARG);
+    if (at !== undefined) {
+        performArgs.at = at;
+    }
+    const to = boxFractionFromArgs(inner, DRAG_TO_POINT_ARG);
+    if (to !== undefined) {
+        performArgs.to = to;
+    }
     // `keys` and `code` are read but not forwarded: both are routed away by the caller — a multi-key
     // sequence and an explicit physical code have no driver spelling — so carrying them into the
     // provider would only invite it to guess at a gesture the caller did not ask for.
@@ -284,7 +294,11 @@ const ANCHOR_FIELDS = [
     'name',
     'nth',
     'of',
+    'componentNth',
+    'componentOf',
+    'ownText',
     'secret',
+    'within',
 ];
 /**
  * Press with a leased page's real keyboard, or undefined when this session is not such a lease.
@@ -298,6 +312,31 @@ const ANCHOR_FIELDS = [
  * keeps the in-page press, with the reason: a person's keyboard could not reach it either.
  * ponytail: lease only; the drive provider keeps its documented element-press rule.
  */
+/**
+ * Put focus on a press's target, as a person does before they press a key in a field.
+ *
+ * A real keyboard cannot aim at an element, but focus can: focus the element, confirm it holds
+ * focus, and the real key then lands there, with every default action a browser gives a trusted
+ * key (an Enter in a text field submits its form). Returns what the focused element is called, so
+ * the saved step can find it again (the real keyboard reports no element of its own), or
+ * `undefined` when the element did not take focus. No ref: nothing to focus, nothing to name.
+ */
+async function focusForPress(deps, session, ref) {
+    if (0 === ref.length) {
+        return {};
+    }
+    const focus = asRecord(await commandOrThrow(deps, session.id, ReticleCommand.ACT, {
+        ref,
+        action: ActionType.FOCUS,
+        args: {},
+    }));
+    const inspected = asRecord(await commandOrThrow(deps, session.id, ReticleCommand.INSPECT, { ref }));
+    const states = Array.isArray(inspected['states']) ? inspected['states'] : [];
+    if (!states.includes(ElementState.FOCUSED)) {
+        return undefined;
+    }
+    return Object.fromEntries(ANCHOR_FIELDS.flatMap((k) => (k in focus ? [[k, focus[k]]] : [])));
+}
 async function pressOnLease(deps, session, ref, inner) {
     const pool = deps.pool;
     if (pool === undefined || !pool.hasKeyboard(session.id)) {
@@ -307,21 +346,9 @@ async function pressOnLease(deps, session, ref, inner) {
     if (unspellable !== undefined) {
         return synthetic(unspellable);
     }
-    // What the focused element is called, from the focus act's own report, so the saved step can
-    // find it again: the real keyboard reports no element of its own.
-    let anchor = {};
-    if (0 < ref.length) {
-        const focus = asRecord(await commandOrThrow(deps, session.id, ReticleCommand.ACT, {
-            ref,
-            action: ActionType.FOCUS,
-            args: {},
-        }));
-        anchor = Object.fromEntries(ANCHOR_FIELDS.flatMap((k) => (k in focus ? [[k, focus[k]]] : [])));
-        const inspected = asRecord(await commandOrThrow(deps, session.id, ReticleCommand.INSPECT, { ref }));
-        const states = Array.isArray(inspected['states']) ? inspected['states'] : [];
-        if (!states.includes(ElementState.FOCUSED)) {
-            return synthetic(InputModeReason.TARGET_NOT_FOCUSABLE);
-        }
+    const anchor = await focusForPress(deps, session, ref);
+    if (anchor === undefined) {
+        return synthetic(InputModeReason.TARGET_NOT_FOCUSABLE);
     }
     const performed = await pool.pressLease(session.id, performArgsOf(inner));
     if (performed?.performed !== true) {
@@ -403,20 +430,21 @@ async function hoverForReal(deps, session, ref, inner, provider) {
     if (!inView) {
         throw new Error(HOVER_OFF_VIEWPORT_MSG);
     }
+    const at = boxFractionFromArgs(inner, ACT_POINT_ARG);
     if (providerReady && provider !== undefined) {
         try {
-            const performed = await provider.perform(session.url, ActionType.HOVER, box, {});
+            const performed = await provider.perform(session.url, ActionType.HOVER, box, at === undefined ? {} : { at });
             // Hover always has a resolved box, so there is always a center to report: the provider's own
             // reading, or the box's if it reported none. Both are the same point, not a fabricated one.
             if (performed.performed) {
-                return hoverSucceeded(performed.center ?? boxCenter(box), scrolled);
+                return hoverSucceeded(performed.center ?? boxPoint(box, at), scrolled);
             }
         }
         catch {
             // A provider error used to fall back to synthetic dispatch. For hover that is a lie.
         }
     }
-    const { cx, cy } = boxCenter(box);
+    const { cx, cy } = boxPoint(box, at);
     if (true === (await deps.pool?.hoverLease(session.id, cx, cy))) {
         return hoverSucceeded({ cx, cy }, scrolled);
     }
@@ -436,6 +464,11 @@ export async function tryRealInput(deps, session, ref, action, args) {
     const provider = deps.realInput;
     const inner = asRecord(args['args']);
     const askedForNative = true === inner[NATIVE_INPUT_ARG];
+    // The page refuses the same point on the synthetic path, with the same sentence.
+    const pointProblem = actPointProblem(action, inner);
+    if (pointProblem !== undefined) {
+        throw new Error(`cannot ${action}: ${pointProblem}`);
+    }
     if (action === ActionType.HOVER) {
         return hoverForReal(deps, session, ref, inner, provider);
     }
@@ -460,8 +493,10 @@ export async function tryRealInput(deps, session, ref, action, args) {
     }
     // Two `press`es this module will NOT drive, and neither is a fallback — the reason says which
     // one was asked for, instead of a different gesture being sent. See `unspellablePressReason`.
+    // A press aimed at an element is focused first (focusForPress), as on a lease; only a chord and
+    // an explicit key code stay in the page.
     if (action === ActionType.PRESS) {
-        const unspellable = unspellablePressReason(ref, inner);
+        const unspellable = unspellablePressReason('', inner);
         if (unspellable !== undefined) {
             return synthetic(unspellable);
         }
@@ -500,8 +535,12 @@ export async function tryRealInput(deps, session, ref, action, args) {
         return synthetic(InputModeReason.PAGE_NOT_CORRELATED);
     }
     const performArgs = performArgsOf(inner);
-    // A document key has no element of its own: skip INSPECT and the box entirely.
+    // A key addresses focus, not a point: focus the target (if any), then skip INSPECT and the box.
     if (action === ActionType.PRESS) {
+        const anchor = await focusForPress(deps, session, ref);
+        if (anchor === undefined) {
+            return synthetic(InputModeReason.TARGET_NOT_FOCUSABLE);
+        }
         try {
             const performed = await provider.perform(session.url, action, PRESS_HAS_NO_BOX, performArgs);
             if (!performed.performed) {
@@ -516,6 +555,7 @@ export async function tryRealInput(deps, session, ref, action, args) {
             // `holdMs` to — an agent checking for an armed hold-to-confirm control read `undefined`.
             return {
                 result: {
+                    ...anchor,
                     performed: true,
                     action,
                     inputMode: performed.inputMode,
@@ -557,8 +597,12 @@ export async function tryRealInput(deps, session, ref, action, args) {
         return synthetic(InputModeReason.ELEMENT_NOT_LOCATABLE);
     }
     let toBox;
-    if (action === ActionType.DRAG) {
-        const toRef = asString(inner['toRef']);
+    const toRef = asString(inner['toRef']);
+    // A drag that names only its end point moves inside the source, such as a stroke on one canvas.
+    if (action === ActionType.DRAG && toRef === undefined && performArgs.to !== undefined) {
+        toBox = box;
+    }
+    else if (action === ActionType.DRAG) {
         if (toRef === undefined) {
             return synthetic(InputModeReason.DRAG_TARGET_UNRESOLVED);
         }
@@ -614,18 +658,89 @@ export async function tryRealInput(deps, session, ref, action, args) {
     }
 }
 /**
- * The session a flow replay runs on, with a press sent to the lease's real keyboard.
+ * The session a flow replay runs on, with a press sent to the real keyboard, as `reticle_act` does.
  *
  * Replay dispatches its steps itself, not through `reticle_act`, so a recorded Tab replayed as a
  * synthetic keydown that moves no focus, and a keyboard flow that passed live drifted on replay.
- * Every other command, and a press this lease cannot drive for real, goes to the page as before.
- * A Proxy, not a copy: the session keeps private state its own methods read.
+ * The real keyboard is a lease's, or the driven browser's when a real-input provider is configured:
+ * that is `reticle verify`'s own page, where a synthetic Enter submitted no form, so a recorded
+ * "fill, press Enter" journey failed on a working app. Every other command, and a press that cannot
+ * be driven for real, goes to the page as before. A Proxy, not a copy: the session keeps private
+ * state its own methods read.
+ */
+/**
+ * A sequence with a press in it, run as the page and the keyboard would run it.
+ *
+ * Replay sends a recorded sequence as one in-page command, so a press inside it stayed a synthetic
+ * key event: a recorded "fill, press Enter" sequence submitted no form and failed on a working app.
+ * The other sub-steps still go to the page together, in order; each press goes to the real keyboard
+ * (focus, then the key), and to the page as before when the real keyboard cannot take it. The
+ * first failure is returned as the page returned it, so a stale-ref retry still finds its step.
  */
+async function sequenceWithRealPresses(deps, session, steps, timeoutMs) {
+    const share = (n) => timeoutMs === undefined ? undefined : Math.ceil((timeoutMs * n) / Math.max(1, steps.length));
+    let last = {
+        kind: 'command_result',
+        id: ReticleCommand.ACT_SEQUENCE,
+        ok: true,
+        result: {},
+    };
+    let chunk = [];
+    const flush = async () => {
+        if (0 === chunk.length) {
+            return true;
+        }
+        last = await session.command(ReticleCommand.ACT_SEQUENCE, { steps: chunk }, share(chunk.length));
+        chunk = [];
+        return last.ok;
+    };
+    for (const sub of steps) {
+        const step = asRecord(sub);
+        if (ActionType.PRESS !== step['action']) {
+            chunk.push(sub);
+            continue;
+        }
+        if (!(await flush())) {
+            return last;
+        }
+        // A click before this press can load a new page, and then the press's ref is stale. Answered as
+        // the page answers a stale ref, so the caller's retry finds the press again on the new page.
+        let real;
+        try {
+            real = await tryRealInput(deps, session, asString(step['ref']) ?? '', ActionType.PRESS, step);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (!isStaleRefError(message)) {
+                throw error;
+            }
+            return { kind: 'command_result', id: ActionType.PRESS, ok: false, error: message };
+        }
+        if (real.result === undefined) {
+            chunk.push(sub);
+            continue;
+        }
+        last = {
+            kind: 'command_result',
+            id: ActionType.PRESS,
+            ok: true,
+            result: { dispatched: true, settled: real.settled, ...asRecord(real.result) },
+        };
+    }
+    await flush();
+    return last;
+}
 export function withLeaseKeyboard(deps, session) {
-    if (deps.realInput !== undefined || deps.pool?.hasKeyboard(session.id) !== true) {
+    if (deps.realInput === undefined && deps.pool?.hasKeyboard(session.id) !== true) {
         return session;
     }
     const command = async (name, args = {}, timeoutMs) => {
+        const steps = args['steps'];
+        if (ReticleCommand.ACT_SEQUENCE === name &&
+            Array.isArray(steps) &&
+            steps.some((sub) => ActionType.PRESS === asRecord(sub)['action'])) {
+            return await sequenceWithRealPresses(deps, session, steps, timeoutMs);
+        }
         if (ReticleCommand.ACT === name && ActionType.PRESS === args['action']) {
             const ref = asString(args['ref']) ?? '';
             const real = await tryRealInput(deps, session, ref, ActionType.PRESS, args);

package/dist/surface/tools/session-ports.d.ts

@@ -55,3 +55,17 @@ export declare function suiteFixturePort(realInput: RealInputProvider | undefine
  * is the reach the boundary guard exists to ask about.
  */
 export declare function sessionMutationPort(realInput: RealInputProvider | undefined, appUrl: string | undefined): Promise<NetworkMutationPort | undefined>;
+/**
+ * The state a verify run started in, put back before each flow after the first.
+ *
+ * `reticle verify` replays every flow in ONE driven page. A flow that signs out (an auto-saved
+ * "log out" fragment, or a journey that ends on the logout link) left every later flow signed out,
+ * and each of them then failed for a reason none of them named. The leased suite path never had
+ * this: each flow boots its own context from one captured seed. This gives the single-page path
+ * the same start.
+ *
+ * Call it before each flow. It answers `undefined` to go on, or the reason the flow cannot start
+ * where the run started, which the caller reports as not proved. Nothing to capture (no driven
+ * page, no storage support) means the run goes on as before.
+ */
+export declare function flowStartState(provider: RealInputProvider | undefined, currentUrl: () => string | undefined): () => Promise<string | undefined>;

package/dist/surface/tools/session-ports.js

@@ -100,3 +100,56 @@ export async function sessionMutationPort(realInput, appUrl) {
         return undefined;
     }
 }
+/**
+ * The state a verify run started in, put back before each flow after the first.
+ *
+ * `reticle verify` replays every flow in ONE driven page. A flow that signs out (an auto-saved
+ * "log out" fragment, or a journey that ends on the logout link) left every later flow signed out,
+ * and each of them then failed for a reason none of them named. The leased suite path never had
+ * this: each flow boots its own context from one captured seed. This gives the single-page path
+ * the same start.
+ *
+ * Call it before each flow. It answers `undefined` to go on, or the reason the flow cannot start
+ * where the run started, which the caller reports as not proved. Nothing to capture (no driven
+ * page, no storage support) means the run goes on as before.
+ */
+export function flowStartState(provider, currentUrl) {
+    let first = true;
+    let saved;
+    return async () => {
+        const url = currentUrl();
+        if (first) {
+            first = false;
+            if (provider === undefined || url === undefined) {
+                return undefined;
+            }
+            try {
+                const port = await fixturePortFor(provider, url);
+                saved = port === undefined ? undefined : { state: await port.capture(), url };
+            }
+            catch {
+                saved = undefined;
+            }
+            return undefined;
+        }
+        if (saved === undefined || provider === undefined) {
+            return undefined;
+        }
+        try {
+            // Straight to the provider, not through `fixturePortFor`: its address check compares the
+            // session's recorded address with the page's, and a flow that reloaded or signed out leaves
+            // the two different while the page is the same. The provider still refuses a page it does
+            // not drive (it answers false), so nothing is restored into a stranger's page.
+            // Tabs first: a tab the previous flow opened is a second connected session otherwise.
+            await provider.closeOtherPages?.();
+            const restored = await provider.applyStorageState?.(url ?? saved.url, saved.state);
+            return true === restored
+                ? undefined
+                : 'could not put the page back in the state the run started with: no driven page matched';
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return `could not put the page back in the state the run started with: ${message}`;
+        }
+    };
+}

package/dist/surface/tools/tool-kit.d.ts

@@ -31,6 +31,12 @@ export interface ToolDeps<Ext = unknown> {
      * the fake-pool lease tests are deliberately runnable without a real Chromium.
      */
     browserProbe?: () => Promise<ChromiumProbe>;
+    /**
+     * Whether something on this loopback port accepted a connection. Asked only after a lease
+     * navigation timed out, to tell a dev server compiling its first route from no server (#2005).
+     * Optional: absent ⇒ the timeout keeps its generic advice.
+     */
+    portAccepts?: (port: number) => Promise<boolean>;
     baselines: BaselineStore;
     recordings: RecordingStore;
     /** on-disk anchored-flow store (.reticle/flows/). */

package/dist/surface/tools/tool-kit.js

@@ -156,6 +156,8 @@ export const CDP_TOOLS = new Set([
     // Breaks a request through the same Playwright route `reticle_network_mock` uses, so it fails the
     // same way under version skew and must be refused with the same sentence.
     ReticleTool.FLOW_MUTATE,
+    // Reads JS coverage through the lease's Playwright page, the way `reticle_network_mock` reaches it.
+    ReticleTool.LEASE_COVERAGE,
 ]);
 /**
  * Tools whose result hands the agent refs. The tab they were minted in is remembered, so the call
@@ -171,7 +173,6 @@ export const REF_MINTING_TOOLS = new Set([
     // The same three merged, on the `merged` surface. Its `state` action mints nothing, and
     // over-inclusion is the safe direction here: the worst case is a refusal naming two tabs.
     ReticleTool.LOOK,
-    ReticleTool.EXPLORE,
     // `crawl` mints refs for the controls it drives and `coverage` for the ones it reports untouched.
     // Both are actions on the merged verify tool now.
     ReticleTool.VERIFY,
@@ -212,11 +213,9 @@ export const SESSION_BOUND_TOOLS = new Set([
     ReticleTool.ANIMATIONS,
     ReticleTool.BASELINE, // merged save/list/diff — save+diff are live reads
     ReticleTool.RECORD, // merged start/stop — both live
-    ReticleTool.REPLAY,
     ReticleTool.CLOCK,
     ReticleTool.STATE,
     ReticleTool.STORAGE,
-    ReticleTool.EXPLORE,
     ReticleTool.SCROLL_TO,
     ReticleTool.NAVIGATE,
 ]);

package/dist/surface/tools/tool-surface.js

@@ -473,7 +473,6 @@ const OPEN_WORLD = new Set([
     ReticleTool.NAVIGATE,
     ReticleTool.SESSION,
     ReticleTool.VERIFY,
-    ReticleTool.EXPLORE,
     ReticleTool.FEEDBACK,
     ReticleTool.RUN,
 ]);