@reticlehq/server 2.13.0 → 2.14.0

package/dist/flows/flow-secret-field.d.ts

@@ -0,0 +1,14 @@
+import { type FlowAnchor } from '@reticlehq/core';
+/**
+ * What the anchor CALLS the field it points at.
+ *
+ * Every anchor kind names its target differently and all of them can name a password: a testid
+ * (auth-password), an accessible name (role=textbox, name="Password"), a signal. Checking only the
+ * testid variant would redact the app that uses test ids and quietly leak the one that does not —
+ * and an app without test ids is exactly the app whose flows were recorded by role.
+ *
+ * Save and replay MUST share this. Redaction keys off the field name; substitution looks up
+ * `RETICLE_SECRET_<FIELD>` from the same string. Two copies would redact `Password` and then fail
+ * to find the env var because the runner passed a role or a label instead.
+ */
+export declare function anchorFieldName(anchor: FlowAnchor): string | undefined;

package/dist/flows/flow-secret-field.js

@@ -0,0 +1,22 @@
+import { AnchorKind } from '@reticlehq/core';
+/**
+ * What the anchor CALLS the field it points at.
+ *
+ * Every anchor kind names its target differently and all of them can name a password: a testid
+ * (auth-password), an accessible name (role=textbox, name="Password"), a signal. Checking only the
+ * testid variant would redact the app that uses test ids and quietly leak the one that does not —
+ * and an app without test ids is exactly the app whose flows were recorded by role.
+ *
+ * Save and replay MUST share this. Redaction keys off the field name; substitution looks up
+ * `RETICLE_SECRET_<FIELD>` from the same string. Two copies would redact `Password` and then fail
+ * to find the env var because the runner passed a role or a label instead.
+ */
+export function anchorFieldName(anchor) {
+    if (AnchorKind.TESTID === anchor.kind)
+        return anchor.value;
+    if (AnchorKind.ROLE === anchor.kind)
+        return anchor.name;
+    if (AnchorKind.SIGNAL === anchor.kind)
+        return anchor.name;
+    return undefined;
+}

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

@@ -11,6 +11,7 @@ import type { FlowReplaySession, Sleep } from './flow-replay.js';
 export declare function runRoleStep(session: FlowReplaySession, step: FlowStep, index: number, anchor: Extract<FlowAnchor, {
     kind: typeof AnchorKind.ROLE;
 }>, confirmDangerous: boolean, sleep: Sleep): Promise<FlowStepResult>;
+export declare function replayDestructiveActionHint(rawError: string): string;
 /** 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;

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

@@ -9,6 +9,9 @@
 import { AnchorKind, DEGRADED_ANCHOR_ROLE, DriftReason, QueryBy, ReticleCommand, } from '@reticlehq/core';
 import { ReticleTool } from '../tools/tool-names.js';
 import { replayActionArgs } from './replay.js';
+import { isStaleRefError } from '../tools/act-sequence-retry.js';
+import { waitForReaction } from '../tools/react-grace.js';
+import { anchorFieldName } from './flows.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';
@@ -81,30 +84,98 @@ export async function runRoleStep(session, step, index, anchor, confirmDangerous
             },
         };
     }
-    return await actOnResolvedRef(session, step, index, label, ref, confirmDangerous);
+    return await actOnResolvedRef(session, step, index, label, ref, confirmDangerous, anchorFieldName(anchor), 
+    // The retry's whole point: run the SAME locator against the DOM as it is now.
+    async () => (await resolveQuery(session, roleQueryArgs(anchor), sleep)).refs[0]);
+}
+/**
+ * `assertActionAllowed`'s refusal — "potentially destructive action blocked; retry with
+ * args.confirmDangerous=true" — is written for a LIVE call, where retrying with that arg works. It
+ * does not during replay: `replayActionArgs` deliberately strips any `confirmDangerous` a step's own
+ * args carry and restores it only from the ONE call-level boolean this run was given, because a
+ * destructive confirmation has to be a decision made for THIS run, never a value saved into the
+ * recording (#94). A caller who hand-edits the flow file's step args to add it gets it silently
+ * deleted, replays again, and reads the identical refusal — which reads as though nothing they tried
+ * worked, when what happened is they tried the one thing that cannot work here.
+ *
+ * Appends the path that does, rather than replacing the message: an agent that has already learned
+ * to recognise the raw refusal still finds it, plus the fix for this specific caller.
+ */
+const DESTRUCTIVE_ACTION_PATTERN = /potentially destructive (?:\w+ )*(?:action|tool) blocked/i;
+export function replayDestructiveActionHint(rawError) {
+    if (!DESTRUCTIVE_ACTION_PATTERN.test(rawError))
+        return rawError;
+    return (`${rawError} — this is a flow REPLAY: a step's own args.confirmDangerous is stripped before ` +
+        'dispatch and never persists, so editing the flow file does nothing. Pass it at the call level ' +
+        `instead: ${ReticleTool.FLOW_REPLAY} { confirmDangerous: true } acknowledges every flagged step ` +
+        // `reticle_verify{action:"flows"}` (the batch suite runner) has no such argument today — naming
+        // it here would repeat the exact defect this message exists to fix, so the honest statement is
+        // that a flow with a flagged step currently has to be replayed on its own to pass it.
+        'for this run. The batch reticle_verify{action:"flows"} has no equivalent option yet, so a flow ' +
+        'with a flagged step has to be replayed on its own to acknowledge it.');
 }
 /**
  * Dispatch one already-resolved step. Shared so every anchor kind runs the action the same way —
  * including the action window, whose open/close must not depend on which anchor found the element.
  */
