@reticlehq/server 3.3.0 → 3.4.0

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

@@ -2,10 +2,10 @@ import { formatStepAddress } from 'open-verification';
 import { assertsState, expectLabel, expectedElementTestid, withoutClauses } from '@reticlehq/core';
 import { span } from '../../trace.js';
 import { anchorLabel, expectElementDrift, resolveTestid, testidDrift, ambiguousAnchorDrift, } from './flow-anchor.js';
-export { anchorLabel, componentLabel, componentQueryArgs, editDistance, expectElementDrift, nearestIsAmbiguous, nearestTestid, resolveQuery, testidDrift, } from './flow-anchor.js';
-import { routeOfEvent } from '@reticlehq/engine/question/predicate/predicate-route.js';
+export { nearestIsAmbiguous, nearestTestid, resolveQuery } from './flow-anchor.js';
+import { routeOfEvent, routeOfUrl } from '@reticlehq/engine/question/predicate/predicate-route.js';
 import { stepEffect } from '@reticlehq/engine/evidence/step-effect.js';
-import { AnchorKind, DriftReason, EventType, FlowStepTool, PredicateKind, } from '@reticlehq/core';
+import { AnchorKind, DriftReason, EventType, FlowStepTool, StepEffect, PredicateKind, } from '@reticlehq/core';
 import { asString, isConsequenceDrift } from '@reticlehq/core';
 import { anchorFieldName } from './fields/flow-secret-field.js';
 import { degradedStepResult, isDegradedAnchor, runComponentStep, runRoleStep, runSequenceStep, } from './flow-step-runners.js';
@@ -48,8 +48,11 @@ const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 function currentRoute(session) {
     const routes = session.eventsSince(0).filter((e) => e.type === EventType.ROUTE_CHANGE);
     const last = routes.at(-1);
-    if (last === undefined)
-        return undefined;
+    // A page that loaded and never navigated has no route event; its URL is still where it is.
+    if (last === undefined) {
+        const loaded = session.url === undefined ? undefined : routeOfUrl(session.url);
+        return loaded !== undefined && loaded.routePath.length > 0 ? loaded.routePath : undefined;
+    }
     // The ROUTER's path. This field answers "which page did this step run on", and the document
     // pathname is `/` on every page of a hash-routed app — so a whole desktop replay reported `/` for
     // every step. Sixth place the same reading was wrong; see routeOfEvent.
@@ -280,6 +283,30 @@ async function runSignalStep(session, step, index, name, waitForSignal, signalTi
         },
     };
 }
+/**
+ * The index a replay resumes at, or `undefined` when `from` names no step of this flow.
+ *
+ * A step declared `commits` in the prefix refuses the resume (0 = replay everything): re-driving it
+ * is not setup, it is a second charge, a second email, a second record.
+ */
+export function resumeIndex(from, steps) {
+    if (from === undefined)
+        return 0;
+    const at = 'number' === typeof from ? from : steps.findIndex((step) => step.id === from);
+    if (at < 0 || at >= steps.length || !Number.isInteger(at))
+        return undefined;
+    return steps.slice(0, at).some((step) => StepEffect.COMMITS === step.effect) ? 0 : at;
+}
+/** The `from` argument, narrowed: a step index or a step id. */
+export function resumeArg(raw) {
+    return 'number' === typeof raw || ('string' === typeof raw && raw.length > 0) ? raw : undefined;
+}
+/** Why `from` cannot be resumed at, or undefined when it can (or was not given). */
+export function unresolvedResume(from, steps) {
+    if (resumeIndex(from, steps) !== undefined)
+        return undefined;
+    return `cannot resume at ${JSON.stringify(from)}: this flow has ${String(steps.length)} step(s) and no step by that id`;
+}
 /**
  * Run an `invoke` step: load the named flow and replay it, or fail saying why.
  *
@@ -291,7 +318,7 @@ async function runSignalStep(session, step, index, name, waitForSignal, signalTi
  * own, and the sub-journey's outcome is summarised on the invocation, so a reader sees the shape
  * they recorded rather than a flattened list that has lost every boundary.
  */
