@reticlehq/server 2.3.0 → 2.5.0

package/dist/flows/decision.js

@@ -1,5 +1,5 @@
 import { AnchorKind, ReplayStatus, } from '@reticlehq/core';
-import { classifyFlowAssertions } from './flow-classify.js';
+import { classifyFlowAssertions, FlowAssertionGrade } from './flow-classify.js';
 import { SUCCESS_STEP_TOOL } from './flow-success.js';
 /**
  * Turn a replay result into the autonomy DECISION envelope — the judgement a human reviewer used to
@@ -35,7 +35,7 @@ export function buildDecision(result, flow) {
         // Green — but is it green-for-the-right-reason? A flow that asserts no consequence can pass while
         // broken, so the honest next action is to add one.
         const grade = flow !== undefined ? classifyFlowAssertions(flow) : undefined;
-        const verifiesOutcome = grade?.hasConsequenceAssertion === true;
+        const verifiesOutcome = true === grade?.hasConsequenceAssertion;
         const intent = flow?.intent;
         return {
             verdict: 'pass',
@@ -92,16 +92,51 @@ function suiteVerdictOf(status) {
  * decision-annotated replay results + their flows. Passing flows are counted; only failures carry
  * detail (token-cheap), each with the actionable decision so the agent fixes without re-querying.
  */
