@reticlehq/server 3.2.0 → 3.4.0

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

@@ -0,0 +1,119 @@
+import { createHash } from 'node:crypto';
+import { PredicateKind } from '@reticlehq/core';
+/**
+ * One journey, however many times it was driven.
+ *
+ * Every browser session saves its own flow at teardown, so a journey driven in five sessions was
+ * five near-identical files. Two flows are the SAME journey when they start on the same page and
+ * take the same steps: same tool, action, anchor and invocation, in the same order. What was typed
+ * and what was claimed do not decide it — a re-drive that fills a different value or declares one
+ * more consequence is the same journey, better described.
+ */
+/** The anchor minus its source location, which moves when an unrelated line is edited. */
+function anchorShape(anchor) {
+    const { source: _source, ...rest } = anchor;
+    return rest;
+}
+function stepShape(step) {
+    return [
+        step.tool,
+        step.action ?? null,
+        anchorShape(step.anchor),
+        step.invoke ?? null,
+        (step.steps ?? []).map(stepShape),
+    ];
+}
+const FINGERPRINT_LENGTH = 12;
+/** A short, stable identity for a journey's shape: its start page and its steps. */
+export function journeyFingerprint(flow) {
+    return createHash('sha256')
+        .update(JSON.stringify([flow.startPath ?? null, flow.steps.map(stepShape)]))
+        .digest('hex')
+        .slice(0, FINGERPRINT_LENGTH);
+}
+/** `kept` wins wherever it says something; `other` fills only what `kept` left unsaid. */
+function fillStep(kept, other) {
+    if (other === undefined)
+        return kept;
+    const merged = { ...other, ...kept };
+    if (kept.steps !== undefined) {
+        merged.steps = kept.steps.map((sub, i) => fillStep(sub, other.steps?.[i]));
+    }
+    return merged;
+}
+/**
+ * Fold two copies of one journey into one file.
+ *
+ * Gap-filling, never overwriting: whatever the kept flow already says — its name, its intent, a
+ * step's declared consequence, a quarantine a person wrote — survives, and the other copy only
+ * supplies what is missing. So a merge can add an assertion or an intent and can never remove one.
+ */
+export function mergeJourney(kept, other) {
+    return {
+        ...other,
+        ...kept,
+        steps: kept.steps.map((step, i) => fillStep(step, other.steps[i])),
+    };
+}
+/**
+ * The name a new journey saves under.
+ *
+ * Its readable name when that is free or already this journey's; otherwise the same name with the
+ * fingerprint's head, so two different journeys that share an intent never overwrite each other.
+ */
+export function journeyName(base, fingerprint, taken) {
+    const owner = taken.get(base);
+    return owner === undefined || owner === fingerprint ? base : `${base}-${fingerprint.slice(0, 6)}`;
+}
+/**
+ * What must hold before a journey and what it leaves behind, read from where it started and ended.
+ *
+ * Routes only: the page is the one piece of state every recorded step knows for certain, and a
+ * claim written from a guess about the rest would be a precondition nobody met. Written in the
+ * exact form `canFollow` compares by value, so A-then-B is answerable from the two files alone.
+ */
+export function routeClaims(startPath, steps) {
+    const first = startPath ?? steps[0]?.page;
+    const last = steps.at(-1);
+    const end = last?.endPage ?? last?.page;
+    return {
+        ...(first === undefined ? {} : { requires: [{ kind: PredicateKind.ROUTE, pathname: first }] }),
+        ...(end === undefined ? {} : { ensures: [{ kind: PredicateKind.ROUTE, pathname: end }] }),
+    };
+}
+/**
+ * The preconditions only another flow can establish.
+ *
+ * A route claim on the page the flow starts on is not one of them: replay navigates there itself, so
+ * it neither opts the flow out of the reset nor gates the run. That is the claim a saved drive writes
+ * for the map (see routeClaims) — reading it as "starts from leftover state" would stop every
+ * auto-saved flow from ever being reset.
+ */
+export function establishedState(flow) {
+    const start = flow.startPath;
+    return (flow.requires ?? []).filter((claim) => !(start !== undefined &&
+        PredicateKind.ROUTE === claim.kind &&
+        claim.pathname !== undefined &&
+        samePath(claim.pathname, start)));
+}
+/**
+ * Is the tab where the flow asked to start? Up to a trailing slash, and up to the query the flow
+ * did not ask about.
+ *
+ * `startPath` is the SPECIFICATION, so it decides what counts. A query it recorded is compared:
+ * `?tab=wrap` and `?tab=summary` are different pages, and a replay that starts on the wrong one
+ * proves nothing about the right one. A query it did NOT record is ignored: the tab carrying
+ * `?next=%2F` on a login page, or the identity params Reticle puts on a leased tab, are not the flow
+ * being elsewhere, and navigating to strip them costs a session for nothing.
+ *
+ * The asymmetry is the whole point and the reason `observed` and `expected` are named rather than
+ * `a` and `b`. Comparing with the query on both sides always re-navigated a query-bearing
+ * `startPath` (#1059, which killed the session mid-flow); comparing with it on neither side reads a
+ * tab on `?tab=summary` as already at `?tab=wrap`.
+ */
+export function samePath(observed, expected) {
+    const trimmed = (path) => path.replace(/\/$/, '');
+    const withoutQuery = (path) => path.replace(/\?[^#]*/, '');
+    const comparable = expected.includes('?') ? observed : withoutQuery(observed);
+    return trimmed(comparable) === trimmed(expected);
+}

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

@@ -1,5 +1,6 @@
 import type { FlowReplayResult } from '@reticlehq/core';
 import type { ToolDeps } from '../../surface/tools/tool-kit.js';
+import { withLearnedSources } from './learned-sources.js';
 /**
  * Write back what a replay taught the flow, once the replay has finished writing its own.
  *
@@ -50,3 +51,5 @@ export declare function replayAndLearn(deps: ToolDeps,
  * caught it. `seed` and anything added later travel the same path, so the whole object goes.
  */
 args: Record<string, unknown>): Promise<FlowReplayResult>;
+/** Write back the files a clean replay's anchors resolved to. Best-effort, as `persistLearning` is. */
+export declare function persistSources(deps: ToolDeps, args: Record<string, unknown>, sources: Parameters<typeof withLearnedSources>[1]): Promise<void>;

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

@@ -1,6 +1,16 @@
 import { asString } from '@reticlehq/core';
 import { flowsForSession } from './flow-store-for-session.js';
 import { replayNamedFlow } from './flow-replay-run.js';
+import { recordingSources, withLearnedSources } from './learned-sources.js';
+import { ReplayStatus } from '@reticlehq/core';
+function projectOf(deps, args) {
+    try {
+        return deps.sessions.resolve(asString(args['sessionId'])).projectId;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Write back what a replay taught the flow, once the replay has finished writing its own.
  *
@@ -26,13 +36,7 @@ export async function persistLearning(deps, args, result) {
     if (0 === name.length)
         return result;
     try {
-        let projectId;
-        try {
-            projectId = deps.sessions.resolve(asString(args['sessionId'])).projectId;
-        }
-        catch {
-            projectId = undefined;
-        }
+        const projectId = projectOf(deps, args);
         await flowsForSession(deps, projectId).flows.recordLearned(name, learned, projectId);
     }
     catch {
@@ -72,5 +76,32 @@ export async function replayAndLearn(deps,
  * caught it. `seed` and anything added later travel the same path, so the whole object goes.
  */
 args) {
-    return await persistLearning(deps, args, await replayNamedFlow(deps, args));
+    let recorded;
+    const result = await replayNamedFlow(deps, args, (session) => {
+        recorded = recordingSources(session);
+        return recorded.session;
+    });
+    // Only a clean run teaches a file: a drifted step may have resolved to the wrong element.
+    if (result.status === ReplayStatus.OK && recorded !== undefined && recorded.sources.size > 0) {
+        await persistSources(deps, args, recorded.sources);
+    }
+    return await persistLearning(deps, args, result);
+}
+/** Write back the files a clean replay's anchors resolved to. Best-effort, as `persistLearning` is. */
+export async function persistSources(deps, args, sources) {
+    const name = asString(args['flowName']) ?? '';
+    if (0 === name.length)
+        return;
+    try {
+        const projectId = projectOf(deps, args);
+        const store = flowsForSession(deps, projectId).flows;
+        const current = await store.load(name, projectId);
+        // Read first so a flow that already names every file is never rewritten.
+        if (!current.ok || withLearnedSources(current.value, sources) === undefined)
+            return;
+        await store.recordSources(name, sources, projectId);
+    }
+    catch {
+        // Bookkeeping only.
+    }
 }

package/dist/language/flows/flow-replay-run.d.ts

@@ -1,15 +1,14 @@
-import { FlowErrorCode, type CommandResult, type FlowFile, type FlowReplayResult, type Contradiction, type FlowStepResult, type ReticleEvent } from '@reticlehq/core';
+import { type CommandResult, type FlowFile, type FlowReplayResult, type Contradiction, type FlowStepResult, type ReticleEvent } from '@reticlehq/core';
 import type { ArrivalClock } from '../../surface/tools/act/navigation/navigate-arrival.js';
 import type { SessionManager } from '../../portal/session/session-manager.js';
 import type { Session } from '../../portal/session/session.js';
-import { DocumentLostDuringReplay } from './flow-replay.js';
+import { DocumentLostDuringReplay, type FlowReplaySession } from './flow-replay.js';
 import type { ToolDeps } from '../../surface/tools/tool-kit.js';
 export declare function latestRecordedFlow(events: ReticleEvent[]): {
     name: string;
     flow: import('@reticlehq/core').FlowFile;
 } | undefined;
-/** Map a structured FlowErrorCode to a legible one-line message for the agent. */
-export declare function flowErrorMessage(code: FlowErrorCode, detail?: string): string;
+export { flowErrorMessage } from './flow-result.js';
 /** The slice of a session the start-path logic reads: the live URL plus the event buffer. */
 interface StartPathSession {
     url?: string;
@@ -25,21 +24,39 @@ interface StartPathSession {
  * navigation was refused or the SDK never reconnected in the window.
  */
 export declare function startPathMismatchHint(flow: FlowFile, session: StartPathSession): string | undefined;
+/** What replay learned on its way to step 0. Both fields absent = the tab was left exactly as it was. */
+export interface StartPathArrival {
+    /** The successor session replay must continue on. Absent when nothing was navigated, or arrival timed out. */
+    session?: Session;
+    /** Set when the RESET itself is why step 1 cannot start — the reason a step-1 red is not drift. */
+    resetCost?: string;
+}
 /**
- * Replay's half of the FlowFile contract: navigate to the flow's `startPath` before step 1.
+ * Replay's half of the FlowFile contract: put the tab on the flow's `startPath` before step 1, and
+ * RELOAD it if it is already there.
+ *
+ * The reload is the state contract. Replaying "add a task" twice against a tab nobody reset gives
+ * the second run a world the recording never saw, and its assertions then describe the first run
+ * rather than the app. Our own `replay-determinism.mjs` has always refreshed before every run — the
+ * determinism we measured was never the determinism a user got.
+ *
+ * `requires` is the declared opt-out, and its first caller. A flow that says it starts from state
+ * another flow established is the one flow a page load would destroy, so it is never reset — here
+ * or from the wrong page. Silence is not an opt-out: a flow that depends on leftovers without
+ * saying so is a flow whose green means nothing on a fresh machine, and CI is a fresh machine.
  *
  * A full-page load tears down the session socket, so the navigation must happen here — before any
  * step runs — and the replay continues on the session the SDK reconnects as (found via the same
  * tombstone rebind that lets `resolve(oldId)` answer after any navigation). Best-effort by design:
- * when the flow carries no startPath, the tab is already there, the current route is unobservable,
- * the navigation is refused, or the SDK never reconnects in the window, it returns undefined and
- * replay proceeds on the connected session as before — with startPathMismatchHint turning any
- * resulting drift into an actionable next move rather than a mystifying one.
+ * when the flow carries no startPath, the current route is unobservable, the navigation is refused,
+ * or the SDK never reconnects in the window, replay proceeds on the connected session as before —
+ * with startPathMismatchHint turning any resulting drift into an actionable next move rather than a
+ * mystifying one.
  */
 export declare function arriveAtStartPath(sessions: SessionManager, session: StartPathSession & {
     id: string;
     command(name: string, args?: Record<string, unknown>): Promise<CommandResult>;
-}, flow: FlowFile, timeoutMs?: number, clock?: ArrivalClock): Promise<Session | undefined>;
+}, flow: FlowFile, timeoutMs?: number, clock?: ArrivalClock): Promise<StartPathArrival>;
 /**
  * Send a tab somewhere and wait for the session that comes back.
  *
@@ -57,7 +74,9 @@ export declare function navigateAndAwait(sessions: SessionManager, session: {
     /** Optional because a session's URL is, and `carryReticleIdentity` already handles its absence. */
     url?: string;
     command(name: string, args?: Record<string, unknown>): Promise<CommandResult>;
-}, destination: string, expectedPath: string, timeoutMs?: number, clock?: ArrivalClock): Promise<Session | undefined>;
+}, destination: string, expectedPath: string, timeoutMs?: number, clock?: ArrivalClock, 
+/** True when the destination is the page we are already on — see `arrivedSuccessor`. */
+isReload?: boolean): Promise<Session | undefined>;
 /**
  * The honest answer when the document replay was driving went away mid-run.
  *
@@ -75,7 +94,9 @@ export declare function navigateAndAwait(sessions: SessionManager, session: {
  * with. `navigateAndAwait` CAN wait, because it knows it asked for the navigation, and it does.
  */
 export declare function lostDocumentResult(name: string, lost: DocumentLostDuringReplay): FlowReplayResult;
-export declare function replayNamedFlow(deps: ToolDeps, args: Record<string, unknown>): Promise<FlowReplayResult>;
+export declare function replayNamedFlow(deps: ToolDeps, args: Record<string, unknown>, 
+/** Wraps the session the steps run on, so a caller can watch what they resolved. */
+observe?: (session: FlowReplaySession) => FlowReplaySession): Promise<FlowReplayResult>;
 export declare function crossStepOnly(whole: readonly Contradiction[], steps: readonly FlowStepResult[]): Contradiction[];
 /**
  * The connecting session's project, or undefined when no browser is attached. Flow tools use it to

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

@@ -2,16 +2,17 @@ import { resolveFlowUploads } from './fields/flow-upload-resolve.js';
 import { learnFromRun } from '@reticlehq/engine/evidence/learned-guards.js';
 import { EventType, FLOW_SIGNAL_TIMEOUT_MS, FlowErrorCode, RecordedFlowSchema, ReplayStatus, ReticleCommand, RunKind, RunStatus, } from '@reticlehq/core';
 import { haltedFrom } from './recording/replay-halt.js';
+import { establishedState, samePath } from './flow-journey.js';
 import { asRecord, asString } from '@reticlehq/core';
 import { routeOfEvent, routeOfUrl } from '@reticlehq/engine/question/predicate/predicate-route.js';
 import { carryReticleIdentity } from '../../surface/tools/lease-tools.js';
 import { replayFlow } from './flow-replay.js';
-import { anchorQueryArgs } from './flow-step-runners.js';
+import { anchorPrecondition, anchorQueryArgs } from './flow-step-runners.js';
 import { queryRefs } from './replay.js';
 import { assertSuccess, dynamicTestids, successLabel, SUCCESS_STEP_TOOL } from './flow-success.js';
 import { buildDecision, unverifiableReason } from './decision.js';
 import { unsuppliedSecrets } from './fields/flow-secret-field.js';
-import { assertStepExpect, DocumentLostDuringReplay, } from './flow-replay.js';
+import { assertStepExpect, DocumentLostDuringReplay, resumeArg, unresolvedResume, } from './flow-replay.js';
 import { isDocumentGoneError } from '../../portal/session/facts/session-replaced.js';
 import { classifyFlowAssertions, flattenSteps } from './flow-classify.js';
 import { dischargeFlowIntent, flowIntentStatement, flowReplayVerdictId } from './flow-intent.js';
@@ -31,7 +32,6 @@ import { consultSubjectFor, selectConsulted } from './flow-memory-consult.js';
 import { log } from '../../log.js';
 import { flowsForSession } from './flow-store-for-session.js';
 import { projectForRoot } from '../../memory/project/project-for-root.js';
-import { FlowParseNote } from './flow-expect-grammar.js';
 export function latestRecordedFlow(events) {
     for (let i = events.length - 1; i >= 0; i--) {
         const event = events[i];
@@ -43,21 +43,8 @@ export function latestRecordedFlow(events) {
     }
     return 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;
-    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';
-    }
-}
+export { flowErrorMessage } from './flow-result.js';
+import { flowErrorMessage } from './flow-result.js';
 /** Map the wire ReplayStatus onto the persisted RunStatus (ok→pass). */
 function replayToRunStatus(status) {
     switch (status) {
@@ -106,20 +93,25 @@ recordRoot) {
 function currentPathOf(session) {
     const routes = session.eventsSince(0).filter((e) => e.type === EventType.ROUTE_CHANGE);
     const last = routes.at(-1);
-    // pathname + hash, because `startPath` is compared against this and must stay NAVIGABLE. Reading
-    // the pathname alone made both sides `/` on a hash router — always "same path", so the hint never
-    // fired however far the tab had drifted, on the router desktop renderers use by default.
+    // pathname + search + hash, because `startPath` is compared against this and must stay NAVIGABLE.
+    //
+    // Reading the pathname alone made both sides `/` on a hash router — always "same path", so the
+    // hint never fired however far the tab had drifted, on the router desktop renderers use by
+    // default. Leaving the SEARCH out was the mirror defect: `startPath` keeps its query, so a flow
+    // starting at `/admin/events/7?tab=wrap` never matched a tab sitting on exactly that, re-navigated
+    // on every replay, and the re-navigation killed the session mid-flow.
+    //
+    // Comparing without the query instead would have been worse in the direction that matters. The
+    // query usually decides what the page renders, so a tab on `?tab=summary` would read as "already
+    // at `?tab=wrap`" and the replay would start on the wrong page with nothing saying so. Both sides
+    // carry it, which keeps a real difference visible and stops the false one.
     const observed = last === undefined ? undefined : routeOfEvent(last);
     if (observed !== undefined)
-        return `${observed.docPath}${observed.hash}`;
+        return `${observed.docPath}${observed.search}${observed.hash}`;
     if (session.url === undefined)
         return undefined;
     const fromUrl = routeOfUrl(session.url);
-    return fromUrl === undefined ? undefined : `${fromUrl.docPath}${fromUrl.hash}`;
-}
-/** Pathname equality up to a trailing slash — a router normalising one must not read as "elsewhere". */
-function samePath(a, b) {
-    return a.replace(/\/$/, '') === b.replace(/\/$/, '');
+    return fromUrl === undefined ? undefined : `${fromUrl.docPath}${fromUrl.search}${fromUrl.hash}`;
 }
 /**
  * Ask the project what it already knows about this flow.
@@ -201,9 +193,26 @@ const REAL_ARRIVAL_CLOCK = {
  * `resolve` throws). Keyed to the navigated tab's own identity on purpose: matching "any session at
  * the target page" would happily hand replay an unrelated tab that was already sitting there.
  */
-function arrivedSuccessor(sessions, oldId, target) {
+function arrivedSuccessor(sessions, oldId, target, 
+/** The handle that issued the navigation, when only a genuinely new one counts as arrival. */
+mustReplace) {
     try {
         const candidate = sessions.resolve(oldId);
+        /*
+         * A RELOAD lands on the path it left, so the path cannot tell the successor from the tab that
+         * is still tearing down — `resolve(oldId)` answers with the dying one while it is registered,
+         * which looks like instant arrival and hands replay a socket that will never answer again.
+         *
+         * The discriminator is the OBJECT, not the id. A leased tab carries its identity across a page
+         * load (that is what the identity params are for), so it reconnects under the SAME id — waiting
+         * for a new id there waits forever, and the first lease this was tried on timed out at step 1
+         * on a tab that was perfectly healthy. `SessionManager.add` replaces the instance on every
+         * reconnect, so a different instance is exactly "the socket came back".
+         *
+         * A navigation to a different route has the path as its discriminator and does not need this.
+         */
+        if (mustReplace !== undefined && candidate === mustReplace)
+            return undefined;
         const path = currentPathOf(candidate);
         return path !== undefined && samePath(path, target) ? candidate : undefined;
     }
@@ -242,36 +251,83 @@ async function firstStepResolvesHere(session, flow) {
     }
 }
 /**
- * Replay's half of the FlowFile contract: navigate to the flow's `startPath` before step 1.
+ * Replay's half of the FlowFile contract: put the tab on the flow's `startPath` before step 1, and
+ * RELOAD it if it is already there.
+ *
+ * The reload is the state contract. Replaying "add a task" twice against a tab nobody reset gives
+ * the second run a world the recording never saw, and its assertions then describe the first run
+ * rather than the app. Our own `replay-determinism.mjs` has always refreshed before every run — the
+ * determinism we measured was never the determinism a user got.
+ *
+ * `requires` is the declared opt-out, and its first caller. A flow that says it starts from state
+ * another flow established is the one flow a page load would destroy, so it is never reset — here
+ * or from the wrong page. Silence is not an opt-out: a flow that depends on leftovers without
+ * saying so is a flow whose green means nothing on a fresh machine, and CI is a fresh machine.
  *
  * A full-page load tears down the session socket, so the navigation must happen here — before any
  * step runs — and the replay continues on the session the SDK reconnects as (found via the same
  * tombstone rebind that lets `resolve(oldId)` answer after any navigation). Best-effort by design:
- * when the flow carries no startPath, the tab is already there, the current route is unobservable,
- * the navigation is refused, or the SDK never reconnects in the window, it returns undefined and
- * replay proceeds on the connected session as before — with startPathMismatchHint turning any
- * resulting drift into an actionable next move rather than a mystifying one.
+ * when the flow carries no startPath, the current route is unobservable, the navigation is refused,
+ * or the SDK never reconnects in the window, replay proceeds on the connected session as before —
+ * with startPathMismatchHint turning any resulting drift into an actionable next move rather than a
+ * mystifying one.
  */
 export async function arriveAtStartPath(sessions, session, flow, timeoutMs = START_PATH_ARRIVAL_TIMEOUT_MS, clock = REAL_ARRIVAL_CLOCK) {
     const target = flow.startPath;
     if (target === undefined || 0 === target.length)
-        return undefined;
+        return {};
     const current = currentPathOf(session);
-    if (current === undefined || samePath(current, target))
-        return undefined;
-    // The route differs — but that only matters if it stops the flow starting. See above.
-    if (await firstStepResolvesHere(session, flow))
-        return undefined;
+    if (current === undefined)
+        return {};
+    // The declared opt-out, both directions. See above.
+    if (0 < establishedState(flow).length)
+        return {};
+    const here = samePath(current, target);
+    // A route mismatch that step 1 can start from anyway is not worth a page load: navigating away
+    // from a persistent anchor could only hurt, and did. Arriving is the goal; resetting a tab that is
+    // ALREADY here is a different decision, taken above, and this must not override it.
+    if (!here && (await firstStepResolvesHere(session, flow)))
+        return {};
     let destination;
     try {
         // startPath is a pathname (a host belongs to the machine, not the journey) — resolve it
-        // against the tab's own URL to get something the browser can be sent to.
-        destination = new URL(target, session.url).toString();
+        // against the tab's own URL to get something the browser can be sent to. Already HERE, the
+        // reset reloads the page the tab is on: `samePath` ignored a query the flow did not record, and
+        // navigating to `target` would strip it, so the replay would test a different page than the one
+        // it just agreed it was on.
+        destination = new URL(here ? current : target, session.url).toString();
     }
     catch {
-        return undefined; // no usable base URL — nowhere to navigate from
+        return {}; // no usable base URL — nowhere to navigate from
     }
-    return navigateAndAwait(sessions, session, destination, target, timeoutMs, clock);
+    // Measured either side of the reset, and only when the reset is a reload: reachable before and
+    // gone after is the reload's doing, not the flow file's. Without this, an app holding its session
+    // in memory comes back signed out and step 1 blames a component that is completely fine.
+    const resolvedBefore = here && (await firstStepResolvesHere(session, flow));
+    const arrived = await navigateAndAwait(sessions, session, destination, target, timeoutMs, clock, here);
+    if (arrived === undefined)
+        return {};
+    if (!resolvedBefore || (await firstStepResolvesHere(arrived, flow)))
+        return { session: arrived };
+    return {
+        session: arrived,
+        resetCost: resetCostHint(flow, target),
+    };
+}
+/**
+ * Why step 1 failed after the reset, and the one line that opts the flow out.
+ *
+ * No tool writes `requires`, so naming the field was advice nobody could act on without guessing its
+ * shape. The first anchor IS the precondition: the element step 1 needs, present before it runs.
+ */
+function resetCostHint(flow, target) {
+    const first = flow.steps?.[0];
+    const needs = first === undefined ? undefined : anchorPrecondition(first.anchor);
+    const optOut = needs === undefined
+        ? 'Declare what it needs (`requires`) in the flow file to opt out of the reset'
+        : `Add \`"requires":${JSON.stringify([needs])}\` to the flow file to opt out of the reset`;
+    return (`replay reloaded ${target} before step 1 and the first anchor did not come back — this flow ` +
+        `starts from state a page load discards. ${optOut}, or record it from a cold page`);
 }
 /**
  * Send a tab somewhere and wait for the session that comes back.
@@ -285,7 +341,9 @@ export async function arriveAtStartPath(sessions, session, flow, timeoutMs = STA
  * to move and this decides how, which is also why the deliberate short-circuits live up there and
  * not in here: a caller that has already decided it must move should not have to argue with them.
  */
-export async function navigateAndAwait(sessions, session, destination, expectedPath, timeoutMs = START_PATH_ARRIVAL_TIMEOUT_MS, clock = REAL_ARRIVAL_CLOCK) {
+export async function navigateAndAwait(sessions, session, destination, expectedPath, timeoutMs = START_PATH_ARRIVAL_TIMEOUT_MS, clock = REAL_ARRIVAL_CLOCK, 
+/** True when the destination is the page we are already on — see `arrivedSuccessor`. */
+isReload = false) {
     // A leased tab is addressed by URL params, so navigating without them would strand the lease.
     const url = carryReticleIdentity(session.url, destination);
     try {
@@ -303,7 +361,7 @@ export async function navigateAndAwait(sessions, session, destination, expectedP
     }
     const deadline = clock.now() + timeoutMs;
     for (;;) {
-        const arrived = arrivedSuccessor(sessions, session.id, expectedPath);
+        const arrived = arrivedSuccessor(sessions, session.id, expectedPath, isReload ? session : undefined);
         if (arrived !== undefined)
             return arrived;
         if (clock.now() >= deadline)
@@ -358,10 +416,18 @@ async function loadInvokedFlows(deps, flow, projectId) {
  * a consequence of the first being absent.
  */
 async function firstUnmetPrecondition(session, flow, since) {
-    for (const claim of flow.requires ?? []) {
+    for (const claim of establishedState(flow)) {
         // Zero budget: a precondition is a claim about the state you are starting FROM. Waiting for one
         // turns "was it true" into "did it become true", which is a different and much weaker question.
-        const drift = await assertStepExpect(session, claim, new Set(), waitForPredicate, 0, since);
+        let drift;
+        try {
+            drift = await assertStepExpect(session, claim, waitForPredicate, 0, since);
+        }
+        catch (error) {
+            if (!isDocumentGoneError(error))
+                throw error;
+            return `the page went away while this flow's preconditions were being checked, so nothing ran and nothing was proved. Replay again once the page is back.`;
+        }
         if (drift !== undefined) {
             return `a precondition of this flow does not hold (${JSON.stringify(claim)}), so nothing ran and nothing was proved. Run the flow that establishes it first, or drive that state yourself.`;
         }
@@ -390,7 +456,8 @@ export function lostDocumentResult(name, lost) {
         status: ReplayStatus.OK,
         steps: lost.steps,
         unverifiable: {
-            reason: `the page loaded a new document while step ${String(lost.atStep)} was running, so the run ` +
+            reason: `the page's connection to Reticle was replaced while step ${String(lost.atStep)} was running ` +
+                `(a new document loaded, or its socket reconnected), so the run ` +
                 `could not be graded — the steps before it are reported and nothing after it was observed. ` +
                 `Nothing here says the app failed. If that navigation is part of the journey, record the ` +
                 `step's consequence with \`expect\` and replay again; if it was not, the flow started ` +
@@ -398,7 +465,9 @@ export function lostDocumentResult(name, lost) {
         },
     };
 }
-export async function replayNamedFlow(deps, args) {
+export async function replayNamedFlow(deps, args, 
+/** Wraps the session the steps run on, so a caller can watch what they resolved. */
+observe = (s) => s) {
     const startedAt = deps.now();
     const name = asString(args['flowName']) ?? '';
     // Resolve within the connecting app's scope so a shared daemon replays THIS project's flow, not a
@@ -438,8 +507,11 @@ export async function replayNamedFlow(deps, args) {
     // The FlowFile contract: replay navigates to the flow's startPath before step 1, and the steps run
     // on the session the SDK reconnects as. When arrival can't be confirmed, replay proceeds on the
     // connected session — and the hint below turns the wrong-page drift into an actionable next move.
-    const session = (await arriveAtStartPath(deps.sessions, connected, loaded.value)) ?? connected;
-    const startPathHint = startPathMismatchHint(loaded.value, session);
+    const arrival = await arriveAtStartPath(deps.sessions, connected, loaded.value);
+    const session = arrival.session ?? connected;
+    // The reset's own cost outranks the wrong-page hint: if the reload is why step 1 cannot start,
+    // "navigate there and replay" is advice that would do the same thing again.
+    const startPathHint = arrival.resetCost ?? startPathMismatchHint(loaded.value, session);
     // Floor the success oracle at the start of THIS replay so a stale signal from a prior run
     // in the same session can't fake a pass.
     const replayFloor = session.elapsed();
@@ -495,6 +567,12 @@ export async function replayNamedFlow(deps, args) {
             },
         };
     }
+    const from = resumeArg(args['from']);
+    const badResume = unresolvedResume(from, replayable.steps);
+    if (badResume !== undefined) {
+        const error = { code: FlowErrorCode.STEP_NOT_FOUND, message: badResume };
+        return { name: replayable.name, status: ReplayStatus.ERROR, steps: [], error };
+    }
     const unmet = await firstUnmetPrecondition(session, replayable, replayFloor);
     if (unmet !== undefined) {
         return {
@@ -506,7 +584,7 @@ export async function replayNamedFlow(deps, args) {
     }
     let steps;
     try {
-        steps = await replayFlow(session, replayable, waitForPredicate, FLOW_SIGNAL_TIMEOUT_MS, true === args['confirmDangerous'], undefined, {
+        steps = await replayFlow(observe(session), replayable, waitForPredicate, FLOW_SIGNAL_TIMEOUT_MS, true === args['confirmDangerous'], undefined, {
             // How an `invoke` step finds the flow it runs. Scoped to the same project as the flow being
             // replayed, so a composite cannot reach into another app's store for a same-named sub-journey.
             resolveFlow: async (invoked) => {
@@ -516,6 +594,7 @@ export async function replayNamedFlow(deps, args) {
             // Bug-sweep mode: keep going past a step whose action ran and whose consequence merely did
             // not hold, so one flow reports one verdict per step instead of stopping at the first defect.
             sweep: true === args['sweep'],
+            ...(from === undefined ? {} : { from }),
         });
     }
     catch (error) {

package/dist/language/flows/flow-replay-types.d.ts

@@ -26,6 +26,15 @@ export interface FlowReplaySession {
     onEvent(listener: (event: ReticleEvent) => void): () => void;
     /** Buffer clock (ms since connect) — required by the predicate engine's `settled` check. */
     elapsed(): number;
+    /**
+     * Where the app under test lives, so a third-party beacon is not mistaken for the app still
+     * working. Optional for the same reason `beginAction` is — a minimal test double should not have
+     * to invent an origin — and it FAILS OPEN: with no origin nothing is foreign, so an omitted value
+     * suppresses nothing rather than silently widening what a replay ignores.
+     */
+    url?: string;
+    /** Same-origin endpoints the project declared as background — see `Session.background`. */
+    background?: readonly string[];
 }
 /**
  * The injected predicate-waiter (the real waitForPredicate) — reused, never reimplemented.