@reticlehq/server 3.5.0 → 3.6.0

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

@@ -1,11 +1,12 @@
 import { formatStepAddress } from 'open-verification';
 import { assertsState, expectLabel, expectedElementTestid, withoutClauses } from '@reticlehq/core';
 import { span } from '../../trace.js';
-import { anchorLabel, expectElementDrift, resolveTestid, testidDrift, ambiguousAnchorDrift, } from './flow-anchor.js';
+import { ambiguityDrift, anchorLabel, expectElementDrift, 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 { stepEffect } from '@reticlehq/engine/evidence/step-effect.js';
-import { AnchorKind, DriftReason, EventType, FlowStepTool, StepEffect, PredicateKind, } from '@reticlehq/core';
+import { AnchorKind, DriftReason, EventType, FlowStepTool, StepEffect, PredicateKind, ReplayStatus, } from '@reticlehq/core';
 import { asString, isConsequenceDrift } from '@reticlehq/core';
 import { anchorFieldName } from './fields/flow-secret-field.js';
 import { degradedStepResult, isDegradedAnchor, runComponentStep, runRoleStep, runSequenceStep, } from './flow-step-runners.js';
@@ -100,11 +101,48 @@ function summarizeConsequence(events) {
         const status = 'number' === typeof data['status'] ? ` ${data['status']}` : '';
         parts.push(`${method} ${path}${status}`.trim());
     }
-    const errors = events.filter((e) => e.type === EventType.CONSOLE_ERROR || e.type === EventType.ERROR_UNCAUGHT).length;
+    const errors = events.filter(isConsoleError).length;
     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;
+/** At most this many console errors travel on one step; its `digest` still counts them all. */
+const CONSOLE_ERRORS_PER_STEP = 5;
+/** The console errors a step's window saw, for the run artifact's evidence. See FlowStepResult. */
+function consoleErrorsIn(events) {
+    const errors = events
+        .filter(isConsoleError)
+        .slice(0, CONSOLE_ERRORS_PER_STEP)
+        .map((e) => ({ level: e.type, message: asString(e.data['message']) ?? '', at: e.t }));
+    return errors.length > 0 ? errors : undefined;
+}
+/** The console-absent clauses an expect cannot pass without: itself, or any `allOf` member. */
+function requiredConsoleAbsences(expect) {
+    if (PredicateKind.ALL_OF === expect.kind)
+        return expect.predicates.flatMap(requiredConsoleAbsences);
+    return PredicateKind.CONSOLE === expect.kind && true === expect.absent ? [expect] : [];
+}
+/**
+ * A console-absent expect, read again over the step's WHOLE window.
+ *
+ * The wait that graded the expect ends before the window does, so an error landing between the two
+ * was counted by the step's consequence and missed by its verdict (#1344). The window wins.
+ */
+function lateConsoleDrift(expect, events) {
+    for (const clause of requiredConsoleAbsences(expect)) {
+        const read = evalConsole(events, clause);
+        if (read.pass)
+            continue;
+        return {
+            reasonKind: DriftReason.SIGNAL_NOT_OBSERVED,
+            reason: read.failureReason ?? "the step's declared consequence did not hold",
+            anchor: expectLabel(expect),
+            nearest: null,
+        };
+    }
+    return undefined;
+}
 /** 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);
@@ -124,17 +162,13 @@ export async function runTestidStep(session, step, index, value, dynamic, confir
      * reads `drift` and `ok` and never reads a note, so "we guessed which element you meant" was
      * indistinguishable from "it did what it did before" -- the one claim a replay makes.
      *
-     * The action is NOT dispatched. Acting and then reporting drift would leave the app changed by
-     * a click nobody can attribute, which is worse than the ambiguity it reports.
+     * The record itself comes from `ambiguityDrift`, shared with the role and component runners: this
+     * anchor kind was the first to get the rule, and writing it inline is how the other two came to
+     * answer the same question differently.
      */
-    if (refs.length > 1) {
-        return {
-            step: index,
-            tool: step.tool,
-            anchor: value,
-            ok: false,
-            drift: ambiguousAnchorDrift(value, refs.length),
-        };
+    const ambiguous = ambiguityDrift(step.anchor, refs);
+    if (ambiguous !== null) {
+        return { step: index, tool: step.tool, anchor: value, ok: false, drift: ambiguous };
     }
     const ref = refs[0] ?? '';
     /*
@@ -146,15 +180,12 @@ export async function runTestidStep(session, step, index, value, dynamic, confir
      * so the kind most likely to appear in a real flow was the kind without the cure.
      *
      * The re-resolve keeps the ambiguity rule above: more than one match is drift, never a guess, so
-     * it hands back a ref only when the locator still names exactly one element.
+     * it reports an `anchor_ambiguous` drift rather than handing back the first of the new matches.
      */
     const result = await actOnResolvedRef(session, step, index, value, ref, confirmDangerous, 
     // 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 () => {
-        const again = await resolveTestid(session, value, sleep);
-        return 1 === again.refs.length ? again.refs[0] : undefined;
-    });
+    anchorFieldName(step.anchor), async () => reresolved(step.anchor, (await resolveTestid(session, value, sleep)).refs));
     if (!result.ok)
         return result;
     // assert the step's expect.element testid is present AFTER the action —
