@reticlehq/server 3.9.0 → 3.10.0

package/dist/language/flows/flow-replay.js

@@ -1,22 +1,25 @@
 import { formatStepAddress } from 'open-verification';
 import { assertsState, expectLabel, expectedElementTestid, withoutClauses } from '@reticlehq/core';
 import { span } from '../../trace.js';
-import { ambiguityDrift, anchorLabel, expectElementDrift, reresolved, resolveTestid, testidDrift, } from './flow-anchor.js';
+import { ambiguityDrift, anchorLabel, expectElementDrift, refFor, reresolved, resolveTestid, testidDrift, } from './flow-anchor.js';
 export { nearestIsAmbiguous, nearestTestid, resolveQuery } from './flow-anchor.js';
 import { routeOfEvent, routeOfUrl } from '@reticlehq/engine/question/predicate/predicate-route.js';
 import { evalConsole } from '@reticlehq/engine/question/predicate/predicate-console.js';
 import { appScope, stepEffect } from '@reticlehq/engine/evidence/step-effect.js';
+import { stepContradictions } from './flow-cross-step.js';
 import { AnchorKind, DriftReason, EventType, FlowStepTool, StepEffect, PredicateKind, ReplayStatus, } from '@reticlehq/core';
 import { asString, invokedFlowMissing, isConsequenceDrift } from '@reticlehq/core';
 import { anchorFieldName } from './fields/flow-secret-field.js';
 import { degradedStepResult, isDocumentPressStep, isDegradedAnchor, runComponentStep, runRoleStep, runSequenceStep, } from './flow-step-runners.js';
 import { inFlightRequestLabels } from '../../surface/tools/act/settle-in-flight.js';
 import { namedNetIsInFlight } from '@reticlehq/engine/evidence/unsettled.js';
+import { captureBaselines } from '@reticlehq/engine/evidence/baseline.js';
 /** What a still-open named request means, in the drift's own words. */
 const IN_FLIGHT_AT_BUDGET_END = 'the request this step declared had not come back when the budget ended — it is still in flight, ' +
     'so nothing here says the app failed. Raise the step timeout, or look at the endpoint';
 import { isDocumentGoneError, SESSION_DISCONNECTED_REASON, } from '../../portal/session/facts/session-replaced.js';
 import { actOnResolvedRef } from './flow-step-runners.js';
+import { isPageStep, runPageStep } from './steps/page-steps.js';
 /**
  * The document this replay was driving went away mid-run.
  *
@@ -41,6 +44,18 @@ export class DocumentLostDuringReplay extends Error {
     }
 }
 const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/*
+ * How replay paces itself between steps. A person does not act on a screen that is still changing,
+ * and replay did: it acted the moment the last step's consequence held. An htmx row swap puts a new
+ * button in the page and binds it a moment later, so a click in between did nothing, and a correct
+ * build failed. A busy machine makes that moment longer, so the false fail came under parallel load.
+ *
+ * Quiet means no network, DOM or animation activity for `STEP_QUIET_MS`, which is shorter than any
+ * person takes to act on a changed screen. A page that never goes quiet (a poll, a spinner) gets
+ * `STEP_QUIET_BUDGET_MS` and then the step runs anyway: the wait paces replay and decides nothing.
+ */
+const STEP_QUIET_MS = 250;
+const STEP_QUIET_BUDGET_MS = 2_000;
 /**
  * The route (pathname) currently in effect — the page a step runs on. Reads the latest ROUTE_CHANGE
  * from the whole event buffer; mirrors the predicate engine's route field order (pathname → to).
@@ -58,8 +73,9 @@ function currentRoute(session) {
     // pathname is `/` on every page of a hash-routed app — so a whole desktop replay reported `/` for
     // every step. Sixth place the same reading was wrong; see routeOfEvent.
     const parts = routeOfEvent(last);
-    if (parts === undefined || 0 === parts.docPath.length)
+    if (parts === undefined || 0 === parts.docPath.length) {
         return undefined;
+    }
     return parts.routePath.length > 0 ? parts.routePath : undefined;
 }
 /** Pathname only (drop origin + query) so a net URL stays terse in the journey. */
