@reticlehq/server 2.4.0 → 2.6.0

package/dist/flows/flow-replay.js

@@ -1,7 +1,9 @@
-import { AnchorKind, DriftReason, EventType, ReticleCommand, QueryBy, } from '@reticlehq/core';
+import { span } from '../trace.js';
+import { AnchorKind, DriftReason, EventType, ReticleCommand, QueryBy, PredicateKind, } from '@reticlehq/core';
 import { asRecord, asString } from '../tools/tools-helpers.js';
 import { replayActionArgs, ambiguousTestidNote, queryRefs } from './replay.js';
-import { runRoleStep, runComponentStep } from './flow-step-runners.js';
+import { degradedStepResult, isDegradedAnchor, runComponentStep, runRoleStep, runSequenceStep, } from './flow-step-runners.js';
+import { successToPredicate } from './flow-success.js';
 import { ReticleTool } from '../tools/tool-names.js';
 /**
  * A single ASCII-ish edit distance (case-insensitive). Small inputs (testids), so O(n*m) is fine.
@@ -59,6 +61,22 @@ export function nearestTestid(missing, present) {
  */
 const ANCHOR_SETTLE_ATTEMPTS = 8;
 const ANCHOR_SETTLE_DELAY_MS = 150;
+/**
+ * The budget that actually governs, in wall-clock milliseconds.
+ *
+ * Attempts were the bound, and on an event-chatty page that collapsed. `settleTick` ends on EITHER
+ * an event OR the tick, so a page emitting continuously (API calls, a large form render, CSS
+ * transition start/end pairs) burned all eight attempts in **224–758ms measured** — a budget
+ * documented as 1.2s, spent in a fifth of it, before a newly routed page had mounted its controls.
+ * Cross-route replays drifted `testid_not_found` at 278ms while the same flow passed on a quiet page.
+ *
+ * An event arriving is evidence the page is still working. It should EXTEND the wait, not spend it.
+ * So the deadline decides when to give up, and the attempt cap below survives only as a backstop
+ * against a pathological storm spinning this loop hot.
+ */
+const ANCHOR_SETTLE_BUDGET_MS = ANCHOR_SETTLE_ATTEMPTS * ANCHOR_SETTLE_DELAY_MS;
+/** Backstop only. Generous on purpose: the deadline is the real bound, this just prevents a spin. */
+const ANCHOR_SETTLE_MAX_ATTEMPTS = 40;
 const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /** Extract the live element refs + the zero-match near-miss hint from a QUERY command result. */
 function readQuery(result) {
@@ -67,10 +85,10 @@ function readQuery(result) {
         return { refs };
     const payload = asRecord(result.result);
     const rawHint = payload['hint'];
-    if (typeof rawHint === 'object' && rawHint !== null) {
+    if ('object' === typeof rawHint && rawHint !== null) {
         const hint = asRecord(rawHint);
         const present = Array.isArray(hint['presentTestids'])
-            ? hint['presentTestids'].filter((t) => typeof t === 'string')
+            ? hint['presentTestids'].filter((t) => 'string' === typeof t)
             : [];
         return {
             refs,
@@ -78,7 +96,7 @@ function readQuery(result) {
                 route: asString(hint['route']) ?? '',
                 presentTestids: present,
                 presentRegions: [],
-                knownEmptyState: hint['knownEmptyState'] === true,
+                knownEmptyState: true === hint['knownEmptyState'],
             },
         };
     }
@@ -107,7 +125,7 @@ export function nearestIsAmbiguous(missing, present) {
     return count >= 2;
 }
 /** Build the legible-drift record for a testid anchor that resolved to zero live elements. */
-function testidDrift(value, hint) {
+export function testidDrift(value, hint) {
     const present = hint?.presentTestids ?? [];
     const drift = {
         reasonKind: DriftReason.TESTID_NOT_FOUND,
@@ -125,10 +143,42 @@ function testidDrift(value, hint) {
  * so a present anchor costs one query; a genuinely missing one costs the full (bounded) settle and
  * then drifts. The last result's near-miss hint is returned for the drift record.
  */
-export async function resolveQuery(session, queryArgs, sleep) {
+/**
+ * One wait between anchor attempts: the fixed tick, or the next DOM event — whichever comes first.
+ *
+ * An element mounting IS a mutation, and the session already streams those, so sleeping out the rest
+ * of a 150ms tick after the thing has already appeared is pure latency. Measured on next-app-router:
+ * a single `flow.step` span was 1079ms around nine QUERY round-trips of 1–2ms each — the cost was
+ * entirely the sleeping, and four such steps made up 4.3s of that app's 7.6s.
+ *
+ * It can only resolve the wait EARLIER, never end the loop earlier: the attempt budget above is
+ * untouched, so a genuinely missing anchor still spends the full settle before it drifts. An early
+ * "not found" would be a false drift, which is the failure this loop exists to prevent.
+ */
+async function settleTick(session, sleep) {
+    let unsubscribe;
+    try {
+        await new Promise((resolve) => {
+            let done = false;
+            const finish = () => {
+                if (done)
+                    return;
+                done = true;
+                resolve();
+            };
+            unsubscribe = session.onEvent(finish);
+            void sleep(ANCHOR_SETTLE_DELAY_MS).then(finish);
+        });
+    }
+    finally {
+        unsubscribe?.();
+    }
+}
+export async function resolveQuery(session, queryArgs, sleep, now = Date.now) {
     let last = readQuery(await session.command(ReticleCommand.QUERY, queryArgs));
-    for (let attempt = 1; last.refs.length === 0 && attempt < ANCHOR_SETTLE_ATTEMPTS; attempt += 1) {
-        await sleep(ANCHOR_SETTLE_DELAY_MS);
+    const deadline = now() + ANCHOR_SETTLE_BUDGET_MS;
+    for (let attempt = 1; 0 === last.refs.length && now() < deadline && attempt < ANCHOR_SETTLE_MAX_ATTEMPTS; attempt += 1) {
+        await settleTick(session, sleep);
         last = readQuery(await session.command(ReticleCommand.QUERY, queryArgs));
     }
     return last;
@@ -188,7 +238,7 @@ function summarizeConsequence(events) {
         const data = n.data ?? {};
         const method = asString(data['method']) ?? 'GET';
         const path = trimUrl(asString(data['url']) ?? '');
-        const status = typeof data['status'] === 'number' ? ` ${data['status']}` : '';
+        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;
@@ -206,7 +256,7 @@ export function componentLabel(anchor) {
     return anchor.component ?? anchor.name ?? anchor.role ?? 'component';
 }
 /** The value of a step's primary anchor, for labelling the result row. */
-function anchorLabel(anchor) {
+export function anchorLabel(anchor) {
     if (anchor.kind === AnchorKind.TESTID)
         return anchor.value;
     if (anchor.kind === AnchorKind.SIGNAL)
@@ -227,7 +277,7 @@ export function componentQueryArgs(anchor) {
 /** 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) {
     const { refs, hint } = await resolveTestid(session, value, sleep);
-    if (refs.length === 0) {
+    if (0 === refs.length) {
         return {
             step: index,
             tool: step.tool,
@@ -263,7 +313,7 @@ async function runTestidStep(session, step, index, value, dynamic, confirmDanger
     const expectTestid = step.expect?.element?.testid;
     if (expectTestid !== undefined && !dynamic.has(expectTestid)) {
         const expectRefs = await resolveTestid(session, expectTestid, sleep);
-        if (expectRefs.refs.length === 0) {
+        if (0 === expectRefs.refs.length) {
             return {
                 step: index,
                 tool: step.tool,
@@ -278,27 +328,50 @@ async function runTestidStep(session, step, index, value, dynamic, confirmDanger
     return result;
 }
 /**
- * After a step's anchor resolves + its action runs, an `expect.state` additionally asserts STORE
- * TRUTH — the source of truth no DOM read can reach. Evaluated with the same predicate engine (waits
- * up to the timeout so an async store update can settle); a mismatch is legible drift, not a blind
- * fail. Returns the drift on mismatch, else undefined.
+ * After a step's anchor resolves and its action runs, its `expect` is EVALUATED — every kind of it.
+ *
+ * For a long time only `expect.state` was, so a recorded `expect.signal` or `expect.net` was written
+ * to disk and read by nothing while `flow_save` graded the flow "asserted". Driven end to end over
+ * MCP: annotate a step with a signal that never fires, save (grade "asserted"), replay -> status
+ * "ok". A green that cannot go red, inside the feature whose job is catching exactly that.
+ *
+ * It compiles through the SAME `successToPredicate` the flow-level `success` has always used, so
+ * there is one definition of what an expect means and the step form cannot drift from it again.
+ * Turning this on makes previously-green flows go red. That is the point — they were green because
+ * nothing was looking.
  */
-async function assertStepState(session, state, waitForSignal, timeoutMs, since) {
-    const predicate = { kind: 'state', path: state.path };
-    if (state.store !== undefined)
-        predicate.store = state.store;
-    if (state.equals !== undefined)
-        predicate.equals = state.equals;
+async function assertStepExpect(session, expect, dynamic, waitForSignal, timeoutMs, since) {
+    // `element` is deliberately dropped: the step runner already asserts expect.element.testid against
+    // the live DOM before we get here, and re-asserting it through the predicate engine would be a
+    // second round trip for the same fact.
+    const { element: _element, ...consequences } = expect;
+    const predicate = successToPredicate(consequences, dynamic);
+    if (predicate === undefined)
+        return undefined;
     const verdict = await waitForSignal(session, predicate, timeoutMs, since);
     if (verdict.pass)
         return undefined;
     return {
-        reasonKind: DriftReason.STATE_MISMATCH,
-        reason: verdict.failureReason ?? `state '${state.path}' did not hold`,
-        anchor: `state:${state.path}`,
+        // 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 ? DriftReason.STATE_MISMATCH : DriftReason.SIGNAL_NOT_OBSERVED,
+        reason: verdict.failureReason ?? "the step's declared consequence did not hold",
+        anchor: expectLabel(expect),
         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 ?? '*'}`;
+    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.
@@ -310,7 +383,7 @@ async function runSignalStep(session, step, index, name, waitForSignal, signalTi
     // satisfied a LATER flow's signal step even when that flow's own action never fired it — a
     // 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: 'signal', name }, signalTimeoutMs, since);
+    const verdict = await waitForSignal(session, { kind: PredicateKind.SIGNAL, name }, signalTimeoutMs, since);
     if (verdict.pass)
         return { step: index, tool: step.tool, anchor: name, ok: true };
     return {
@@ -348,28 +421,39 @@ export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs,
         const page = currentRoute(session);
         // Event-time floor so the consequence reflects only THIS step's aftermath, not prior steps'.
         const cursorBefore = session.elapsed();
-        let result;
-        if (step.anchor.kind === AnchorKind.SIGNAL) {
-            result = await runSignalStep(session, step, index, label, waitForSignal, signalTimeoutMs, replayFloor);
-        }
-        else if (step.anchor.kind === AnchorKind.COMPONENT) {
-            result = await runComponentStep(session, step, index, step.anchor, confirmDangerous, sleep);
-        }
-        else 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 if it were a testid.
-            result = await runRoleStep(session, step, index, step.anchor, confirmDangerous, sleep);
-        }
-        else {
-            result = await runTestidStep(session, step, index, label, dynamic, confirmDangerous, sleep);
-        }
-        // A step may additionally assert STORE TRUTH (expect.state) once its action has run — caught
-        // deterministically here, in the same cheap replay loop, with no LLM.
-        if (result.ok && result.drift === undefined && step.expect?.state !== undefined) {
-            const stateDrift = await assertStepState(session, step.expect.state, waitForSignal, signalTimeoutMs, cursorBefore);
-            if (stateDrift !== undefined) {
+        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
+        // the replay engine gets, nested under the tool call with the browser round-trips beneath it.
+        const result = await span('flow.step', { index, anchor: step.anchor.kind, label }, async () => {
+            if (isDegradedAnchor(step.anchor)) {
+                // Never QUERY the sentinel — it marks "no anchor was determined", not an element to find.
+                return degradedStepResult(step, index, label);
+            }
+            if (subSteps !== undefined && subSteps.length > 0) {
+                return runSequenceStep(session, step, index, subSteps, confirmDangerous, sleep);
+            }
+            if (step.anchor.kind === AnchorKind.SIGNAL) {
+                return runSignalStep(session, step, index, label, waitForSignal, signalTimeoutMs, replayFloor);
+            }
+            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.
+                return runRoleStep(session, step, index, step.anchor, confirmDangerous, sleep);
+            }
+            return runTestidStep(session, step, index, label, dynamic, confirmDangerous, sleep);
+        });
+        // Once the anchor resolved and the action ran, the step's own expect is evaluated — signal, net,
+        // console and store truth alike — deterministically, in the same cheap replay loop, with no LLM.
+        const stepExpect = step.expect;
+        if (result.ok && result.drift === undefined && stepExpect !== undefined) {
+            const expectDrift = await assertStepExpect(session, stepExpect, dynamic, waitForSignal, signalTimeoutMs, cursorBefore);
+            if (expectDrift !== undefined) {
                 result.ok = false;
-                result.drift = stateDrift;
+                result.drift = expectDrift;
             }
         }
         if (page !== undefined)

package/dist/flows/flow-report.js

@@ -61,7 +61,7 @@ function evidenceList(steps) {
                 seen.add(part.trim());
         }
     }
-    if (seen.size === 0)
+    if (0 === seen.size)
         return '_No observable consequence captured._';
     return [...seen].map((e) => `- ${e}`).join('\n');
 }

package/dist/flows/flow-scope.d.ts

@@ -4,12 +4,7 @@
  * app's flows. These pure helpers pick the flows that belong on a given session's panel and shape them
  * into replay chips — testable without a bridge or a filesystem.
  */
-import { type FlowFile } from '@reticlehq/core';
-/** A replayable flow as the HUD renders it: a name + an optional page it can start from. */
-export interface FlowChip {
-    name: string;
-    start?: string;
-}
+import { type FlowChip, type FlowFile } from '@reticlehq/core';
 /**
  * A flow belongs on a session's HUD when it carries no projectId (legacy/global — visible everywhere
  * for back-compat) OR its projectId matches the connecting session's. A flow stamped for project A

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

@@ -8,16 +8,36 @@
  */
 import { AnchorKind, type FlowAnchor, type FlowStep, type FlowStepResult } from '@reticlehq/core';
 import type { FlowReplaySession, Sleep } from './flow-replay.js';
-/** Run one role+name-anchored step: re-resolve via QUERY by:'role', ACT on the live ref, else drift. */
 export declare function runRoleStep(session: FlowReplaySession, step: FlowStep, index: number, anchor: Extract<FlowAnchor, {
     kind: typeof AnchorKind.ROLE;
 }>, confirmDangerous: boolean, sleep: Sleep): Promise<FlowStepResult>;
-/**
- * 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): 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;
 }>, confirmDangerous: boolean, sleep: Sleep): Promise<FlowStepResult>;
+/**
+ * DEGRADED_ANCHOR_ROLE is a MARKER ("no anchor could be determined"), never a locator.
+ *
+ * Recognising it is most of the fix: a nameless-ROLE anchor used to fall through to the testid
+ * runner, which asked the DOM eight times for a testid literally named "unresolved", found none (it
+ * never exists), and reported a MISSING ELEMENT. It then ran edit-distance against the word
+ * "unresolved" and offered the nearest testid as a rebind target — which flow_verify printed while
+ * flow_heal refused it on confidence. Two tools contradicting each other over a candidate that never
+ * meant anything.
+ *
+ * Both recorders emit this sentinel, so the check belongs here on the replay side, where all of them
+ * land.
+ */
+export declare function isDegradedAnchor(anchor: FlowAnchor): boolean;
+export declare function degradedStepResult(step: FlowStep, index: number, label: string): FlowStepResult;
+/**
+ * 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
+ * execute identically.
+ *
+ * `replayFlow` had no sequence branch at all. It dispatches on `anchor.kind`, so a saved sequence fell
+ * to the testid runner and ran ONE act with `action: ''` (a saved sequence carries no top-level
+ * action) — sub-steps 2..n never executed. Fixing the anchor without this would have turned a visible
+ * drift into a silent partial replay reporting ok.
+ */
+export declare function runSequenceStep(session: FlowReplaySession, step: FlowStep, index: number, subs: readonly FlowStep[], confirmDangerous: boolean, sleep: Sleep): Promise<FlowStepResult>;

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

@@ -6,10 +6,12 @@
  * 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, DriftReason, QueryBy, ReticleCommand, } from '@reticlehq/core';
+import { AnchorKind, DEGRADED_ANCHOR_ROLE, DriftReason, QueryBy, ReticleCommand, } from '@reticlehq/core';
 import { ReticleTool } from '../tools/tool-names.js';
 import { replayActionArgs } from './replay.js';
-import { componentLabel, componentQueryArgs, resolveQuery } from './flow-replay.js';
+import { anchorLabel, componentLabel, componentQueryArgs, resolveQuery, testidDrift, } from './flow-replay.js';
+import { nearestRoleName } from './role-anchor-nearest.js';
+import { roleDriftReason } from './role-drift-reason.js';
 /** Query args for a NAMED role anchor — the handle that identifies an instance, not a JSX site. */
 function roleQueryArgs(anchor) {
     return {
@@ -19,11 +21,53 @@ function roleQueryArgs(anchor) {
     };
 }
 /** Run one role+name-anchored step: re-resolve via QUERY by:'role', ACT on the live ref, else drift. */
+/**
+ * The controls actually on the page, as role + name, for the nearest-match scan.
+ *
+ * Reads the interactive snapshot rather than a second query per candidate: one round trip, and it is
+ * the same view the coverage tool uses, so "what is on this page" has one definition.
+ */
+async function nearestRoleNameOnPage(session, anchor) {
+    const wanted = 'string' === typeof anchor.name ? anchor.name : undefined;
+    if (wanted === undefined)
+        return null;
+    try {
+        // Straight off the QUERY result: resolveQuery reduces to refs, and the NAMES are what this needs.
+        const result = await session.command(ReticleCommand.QUERY, {
+            by: QueryBy.ROLE,
+            value: anchor.role,
+        });
+        const payload = result.result;
+        const elements = 'object' === typeof payload && payload !== null
+            ? payload.elements
+            : undefined;
+        if (!Array.isArray(elements))
+            return null;
+        const candidates = elements
+            .map((element) => 'object' === typeof element && element !== null
+            ? element.name
+            : undefined)
+            .filter((name) => 'string' === typeof name && name.length > 0)
+            .map((name) => ({ role: anchor.role, name }));
+        return nearestRoleName(anchor.role, wanted, candidates);
+    }
+    catch {
+        // A drift report must never fail because the suggestion lookup did.
+        return null;
+    }
+}
 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];
     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
+        // about candidates, when nothing had looked. It looks now, and it is deliberately stricter than
+        // the testid path: a role name is user-visible text, so a near-match is far more likely to be a
+        // different control than a renamed one. A candidate here is INFORMATION for the agent; heal
+        // still refuses to rebind a role anchor on its own.
+        const nearest = await nearestRoleNameOnPage(session, anchor);
         return {
             step: index,
             tool: step.tool,
@@ -31,9 +75,9 @@ export async function runRoleStep(session, step, index, anchor, confirmDangerous
             ok: false,
             drift: {
                 reasonKind: DriftReason.COMPONENT_NOT_FOUND,
-                reason: `role anchor ${label} not found`,
+                reason: roleDriftReason(anchor.role, String(anchor.name), nearest),
                 anchor: label,
-                nearest: null,
+                nearest,
             },
         };
     }
@@ -43,7 +87,7 @@ export async function runRoleStep(session, step, index, anchor, confirmDangerous
  * 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 async function actOnResolvedRef(session, step, index, label, ref, confirmDangerous) {
+async function actOnResolvedRef(session, step, index, label, ref, confirmDangerous) {
     session.beginAction?.(ReticleTool.FLOW_REPLAY, { ref, action: step.action ?? '' });
     let act;
     try {
@@ -65,7 +109,7 @@ export async function actOnResolvedRef(session, step, index, label, ref, confirm
 export async function runComponentStep(session, step, index, anchor, confirmDangerous, sleep) {
     const label = componentLabel(anchor);
     const { refs } = await resolveQuery(session, componentQueryArgs(anchor), sleep);
-    if (refs.length === 0) {
+    if (0 === refs.length) {
         return {
             step: index,
             tool: step.tool,
@@ -100,3 +144,109 @@ export async function runComponentStep(session, step, index, anchor, confirmDang
         result.error = act.error ?? 'command failed';
     return result;
 }
+/**
+ * DEGRADED_ANCHOR_ROLE is a MARKER ("no anchor could be determined"), never a locator.
+ *
+ * Recognising it is most of the fix: a nameless-ROLE anchor used to fall through to the testid
+ * runner, which asked the DOM eight times for a testid literally named "unresolved", found none (it
+ * never exists), and reported a MISSING ELEMENT. It then ran edit-distance against the word
+ * "unresolved" and offered the nearest testid as a rebind target — which flow_verify printed while
+ * flow_heal refused it on confidence. Two tools contradicting each other over a candidate that never
+ * meant anything.
+ *
+ * Both recorders emit this sentinel, so the check belongs here on the replay side, where all of them
+ * land.
+ */
+export function isDegradedAnchor(anchor) {
+    return (anchor.kind === AnchorKind.ROLE &&
+        anchor.role === DEGRADED_ANCHOR_ROLE &&
+        anchor.name === undefined);
+}
+/** What a step with no resolvable anchor reports, instead of a missing-element story. */
+const DEGRADED_STEP_REASON = 'recorded without a resolvable anchor (no data-testid, no accessible role+name), so it can never ' +
+    'resolve on replay — add a data-testid to the element and record this flow again';
+export function degradedStepResult(step, index, label) {
+    return {
+        step: index,
+        tool: step.tool,
+        anchor: label,
+        ok: false,
+        drift: {
+            reasonKind: DriftReason.ANCHOR_DEGRADED,
+            reason: DEGRADED_STEP_REASON,
+            anchor: label,
+            // Deliberately null: the old path produced a nearest match to the WORD "unresolved", which is
+            // not a candidate for anything.
+            nearest: null,
+        },
+    };
+}
+/** QUERY args for an element anchor — null when the anchor addresses no element. */
+function anchorQueryArgs(anchor) {
+    if (anchor.kind === AnchorKind.TESTID)
+        return { by: QueryBy.TESTID, value: anchor.value };
+    if (anchor.kind === AnchorKind.COMPONENT)
+        return componentQueryArgs(anchor);
+    if (anchor.kind === AnchorKind.ROLE && !isDegradedAnchor(anchor))
+        return roleQueryArgs(anchor);
+    return null;
+}
+/**
+ * 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
+ * execute identically.
+ *
+ * `replayFlow` had no sequence branch at all. It dispatches on `anchor.kind`, so a saved sequence fell
+ * to the testid runner and ran ONE act with `action: ''` (a saved sequence carries no top-level
+ * action) — sub-steps 2..n never executed. Fixing the anchor without this would have turned a visible
+ * drift into a silent partial replay reporting ok.
+ */
+export async function runSequenceStep(session, step, index, subs, confirmDangerous, sleep) {
+    const live = [];
+    for (const [subIndex, sub] of subs.entries()) {
+        const label = `${anchorLabel(sub.anchor)} (sub-step ${String(subIndex)})`;
+        const queryArgs = anchorQueryArgs(sub.anchor);
+        if (null === queryArgs)
+            return degradedStepResult(step, index, label);
+        const { refs, hint } = await resolveQuery(session, queryArgs, sleep);
+        const ref = 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,
+                    },
+            };
+        }
+        live.push({
+            ref,
+            action: sub.action ?? '',
+            args: replayActionArgs(sub.args, confirmDangerous),
+        });
+    }
+    session.beginAction?.(ReticleTool.FLOW_REPLAY, { steps: live.length });
+    let act;
+    try {
+        act = await session.command(ReticleCommand.ACT_SEQUENCE, { steps: live });
+    }
+    finally {
+        session.finishAction?.();
+    }
+    const result = {
+        step: index,
+        tool: step.tool,
+        anchor: anchorLabel(step.anchor),
+        ok: act.ok,
+    };
+    if (!act.ok)
+        result.error = act.error ?? 'command failed';
+    return result;
+}

package/dist/flows/flow-success.js

@@ -12,7 +12,7 @@
  * tool and the `@reticlehq/test` spec runner share one implementation — no divergent oracle.
  * Pure: no IO, no clock.
  */
-import { AnchorKind } from '@reticlehq/core';
+import { AnchorKind, PredicateKind } from '@reticlehq/core';
 /** The dynamic (LLM-output) testids whose presence is never asserted — same rule replay uses. */
 export function dynamicTestids(flow) {
     return new Set((flow.dynamic ?? [])
@@ -28,7 +28,7 @@ export function successLabel(success) {
     if (success.net !== undefined)
         return success.net.urlContains ?? success.net.method ?? 'net';
     if (success.console !== undefined) {
-        return `console:${success.console.absent === true ? 'clean' : (success.console.level ?? 'error')}`;
+        return `console:${true === success.console.absent ? 'clean' : (success.console.level ?? 'error')}`;
     }
     if (success.state !== undefined)
         return `state:${success.state.path}`;
@@ -39,11 +39,11 @@ export function successToPredicate(success, dynamic) {
     const parts = [];
     if (success.signal !== undefined) {
         parts.push(success.signalData !== undefined
-            ? { kind: 'signal', name: success.signal, dataMatches: success.signalData }
-            : { kind: 'signal', name: success.signal });
+            ? { kind: PredicateKind.SIGNAL, name: success.signal, dataMatches: success.signalData }
+            : { kind: PredicateKind.SIGNAL, name: success.signal });
     }
     if (success.net !== undefined) {
-        const net = { kind: 'net' };
+        const net = { kind: PredicateKind.NET };
         if (success.net.method !== undefined)
             net.method = success.net.method;
         if (success.net.urlContains !== undefined)
@@ -56,12 +56,14 @@ export function successToPredicate(success, dynamic) {
             // exact count (e.g. 1) is transiently satisfied the instant the FIRST matching request lands —
             // before a double-submit's duplicate arrives. Gating on `settled` forces the count to be read
             // only after the network has gone quiet, so the duplicate IS counted and the over-count fails.
-            parts.push({ kind: 'settled' });
+            parts.push({ kind: PredicateKind.SETTLED });
         }
         parts.push(net);
     }
     if (success.console !== undefined) {
-        const con = { kind: 'console' };
+        const con = {
+            kind: PredicateKind.CONSOLE,
+        };
         if (success.console.level !== undefined)
             con.level = success.console.level;
         if (success.console.absent !== undefined) {
@@ -70,13 +72,16 @@ export function successToPredicate(success, dynamic) {
             // error yet" at the first poll and passes BEFORE the action's error fires. Gate on `settled` so
             // the console is read only after the page quiets, by which point any error is in the buffer.
             if (success.console.absent)
-                parts.push({ kind: 'settled' });
+                parts.push({ kind: PredicateKind.SETTLED });
         }
         parts.push(con);
     }
     const state = success.state;
     if (state !== undefined) {
-        const part = { kind: 'state', path: state.path };
+        const part = {
+            kind: PredicateKind.STATE,
+            path: state.path,
+        };
         if (state.store !== undefined)
             part.store = state.store;
         if (state.equals !== undefined)
@@ -85,8 +90,8 @@ export function successToPredicate(success, dynamic) {
         // wait-for-change. A wait-until-true waiter would pass the instant the path already equals the
         // value — which, for "an unrelated path stayed put", is true BEFORE a side-effect leak fires. Gate
         // on `settled` so the read happens after the page quiets, by which point the leak has landed.
-        if (state.hold === true)
-            parts.push({ kind: 'settled' });
+        if (true === state.hold)
+            parts.push({ kind: PredicateKind.SETTLED });
         parts.push(part);
     }
     const element = success.element;
@@ -102,15 +107,15 @@ export function successToPredicate(success, dynamic) {
             if (element.name !== undefined)
                 query['name'] = element.name;
             if (Object.keys(query).length > 0)
-                parts.push({ kind: 'element', query });
+                parts.push({ kind: PredicateKind.ELEMENT, query });
         }
     }
     const [first] = parts;
-    if (parts.length === 0)
+    if (0 === parts.length)
         return undefined;
-    if (parts.length === 1 && first !== undefined)
+    if (1 === parts.length && first !== undefined)
         return first;
-    return { kind: 'allOf', predicates: parts };
+    return { kind: PredicateKind.ALL_OF, predicates: parts };
 }
 /**
  * Assert a flow's success end-condition after replay. Delegates to the injected waitForSignal (the