@@ -297,6 +328,19 @@ export function resumeIndex(from, steps) {
         return undefined;
     return steps.slice(0, at).some((step) => StepEffect.COMMITS === step.effect) ? 0 : at;
 }
+/** How far a replay drives: `to` stops before a step, `at` picks up at one. Positive indices only. */
+export function replayWindow(args) {
+    const index = (raw) => 'number' === typeof raw && Number.isInteger(raw) && 0 < raw ? raw : undefined;
+    const to = index(args['to']);
+    const at = index(args['at']);
+    return { ...(to === undefined ? {} : { to }), ...(at === undefined ? {} : { at }) };
+}
+/** A part-way replay's status, from the steps it drove. */
+export function partialStatus(steps) {
+    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. */
 export function resumeArg(raw) {
     return 'number' === typeof raw || ('string' === typeof raw && raw.length > 0) ? raw : undefined;
@@ -342,7 +386,8 @@ async function runInvokeStep(session, flow, step, index, waitForSignal, signalTi
     }
     // `from` is an offset into the CALLER's steps. A sub-journey invoked from the setup prefix runs
     // whole and unchecked (from = its length); one invoked at or after the resume point runs normally.
-    const { from: _outer, ...rest } = options;
+    // Nor the progress callback: a sub-flow's steps are one step of the flow the chip is drawing.
+    const { from: _outer, onStep: _progress, to: _to, at: _at, ...rest } = options;
     const carried = setup ? { ...rest, from: sub.steps.length } : rest;
     const nested = await replayFlow(session, sub, waitForSignal, signalTimeoutMs, confirmDangerous, sleep, {
         ...carried,
@@ -377,13 +422,28 @@ export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs,
     // wait for the slowest step would trade a false red for a slow suite. See FlowStep.timeoutMs.
     const waitFor = (step) => step.timeoutMs ?? flow.signalTimeoutMs ?? signalTimeoutMs;
     let index = 0;
+    const tell = (result) => {
+        try {
+            options.onStep?.(index + 1, flow.steps.length, true === result?.ok && result.drift === undefined);
+        }
+        catch {
+            /* progress is a picture of the replay, never a reason to stop it */
+        }
+    };
     try {
         for (const step of flow.steps) {
+            if (options.to !== undefined && index >= options.to)
+                break;
+            if (options.at !== undefined && index < options.at) {
+                index += 1;
+                continue;
+            }
             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)
                     results.pop();
+                tell(last);
                 if (last !== undefined && false === last.ok)
                     break;
                 index += 1;
@@ -459,6 +519,18 @@ export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs,
             const consequence = summarizeConsequence(windowEvents);
             if (consequence !== undefined)
                 result.consequence = consequence;
+            const consoleErrors = consoleErrorsIn(windowEvents);
+            if (consoleErrors !== undefined)
+                result.consoleErrors = consoleErrors;
+            for (const expectation of checked) {
+                if (!result.ok || result.drift !== undefined)
+                    break;
+                const late = lateConsoleDrift(expectation, windowEvents);
+                if (late !== undefined) {
+                    result.ok = false;
+                    result.drift = late;
+                }
+            }
             // Per-step wall time is NOT shipped: it is `window.until - window.since`, computed from two numbers
             // the next line already puts in the same object, under the same emission condition. A step used to
             // carry the subtraction AND both operands, on every step of every replay.
@@ -484,6 +556,7 @@ export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs,
             if (index < from)
                 result.note = `setup step for resuming at step ${String(from)} failed`;
             results.push(result);
+            tell(result);
             // Under `sweep`, a failure whose action still RAN does not stop the run — the page is where the
             // step left it, so the next step is as meaningful as it was going to be. Anything else halts.
             const sweepPast = true === options.sweep &&

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

@@ -27,7 +27,11 @@ export function buildFlowChips(flows, sessionProjectId) {
         const start = first !== undefined && first.anchor.kind === AnchorKind.TESTID
             ? first.anchor.value
             : undefined;
-        chips.push(start === undefined ? { name: flow.name } : { name: flow.name, start });
+        chips.push({
+            name: flow.name,
+            createdAt: flow.createdAt,
+            ...(start === undefined ? {} : { start }),
+        });
     }
     return chips;
 }

package/dist/language/flows/flow-step-runners.d.ts

@@ -1,5 +1,6 @@
-import { AnchorKind, type FlowAnchor, type FlowStep, type FlowStepResult, type Predicate } from '@reticlehq/core';
+import { AnchorKind, type FlowAnchor, type FlowReplayResult, type FlowStep, type FlowStepResult, type Predicate } from '@reticlehq/core';
 import type { FlowReplaySession, Sleep } from './flow-replay-types.js';
+import { type Reresolved } from './flow-anchor.js';
 export declare function runRoleStep(session: FlowReplaySession, step: FlowStep, index: number, anchor: Extract<FlowAnchor, {
     kind: typeof AnchorKind.ROLE;
 }>, confirmDangerous: boolean, sleep: Sleep): Promise<FlowStepResult>;
@@ -19,8 +20,11 @@ field?: string,
  * found, and the retry below is worthless without it: re-dispatching the SAME dead ref fails
  * identically. What changed between the two attempts is the DOM, so the locator has to be run
  * against it again.
+ *
+ * It reports WHAT it found, not just a ref: see `Reresolved`. A re-render that turns one match into
+ * three is a drift, and the caller is the only layer that can say so with the right anchor in hand.
  */
-reresolve?: () => Promise<string | undefined>): Promise<FlowStepResult>;
+reresolve?: () => Promise<Reresolved | undefined>): Promise<FlowStepResult>;
 /** Run one component-anchored step: re-resolve via QUERY by:'component', ACT on the live ref, else drift. */
 export declare function runComponentStep(session: FlowReplaySession, step: FlowStep, index: number, anchor: Extract<FlowAnchor, {
     kind: typeof AnchorKind.COMPONENT;
@@ -55,6 +59,20 @@ export declare function anchorQueryArgs(anchor: FlowAnchor): Record<string, unkn
  * flow's own `requires` holds. No tool writes `requires`, so the reset's hint hands over this line.
  */
 export declare function anchorPrecondition(anchor: FlowAnchor): Predicate | undefined;
+/**
+ * The honest answer when a step's target kept going stale.
+ *
+ * Replay looks the element up again and goes on while that gets it further, so a step still stale
+ * after that is one the page re-rendered around faster than it could be targeted. Reporting it as
+ * `error` with the browser's own sentence says "your app broke", which is a claim nothing observed
+ * and sends a reader into product code that is fine. It is the same bucket as a document that went
+ * away: the steps before it are real and are attached, the step that could not be acted on is among
+ * them with its index, and nothing after it ran.
+ *
+ * Left alone, so the ordinary verdict stands, when anything else is in the run: a drifted anchor is
+ * drift whatever else happened, and a failure that is not staleness is a failure.
+ */
+export declare function staleTargetResult(name: string, steps: readonly FlowStepResult[]): FlowReplayResult | undefined;
 /**
  * Run an act_sequence step: resolve every sub-step's OWN anchor, then dispatch the whole thing as one
  * ACT_SEQUENCE — the same shape `replayProgram` already uses, so a recorded sequence and a saved one

package/dist/language/flows/flow-step-runners.js

@@ -7,13 +7,13 @@
  * or a step's events land in the wrong window depending on how it was addressed.
  */
 import { expectedElementTestid } from '@reticlehq/core';
-import { AnchorKind, DEGRADED_ANCHOR_ROLE, DriftReason, PredicateKind, QueryBy, ReticleCommand, } from '@reticlehq/core';
+import { AnchorKind, DEGRADED_ANCHOR_ROLE, DriftReason, PredicateKind, QueryBy, ReplayStatus, ReticleCommand, } from '@reticlehq/core';
 import { ReticleTool } from '@reticlehq/core';
 import { replayActionArgs } from './replay.js';
 import { isStaleRefError } from '../../surface/tools/act/act-sequence-retry.js';
 import { waitForReaction } from '../../surface/tools/act/react-grace.js';
 import { anchorFieldName } from './flows.js';
-import { anchorLabel, componentLabel, componentQueryArgs, expectElementDrift, resolveQuery, testidDrift, } from './flow-anchor.js';
+import { ambiguityDrift, refFor, anchorLabel, componentLabel, componentQueryArgs, expectElementDrift, reresolved, resolveQuery, testidDrift, } from './flow-anchor.js';
 import { nearestRoleName } from './role-anchor-nearest.js';
 import { roleDriftReason } from '../../judgement/outcome/role-drift-reason.js';
 /** Query args for a NAMED role anchor — the handle that identifies an instance, not a JSX site. */
@@ -63,7 +63,25 @@ async function nearestRoleNameOnPage(session, anchor) {
 export async function runRoleStep(session, step, index, anchor, confirmDangerous, sleep) {
     const label = `${anchor.role} "${String(anchor.name)}"`;
     const { refs } = await resolveQuery(session, roleQueryArgs(anchor), sleep);
-    const ref = refs[0];
+    /*
+     * More than one match is DRIFT, not a guess. This path took `refs[0]`, dispatched, and returned
+     * `ok: true`, so a flow recorded against "View result" on row 3 of a table replayed by clicking row
+     * 1 and PASSED whenever every row shared the consequence (the same GET returning 200). The verdict
+     * reads `drift` and `ok` and nothing else, so a green here is indistinguishable from a replay that
+     * did what it did before.
+     *
+     * A role+name anchor is MORE likely to land here than a testid is: `button "View result"` is
+     * user-visible text, and a table repeats it by nature, so several matches is the expected shape of
+     * a recorded row action rather than an accident.
+     *
+     * The check itself lives in `ambiguityDrift`, shared with the testid and component runners: written
+     * per-runner, this rule got applied to two anchor kinds and forgotten for the third.
+     */
+    const ambiguous = ambiguityDrift(anchor, refs);
+    if (ambiguous !== null) {
+        return { step: index, tool: step.tool, anchor: label, ok: false, drift: ambiguous };
+    }
+    const ref = refFor(anchor, refs);
     if (ref === undefined) {
         // `nearest` used to be the literal null, so heal answered "no nearest match cleared the
         // confidence floor" for EVERY role-anchored drift — a structural limit reported as a judgement
@@ -86,8 +104,15 @@ export async function runRoleStep(session, step, index, anchor, confirmDangerous
         };
     }
     return await actOnResolvedRef(session, step, index, label, ref, confirmDangerous, anchorFieldName(anchor), 
-    // The retry's whole point: run the SAME locator against the DOM as it is now.
-    async () => (await resolveQuery(session, roleQueryArgs(anchor), sleep)).refs[0]);
+    /*
+     * The retry's whole point: run the SAME locator against the DOM as it is now.
+     *
+     * It reports WHAT it found, not just a ref. A re-render can turn an unambiguous anchor into an
+     * ambiguous one between the two dispatches, and dispatching at the first of the new matches would
+     * re-make the guess the check above exists to refuse — one layer deeper, where the caller cannot
+     * see it. `reresolved` is the same rule as that check, so the two cannot disagree.
+     */
+    async () => reresolved(anchor, (await resolveQuery(session, roleQueryArgs(anchor), sleep)).refs));
 }
 /**
  * `assertActionAllowed`'s refusal — "potentially destructive action blocked; retry with
@@ -131,6 +156,9 @@ field,
  * found, and the retry below is worthless without it: re-dispatching the SAME dead ref fails
  * identically. What changed between the two attempts is the DOM, so the locator has to be run
  * against it again.
+ *
+ * It reports WHAT it found, not just a ref: see `Reresolved`. A re-render that turns one match into
+ * three is a drift, and the caller is the only layer that can say so with the right anchor in hand.
  */
 reresolve) {
     const dispatch = async (at) => {
@@ -167,8 +195,24 @@ reresolve) {
             sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
         });
         const fresh = await reresolve();
+        /*
+         * The re-render turned one match into SEVERAL, so there is nothing to dispatch at and the answer
+         * is a drift — the same `anchor_ambiguous` the first resolution would have given, reported for the
+         * same reason.
+         *
+         * The staleness this retry exists to absorb is a different diagnosis with a different fix, and
+         * this used to be the only one reported: the step came back as `{ok: false, error: "ref 'e-orig'
+         * no longer resolves to an element"}` — a sentence about an element that is GONE, sent for an
+         * element that is now three. An agent reading it goes hunting for a rename, or re-records the
+         * flow, when the actual fix is a narrower anchor. Telling the two apart is what `Reresolved` is
+         * for, and the reason `ANCHOR_AMBIGUOUS` exists as its own kind rather than folding into "not
+         * found".
+         */
+        if (fresh !== undefined && 'drift' in fresh) {
+            return { step: index, tool: step.tool, anchor: label, ok: false, drift: fresh.drift };
+        }
         if (fresh !== undefined)
-            act = await dispatch(fresh);
+            act = await dispatch(fresh.ref);
     }
     const result = { step: index, tool: step.tool, anchor: label, ok: act.ok };
     if (!act.ok)
@@ -195,10 +239,28 @@ export async function runComponentStep(session, step, index, anchor, confirmDang
             },
         };
     }