+/**
+ * Why a green replay still verified nothing, or undefined when it genuinely did.
+ *
+ * A flow with no steps, or one that asserts no observable consequence, replays green no matter what
+ * the app does — the grader already knows this at save time and says so. Counting it as `passed`
+ * turned that warning into "all 1 flow pass", which is a false green in the exact feature sold as
+ * the regression suite. Classified only when the flow file is available; never guessed.
+ */
+function unverifiableReason(flow) {
+    if (flow === undefined)
+        return undefined;
+    if (0 === flow.steps.length) {
+        return 'the flow has no steps — it replays green whatever the app does. Record it again, or add steps with reticle_annotate.';
+    }
+    const c = classifyFlowAssertions(flow);
+    if (c.grade !== FlowAssertionGrade.ASSERTION_FREE)
+        return undefined;
+    return (c.warning ??
+        'the flow asserts no observable consequence, so it passes even when the feature is broken.');
+}
 export function buildSuiteVerdict(runs) {
     const failures = [];
+    const unverifiable = [];
     let passed = 0;
     for (const { replay, flow } of runs) {
         if (replay.status === ReplayStatus.OK) {
-            passed += 1;
+            const reason = unverifiableReason(flow);
+            // A green that cannot go red is not a pass. Counted apart, so `passed` stays a count of things
+            // actually verified rather than of replays that merely completed.
+            if (reason !== undefined)
+                unverifiable.push({ flow: replay.name, reason });
+            else
+                passed += 1;
             continue;
         }
         const decision = replay.decision ?? buildDecision(replay, flow);
         const row = { flow: replay.name, verdict: suiteVerdictOf(replay.status) };
+        // Zero step results PLUS an error is the signature of a replay that never STARTED — the flow file
+        // failed to load (before the session is even resolved), or its leased context never came up. A
+        // flow that ran and failed always carries its failing step; a flow with no steps replays OK and
+        // never reaches here. Both arrive as ReplayStatus.ERROR, so without this the suite cannot tell
+        // "the app broke" from "Reticle could not run this" — and the bug metric reported the second as
+        // the first, 8 times in one sweep.
+        if (0 === replay.steps.length && replay.error !== undefined)
+            row.couldNotRun = true;
         if (decision.whatChanged !== undefined)
             row.whatChanged = decision.whatChanged;
         if (decision.whereInSource !== undefined)
@@ -111,9 +146,30 @@ export function buildSuiteVerdict(runs) {
     }
     const total = runs.length;
     const failed = failures.length;
-    const status = failed === 0 ? 'pass' : 'fail';
-    const summary = failed === 0
-        ? `all ${total} flow${total === 1 ? '' : 's'} pass`
-        : `${passed}/${total} flows pass — ${failed} need attention: ${failures.map((f) => f.flow).join(', ')}`;
-    return { status, total, passed, failed, summary, failures };
+    // A real failure outranks an unverifiable flow: a broken flow is worse news than an empty one.
+    // An EMPTY suite is unverifiable for the same reason a flow that asserts nothing is — it is the
+    // purest green that cannot go red. It used to report `pass` with the summary "all 0 flows pass",
+    // which meant `reticle verify` went green on every project that had not written a flow yet, and on
+    // any project where the flows directory failed to resolve. Found by the adversarial MCP sweep; it
+    // was the only invented answer in 994 calls.
+    const status = failed > 0 ? 'fail' : unverifiable.length > 0 || 0 === total ? 'unverifiable' : 'pass';
+    const cannotFail = 0 === unverifiable.length
+        ? ''
+        : ` — ${String(unverifiable.length)} verified nothing (${unverifiable.map((u) => u.flow).join(', ')})`;
+    const summary = 0 === total
+        ? 'no flows to verify — nothing was checked. Record one with reticle_record { action: "start" }, then reticle_flow_save.'
+        : 0 === failed
+            ? 0 === unverifiable.length
+                ? `all ${total} flow${1 === total ? '' : 's'} pass`
+                : `${String(passed)}/${String(total)} flows verified${cannotFail}`
+            : `${passed}/${total} flows pass — ${failed} need attention: ${failures.map((f) => f.flow).join(', ')}${cannotFail}`;
+    return {
+        status,
+        total,
+        passed,
+        failed,
+        summary,
+        failures,
+        ...(unverifiable.length > 0 ? { unverifiable } : {}),
+    };
 }

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

@@ -0,0 +1,6 @@
+interface EmptyFlowRefusal {
+    error: string;
+    recovery: string;
+}
+export declare function emptyFlowRefusal(stepCount: number, name: string): EmptyFlowRefusal | undefined;
+export {};

package/dist/flows/empty-flow.js

@@ -0,0 +1,24 @@
+/**
+ * Refuse to save a flow with no steps.
+ *
+ * It used to succeed: `flow_save` returned `{ stepCount: 0, grade: "assertion-free" }` with no error,
+ * `flow_list` then showed one more flow, and `flow_verify` called it `unverifiable` — forever. The
+ * agent believes it saved a regression test; what it wrote is a permanent suite entry that can never
+ * go green or red.
+ *
+ * Zero steps is not a degraded flow, it is the absence of one. And the refusal matters most on the
+ * stacks where the recorder is known to capture nothing, because there the empty save is the only
+ * signal the agent would ever get that something went wrong.
+ */
+import { ReticleTool } from '../tools/tool-names.js';
+export function emptyFlowRefusal(stepCount, name) {
+    if (stepCount > 0)
+        return undefined;
+    return {
+        error: `'${name}' has no steps, so there is nothing to save — a flow with no steps can never pass or fail, and would sit in the suite reporting "unverifiable" forever`,
+        recovery: `Nothing was captured between ${ReticleTool.RECORD} { action: "start" } and { action: "stop" }. ` +
+            `Drive at least one action with ${ReticleTool.ACT} or ${ReticleTool.ACT_AND_WAIT} while the ` +
+            `recording is open, then save. If you DID act and this still says zero, the recorder captured ` +
+            `nothing for this stack — report it with ${ReticleTool.FEEDBACK}.`,
+    };
+}

package/dist/flows/flake-store.d.ts

@@ -1,6 +1,5 @@
 import type { FileSystemPort } from '../project/fs-port.js';
 import { type FlakeLedger } from './flake.js';
-export declare const FLAKE_FILE_VERSION = 1;
 /**
  * Persists the per-flow flake ledger at `.reticle/flake.json`. Local single-project memory (stays OSS —
  * OSS-VS-SERVER). Loads never throw: missing/malformed/wrong-version degrades to an empty ledger, so

package/dist/flows/flake-store.js

@@ -1,7 +1,7 @@
 import { dirname } from 'node:path';
 import { reticleDirPaths } from '../project/reticle-dir.js';
 import { FlakeFileSchema, emptyRecord, isFlaky, recordOutcome } from './flake.js';
-export const FLAKE_FILE_VERSION = 1;
+const FLAKE_FILE_VERSION = 1;
 /**
  * Persists the per-flow flake ledger at `.reticle/flake.json`. Local single-project memory (stays OSS —
  * OSS-VS-SERVER). Loads never throw: missing/malformed/wrong-version degrades to an empty ledger, so

package/dist/flows/flake.d.ts

@@ -5,7 +5,7 @@ import { z } from 'zod';
  * (excluded from gate-blocking) and surfaced for repair, never silently blocking. The caller accrues an
  * outcome ONLY for unchanged-code replays (a fail after a code change is a legitimate red, not flake).
  */
-export declare const FlakeRecordSchema: z.ZodObject<{
+declare const FlakeRecordSchema: z.ZodObject<{
     runs: z.ZodNumber;
     fails: z.ZodNumber;
 }, "strip", z.ZodTypeAny, {
@@ -55,3 +55,4 @@ export declare function recordOutcome(record: FlakeRecord, passed: boolean): Fla
 export declare function isFlaky(record: FlakeRecord, minRuns?: number): boolean;
 /** Observed intermittent-failure rate (0 when too few runs to judge). */
 export declare function flakeRate(record: FlakeRecord): number;
+export {};

package/dist/flows/flake.js

@@ -5,7 +5,7 @@ import { z } from 'zod';
  * (excluded from gate-blocking) and surfaced for repair, never silently blocking. The caller accrues an
  * outcome ONLY for unchanged-code replays (a fail after a code change is a legitimate red, not flake).
  */
-export const FlakeRecordSchema = z.object({
+const FlakeRecordSchema = z.object({
     runs: z.number().int().min(0),
     fails: z.number().int().min(0),
 });
@@ -31,5 +31,5 @@ export function isFlaky(record, minRuns = DEFAULT_MIN_FLAKE_RUNS) {
 }
 /** Observed intermittent-failure rate (0 when too few runs to judge). */
 export function flakeRate(record) {
-    return record.runs === 0 ? 0 : record.fails / record.runs;
+    return 0 === record.runs ? 0 : record.fails / record.runs;
 }

package/dist/flows/flow-classify.js

@@ -33,6 +33,18 @@ const INTENT_WITHOUT_OUTCOME_WARNING = 'This flow declares a business intent but
 // Consequence vs presence-only classification lives in @reticlehq/core (one source for all graders).
 const expectIsConsequence = flowExpectHasConsequence;
 const expectIsWeak = flowExpectIsPresenceOnly;
+/**
+ * A step expect counts the same as a flow-level one, because replay now evaluates the same set.
+ *
+ * This was briefly narrowed to `state` only — correctly, at the time: replay checked element presence
+ * and state and nothing else, so grading a step signal/net as a consequence produced a flow that
+ * reported `grade: "asserted"` and could not go red. `assertStepExpect` closed that by compiling
+ * every step expect through the same `successToPredicate` the flow-level path uses, so the narrow
+ * rule is no longer true and would now UNDER-grade real assertions.
+ *
+ * The invariant to keep: this function and what replay enforces must move together. If one ever
+ * describes more than the other, the difference is a false green or a lost verification.
+ */
 /** Walk steps + act_sequence sub-steps so an expect on either level is counted. */
 function flattenSteps(steps) {
     const out = [];

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

@@ -64,7 +64,7 @@ async function recordReplayRun(deps, name, status, driftSteps, durationMs, proje
     });
     // Per-project cloud: push memory outcomes only when cloud is attached AND memory sync is enabled.
     const cloud = await resolveProjectCloud(deps.fs, deps.reticleRoot, homedir(), process.env);
-    if (cloud.config === null || !cloud.policy.memory)
+    if (null === cloud.config || !cloud.policy.memory)
         return; // not attached / memory disabled → local only
     const result = await syncRunRecordToCloud({ kind: RunKind.FLOW_REPLAY, name, status: runStatus, at: deps.now(), durationMs }, projectId, cloud.config, (url, init) => fetch(url, init));
     if (result.outcome !== SyncOutcome.SYNCED) {
@@ -82,7 +82,7 @@ async function recordReplayRun(deps, name, status, driftSteps, durationMs, proje
  */
 export function startPathMismatchHint(flow, session) {
     const startPath = flow.startPath;
-    if (startPath === undefined || startPath.length === 0)
+    if (startPath === undefined || 0 === startPath.length)
         return undefined;
     const routes = session.eventsSince(0).filter((e) => e.type === EventType.ROUTE_CHANGE);
     const last = routes.at(-1);
@@ -127,7 +127,7 @@ export async function replayNamedFlow(deps, args) {
     // Floor the success oracle at the start of THIS replay so a stale signal from a prior run
     // in the same session can't fake a pass.
     const replayFloor = session.elapsed();
-    const steps = await replayFlow(session, loaded.value, waitForPredicate, FLOW_SIGNAL_TIMEOUT_MS, args['confirmDangerous'] === true);
+    const steps = await replayFlow(session, loaded.value, waitForPredicate, FLOW_SIGNAL_TIMEOUT_MS, true === args['confirmDangerous']);
     // "green means intent satisfied": when every step ran clean, assert the flow's success
     // end-condition as a real consequence. A signal/net success that never fires FAILS the replay
     // even though all locators resolved — the regression a healed-but-wrong locator ships green.
@@ -188,7 +188,7 @@ export async function replayNamedFlow(deps, args) {
 async function computeReplayDeviation(deps, session, floor) {
     try {
         const segments = computeSegments(session.eventsSince(floor));
-        if (segments.length === 0)
+        if (0 === segments.length)
             return undefined;
         return await reportAndAccumulate(new EnvelopeStore(deps.fs, deps.reticleRoot), segments);
     }

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

@@ -1,4 +1,4 @@
-import { AnchorKind, type CommandResult, type FlowAnchor, type FlowFile, type FlowStepResult, type ReticleEvent, type QueryEmptyHint } from '@reticlehq/core';
+import { AnchorKind, type CommandResult, type Drift, type FlowAnchor, type FlowFile, type FlowStepResult, type ReticleEvent, type QueryEmptyHint } from '@reticlehq/core';
 import type { EvalResult, Predicate } from '../events/predicate.js';
 /**
  * The session surface flow-replay needs: QUERY to re-resolve a testid anchor against the live
@@ -47,12 +47,8 @@ export type Sleep = (ms: number) => Promise<void>;
  * Such a drift is surfaced (with a nearest) but never auto-healed.
  */
 export declare function nearestIsAmbiguous(missing: string, present: string[]): boolean;
-/**
- * Re-resolve any QUERY against the live DOM, tolerating an in-flight render: QUERY, and while it
- * returns zero refs, sleep and retry up to ANCHOR_SETTLE_ATTEMPTS. Returns as soon as refs appear,
- * 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.
- */
+/** Build the legible-drift record for a testid anchor that resolved to zero live elements. */
+export declare function testidDrift(value: string, hint: QueryEmptyHint | undefined): Drift;
 export declare function resolveQuery(session: FlowReplaySession, queryArgs: Record<string, unknown>, sleep: Sleep): Promise<{
     refs: string[];
     hint?: QueryEmptyHint;
@@ -61,6 +57,8 @@ export declare function resolveQuery(session: FlowReplaySession, queryArgs: Reco
 export declare function componentLabel(anchor: Extract<FlowAnchor, {
     kind: typeof AnchorKind.COMPONENT;
 }>): string;
+/** The value of a step's primary anchor, for labelling the result row. */
+export declare function anchorLabel(anchor: FlowAnchor): string;
 /** QUERY args for a component auto-anchor — source (precise) + component name (coarse) as given. */
 export declare function componentQueryArgs(anchor: Extract<FlowAnchor, {
     kind: typeof AnchorKind.COMPONENT;

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.
@@ -67,10 +69,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 +80,7 @@ function readQuery(result) {
                 route: asString(hint['route']) ?? '',
                 presentTestids: present,
                 presentRegions: [],
-                knownEmptyState: hint['knownEmptyState'] === true,
+                knownEmptyState: true === hint['knownEmptyState'],
             },
         };
     }
@@ -107,7 +109,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 +127,41 @@ 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.
  */
+/**
+ * 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) {
     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);
+    for (let attempt = 1; 0 === last.refs.length && attempt < ANCHOR_SETTLE_ATTEMPTS; attempt += 1) {
+        await settleTick(session, sleep);
         last = readQuery(await session.command(ReticleCommand.QUERY, queryArgs));
     }
     return last;
@@ -188,7 +221,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 +239,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 +260,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 +296,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 +311,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 +366,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 +404,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>;