@reticlehq/server 2.13.0 → 2.14.0

package/dist/flows/affected-tools.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { ReticleTool } from '../tools/tool-names.js';
 import { loadNamedFlows, resolveChangedFiles } from '../cli/cli-flow-commands.js';
+import { sessionRoot, sessionProjectId } from '../project/session-root.js';
 import { affectedSavedFlows } from './flow-sources.js';
 /**
  * `reticle_affected` — which saved flows must re-verify for a set of changed files.
@@ -43,20 +44,32 @@ export const AFFECTED_TOOLS = [
                 ? args['files'].filter((f) => 'string' === typeof f)
                 : [];
             const since = 'string' === typeof args['since'] ? args['since'] : undefined;
-            const changedFiles = await resolveChangedFiles(files, since);
-            const flows = await loadNamedFlows(deps.fs, deps.reticleRoot);
+            // Same address as verify_change, resolved the same way: `deps.reticleRoot` is the configured
+            // project directory (the daemon's cwd is not), and the session names which project's flows.
+            const changed = await resolveChangedFiles(files, since, deps.reticleRoot);
+            const changedFiles = changed.files;
+            // No `sessionId` on this tool's surface, and it does not need one: passing `undefined`
+            // resolves the single connected session, and falls back exactly as before when it cannot.
+            // Adding an argument here would be a surface change to fix an addressing bug.
+            const flows = await loadNamedFlows(deps.fs, sessionRoot(deps, undefined), sessionProjectId(deps, undefined));
             const result = affectedSavedFlows(flows, changedFiles);
             // Three different situations produced the same empty answer: no files changed, no flows saved,
             // and a git ref that resolved to nothing. Only the first means "nothing to re-verify"; the
             // others mean the question could not be answered, and re-running nothing on that basis is how a
             // regression ships. Say which one it is.
-            const why = 0 === flows.length
-                ? 'no saved flows exist yet, so nothing COULD be affected — record one with reticle_record then reticle_flow_save'
-                : 0 === changedFiles.length
-                    ? since === undefined && 0 === files.length
-                        ? 'no files were given and no `since` ref was passed, so nothing was compared — pass the files you edited, or a git ref'
-                        : 'nothing changed against that input, so no saved flow needs re-verifying'
-                    : undefined;
+            const why = 
+            // A git failure OUTRANKS every other explanation: the others describe a question that was
+            // answered, and this one is a question that was not. Reporting "nothing changed" over a
+            // mistyped ref or a shallow clone is how a regression ships past the tool meant to catch it.
+            changed.failed
+                ? `could not read the diff for \`${String(since)}\`, so NOTHING was compared and this result proves nothing: ${changed.reason ?? 'git failed'}`
+                : 0 === flows.length
+                    ? 'no saved flows exist yet, so nothing COULD be affected — record one with reticle_record then reticle_flow_save'
+                    : 0 === changedFiles.length
+                        ? since === undefined && 0 === files.length
+                            ? 'no files were given and no `since` ref was passed, so nothing was compared — pass the files you edited, or a git ref'
+                            : 'nothing changed against that input, so no saved flow needs re-verifying'
+                        : undefined;
             return {
                 changedFiles,
                 ...result,

package/dist/flows/annotate.d.ts

@@ -7,7 +7,8 @@ import { type Annotation, type AnnotateOutcome } from '@reticlehq/core';
  * assert-signal → step.expect.signal (+ signalData) on the LAST step (needs ≥1 step)
  * assert-visible → step.expect.element.testid on the LAST step (needs ≥1 step)
  * mark-dynamic → flow.dynamic[] += testid flow-level, allowed with 0 steps
- * success-state → flow.success = { signal | element } flow-level (signal XOR testid; both → signal)
+ * success-state → flow.success = { signal | state | net | console | element | text } flow-level,
+ *                 resolved in that precedence order (a consequence beats a presence check)
  *
  * FIRST CUT: only the four structured kinds above. Free natural-language annotation → predicate
  * compilation is explicitly FUTURE — an NL string never reaches here (AnnotationSchema

package/dist/flows/annotate.js

@@ -7,7 +7,8 @@ import { AnnotationErrorCode, AnnotationKind, AnnotationTarget, COMPILED_PREDICA
  * assert-signal → step.expect.signal (+ signalData) on the LAST step (needs ≥1 step)
  * assert-visible → step.expect.element.testid on the LAST step (needs ≥1 step)
  * mark-dynamic → flow.dynamic[] += testid flow-level, allowed with 0 steps
- * success-state → flow.success = { signal | element } flow-level (signal XOR testid; both → signal)
+ * success-state → flow.success = { signal | state | net | console | element | text } flow-level,
+ *                 resolved in that precedence order (a consequence beats a presence check)
  *
  * FIRST CUT: only the four structured kinds above. Free natural-language annotation → predicate
  * compilation is explicitly FUTURE — an NL string never reaches here (AnnotationSchema
@@ -73,6 +74,19 @@ export function compileAnnotation(a, stepCount) {
             if (a.testid !== undefined) {
                 return flowSuccess(a, { element: { testid: a.testid } });
             }
+            // Last, and above only MISSING_FIELD. An element is a locator and text is content; where a
+            // caller offered both, the locator is the more stable anchor. But text beats nothing at all,
+            // which is what an app whose only observable is a rendered value used to get (#811).
+            if (a.text !== undefined) {
+                const text = { contains: a.text.contains };
+                if (a.text.scope !== undefined)
+                    text.scope = a.text.scope;
+                if (a.text.absent !== undefined)
+                    text.absent = a.text.absent;
+                if (a.text.visible !== undefined)
+                    text.visible = a.text.visible;
+                return flowSuccess(a, { text });
+            }
             return { result: { ok: false, code: AnnotationErrorCode.MISSING_FIELD } };
         }
         case AnnotationKind.INTENT:
@@ -153,6 +167,10 @@ export function describeCompiled(a) {
                 const level = a.console.level ?? 'error';
                 return `${COMPILED_PREDICATE_PREFIX} succeed when ${true === a.console.absent ? `no console.${level}` : `console.${level}`}`;
             }
+            if (a.testid === undefined && a.text !== undefined) {
+                const where = a.text.scope === undefined ? '' : ` in ${a.text.scope}`;
+                return `${COMPILED_PREDICATE_PREFIX} succeed when ${true === a.text.absent ? 'text is gone:' : 'text shows:'} ${JSON.stringify(a.text.contains)}${where}`;
+            }
             return `${COMPILED_PREDICATE_PREFIX} succeed when ${a.testid ?? ''} visible`;
         case AnnotationKind.INTENT:
             return `${COMPILED_PREDICATE_PREFIX} intent: ${a.text}`;

package/dist/flows/coverage.d.ts

@@ -9,7 +9,7 @@ interface DeclaredSurface {
     signals: readonly string[];
     flows: readonly string[];
 }
-export interface CoverageDimension {
+interface CoverageDimension {
     total: number;
     covered: number;
     /**
@@ -34,7 +34,7 @@ export interface Coverage {
 /** The gate's outcome when the project has recorded no flows at all — not a pass, and not a failure. */
 export declare const NO_FLOWS = "no_flows";
 /** The gate's flow-coverage line. `pct` and `outcome` are mutually exclusive by construction. */
