@reticlehq/server 3.5.0 → 3.7.0

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

@@ -4,10 +4,10 @@ import { EventType, FLOW_SIGNAL_TIMEOUT_MS, FlowErrorCode, RecordedFlowSchema, R
 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 { navigablePath, 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 { anchorPrecondition, anchorQueryArgs } from './flow-step-runners.js';
+import { partialStatus, replayFlow, replayWindow } from './flow-replay.js';
+import { anchorPrecondition, anchorQueryArgs, staleTargetResult } 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';
@@ -17,7 +17,7 @@ import { isDocumentGoneError } from '../../portal/session/facts/session-replaced
 import { classifyFlowAssertions, flattenSteps } from './flow-classify.js';
 import { dischargeFlowIntent, flowIntentStatement, flowReplayVerdictId } from './flow-intent.js';
 import { IntentStore } from '../../memory/intent/intent-store.js';
-import { sessionRoot } from '../../memory/project/session-root.js';
+import { safeSessionTarget, sessionRoot, } from '../../memory/project/session-root.js';
 import { waitForPredicate } from '@reticlehq/engine/question/predicate/predicate.js';
 import { computeSegments } from '../../memory/journal/rollups.js';
 import { stepEffect } from '@reticlehq/engine/evidence/step-effect.js';
@@ -28,10 +28,13 @@ import { EnvelopeStore } from '../../memory/journal/envelope-store.js';
 import { homedir } from 'node:os';
 import { cloudFetch, syncRunRecordToCloud, SyncOutcome } from '../../memory/cloud/cloud-sync.js';
 import { resolveProjectCloud } from '../../memory/cloud/cloud-config.js';
+import { memoryReadHeaders, memoryReadUrl, scopedMemoryEntries, } from '../../memory/cloud/memory-scope.js';
 import { consultSubjectFor, selectConsulted } from './flow-memory-consult.js';
 import { log } from '../../log.js';
+import { replayStepShooter } from '../../features/visual/step-shots.js';
 import { flowsForSession } from './flow-store-for-session.js';
 import { projectForRoot } from '../../memory/project/project-for-root.js';
+import { CROSS_STEP_INDEX, crossStepOnly } from './flow-cross-step.js';
 export function latestRecordedFlow(events) {
     for (let i = events.length - 1; i >= 0; i--) {
         const event = events[i];
@@ -44,7 +47,7 @@ export function latestRecordedFlow(events) {
     return undefined;
 }
 export { flowErrorMessage } from './flow-result.js';
-import { flowErrorMessage } from './flow-result.js';
+import { flowErrorMessage, noteReplayCheck } from './flow-result.js';
 /** Map the wire ReplayStatus onto the persisted RunStatus (ok→pass). */
 function replayToRunStatus(status) {
     switch (status) {
@@ -105,13 +108,14 @@ function currentPathOf(session) {
     // 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.
+    // Reticle's own params dropped, as the recording drops them from `startPath` (#1411).
     const observed = last === undefined ? undefined : routeOfEvent(last);
     if (observed !== undefined)
-        return `${observed.docPath}${observed.search}${observed.hash}`;
+        return navigablePath(observed);
     if (session.url === undefined)
         return undefined;
     const fromUrl = routeOfUrl(session.url);
-    return fromUrl === undefined ? undefined : `${fromUrl.docPath}${fromUrl.search}${fromUrl.hash}`;
+    return fromUrl === undefined ? undefined : navigablePath(fromUrl);
 }
 /**
  * Ask the project what it already knows about this flow.
@@ -130,18 +134,17 @@ async function consultProjectMemory(deps, flow, root) {
     if (subject === undefined)
         return undefined;
     try {
-        // The APP's root, not the daemon's. `deps.reticleRoot` is wherever the daemon was launched,
-        // which for a user-scoped MCP registration is almost never the project being verified — so the
-        // link file it reads is the wrong one, or absent, and every project silently reads as
-        // "not attached". Same class of bug as the flow store resolving per daemon instead of per
-        // session, and it is invisible: the feature simply never appears.
+        // The APP's root, not the daemon's (wherever it was launched): its link file is this project's.
         const cloud = await resolveProjectCloud(deps.fs, root, homedir(), process.env);
         if (null === cloud.config || !cloud.policy.memory)
             return undefined;
-        const url = `${cloud.config.url}/v1/memory?subject=${encodeURIComponent(subject)}`;
+        // Scoped to the linked project. The key covers a whole workspace, so a read that named no
+        // project could be answered with ANOTHER repo's knowledge and this replay would carry it into a
+        // verdict as if it were this app's — see `memory-scope.ts` for the whole shape.
+        const url = memoryReadUrl(cloud.config.url, { projectId: cloud.projectId, subject });
         const res = await cloudFetch(url, {
             method: 'GET',
-            headers: { authorization: `Bearer ${cloud.config.apiKey}` },
+            headers: memoryReadHeaders(cloud.config.apiKey),
         });
         if (200 !== res.status)
             return undefined;
@@ -149,9 +152,14 @@ async function consultProjectMemory(deps, flow, root) {
         // property yields the function itself, `.entries` on it is undefined, and the whole feature
         // fails silently to "the project knows nothing" — which is indistinguishable from the honest
         // empty case and is why this took a live drive to notice at all.
-        const body = (await res.json());
-        const entries = body?.entries;
-        if (!Array.isArray(entries))
+        const body = await res.json();
+        // The envelope is the check that works: the platform names the project on the RESPONSE and not
+        // on each entry, so the entry-level filter alone kept a whole sibling workspace while looking
+        // like it did something. `undefined` means the response could not be shown to be this project's
+        // — nothing is attached, because a verdict carrying another repo's "established knowledge" is
+        // worse than one carrying none. See `memory-scope.ts`.
+        const entries = scopedMemoryEntries(body, cloud.projectId);
+        if (entries === undefined)
             return undefined;
         const picked = selectConsulted(entries);
         return 0 === picked.length ? undefined : picked;
@@ -167,8 +175,8 @@ async function consultProjectMemory(deps, flow, root) {
  * anchor simply isn't on this page yet. Detect that so the decision says "navigate there first"
  * instead of a mystifying "a step no longer matches". Returns undefined when the routes agree or the
  * current route is unobservable — never a false alarm. Replay normally never gets here on a
- * wrong page (arriveAtStartPath navigates before step 1); this is the fallback for when that
- * navigation was refused or the SDK never reconnected in the window.
+ * wrong page (arriveAtStartPath navigates before step 1); this is the fallback when navigation
+ * was refused. A page that never reconnected is reported as unverifiable before step 1.
  */
 export function startPathMismatchHint(flow, session) {
     const startPath = flow.startPath;
@@ -188,33 +196,25 @@ const REAL_ARRIVAL_CLOCK = {
 };
 /**
  * The session `oldId` denotes right now — itself, or the tombstone successor `resolve` rebinds to
- * after a full-document navigation — but only once it actually sits on `target`. Undefined while
- * the tab is still travelling (or in the gap between teardown and the successor's HELLO, when
- * `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.
+ * after a full-document navigation. A different instance proves the SDK reconnected even when the
+ * app redirected to another route. Keyed to the navigated tab's own identity on purpose: matching
+ * "any session at the target page" could hand replay an unrelated tab already sitting there.
  */
 function arrivedSuccessor(sessions, oldId, target, 
-/** The handle that issued the navigation, when only a genuinely new one counts as arrival. */
-mustReplace) {
+/** The handle that issued the navigation. */
+issuedBy, isReload) {
     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)
+        // A reload can return the dying handle on the same path. Compare instances, not ids: a leased
+        // tab can reconnect under the same id. A redirect counts only on a new instance.
+        if (isReload && candidate === issuedBy)
             return undefined;
         const path = currentPathOf(candidate);
-        return path !== undefined && samePath(path, target) ? candidate : undefined;
+        if (path === undefined)
+            return undefined;
+        const matches = samePath(path, target);
+        // A still-connected old tab on the wrong route is not a redirected successor.
+        return matches || candidate !== issuedBy ? { session: candidate, matches } : undefined;
     }
     catch {
         return undefined;
@@ -267,10 +267,9 @@ async function firstStepResolvesHere(session, flow) {
  * 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 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.
+ * when the flow carries no startPath, the current route is unobservable, or navigation is refused,
+ * replay proceeds on the connected session. A missing successor stops before step 1; a redirect
+ * continues on the live successor with a route-specific hint.
  */
 export async function arriveAtStartPath(sessions, session, flow, timeoutMs = START_PATH_ARRIVAL_TIMEOUT_MS, clock = REAL_ARRIVAL_CLOCK) {
     const target = flow.startPath;
@@ -304,9 +303,24 @@ export async function arriveAtStartPath(sessions, session, flow, timeoutMs = STA
     // 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)
+    const outcome = await navigateAndAwait(sessions, session, destination, target, timeoutMs, clock, here);
+    if ('lost' === outcome.kind) {
+        return {
+            lost: `replay ${here ? 'reloaded' : 'navigated to'} ${target} before step 1 and no page was connected ` +
+                `after ${String(timeoutMs)}ms, so the session it was driving is gone and nothing ran. A slow ` +
+                `or backgrounded tab can take longer to come back: bring it to the front and replay`,
+        };
+    }
+    if ('refused' === outcome.kind)
         return {};
+    if ('redirected' === outcome.kind) {
+        const path = currentPathOf(outcome.session) ?? 'another route';
+        return {
+            session: outcome.session,
+            redirected: `replay ${here ? 'reloaded' : 'navigated to'} ${target} before step 1, but the tab reconnected on ${path}. Check the redirect or sign in before replaying`,
+        };
+    }
+    const arrived = outcome.session;
     if (!resolvedBefore || (await firstStepResolvesHere(arrived, flow)))
         return { session: arrived };
     return {
@@ -329,18 +343,6 @@ function resetCostHint(flow, target) {
     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.
- *
- * A navigation is a full page load: the session that issued it DIES and a successor connects with a
- * new id. Every caller therefore has to wait for that successor rather than reuse the handle it
- * already holds, and getting this wrong does not error — it leaves the caller talking to a session
- * that will never answer again.
- *
- * Extracted so there is ONE of these rather than one per caller. `arriveAtStartPath` decides WHETHER
- * 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, 
 /** True when the destination is the page we are already on — see `arrivedSuccessor`. */
 isReload = false) {
@@ -349,7 +351,7 @@ isReload = false) {
     try {
         const outcome = await session.command(ReticleCommand.NAVIGATE, { url });
         if (!outcome.ok || true !== asRecord(outcome.result)['ok'])
-            return undefined;
+            return { kind: 'refused' };
     }
     catch (error) {
         // A navigation that unloads the page rejects the very command that asked for it — the transport
@@ -357,15 +359,18 @@ isReload = false) {
         // and left replay driving a handle that could never answer again, which is how a flow with a
         // startPath died at step 1 on an app that had loaded perfectly. Anything else is a real refusal.
         if (!isDocumentGoneError(error))
-            return undefined;
+            return { kind: 'refused' };
     }
     const deadline = clock.now() + timeoutMs;
     for (;;) {
-        const arrived = arrivedSuccessor(sessions, session.id, expectedPath, isReload ? session : undefined);
-        if (arrived !== undefined)
-            return arrived;
+        const arrived = arrivedSuccessor(sessions, session.id, expectedPath, session, isReload);
+        if (true === arrived?.matches)
+            return { kind: 'arrived', session: arrived.session };
+        // A live redirect is a different result from no SDK reconnection at all.
         if (clock.now() >= deadline)
-            return undefined;
+            return arrived === undefined
+                ? { kind: 'lost' }
+                : { kind: 'redirected', session: arrived.session };
         await clock.sleep(START_PATH_POLL_MS);
     }
 }
@@ -382,7 +387,7 @@ isReload = false) {
  * conservative direction, because a composite graded on a flow nobody could read is graded on a
  * promise.
  */
-async function loadInvokedFlows(deps, flow, projectId) {
+async function loadInvokedFlows(deps, flow, target) {
     const out = new Map();
     const queue = [flow];
     const seen = new Set([flow.name]);
@@ -395,7 +400,7 @@ async function loadInvokedFlows(deps, flow, projectId) {
             if (name === undefined || seen.has(name))
                 continue;
             seen.add(name);
-            const sub = await flowsForSession(deps, projectId).flows.load(name, projectId);
+            const sub = await flowsForSession(deps, target).flows.load(name, target.projectId);
             if (!sub.ok)
                 continue;
             out.set(name, sub.value);
@@ -453,7 +458,7 @@ async function firstUnmetPrecondition(session, flow, since) {
 export function lostDocumentResult(name, lost) {
     return {
         name,
-        status: ReplayStatus.OK,
+        status: ReplayStatus.UNVERIFIABLE,
         steps: lost.steps,
         unverifiable: {
             reason: `the page's connection to Reticle was replaced while step ${String(lost.atStep)} was running ` +
@@ -473,16 +478,11 @@ observe = (s) => s) {
     // Resolve within the connecting app's scope so a shared daemon replays THIS project's flow, not a
     // same-named flow from another app. Safe-resolve: a missing session degrades to the global store,
     // and the load-then-session order (unchanged) still surfaces a not-found before a no-session error.
-    let projectId;
-    try {
-        projectId = deps.sessions.resolve(asString(args['sessionId'])).projectId;
-    }
-    catch {
-        projectId = undefined;
-    }
+    const target = safeSessionTarget(deps, asString(args['sessionId']));
+    const { projectId } = target;
     // The app's store, not the daemon's: this load answering `flow_not_found` for a flow plainly on
     // disk is what made replay unusable from a daemon started outside the project.
-    const loaded = await flowsForSession(deps, projectId).flows.load(name, projectId);
+    const loaded = await flowsForSession(deps, target).flows.load(name, projectId);
     if (!loaded.ok) {
         await recordReplayRun(deps, name, ReplayStatus.ERROR, 0, deps.now() - startedAt, projectId, sessionRoot(deps, asString(args['sessionId'])));
         return {
@@ -507,11 +507,23 @@ observe = (s) => s) {
     // 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 arrival = await arriveAtStartPath(deps.sessions, connected, loaded.value);
+    // Continuing at a step means the page is already there; going to the start would undo it.
+    const { to, at: continueAt } = replayWindow(args);
+    const arrival = continueAt === undefined ? await arriveAtStartPath(deps.sessions, connected, loaded.value) : {};
+    // Continuing on `connected` after the tab left timed every step out on a dead handle (#1129).
+    if (arrival.lost !== undefined) {
+        const reason = arrival.lost;
+        return {
+            name: loaded.value.name,
+            status: ReplayStatus.UNVERIFIABLE,
+            steps: [],
+            unverifiable: { reason },
+        };
+    }
     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);
+    const startPathHint = arrival.redirected ?? 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();
@@ -521,7 +533,7 @@ observe = (s) => s) {
     // Loaded once and used for BOTH the replay and the grading below. A composite asserts through
     // what it runs, and a grader that cannot see the sub-flows reports `unverifiable` on a journey
     // that checks itself thoroughly — right about the file, wrong about the journey.
-    const invokedFlows = await loadInvokedFlows(deps, replayable, projectId);
+    const invokedFlows = await loadInvokedFlows(deps, replayable, target);
     /*
      * The flow's own preconditions, before a single step runs.
      *
@@ -557,11 +569,11 @@ observe = (s) => s) {
         const names = missing.map((each) => each.envKey).join(', ');
         return {
             name: replayable.name,
-            status: ReplayStatus.OK,
+            status: ReplayStatus.UNVERIFIABLE,
             steps: [],
             unverifiable: {
-                reason: `this flow fills a redacted field and nothing supplied it, so nothing ran and nothing ` +
-                    `was proved. Set ${names} in the environment the daemon runs in, then replay. Until then ` +
+                reason: `this flow fills a redacted field and nothing supplied it, so nothing ran and nothing was ` +
+                    `proved. Pass it with this call — secrets: { ${missing.map((each) => `"${each.field}": "…"`).join(', ')} } — or set ${names} where the daemon runs and restart it. Until then ` +
                     `the value typed would be the placeholder itself, and any failure after it would be ` +
                     `about this and not about the application.`,
             },
@@ -577,7 +589,7 @@ observe = (s) => s) {
     if (unmet !== undefined) {
         return {
             name: replayable.name,
-            status: ReplayStatus.OK,
+            status: ReplayStatus.UNVERIFIABLE,
             steps: [],
             unverifiable: { reason: unmet },
         };
@@ -588,13 +600,21 @@ observe = (s) => s) {
             // 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) => {
-                const sub = await flowsForSession(deps, projectId).flows.load(invoked, projectId);
+                const sub = await flowsForSession(deps, target).flows.load(invoked, projectId);
                 return sub.ok ? await resolveFlowUploads(deps, sub.value) : undefined;
             },
             // 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 }),
+            ...(to === undefined ? {} : { to }),
+            ...(continueAt === undefined ? {} : { at: continueAt }),
+            // The HUD's replay chip, when the human pressed ▶. In-process only: an agent's arguments
+            // arrive as JSON and can never carry a function.
+            onStepResult: replayStepShooter(deps, session.id),
+            ...('function' === typeof args['onStep']
+                ? { onStep: args['onStep'] }
+                : {}),
         });
     }
     catch (error) {
@@ -602,6 +622,9 @@ observe = (s) => s) {
             throw error;
         return lostDocumentResult(name, error);
     }
+    // Only part of the journey was driven here: its steps were checked, nothing about the whole flow.
+    if (0 < (continueAt ?? 0) || (to !== undefined && to < loaded.value.steps.length))
+        return { name, status: partialStatus(steps), steps };
     // Computed HERE, before the synthetic success row is appended below: once that row is pushed,
     // `steps.length` no longer counts only the flow's own steps and the arithmetic is wrong.
     const halted = haltedFrom(steps, loaded.value.steps.length);
@@ -639,6 +662,9 @@ observe = (s) => s) {
         };
         steps.push(row);
     }
+    const staleTarget = staleTargetResult(name, steps);
+    if (staleTarget !== undefined)
+        return staleTarget;
     const driftSteps = steps.filter((s) => s.drift !== undefined).length;
     const allOk = steps.every((s) => s.ok);
     const status = driftSteps > 0 ? ReplayStatus.DRIFT : allOk ? ReplayStatus.OK : ReplayStatus.ERROR;
@@ -674,8 +700,9 @@ observe = (s) => s) {
      * moment somebody needs to know what this feature is supposed to do and who established it. A
      * knowledge base you only see when everything is already fine is decoration.
      */
-    // No projectId argument: the API key is already bound to one project server-side, so passing a
-    // second opinion about which project this is would only create a way for the two to disagree.
+    // The scope comes from the link file, inside `consultProjectMemory`. It is NOT the API key's
+    // job: a key covers a whole workspace and a workspace holds more than one repo, so "bound to one
+    // project server-side" was an assumption that handed this replay another app's knowledge.
     const knows = await consultProjectMemory(deps, loaded.value, replayRoot);
     const failed = steps.find((step) => !step.ok && step.drift === undefined);
     if (failed !== undefined) {
@@ -700,13 +727,12 @@ observe = (s) => s) {
         result.halted = halted;
     if (knows !== undefined)
         result.knows = knows;
-    // A green that cannot go red is not a pass. `reticle_flow_verify` already refuses to count these,
-    // via this same function -- a single-flow caller saw a bare `ok` and had no way to learn the flow
-    // asserts nothing. Derived from the same helper on purpose: two copies of this judgement would
-    // drift, and the sibling tools would then disagree about the same flow.
+    // A green that cannot go red is not a pass: the same judgement `reticle_flow_verify` makes.
     const cannotFail = status === ReplayStatus.OK ? unverifiableReason(loaded.value, invokedFlows) : undefined;
     if (cannotFail !== undefined)
         result.unverifiable = { reason: cannotFail };
+    // One check of the session that ran it, so its end does not say "nothing was checked".
+    noteReplayCheck(session, name, status, cannotFail !== undefined);
     if (status !== ReplayStatus.OK)
         result.decision = buildDecision(result, loaded.value, intentSaid, invokedFlows);
     applyStartPathHint(result, startPathHint);
@@ -768,27 +794,6 @@ observe = (s) => s) {
      */
     return result;
 }
-/** A contradiction's identity for de-duplication: the rule that fired, and the evidence it fired on. */
-function contradictionId(found) {
-    return `${found.kind}|${found.detail}`;
-}
-/**
- * The contradictions the whole-span pass found that no individual step could.
- *
- * A step's window closes when the step ends, so a request fired at step 2 and still unanswered at
- * step 5 is invisible to every per-step window: step 2's closed before the answer came and step 5
- * never saw it start. Re-running the detectors over the whole replay span finds those — and re-finds
- * everything the steps already reported, which is what the subtraction is for. Reporting a finding
- * twice teaches a reader that the count is noise.
- *
- * Exported for its own test: the subtraction is the whole rule, and it is pure.
- */
-/** Cross-step findings belong to no single step; -1 is the address the suite verdict already uses. */
-const CROSS_STEP_INDEX = -1;
-export function crossStepOnly(whole, steps) {
-    const seen = new Set(steps.flatMap((step) => (step.contradictions ?? []).map(contradictionId)));
-    return whole.filter((found) => !seen.has(contradictionId(found)));
-}
 /**
  * The deviation report over a replay's route segments — compared against the learned envelope, which is
  * then updated. Best-effort: any failure (disk, empty window) yields undefined, never breaking the replay.

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

@@ -12,7 +12,7 @@ import type { EvalResult } from '@reticlehq/engine/question/predicate/predicate.
  * (via the injected waitForPredicate). Mirrors PredicateSession so the same fake drives both.
  */
 export interface FlowReplaySession {
-    command(name: string, args?: Record<string, unknown>): Promise<CommandResult>;
+    command(name: string, args?: Record<string, unknown>, timeoutMs?: number): Promise<CommandResult>;
     /**
      * Attribution window around each replayed step. Optional so a minimal test double still satisfies the
      * interface, but a real session MUST supply it: without a window the step's own effects carry no

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

@@ -1,7 +1,7 @@
 export { nearestIsAmbiguous, nearestTestid, resolveQuery } from './flow-anchor.js';
 import type { FlowReplaySession, WaitForSignal, Sleep } from './flow-replay-types.js';
 export type { FlowReplaySession, WaitForSignal, Sleep } from './flow-replay-types.js';
-import { type Drift, type FlowFile, type FlowStep, type FlowStepResult } from '@reticlehq/core';
+import { type Drift, type FlowFile, type FlowStep, type FlowStepResult, ReplayStatus } from '@reticlehq/core';
 /**
  * The document this replay was driving went away mid-run.
  *
@@ -43,6 +43,15 @@ export declare function runTestidStep(session: FlowReplaySession, step: FlowStep
  * state it was never meant to run in.
  */
 export declare function assertStepExpect(session: FlowReplaySession, expect: NonNullable<FlowStep['expect']>, waitForSignal: WaitForSignal, timeoutMs: number, since: number): Promise<Drift | undefined>;
+/**
+ * A text check that missed only on case says so, with what would hold. Text checks match case
+ * exactly now, so a flow saved when they did not goes red on capitalisation alone; the person
+ * reading its replay needs the fix (`ignoreCase: true`, or re-record), not a bare "did not hold".
+ */
+export declare function withCaseOnly(reason: string, verdict: {
+    caseOnlyMiss?: boolean;
+    wouldHold?: string;
+}): string;
 /**
  * Replay a loaded flow by RE-RESOLVING every step's semantic anchor against the live DOM — never
  * a stale ref. A testid anchor is re-found by reticle_query; a signal anchor waits on a predicate.
@@ -53,6 +62,16 @@ export declare function assertStepExpect(session: FlowReplaySession, expect: Non
  * How a replay is loaded, where it starts reporting, and how far it goes.
  */
 export interface ReplayFromOptions {
+    /**
+     * Told after every step it reports: how many are done, of how many, and whether this one held.
+     * The HUD's replay chip draws its progress from this; it must never throw into the replay.
+     */
+    onStep?: (done: number, total: number, held: boolean) => void;
+    /**
+     * Told each reported step the moment its outcome is decided, before it is kept, so a caller can
+     * add to it (the step's screenshot). Never allowed to fail the replay.
+     */
+    onStepResult?: (result: FlowStepResult, flow: string) => Promise<void>;
     /**
      * Resume at this step: an index, or a step's `id` (which survives edits that shift indices).
      *
@@ -62,6 +81,16 @@ export interface ReplayFromOptions {
      * for, and swallowing that would report the run as starting where it did not.
      */
     from?: number | string;
+    /**
+     * Stop before this step index: drive the journey only as far as a point, such as a dialog that
+     * several journeys branch from. Absent means the whole flow.
+     */
+    to?: number;
+    /**
+     * Continue at this step on the page as it is: earlier steps are not driven at all, because the
+     * caller already drove an identical prefix (another flow replayed `to` this step).
+     */
+    at?: number;
     /**
      * How to load a flow this one INVOKES. Absent means invocations cannot be followed.
      *
@@ -99,6 +128,16 @@ export interface ReplayFromOptions {
  * is not setup, it is a second charge, a second email, a second record.
  */
 export declare function resumeIndex(from: number | string | undefined, steps: readonly FlowStep[]): number | undefined;
+/**
+ * How far a replay drives: `to` stops before a step (positive), `at` picks up at one on the page as
+ * it is. `at: 0` is the whole flow continuing the page the flow before it left, with no reload.
+ */
+export declare function replayWindow(args: Record<string, unknown>): {
+    to?: number;
+    at?: number;
+};
+/** A part-way replay's status, from the steps it drove. */
+export declare function partialStatus(steps: readonly FlowStepResult[]): ReplayStatus;
 /** The `from` argument, narrowed: a step index or a step id. */
 export declare function resumeArg(raw: unknown): number | string | undefined;
 /** Why `from` cannot be resumed at, or undefined when it can (or was not given). */