@reticlehq/server 3.2.0 → 3.4.0

package/dist/language/flows/flow-replay.d.ts

@@ -1,5 +1,4 @@
-import { Surface } from 'open-verification';
-export { anchorLabel, componentLabel, componentQueryArgs, editDistance, expectElementDrift, nearestIsAmbiguous, nearestTestid, resolveQuery, testidDrift, } from './flow-anchor.js';
+export { nearestIsAmbiguous, nearestTestid, resolveQuery } from './flow-anchor.js';
 import type { FlowReplaySession, WaitForSignal, Sleep } from './flow-replay-types.js';
 export type { FlowReplaySession, WaitForSignal, Sleep } from './flow-replay-types.js';
 import { type Drift, type FlowFile, type FlowStep, type FlowStepResult } from '@reticlehq/core';
@@ -20,6 +19,8 @@ export declare class DocumentLostDuringReplay extends Error {
     readonly atStep: number;
     constructor(steps: FlowStepResult[], atStep: number, lostTo?: unknown);
 }
+/** Run one testid-anchored step: re-resolve via QUERY, then ACT on the live ref, else drift. */
+export declare function runTestidStep(session: FlowReplaySession, step: FlowStep, index: number, value: string, dynamic: ReadonlySet<string>, confirmDangerous: boolean, sleep: Sleep): Promise<FlowStepResult>;
 /**
  * After a step's anchor resolves and its action runs, its `expect` is EVALUATED — every kind of it.
  *
@@ -41,16 +42,26 @@ export declare class DocumentLostDuringReplay extends Error {
  * 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 declare function assertStepExpect(session: FlowReplaySession, expect: NonNullable<FlowStep['expect']>, dynamic: ReadonlySet<string>, waitForSignal: WaitForSignal, timeoutMs: number, since: number): Promise<Drift | undefined>;
+export declare function assertStepExpect(session: FlowReplaySession, expect: NonNullable<FlowStep['expect']>, waitForSignal: WaitForSignal, timeoutMs: number, since: number): Promise<Drift | undefined>;
 /**
  * Replay a loaded flow by RE-RESOLVING every step's semantic anchor against the live DOM — never
  * a stale ref. A testid anchor is re-found by reticle_query; a signal anchor waits on a predicate.
  * On the first anchor MISS the step carries legible drift and replay STOPS, returning the partial
  * results. This is the "whose fault is it" contract, not a blind "command failed".
  */
-/** Where a replay starts reporting. Steps before it are re-driven, silently, as setup. */
+/**
+ * How a replay is loaded, where it starts reporting, and how far it goes.
+ */
 export interface ReplayFromOptions {
-    from?: number;
+    /**
+     * Resume at this step: an index, or a step's `id` (which survives edits that shift indices).
+     *
+     * There is no state to restore, so the steps before it are re-driven — quickly, as setup: their
+     * actions run, their declared consequences are not checked and their results are not reported.
+     * The one exception is a setup step that FAILS: the resume never reached the step it was asked
+     * for, and swallowing that would report the run as starting where it did not.
+     */
+    from?: number | string;
     /**
      * How to load a flow this one INVOKES. Absent means invocations cannot be followed.
      *
@@ -67,13 +78,6 @@ export interface ReplayFromOptions {
         flow: string;
         step: number;
     }[];
-    /**
-     * Which kind of subject this is. Decides whether re-driving the prefix is allowed at all.
-     *
-     * Defaults to `web`, which is the permissive answer — correct for the only surface that resumes
-     * today, and the reason a caller on a committing surface must say so rather than rely on silence.
-     */
-    surface?: Surface;
     /**
      * Keep going past a step whose ACTION ran and whose declared consequence merely did not hold.
      *
@@ -88,4 +92,15 @@ export interface ReplayFromOptions {
      */
     sweep?: boolean;
 }
+/**
+ * The index a replay resumes at, or `undefined` when `from` names no step of this flow.
+ *
+ * A step declared `commits` in the prefix refuses the resume (0 = replay everything): re-driving it
+ * is not setup, it is a second charge, a second email, a second record.
+ */
+export declare function resumeIndex(from: number | string | undefined, steps: readonly FlowStep[]): number | undefined;
+/** The `from` argument, narrowed: a step index or a step id. */
+export declare function resumeArg(raw: unknown): number | string | undefined;
+/** Why `from` cannot be resumed at, or undefined when it can (or was not given). */
+export declare function unresolvedResume(from: number | string | undefined, steps: readonly FlowStep[]): string | undefined;
 export declare function replayFlow(session: FlowReplaySession, flow: FlowFile, waitForSignal: WaitForSignal, signalTimeoutMs: number, confirmDangerous?: boolean, sleep?: Sleep, options?: ReplayFromOptions): Promise<FlowStepResult[]>;

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