+    /*
+     * Several matches is DRIFT here too, and this runner is where the rule was MISSING.
+     *
+     * The other two runners check it (through `ambiguityDrift`); this one took `refs[0]`, dispatched and
+     * returned `ok: true`. `by: QueryBy.COMPONENT` matches by component NAME, and a component rendered
+     * once per row — a table's action button, a card's menu — matches as many times as there are rows.
+     * So the guessed-green shape is not an edge case for this anchor kind, it is its ordinary one, and
+     * it is the exact defect #1227 describes: a click on the wrong element reported as a pass because
+     * the verdict reads `drift` and `ok` and never reads which element was hit.
+     */
+    const ambiguous = ambiguityDrift(anchor, refs);
+    if (ambiguous !== null) {
+        return { step: index, tool: step.tool, anchor: label, ok: false, drift: ambiguous };
+    }
     const ref = refs[0] ?? '';
     // Shared with the role path so both get the same action window AND the same stale-ref retry —
     // this used to dispatch inline, which is how one anchor kind could gain a fix the other lacked.
-    return await actOnResolvedRef(session, step, index, label, ref, confirmDangerous, anchorFieldName(anchor), async () => (await resolveQuery(session, componentQueryArgs(anchor), sleep)).refs[0]);
+    return await actOnResolvedRef(session, step, index, label, ref, confirmDangerous, anchorFieldName(anchor), 
+    // Same rule one layer deeper, same helper: a re-render that turns one match into three must not
+    // be dispatched at either, and it must say so as a drift rather than as a dead ref. This callback
+    // used to return `refs[0]` unconditionally.
+    async () => reresolved(anchor, (await resolveQuery(session, componentQueryArgs(anchor), sleep)).refs));
 }
 /**
  * DEGRADED_ANCHOR_ROLE is a MARKER ("no anchor could be determined"), never a locator.
@@ -268,6 +330,63 @@ export function anchorPrecondition(anchor) {
     }
     return undefined;
 }
+/** What is added to a stale-ref error when it cannot be traced to one sub-step of the sequence. */
+const STALE_SUB_STEP_UNKNOWN = ' (which sub-step that was could not be told, so the ones before it may have run)';
+/** Where a ref that stayed stale sat in the sequence, and that every sub-step before it ran. */
+const staleSubStepPosition = (at, total) => ` (sub-step ${String(at)} of ${String(total)}; ${String(at)} before it ran)`;
+/**
+ * Why a step whose target kept going stale is unverifiable, as the replay result tells a reader.
+ * `step` is the index of the step that could not be acted on.
+ */
+const staleTargetReason = (step) => `step ${String(step)} could not be acted on: its target kept going stale, because the ` +
+    `page re-rendered between finding the element and using it, and the replay looked it up ` +
+    `again for as long as that got it further. The steps before it are reported and nothing ` +
+    `after it ran. Nothing here says the app failed. If an earlier step makes the page ` +
+    `re-render, record that step's consequence with \`expect\` so the replay waits for the new ` +
+    `render before it moves on.`;
+/**
+ * The sub-step, among live[from, to), whose ref the page said it could not find.
+ *
+ * The page echoes the ref in "ref 'x' no longer resolves to an element". A ref it shortened, or one
+ * that is not among these, gives no answer. Neither does a ref that two sub-steps share: the first of
+ * them may already have run, and may be what re-rendered the page, which makes the later one the stale
+ * one, and nothing in the message says so. The caller must not guess which actions already ran.
+ */
+function staleSubStep(error, live, from, to) {
+    const named = /ref '([^']*)'/.exec(error)?.[1];
+    if (named === undefined)
+        return undefined;
+    const sharing = live.flatMap((one, at) => at >= from && at < to && one.ref === named ? [at] : []);
+    const [only] = sharing;
+    return 1 === sharing.length ? only : undefined;
+}
+/**
+ * The honest answer when a step's target kept going stale.
+ *
+ * Replay looks the element up again and goes on while that gets it further, so a step still stale
+ * after that is one the page re-rendered around faster than it could be targeted. Reporting it as
+ * `error` with the browser's own sentence says "your app broke", which is a claim nothing observed
+ * and sends a reader into product code that is fine. It is the same bucket as a document that went
+ * away: the steps before it are real and are attached, the step that could not be acted on is among
+ * them with its index, and nothing after it ran.
+ *
+ * Left alone, so the ordinary verdict stands, when anything else is in the run: a drifted anchor is
+ * drift whatever else happened, and a failure that is not staleness is a failure.
+ */
+export function staleTargetResult(name, steps) {
+    if (steps.some((step) => step.drift !== undefined))
+        return undefined;
+    const failed = steps.filter((step) => !step.ok);
+    const [only] = failed;
+    if (failed.length !== 1 || only === undefined || !isStaleRefError(only.error))
+        return undefined;
+    return {
+        name,
+        status: ReplayStatus.UNVERIFIABLE,
+        steps: [...steps],
+        unverifiable: { reason: staleTargetReason(only.step) },
+    };
+}
 /**
  * Run an act_sequence step: resolve every sub-step's OWN anchor, then dispatch the whole thing as one
  * ACT_SEQUENCE — the same shape `replayProgram` already uses, so a recorded sequence and a saved one
@@ -281,37 +400,62 @@ export function anchorPrecondition(anchor) {
 export async function runSequenceStep(session, step, index, subs, confirmDangerous, sleep, 
 /** Testids whose presence is deliberately NOT asserted — the LLM-output case. */
 dynamic = new Set()) {
-    const live = [];
-    for (const [subIndex, sub] of subs.entries()) {
+    /**
+     * Find one sub-step's element as the page is NOW. Either the live step to dispatch, or the step
+     * result that ends the run: a degraded anchor, or one that is no longer on the page.
+     *
+     * `afterRerender` is the second look, taken because the page re-rendered under a sub-step. An anchor
+     * that now matches several elements is drift there, as it is for a single step's retry: the first of
+     * the new matches may be an element the recording did not mean, and acting on it would report a pass
+     * for a click nobody can attribute. The first look keeps taking the first match.
+     */
+    const resolveSub = async (sub, subIndex, afterRerender = false) => {
         const label = `${anchorLabel(sub.anchor)} (sub-step ${String(subIndex)})`;
         const queryArgs = anchorQueryArgs(sub.anchor);
         if (null === queryArgs)
-            return degradedStepResult(step, index, label);
+            return { stop: degradedStepResult(step, index, label) };
         const { refs, hint } = await resolveQuery(session, queryArgs, sleep);
-        const ref = refs[0];
+        const ambiguous = afterRerender ? ambiguityDrift(sub.anchor, refs) : null;
+        if (ambiguous !== null) {
+            return { stop: { step: index, tool: step.tool, anchor: label, ok: false, drift: ambiguous } };
+        }
+        const ref = afterRerender ? refFor(sub.anchor, refs) : refs[0];
         if (ref === undefined) {
             return {
-                step: index,
-                tool: step.tool,
-                anchor: label,
-                ok: false,
-                drift: sub.anchor.kind === AnchorKind.TESTID
-                    ? testidDrift(sub.anchor.value, hint)
-                    : {
-                        reasonKind: DriftReason.COMPONENT_NOT_FOUND,
-                        reason: `anchor ${label} not found`,
-                        anchor: label,
-                        nearest: null,
-                    },
+                stop: {
+                    step: index,
+                    tool: step.tool,
+                    anchor: label,
+                    ok: false,
+                    drift: sub.anchor.kind === AnchorKind.TESTID
+                        ? testidDrift(sub.anchor.value, hint)
+                        : {
+                            reasonKind: DriftReason.COMPONENT_NOT_FOUND,
+                            reason: `anchor ${label} not found`,
+                            anchor: label,
+                            nearest: null,
+                        },
+                },
             };
         }
-        live.push({
-            ref,
-            action: sub.action ?? '',
-            // Each sub-step carries its OWN anchor, so each gets its own field name. A sequence that ends
-            // in a login is the shape this was reported on, and the sub-step is where the fill lives.
-            args: replayActionArgs(sub.args, confirmDangerous, anchorFieldName(sub.anchor)),
-        });
+        return {
+            live: {
+                ref,
+                action: sub.action ?? '',
+                // Each sub-step carries its OWN anchor, so each gets its own field name. A sequence that ends
+                // in a login is the shape this was reported on, and the sub-step is where the fill lives.
+                args: replayActionArgs(sub.args, confirmDangerous, anchorFieldName(sub.anchor)),
+            },
+        };
+    };
+    // Every anchor is checked before anything runs, so a sub-step that has drifted away is reported as
+    // drift and not discovered half way through a sequence that has already acted.
+    const live = [];
+    for (const [subIndex, sub] of subs.entries()) {
+        const resolved = await resolveSub(sub, subIndex);
+        if ('stop' in resolved)
+            return resolved.stop;
+        live.push(resolved.live);
     }
     const result = {
         step: index,
@@ -320,20 +464,71 @@ dynamic = new Set()) {
         ok: true,
     };
     /** One dispatch through the SAME command either way, so batched and walked replay identically. */
-    const dispatch = async (steps) => {
+    const send = async (steps) => {
         session.beginAction?.(ReticleTool.FLOW_REPLAY, { steps: steps.length });
-        let act;
         try {
-            act = await session.command(ReticleCommand.ACT_SEQUENCE, { steps });
+            return await session.command(ReticleCommand.ACT_SEQUENCE, { steps });
         }
         finally {
             session.finishAction?.();
         }
-        if (act.ok)
-            return true;
-        result.ok = false;
-        result.error = replayDestructiveActionHint(act.error ?? 'command failed');
-        return false;
+    };
+    /**
+     * Run sub-steps [from, to), and survive the page re-rendering under them.
+     *
+     * The refs were resolved before anything ran, and the first action of a sequence is allowed to
+     * re-render the page, so by the time a later sub-step is reached its ref may be dead. The same
+     * anchor is almost always still there under a new ref; what was missing is a second look.
+     *
+     * The page names the ref it could not find, which says WHICH sub-step failed and so which ones
+     * already ran, as long as no other sub-step holds the same ref. Only the rest is resolved again and
+     * sent, so nothing acts twice: starting over is what turns one click into two. A stale ref is the
+     * only failure retried, and the retry goes on only while it gets further. A sub-step that is stale
+     * again at the same point is a target that does not hold still, and the run says so, with how far
+     * it got.
+     */
+    const dispatchFrom = async (from, to) => {
+        let start = from;
+        let staleBefore = -1;
+        for (;;) {
+            const act = await send(live.slice(start, to));
+            if (act.ok)
+                return true;
+            const error = act.error ?? 'command failed';
+            if (!isStaleRefError(error)) {
+                result.ok = false;
+                result.error = replayDestructiveActionHint(error);
+                return false;
+            }
+            const staleAt = staleSubStep(error, live, start, to);
+            if (staleAt === undefined) {
+                result.ok = false;
+                result.error = error + STALE_SUB_STEP_UNKNOWN;
+                return false;
+            }
+            if (staleAt <= staleBefore) {
+                result.ok = false;
+                result.error = error + staleSubStepPosition(staleAt, subs.length);
+                return false;
+            }
+            staleBefore = staleAt;
+            await waitForReaction(session, 0, STALE_REF_GRACE_MS, { sleep });
+            for (let at = staleAt; at < to; at += 1) {
+                const sub = subs[at];
+                if (sub === undefined)
+                    continue;
+                const resolved = await resolveSub(sub, at, true);
+                if ('stop' in resolved) {
+                    result.ok = false;
+                    result.anchor = resolved.stop.anchor;
+                    if (resolved.stop.drift !== undefined)
+                        result.drift = resolved.stop.drift;
+                    return false;
+                }
+                live[at] = resolved.live;
+            }
+            start = staleAt;
+        }
     };
     /** The sub-step's own expectation, unless its testid is deliberately unasserted. */
     const declaredBy = (sub) => {
@@ -368,14 +563,13 @@ dynamic = new Set()) {
      */
     const declaring = subs.some((sub) => declaredBy(sub) !== undefined);
     if (!declaring) {
-        await dispatch(live);
+        await dispatchFrom(0, live.length);
         return result;
     }
     for (const [subIndex, sub] of subs.entries()) {
-        const one = live[subIndex];
-        if (one === undefined)
+        if (live[subIndex] === undefined)
             continue;
-        if (!(await dispatch([one])))
+        if (!(await dispatchFrom(subIndex, subIndex + 1)))
             return result;
         const testid = declaredBy(sub);
         if (testid !== undefined && !(await assertDeclared(testid)))

package/dist/language/flows/flow-store-for-session.d.ts

@@ -24,9 +24,9 @@
  * returned unchanged.
  */
 import { FlowStore } from './flows.js';
-import type { ProjectId } from '@reticlehq/core';
+import type { ProjectTarget } from '../../memory/project/session-root.js';
 import type { ToolDeps } from '../../surface/tools/tool-kit.js';
-export declare function flowsForSession(deps: ToolDeps, projectId: ProjectId | undefined): {
+export declare function flowsForSession(deps: ToolDeps, target: ProjectTarget): {
     flows: FlowStore;
     root: string;
 };

package/dist/language/flows/flow-store-for-session.js

@@ -24,8 +24,8 @@
  * returned unchanged.
  */
 import { FlowStore } from './flows.js';
-export function flowsForSession(deps, projectId) {
-    const resolved = deps.artifactRootFor?.(projectId);
+export function flowsForSession(deps, target) {
+    const resolved = deps.artifactRootFor?.(target.projectId, target.origin);
     if (resolved === undefined || resolved.root === deps.reticleRoot) {
         return { flows: deps.flows, root: deps.reticleRoot };
     }