-async function runInvokeStep(session, flow, step, index, waitForSignal, signalTimeoutMs, confirmDangerous, sleep, options) {
+async function runInvokeStep(session, flow, step, index, waitForSignal, signalTimeoutMs, confirmDangerous, sleep, options, setup = false) {
     const name = step.invoke ?? '';
     const via = options.via ?? [];
     const here = { flow: flow.name, step: index, via };
@@ -313,7 +340,10 @@ async function runInvokeStep(session, flow, step, index, waitForSignal, signalTi
             error: `cannot replay "${name}": it was not found, so this journey would report green having never run it`,
         };
     }
-    const carried = options;
+    // `from` is an offset into the CALLER's steps. A sub-journey invoked from the setup prefix runs
+    // whole and unchecked (from = its length); one invoked at or after the resume point runs normally.
+    const { from: _outer, ...rest } = options;
+    const carried = setup ? { ...rest, from: sub.steps.length } : rest;
     const nested = await replayFlow(session, sub, waitForSignal, signalTimeoutMs, confirmDangerous, sleep, {
         ...carried,
         via: [{ flow: flow.name, step: index }, ...via],
@@ -331,6 +361,9 @@ async function runInvokeStep(session, flow, step, index, waitForSignal, signalTi
 }
 export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs, confirmDangerous = false, sleep = realSleep, options = {}) {
     const results = [];
+    // Steps before this index are setup. `from` was validated by the caller; an unresolvable one
+    // resumes nowhere rather than everywhere, so it cannot silently widen into a full replay.
+    const from = resumeIndex(options.from, flow.steps) ?? flow.steps.length;
     // testids whose region is LLM-dynamic — their expect-presence is NOT asserted.
     const dynamic = new Set((flow.dynamic ?? [])
         .filter((a) => a.kind === AnchorKind.TESTID)
@@ -347,8 +380,10 @@ export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs,
     try {
         for (const step of flow.steps) {
             if (step.invoke !== undefined) {
-                results.push(await runInvokeStep(session, flow, step, index, waitForSignal, signalTimeoutMs, confirmDangerous, sleep, options));
+                results.push(await runInvokeStep(session, flow, step, index, waitForSignal, signalTimeoutMs, confirmDangerous, sleep, options, index < from));
                 const last = results[results.length - 1];
+                if (last !== undefined && index < from && last.ok)
+                    results.pop();
                 if (last !== undefined && false === last.ok)
                     break;
                 index += 1;
@@ -404,7 +439,9 @@ export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs,
              * replay path and belongs in its own commit.
              */
             const declared = [step.expect, ...(step.steps ?? []).map((sub) => sub.expect)].filter((expectation) => expectation !== undefined);
-            for (const expectation of declared) {
+            // A setup step's consequence is not checked: it is re-driven to get somewhere, not to prove it.
+            const checked = index < from ? [] : declared;
+            for (const expectation of checked) {
                 if (!result.ok || result.drift !== undefined)
                     break;
                 const expectDrift = await assertStepExpect(session, expectation, waitForSignal, waitFor(step), cursorBefore);
@@ -415,6 +452,9 @@ export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs,
             }
             if (page !== undefined)
                 result.page = page;
+            const endPage = currentRoute(session);
+            if (endPage !== undefined && endPage !== page)
+                result.endPage = endPage;
             const windowEvents = session.eventsSince(cursorBefore).filter((e) => e.t >= cursorBefore);
             const consequence = summarizeConsequence(windowEvents);
             if (consequence !== undefined)
@@ -437,6 +477,12 @@ export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs,
             // forget the rule and quietly re-introduce the cost. Spelled out only when it is NOT the default.
             if (FlowStepTool.ACT === result.tool)
                 delete result.tool;
+            if (index < from && result.ok && result.drift === undefined) {
+                index += 1;
+                continue;
+            }
+            if (index < from)
+                result.note = `setup step for resuming at step ${String(from)} failed`;
             results.push(result);
             // Under `sweep`, a failure whose action still RAN does not stop the run — the page is where the
             // step left it, so the next step is as meaningful as it was going to be. Anything else halts.

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

@@ -33,3 +33,5 @@ export type FlowResult<T> = {
  * hold the distinction — this is the fourth id joined into a path, and the one that file missed.
  */
 export declare const safeProjectId: (projectId?: ProjectId) => ProjectId | undefined;
+/** Map a structured FlowErrorCode to a legible one-line message for the agent. */
+export declare function flowErrorMessage(code: FlowErrorCode, detail?: string): string;

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

@@ -1,5 +1,6 @@
 import { FlowErrorCode } from '@reticlehq/core';
 import { SAFE_SEGMENT_PATTERN } from '@reticlehq/core';
+import { FlowParseNote } from './flow-expect-grammar.js';
 /**
  * A project id that is safe to put in a path, or nothing.
  *
@@ -24,3 +25,27 @@ import { SAFE_SEGMENT_PATTERN } from '@reticlehq/core';
  * hold the distinction — this is the fourth id joined into a path, and the one that file missed.
  */
 export const safeProjectId = (projectId) => projectId !== undefined && SAFE_SEGMENT_PATTERN.test(projectId) ? projectId : undefined;
+/** Map a structured FlowErrorCode to a legible one-line message for the agent. */
+export function flowErrorMessage(code, detail) {
+    if (FlowErrorCode.PARSE_FAILED === code && undefined !== detail)
+        return detail;
+    // The detail names both versions and the remedy, so it beats anything generic this could say.
+    if (FlowErrorCode.WRONG_VERSION === code && undefined !== detail)
+        return detail;
+    switch (code) {
+        case FlowErrorCode.INVALID_NAME:
+            return 'invalid flow name — use a single safe segment (letters/digits/-/_), no path separators';
+        case FlowErrorCode.NOT_FOUND:
+            return 'no such flow on disk — run reticle_flow{action:"list"} to see saved flows';
+        case FlowErrorCode.PARSE_FAILED:
+            return FlowParseNote.MALFORMED;
+        case FlowErrorCode.NO_RECORDING:
+            return 'no compiled recording by that name — record one (reticle_record{action:"start"|"stop"}) first';
+        // Never "regenerate it": the file is intact and the reader is the wrong one. Telling somebody
+        // to rewrite an undamaged flow is the failure this code was split out of PARSE_FAILED to stop.
+        case FlowErrorCode.WRONG_VERSION:
+            return 'this flow file was written in a different flow-file format — the file is not damaged, this Reticle cannot read that version. Upgrade or downgrade Reticle rather than editing the flow';
+        case FlowErrorCode.STEP_NOT_FOUND:
+            return (detail ?? 'the step to resume at is not in this flow — pass a 0-based index or a step id');
+    }
+}

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,5 +1,5 @@
 import { type Predicate, type ProjectId } from '@reticlehq/core';
-export { REDACTED_FILL } from './fields/flow-secret-field.js';
+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, FlowFile, FlowStep, HealChange, InstrumentationGap } from '@reticlehq/core';
@@ -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 +

package/dist/language/flows/flows.js

@@ -1,14 +1,15 @@
 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';
@@ -164,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
@@ -237,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.
@@ -267,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,
@@ -295,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 +

package/dist/language/flows/recording/replay-halt.js

@@ -21,7 +21,9 @@ export function haltedFrom(results, total) {
         return undefined;
     if (last.ok && last.drift === undefined)
         return undefined;
-    const notAttempted = total - results.length;
+    // From the step's own index, not the count of results: a resumed replay does not report its setup
+    // prefix, so the results array no longer starts at step 0.
+    const notAttempted = total - (last.step + 1);
     // A failure on the FINAL step is not a halt: nothing was left to attempt, and `notAttempted: 0`
     // would send a reader looking for steps that do not exist.
     if (notAttempted <= 0)

package/dist/language/flows/recording/tape/recordings.d.ts

@@ -1,4 +1,4 @@
-import { type Predicate } from '@reticlehq/core';
+import { type FlowFile, type Predicate } from '@reticlehq/core';
 /** One captured agent action, normalized for replay. */
 export interface RecordedStep {
     /** ReticleTool.ACT | ReticleTool.ACT_SEQUENCE */
@@ -27,6 +27,12 @@ export interface RecordedStep {
      * `invoke` first and treats the step as a call.
      */
     invoke?: string;
+    /** The page this step ran on. Written to the saved step (unlike `route`, which cuts journeys). */
+    page?: string;
+    /** The page it ended on once it settled — see `markEnded`. */
+    endPage?: string;
+    /** Why the agent took this step: the `intent` it declared on the action. Names the saved flow. */
+    intent?: string;
 }
 interface ActiveRecording {
     cursor: number;
@@ -59,6 +65,8 @@ export interface CompiledProgram {
      * format change.
      */
     routes?: string[];
+    /** Who made it — see FlowFile.author. Stamped by the caller that knows. */
+    author?: FlowFile['author'];
 }
 /**
  * The `tool` written on an invocation step — core's constant, re-exported for this module's callers.
@@ -105,6 +113,27 @@ export declare class RecordingStore {
      * anything should not carry an empty tape, and "did anything happen at all" stays answerable.
      */
     capture(step: RecordedStep, route?: string): void;
+    /**
+     * Add a consequence to the last captured step of every active recording.
+     *
+     * A separate `reticle_assert` after an act is how an agent proves what the act did, and it never
+     * reached the recorder — only the act tools called `capture` — so the flow kept the click and lost
+     * the proof. What the step already declared is kept; the new check joins it under `allOf`.
+     */
+    attachExpect(expect: Predicate): void;
+    /**
+     * A navigation happened. Navigating records no step, so until the next one is captured, a check
+     * proved now is about the page the navigation opened, not about the last step — and kept on that
+     * step, replay would ask it right after the click, of a page it was never true on.
+     */
+    markNavigated(): void;
+    /**
+     * The page the step just captured ended on, once its action settled.
+     *
+     * Fills only a step that has none, so calling it after an action that captured nothing leaves the
+     * previous step's own answer alone.
+     */
+    markEnded(page: string | undefined): void;
     /**
      * Returns the active recording (cursor + steps) and clears it, or undefined if not recording.
      *

package/dist/language/flows/recording/tape/recordings.js

@@ -1,4 +1,4 @@
-import { FlowStepTool } from '@reticlehq/core';
+import { FlowStepTool, PredicateKind } from '@reticlehq/core';
 /**
  * The `tool` written on an invocation step — core's constant, re-exported for this module's callers.
  *
@@ -31,6 +31,8 @@ const AMBIENT_STEP_CAP = 400;
 export class RecordingStore {
     #active = new Map();
     #compiled = new Map();
+    /** A navigation came after the last captured step — see markNavigated. */
+    #navigatedSinceStep = false;
     start(name, cursor, startPath) {
         const openedOver = new Map();
         for (const [outer, rec] of this.#active)
@@ -67,6 +69,7 @@ export class RecordingStore {
      * anything should not carry an empty tape, and "did anything happen at all" stays answerable.
      */
     capture(step, route) {
+        this.#navigatedSinceStep = false;
         if (!this.#active.has(AMBIENT_RECORDING)) {
             this.#active.set(AMBIENT_RECORDING, {
                 cursor: 0,
@@ -83,12 +86,63 @@ export class RecordingStore {
             // opened on purpose is not capped — they said when it starts and they say when it stops.
             if (AMBIENT_RECORDING === name && rec.steps.length >= AMBIENT_STEP_CAP)
                 continue;
+            // A step nobody marked ended where the next one began.
+            const previous = rec.steps.at(-1);
+            if (previous !== undefined && previous.endPage === undefined && step.page !== undefined) {
+                previous.endPage = step.page;
+            }
             // The route rides on the AMBIENT tape only: a recording somebody opened deliberately is
             // already one journey by construction, and stamping a route on its steps would change what a
             // deliberate recording contains.
             rec.steps.push(AMBIENT_RECORDING === name && route !== undefined ? { ...step, route } : step);
         }
     }
+    /**
+     * Add a consequence to the last captured step of every active recording.
+     *
+     * A separate `reticle_assert` after an act is how an agent proves what the act did, and it never
+     * reached the recorder — only the act tools called `capture` — so the flow kept the click and lost
+     * the proof. What the step already declared is kept; the new check joins it under `allOf`.
+     */
+    attachExpect(expect) {
+        if (this.#navigatedSinceStep)
+            return;
+        for (const rec of this.#active.values()) {
+            const last = rec.steps.at(-1);
+            if (last === undefined)
+                continue;
+            const held = last.expect;
+            last.expect =
+                held === undefined
+                    ? expect
+                    : PredicateKind.ALL_OF === held.kind
+                        ? { ...held, predicates: [...held.predicates, expect] }
+                        : { kind: PredicateKind.ALL_OF, predicates: [held, expect] };
+        }
+    }
+    /**
+     * A navigation happened. Navigating records no step, so until the next one is captured, a check
+     * proved now is about the page the navigation opened, not about the last step — and kept on that
+     * step, replay would ask it right after the click, of a page it was never true on.
+     */
+    markNavigated() {
+        this.#navigatedSinceStep = true;
+    }
+    /**
+     * The page the step just captured ended on, once its action settled.
+     *
+     * Fills only a step that has none, so calling it after an action that captured nothing leaves the
+     * previous step's own answer alone.
+     */
+    markEnded(page) {
+        if (page === undefined)
+            return;
+        for (const rec of this.#active.values()) {
+            const last = rec.steps.at(-1);
+            if (last !== undefined && last.endPage === undefined)
+                last.endPage = page;
+        }
+    }
     /**
      * Returns the active recording (cursor + steps) and clears it, or undefined if not recording.
      *

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

@@ -1,3 +1,4 @@
+import { type Predicate } from '@reticlehq/core';
 import { type CommandResult } from '@reticlehq/core';
 import type { RecordedStep, CompiledProgram } from './recording/tape/recordings.js';
 import type { Session } from '../../portal/session/session.js';
@@ -27,6 +28,13 @@ export declare function queryRefs(result: CommandResult): string[];
  * an empty box fails identically and tells the reader nothing.
  */
 export declare function replayActionArgs(value: unknown, confirmDangerous?: boolean, field?: string): Record<string, unknown>;
+/**
+ * The pathname of a session's live url, or undefined when it has none yet.
+ *
+ * Pathname rather than the whole url, because that is what `startPath` is compared against and what
+ * a hash-routed app makes meaningless in the document location — see routeOfEvent.
+ */
+export declare function pathOf(url: string | undefined): string | undefined;
 /**
  * Capture an act into every in-flight recording, or do nothing when none is running.
  *
@@ -40,6 +48,17 @@ export declare function captureAct(recordings: {
 }, args: Record<string, unknown>, res: unknown, 
 /** Where this step ran, so the ambient tape can be cut into journeys. See RecordedStep.route. */
 route?: string): void;
+/**
+ * Capture an act_and_wait once its verdict is known, keeping `until` as the step's expectation only
+ * on a yes. Recorded before the verdict, a step kept an `until` that came back `no` or `no-fault` —
+ * a regression test asserting something never once observed to hold because of the action. The
+ * action itself is always recorded: it happened, and replay needs it to reach the next step.
+ */
+export declare function captureVerdictedAct(recordings: Parameters<typeof captureAct>[0], args: Record<string, unknown>, res: unknown, route: string | undefined, verified: string | undefined): void;
+/** Fold a PASSING standalone assertion into the step it proved. See RecordingStore.attachExpect. */
+export declare function captureAssertion(recordings: {
+    attachExpect: (expect: Predicate) => void;
+}, raw: 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