@@ -1,23 +1,21 @@
-import { mayResumeByReplayingPrefix, StepEffect } from '@reticlehq/core';
-import { Surface, formatStepAddress } from 'open-verification';
+import { formatStepAddress } from 'open-verification';
+import { assertsState, expectLabel, expectedElementTestid, withoutClauses } from '@reticlehq/core';
 import { span } from '../../trace.js';
-import { anchorLabel, expectElementDrift, resolveTestid, testidDrift } from './flow-anchor.js';
-export { anchorLabel, componentLabel, componentQueryArgs, editDistance, expectElementDrift, nearestIsAmbiguous, nearestTestid, resolveQuery, testidDrift, } from './flow-anchor.js';
-import { routeOfEvent } from '@reticlehq/engine/question/predicate/predicate-route.js';
+import { anchorLabel, expectElementDrift, resolveTestid, testidDrift, ambiguousAnchorDrift, } from './flow-anchor.js';
+export { nearestIsAmbiguous, nearestTestid, resolveQuery } from './flow-anchor.js';
+import { routeOfEvent, routeOfUrl } from '@reticlehq/engine/question/predicate/predicate-route.js';
 import { stepEffect } from '@reticlehq/engine/evidence/step-effect.js';
-import { AnchorKind, DriftReason, EventType, FlowStepTool, ReticleCommand, PredicateKind, } from '@reticlehq/core';
+import { AnchorKind, DriftReason, EventType, FlowStepTool, StepEffect, PredicateKind, } from '@reticlehq/core';
 import { asString, isConsequenceDrift } from '@reticlehq/core';
-import { replayActionArgs, ambiguousTestidNote } from './replay.js';
 import { anchorFieldName } from './fields/flow-secret-field.js';
 import { degradedStepResult, isDegradedAnchor, runComponentStep, runRoleStep, runSequenceStep, } from './flow-step-runners.js';
-import { successToPredicate } from './flow-success.js';
 import { inFlightRequestLabels } from '../../surface/tools/act/settle-in-flight.js';
 import { namedNetIsInFlight } from '@reticlehq/engine/evidence/unsettled.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 { ReticleTool } from '@reticlehq/core';
-import { isDocumentGoneError } from '../../portal/session/facts/session-replaced.js';
+import { isDocumentGoneError, SESSION_DISCONNECTED_REASON, } from '../../portal/session/facts/session-replaced.js';
+import { actOnResolvedRef } from './flow-step-runners.js';
 /**
  * The document this replay was driving went away mid-run.
  *
@@ -50,8 +48,11 @@ const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 function currentRoute(session) {
     const routes = session.eventsSince(0).filter((e) => e.type === EventType.ROUTE_CHANGE);
     const last = routes.at(-1);
-    if (last === undefined)
-        return undefined;
+    // A page that loaded and never navigated has no route event; its URL is still where it is.
+    if (last === undefined) {
+        const loaded = session.url === undefined ? undefined : routeOfUrl(session.url);
+        return loaded !== undefined && loaded.routePath.length > 0 ? loaded.routePath : undefined;
+    }
     // The ROUTER's path. This field answers "which page did this step run on", and the document
     // 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.
@@ -105,7 +106,7 @@ function summarizeConsequence(events) {
     return parts.length > 0 ? parts.join('; ') : undefined;
 }
 /** Run one testid-anchored step: re-resolve via QUERY, then ACT on the live ref, else drift. */
