@reticlehq/server 2.0.0

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

@@ -0,0 +1,33 @@
+/**
+ * Evaluate a flow's `success` end-condition — "green means intent satisfied".
+ *
+ * This is the one piece replay does NOT do per-step: turn a flow's success FlowExpect into a
+ * Predicate and assert it with the SAME waitForPredicate engine the tools/replay use. A signal/net
+ * success is a real CONSEQUENCE — a locator healed to the wrong element cannot fake it, so it
+ * catches the regression self-healing tools ship green (mabl/qate.ai). The dynamic skip-set is
+ * honored exactly as in replay: a success bound to a dynamic (LLM-output) testid is presence-only,
+ * never asserted, so the skip is symmetric across the step layer and the success layer.
+ *
+ * Lives in reticle-server (alongside the predicate engine) so BOTH the live MCP `reticle_flow_replay`
+ * tool and the `@reticlehq/test` spec runner share one implementation — no divergent oracle.
+ * Pure: no IO, no clock.
+ */
+import { type FlowExpect, type FlowFile } from '@reticlehq/core';
+import type { EvalResult, Predicate } from '../events/predicate.js';
+import type { FlowReplaySession, WaitForSignal } from './flow-replay.js';
+/** The dynamic (LLM-output) testids whose presence is never asserted — same rule replay uses. */
+export declare function dynamicTestids(flow: FlowFile): Set<string>;
+/** The synthetic step.tool a replay appends when it asserts the flow's success oracle. */
+export declare const SUCCESS_STEP_TOOL = "success";
+/** A short human label for the success end-condition, for result rows. */
+export declare function successLabel(success: FlowExpect): string;
+/** Compile a success FlowExpect into a predicate. undefined → nothing assertable (vacuously met). */
+export declare function successToPredicate(success: FlowExpect, dynamic: ReadonlySet<string>): Predicate | undefined;
+/**
+ * Assert a flow's success end-condition after replay. Delegates to the injected waitForSignal (the
+ * real waitForPredicate in production, a fake in unit tests). Passes when: no success was declared,
+ * OR every success field was dynamic-skipped (vacuously met), OR the compiled predicate held within
+ * the injected timeout. Never reads the wall clock.
+ */
+export declare function assertSuccess(session: FlowReplaySession, success: FlowExpect | undefined, dynamic: ReadonlySet<string>, waitForSignal: WaitForSignal, timeoutMs: number, since?: number): Promise<EvalResult>;
+//# sourceMappingURL=flow-success.d.ts.map

package/dist/flows/flow-success.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-success.d.ts","sourceRoot":"","sources":["../../src/flows/flow-success.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAc,KAAK,UAAU,EAAE,KAAK,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC7E,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACpE,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEzE,iGAAiG;AACjG,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,GAAG,CAAC,MAAM,CAAC,CAM1D;AAED,0FAA0F;AAC1F,eAAO,MAAM,iBAAiB,YAAY,CAAC;AAE3C,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM,CAQxD;AAED,qGAAqG;AACrG,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,UAAU,EACnB,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,GAC3B,SAAS,GAAG,SAAS,CAsEvB;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE,UAAU,GAAG,SAAS,EAC/B,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,EAC5B,aAAa,EAAE,aAAa,EAC5B,SAAS,EAAE,MAAM,EACjB,KAAK,SAAI,GACR,OAAO,CAAC,UAAU,CAAC,CAOrB"}

package/dist/flows/flow-success.js