-export interface FlowCoverageReport {
+interface FlowCoverageReport {
     covered: number;
     total: number;
     pct?: number;

package/dist/flows/flake.d.ts

@@ -15,7 +15,7 @@ declare const FlakeRecordSchema: z.ZodObject<{
     runs: number;
     fails: number;
 }>;
-export type FlakeRecord = z.infer<typeof FlakeRecordSchema>;
+type FlakeRecord = z.infer<typeof FlakeRecordSchema>;
 /** Per-flow map (flow name → record). */
 export type FlakeLedger = Record<string, FlakeRecord>;
 export declare const FlakeFileSchema: z.ZodObject<{
@@ -31,17 +31,17 @@ export declare const FlakeFileSchema: z.ZodObject<{
         fails: number;
     }>>;
 }, "strip", z.ZodTypeAny, {
-    version: 1;
     flows: Record<string, {
         runs: number;
         fails: number;
     }>;
-}, {
     version: 1;
+}, {
     flows: Record<string, {
         runs: number;
         fails: number;
     }>;
+    version: 1;
 }>;
 export declare function emptyRecord(): FlakeRecord;
 /** Accrue one unchanged-code replay outcome. */

package/dist/flows/flow-expect-grammar.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Accept the assertion grammar a drive already uses, in a saved flow file.
+ *
+ * FlowExpect is a flat object (`signal` is a name string; `net`/`state` sit beside it). Agents write
+ * the `act_and_wait` shape instead — `{ kind: "allOf", predicates: [...] }`, or sibling channels
+ * with `signal: { name, count }` — and replay answered `flow_parse_failed` / "malformed". That sent
+ * people looking for a JSON syntax error in a file they had just written, and the workaround was to
+ * drop every channel but one.
+ *
+ * Coercion happens at load: the on-disk schema does not move, FLOW_FILE_VERSION stays 1, and a
+ * re-save writes the canonical shape. A kind a saved flow cannot enforce is refused, not stripped
+ * to an empty expect that would grade asserted-while-unchecked.
+ */
+import { type FlowFile } from '@reticlehq/core';
+import type { ZodError } from 'zod';
+import type { FlowResult } from './flows.js';
+export declare const FlowParseNote: {
+    readonly NOT_JSON: "flow file is not valid JSON — fix the syntax or regenerate it with reticle_flow_save";
+    readonly MALFORMED: "flow file is malformed — fix or regenerate it with reticle_flow_save";
+    readonly UNSUPPORTED_SHAPE: "valid JSON, unsupported expect shape";
+    readonly UNENFORCED: "valid JSON, but this expect uses a predicate kind a saved flow cannot enforce (settled, route, animation, anyOf, not)";
+};
+export type CoerceExpectResult = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    detail: string;
+};
+export declare function coerceFlowExpect(raw: unknown): CoerceExpectResult;
+export declare function coerceFlowFileExpects(raw: unknown): CoerceExpectResult;
+export declare function describeFlowZodFailure(error: ZodError): string;
+export declare function parseFlowFileText(text: string): FlowResult<FlowFile>;

package/dist/flows/flow-expect-grammar.js

@@ -0,0 +1,155 @@
+/**
+ * Accept the assertion grammar a drive already uses, in a saved flow file.
+ *
+ * FlowExpect is a flat object (`signal` is a name string; `net`/`state` sit beside it). Agents write
+ * the `act_and_wait` shape instead — `{ kind: "allOf", predicates: [...] }`, or sibling channels
+ * with `signal: { name, count }` — and replay answered `flow_parse_failed` / "malformed". That sent
+ * people looking for a JSON syntax error in a file they had just written, and the workaround was to
+ * drop every channel but one.
+ *
+ * Coercion happens at load: the on-disk schema does not move, FLOW_FILE_VERSION stays 1, and a
+ * re-save writes the canonical shape. A kind a saved flow cannot enforce is refused, not stripped
+ * to an empty expect that would grade asserted-while-unchecked.
+ */
+import { FlowErrorCode, FlowFileSchema } from '@reticlehq/core';
+import { PredicateSchema } from '../events/predicate.js';
+import { predicateToExpect } from './predicate-to-expect.js';
+export const FlowParseNote = {
+    NOT_JSON: 'flow file is not valid JSON — fix the syntax or regenerate it with reticle_flow_save',
+    MALFORMED: 'flow file is malformed — fix or regenerate it with reticle_flow_save',
+    UNSUPPORTED_SHAPE: 'valid JSON, unsupported expect shape',
+    UNENFORCED: 'valid JSON, but this expect uses a predicate kind a saved flow cannot enforce (settled, route, animation, anyOf, not)',
+};
+function isRecord(value) {
+    return 'object' === typeof value && null !== value && !Array.isArray(value);
+}
+/**
+ * Flatten `signal: { name, count }` into the on-disk fields. Other channels already match FlowExpect.
+ * Leave a signal object with no name alone so the schema failure can name the key.
+ */
+function flattenSignalObject(raw) {
+    const signal = raw['signal'];
+    if (!isRecord(signal))
+        return raw;
+    const name = signal['name'];
+    if ('string' !== typeof name)
+        return raw;
+    const out = { ...raw, signal: name };
+    if ('number' === typeof signal['count'])
+        out['signalCount'] = signal['count'];
+    if (undefined !== signal['dataMatches'])
+        out['signalData'] = signal['dataMatches'];
+    return out;
+}
+export function coerceFlowExpect(raw) {
+    if (isRecord(raw) && 'kind' in raw) {
+        const parsed = PredicateSchema.safeParse(raw);
+        if (!parsed.success) {
+            return { ok: false, detail: describePredicateExpectFailure(parsed.error) };
+        }
+        const expect = predicateToExpect(parsed.data);
+        if (undefined === expect)
+            return { ok: false, detail: FlowParseNote.UNENFORCED };
+        return { ok: true, value: expect };
+    }
+    if (!isRecord(raw))
+        return { ok: true, value: raw };
+    return { ok: true, value: flattenSignalObject(raw) };
+}
+function describePredicateExpectFailure(error) {
+    const issue = error.issues[0];
+    if (undefined === issue)
+        return FlowParseNote.UNSUPPORTED_SHAPE;
+    const key = issue.path[0];
+    if ('string' === typeof key || 'number' === typeof key) {
+        return `${FlowParseNote.UNSUPPORTED_SHAPE} key "${String(key)}"`;
+    }
+    return FlowParseNote.UNSUPPORTED_SHAPE;
+}
+export function coerceFlowFileExpects(raw) {
+    if (!isRecord(raw))
+        return { ok: true, value: raw };
+    const next = { ...raw };
+    const stepsIn = next['steps'];
+    if (Array.isArray(stepsIn)) {
+        const steps = [];
+        for (let i = 0; i < stepsIn.length; i++) {
+            const step = stepsIn[i];
+            if (!isRecord(step) || undefined === step['expect']) {
+                steps.push(step);
+                continue;
+            }
+            const coerced = coerceFlowExpect(step['expect']);
+            if (!coerced.ok) {
+                return {
+                    ok: false,
+                    detail: `${FlowParseNote.UNSUPPORTED_SHAPE} at step ${String(i)}: ${coerced.detail}`,
+                };
+            }
+            steps.push({ ...step, expect: coerced.value });
+        }
+        next['steps'] = steps;
+    }
+    if (undefined !== next['success']) {
+        const coerced = coerceFlowExpect(next['success']);
+        if (!coerced.ok) {
+            return {
+                ok: false,
+                detail: `${FlowParseNote.UNSUPPORTED_SHAPE} at success: ${coerced.detail}`,
+            };
+        }
+        next['success'] = coerced.value;
+    }
+    return { ok: true, value: next };
+}
+export function describeFlowZodFailure(error) {
+    const issue = error.issues[0];
+    if (undefined === issue)
+        return FlowParseNote.MALFORMED;
+    const path = issue.path;
+    // A strict object reports an unrecognized key as `unrecognized_keys` on the OBJECT's path, with
+    // the offending names in `keys` — not as an issue whose path ends in the key. Reading only the
+    // path shape reported the one failure this exists to name as a bare "malformed", which sends the
+    // author back to the file to find a typo we had already identified.
+    if ('unrecognized_keys' === issue.code) {
+        const named = issue.keys.map((k) => `"${k}"`).join(', ');
+        if ('steps' === path[0] && 'number' === typeof path[1] && 'expect' === path[2]) {
+            return `${FlowParseNote.UNSUPPORTED_SHAPE} at step ${String(path[1])} key ${named}`;
+        }
+        if ('success' === path[0])
+            return `${FlowParseNote.UNSUPPORTED_SHAPE} at success key ${named}`;
+        return `${FlowParseNote.UNSUPPORTED_SHAPE} — unrecognized key ${named}`;
+    }
+    if ('steps' === path[0] &&
+        'number' === typeof path[1] &&
+        'expect' === path[2] &&
+        'string' === typeof path[3]) {
+        return `${FlowParseNote.UNSUPPORTED_SHAPE} at step ${String(path[1])} key "${path[3]}"`;
+    }
+    if ('success' === path[0] && 'string' === typeof path[1]) {
+        return `${FlowParseNote.UNSUPPORTED_SHAPE} at success key "${path[1]}"`;
+    }
+    return FlowParseNote.MALFORMED;
+}
+export function parseFlowFileText(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return { ok: false, code: FlowErrorCode.PARSE_FAILED, detail: FlowParseNote.NOT_JSON };
+    }
+    const coerced = coerceFlowFileExpects(parsed);
+    if (!coerced.ok) {
+        return { ok: false, code: FlowErrorCode.PARSE_FAILED, detail: coerced.detail };
+    }
+    const result = FlowFileSchema.safeParse(coerced.value);
+    if (!result.success) {
+        return {
+            ok: false,
+            code: FlowErrorCode.PARSE_FAILED,
+            detail: describeFlowZodFailure(result.error),
+        };
+    }
+    return { ok: true, value: result.data };
+}

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

