@reticlehq/server 2.3.0 → 2.5.0

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

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

package/dist/flows/flow-success.js

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

package/dist/flows/flow-tools.js

@@ -1,4 +1,6 @@
 import { z } from 'zod';
+import { emptyFlowRefusal } from './empty-flow.js';
+import { aliasParam } from '../tools/alias-args.js';
 import { FlowErrorCode, RecordedSaveError, ReplayStatus, } from '@reticlehq/core';
 import { FlakeStore } from './flake-store.js';
 import { ReticleTool } from '../tools/tool-names.js';
@@ -25,7 +27,7 @@ export { replayNamedFlow } from './flow-replay-run.js';
 async function syncSavedFlowToCloud(deps, flow, projectId) {
     // Per-project cloud: sync a saved flow only when cloud is attached AND flow sync is enabled.
     const cloud = await resolveProjectCloud(deps.fs, deps.reticleRoot, homedir(), process.env);
-    if (cloud.config === null || !cloud.policy.flows)
+    if (null === cloud.config || !cloud.policy.flows)
         return; // not attached / flows disabled → local only
     const result = await syncFlowToCloud(flow, cloud.config, projectId, (url, init) => fetch(url, init));
     if (result.outcome !== SyncOutcome.SYNCED) {
@@ -43,7 +45,7 @@ async function syncSavedFlowToCloud(deps, flow, projectId) {
 export function leasableAppUrl(deps, sessionId) {
     try {
         const url = deps.sessions.resolve(sessionId).url;
-        if (typeof url !== 'string' || url.length === 0)
+        if (typeof url !== 'string' || 0 === url.length)
             return undefined;
         return new URL(url).origin;
     }
@@ -70,6 +72,10 @@ 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).',
         inputSchema: {
+            flow: z
+                .string()
+                .optional()
+                .describe('Alias for `flowName` (the name reticle_annotate uses).'),
             flowName: z
                 .string()
                 .describe('Name for the flow file (saved to .reticle/flows/<flowName>.json). Use again in reticle_flow{action:"load"} / reticle_flow_replay.'),
@@ -103,7 +109,7 @@ export const FLOW_TOOLS = [
             code: z.string().optional(),
         },
         handler: (deps, args) => {
-            const name = asString(args['flowName']) ?? '';
+            const name = asString(aliasParam(args, 'flowName', ['flow'])['flowName']) ?? '';
             const program = deps.recordings.getCompiled(name);
             if (program === undefined) {
                 return Promise.resolve({
@@ -121,6 +127,11 @@ export const FLOW_TOOLS = [
                 ...(intent !== undefined ? { intent } : {}),
             };
             const projectId = sessionProjectId(deps, asString(args['sessionId']));
+            // A zero-step recording is not a flow. Saving it wrote a file the suite reports "unverifiable"
+            // forever while telling the agent it had saved a regression test — see empty-flow.
+            const emptyRefusal = emptyFlowRefusal(program.steps.length, name);
+            if (emptyRefusal !== undefined)
+                return Promise.resolve(emptyRefusal);
             return deps.flows.save(program, annotations, projectId).then(async (res) => {
                 if (!res.ok)
                     return { error: flowErrorMessage(res.code), code: res.code };
@@ -170,6 +181,10 @@ 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 }.',
         inputSchema: {
+            flow: z
+                .string()
+                .optional()
+                .describe('Alias for `flowName` (the name reticle_annotate uses).'),
             flowName: z
                 .string()
                 .describe('Flow file name (without .json extension) from reticle_flow{action:"list"}.'),
@@ -179,13 +194,19 @@ export const FLOW_TOOLS = [
                 .describe('Active session ID — resolves the flow within that app’s scope.'),
         },
         outputSchema: {
+            flow: z
+                .string()
+                .optional()
+                .describe('Alias for `flowName` (the name reticle_annotate uses).'),
             flowName: z.string(),
             steps: z.array(z.unknown()),
             createdAt: z.number().optional(),
         },
         handler: (deps, args) => {
             const projectId = sessionProjectId(deps, asString(args['sessionId']));
-            return deps.flows.load(asString(args['flowName']) ?? '', projectId).then((res) => {
+            return deps.flows
+                .load(asString(aliasParam(args, 'flowName', ['flow'])['flowName']) ?? '', projectId)
+                .then((res) => {
                 if (!res.ok)
                     return { error: flowErrorMessage(res.code), code: res.code };
                 const { name, ...rest } = res.value;
@@ -199,6 +220,10 @@ export const FLOW_TOOLS = [
             'to the connected app. Returns { deleted: true } or a structured { error, code } (code not_found ' +
             'when no such flow — deleting an absent flow is an error, not a silent no-op).',
         inputSchema: {
+            flow: z
+                .string()
+                .optional()
+                .describe('Alias for `flowName` (the name reticle_annotate uses).'),
             flowName: z
                 .string()
                 .describe('Flow file name (without .json extension) from reticle_flow{action:"list"}.'),
@@ -214,7 +239,9 @@ export const FLOW_TOOLS = [
         },
         handler: (deps, args) => {
             const projectId = sessionProjectId(deps, asString(args['sessionId']));
-            return deps.flows.remove(asString(args['flowName']) ?? '', projectId).then((res) => {
+            return deps.flows
+                .remove(asString(aliasParam(args, 'flowName', ['flow'])['flowName']) ?? '', projectId)
+                .then((res) => {
                 if (!res.ok)
                     return { error: flowErrorMessage(res.code), code: res.code };
                 return { deleted: true };
@@ -230,6 +257,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).',
         inputSchema: {
+            flow: z
+                .string()
+                .optional()
+                .describe('Alias for `flowName` (the name reticle_annotate uses).'),
             flowName: z
                 .string()
                 .describe('Flow file name (without .json extension) from reticle_flow{action:"list"}.'),
@@ -311,7 +342,7 @@ export const FLOW_TOOLS = [
             // "Replay all" means all of THIS app's flows (+ legacy), not every project's on a shared daemon.
             const projectId = sessionProjectId(deps, sessionId);
             const requested = Array.isArray(args['names'])
-                ? args['names'].filter((n) => typeof n === 'string')
+                ? args['names'].filter((n) => 'string' === typeof n)
                 : await deps.flows.list(projectId);
             // verify:server — hand the whole suite to the hosted runner; it records the verification itself.
             const cloud = await resolveProjectCloud(deps.fs, deps.reticleRoot, homedir(), process.env);
@@ -345,12 +376,18 @@ export const FLOW_TOOLS = [
                         await lease.release().catch(() => undefined);
                     }
                 });
-                return buildSuiteVerdict(outcomes.map((o, i) => ({
-                    replay: o.ok && o.value !== undefined
-                        ? o.value
-                        : leaseFailureReplay(requested[i] ?? '', o.error),
-                })));
+                const parallelRuns = await Promise.all(outcomes.map(async (o, i) => {
+                    const name = requested[i] ?? '';
+                    const replay = o.ok && o.value !== undefined ? o.value : leaseFailureReplay(name, o.error);
+                    const loaded = await deps.flows.load(name, projectId).catch(() => null);
+                    const flow = loaded !== null && loaded.ok ? loaded.value : undefined;
+                    return flow === undefined ? { replay } : { replay, flow };
+                }));
+                return buildSuiteVerdict(parallelRuns);
             }
+            // The flow FILE travels with each replay so the verdict can tell a green that verified
+            // something from a green that could never have gone red. Without it the suite reported "all 1
+            // flow pass" for a flow with no steps at all.
             const runs = [];
             const timed = [];
             // The flake ledger the CLI gate already keeps — see FlakeStore. It was only ever written by
@@ -362,7 +399,9 @@ export const FLOW_TOOLS = [
             for (const flowName of requested) {
                 const start = deps.now();
                 const replay = await replayNamedFlow(deps, { flowName, sessionId });
-                runs.push({ replay });
+                const loaded = await deps.flows.load(flowName, projectId).catch(() => null);
+                const flow = loaded !== null && loaded.ok ? loaded.value : undefined;
+                runs.push(flow === undefined ? { replay } : { replay, flow });
                 timed.push({ replay, durationMs: deps.now() - start });
             }
             // Accrue this run's outcomes, then report what the ledger knows. Best-effort on both halves: a
@@ -389,6 +428,10 @@ export const FLOW_TOOLS = [
             'recorded name. Returns { name, stepCount, degraded, empty } or { error, code } (code ' +
             'flow_no_recorded when no recording is present).',
         inputSchema: {
+            flow: z
+                .string()
+                .optional()
+                .describe('Alias for `flowName` (the name reticle_annotate uses).'),
             flowName: z
                 .string()
                 .optional()
@@ -419,10 +462,13 @@ export const FLOW_TOOLS = [
                     code: RecordedSaveError.NO_RECORDED_FLOW,
                 };
             }
-            const override = asString(args['flowName']);
+            const override = asString(aliasParam(args, 'flowName', ['flow'])['flowName']);
             const flow = override !== undefined ? { ...recorded.flow, name: override } : recorded.flow;
             // The store stamps the project into the file AND routes it to the per-project subdir (a shared
             // daemon serves many apps), so location and content agree from one source of truth.
+            const emptyRecorded = emptyFlowRefusal(flow.steps.length, flow.name);
+            if (emptyRecorded !== undefined)
+                return emptyRecorded;
             const res = await deps.flows.saveFlow(flow, session.projectId);
             if (!res.ok)
                 return { error: flowErrorMessage(res.code), code: res.code };
@@ -446,6 +492,10 @@ export const FLOW_TOOLS = [
             'untouched). Returns { name, status: healed|drift|unhealable|consequence_broken|' +
             'nothing_to_heal|error, applied, proposals[], changed[], message }.',
         inputSchema: {
+            flow: z
+                .string()
+                .optional()
+                .describe('Alias for `flowName` (the name reticle_annotate uses).'),
             flowName: z.string().describe('Flow file name to heal (from reticle_flow{action:"list"}).'),
             apply: z.boolean().optional(),
             confirmDangerous: z
@@ -458,6 +508,10 @@ export const FLOW_TOOLS = [
                 .describe('Active session ID from reticle_sessions. Omit when only one browser session is open.'),
         },
         outputSchema: {
+            flow: z
+                .string()
+                .optional()
+                .describe('Alias for `flowName` (the name reticle_annotate uses).'),
             flowName: z.string(),
             status: z.string(),
             applied: z.boolean(),

package/dist/flows/flows.js

@@ -28,10 +28,10 @@ function sourceArg(src) {
     const source = asRecord(src['source']);
     const file = source['file'];
     const line = source['line'];
-    if (typeof file !== 'string' || file.length === 0 || typeof line !== 'number')
+    if (typeof file !== 'string' || 0 === file.length || typeof line !== 'number')
         return undefined;
     const out = { file, line };
-    if (typeof source['column'] === 'number')
+    if ('number' === typeof source['column'])
         out.column = source['column'];
     return out;
 }
@@ -109,8 +109,12 @@ export function recordedStepToFlowStep(step) {
     if (step.tool === ReticleTool.ACT_SEQUENCE) {
         const rawSubs = Array.isArray(step.args['steps']) ? step.args['steps'] : [];
         const subs = rawSubs.map(subStepToFlowStep);
-        const degraded = subs.some((s) => s.degraded === true);
-        const anchor = subs[0]?.anchor ?? degradedAnchor();
+        const degraded = subs.some((s) => true === s.degraded);
+        // The first sub-step that HAS an anchor, not blindly the first. Taking subs[0] handed the whole
+        // sequence the degraded sentinel whenever sub-step 0 lacked a testid — even with every later
+        // sub-step perfectly anchored — and replay then queried the DOM for a testid literally named
+        // "unresolved", so the step drifted on all 5 apps, every replay.
+        const anchor = subs.find((s) => s.degraded !== true)?.anchor ?? subs[0]?.anchor ?? degradedAnchor();
         const out = { tool: ReticleTool.ACT_SEQUENCE, anchor, steps: subs };
         if (degraded)
             out.degraded = true;
@@ -185,14 +189,14 @@ export class FlowStore {
         const flow = withAnnotations(base, annotations);
         await this.#fs.mkdir(flowDir(this.#root, pid));
         await this.#fs.writeFile(flowPath(this.#root, program.name, pid), this.#serialize(flow));
-        const degraded = flow.steps.filter((s) => s.degraded === true).length;
+        const degraded = flow.steps.filter((s) => true === s.degraded).length;
         return {
             ok: true,
             value: {
                 name: program.name,
                 stepCount: flow.steps.length,
                 degraded,
-                empty: flow.steps.length === 0,
+                empty: 0 === flow.steps.length,
             },
         };
     }
@@ -214,14 +218,14 @@ export class FlowStore {
         const valid = parsed.data;
         await this.#fs.mkdir(flowDir(this.#root, pid));
         await this.#fs.writeFile(flowPath(this.#root, asFlowName(valid.name), pid), this.#serialize(valid));
-        const degraded = valid.steps.filter((s) => s.degraded === true).length;
+        const degraded = valid.steps.filter((s) => true === s.degraded).length;
         return {
             ok: true,
             value: {
                 name: valid.name,
                 stepCount: valid.steps.length,
                 degraded,
-                empty: valid.steps.length === 0,
+                empty: 0 === valid.steps.length,
             },
         };
     }
@@ -247,7 +251,7 @@ export class FlowStore {
         // Write back to the SAME file load resolved (nested if it lives there, else legacy flat), so a
         // heal never forks a second copy and byte-stability holds regardless of where the flow lives.
         const path = await this.#resolveReadPath(name, pid);
-        if (path === null)
+        if (null === path)
             return { ok: false, code: FlowErrorCode.NOT_FOUND };
         const { flow: next, applied } = applyHealChanges(flow, changes);
         await this.#fs.writeFile(path, this.#serialize(next));
@@ -343,7 +347,7 @@ export class FlowStore {
         if (!isValidFlowName(name))
             return { ok: false, code: FlowErrorCode.INVALID_NAME };
         const path = await this.#resolveReadPath(name, safeProjectId(projectId));
-        if (path === null)
+        if (null === path)
             return { ok: false, code: FlowErrorCode.NOT_FOUND };
         let text;
         try {
@@ -377,7 +381,7 @@ export class FlowStore {
         if (!isValidFlowName(name))
             return { ok: false, code: FlowErrorCode.INVALID_NAME };
         const path = await this.#resolveReadPath(name, safeProjectId(projectId));
-        if (path === null)
+        if (null === path)
             return { ok: false, code: FlowErrorCode.NOT_FOUND };
         await this.#fs.rm(path);
         return { ok: true, value: undefined };

package/dist/flows/gate.d.ts

@@ -6,12 +6,12 @@
  * inputs (git diff → affected → run artifacts + flake ledger) and maps `pass` to the exit code.
  */
 /** A flow whose assertions were WEAKENED since its last passing run. */
-export interface DowngradedFlow {
+interface DowngradedFlow {
     flow: string;
     /** Step indices whose mustHold dropped from a consequence to presence-only. */
     steps: number[];
 }
-export interface GateInput {
+interface GateInput {
     /** Flows that must be covered (from the affected index over the changed files). */
     affected: readonly string[];
     /** Flows that have a passing verification artifact. */
@@ -23,7 +23,7 @@ export interface GateInput {
     /** Flows that covered a changed file but no longer exist — coverage deleted rather than satisfied. */
     deleted?: readonly string[];
 }
-export interface GateResult {
+interface GateResult {
     /** True when every affected, non-flaky flow has a passing artifact AND nothing was weakened/deleted. */
     pass: boolean;
     /** Affected flows with no passing artifact and not flaky — these block the gate. */
@@ -36,3 +36,4 @@ export interface GateResult {
     deleted: string[];
 }
 export declare function gateDecision(input: GateInput): GateResult;
+export {};

package/dist/flows/gate.js

@@ -24,7 +24,7 @@ export function gateDecision(input) {
     const downgraded = [...(input.downgraded ?? [])];
     const deleted = [...(input.deleted ?? [])];
     return {
-        pass: uncovered.length === 0 && downgraded.length === 0 && deleted.length === 0,
+        pass: 0 === uncovered.length && 0 === downgraded.length && 0 === deleted.length,
         uncovered,
         quarantined,
         downgraded,

package/dist/flows/heal-run.d.ts

@@ -7,12 +7,4 @@
  */
 import { type FlowHealResult } from '@reticlehq/core';
 import type { ToolDeps } from '../tools/tools.js';
-export declare const HEAL_MESSAGES: {
-    readonly NOTHING: "nothing to heal — every anchor resolved on replay";
-    readonly HEALED: "rewrote drifted testid anchors to their nearest surviving match and re-verified the flow's success consequence still fires";
-    readonly DRIFT_DRY: "confident rebind(s) proposed — re-run with apply:true to write them to disk";
-    readonly UNHEALABLE: "drift found, but no nearest match cleared the confidence floor (HEAL_CONFIDENCE_MIN=0.5); file left untouched — add a data-testid or fix the flow by hand";
-    readonly HEALED_UNVERIFIED: "rewrote drifted testid anchors — but this flow declares no success consequence, so the rebind resolves a locator without proving the intent still holds. Add a success-state assertion (reticle_annotate) so future heals can be verified.";
-    readonly CONSEQUENCE_BROKEN: "rebind resolves the drifted locator to a surviving element, but the healed flow no longer satisfies its success consequence — refusing to write (a heal that loses the intent would ship a green-but-dead test). Fix by hand and verify";
-};
 export declare function healFlow(deps: ToolDeps, args: Record<string, unknown>): Promise<FlowHealResult>;