@@ -81,19 +97,23 @@ function summarizeConsequence(events) {
     const lastRoute = events.filter((e) => e.type === EventType.ROUTE_CHANGE).at(-1);
     if (lastRoute !== undefined) {
         const routed = routeOfEvent(lastRoute);
-        if (routed !== undefined && routed.routePath.length > 0)
+        if (routed !== undefined && routed.routePath.length > 0) {
             parts.push(`→ ${routed.routePath}`);
+        }
     }
     const signals = new Set();
     for (const e of events) {
-        if (e.type !== EventType.SIGNAL)
+        if (e.type !== EventType.SIGNAL) {
             continue;
+        }
         const name = asString((e.data ?? {})['name']);
-        if (name !== undefined)
+        if (name !== undefined) {
             signals.add(name);
+        }
     }
-    for (const name of [...signals].slice(0, 2))
+    for (const name of [...signals].slice(0, 2)) {
         parts.push(`signal ${name}`);
+    }
     for (const n of events.filter((e) => e.type === EventType.NET_REQUEST).slice(0, 2)) {
         const data = n.data ?? {};
         const method = asString(data['method']) ?? 'GET';
@@ -102,8 +122,9 @@ function summarizeConsequence(events) {
         parts.push(`${method} ${path}${status}`.trim());
     }
     const errors = events.filter(isConsoleError).length;
-    if (errors > 0)
+    if (errors > 0) {
         parts.push(`${errors} console error${errors > 1 ? 's' : ''}`);
+    }
     return parts.length > 0 ? parts.join('; ') : undefined;
 }
 const isConsoleError = (e) => e.type === EventType.CONSOLE_ERROR || e.type === EventType.ERROR_UNCAUGHT;
@@ -119,8 +140,9 @@ function consoleErrorsIn(events) {
 }
 /** The console-absent clauses an expect cannot pass without: itself, or any `allOf` member. */
 function requiredConsoleAbsences(expect) {
-    if (PredicateKind.ALL_OF === expect.kind)
+    if (PredicateKind.ALL_OF === expect.kind) {
         return expect.predicates.flatMap(requiredConsoleAbsences);
+    }
     return PredicateKind.CONSOLE === expect.kind && true === expect.absent ? [expect] : [];
 }
 /**
@@ -132,8 +154,9 @@ function requiredConsoleAbsences(expect) {
 function lateConsoleDrift(expect, events) {
     for (const clause of requiredConsoleAbsences(expect)) {
         const read = evalConsole(events, clause);
-        if (read.pass)
+        if (read.pass) {
             continue;
+        }
         return {
             reasonKind: DriftReason.SIGNAL_NOT_OBSERVED,
             reason: read.failureReason ?? "the step's declared consequence did not hold",
@@ -143,6 +166,13 @@ function lateConsoleDrift(expect, events) {
     }
     return undefined;
 }
+/** A console-absent expect read over the start-page load, said as such. See `loadSince`. */
+function loadDrift(expect, loadEvents) {
+    const drift = 0 === loadEvents.length ? undefined : lateConsoleDrift(expect, loadEvents);
+    return drift === undefined
+        ? undefined
+        : { ...drift, reason: `${drift.reason}, logged while replay loaded the start page` };
+}
 /** Run one testid-anchored step: re-resolve via QUERY, then ACT on the live ref, else drift. */
 export async function runTestidStep(session, step, index, value, dynamic, confirmDangerous, sleep) {
     const { refs, hint } = await resolveTestid(session, value, sleep);
@@ -170,7 +200,8 @@ export async function runTestidStep(session, step, index, value, dynamic, confir
     if (ambiguous !== null) {
         return { step: index, tool: step.tool, anchor: value, ok: false, drift: ambiguous };
     }
-    const ref = refs[0] ?? '';
+    // The only match, or the recorded position among a shared test id (#2135).
+    const ref = refFor(step.anchor, refs) ?? '';
     /*
      * The same dispatch its siblings use, including the one re-resolve on a stale ref (2.3).
      *
@@ -186,8 +217,9 @@ export async function runTestidStep(session, step, index, value, dynamic, confir
     // The field this step types into — from the anchor, so a redacted fill can be supplied from
     // RETICLE_SECRET_<FIELD> without the flow carrying the secret.
     anchorFieldName(step.anchor), async () => reresolved(step.anchor, (await resolveTestid(session, value, sleep)).refs));
-    if (!result.ok)
+    if (!result.ok) {
         return result;
+    }
     // assert the step's expect.element testid is present AFTER the action —
     // unless that testid was marked DYNAMIC (the LLM-output case), in which case its presence/content
     // is NOT asserted (only the action ran). The skip is scoped strictly to the dynamic set.
@@ -230,7 +262,7 @@ export async function runTestidStep(session, step, index, value, dynamic, confir
  * quietly stop agreeing, and the disagreement would land as a flow that replays green against a
  * state it was never meant to run in.
  */
-export async function assertStepExpect(session, expect, waitForSignal, timeoutMs, since) {
+export async function assertStepExpect(session, expect, waitForSignal, timeoutMs, since, baselines) {
     // A testid is already asserted against the live DOM by the step runner. A role/name locator is
     // not that path — stripping every element made a recorded `until` by button name a no-op, so a
     // flow that proved the control at capture time could not go red when it was gone.
@@ -254,16 +286,19 @@ export async function assertStepExpect(session, expect, waitForSignal, timeoutMs
     (clause) => PredicateKind.ELEMENT === clause.kind &&
         clause.query.testid !== undefined &&
         true !== clause.absent);
-    if (predicate === undefined)
+    if (predicate === undefined) {
         return undefined;
-    const verdict = await waitForSignal(session, predicate, timeoutMs, since);
-    if (verdict.pass)
+    }
+    const verdict = await waitForSignal(session, predicate, timeoutMs, since, baselines);
+    if (verdict.pass) {
         return undefined;
+    }
     // The wait ended because the page stopped being observable, not because the consequence failed:
     // the same fact as a command the dying socket rejected, so it takes the same path (the replay loop
     // reports a lost document). As a drift, a socket that blinked for 26ms read as the app's defect.
-    if (true === verdict.observationLost)
+    if (true === verdict.observationLost) {
         throw new Error(SESSION_DISCONNECTED_REASON);
+    }
     // A request the step NAMED that had not come back yet is a blind spot, not an assertion the app
     // failed. The live verdict path already draws this line (namedNetIsInFlight); replay read the
     // same window and never asked, so a slow endpoint was reported as a consequence that never fired.
@@ -272,14 +307,17 @@ export async function assertStepExpect(session, expect, waitForSignal, timeoutMs
         ? []
         : inFlightRequestLabels(session.eventsSince(since), session.url, session.background);
     const namedInFlight = namedNetIsInFlight(predicate, openRequests);
+    // The store case keeps its own kind because heal and the run report branch on it; everything
+    // else is a consequence that did not hold, and the reason carries observed-vs-expected.
+    let reasonKind = DriftReason.SIGNAL_NOT_OBSERVED;
+    if (assertsState(expect)) {
+        reasonKind = DriftReason.STATE_MISMATCH;
+    }
+    else if (namedInFlight) {
+        reasonKind = DriftReason.NET_STILL_IN_FLIGHT;
+    }
     return {
-        // The store case keeps its own kind because heal and the run report branch on it; everything
-        // else is a consequence that did not hold, and the reason carries observed-vs-expected.
-        reasonKind: assertsState(expect)
-            ? DriftReason.STATE_MISMATCH
-            : namedInFlight
-                ? DriftReason.NET_STILL_IN_FLIGHT
-                : DriftReason.SIGNAL_NOT_OBSERVED,
+        reasonKind,
         reason: namedInFlight
             ? `${IN_FLIGHT_AT_BUDGET_END} (${openRequests.join(', ')})`
             : withCaseOnly(verdict.failureReason ?? "the step's declared consequence did not hold", verdict),
@@ -293,8 +331,9 @@ export async function assertStepExpect(session, expect, waitForSignal, timeoutMs
  * reading its replay needs the fix (`ignoreCase: true`, or re-record), not a bare "did not hold".
  */
 export function withCaseOnly(reason, verdict) {
-    if (true !== verdict.caseOnlyMiss)
+    if (true !== verdict.caseOnlyMiss) {
         return reason;
+    }
     const shown = verdict.wouldHold === undefined ? '' : ` ("${verdict.wouldHold}")`;
     return `${reason} — the page shows it in another case${shown}. Text checks match case exactly: if any case is meant, add ignoreCase: true to this check, or re-record the flow.`;
 }
@@ -310,8 +349,9 @@ async function runSignalStep(session, step, index, name, waitForSignal, signalTi
     // cross-flow false green on the exact suite-verify path the regression-cost claim rests on. The
     // replay-start floor excludes prior flows/runs while still seeing this run's adjacent-step signal.
     const verdict = await waitForSignal(session, { kind: PredicateKind.SIGNAL, name }, signalTimeoutMs, since);
-    if (verdict.pass)
+    if (verdict.pass) {
         return { step: index, tool: step.tool, anchor: name, ok: true };
+    }
     return {
         step: index,
         tool: step.tool,
@@ -332,11 +372,13 @@ async function runSignalStep(session, step, index, name, waitForSignal, signalTi
  * is not setup, it is a second charge, a second email, a second record.
  */
 export function resumeIndex(from, steps) {
-    if (from === undefined)
+    if (from === undefined) {
         return 0;
+    }
     const at = 'number' === typeof from ? from : steps.findIndex((step) => step.id === from);
-    if (at < 0 || at >= steps.length || !Number.isInteger(at))
+    if (at < 0 || at >= steps.length || !Number.isInteger(at)) {
         return undefined;
+    }
     return steps.slice(0, at).some((step) => StepEffect.COMMITS === step.effect) ? 0 : at;
 }
 /**
@@ -351,8 +393,9 @@ export function replayWindow(args) {
 }
 /** A part-way replay's status, from the steps it drove. */
 export function partialStatus(steps) {
-    if (steps.some((step) => step.drift !== undefined))
+    if (steps.some((step) => step.drift !== undefined)) {
         return ReplayStatus.DRIFT;
+    }
     return steps.every((step) => step.ok) ? ReplayStatus.OK : ReplayStatus.ERROR;
 }
 /** The `from` argument, narrowed: a step index or a step id. */
@@ -361,8 +404,9 @@ export function resumeArg(raw) {
 }
 /** Why `from` cannot be resumed at, or undefined when it can (or was not given). */
 export function unresolvedResume(from, steps) {
-    if (resumeIndex(from, steps) !== undefined)
+    if (resumeIndex(from, steps) !== undefined) {
         return undefined;
+    }
     return `cannot resume at ${JSON.stringify(from)}: this flow has ${String(steps.length)} step(s) and no step by that id`;
 }
 /**
@@ -446,31 +490,70 @@ export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs,
     };
     try {
         for (const step of flow.steps) {
-            if (options.to !== undefined && index >= options.to)
+            if (options.to !== undefined && index >= options.to) {
                 break;
+            }
             if (options.at !== undefined && index < options.at) {
                 index += 1;
                 continue;
             }
+            if (index > (options.at ?? 0)) {
+                await waitForSignal(session, { kind: PredicateKind.SETTLED, quietMs: STEP_QUIET_MS }, STEP_QUIET_BUDGET_MS);
+            }
             if (step.invoke !== undefined) {
                 results.push(await runInvokeStep(session, flow, step, index, waitForSignal, signalTimeoutMs, confirmDangerous, sleep, options, index < from));
                 const last = results[results.length - 1];
-                if (last !== undefined && index < from && last.ok)
+                if (last !== undefined && index < from && last.ok) {
                     results.pop();
+                }
                 tell(last);
-                if (last !== undefined && false === last.ok)
+                if (last !== undefined && false === last.ok) {
+                    break;
+                }
+                index += 1;
+                continue;
+            }
+            if (isPageStep(step)) {
+                const ran = await runPageStep(step, index, {
+                    open: options.navigate,
+                    send: options.request,
+                    checked: index >= from,
+                    confirmDangerous,
+                    // A navigated page's clock starts at its own connect, so its whole life is the window.
+                    judge: (on, expectation) => assertStepExpect(on, expectation, waitForSignal, waitFor(step), 0),
+                    route: currentRoute,
+                });
+                const result = ran.result;
+                if (ran.session !== undefined) {
+                    // The page that asked for the load is gone; every later step runs on the one that loaded.
+                    session = ran.session;
+                }
+                if (index < from && result.ok && result.drift === undefined) {
+                    index += 1;
+                    continue;
+                }
+                if (index < from) {
+                    result.note = `setup step for resuming at step ${String(from)} failed`;
+                }
+                await options.onStepResult?.(result, flow.name).catch(() => undefined);
+                results.push(result);
+                tell(result);
+                if (!result.ok || result.drift !== undefined) {
                     break;
+                }
                 index += 1;
                 continue;
             }
             const label = anchorLabel(step.anchor);
             /** One sub-step's expect, over the window that sub-step opened. See runSequenceStep. */
-            const judgeSubStep = async (expectation, since) => (await assertStepExpect(session, expectation, waitForSignal, waitFor(step), since)) ??
+            const budget = waitFor(step);
+            const judgeSubStep = async (expectation, since, before) => (await assertStepExpect(session, expectation, waitForSignal, budget, since, before)) ??
                 lateConsoleDrift(expectation, session.eventsSince(since).filter((e) => e.t >= since));
             // The page this step runs on (the journey's "which page") — captured before the action.
             const page = currentRoute(session);
-            // Event-time floor so the consequence reflects only THIS step's aftermath, not prior steps'.
+            // This step's event-time floor, and (as act_and_wait) what `unchanged` and kin compare with.
             const cursorBefore = session.elapsed();
+            const baselines = index < from ? undefined : await captureBaselines(session, step.expect);
             const subSteps = step.steps;
             // Traced per step, so a slow replay says WHICH step and which anchor kind spent the time. The
             // per-step `durationMs` below is what the agent gets back; this is what a developer profiling
@@ -493,9 +576,12 @@ export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs,
                 if (step.anchor.kind === AnchorKind.COMPONENT) {
                     return runComponentStep(session, step, index, step.anchor, confirmDangerous, sleep);
                 }
-                if (step.anchor.kind === AnchorKind.ROLE && step.anchor.name !== undefined) {
-                    // A NAMED role anchor addresses one element. The nameless one is the degraded placeholder
-                    // and keeps its old path, where it fails legibly rather than querying a role as a testid.
+                if (step.anchor.kind === AnchorKind.ROLE) {
+                    // Named or nameless, a role anchor resolves by role. The degraded placeholder and the
+                    // document-key press were handled above, so what reaches here addresses a real control:
+                    // a nameless one (an icon-only button) by its position among nameless controls of its
+                    // role. It used to fall through to the testid path, which queried the ROLE as a testid
+                    // and answered `testid "button" not found` on a working page.
                     return runRoleStep(session, step, index, step.anchor, confirmDangerous, sleep);
                 }
                 return runTestidStep(session, step, index, label, dynamic, confirmDangerous, sleep);
@@ -516,30 +602,40 @@ export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs,
             // A setup step's consequence is not checked: it is re-driven to get somewhere, not to prove it.
             const checked = index < from ? [] : own;
             for (const expectation of checked) {
-                if (!result.ok || result.drift !== undefined)
+                if (!result.ok || result.drift !== undefined) {
                     break;
-                const expectDrift = await assertStepExpect(session, expectation, waitForSignal, waitFor(step), cursorBefore);
+                }
+                const expectDrift = await assertStepExpect(session, expectation, waitForSignal, waitFor(step), cursorBefore, baselines);
                 if (expectDrift !== undefined) {
                     result.ok = false;
                     result.drift = expectDrift;
                 }
             }
-            if (page !== undefined)
+            if (page !== undefined) {
                 result.page = page;
+            }
             const endPage = currentRoute(session);
-            if (endPage !== undefined && endPage !== page)
+            if (endPage !== undefined && endPage !== page) {
                 result.endPage = endPage;
+            }
             const windowEvents = session.eventsSince(cursorBefore).filter((e) => e.t >= cursorBefore);
+            const loadSince = 0 === index ? options.loadSince : undefined;
+            const loadEvents = loadSince === undefined
+                ? []
+                : session.eventsSince(loadSince).filter((e) => e.t < cursorBefore);
             const consequence = summarizeConsequence(windowEvents);
-            if (consequence !== undefined)
+            if (consequence !== undefined) {
                 result.consequence = consequence;
+            }
             const consoleErrors = consoleErrorsIn(windowEvents);
-            if (consoleErrors !== undefined)
+            if (consoleErrors !== undefined) {
                 result.consoleErrors = consoleErrors;
+            }
             for (const expectation of checked) {
-                if (!result.ok || result.drift !== undefined)
+                if (!result.ok || result.drift !== undefined) {
                     break;
-                const late = lateConsoleDrift(expectation, windowEvents);
+                }
+                const late = lateConsoleDrift(expectation, windowEvents) ?? loadDrift(expectation, loadEvents);
                 if (late !== undefined) {
                     result.ok = false;
                     result.drift = late;
@@ -551,9 +647,21 @@ export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs,
             const cursorAfter = session.elapsed();
             // ONE builder, shared with the live act path, so a driven step and a replayed one describe what
             // happened in identical words rather than in two vocabularies that agree by coincidence.
-            Object.assign(result, stepEffect(windowEvents, { since: cursorBefore, until: cursorAfter }, 
-            // A failure the step declared is its expected result, as it is on the live path.
-            { ...appScope(session), declared }));
+            const effect = stepEffect(windowEvents, { since: cursorBefore, until: cursorAfter }, 
+            // A failure the step declared is its expected result, as it is on the live path. The reads
+            // that finished before the step let a background read that fails on every tick be left
+            // alone, instead of being blamed on each step it happens to fall inside.
+            {
+                ...appScope(session),
+                declared,
+                before: session
+                    .eventsSince(0)
+                    .filter((e) => e.t < cursorBefore && e.type === EventType.NET_REQUEST),
+            });
+            // "Never settled" is decided once the replay is over, by the whole-span pass (flow-cross-step).
+            const stepOwn = stepContradictions(effect.contradictions ?? []);
+            delete effect.contradictions;
+            Object.assign(result, effect, 0 === stepOwn.length ? {} : { contradictions: stepOwn });
             /*
              * A prefix step is setup and is not reported -- UNLESS it failed.
              *
@@ -563,14 +671,16 @@ export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs,
              */
             // `tool` is dropped HERE rather than at the ten places that set it, so a new step runner cannot
             // forget the rule and quietly re-introduce the cost. Spelled out only when it is NOT the default.
-            if (FlowStepTool.ACT === result.tool)
+            if (FlowStepTool.ACT === result.tool) {
                 delete result.tool;
+            }
             if (index < from && result.ok && result.drift === undefined) {
                 index += 1;
                 continue;
             }
-            if (index < from)
+            if (index < from) {
                 result.note = `setup step for resuming at step ${String(from)} failed`;
+            }
             await options.onStepResult?.(result, flow.name).catch(() => undefined);
             results.push(result);
             tell(result);
@@ -579,14 +689,21 @@ export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs,
             const sweepPast = true === options.sweep &&
                 result.drift !== undefined &&
                 isConsequenceDrift(result.drift.reasonKind);
-            if (!sweepPast && (result.drift !== undefined || !result.ok))
+            if (!sweepPast && (result.drift !== undefined || !result.ok)) {
                 break;
+            }
             index += 1;
         }
+        // And once after the last step: a page can satisfy the last expect at once and finish its own
+        // work after (a sort header marks itself, then fetches the rows). The journey is judged next.
+        if (results.length > 0) {
+            await waitForSignal(session, { kind: PredicateKind.SETTLED, quietMs: STEP_QUIET_MS }, STEP_QUIET_BUDGET_MS);
+        }
     }
     catch (error) {
-        if (!isDocumentGoneError(error))
+        if (!isDocumentGoneError(error)) {
             throw error;
+        }
         throw new DocumentLostDuringReplay(results, index, error);
     }
     return results;

package/dist/language/flows/flow-replayable.js

@@ -53,6 +53,9 @@ function relax(predicate, money) {
     }
     if (PredicateKind.TEXT === predicate.kind &&
         predicate.satisfies === undefined &&
+        // An absent count stays exact: made word-level, it says no count is on the page, and a page
+        // that shows another count fails it.
+        true !== predicate.absent &&
         predicate.contains !== undefined &&
         HAS_NUMBER.test(predicate.contains)) {
         const relaxed = wordLevel(predicate.contains, money);
@@ -143,7 +146,10 @@ export function replayability(flow) {
                 (AnchorKind.ROLE === anchor?.kind && DEGRADED_ANCHOR_ROLE === anchor.role))) {
             blocked.push(`step ${at} has no anchor a replay can find`);
         }
-        else if (own && AnchorKind.TESTID === anchor?.kind && anchor.of !== undefined) {
+        else if (own &&
+            AnchorKind.TESTID === anchor?.kind &&
+            anchor.of !== undefined &&
+            anchor.nth === undefined) {
             blocked.push(`step ${at} anchors on test id '${anchor.value}', which ${String(anchor.of)} elements share`);
         }
         if (own &&

package/dist/language/flows/flow-start-path.d.ts

@@ -33,9 +33,15 @@ export interface StartPathArrival {
     redirected?: string;
     /** Set when the page's loading kept replay waiting past the step budget. */
     wait?: StartPageWait;
+    /** Set when the flow declares a route and replay could not put the tab on it: nothing may run (#2034). */
+    unreached?: string;
 }
 /** The replay result, with how long replay waited for its start page when that went past the budget. */
 export declare function withStartPageWait<R extends FlowReplayResult>(result: R, arrival: StartPathArrival): R;
+/** Record where a replay left the tab, so the next reset does not keep that flow's query. */
+export declare function noteReplayEnded(session: StartPathSession & {
+    id: string;
+}): void;
 /**
  * Replay's half of the FlowFile contract: put the tab on the flow's `startPath` before step 1, and
  * RELOAD it if it is already there.
@@ -50,6 +56,10 @@ export declare function withStartPageWait<R extends FlowReplayResult>(result: R,
  * or from the wrong page. Silence is not an opt-out: a flow that depends on leftovers without
  * saying so is a flow whose green means nothing on a fresh machine, and CI is a fresh machine.
  *
+ * A route in `requires` is not an opt-out. It is the page the flow needs, and replay goes there:
+ * see `arriveAtDeclaredRoute`. A suite ran such a flow on the page the previous flow left open,
+ * and its anchors then failed, or matched ambiguously, on an unrelated page (#2034).
+ *
  * A full-page load tears down the session socket, so the navigation must happen here — before any
  * step runs — and the replay continues on the session the SDK reconnects as (found via the same
  * tombstone rebind that lets `resolve(oldId)` answer after any navigation). Best-effort by design:
@@ -63,6 +73,11 @@ export declare function arriveAtStartPath(sessions: SessionManager, session: Sta
 }, flow: FlowFile, timeoutMs?: number, clock?: ArrivalClock, 
 /** Whether the tab is still loading. Replay passes one for a pool lease, the only tab it can ask. */
 stillLoading?: () => Promise<boolean>, loadingCapMs?: number): Promise<StartPathArrival>;
+/**
+ * The arrival for a replay that continues at a step and so does not move the tab. A declared route
+ * claim must still hold where the tab is, as it did when it was a precondition the run checked.
+ */
+export declare function routeClaimsWhereTheTabIs(flow: FlowFile, session: StartPathSession): StartPathArrival;
 /**
  * Send a tab somewhere and wait for the session that comes back.
  *
@@ -95,14 +110,28 @@ export type NavigateOutcome = {
     stillLoading: boolean;
     wait?: StartPageWait;
 };
+/**
+ * Whether assigning `to` from `from` is a jump within the same document. That is the case when the
+ * URLs differ at most in the fragment and `to` has a fragment; a browser then loads no page. Without
+ * a fragment, the same URL reloads by itself. Undefined or unparsable URLs are not a jump.
+ */
+export declare function isFragmentJump(from: string | undefined, to: string): boolean;
 export declare function navigateAndAwait(sessions: SessionManager, session: {
     id: string;
     /** Optional because a session's URL is, and `carryReticleIdentity` already handles its absence. */
     url?: string;
     command(name: string, args?: Record<string, unknown>): Promise<CommandResult>;
-}, destination: string, expectedPath: string, timeoutMs: number, clock?: ArrivalClock, 
-/** True when the destination is the page we are already on — see `arrivedSuccessor`. */
-isReload?: boolean, 
-/** Whether the navigated page is still loading; absent when it cannot be asked. */
-stillLoading?: () => Promise<boolean>, loadingCapMs?: number): Promise<NavigateOutcome>;
+}, destination: string, expectedPath: string, timeoutMs: number, clock?: ArrivalClock, options?: {
+    /** True when the destination is the page we are already on — see `arrivedSuccessor`. */
+    isReload?: boolean;
+    /** Whether the navigated page is still loading; absent when it cannot be asked. */
+    stillLoading?: () => Promise<boolean>;
+    loadingCapMs?: number;
+    /**
+     * Accept the first NEW page at once, on any path. A flow's `navigate` step opens a URL the
+     * server may redirect (a paused short link goes to `/404`), and the page that connects is the
+     * destination. Start-page arrival leaves this off: it waits for its own path first.
+     */
+    acceptRedirect?: boolean;
+}): Promise<NavigateOutcome>;
 export {};