@@ -8,7 +8,7 @@ export declare function latestRecordedFlow(events: ReticleEvent[]): {
     flow: import('@reticlehq/core').FlowFile;
 } | undefined;
 /** Map a structured FlowErrorCode to a legible one-line message for the agent. */
-export declare function flowErrorMessage(code: FlowErrorCode): string;
+export declare function flowErrorMessage(code: FlowErrorCode, detail?: string): string;
 /** The slice of a session the start-path logic reads: the live URL plus the event buffer. */
 interface StartPathSession {
     url?: string;

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

@@ -1,5 +1,8 @@
+import { resolveFlowUploads } from './flow-upload-resolve.js';
 import { EventType, FLOW_SIGNAL_TIMEOUT_MS, FlowErrorCode, RecordedFlowSchema, ReplayStatus, ReticleCommand, RunKind, RunStatus, } from '@reticlehq/core';
+import { haltedFrom } from './replay-halt.js';
 import { asRecord, asString } from '../tools/tools-helpers.js';
+import { routeOfEvent, routeOfUrl } from '../events/predicate-route.js';
 import { carryReticleIdentity } from '../tools/lease-tools.js';
 import { replayFlow } from './flow-replay.js';
 import { anchorQueryArgs } from './flow-step-runners.js';
@@ -22,6 +25,7 @@ import { resolveProjectCloud } from '../cloud/cloud-config.js';
 import { consultSubjectFor, selectConsulted } from './flow-memory-consult.js';
 import { log } from '../log.js';
 import { flowsForSession } from './flow-store-for-session.js';
+import { FlowParseNote } from './flow-expect-grammar.js';
 export function latestRecordedFlow(events) {
     for (let i = events.length - 1; i >= 0; i--) {
         const event = events[i];
@@ -34,14 +38,16 @@ export function latestRecordedFlow(events) {
     return undefined;
 }
 /** Map a structured FlowErrorCode to a legible one-line message for the agent. */
-export function flowErrorMessage(code) {
+export function flowErrorMessage(code, detail) {
+    if (FlowErrorCode.PARSE_FAILED === 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 'flow file is malformed — fix or regenerate it with reticle_flow_save';
+            return FlowParseNote.MALFORMED;
         case FlowErrorCode.NO_RECORDING:
             return 'no compiled recording by that name — record one (reticle_record{action:"start"|"stop"}) first';
     }
@@ -93,22 +99,17 @@ recordRoot) {
  */
 function currentPathOf(session) {
     const routes = session.eventsSince(0).filter((e) => e.type === EventType.ROUTE_CHANGE);
-    const data = routes.at(-1)?.data ?? {};
+    const last = routes.at(-1);
     // pathname + hash, because `startPath` is compared against this and must stay NAVIGABLE. Reading
     // the pathname alone made both sides `/` on a hash router — always "same path", so the hint never
     // fired however far the tab had drifted, on the router desktop renderers use by default.
-    const observed = asString(data['pathname']) ?? asString(data['to']);
+    const observed = last === undefined ? undefined : routeOfEvent(last);
     if (observed !== undefined)
-        return `${observed}${asString(data['hash']) ?? ''}`;
+        return `${observed.docPath}${observed.hash}`;
     if (session.url === undefined)
         return undefined;
-    try {
-        const parsed = new URL(session.url);
-        return `${parsed.pathname}${parsed.hash}`;
-    }
-    catch {
-        return undefined;
-    }
+    const fromUrl = routeOfUrl(session.url);
+    return fromUrl === undefined ? undefined : `${fromUrl.docPath}${fromUrl.hash}`;
 }
 /** Pathname equality up to a trailing slash — a router normalising one must not read as "elsewhere". */
 function samePath(a, b) {
@@ -318,7 +319,7 @@ export async function replayNamedFlow(deps, args) {
             name,
             status: ReplayStatus.ERROR,
             steps: [],
-            error: { code: loaded.code, message: flowErrorMessage(loaded.code) },
+            error: { code: loaded.code, message: flowErrorMessage(loaded.code, loaded.detail) },
         };
     }
     // What this flow is FOR, from the shared ledger — so a failure can report the business outcome
@@ -341,13 +342,23 @@ 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, true === args['confirmDangerous']);
+    // A recorded upload names a path on disk; the browser can only take bytes. Resolved once, before
+    // step 1, through the same helper the live `reticle_act` uses. See resolveFlowUploads.
+    const replayable = await resolveFlowUploads(deps, loaded.value);
+    const steps = await replayFlow(session, replayable, waitForPredicate, FLOW_SIGNAL_TIMEOUT_MS, true === args['confirmDangerous']);
+    // Computed HERE, before the synthetic success row is appended below: once that row is pushed,
+    // `steps.length` no longer counts only the flow's own steps and the arithmetic is wrong.
+    const halted = haltedFrom(steps, loaded.value.steps.length);
     // "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.
     const stepsClean = steps.length > 0 && steps.every((s) => s.ok && s.drift === undefined);
     if (stepsClean && loaded.value.success !== undefined) {
-        const verdict = await assertSuccess(session, loaded.value.success, dynamicTestids(loaded.value), waitForPredicate, FLOW_SIGNAL_TIMEOUT_MS, replayFloor);
+        const verdict = await assertSuccess(session, loaded.value.success, dynamicTestids(loaded.value), waitForPredicate, 
+        // The flow's own declaration, not the built-in floor: an app slow enough to need a longer
+        // step wait is slow enough that its OUTCOME lands late too, and greening every step only to
+        // fail the success oracle at 4s is the same false red one layer down.
+        loaded.value.signalTimeoutMs ?? FLOW_SIGNAL_TIMEOUT_MS, replayFloor);
         const row = {
             step: steps.length,
             tool: SUCCESS_STEP_TOOL,
@@ -412,6 +423,8 @@ export async function replayNamedFlow(deps, args) {
         return errored;
     }
     const result = { name, status, steps };
+    if (halted !== undefined)
+        result.halted = halted;
     if (knows !== undefined)
         result.knows = knows;
     // A green that cannot go red is not a pass. `reticle_flow_verify` already refuses to count these,

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

@@ -49,6 +49,16 @@ export type Sleep = (ms: number) => Promise<void>;
 export declare function nearestIsAmbiguous(missing: string, present: string[]): boolean;
 /** 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;
+/**
+ * Build the drift for a step whose `expect.element` testid was absent after the action ran.
+ *
+ * Deliberately not `testidDrift`: that one means "this step's anchor is gone", and reusing it here
+ * put the assertion's target in the result's `anchor` field — the field documented as the value the
+ * step is bound to. A caller then reads `testid_not_found` naming something that was never the
+ * step's locator and goes hunting for a rename, while the truth is the step ran and its
+ * consequence did not hold.
+ */
+export declare function expectElementDrift(value: string, hint: QueryEmptyHint | undefined): Drift;
 export declare function resolveQuery(session: FlowReplaySession, queryArgs: Record<string, unknown>, sleep: Sleep, now?: () => number): Promise<{
     refs: string[];
     hint?: QueryEmptyHint;

package/dist/flows/flow-replay.js

@@ -1,8 +1,9 @@
 import { span } from '../trace.js';
-import { routePathOf } from '../events/predicate-route.js';
+import { routeOfEvent } from '../events/predicate-route.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 { anchorFieldName } from './flow-secret-field.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';
@@ -138,6 +139,27 @@ export function testidDrift(value, hint) {
         drift.ambiguous = true;
     return drift;
 }
+/**
+ * Build the drift for a step whose `expect.element` testid was absent after the action ran.
+ *
+ * Deliberately not `testidDrift`: that one means "this step's anchor is gone", and reusing it here
+ * put the assertion's target in the result's `anchor` field — the field documented as the value the
+ * step is bound to. A caller then reads `testid_not_found` naming something that was never the
+ * step's locator and goes hunting for a rename, while the truth is the step ran and its
+ * consequence did not hold.
+ */
+export function expectElementDrift(value, hint) {
+    const present = hint?.presentTestids ?? [];
+    const drift = {
+        reasonKind: DriftReason.EXPECT_ELEMENT_NOT_FOUND,
+        reason: `expect.element testid "${value}" not present after the action`,
+        anchor: value,
+        nearest: nearestTestid(value, present),
+    };
+    if (nearestIsAmbiguous(value, present))
+        drift.ambiguous = true;
+    return drift;
+}
 /**
  * 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,
@@ -198,15 +220,13 @@ function currentRoute(session) {
     const last = routes.at(-1);
     if (last === undefined)
         return undefined;
-    const data = last.data ?? {};
     // 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 routePathOf.
-    const pathname = asString(data['pathname']) ?? asString(data['to']);
-    if (pathname === undefined || 0 === pathname.length)
+    // every step. Sixth place the same reading was wrong; see routeOfEvent.
+    const parts = routeOfEvent(last);
+    if (parts === undefined || 0 === parts.docPath.length)
         return undefined;
-    const routed = routePathOf(pathname, asString(data['hash']) ?? '');
-    return routed.length > 0 ? routed : undefined;
+    return parts.routePath.length > 0 ? parts.routePath : undefined;
 }
 /** Pathname only (drop origin + query) so a net URL stays terse in the journey. */
 function trimUrl(url) {
@@ -226,10 +246,9 @@ function summarizeConsequence(events) {
     const parts = [];
     const lastRoute = events.filter((e) => e.type === EventType.ROUTE_CHANGE).at(-1);
     if (lastRoute !== undefined) {
-        const data = lastRoute.data ?? {};
-        const to = asString(data['pathname']) ?? asString(data['to']);
-        if (to !== undefined && to.length > 0)
-            parts.push(`→ ${to}`);
+        const routed = routeOfEvent(lastRoute);
+        if (routed !== undefined && routed.routePath.length > 0)
+            parts.push(`→ ${routed.routePath}`);
     }
     const signals = new Set();
     for (const e of events) {
@@ -301,9 +320,11 @@ async function runTestidStep(session, step, index, value, dynamic, confirmDanger
         act = await session.command(ReticleCommand.ACT, {
             ref,
             action: step.action ?? '',
-            // `value` is the anchor's own name — the field this step types into — so a redacted fill can
-            // be supplied from RETICLE_SECRET_<FIELD> without the flow carrying the secret.
-            args: replayActionArgs(step.args, confirmDangerous, value),
+            // 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 {
@@ -326,9 +347,12 @@ async function runTestidStep(session, step, index, value, dynamic, confirmDanger
             return {
                 step: index,
                 tool: step.tool,
-                anchor: expectTestid,
+                // The step's OWN anchor, not the expectation's target. Replay stops at the first drift, so
+                // this result is the only thing the caller sees about why the run ended — naming the
+                // assertion here reads as "step N's locator drifted" and hides that the action did run.
+                anchor: value,
                 ok: false,
-                drift: testidDrift(expectTestid, expectRefs.hint),
+                drift: expectElementDrift(expectTestid, expectRefs.hint),
             };
         }
     }
@@ -350,10 +374,13 @@ async function runTestidStep(session, step, index, value, dynamic, confirmDanger
  * nothing was looking.
  */
 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;
+    // 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);
     if (predicate === undefined)
         return undefined;
@@ -379,6 +406,9 @@ function expectLabel(expect) {
         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). */
@@ -423,6 +453,11 @@ export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs,
     // Floor for signal steps: signals that fire during THIS replay, never a prior flow/run in the same
     // session. Captured once, before any step, so a back-to-back suite verify cannot cross-satisfy.
     const replayFloor = session.elapsed();
+    // How long a step waits for its consequence: the step's own declaration, else the flow's, else the
+    // caller's default. Resolved per step rather than once, because one slow step in an otherwise fast
+    // journey is the common shape — a file import, a model-backed endpoint — and making the whole flow
+    // wait for the slowest step would trade a false red for a slow suite. See FlowStep.timeoutMs.
+    const waitFor = (step) => step.timeoutMs ?? flow.signalTimeoutMs ?? signalTimeoutMs;
     let index = 0;
     for (const step of flow.steps) {
         const label = anchorLabel(step.anchor);
@@ -443,7 +478,7 @@ export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs,
                 return runSequenceStep(session, step, index, subSteps, confirmDangerous, sleep);
             }
             if (step.anchor.kind === AnchorKind.SIGNAL) {
-                return runSignalStep(session, step, index, label, waitForSignal, signalTimeoutMs, replayFloor);
+                return runSignalStep(session, step, index, label, waitForSignal, waitFor(step), replayFloor);
             }
             if (step.anchor.kind === AnchorKind.COMPONENT) {
                 return runComponentStep(session, step, index, step.anchor, confirmDangerous, sleep);
@@ -459,7 +494,7 @@ export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs,
         // 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);
+            const expectDrift = await assertStepExpect(session, stepExpect, dynamic, waitForSignal, waitFor(step), cursorBefore);
             if (expectDrift !== undefined) {
                 result.ok = false;
                 result.drift = expectDrift;