@reticlehq/server 2.4.0 → 2.6.0

package/dist/flows/flow-tools.js

@@ -1,6 +1,8 @@
 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 { recordSuiteFlakes } from './suite-flakes.js';
 import { ReticleTool } from '../tools/tool-names.js';
 import { asNumber, asString } from '../tools/tools-helpers.js';
 import { log } from '../log.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);
@@ -352,18 +383,15 @@ export const FLOW_TOOLS = [
                     const flow = loaded !== null && loaded.ok ? loaded.value : undefined;
                     return flow === undefined ? { replay } : { replay, flow };
                 }));
-                return buildSuiteVerdict(parallelRuns);
+                const flaky = await recordSuiteFlakes(deps.fs, deps.reticleRoot, parallelRuns);
+                const verdict = buildSuiteVerdict(parallelRuns);
+                return flaky.length > 0 ? { ...verdict, flaky: [...flaky] } : verdict;
             }
             // 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
-            // `reticle flow` on the command line, so an AGENT running this tool a hundred times learned
-            // nothing about which flows are intermittent. Same product, same ledger, two surfaces, and the
-            // one an agent uses was the blind half.
-            const flakes = new FlakeStore(deps.fs, deps.reticleRoot);
             // Sequential default: every flow replays against the same live session, so they must not overlap.
             for (const flowName of requested) {
                 const start = deps.now();
@@ -373,19 +401,18 @@ export const FLOW_TOOLS = [
                 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
-            // flake ledger is memory, not a gate, and it must never turn a working verify into an error.
-            for (const { replay } of runs) {
-                await flakes.record(replay.name, replay.status === ReplayStatus.OK).catch(() => undefined);
-            }
-            const flaky = await flakes.flakyFlows().catch(() => []);
+            // The flake ledger the CLI gate already keeps — see FlakeStore. It was only ever written by
+            // `reticle flow` on the command line, so an AGENT running this tool a hundred times learned
+            // nothing about which flows are intermittent. Same product, same ledger, two surfaces, and the
+            // one an agent uses was the blind half.
+            const flaky = await recordSuiteFlakes(deps.fs, deps.reticleRoot, runs);
             // Emit the consolidated run artifact (Runs tab) + best-effort cloud push. Never blocks the verdict.
             await persistAndSyncVerificationRun(deps, timed, projectId);
             const verdict = buildSuiteVerdict(runs);
             // A flow that has both passed and failed on UNCHANGED code is a different thing from a
             // regression, and an agent that cannot tell them apart either chases a ghost or ignores a real
             // break. Present only when the ledger has seen enough runs to say so.
-            return flaky.length > 0 ? { ...verdict, flaky } : verdict;
+            return flaky.length > 0 ? { ...verdict, flaky: [...flaky] } : verdict;
         },
     },
     {
@@ -397,6 +424,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()
@@ -427,10 +458,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 };
@@ -454,6 +488,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
@@ -466,6 +504,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>;

package/dist/flows/heal-run.js

@@ -12,7 +12,7 @@ import { replayFlow } from './flow-replay.js';
 import { applyHealChanges, collectProposals } from './heal.js';
 import { assertSuccess, dynamicTestids, successLabel } from './flow-success.js';
 import { flowErrorMessage, sessionProjectId } from './flow-replay-run.js';