-async function runTestidStep(session, step, index, value, dynamic, confirmDangerous, sleep) {
+export async function runTestidStep(session, step, index, value, dynamic, confirmDangerous, sleep) {
     const { refs, hint } = await resolveTestid(session, value, sleep);
     if (0 === refs.length) {
         return {
@@ -116,35 +117,50 @@ async function runTestidStep(session, step, index, value, dynamic, confirmDanger
             drift: testidDrift(value, hint),
         };
     }
-    const ref = refs[0] ?? '';
-    const note = refs.length > 1 ? ambiguousTestidNote(value) : undefined;
-    session.beginAction?.(ReticleTool.FLOW_REPLAY, { ref, action: step.action ?? '' });
-    let act;
-    try {
-        act = await session.command(ReticleCommand.ACT, {
-            ref,
-            action: step.action ?? '',
-            // 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. The testid runner used to pass
-            // the testid string here and the other two runners passed nothing, so a role-anchored login
-            // typed the literal placeholder.
-            args: replayActionArgs(step.args, confirmDangerous, anchorFieldName(step.anchor)),
-        });
-    }
-    finally {
-        session.finishAction?.();
+    /*
+     * More than one match is DRIFT, not a note on a passing step.
+     *
+     * This used to take refs[0], act, and return ok:true with `ambiguousTestidNote`. The verdict
+     * 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.
+     */
+    if (refs.length > 1) {
+        return {
+            step: index,
+            tool: step.tool,
+            anchor: value,
+            ok: false,
+            drift: ambiguousAnchorDrift(value, refs.length),
+        };
     }
-    const result = { step: index, tool: step.tool, anchor: value, ok: act.ok };
-    if (!act.ok) {
-        result.error = act.error ?? 'command failed';
-        if (note !== undefined)
-            result.note = note;
+    const ref = refs[0] ?? '';
+    /*
+     * The same dispatch its siblings use, including the one re-resolve on a stale ref (2.3).
+     *
+     * This runner had its own inline copy and no retry, so a flow died on a re-render purely because
+     * the step was anchored by testid rather than by role — the locator deciding how sturdy the replay
+     * is, which is exactly backwards. testid is also the anchor `reticle init` steers people towards,
+     * 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.
+     */
+    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;
+    });
+    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.
-    const expectTestid = step.expect?.element?.testid;
+    const expectTestid = expectedElementTestid(step.expect);
     if (expectTestid !== undefined && !dynamic.has(expectTestid)) {
         const expectRefs = await resolveTestid(session, expectTestid, sleep);
         if (0 === expectRefs.refs.length) {
@@ -160,8 +176,6 @@ async function runTestidStep(session, step, index, value, dynamic, confirmDanger
             };
         }
     }
-    if (note !== undefined)
-        result.note = note;
     return result;
 }
 /**
@@ -185,30 +199,52 @@ async function runTestidStep(session, step, index, value, dynamic, confirmDanger
  * 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, dynamic, waitForSignal, timeoutMs, since) {
+export async function assertStepExpect(session, expect, waitForSignal, timeoutMs, since) {
     // 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.
-    const consequences = { ...expect };
-    if (undefined !== consequences.element?.testid) {
-        delete consequences.element;
-    }
-    const predicate = successToPredicate(consequences, dynamic);
+    /*
+     * Two clauses replay must not wait on, both for reasons that predate the tree.
+     *
+     * A testid element was already asserted against the live DOM by the step runner, so waiting on it
+     * again is a second read of a question already answered. A DYNAMIC testid is one whose content a
+     * model writes, and its presence is deliberately never asserted.
+     *
+     * A role/name locator is NEITHER, and stripping every element made a recorded `until` by button
+     * name a no-op — a flow that proved the control at capture time could not go red when it was gone.
+     *
+     * The DYNAMIC set used to be a parameter here and was dead the whole time: the testid was deleted
+     * from the expectation on the line above, and the only thing that read the set asked for the
+     * testid that had just been removed. One production caller was already passing an empty set. The
+     * rule is real and still applies to the flow's SUCCESS oracle, which is where it lives.
+     */
+    const predicate = withoutClauses(expect, 
+    // Only a PRESENT testid is the runner's to check; an absence stays here or nobody checks it.
+    (clause) => PredicateKind.ELEMENT === clause.kind &&
+        clause.query.testid !== undefined &&
+        true !== clause.absent);
     if (predicate === undefined)
         return undefined;
     const verdict = await waitForSignal(session, predicate, timeoutMs, since);
     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)
+        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.
     // An unrelated open request does not pardon a named URL that never started — matching decides it.
-    const openRequests = expect.state === undefined ? inFlightRequestLabels(session.eventsSince(since)) : [];
+    const openRequests = assertsState(expect)
+        ? []
+        : inFlightRequestLabels(session.eventsSince(since), session.url, session.background);
     const namedInFlight = namedNetIsInFlight(predicate, openRequests);
     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: expect.state !== undefined
+        reasonKind: assertsState(expect)
             ? DriftReason.STATE_MISMATCH
             : namedInFlight
                 ? DriftReason.NET_STILL_IN_FLIGHT
@@ -220,21 +256,6 @@ export async function assertStepExpect(session, expect, dynamic, waitForSignal,
         nearest: null,
     };
 }