@@ -0,0 +1,131 @@
+/**
+ * Evaluate a flow's `success` end-condition — "green means intent satisfied".
+ *
+ * This is the one piece replay does NOT do per-step: turn a flow's success FlowExpect into a
+ * Predicate and assert it with the SAME waitForPredicate engine the tools/replay use. A signal/net
+ * success is a real CONSEQUENCE — a locator healed to the wrong element cannot fake it, so it
+ * catches the regression self-healing tools ship green (mabl/qate.ai). The dynamic skip-set is
+ * honored exactly as in replay: a success bound to a dynamic (LLM-output) testid is presence-only,
+ * never asserted, so the skip is symmetric across the step layer and the success layer.
+ *
+ * Lives in reticle-server (alongside the predicate engine) so BOTH the live MCP `reticle_flow_replay`
+ * tool and the `@reticlehq/test` spec runner share one implementation — no divergent oracle.
+ * Pure: no IO, no clock.
+ */
+import { AnchorKind } 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 ?? [])
+        .filter((a) => a.kind === AnchorKind.TESTID)
+        .map((a) => (a.kind === AnchorKind.TESTID ? a.value : '')));
+}
+/** The synthetic step.tool a replay appends when it asserts the flow's success oracle. */
+export const SUCCESS_STEP_TOOL = 'success';
+/** A short human label for the success end-condition, for result rows. */
+export function successLabel(success) {
+    if (success.signal !== undefined)
+        return success.signal;
+    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')}`;
+    }
+    if (success.state !== undefined)
+        return `state:${success.state.path}`;
+    return success.element?.testid ?? success.element?.name ?? success.element?.role ?? 'success';
+}
+/** Compile a success FlowExpect into a predicate. undefined → nothing assertable (vacuously met). */
+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 });
+    }
+    if (success.net !== undefined) {
+        const net = { kind: 'net' };
+        if (success.net.method !== undefined)
+            net.method = success.net.method;
+        if (success.net.urlContains !== undefined)
+            net.urlContains = success.net.urlContains;
+        if (success.net.status !== undefined)
+            net.status = success.net.status;
+        if (success.net.count !== undefined) {
+            net.count = success.net.count;
+            // A cardinality assertion is inherently POST-SETTLE. The success waiter is wait-until-true, so an
+            // 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(net);
+    }
+    if (success.console !== undefined) {
+        const con = { kind: 'console' };
+        if (success.console.level !== undefined)
+            con.level = success.console.level;
+        if (success.console.absent !== undefined) {
+            con.absent = success.console.absent;
+            // An `absent` assertion is post-settle, same as net.count: a wait-until-true waiter sees "no
+            // 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(con);
+    }
+    const state = success.state;
+    if (state !== undefined) {
+        const part = { kind: 'state', path: state.path };
+        if (state.store !== undefined)
+            part.store = state.store;
+        if (state.equals !== undefined)
+            part.equals = state.equals;
+        // `hold` = an INVARIANT ("this state must still hold after the action settles"), vs the default
+        // 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' });
+        parts.push(part);
+    }
+    const element = success.element;
+    if (element !== undefined) {
+        const testid = element.testid;
+        // A dynamic-marked testid is NOT asserted as a success condition (presence-only).
+        if (testid === undefined || !dynamic.has(testid)) {
+            const query = {};
+            if (testid !== undefined)
+                query['testid'] = testid;
+            if (element.role !== undefined)
+                query['role'] = element.role;
+            if (element.name !== undefined)
+                query['name'] = element.name;
+            if (Object.keys(query).length > 0)
+                parts.push({ kind: 'element', query });
+        }
+    }
+    const [first] = parts;
+    if (parts.length === 0)
+        return undefined;
+    if (parts.length === 1 && first !== undefined)
+        return first;
+    return { kind: 'allOf', predicates: parts };
+}
+/**
+ * Assert a flow's success end-condition after replay. Delegates to the injected waitForSignal (the
+ * real waitForPredicate in production, a fake in unit tests). Passes when: no success was declared,
+ * OR every success field was dynamic-skipped (vacuously met), OR the compiled predicate held within
+ * the injected timeout. Never reads the wall clock.
+ */
+export async function assertSuccess(session, success, dynamic, waitForSignal, timeoutMs, since = 0) {
+    if (success === undefined)
+        return { pass: true };
+    const predicate = successToPredicate(success, dynamic);
+    if (predicate === undefined)
+        return { pass: true };
+    // `since` floors the window at the start of THIS replay so a success signal left in the buffer by
+    // a prior replay/run (or, in heal, by the pre-heal drift replay) cannot fake a pass.
+    return waitForSignal(session, predicate, timeoutMs, since);
+}
+//# sourceMappingURL=flow-success.js.map

package/dist/flows/flow-success.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-success.js","sourceRoot":"","sources":["../../src/flows/flow-success.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,4 @@
+import type { ToolDef } from '../tools/tools.js';
+export { replayNamedFlow } from './flow-replay-run.js';
+export declare const FLOW_TOOLS: ToolDef[];
+//# sourceMappingURL=flow-tools.d.ts.map

package/dist/flows/flow-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-tools.d.ts","sourceRoot":"","sources":["../../src/flows/flow-tools.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,OAAO,EAAY,MAAM,mBAAmB,CAAC;AAG3D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AA6BvD,eAAO,MAAM,UAAU,EAAE,OAAO,EAoT/B,CAAC"}

package/dist/flows/flow-tools.js

@@ -0,0 +1,460 @@
+import { z } from 'zod';
+import { FLOW_SIGNAL_TIMEOUT_MS, FlowErrorCode, HEAL_CONFIDENCE_MIN, HealStatus, RecordedSaveError, ReplayStatus, } from '@reticlehq/core';
+import { ReticleTool } from '../tools/tool-names.js';
+import { asString } from '../tools/tools-helpers.js';
+import { log } from '../log.js';
+import { resolveCloudConfig, syncFlowToCloud, SyncOutcome } from '../cloud/cloud-sync.js';
+import { replayFlow } from './flow-replay.js';
+import { buildSuiteVerdict } from './decision.js';
+import { classifyFlowAssertions } from './flow-classify.js';
+import { assertSuccess, dynamicTestids, successLabel } from './flow-success.js';
+import { flowPath } from '../project/reticle-dir.js';
+import { applyHealChanges, collectProposals } from './heal.js';
+import { waitForPredicate } from '../events/predicate.js';
+import { replayNamedFlow, flowErrorMessage, latestRecordedFlow } from './flow-replay-run.js';
+export { replayNamedFlow } from './flow-replay-run.js';
+/**
+ * The connecting session's project, or undefined when no browser is attached. Flow tools use it to
+ * scope storage to the current app on a shared daemon; resolving must NOT throw here (list/load are
+ * documented to work headless), so a missing/unknown session degrades to the global/legacy store.
+ */
+function sessionProjectId(deps, sessionId) {
+    try {
+        return deps.sessions.resolve(sessionId).projectId;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Best-effort mirror of a just-saved flow to Reticle Cloud (only when logged in — both cloud env vars
+ * set). Fire-and-forget: resolves the config, POSTs via the platform fetch, and logs the outcome. Any
+ * failure is swallowed so a network hiccup never affects the local save.
+ */
+async function syncSavedFlowToCloud(flow, projectId) {
+    const config = resolveCloudConfig(process.env);
+    if (config === null)
+        return; // not logged in → stays local
+    const result = await syncFlowToCloud(flow, config, projectId, (url, init) => fetch(url, init));
+    if (result.outcome !== SyncOutcome.SYNCED) {
+        log('cloud-flow-sync-failed', { flow: flow.name, status: result.status, error: result.error });
+    }
+}
+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: {
+            flowName: z
+                .string()
+                .describe('Name for the flow file (saved to .reticle/flows/<flowName>.json). Use again in reticle_flow_load/reticle_flow_replay.'),
+            sessionId: z
+                .string()
+                .optional()
+                .describe('Active session ID — scopes the saved flow to that app.'),
+        },
+        // Schema MUST match what the handler actually returns on BOTH paths: success
+        // { name, stepCount, degraded, empty, assertions? } and error { error, code }. The prior schema
+        // declared { saved, path } — fields the handler never returns — so a schema-validating MCP
+        // client rejected every reticle_flow_save result ("expected boolean"). Unit tests call the handler
+        // directly and bypass MCP output validation, so only a live MCP run caught it (cf. the same
+        // class of bug fixed for FLOW_LIST above).
+        outputSchema: {
+            name: z.string().optional(),
+            stepCount: z.number().optional(),
+            degraded: z.number().optional(),
+            empty: z.boolean().optional(),
+            assertions: z
+                .object({
+                grade: z.string().describe('asserted | presence-only | assertion-free'),
+                hasConsequenceAssertion: z.boolean(),
+                totalSteps: z.number(),
+                consequenceSteps: z.number(),
+                weakSteps: z.number(),
+                warning: z.string().optional(),
+            })
+                .optional(),
+            error: z.string().optional(),
+            code: z.string().optional(),
+        },
+        handler: (deps, args) => {
+            const name = asString(args['flowName']) ?? '';
+            const program = deps.recordings.getCompiled(name);
+            if (program === undefined) {
+                return Promise.resolve({
+                    error: flowErrorMessage(FlowErrorCode.NO_RECORDING),
+                    code: FlowErrorCode.NO_RECORDING,
+                });
+            }
+            // fold any structured annotations (expect/dynamic/success/intent) onto the saved flow.
+            const success = deps.annotations.success(name);
+            const intent = deps.annotations.intent(name);
+            const annotations = {
+                stepExpect: deps.annotations.stepExpect(name),
+                dynamic: deps.annotations.dynamic(name),
+                ...(success !== undefined ? { success } : {}),
+                ...(intent !== undefined ? { intent } : {}),
+            };
+            const projectId = sessionProjectId(deps, asString(args['sessionId']));
+            return deps.flows.save(program, annotations, projectId).then(async (res) => {
+                if (!res.ok)
+                    return { error: flowErrorMessage(res.code), 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).
+                const loaded = await deps.flows.load(res.value.name, projectId);
+                return loaded.ok
+                    ? { ...res.value, assertions: classifyFlowAssertions(loaded.value) }
+                    : res.value;
+            });
+        },
+    },
+    {
+        name: ReticleTool.FLOW_LIST,
+        description: 'List saved flow names under .reticle/flows (a fresh agent learns the demonstrated journeys ' +
+            'without a browser). Scoped to the connected app: with a session it lists that project’s ' +
+            'flows plus legacy untagged ones; with no browser it lists every flow in the repo.',
+        inputSchema: {
+            sessionId: z
+                .string()
+                .optional()
+                .describe('Active session ID — scopes the list to that app. Omit to list every saved flow.'),
+        },
+        outputSchema: {
+            flows: z.array(z.object({ name: z.string(), path: z.string(), createdAt: z.number().optional() })),
+        },
+        // Return {name, path} objects to MATCH the declared outputSchema. Returning bare name strings
+        // (the prior bug) made schema-validating MCP clients reject the result ("expected object,
+        // received string") — caught driving the live demo.
+        handler: (deps, args) => {
+            const projectId = sessionProjectId(deps, asString(args['sessionId']));
+            return deps.flows.list(projectId).then((names) => ({
+                flows: names.map((name) => ({ name, path: flowPath(deps.reticleRoot, name, projectId) })),
+            }));
+        },
+    },
+    {
+        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: {
+            flowName: z
+                .string()
+                .describe('Flow file name (without .json extension) from reticle_flow_list.'),
+            sessionId: z
+                .string()
+                .optional()
+                .describe('Active session ID — resolves the flow within that app’s scope.'),
+        },
+        outputSchema: {
+            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) => {
+                if (!res.ok)
+                    return { error: flowErrorMessage(res.code), code: res.code };
+                const { name, ...rest } = res.value;
+                return { flowName: name, ...rest };
+            });
+        },
+    },
+    {
+        name: ReticleTool.FLOW_REPLAY,
+        description: "Replay a git-checked flow from .reticle/flows/<name>.json. RE-RESOLVES each step's semantic " +
+            'anchor (testid via reticle_query; signal via predicate) against the LIVE DOM — never reuses a ' +
+            'stale ref. On an anchor MISS returns legible DRIFT { step, anchor, drift:{ reasonKind, reason, ' +
+            'nearest } } (the closest surviving testid) and stops — the "whose fault is it" contract. ' +
+            '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: {
+            flowName: z
+                .string()
+                .describe('Flow file name (without .json extension) from reticle_flow_list.'),
+            confirmDangerous: z
+                .boolean()
+                .optional()
+                .describe('Set true to allow destructive controls during this replay only.'),
+            sessionId: z
+                .string()
+                .optional()
+                .describe('Active session ID from reticle_sessions. Omit when only one browser session is open.'),
+        },
+        outputSchema: {
+            status: z.string().describe('ok | drift | error'),
+            steps: z.array(z.unknown()),
+            proposals: z.array(z.unknown()).optional(),
+            error: z.object({ code: z.string(), message: z.string() }).optional(),
+            decision: z
+                .object({
+                verdict: z.string(),
+                summary: z.string(),
+                whatChanged: z.string().optional(),
+                whereInSource: z.string().optional(),
+                suggestedFix: z.string().optional(),
+                nextAction: z.string(),
+            })
+                .optional()
+                .describe('Autonomy envelope: verdict + what changed + where + fix + next action.'),
+        },
+        // The decision envelope is attached by replayNamedFlow only on drift/fail (clean pass stays
+        // token-flat). Single-flow replay and whole-suite verify share that one implementation.
+        handler: (deps, args) => replayNamedFlow(deps, args),
+    },
+    {
+        name: ReticleTool.FLOW_VERIFY,
+        description: 'Replay EVERY saved flow (or a given subset) and return ONE consolidated suite verdict — the ' +
+            'autonomous regression check to run after a build/change. Deterministic (no LLM per flow). ' +
+            'Returns { status: pass|fail, total, passed, failed, summary, failures:[{ flow, verdict, ' +
+            'whatChanged, whereInSource, nextAction }] } — passing flows are counted, only failures carry ' +
+            'detail (the actionable fix). One call replaces N hand-driven replays.',
+        inputSchema: {
+            names: z
+                .array(z.string())
+                .optional()
+                .describe('Flow names to verify. Omit to verify every saved flow.'),
+            sessionId: z
+                .string()
+                .optional()
+                .describe('Active session ID from reticle_sessions. Omit when only one browser session is open.'),
+        },
+        outputSchema: {
+            status: z.string().describe('pass | fail'),
+            total: z.number(),
+            passed: z.number(),
+            failed: z.number(),
+            summary: z.string(),
+            failures: z.array(z.unknown()),
+        },
+        handler: async (deps, args) => {
+            const sessionId = asString(args['sessionId']);
+            // "Replay all" means all of THIS app's flows (+ legacy), not every project's on a shared daemon.
+            const requested = Array.isArray(args['names'])
+                ? args['names'].filter((n) => typeof n === 'string')
+                : await deps.flows.list(sessionProjectId(deps, sessionId));
+            const runs = [];
+            // Sequential: each flow replays against the same live session; parallel would race the DOM.
+            for (const flowName of requested) {
+                const replay = await replayNamedFlow(deps, { flowName, sessionId });
+                runs.push({ replay });
+            }
+            return buildSuiteVerdict(runs);
+        },
+    },
+    {
+        name: ReticleTool.FLOW_SAVE_RECORDED,
+        description: 'Persist the HUMAN-recorded flow from the live tab. The recorder toolbar compiles the ' +
+            "human's real clicks/inputs into a semantically anchored FlowFile in-page and emits it; this " +
+            'tool reads the LATEST recorded-flow from the session and writes it to .reticle/flows/<name>.json ' +
+            '(no recompilation — the browser already resolved every anchor). Pass `name` to override the ' +
+            'recorded name. Returns { name, stepCount, degraded, empty } or { error, code } (code ' +
+            'flow_no_recorded when no recording is present).',
+        inputSchema: {
+            flowName: z
+                .string()
+                .optional()
+                .describe('Override the flow name embedded in the recorded flow. Omit to use the recorder-assigned name.'),
+            ...{
+                sessionId: z
+                    .string()
+                    .optional()
+                    .describe('Active session ID from reticle_sessions. Omit when only one browser session is open.'),
+            },
+        },
+        // Match the handler's actual return (SaveSummary { name, stepCount, degraded, empty } or
+        // { error, code }) — the prior `flowName` key silently stripped the real `name`/`empty` fields.
+        outputSchema: {
+            name: z.string().optional(),
+            stepCount: z.number().optional(),
+            degraded: z.number().optional(),
+            empty: z.boolean().optional(),
+            error: z.string().optional(),
+            code: z.string().optional(),
+        },
+        handler: async (deps, args) => {
+            const session = deps.sessions.resolve(asString(args['sessionId']));
+            const recorded = latestRecordedFlow(session.eventsSince(0));
+            if (recorded === undefined) {
+                return {
+                    error: 'no human recording on this tab — start the recorder toolbar and click Stop first',
+                    code: RecordedSaveError.NO_RECORDED_FLOW,
+                };
+            }
+            const override = asString(args['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 res = await deps.flows.saveFlow(flow, session.projectId);
+            if (!res.ok)
+                return { error: flowErrorMessage(res.code), code: res.code };
+            // If logged into Reticle Cloud, 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(flow, session.projectId);
+            const { name, ...rest } = res.value;
+            return { flowName: name, ...rest };
+        },
+    },
+    {
+        name: ReticleTool.FLOW_HEAL,
+        description: 'Self-healing replay. Re-runs reticle_flow_replay; on testid DRIFT computes confidence-scored ' +
+            'nearest-match rebind PROPOSALS. With apply:false (default) returns the proposed diff WITHOUT ' +
+            'writing. With apply:true, writes the confident rebind(s) back into .reticle/flows/<name>.json and ' +
+            'returns what changed — never silently. Before writing, apply re-replays the healed flow and ' +
+            're-asserts its success consequence: if the rebound locator resolves but the consequence no ' +
+            'longer fires, the write is REFUSED (status:consequence_broken) — it heals the locator, never ' +
+            'the intent. A drift with no proposal above the confidence floor is status:unhealable (file ' +
+            'untouched). Returns { name, status: healed|drift|unhealable|consequence_broken|' +
+            'nothing_to_heal|error, applied, proposals[], changed[], message }.',
+        inputSchema: {
+            flowName: z.string().describe('Flow file name to heal (from reticle_flow_list).'),
+            apply: z.boolean().optional(),
+            confirmDangerous: z
+                .boolean()
+                .optional()
+                .describe('Set true to allow destructive controls during this heal replay only.'),
+            sessionId: z
+                .string()
+                .optional()
+                .describe('Active session ID from reticle_sessions. Omit when only one browser session is open.'),
+        },
+        outputSchema: {
+            flowName: z.string(),
+            status: z.string(),
+            applied: z.boolean(),
+            proposals: z.array(z.unknown()),
+            changed: z.array(z.unknown()),
+            message: z.string(),
+            error: z.object({ code: z.string(), message: z.string() }).optional(),
+        },
+        handler: (deps, args) => healFlow(deps, args).then(({ name, ...rest }) => ({ flowName: name, ...rest })),
+    },
+];
+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',
+    UNHEALABLE: `drift found, but no nearest match cleared the confidence floor (HEAL_CONFIDENCE_MIN=${HEAL_CONFIDENCE_MIN}); file left untouched — add a data-testid or fix the flow by hand`,
+    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.',
+    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',
+};
+function toChange(proposal) {
+    return { step: proposal.step, from: proposal.from, to: proposal.to };
+}
+/**
+ * Self-heal handler: load → replay → collect confident proposals → (apply ? write : dry).
+ * Never silently rewrites: only proposals that cleared HEAL_CONFIDENCE_MIN are eligible, and only
+ * when apply:true. A heal disk failure maps back to status:error.
+ */
+async function healFlow(deps, args) {
+    const name = asString(args['flowName']) ?? '';
+    const apply = args['apply'] === true;
+    const projectId = sessionProjectId(deps, asString(args['sessionId']));
+    const loaded = await deps.flows.load(name, projectId);
+    if (!loaded.ok) {
+        return {
+            name,
+            status: HealStatus.ERROR,
+            applied: false,
+            proposals: [],
+            changed: [],
+            message: flowErrorMessage(loaded.code),
+            error: { code: loaded.code, message: flowErrorMessage(loaded.code) },
+        };
+    }
+    const session = deps.sessions.resolve(asString(args['sessionId']));
+    const steps = await replayFlow(session, loaded.value, waitForPredicate, FLOW_SIGNAL_TIMEOUT_MS, args['confirmDangerous'] === true);
+    const drifted = steps.some((s) => s.drift !== undefined);
+    const failed = steps.find((s) => !s.ok && s.drift === undefined);
+    if (failed !== undefined) {
+        const message = failed.error ?? 'flow replay failed before an anchor could be healed';
+        return {
+            name,
+            status: HealStatus.ERROR,
+            applied: false,
+            proposals: [],
+            changed: [],
+            message,
+            error: { code: ReplayStatus.ERROR, message },
+        };
+    }
+    if (!drifted) {
+        return {
+            name,
+            status: HealStatus.NOTHING_TO_HEAL,
+            applied: false,
+            proposals: [],
+            changed: [],
+            message: HEAL_MESSAGES.NOTHING,
+        };
+    }
+    const proposals = collectProposals(steps);
+    if (proposals.length === 0) {
+        return {
+            name,
+            status: HealStatus.UNHEALABLE,
+            applied: false,
+            proposals: [],
+            changed: [],
+            message: HEAL_MESSAGES.UNHEALABLE,
+        };
+    }
+    if (!apply) {
+        return {
+            name,
+            status: HealStatus.DRIFT,
+            applied: false,
+            proposals,
+            changed: [],
+            message: HEAL_MESSAGES.DRIFT_DRY,
+        };
+    }
+    // Heal-the-locator-never-the-intent invariant: "heal the locator, never the intent." Before persisting, verify the rebind on a
+    // healed in-memory copy: a rebound testid can resolve to a real but WRONG element that no longer
+    // triggers the flow's success consequence (e.g. a look-alike control). Persisting that would ship
+    // a green flow that tests nothing. Re-replay the healed flow and assert its success; refuse the
+    // write if the consequence no longer fires. Flows with no declared success can't be verified — we
+    // still heal them but say so loudly so the gap is visible.
+    const { flow: healed } = applyHealChanges(loaded.value, proposals.map(toChange));
+    if (healed.success !== undefined) {
+        // Floor the success oracle at the start of the VERIFY replay so the success signal emitted by the
+        // earlier drift replay's prefix (this same heal call) cannot fake the verification.
+        const verifyFloor = session.elapsed();
+        const verifySteps = await replayFlow(session, healed, waitForPredicate, FLOW_SIGNAL_TIMEOUT_MS, args['confirmDangerous'] === true);
+        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)
+            : { pass: false, failureReason: 'healed flow did not replay cleanly' };
+        if (!verdict.pass) {
+            return {
+                name,
+                status: HealStatus.CONSEQUENCE_BROKEN,
+                applied: false,
+                proposals,
+                changed: [],
+                message: `${HEAL_MESSAGES.CONSEQUENCE_BROKEN} (${successLabel(healed.success)}: ${verdict.failureReason ?? 'not satisfied'})`,
+            };
+        }
+    }
+    const written = await deps.flows.heal(name, proposals.map(toChange), projectId);
+    if (!written.ok) {
+        return {
+            name,
+            status: HealStatus.ERROR,
+            applied: false,
+            proposals,
+            changed: [],
+            message: flowErrorMessage(written.code),
+            error: { code: written.code, message: flowErrorMessage(written.code) },
+        };
+    }
+    return {
+        name,
+        status: HealStatus.HEALED,
+        applied: written.value.changed.length > 0,
+        proposals,
+        changed: written.value.changed,
+        message: loaded.value.success !== undefined ? HEAL_MESSAGES.HEALED : HEAL_MESSAGES.HEALED_UNVERIFIED,
+    };
+}
+//# sourceMappingURL=flow-tools.js.map