-export const HEAL_MESSAGES = {
+const HEAL_MESSAGES = {
     NOTHING: 'nothing to heal — every anchor resolved on replay',
     HEALED: "rewrote drifted testid anchors to their nearest surviving match and re-verified the flow's success consequence still fires",
     DRIFT_DRY: 'confident rebind(s) proposed — re-run with apply:true to write them to disk',
@@ -25,7 +25,7 @@ function toChange(proposal) {
 }
 export async function healFlow(deps, args) {
     const name = asString(args['flowName']) ?? '';
-    const apply = args['apply'] === true;
+    const apply = true === args['apply'];
     const projectId = sessionProjectId(deps, asString(args['sessionId']));
     const loaded = await deps.flows.load(name, projectId);
     if (!loaded.ok) {
@@ -40,7 +40,7 @@ export async function healFlow(deps, args) {
         };
     }
     const session = deps.sessions.resolve(asString(args['sessionId']));
-    const steps = await replayFlow(session, loaded.value, waitForPredicate, FLOW_SIGNAL_TIMEOUT_MS, args['confirmDangerous'] === true);
+    const steps = await replayFlow(session, loaded.value, waitForPredicate, FLOW_SIGNAL_TIMEOUT_MS, true === args['confirmDangerous']);
     const drifted = steps.some((s) => s.drift !== undefined);
     const failed = steps.find((s) => !s.ok && s.drift === undefined);
     if (failed !== undefined) {
@@ -66,7 +66,7 @@ export async function healFlow(deps, args) {
         };
     }
     const proposals = collectProposals(steps);
-    if (proposals.length === 0) {
+    if (0 === proposals.length) {
         return {
             name,
             status: HealStatus.UNHEALABLE,
@@ -97,7 +97,7 @@ export async function healFlow(deps, args) {
         // Floor the success oracle at the start of the VERIFY replay so the earlier drift replay's signal
         // cannot fake the verification.
         const verifyFloor = session.elapsed();
-        const verifySteps = await replayFlow(session, toVerify, waitForPredicate, FLOW_SIGNAL_TIMEOUT_MS, args['confirmDangerous'] === true);
+        const verifySteps = await replayFlow(session, toVerify, waitForPredicate, FLOW_SIGNAL_TIMEOUT_MS, true === args['confirmDangerous']);
         const verifyClean = verifySteps.length > 0 && verifySteps.every((s) => s.ok && s.drift === undefined);
         const verdict = verifyClean
             ? await assertSuccess(session, healed.success, dynamicTestids(healed), waitForPredicate, FLOW_SIGNAL_TIMEOUT_MS, verifyFloor)

package/dist/flows/heal.js

@@ -23,7 +23,7 @@ export function confidenceFor(from, to) {
     if (from === to)
         return 1;
     const span = Math.max(from.length, to.length);
-    if (span === 0)
+    if (0 === span)
         return 1;
     const raw = 1 - editDistance(from, to) / span;
     if (raw >= 1)
@@ -62,10 +62,10 @@ function proposeRebindWith(drift, step, minConfidence) {
     // Never auto-heal an ambiguous drift: when two present testids tie at the minimum distance, the
     // `nearest` pick is arbitrary, so a rebind would be a coin-flip that can land on the wrong element
     // and ship a bug green. Surface it (the drift still carries `nearest`) and defer to a human.
-    if (drift.ambiguous === true)
+    if (true === drift.ambiguous)
         return undefined;
     const to = drift.nearest;
-    if (to === null)
+    if (null === to)
         return undefined;
     const confidence = confidenceFor(drift.anchor, to);
     if (confidence < minConfidence)

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

@@ -0,0 +1,38 @@
+/**
+ * The assertion the agent MADE, in the shape a saved flow can keep.
+ *
+ * `reticle_act_and_wait { until }` is how agents assert — 12 of 14 calls in a day of telemetry
+ * carried an `until`. `compileActStep` recorded only the ACTION, so a flow saved after an asserted
+ * drive came back graded `assertion-free`: "performs actions but asserts no observable consequence —
+ * it will pass even if the feature is broken." The agent had already said what success meant;
+ * Reticle discarded it and then warned the agent that the flow asserts nothing.
+ *
+ * That is the regression-suite story failing at its last step. "Record once, verify forever" is only
+ * worth anything if the recorded flow can go RED, and locally 32 of 39 saved flows cannot.
+ *
+ * The inverse of `successToPredicate`. Only the kinds FlowExpect can express are carried: `settled`
+ * is a wait rather than a claim, and `route`/`animation`/`anyOf`/`not` have no representation at all.
+ * Inventing one would write an assertion into the file that the agent never made, which is worse
+ * than recording none — a flow that asserts something nobody chose is a false green with extra steps.
+ */
+import type { FlowExpect } from '@reticlehq/core';
+import type { Predicate } from '../events/predicate.js';
+export declare function predicateToExpect(predicate: Predicate): FlowExpect | undefined;
+/**
+ * The subset a REPLAY actually enforces today.
+ *
+ * `flow-replay` checks exactly two things per step: `expect.element.testid` is present after the
+ * action, and `expect.state` holds. A recorded `net` or `signal` expect is graded as a consequence
+ * assertion by `classifyFlowAssertions` and then never evaluated — so writing one into a flow file
+ * would make it report `grade: "asserted"` while nothing checks it.
+ *
+ * That is a false green, in the feature whose entire purpose is preventing them, produced by the
+ * change that was meant to strengthen it. So only the enforced kinds are recorded: a flow that says
+ * it asserts something must actually go red when that thing breaks.
+ *
+ * Lifting this is worth doing — net and signal are the assertions agents most often make, and the
+ * conversion above already handles them — but it requires replay to evaluate them per step (the
+ * machinery exists: successToPredicate + the predicate engine). Until then, recording them would
+ * trade a weak flow for a lying one.
+ */
+export declare function enforcedOnReplay(expect: FlowExpect | undefined): FlowExpect | undefined;

package/dist/flows/predicate-to-expect.js

@@ -0,0 +1,95 @@
+import { PredicateKind } from '@reticlehq/core';
+/** Merge two partial expectations; later keys win only where the earlier one said nothing. */
+function merge(into, from) {
+    return { ...from, ...into };
+}
+export function predicateToExpect(predicate) {
+    switch (predicate.kind) {
+        case PredicateKind.SIGNAL: {
+            if (predicate.name === undefined)
+                return undefined;
+            return predicate.dataMatches === undefined
+                ? { signal: predicate.name }
+                : { signal: predicate.name, signalData: predicate.dataMatches };
+        }
+        case PredicateKind.NET: {
+            const net = {};
+            if (predicate.method !== undefined)
+                net.method = predicate.method;
+            if (predicate.urlContains !== undefined)
+                net.urlContains = predicate.urlContains;
+            if (predicate.status !== undefined)
+                net.status = predicate.status;
+            if (predicate.count !== undefined)
+                net.count = predicate.count;
+            return 0 === Object.keys(net).length ? undefined : { net };
+        }
+        case PredicateKind.CONSOLE: {
+            const console_ = {};
+            if (predicate.level !== undefined)
+                console_.level = predicate.level;
+            if (predicate.absent !== undefined)
+                console_.absent = predicate.absent;
+            return 0 === Object.keys(console_).length ? undefined : { console: console_ };
+        }
+        case PredicateKind.ELEMENT: {
+            const element = {};
+            if (predicate.query.testid !== undefined)
+                element.testid = predicate.query.testid;
+            if (predicate.query.role !== undefined)
+                element.role = predicate.query.role;
+            if (predicate.query.name !== undefined)
+                element.name = predicate.query.name;
+            return 0 === Object.keys(element).length ? undefined : { element };
+        }
+        case PredicateKind.STATE: {
+            const state = { path: predicate.path };
+            if (predicate.store !== undefined)
+                state.store = predicate.store;
+            if (predicate.equals !== undefined)
+                state.equals = predicate.equals;
+            return { state };
+        }
+        case PredicateKind.ALL_OF: {
+            // `settled` members drop out on their own by returning undefined.
+            let combined;
+            for (const part of predicate.predicates) {
+                const expect = predicateToExpect(part);
+                if (expect === undefined)
+                    continue;
+                combined = combined === undefined ? expect : merge(combined, expect);
+            }
+            return combined;
+        }
+        default:
+            // settled | route | animation | anyOf | not — nothing FlowExpect can say honestly.
+            return undefined;
+    }
+}
+/**
+ * The subset a REPLAY actually enforces today.
+ *
+ * `flow-replay` checks exactly two things per step: `expect.element.testid` is present after the
+ * action, and `expect.state` holds. A recorded `net` or `signal` expect is graded as a consequence
+ * assertion by `classifyFlowAssertions` and then never evaluated — so writing one into a flow file
+ * would make it report `grade: "asserted"` while nothing checks it.
+ *
+ * That is a false green, in the feature whose entire purpose is preventing them, produced by the
+ * change that was meant to strengthen it. So only the enforced kinds are recorded: a flow that says
+ * it asserts something must actually go red when that thing breaks.
+ *
+ * Lifting this is worth doing — net and signal are the assertions agents most often make, and the
+ * conversion above already handles them — but it requires replay to evaluate them per step (the
+ * machinery exists: successToPredicate + the predicate engine). Until then, recording them would
+ * trade a weak flow for a lying one.
+ */
+export function enforcedOnReplay(expect) {
+    if (expect === undefined)
+        return undefined;
+    const kept = {};
+    if (expect.element?.testid !== undefined)
+        kept.element = expect.element;
+    if (expect.state !== undefined)
+        kept.state = expect.state;
+    return 0 === Object.keys(kept).length ? undefined : kept;
+}

package/dist/flows/replay.d.ts

@@ -15,6 +15,17 @@ export declare function ambiguousTestidNote(value: string): string;
 export declare function queryRefs(result: CommandResult): string[];
 /** A destructive-action confirmation is one-shot and must never persist into a recording. */
 export declare function replayActionArgs(value: unknown, confirmDangerous?: boolean): Record<string, unknown>;
+/**
+ * Capture an act into every in-flight recording, or do nothing when none is running.
+ *
+ * Every tool that drives the page must call this. reticle_act_and_wait did not, which is the tool
+ * the documented agent recipe drives with — so "record start -> drive -> record stop -> flow_save"
+ * saved a flow with zero steps.
+ */
+export declare function captureAct(recordings: {
+    active: () => string[];
+    capture: (step: RecordedStep) => void;
+}, args: Record<string, unknown>, res: unknown): void;
 /**
  * Compile a single reticle_act invocation into a normalized RecordedStep using the action result. Anchor
  * priority mirrors synthesizeAnchor: a data-testid is the gold standard; failing that, the element's
@@ -22,7 +33,11 @@ export declare function replayActionArgs(value: unknown, confirmDangerous?: bool
  * a volatile ref. Only when neither is available is the step ref-bound (in-session only).
  */
 export declare function compileActStep(args: Record<string, unknown>, res: unknown): RecordedStep;
-/** Compile an reticle_act_sequence invocation, normalizing each sub-step to its testid where resolvable. */
+/**
+ * Compile an reticle_act_sequence invocation, normalizing each sub-step through the SAME anchor
+ * priority a single act uses (see compileAnchorArgs) — not testid-or-nothing, which is what made
+ * every sequence unreplayable on an app without testids.
+ */
 export declare function compileSequenceStep(args: Record<string, unknown>, res: unknown): RecordedStep;
 interface ReplayStepResult {
     tool: string;