-async function actOnResolvedRef(session, step, index, label, ref, confirmDangerous) {
-    session.beginAction?.(ReticleTool.FLOW_REPLAY, { ref, action: step.action ?? '' });
-    let act;
-    try {
-        act = await session.command(ReticleCommand.ACT, {
-            ref,
-            action: step.action ?? '',
-            args: replayActionArgs(step.args, confirmDangerous),
+async function actOnResolvedRef(session, step, index, label, ref, confirmDangerous, 
+/**
+ * The field name a redacted fill is supplied under, from `anchorFieldName` — the SAME function
+ * redaction uses to decide what to hide. Without it a role-anchored secret is redacted at save
+ * and looked up at replay under no name at all, so the flow types the placeholder into the form.
+ */
+field, 
+/**
+ * Resolve the anchor again. Supplied by the caller because only it knows how this step's anchor is
+ * found, and the retry below is worthless without it: re-dispatching the SAME dead ref fails
+ * identically. What changed between the two attempts is the DOM, so the locator has to be run
+ * against it again.
+ */
+reresolve) {
+    const dispatch = async (at) => {
+        session.beginAction?.(ReticleTool.FLOW_REPLAY, { ref: at, action: step.action ?? '' });
+        try {
+            const r = await session.command(ReticleCommand.ACT, {
+                ref: at,
+                action: step.action ?? '',
+                args: replayActionArgs(step.args, confirmDangerous, field),
+            });
+            return { ok: r.ok, error: r.error };
+        }
+        finally {
+            session.finishAction?.();
+        }
+    };
+    let act = await dispatch(ref);
+    /*
+     * One retry, and only for staleness.
+     *
+     * A saved flow of `fill` then `click` failed with "ref 'eNNNN' no longer resolves to an element",
+     * a different ref each attempt: the fill re-rendered the page between the click step resolving its
+     * element and dispatching at it. `flow_heal` answered `unhealable` and was right — the locator was
+     * correct, only the timing was wrong — and the flow format has no way to express a wait, so there
+     * was nothing the user could do.
+     *
+     * `act_sequence` already solved this race for the same reason; the predicate and the grace period
+     * come from there rather than being written twice. A step that failed for any OTHER reason is
+     * never retried: a replay that quietly repeats actions turns one click into two, which is worse
+     * than the failure it papers over.
+     */
+    if (!act.ok && isStaleRefError(act.error) && reresolve !== undefined) {
+        await waitForReaction(session, 0, STALE_REF_GRACE_MS, {
+            sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
         });
-    }
-    finally {
-        session.finishAction?.();
+        const fresh = await reresolve();
+        if (fresh !== undefined)
+            act = await dispatch(fresh);
     }
     const result = { step: index, tool: step.tool, anchor: label, ok: act.ok };
     if (!act.ok)
-        result.error = act.error ?? 'command failed';
+        result.error = replayDestructiveActionHint(act.error ?? 'command failed');
     return result;
 }
+/** How long to let the app finish re-rendering before the one retry. Matches the sequence path. */
+const STALE_REF_GRACE_MS = 400;
 /** Run one component-anchored step: re-resolve via QUERY by:'component', ACT on the live ref, else drift. */
 export async function runComponentStep(session, step, index, anchor, confirmDangerous, sleep) {
     const label = componentLabel(anchor);
@@ -124,25 +195,9 @@ export async function runComponentStep(session, step, index, anchor, confirmDang
         };
     }
     const ref = refs[0] ?? '';
-    // Attribute the step's effects to the step. Without this window they arrive with no actionId and are
-    // learned as ambient churn on the very regions the flow exercises.
-    session.beginAction?.(ReticleTool.FLOW_REPLAY, { ref, action: step.action ?? '' });
-    let act;
-    try {
-        act = await session.command(ReticleCommand.ACT, {
-            ref,
-            action: step.action ?? '',
-            args: replayActionArgs(step.args, confirmDangerous),
-        });
-    }
-    finally {
-        // Close on every exit so a throwing step cannot leak the window onto the next step's events.
-        session.finishAction?.();
-    }
-    const result = { step: index, tool: step.tool, anchor: label, ok: act.ok };
-    if (!act.ok)
-        result.error = act.error ?? 'command failed';
-    return result;
+    // Shared with the role path so both get the same action window AND the same stale-ref retry —
+    // this used to dispatch inline, which is how one anchor kind could gain a fix the other lacked.
+    return await actOnResolvedRef(session, step, index, label, ref, confirmDangerous, anchorFieldName(anchor), async () => (await resolveQuery(session, componentQueryArgs(anchor), sleep)).refs[0]);
 }
 /**
  * DEGRADED_ANCHOR_ROLE is a MARKER ("no anchor could be determined"), never a locator.
@@ -235,7 +290,9 @@ export async function runSequenceStep(session, step, index, subs, confirmDangero
         live.push({
             ref,
             action: sub.action ?? '',
-            args: replayActionArgs(sub.args, confirmDangerous),
+            // Each sub-step carries its OWN anchor, so each gets its own field name. A sequence that ends
+            // in a login is the shape this was reported on, and the sub-step is where the fill lives.
+            args: replayActionArgs(sub.args, confirmDangerous, anchorFieldName(sub.anchor)),
         });
     }
     session.beginAction?.(ReticleTool.FLOW_REPLAY, { steps: live.length });
@@ -253,6 +310,6 @@ export async function runSequenceStep(session, step, index, subs, confirmDangero
         ok: act.ok,
     };
     if (!act.ok)
-        result.error = act.error ?? 'command failed';
+        result.error = replayDestructiveActionHint(act.error ?? 'command failed');
     return result;
 }

package/dist/flows/flow-success.js

@@ -32,6 +32,8 @@ export function successLabel(success) {
     }
     if (success.state !== undefined)
         return `state:${success.state.path}`;
+    if (success.text !== undefined)
+        return `text:${success.text.contains}`;
     return success.element?.testid ?? success.element?.name ?? success.element?.role ?? 'success';
 }
 /** Compile a success FlowExpect into a predicate. undefined → nothing assertable (vacuously met). */
@@ -122,6 +124,26 @@ export function successToPredicate(success, dynamic) {
                 parts.push({ kind: PredicateKind.ELEMENT, query });
         }
     }
+    const text = success.text;
+    if (text !== undefined) {
+        const part = {
+            kind: PredicateKind.TEXT,
+            contains: text.contains,
+        };
+        if (text.scope !== undefined)
+            part.scope = text.scope;
+        if (text.visible !== undefined)
+            part.visible = text.visible;
+        if (true === text.absent) {
+            part.absent = true;
+            // Same post-settle reasoning as `console.absent` and `state.hold`: a wait-until-true waiter
+            // reads "not there yet" on the first poll and passes BEFORE the text it is meant to see
+            // disappear has even been rendered. Gate on `settled` so the read happens after the page
+            // quiets, by which point a text that was going to appear has.
+            parts.push({ kind: PredicateKind.SETTLED });
+        }
+        parts.push(part);
+    }
     const [first] = parts;
     if (0 === parts.length)
         return undefined;

package/dist/flows/flow-tools.js

@@ -14,6 +14,7 @@ import { homedir } from 'node:os';
 import { resolveProjectCloud } from '../cloud/cloud-config.js';
 import { buildSuiteVerdict } from './decision.js';
 import { classifyFlowAssertions } from './flow-classify.js';
+import { recordingBacktrackWarning } from './recording-backtrack.js';
 import { isValidFlowName, flowPath } from '../project/reticle-dir.js';
 import {} from './flows.js';
 import { flowsForSession } from './flow-store-for-session.js';
@@ -84,7 +85,7 @@ const INTENT_GAP_FIELD = z
 export const FLOW_TOOLS = [
     {
         name: ReticleTool.FLOW_SAVE,
-        description: 'Persist the last/active recording (by name) as a git-checked, anchor-resolved flow at .reticle/flows/<name>.json. Each step is bound to a SEMANTIC anchor (testid/role/signal), never a volatile ref; steps without a resolvable testid are kept with degraded:true (a "add a data-testid here" marker) rather than dropped. Returns { name, stepCount, degraded, empty, assertions } — `assertions.grade` is asserted | presence-only | assertion-free: a flow that only acts (or only checks element presence) will pass even if the feature breaks, so when grade is not "asserted" follow assertions.warning and add a consequence assertion via reticle_annotate (assert-signal / assert-net / success-state).',
+        description: 'Persist the last/active recording (by name) as a git-checked, anchor-resolved flow at .reticle/flows/<name>.json. Each step is bound to a SEMANTIC anchor (testid/role/signal), never a volatile ref; steps without a resolvable testid are kept with degraded:true (a "add a data-testid here" marker) rather than dropped. Returns { name, stepCount, degraded, empty, assertions, warning? } — `assertions.grade` is asserted | presence-only | assertion-free: a flow that only acts (or only checks element presence) will pass even if the feature breaks, so when grade is not "asserted" follow assertions.warning and add a consequence assertion via reticle_annotate (assert-signal / assert-net / success-state). `warning` is present when the recording left a page and returned to it: replay has no navigation steps, so the next click will look for a control on a page the tab is no longer on.',
         inputSchema: {
             flow: z
                 .string()
@@ -128,6 +129,10 @@ export const FLOW_TOOLS = [
             })
                 .optional(),
             intentGap: INTENT_GAP_FIELD,
+            warning: z
+                .string()
+                .optional()
+                .describe('Present when the recording left a page and returned to it. Replay has no navigation steps, so the next click will look for a control on a page the tab is no longer on.'),
             error: z.string().optional(),
             code: z.string().optional(),
         },
@@ -189,7 +194,7 @@ export const FLOW_TOOLS = [
             const toSave = saveAs === undefined ? program : { ...program, name: saveAs };
             return flows.save(toSave, annotations, projectId).then(async (res) => {
                 if (!res.ok)
-                    return { error: flowErrorMessage(res.code), code: res.code };
+                    return { error: flowErrorMessage(res.code, res.detail), code: res.code };
                 deps.annotations.clear(name);
                 // Grade the saved flow's assertions so the agent learns immediately if it just saved a flow
                 // that asserts nothing observable (passes even when the feature is broken).
@@ -199,13 +204,19 @@ export const FLOW_TOOLS = [
                 // back from a save that succeeded, so the guard is a type narrowing rather than a doubt.
                 const saved = res.value.name;
                 const path = isValidFlowName(saved) ? flowPath(root, saved, projectId) : undefined;
+                const backtrack = recordingBacktrackWarning(program.routes ?? []);
                 return loaded.ok
                     ? {
                         ...res.value,
                         ...(path === undefined ? {} : { path }),
                         assertions: classifyFlowAssertions(loaded.value),
+                        ...(backtrack === undefined ? {} : { warning: backtrack }),
                     }
-                    : { ...res.value, ...(path === undefined ? {} : { path }) };
+                    : {
+                        ...res.value,
+                        ...(path === undefined ? {} : { path }),
+                        ...(backtrack === undefined ? {} : { warning: backtrack }),
+                    };
             });
         },
     },
@@ -246,7 +257,7 @@ export const FLOW_TOOLS = [
     },
     {
         name: ReticleTool.FLOW_LOAD,
-        description: 'Read + validate a saved flow by flowName from .reticle/flows/<flowName>.json. Returns the FlowFile (version, flowName, createdAt, anchored steps) or a structured { error, code }.',
+        description: 'Read + validate a saved flow by flowName from .reticle/flows/<flowName>.json. Returns the FlowFile (version, flowName, createdAt, anchored steps) or a structured { error, code }. Step `expect` (and flow `success`) accepts the same allOf grammar as reticle_act_and_wait; a parse failure names the step and key rather than calling the file malformed.',
         inputSchema: {
             flow: z
                 .string()
@@ -275,7 +286,7 @@ export const FLOW_TOOLS = [
                 .load(asString(aliasParam(args, 'flowName', ['flow'])['flowName']) ?? '', projectId)
                 .then((res) => {
                 if (!res.ok)
-                    return { error: flowErrorMessage(res.code), code: res.code };
+                    return { error: flowErrorMessage(res.code, res.detail), code: res.code };
                 const { name, ...rest } = res.value;
                 return { flowName: name, ...rest };
             });
@@ -310,7 +321,7 @@ export const FLOW_TOOLS = [
                 .remove(asString(aliasParam(args, 'flowName', ['flow'])['flowName']) ?? '', projectId)
                 .then((res) => {
                 if (!res.ok)
-                    return { error: flowErrorMessage(res.code), code: res.code };
+                    return { error: flowErrorMessage(res.code, res.detail), code: res.code };
                 return { deleted: true };
             });
         },
@@ -324,7 +335,10 @@ export const FLOW_TOOLS = [
             'Returns { name, status: ok|drift|error, steps:[...] }; missing/malformed files and action ' +
             'failures are status:error with a structured code (distinct from contract-changed drift). ' +
             'An ok replay of a flow that asserts no consequence also carries unverifiable:{reason} — it ' +
-            'would read ok even if the feature were broken, so do NOT treat that ok as proof.',
+            'would read ok even if the feature were broken, so do NOT treat that ok as proof. ' +
+            'A run that stops early carries halted:{atStep, notAttempted}: `steps` is SHORTER than the ' +
+            'flow because replay stopped, not because a step was skipped — do not read a missing step as ' +
+            'an action that failed to dispatch.',
         inputSchema: {
             flow: z
                 .string()
@@ -354,6 +368,11 @@ export const FLOW_TOOLS = [
                 .optional()
                 .describe('Push-default deviation report over the replay segments: ranked deviations vs the learned envelope + a nominal count, or a fall-back note below 3 runs.'),
             error: z.object({ code: z.string(), message: z.string() }).optional(),
+            // Same rule as `unverifiable` below, and the same failure if it is left out.
+            halted: z
+                .object({ atStep: z.number(), notAttempted: z.number() })
+                .optional()
+                .describe('Set when the replay STOPPED at a failing step: `steps` is shorter than the flow, and this says where it stopped and how many steps were never attempted. Absent means every step ran.'),
             // Declared here or a validating profile strips it -- the same way `name` was stripped once.
             // A field the handler sets and the schema omits arrives as nothing, silently.
             unverifiable: z
@@ -566,7 +585,7 @@ export const FLOW_TOOLS = [
             // it — and the pair that disagreed were the two ways to save the same thing.
             const res = await flowsForSession(deps, session.projectId).flows.saveFlow(flow, session.projectId);
             if (!res.ok)
-                return { error: flowErrorMessage(res.code), code: res.code };
+                return { error: flowErrorMessage(res.code, res.detail), code: res.code };
             // If logged in to Reticle, mirror the saved flow to the team's regression suite. Best-effort
             // and non-blocking: the flow is already on disk, so a sync failure never fails the save.
             void syncSavedFlowToCloud(deps, flow, session.projectId);

package/dist/flows/flow-upload-resolve.d.ts

@@ -0,0 +1,23 @@
+import { type FlowFile } from '@reticlehq/core';
+import type { ToolDeps } from '../tools/tools.js';
+/**
+ * Turn a recorded upload's `path` into the bytes the browser can actually take, once, before replay
+ * runs a single step.
+ *
+ * The recorder and the replayer disagreed about what an upload step IS, and the disagreement was
+ * total: `reticle_record` writes `{"action":"upload","args":{"path":"test-fixtures/pipe.step"}}` —
+ * the only form the live `reticle_act` accepts, and the form that works interactively — while replay
+ * dispatched it straight at the browser, which refused with "upload does not read path, so it would
+ * be dropped". A recorded upload could therefore never replay as recorded. The capability was there
+ * the whole time: an agent who hand-patched the flow JSON to `{name, content, type}` got a real
+ * upload, a real `POST /api/v0/files -> 200`, and the app went on to perceive the file.
+ *
+ * Resolved HERE rather than at each of the four dispatch sites inside replay, and rather than at
+ * save time: the flow file stays small and legible, the fixture stays on disk where it can be
+ * reviewed and updated, and a flow that names a file nobody checked in fails saying so instead of
+ * carrying a stale copy of it.
+ *
+ * `rewriteUploadArgs` is the same function the live path uses, so the two cannot drift again — which
+ * is the whole reason this defect existed.
+ */
+export declare function resolveFlowUploads(deps: Pick<ToolDeps, 'fs' | 'reticleRoot'>, flow: FlowFile): Promise<FlowFile>;

package/dist/flows/flow-upload-resolve.js

@@ -0,0 +1,46 @@
+import { ActionType } from '@reticlehq/core';
+import { rewriteUploadArgs } from '../tools/real-input-attempt.js';
+/**
+ * Turn a recorded upload's `path` into the bytes the browser can actually take, once, before replay
+ * runs a single step.
+ *
+ * The recorder and the replayer disagreed about what an upload step IS, and the disagreement was
+ * total: `reticle_record` writes `{"action":"upload","args":{"path":"test-fixtures/pipe.step"}}` —
+ * the only form the live `reticle_act` accepts, and the form that works interactively — while replay
+ * dispatched it straight at the browser, which refused with "upload does not read path, so it would
+ * be dropped". A recorded upload could therefore never replay as recorded. The capability was there
+ * the whole time: an agent who hand-patched the flow JSON to `{name, content, type}` got a real
+ * upload, a real `POST /api/v0/files -> 200`, and the app went on to perceive the file.
+ *
+ * Resolved HERE rather than at each of the four dispatch sites inside replay, and rather than at
+ * save time: the flow file stays small and legible, the fixture stays on disk where it can be
+ * reviewed and updated, and a flow that names a file nobody checked in fails saying so instead of
+ * carrying a stale copy of it.
+ *
+ * `rewriteUploadArgs` is the same function the live path uses, so the two cannot drift again — which
+ * is the whole reason this defect existed.
+ */
+export async function resolveFlowUploads(deps, flow) {
+    const resolveStep = async (step) => {
+        const nested = step.steps;
+        const steps = nested === undefined ? undefined : await Promise.all(nested.map(resolveStep));
+        const isUpload = step.action === ActionType.UPLOAD && step.args?.['path'] !== undefined;
+        const args = isUpload
+            ? await rewriteUploadArgs(deps, ActionType.UPLOAD, step.args ?? {})
+            : step.args;
+        return {
+            ...step,
+            ...(args === undefined ? {} : { args }),
+            ...(steps === undefined ? {} : { steps }),
+        };
+    };
+    // Untouched flows are returned as-is so the common journey allocates nothing and the on-disk file
+    // and the replayed one stay the same object to compare.
+    if (!hasUpload(flow.steps))
+        return flow;
+    return { ...flow, steps: await Promise.all(flow.steps.map(resolveStep)) };
+}
+function hasUpload(steps) {
+    return steps.some((s) => (s.action === ActionType.UPLOAD && s.args?.['path'] !== undefined) ||
+        (s.steps !== undefined && hasUpload(s.steps)));
+}

package/dist/flows/flows.d.ts

@@ -13,6 +13,7 @@ export type FlowResult<T> = {
 } | {
     ok: false;
     code: FlowErrorCode;
+    detail?: string;
 };
 /** Pick the on-disk anchor for a normalized step: testid > component(auto) > degraded role. */
 export declare function anchorForStep(args: Record<string, unknown>): {
@@ -27,6 +28,20 @@ export declare function anchorForStep(args: Record<string, unknown>): {
  * reader what to do: the value belongs in the environment, not in a file they are about to commit.
  */
 export declare const REDACTED_FILL = "<redacted: supply at replay>";
+/**
+ * What the anchor CALLS the field it points at.
+ *
+ * Every anchor kind names its target differently and all of them can name a password: a testid
+ * (auth-password), an accessible name (role=textbox, name="Password"), a signal. Checking only the
+ * testid variant would redact the app that uses test ids and quietly leak the one that does not —
+ * and an app without test ids is exactly the app whose flows were recorded by role.
+ *
+ * Exported because REPLAY has to agree with redaction about what the field is called. It did not:
+ * the replay paths took a `field` argument that only the testid caller passed, so a role-anchored
+ * secret was redacted at save under one name and looked up at replay under none — the flow typed
+ * the placeholder into the form. One function decides it for both sides, or the two drift again.
+ */
+export declare function anchorFieldName(anchor: FlowAnchor): string | undefined;
 /**
  * Pure: map one normalized RecordedStep → FlowStep with a semantic anchor (+ degraded marker).
  * A ref-only (stable:false) step is recorded with a best-effort anchor and degraded:true —

package/dist/flows/flows.js

@@ -6,6 +6,7 @@ import { applyHealChanges } from './heal.js';
 import { flowIntentGap, linkFlowIntent } from './flow-intent.js';
 import { IntentStore } from '../intent/intent-store.js';
 import { flowDir, flowPath, reticleDirPaths, isValidFlowName } from '../project/reticle-dir.js';
+import { describeFlowZodFailure, parseFlowFileText } from './flow-expect-grammar.js';
 /**
  * A projectId only scopes storage when it's a safe single path segment (it's stamped from the
  * session's HELLO, but the store defends the disk boundary itself). An unsafe/absent value collapses
@@ -540,8 +541,13 @@ function redactSecretFill(anchor, args) {
  * (auth-password), an accessible name (role=textbox, name="Password"), a signal. Checking only the
  * testid variant would redact the app that uses test ids and quietly leak the one that does not —
  * and an app without test ids is exactly the app whose flows were recorded by role.
+ *
+ * Exported because REPLAY has to agree with redaction about what the field is called. It did not:
+ * the replay paths took a `field` argument that only the testid caller passed, so a role-anchored
+ * secret was redacted at save under one name and looked up at replay under none — the flow typed
+ * the placeholder into the form. One function decides it for both sides, or the two drift again.
  */
-function anchorFieldName(anchor) {
+export function anchorFieldName(anchor) {
     if (AnchorKind.TESTID === anchor.kind)
         return anchor.value;
     if (AnchorKind.ROLE === anchor.kind)
@@ -700,8 +706,15 @@ export class FlowStore {
         // per-project subdir. Both come from the same `pid`, so on-disk location and content always agree.
         const stamped = pid === undefined ? flow : { ...flow, projectId: pid };
         const parsed = FlowFileSchema.safeParse(stamped);
-        if (!parsed.success)
-            return { ok: false, code: FlowErrorCode.PARSE_FAILED };
+        if (!parsed.success) {
+            // Named, not bare: the load path already says which step and key it choked on, and a save
+            // that refuses in silence sends the caller to the file to guess at what a load would tell it.
+            return {
+                ok: false,
+                code: FlowErrorCode.PARSE_FAILED,
+                detail: describeFlowZodFailure(parsed.error),
+            };
+        }
         const valid = await this.#linkIntent(parsed.data);
         await this.#fs.mkdir(flowDir(this.#root, pid));
         await this.#fs.writeFile(flowPath(this.#root, asFlowName(valid.name), pid), this.#serialize(valid));
@@ -837,17 +850,7 @@ export class FlowStore {
                 code: this.#fs.isNotFound(error) ? FlowErrorCode.NOT_FOUND : FlowErrorCode.PARSE_FAILED,
             };
         }
-        let parsed;
-        try {
-            parsed = JSON.parse(text);
-        }
-        catch {
-            return { ok: false, code: FlowErrorCode.PARSE_FAILED };
-        }
-        const result = FlowFileSchema.safeParse(parsed);
-        if (!result.success)
-            return { ok: false, code: FlowErrorCode.PARSE_FAILED };
-        return { ok: true, value: result.data };
+        return parseFlowFileText(text);
     }
     /**
      * Delete a flow's file so a renamed/obsolete flow stops lingering in the replay list. Resolves the

package/dist/flows/git-changed.d.ts

@@ -1,8 +1,27 @@
 /** Parse `git diff --name-only` output into a clean file list. Pure; exported for testing. */
 export declare function parseGitFiles(output: string): string[];
 /**
- * Files changed since a git ref (`git diff --name-only <ref>`), so `reticle gate --since main` works from
- * the real diff instead of hand-listed files. Returns [] on any git failure (not a repo, bad ref) rather
- * than throwing — the caller degrades to "no changes" and the gate simply passes, never crashes CI.
+ * The outcome of asking git what changed — files, and whether the question could be answered.
+ *
+ * `files: []` used to mean both "the tree is clean" and "git could not tell us", and those are
+ * opposite answers to the only question `reticle_affected` and `reticle_verify_change` exist to ask.
+ * A caller that cannot distinguish them reports "nothing to re-verify" over a mistyped ref, a
+ * shallow clone with no history, or a daemon outside the repository — and the agent ships.
  */
-export declare function changedFilesSince(ref: string, cwd: string): Promise<string[]>;
+export interface ChangedFiles {
+    files: string[];
+    /** True when git could not answer. `files` is then empty because nothing was learned. */
+    failed: boolean;
+    /** Why, when it failed — for the caller to surface, never to swallow. */
+    reason?: string;
+}
+/**
+ * Files changed since a git ref (`git diff --name-only <ref>`), so `reticle gate --since main` works
+ * from the real diff instead of hand-listed files.
+ *
+ * Never throws, and never pretends. The CLI gate may still degrade to "no changes" and pass rather
+ * than crash CI — that reasoning was right and is unchanged — but it now has to opt into doing so by
+ * ignoring `failed`, instead of being handed a clean-looking empty list. The MCP tools read the flag
+ * and say they could not tell.
+ */
+export declare function changedFilesSince(ref: string, cwd: string): Promise<ChangedFiles>;

package/dist/flows/git-changed.js

@@ -9,16 +9,42 @@ export function parseGitFiles(output) {
         .filter((line) => line.length > 0);
 }
 /**
- * Files changed since a git ref (`git diff --name-only <ref>`), so `reticle gate --since main` works from
- * the real diff instead of hand-listed files. Returns [] on any git failure (not a repo, bad ref) rather
- * than throwing — the caller degrades to "no changes" and the gate simply passes, never crashes CI.
+ * A ref beginning with `-` is read by git as an OPTION, not a ref.
+ *
+ * `execFile` runs no shell, so this is argument injection rather than command injection — but
+ * `--output=<path>` in the ref position is enough to make git write somewhere it was not asked to.
+ * Refused rather than escaped: `--end-of-options` is not supported by every git version we might
+ * meet, and a ref that starts with a dash is not a thing a caller legitimately wants.
+ */
+function refIsOptionLike(ref) {
+    return ref.startsWith('-');
+}
+/**
+ * Files changed since a git ref (`git diff --name-only <ref>`), so `reticle gate --since main` works
+ * from the real diff instead of hand-listed files.
+ *
+ * Never throws, and never pretends. The CLI gate may still degrade to "no changes" and pass rather
+ * than crash CI — that reasoning was right and is unchanged — but it now has to opt into doing so by
+ * ignoring `failed`, instead of being handed a clean-looking empty list. The MCP tools read the flag
+ * and say they could not tell.
  */
 export async function changedFilesSince(ref, cwd) {
+    if (refIsOptionLike(ref)) {
+        return {
+            files: [],
+            failed: true,
+            reason: `refusing ref "${ref}": a leading dash makes git read it as an option, not a ref`,
+        };
+    }
     try {
         const { stdout } = await run('git', ['diff', '--name-only', ref], { cwd });
-        return parseGitFiles(stdout);
+        return { files: parseGitFiles(stdout), failed: false };
     }
-    catch {
-        return [];
+    catch (error) {
+        return {
+            files: [],
+            failed: true,
+            reason: error instanceof Error ? error.message : String(error),
+        };
     }
 }

package/dist/flows/heal-run.js

@@ -36,8 +36,8 @@ export async function healFlow(deps, args) {
             applied: false,
             proposals: [],
             changed: [],
-            message: flowErrorMessage(loaded.code),
-            error: { code: loaded.code, message: flowErrorMessage(loaded.code) },
+            message: flowErrorMessage(loaded.code, loaded.detail),
+            error: { code: loaded.code, message: flowErrorMessage(loaded.code, loaded.detail) },
         };
     }
     const session = deps.sessions.resolve(asString(args['sessionId']));

package/dist/flows/predicate-to-expect.d.ts

@@ -37,7 +37,8 @@ export declare function predicateToExpect(predicate: Predicate): FlowExpect | un
  * `reticle_verify` then correctly called it `unverifiable` — the record → save → verify path
  * completing all the way to a run that could never be a pass. Found by driving it.
  *
- * The list below is exactly what `successToPredicate` reads, plus the testid the step runner
- * asserts directly against the DOM. Anything it cannot compile is still dropped.
+ * The list below is exactly what `successToPredicate` reads, including an element located by
+ * role or name. A testid is also asserted directly against the DOM by the step runner. Anything
+ * it cannot compile is still dropped.
  */
 export declare function enforcedOnReplay(expect: FlowExpect | undefined): FlowExpect | undefined;