-/** Name the thing that was asserted, for the drift's `anchor` column. */
-function expectLabel(expect) {
-    if (expect.signal !== undefined)
-        return `signal:${expect.signal}`;
-    if (expect.net !== undefined)
-        return `net:${expect.net.urlContains ?? expect.net.method ?? '*'}`;
-    if (expect.state !== undefined)
-        return `state:${expect.state.path}`;
-    if (expect.console !== undefined)
-        return `console:${expect.console.level ?? '*'}`;
-    if (undefined !== expect.element) {
-        return expect.element.testid ?? expect.element.name ?? expect.element.role ?? 'element';
-    }
-    return 'expect';
-}
 /** Run one signal-anchored step: wait for the signal predicate, else drift (no nearest for signals). */
 async function runSignalStep(session, step, index, name, waitForSignal, signalTimeoutMs, since) {
     // Scope to THIS replay's floor, not the whole buffer.
@@ -263,38 +284,28 @@ async function runSignalStep(session, step, index, name, waitForSignal, signalTi
     };
 }
 /**
- * Where to start REPORTING — and whether re-driving the steps before it is allowed at all.
- *
- * "Resume is nearly free, just re-run the prefix" is true of a browser and false on a subject that
- * COMMITS. Re-driving a prefix on a service re-sends every request before step N; on a device it
- * moves an arm again. Neither is a convenience, and a protocol that did it silently would be
- * defective rather than helpful.
+ * The index a replay resumes at, or `undefined` when `from` names no step of this flow.
  *
- * So the surface's declared profile decides, through the specification's own `resumeStrategy` rather
- * than a local reading of `replayPrefix`. A refusal resumes from 0 — the whole journey is reported,
- * nothing is skipped and nothing is silently repeated beyond what a plain replay already does.
+ * A step declared `commits` in the prefix refuses the resume (0 = replay everything): re-driving it
+ * is not setup, it is a second charge, a second email, a second record.
  */
