@reticlehq/server 3.2.0 → 3.4.0

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

@@ -12,21 +12,36 @@
  * 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 '@reticlehq/engine/question/predicate/predicate.js';
+import { type FlowExpect, type FlowFile, type Predicate } from '@reticlehq/core';
+import type { EvalResult } from '@reticlehq/engine/question/predicate/predicate.js';
 import type { FlowReplaySession, WaitForSignal } from './flow-replay-types.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;
+export declare function successLabel(success: Predicate | undefined): string;
+/**
+ * What a flow's success oracle actually asserts, once the file has been read and the dynamic
+ * (LLM-output) testids have been taken out of it.
+ *
+ * Most of what this function used to do is gone, and that is the migration working as intended: it
+ * compiled a flat `FlowExpect` into a `Predicate`, and a step's `expect` IS a predicate now, lifted
+ * by the schema when the file is read. It keeps the name and the signature because it is on
+ * `@reticlehq/test`'s published surface, and it still accepts the flat shape for the same reason a
+ * v1 file still loads — a spec written against the old spelling is not wrong, it is old.
+ *
+ * What remains is the DYNAMIC SKIP, and it is not cosmetic. A testid whose content a model writes is
+ * asserted for PRESENCE by the step layer and never for content; a success oracle bound to one would
+ * assert exactly what the flow has already declared unassertable. Dropping every such clause can
+ * leave nothing at all, and `undefined` is the honest answer — vacuously met, the same as declaring
+ * no success, because nothing here was checkable.
+ */
+export declare function successToPredicate(success: Predicate | FlowExpect | undefined, 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>;
+export declare function assertSuccess(session: FlowReplaySession, success: Predicate | undefined, dynamic: ReadonlySet<string>, waitForSignal: WaitForSignal, timeoutMs: number, since?: number): Promise<EvalResult>;

package/dist/language/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, PredicateKind } from '@reticlehq/core';
+import { AnchorKind, PredicateKind, clauseOfKind, flowExpectToPredicate, withoutClauses, } 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 ?? [])
@@ -23,145 +23,59 @@ export function dynamicTestids(flow) {
 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:${true === success.console.absent ? 'clean' : (success.console.level ?? 'error')}`;
+    /*
+     * NOT `expectLabel`, and the difference is the reader.
+     *
+     * That one names a clause for a drift row, where `signal:` tells you which channel failed. This
+     * one is `mustHold` in the domain model an agent reads BEFORE testing — a list of what each flow
+     * guarantees — and there the prefix is noise on the commonest case. A signal's own name is the
+     * sentence: "order:placed" is what must hold.
+     */
+    const signal = clauseOfKind(success, PredicateKind.SIGNAL);
+    if (signal?.name !== undefined)
+        return signal.name;
+    const net = clauseOfKind(success, PredicateKind.NET);
+    if (net !== undefined)
+        return net.urlContains ?? net.method ?? 'net';
+    const console_ = clauseOfKind(success, PredicateKind.CONSOLE);
+    if (console_ !== undefined) {
+        return `console:${true === console_.absent ? 'clean' : (console_.level ?? 'error')}`;
     }
-    if (success.state !== undefined)
-        return `state:${success.state.path}`;
-    if (success.text !== undefined)
-        return `text:${success.text.contains}`;
-    return success.element?.testid ?? success.element?.name ?? success.element?.role ?? 'success';
+    const state = clauseOfKind(success, PredicateKind.STATE);
+    if (state !== undefined)
+        return `state:${state.path}`;
+    const text = clauseOfKind(success, PredicateKind.TEXT);
+    if (text?.contains !== undefined)
+        return `text:${text.contains}`;
+    const element = clauseOfKind(success, PredicateKind.ELEMENT);
+    const q = element?.query;
+    return q?.testid ?? q?.name ?? q?.role ?? 'success';
 }
-/** Compile a success FlowExpect into a predicate. undefined → nothing assertable (vacuously met). */
+/**
+ * What a flow's success oracle actually asserts, once the file has been read and the dynamic
+ * (LLM-output) testids have been taken out of it.
+ *
+ * Most of what this function used to do is gone, and that is the migration working as intended: it
+ * compiled a flat `FlowExpect` into a `Predicate`, and a step's `expect` IS a predicate now, lifted
+ * by the schema when the file is read. It keeps the name and the signature because it is on
+ * `@reticlehq/test`'s published surface, and it still accepts the flat shape for the same reason a
+ * v1 file still loads — a spec written against the old spelling is not wrong, it is old.
+ *
+ * What remains is the DYNAMIC SKIP, and it is not cosmetic. A testid whose content a model writes is
+ * asserted for PRESENCE by the step layer and never for content; a success oracle bound to one would
+ * assert exactly what the flow has already declared unassertable. Dropping every such clause can
+ * leave nothing at all, and `undefined` is the honest answer — vacuously met, the same as declaring
+ * no success, because nothing here was checkable.
+ */
 export function successToPredicate(success, dynamic) {
-    const parts = [];
-    if (success.signal !== undefined) {
-        const signal = {
-            kind: PredicateKind.SIGNAL,
-            name: success.signal,
-        };
-        if (success.signalData !== undefined)
-            signal.dataMatches = success.signalData;
-        if (success.signalCount !== undefined) {
-            signal.count = success.signalCount;
-            // Same post-settle reasoning as net.count: the success waiter is wait-until-true, so an exact
-            // count is transiently satisfied the instant the FIRST matching signal fires — before a
-            // double-fire's duplicate arrives. Gating on `settled` forces the count to be read only after
-            // the app goes quiet, by which point the duplicate IS counted and the over-count fails.
-            parts.push({ kind: PredicateKind.SETTLED });
-        }
-        parts.push(signal);
-    }
-    if (success.route !== undefined) {
-        // The mirror of `predicateToExpect`'s ROUTE case. Replay evaluates predicates, so carrying the
-        // route back here is the whole of what makes a recorded navigation able to fail.
-        const route = {
-            kind: PredicateKind.ROUTE,
-        };
-        if (success.route.pathname !== undefined)
-            route.pathname = success.route.pathname;
-        if (success.route.contains !== undefined)
-            route.contains = success.route.contains;
-        return route;
-    }
-    if (success.net !== undefined) {
-        const net = { kind: PredicateKind.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: PredicateKind.SETTLED });
-        }
-        parts.push(net);
-    }
-    if (success.console !== undefined) {
-        const con = {
-            kind: PredicateKind.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: PredicateKind.SETTLED });
-        }
-        parts.push(con);
-    }
-    const state = success.state;
-    if (state !== undefined) {
-        const part = {
-            kind: PredicateKind.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 (true === state.hold)
-            parts.push({ kind: PredicateKind.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: PredicateKind.ELEMENT, query });
-        }
-    }
-    const text = success.text;
-    if (text !== undefined) {
-        const part = {
-            kind: PredicateKind.TEXT,
-            contains: text.contains,
-        };
-        if (text.scope !== undefined)
-            part.scope = text.scope;
-        if (text.visible !== undefined)
-            part.visible = text.visible;
-        if (true === text.absent) {
-            part.absent = true;
-            // Same post-settle reasoning as `console.absent` and `state.hold`: a wait-until-true waiter
-            // reads "not there yet" on the first poll and passes BEFORE the text it is meant to see
-            // disappear has even been rendered. Gate on `settled` so the read happens after the page
-            // quiets, by which point a text that was going to appear has.
-            parts.push({ kind: PredicateKind.SETTLED });
-        }
-        parts.push(part);
-    }
-    const [first] = parts;
-    if (0 === parts.length)
+    if (success === undefined)
         return undefined;
-    if (1 === parts.length && first !== undefined)
-        return first;
-    return { kind: PredicateKind.ALL_OF, predicates: parts };
+    const predicate = 'kind' in success ? success : flowExpectToPredicate(success);
+    if (predicate === undefined)
+        return undefined;
+    return withoutClauses(predicate, (clause) => PredicateKind.ELEMENT === clause.kind &&
+        clause.query.testid !== undefined &&
+        dynamic.has(clause.query.testid));
 }
 /**
  * Assert a flow's success end-condition after replay. Delegates to the injected waitForSignal (the
@@ -170,8 +84,6 @@ export function successToPredicate(success, dynamic) {
  * 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 };

package/dist/language/flows/flow-tools.js

@@ -1,3 +1,4 @@
+import { flowAuthor } from './flow-author.js';
 import { FLOW_MUTATE_TOOL } from './flow-mutate-tools.js';
 import { seedSchema } from '../../surface/tools/args/numeric-bounds.js';
 import { z } from 'zod';
@@ -217,7 +218,12 @@ export const FLOW_TOOLS = [
             if (emptyRefusal !== undefined)
                 return Promise.resolve(emptyRefusal);
             const { flows, root } = flowsForSession(deps, projectId);
-            const toSave = saveAs === undefined ? program : { ...program, name: saveAs };
+            const author = flowAuthor();
+            const toSave = {
+                ...program,
+                ...(saveAs === undefined ? {} : { name: saveAs }),
+                ...(author === undefined ? {} : { author }),
+            };
             return flows.save(toSave, annotations, projectId).then(async (res) => {
                 if (!res.ok)
                     return { error: flowErrorMessage(res.code, res.detail), code: res.code };
@@ -382,6 +388,10 @@ export const FLOW_TOOLS = [
                 .boolean()
                 .optional()
                 .describe('Set true to allow destructive controls during this replay only.'),
+            from: z
+                .union([z.number().int().nonnegative(), z.string().min(1)])
+                .optional()
+                .describe('Resume at this step (index or step id). Earlier steps re-run as unchecked, unreported setup; a setup step marked effect:"commits" refuses the resume.'),
             sweep: z
                 .boolean()
                 .optional()
@@ -636,9 +646,7 @@ export const FLOW_TOOLS = [
                     return flow === undefined ? { replay } : { replay, flow };
                 }));
                 const timed = outcomes.map((o, i) => ({
-                    replay: o.ok && o.value !== undefined
-                        ? o.value.replay
-                        : leaseFailureReplay(requested[i] ?? '', o.error),
+                    ...(parallelRuns[i] ?? { replay: leaseFailureReplay(requested[i] ?? '', o.error) }),
                     durationMs: o.ok && o.value !== undefined ? o.value.durationMs : 0,
                 }));
                 const flaky = await recordSuiteFlakes(deps.fs, rootForProjectId(deps, projectId), parallelRuns);
@@ -671,7 +679,11 @@ export const FLOW_TOOLS = [
                     .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 });
+                timed.push({
+                    replay,
+                    durationMs: deps.now() - start,
+                    ...(flow === undefined ? {} : { flow }),
+                });
             }
             // 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

package/dist/language/flows/flows.d.ts

@@ -1,8 +1,8 @@
-import { type ProjectId } from '@reticlehq/core';
-export { REDACTED_FILL } from './fields/flow-secret-field.js';
+import { type Predicate, type ProjectId } from '@reticlehq/core';
+export { REDACTED_FILL, secretEnvKey } from './fields/flow-secret-field.js';
 import { type FlowResult } from './flow-result.js';
 export type { FlowResult } from './flow-result.js';
-import type { FlowAnchor, FlowExpect, FlowFile, FlowStep, HealChange, InstrumentationGap } from '@reticlehq/core';
+import type { FlowAnchor, FlowFile, FlowStep, HealChange, InstrumentationGap } from '@reticlehq/core';
 import type { CompiledProgram, RecordedStep } from './recording/tape/recordings.js';
 import type { FileSystemPort } from '../../memory/project/fs/fs-port.js';
 import type { Clock } from '../../machine/clock.js';
@@ -49,9 +49,9 @@ interface SaveSummary {
  * the same bytes as before.
  */
 export interface FlowAnnotations {
-    stepExpect: Map<number, FlowExpect>;
+    stepExpect: Map<number, Predicate>;
     dynamic: string[];
-    success?: FlowExpect;
+    success?: Predicate;
     /** The flow's declared business goal (intent annotation). */
     intent?: string;
 }
@@ -65,6 +65,15 @@ export declare class FlowStore {
      * the flow before writing. Omitting `annotations` reproduces the same bytes.
      */
     save(program: CompiledProgram, annotations?: FlowAnnotations, projectId?: ProjectId): Promise<FlowResult<SaveSummary>>;
+    /**
+     * Save a flow the session drove, folded into any saved copy of the same journey.
+     *
+     * Every session saves its own drive, so one journey arrived as a near-copy per session. Flows
+     * under `prefix` (the auto-saved ones — a hand-named flow is never merged or removed) that start
+     * on the same page and take the same steps become ONE file: the oldest keeps its name, the others
+     * fill its gaps and are removed. The same scan collapses copies saved before this existed.
+     */
+    saveJourney(program: CompiledProgram, projectId: ProjectId | undefined, prefix: string): Promise<FlowResult<SaveSummary>>;
     /**
      * Persist an already-anchored FlowFile captured in-page (no recompilation). The
      * browser resolved every semantic anchor at capture time; here we only validate the name +
@@ -75,6 +84,10 @@ export declare class FlowStore {
     recordLearned(name: string, learned: NonNullable<FlowFile['learned']>, projectId?: ProjectId): Promise<FlowResult<{
         name: string;
     }>>;
+    /** Give sourceless steps the files a clean replay resolved them to, merged onto the file as it is now. */
+    recordSources(name: string, sources: ReadonlyMap<string, NonNullable<FlowStep['source']>>, projectId?: ProjectId): Promise<FlowResult<{
+        name: string;
+    }>>;
     /**
      * Apply confident testid rebinds to an on-disk flow (the `reticle_flow_heal` apply path),
      * rewriting ONLY the named steps' anchors and preserving every other field. Loading, the name

package/dist/language/flows/flows.js

@@ -1,13 +1,15 @@
-import { asFlowName, asProjectId } from '@reticlehq/core';
+import { asFlowName, asProjectId, } from '@reticlehq/core';
 import { REDACTED_FILL } from './fields/flow-secret-field.js';
-export { REDACTED_FILL } from './fields/flow-secret-field.js';
+export { REDACTED_FILL, secretEnvKey } from './fields/flow-secret-field.js';
 import { safeProjectId } from './flow-result.js';
 import { changeInPlace } from './narrow-write.js';
-import { AnchorKind, DEGRADED_ANCHOR_ROLE, FLOW_FILE_VERSION, FlowErrorCode, FlowFileSchema, FlowStepTool, QueryBy, defaultIsSensitiveKey, } from '@reticlehq/core';
+import { AnchorKind, DEGRADED_ANCHOR_ROLE, FLOW_FILE_VERSION, flowFileVersionFor, FlowErrorCode, FlowFileSchema, FlowStepTool, QueryBy, defaultIsSensitiveKey, } from '@reticlehq/core';
 import { ReticleTool } from '@reticlehq/core';
 import { asRecord, asString } from '@reticlehq/core';
 import { applyHealChanges } from './heal.js';
+import { withLearnedSources } from './learned-sources.js';
 import { flowIntentGap, linkFlowIntent } from './flow-intent.js';
+import { journeyFingerprint, journeyName, mergeJourney, routeClaims } from './flow-journey.js';
 import { IntentStore } from '../../memory/intent/intent-store.js';
 import { flowDir, flowParentDir, flowPath, reticleDirPaths, isValidFlowName, } from '../../memory/project/dir/reticle-dir.js';
 import { describeFlowZodFailure, parseFlowFileText } from './flow-expect-grammar.js';
@@ -163,6 +165,14 @@ function buildStep(tool, anchor, action, args, degraded) {
  * NEVER silently dropped. ACT_SEQUENCE recurses over its sub-steps.
  */
 export function recordedStepToFlowStep(step) {
+    const out = anchoredStep(step);
+    if (step.page !== undefined)
+        out.page = step.page;
+    if (step.endPage !== undefined && step.endPage !== step.page)
+        out.endPage = step.endPage;
+    return out;
+}
+function anchoredStep(step) {
     if (step.invoke !== undefined) {
         // An invocation drives nothing: no action, no args, and an anchor only because every step
         // carries one. Falling through to the action path below would give it an `action` and a
@@ -236,7 +246,8 @@ export class FlowStore {
      * of them produces byte-identical on-disk content (locked by the byte-stability tests).
      */
     #serialize(flow) {
-        return `${JSON.stringify(flow, null, JSON_INDENT)}\n`;
+        const stamped = { ...flow, version: flowFileVersionFor(flow) };
+        return `${JSON.stringify(stamped, null, JSON_INDENT)}\n`;
     }
     /**
      * Register the flow's business goal in the intent ledger and stamp the row's id onto the flow.
@@ -266,16 +277,8 @@ export class FlowStore {
             ...(gap === undefined ? {} : { intentGap: gap }),
         };
     }
-    /**
-     * Convert a CompiledProgram (testid-normalized) into an anchored, on-disk flow + write it.
-     * Optionally fold structured annotations (per-step expect, dynamic[], success) onto
-     * the flow before writing. Omitting `annotations` reproduces the same bytes.
-     */
-    async save(program, annotations, projectId) {
-        if (!isValidFlowName(program.name)) {
-            return { ok: false, code: FlowErrorCode.INVALID_NAME };
-        }
-        const pid = safeProjectId(projectId);
+    /** The on-disk flow a compiled recording becomes, before anything is written. */
+    #build(program, annotations, pid) {
         const steps = program.steps.map(recordedStepToFlowStep);
         const base = {
             version: FLOW_FILE_VERSION,
@@ -294,11 +297,85 @@ export class FlowStore {
              */
             ...(program.startPath === undefined ? {} : { startPath: program.startPath }),
         };
-        const flow = await this.#linkIntent(withAnnotations(base, annotations));
+        const intent = program.steps.find((step) => step.intent !== undefined)?.intent;
+        const annotated = withAnnotations(base, annotations);
+        return {
+            ...annotated,
+            // The action's own intent, when nobody annotated the flow — see RecordedStep.intent.
+            ...(annotated.intent === undefined && intent !== undefined ? { intent } : {}),
+            ...routeClaims(annotated.startPath, annotated.steps),
+            ...(program.author === undefined ? {} : { author: program.author }),
+        };
+    }
+    /**
+     * Convert a CompiledProgram (testid-normalized) into an anchored, on-disk flow + write it.
+     * Optionally fold structured annotations (per-step expect, dynamic[], success) onto
+     * the flow before writing. Omitting `annotations` reproduces the same bytes.
+     */
+    async save(program, annotations, projectId) {
+        if (!isValidFlowName(program.name)) {
+            return { ok: false, code: FlowErrorCode.INVALID_NAME };
+        }
+        const pid = safeProjectId(projectId);
+        const base = this.#build(program, annotations, pid);
+        const flow = await this.#linkIntent(base);
         await this.#fs.mkdir(flowParentDir(this.#root, program.name, pid));
         await this.#fs.writeFile(flowPath(this.#root, program.name, pid), this.#serialize(flow));
         return { ok: true, value: this.#summary(flow) };
     }
+    /**
+     * Save a flow the session drove, folded into any saved copy of the same journey.
+     *
+     * Every session saves its own drive, so one journey arrived as a near-copy per session. Flows
+     * under `prefix` (the auto-saved ones — a hand-named flow is never merged or removed) that start
+     * on the same page and take the same steps become ONE file: the oldest keeps its name, the others
+     * fill its gaps and are removed. The same scan collapses copies saved before this existed.
+     */
+    async saveJourney(program, projectId, prefix) {
+        if (!isValidFlowName(program.name))
+            return { ok: false, code: FlowErrorCode.INVALID_NAME };
+        const pid = safeProjectId(projectId);
+        const fresh = this.#build(program, undefined, pid);
+        const saved = [];
+        for (const name of (await this.list(pid)).filter((n) => n.startsWith(prefix))) {
+            const loaded = await this.load(name, pid);
+            if (loaded.ok)
+                saved.push(loaded.value);
+        }
+        const byPrint = new Map();
+        for (const flow of saved) {
+            const print = journeyFingerprint(flow);
+            byPrint.set(print, [...(byPrint.get(print) ?? []), flow]);
+        }
+        const print = journeyFingerprint(fresh);
+        const taken = new Map(saved.map((flow) => [flow.name, journeyFingerprint(flow)]));
+        const named = { ...fresh, name: journeyName(fresh.name, print, taken) };
+        byPrint.set(print, [...(byPrint.get(print) ?? []), named]);
+        let result = named;
+        for (const [groupPrint, group] of byPrint) {
+            if (group.length < 2 && groupPrint !== print)
+                continue;
+            const [kept, ...rest] = [...group].sort((a, b) => a.createdAt - b.createdAt);
+            if (kept === undefined)
+                continue;
+            const merged = await this.#linkIntent(rest.reduce(mergeJourney, kept));
+            await this.#writeInPlace(merged, pid);
+            for (const dropped of rest) {
+                if (dropped.name !== merged.name && dropped !== named)
+                    await this.remove(dropped.name, pid);
+            }
+            if (groupPrint === print)
+                result = merged;
+        }
+        return { ok: true, value: this.#summary(result) };
+    }
+    /** Write a flow where it already lives, or into its project's directory when it is new. */
+    async #writeInPlace(flow, pid) {
+        const name = asFlowName(flow.name);
+        const path = (await this.#resolveReadPath(name, pid)) ?? flowPath(this.#root, name, pid);
+        await this.#fs.mkdir(flowParentDir(this.#root, name, pid));
+        await this.#fs.writeFile(path, this.#serialize(flow));
+    }
     /**
      * Persist an already-anchored FlowFile captured in-page (no recompilation). The
      * browser resolved every semantic anchor at capture time; here we only validate the name +
@@ -351,6 +428,13 @@ export class FlowStore {
             value: { name },
         }));
     }
+    /** Give sourceless steps the files a clean replay resolved them to, merged onto the file as it is now. */
+    async recordSources(name, sources, projectId) {
+        return await this.#changeInPlace(name, projectId, (flow) => ({
+            next: withLearnedSources(flow, sources) ?? flow,
+            value: { name },
+        }));
+    }
     /**
      * Apply confident testid rebinds to an on-disk flow (the `reticle_flow_heal` apply path),
      * rewriting ONLY the named steps' anchors and preserving every other field. Loading, the name
@@ -362,7 +446,8 @@ export class FlowStore {
      */
     async heal(name, changes, projectId) {
         return await this.#changeInPlace(name, projectId, (flow) => {
-            const { flow: next, applied } = applyHealChanges(flow, changes);
+            // The store's injected clock, so a written flow records when the rebind actually happened.
+            const { flow: next, applied } = applyHealChanges(flow, changes, () => this.#clock.now());
             return { next, value: { name, changed: applied } };
         });
     }

package/dist/language/flows/heal.d.ts

@@ -25,7 +25,15 @@ export declare function confidenceFor(from: string, to: string): number;
  * skipped (idempotent / defensive), never throwing. Shared by the on-disk writer (FlowStore.heal)
  * and the in-memory pre-write verification in reticle_flow_heal, so both rewrite identically.
  */
-export declare function applyHealChanges(flow: FlowFile, changes: HealChange[]): {
+export declare function applyHealChanges(flow: FlowFile, changes: HealChange[], 
+/**
+ * When the rebind happened. Injected rather than read here, because this function is pure and a
+ * clock inside it would make the flow it returns depend on when a test ran.
+ *
+ * Optional so every existing caller keeps working; without it the step still records WHICH anchor
+ * was replaced, which is the half a reader actually acts on.
+ */
+now?: () => number): {
     flow: FlowFile;
     applied: HealChange[];
 };

package/dist/language/flows/heal.js

@@ -38,7 +38,15 @@ export function confidenceFor(from, to) {
  * skipped (idempotent / defensive), never throwing. Shared by the on-disk writer (FlowStore.heal)
  * and the in-memory pre-write verification in reticle_flow_heal, so both rewrite identically.
  */
-export function applyHealChanges(flow, changes) {
+export function applyHealChanges(flow, changes, 
+/**
+ * When the rebind happened. Injected rather than read here, because this function is pure and a
+ * clock inside it would make the flow it returns depend on when a test ran.
+ *
+ * Optional so every existing caller keeps working; without it the step still records WHICH anchor
+ * was replaced, which is the half a reader actually acts on.
+ */
+now) {
     const byStep = new Map();
     for (const change of changes)
         byStep.set(change.step, change);
@@ -51,7 +59,21 @@ export function applyHealChanges(flow, changes) {
             return step;
         }
         applied.push(change);
-        return { ...step, anchor: { kind: AnchorKind.TESTID, value: change.to } };
+        return {
+            ...step,
+            anchor: { kind: AnchorKind.TESTID, value: change.to },
+            /*
+             * `from` is the ORIGINAL recorded anchor, kept across later heals.
+             *
+             * A step healed twice has an intermediate name nobody ever chose, so overwriting with the
+             * newest would throw away the only anchor a reader wants — the one that was recorded by
+             * driving. The timestamp is the LATEST heal, because that is when this anchor arrived.
+             */
+            healed: {
+                from: step.healed?.from ?? change.from,
+                at: now?.() ?? step.healed?.at ?? 0,
+            },
+        };
     });
     return { flow: { ...flow, steps }, applied };
 }

package/dist/language/flows/learned-sources.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Learn a flow step's source file from the element its anchor resolved to on a replay.
+ *
+ * A step recorded before the build stamped the app names no file, so a scoped re-verify cannot say
+ * which edits it covers. Every replay already asks the page for each anchor's element, and that
+ * element carries its stamp now: this records the answer at the one place every resolution passes
+ * through (the session's QUERY), rather than threading it through each step runner.
+ */
+import { type FlowFile, type FlowStep } from '@reticlehq/core';
+import type { FlowReplaySession } from './flow-replay-types.js';
+type StepSource = NonNullable<FlowStep['source']>;
+/** `src/Pay.tsx:12:4` or `src/Pay.tsx:12` → `{file, line}`; anything else is not a location. */
+export declare function parseCompactSource(value: string): StepSource | undefined;
+/** Wrap a replay session so every anchor QUERY that resolves to one stamped element is remembered. */
+export declare function recordingSources(inner: FlowReplaySession): {
+    session: FlowReplaySession;
+    sources: ReadonlyMap<string, StepSource>;
+};
+/** The flow with every sourceless step given the file its anchor resolved to; undefined if none was. */
+export declare function withLearnedSources(flow: FlowFile, sources: ReadonlyMap<string, StepSource>): FlowFile | undefined;
+export {};