-function resumableFrom(options, steps) {
-    const asked = Math.max(0, options.from ?? 0);
-    if (0 === asked)
-        return 0;
-    if (!mayResumeByReplayingPrefix(options.surface ?? Surface.WEB))
+export function resumeIndex(from, steps) {
+    if (from === undefined)
         return 0;
-    /*
-     * The surface answers for the SUBJECT; a step answers for itself.
-     *
-     * `web` is the permissive profile and it is right about a browser in general and wrong about the
-     * one click that charges a card. The surface check cannot see that, because the distinction is
-     * not a property of the realm — it is a property of the step. A flow that declares a prefix step
-     * as `commits` is saying: re-running me is not free, whatever the surface thinks.
-     *
-     * Refusing means resuming from 0, which is the same fail-safe the surface refusal already uses:
-     * the whole journey is reported and nothing is silently repeated beyond what a plain replay does.
-     * Absent effect is UNKNOWN and stays permissive — every flow recorded before this shipped has no
-     * effect on any step, and assuming the worst there would refuse every resume in existence.
-     */
-    const commitsInPrefix = steps.slice(0, asked).some((step) => StepEffect.COMMITS === step.effect);
-    return commitsInPrefix ? 0 : asked;
+    const at = 'number' === typeof from ? from : steps.findIndex((step) => step.id === from);
+    if (at < 0 || at >= steps.length || !Number.isInteger(at))
+        return undefined;
+    return steps.slice(0, at).some((step) => StepEffect.COMMITS === step.effect) ? 0 : at;
+}
+/** 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;
+}
+/** 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)
+        return undefined;
+    return `cannot resume at ${JSON.stringify(from)}: this flow has ${String(steps.length)} step(s) and no step by that id`;
 }
 /**
  * Run an `invoke` step: load the named flow and replay it, or fail saying why.
@@ -307,7 +318,7 @@ function resumableFrom(options, steps) {
  * own, and the sub-journey's outcome is summarised on the invocation, so a reader sees the shape
  * they recorded rather than a flattened list that has lost every boundary.
  */
-async function runInvokeStep(session, flow, step, index, waitForSignal, signalTimeoutMs, confirmDangerous, sleep, options) {
+async function runInvokeStep(session, flow, step, index, waitForSignal, signalTimeoutMs, confirmDangerous, sleep, options, setup = false) {
     const name = step.invoke ?? '';
     const via = options.via ?? [];
     const here = { flow: flow.name, step: index, via };
@@ -329,10 +340,10 @@ async function runInvokeStep(session, flow, step, index, waitForSignal, signalTi
             error: `cannot replay "${name}": it was not found, so this journey would report green having never run it`,
         };
     }
-    // `from` is deliberately dropped rather than forwarded: it is a REPORTING offset into the
-    // caller's own step list, and applying it inside a sub-journey would silently hide that
-    // journey's first steps for a reason that has nothing to do with it.
-    const { from: _ignored, ...carried } = options;
+    // `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;
+    const carried = setup ? { ...rest, from: sub.steps.length } : rest;
     const nested = await replayFlow(session, sub, waitForSignal, signalTimeoutMs, confirmDangerous, sleep, {
         ...carried,
         via: [{ flow: flow.name, step: index }, ...via],
@@ -350,16 +361,9 @@ async function runInvokeStep(session, flow, step, index, waitForSignal, signalTi
 }
 export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs, confirmDangerous = false, sleep = realSleep, options = {}) {
     const results = [];
-    /*
-     * Where to start REPORTING. Everything before it still runs.
-     *
-     * Resuming is re-driving the prefix, not restoring state: there is no way to put an app back
-     * where it was without driving it there, and at a measured ~27ms a step there is no reason to
-     * try. So the prefix executes silently and the caller sees the journey from the point it asked
-     * about -- which is what makes "fix the break, resume, find the next one" a loop rather than a
-     * full re-read each time.
-     */
-    const from = resumableFrom(options, flow.steps);
+    // Steps before this index are setup. `from` was validated by the caller; an unresolvable one
+    // resumes nowhere rather than everywhere, so it cannot silently widen into a full replay.
+    const from = resumeIndex(options.from, flow.steps) ?? flow.steps.length;
     // testids whose region is LLM-dynamic — their expect-presence is NOT asserted.
     const dynamic = new Set((flow.dynamic ?? [])
         .filter((a) => a.kind === AnchorKind.TESTID)
@@ -376,8 +380,10 @@ export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs,
     try {
         for (const step of flow.steps) {
             if (step.invoke !== undefined) {
-                results.push(await runInvokeStep(session, flow, step, index, waitForSignal, signalTimeoutMs, confirmDangerous, sleep, options));
+                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();
                 if (last !== undefined && false === last.ok)
                     break;
                 index += 1;
@@ -433,10 +439,12 @@ export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs,
              * replay path and belongs in its own commit.
              */
             const declared = [step.expect, ...(step.steps ?? []).map((sub) => sub.expect)].filter((expectation) => expectation !== undefined);
-            for (const expectation of declared) {
+            // A setup step's consequence is not checked: it is re-driven to get somewhere, not to prove it.
+            const checked = index < from ? [] : declared;
+            for (const expectation of checked) {
                 if (!result.ok || result.drift !== undefined)
                     break;
-                const expectDrift = await assertStepExpect(session, expectation, dynamic, waitForSignal, waitFor(step), cursorBefore);
+                const expectDrift = await assertStepExpect(session, expectation, waitForSignal, waitFor(step), cursorBefore);
                 if (expectDrift !== undefined) {
                     result.ok = false;
                     result.drift = expectDrift;
@@ -444,6 +452,9 @@ export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs,
             }
             if (page !== undefined)
                 result.page = page;
+            const endPage = currentRoute(session);
+            if (endPage !== undefined && endPage !== page)
+                result.endPage = endPage;
             const windowEvents = session.eventsSince(cursorBefore).filter((e) => e.t >= cursorBefore);
             const consequence = summarizeConsequence(windowEvents);
             if (consequence !== undefined)
@@ -466,8 +477,13 @@ export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs,
             // forget the rule and quietly re-introduce the cost. Spelled out only when it is NOT the default.
             if (FlowStepTool.ACT === result.tool)
                 delete result.tool;
-            if (index >= from || !result.ok || result.drift !== undefined)
-                results.push(result);
+            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`;
+            results.push(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-result.d.ts

@@ -33,3 +33,5 @@ export type FlowResult<T> = {
  * hold the distinction — this is the fourth id joined into a path, and the one that file missed.
  */
 export declare const safeProjectId: (projectId?: ProjectId) => ProjectId | undefined;
+/** Map a structured FlowErrorCode to a legible one-line message for the agent. */
+export declare function flowErrorMessage(code: FlowErrorCode, detail?: string): string;

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

@@ -1,5 +1,6 @@
 import { FlowErrorCode } from '@reticlehq/core';
 import { SAFE_SEGMENT_PATTERN } from '@reticlehq/core';
+import { FlowParseNote } from './flow-expect-grammar.js';
 /**
  * A project id that is safe to put in a path, or nothing.
  *
@@ -24,3 +25,27 @@ import { SAFE_SEGMENT_PATTERN } from '@reticlehq/core';
  * hold the distinction — this is the fourth id joined into a path, and the one that file missed.
  */
 export const safeProjectId = (projectId) => projectId !== undefined && SAFE_SEGMENT_PATTERN.test(projectId) ? projectId : undefined;
+/** Map a structured FlowErrorCode to a legible one-line message for the agent. */
+export function flowErrorMessage(code, detail) {
+    if (FlowErrorCode.PARSE_FAILED === code && undefined !== detail)
+        return detail;
+    // The detail names both versions and the remedy, so it beats anything generic this could say.
+    if (FlowErrorCode.WRONG_VERSION === code && undefined !== detail)
+        return detail;
+    switch (code) {
+        case FlowErrorCode.INVALID_NAME:
+            return 'invalid flow name — use a single safe segment (letters/digits/-/_), no path separators';
+        case FlowErrorCode.NOT_FOUND:
+            return 'no such flow on disk — run reticle_flow{action:"list"} to see saved flows';
+        case FlowErrorCode.PARSE_FAILED:
+            return FlowParseNote.MALFORMED;
+        case FlowErrorCode.NO_RECORDING:
+            return 'no compiled recording by that name — record one (reticle_record{action:"start"|"stop"}) first';
+        // Never "regenerate it": the file is intact and the reader is the wrong one. Telling somebody
+        // to rewrite an undamaged flow is the failure this code was split out of PARSE_FAILED to stop.
+        case FlowErrorCode.WRONG_VERSION:
+            return 'this flow file was written in a different flow-file format — the file is not damaged, this Reticle cannot read that version. Upgrade or downgrade Reticle rather than editing the flow';
+        case FlowErrorCode.STEP_NOT_FOUND:
+            return (detail ?? 'the step to resume at is not in this flow — pass a 0-based index or a step id');
+    }
+}

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

@@ -1,17 +1,26 @@
-/**
- * How one anchored step is turned into a live action.
- *
- * Split out of flow-replay.ts when adding the role+name runner pushed that file past the size cap.
- * These three share one shape — resolve an anchor to a ref, then dispatch — and the sharing is the
- * point: the action window must open and close identically no matter which anchor found the element,
- * or a step's events land in the wrong window depending on how it was addressed.
- */
-import { AnchorKind, type FlowAnchor, type FlowStep, type FlowStepResult } from '@reticlehq/core';
+import { AnchorKind, type FlowAnchor, type FlowStep, type FlowStepResult, type Predicate } from '@reticlehq/core';
 import type { FlowReplaySession, Sleep } from './flow-replay-types.js';
 export declare function runRoleStep(session: FlowReplaySession, step: FlowStep, index: number, anchor: Extract<FlowAnchor, {
     kind: typeof AnchorKind.ROLE;
 }>, confirmDangerous: boolean, sleep: Sleep): Promise<FlowStepResult>;
-export declare function replayDestructiveActionHint(rawError: string): string;
+/**
+ * Dispatch one already-resolved step. Shared so every anchor kind runs the action the same way —
+ * including the action window, whose open/close must not depend on which anchor found the element.
+ */
+export declare function actOnResolvedRef(session: FlowReplaySession, step: FlowStep, index: number, label: string, ref: string, confirmDangerous: boolean, 
+/**
+ * The field name a redacted fill is supplied under, from `anchorFieldName` — the SAME function
+ * redaction uses to decide what to hide. Without it a role-anchored secret is redacted at save
+ * and looked up at replay under no name at all, so the flow types the placeholder into the form.
+ */
+field?: string, 
+/**
+ * Resolve the anchor again. Supplied by the caller because only it knows how this step's anchor is
+ * 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.
+ */
+reresolve?: () => Promise<string | 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;
@@ -39,6 +48,13 @@ export declare function degradedStepResult(step: FlowStep, index: number, label:
  * the step runner's own resolution asking the same thing of the same anchor.
  */
 export declare function anchorQueryArgs(anchor: FlowAnchor): Record<string, unknown> | null;
+/**
+ * The anchor as a PRECONDITION a flow file can store: "this element is on the page".
+ *
+ * What `requires` means for a flow that starts from state a page load discards, in the shape the
+ * 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;
 /**
  * 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

@@ -6,7 +6,8 @@
  * point: the action window must open and close identically no matter which anchor found the element,
  * or a step's events land in the wrong window depending on how it was addressed.
  */
-import { AnchorKind, DEGRADED_ANCHOR_ROLE, DriftReason, QueryBy, ReticleCommand, } from '@reticlehq/core';
+import { expectedElementTestid } from '@reticlehq/core';
+import { AnchorKind, DEGRADED_ANCHOR_ROLE, DriftReason, PredicateKind, QueryBy, ReticleCommand, } from '@reticlehq/core';
 import { ReticleTool } from '@reticlehq/core';
 import { replayActionArgs } from './replay.js';
 import { isStaleRefError } from '../../surface/tools/act/act-sequence-retry.js';
@@ -102,7 +103,7 @@ export async function runRoleStep(session, step, index, anchor, confirmDangerous
  * to recognise the raw refusal still finds it, plus the fix for this specific caller.
  */
 const DESTRUCTIVE_ACTION_PATTERN = /potentially destructive (?:\w+ )*(?:action|tool) blocked/i;
-export function replayDestructiveActionHint(rawError) {
+function replayDestructiveActionHint(rawError) {
     if (!DESTRUCTIVE_ACTION_PATTERN.test(rawError))
         return rawError;
     return (`${rawError} — this is a flow REPLAY: a step's own args.confirmDangerous is stripped before ` +
@@ -118,7 +119,7 @@ export function replayDestructiveActionHint(rawError) {
  * Dispatch one already-resolved step. Shared so every anchor kind runs the action the same way —
  * including the action window, whose open/close must not depend on which anchor found the element.
  */
-async function actOnResolvedRef(session, step, index, label, ref, confirmDangerous, 
+export async function actOnResolvedRef(session, step, index, label, ref, confirmDangerous, 
 /**
  * The field name a redacted fill is supplied under, from `anchorFieldName` — the SAME function
  * redaction uses to decide what to hide. Without it a role-anchored secret is redacted at save
@@ -252,6 +253,21 @@ export function anchorQueryArgs(anchor) {
         return roleQueryArgs(anchor);
     return null;
 }
+/**
+ * The anchor as a PRECONDITION a flow file can store: "this element is on the page".
+ *
+ * What `requires` means for a flow that starts from state a page load discards, in the shape the
+ * flow's own `requires` holds. No tool writes `requires`, so the reset's hint hands over this line.
+ */
+export function anchorPrecondition(anchor) {
+    if (anchor.kind === AnchorKind.TESTID) {
+        return { kind: PredicateKind.ELEMENT, query: { testid: anchor.value } };
+    }
+    if (anchor.kind === AnchorKind.ROLE && !isDegradedAnchor(anchor)) {
+        return { kind: PredicateKind.ELEMENT, query: { role: anchor.role, name: anchor.name } };
+    }
+    return 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
@@ -321,7 +337,7 @@ dynamic = new Set()) {
     };
     /** The sub-step's own expectation, unless its testid is deliberately unasserted. */
     const declaredBy = (sub) => {
-        const testid = sub.expect?.element?.testid;
+        const testid = expectedElementTestid(sub.expect);
         return testid === undefined || dynamic.has(testid) ? undefined : testid;
     };
     /**