@reticlehq/server 3.4.0 → 3.6.0

package/dist/language/flows/flow-cross-step.js

@@ -0,0 +1,21 @@
+/** 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}`;
+}
+/** Cross-step findings belong to no single step; -1 is the address the suite verdict already uses. */
+export const CROSS_STEP_INDEX = -1;
+/**
+ * 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.
+ */
+export function crossStepOnly(whole, steps) {
+    const seen = new Set(steps.flatMap((step) => (step.contradictions ?? []).map(contradictionId)));
+    return whole.filter((found) => !seen.has(contradictionId(found)));
+}

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

@@ -1,15 +1,11 @@
 import { asString } from '@reticlehq/core';
 import { flowsForSession } from './flow-store-for-session.js';
+import { safeSessionTarget } from '../../memory/project/session-root.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;
-    }
+function targetOf(deps, args) {
+    return safeSessionTarget(deps, asString(args['sessionId']));
 }
 /**
  * Write back what a replay taught the flow, once the replay has finished writing its own.
@@ -36,8 +32,8 @@ export async function persistLearning(deps, args, result) {
     if (0 === name.length)
         return result;
     try {
-        const projectId = projectOf(deps, args);
-        await flowsForSession(deps, projectId).flows.recordLearned(name, learned, projectId);
+        const target = targetOf(deps, args);
+        await flowsForSession(deps, target).flows.recordLearned(name, learned, target.projectId);
     }
     catch {
         // Bookkeeping only.
@@ -93,8 +89,9 @@ export async function persistSources(deps, args, sources) {
     if (0 === name.length)
         return;
     try {
-        const projectId = projectOf(deps, args);
-        const store = flowsForSession(deps, projectId).flows;
+        const target = targetOf(deps, args);
+        const { projectId } = target;
+        const store = flowsForSession(deps, target).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)

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

@@ -15,7 +15,8 @@ import { MutationOutcome } from 'open-verification';
 import { z } from 'zod';
 import { sessionMutationPort } from '../../surface/tools/lease-tools.js';
 import { mutationTest } from './mutation-run.js';
-import { replayNamedFlow, sessionProjectId } from './flow-replay-run.js';
+import { replayNamedFlow } from './flow-replay-run.js';
+import { sessionTarget } from '../../memory/project/session-root.js';
 import { flowsForSession } from './flow-store-for-session.js';
 import { ReplayStatus } from '@reticlehq/core';
 const NOTHING_DECLARED = 'this flow declares no network consequence, so it has named nothing whose breakage it could be ' +
@@ -48,8 +49,9 @@ export const FLOW_MUTATE_TOOL = {
     handler: async (deps, args) => {
         const name = asString(args['flowName']) ?? asString(args['flow']) ?? '';
         const sessionId = asString(args['sessionId']);
-        const projectId = sessionProjectId(deps, sessionId);
-        const loaded = await flowsForSession(deps, projectId).flows.load(name, projectId);
+        const project = sessionTarget(deps, sessionId);
+        const { projectId } = project;
+        const loaded = await flowsForSession(deps, project).flows.load(name, projectId);
         if (!loaded.ok) {
             return { flow: name, because: `could not load "${name}": ${String(loaded.code)}` };
         }

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

@@ -1,4 +1,4 @@
-import { type CommandResult, type FlowFile, type FlowReplayResult, type Contradiction, type FlowStepResult, type ReticleEvent } from '@reticlehq/core';
+import { type CommandResult, type FlowFile, type FlowReplayResult, 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';
@@ -20,8 +20,8 @@ interface StartPathSession {
  * 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 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. */
@@ -30,6 +30,10 @@ export interface StartPathArrival {
     session?: Session;
     /** Set when the RESET itself is why step 1 cannot start — the reason a step-1 red is not drift. */
     resetCost?: string;
+    /** Set when the tab was sent away and nothing reconnected: the old handle will never answer (#1129). */
+    lost?: string;
+    /** A live successor arrived on a different route, so replay must not use the dead old handle. */
+    redirected?: string;
 }
 /**
  * Replay's half of the FlowFile contract: put the tab on the flow's `startPath` before step 1, and
@@ -48,10 +52,9 @@ export interface StartPathArrival {
  * 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 declare function arriveAtStartPath(sessions: SessionManager, session: StartPathSession & {
     id: string;
@@ -69,6 +72,18 @@ export declare function arriveAtStartPath(sessions: SessionManager, session: 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.
  */
+/** How a navigate ended: target, redirect, refusal (untouched tab), or no successor. */
+export type NavigateOutcome = {
+    kind: 'arrived';
+    session: Session;
+} | {
+    kind: 'redirected';
+    session: Session;
+} | {
+    kind: 'refused';
+} | {
+    kind: 'lost';
+};
 export declare function navigateAndAwait(sessions: SessionManager, session: {
     id: string;
     /** Optional because a session's URL is, and `carryReticleIdentity` already handles its absence. */
@@ -76,7 +91,7 @@ export declare function navigateAndAwait(sessions: SessionManager, session: {
     command(name: string, args?: Record<string, unknown>): Promise<CommandResult>;
 }, 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>;
+isReload?: boolean): Promise<NavigateOutcome>;
 /**
  * The honest answer when the document replay was driving went away mid-run.
  *
@@ -97,7 +112,6 @@ export declare function lostDocumentResult(name: string, lost: DocumentLostDurin
 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
  * scope storage to the current app on a shared daemon; resolving must NOT throw here (list/load are

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

@@ -6,8 +6,8 @@ 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 { 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,12 @@ 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 { memoryReadUrl, scopedMemoryEntries } from '../../memory/cloud/memory-scope.js';
 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 { 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];
@@ -138,7 +140,10 @@ async function consultProjectMemory(deps, flow, root) {
         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}` },
@@ -149,9 +154,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 +177,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 +198,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 +269,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 +305,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 +345,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 +353,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 +361,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 +389,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 +402,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 +460,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 +480,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 +509,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 +535,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,7 +571,7 @@ 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 ` +
@@ -577,7 +591,7 @@ observe = (s) => s) {
     if (unmet !== undefined) {
         return {
             name: replayable.name,
-            status: ReplayStatus.OK,
+            status: ReplayStatus.UNVERIFIABLE,
             steps: [],
             unverifiable: { reason: unmet },
         };
@@ -588,13 +602,20 @@ 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.
+            ...('function' === typeof args['onStep']
+                ? { onStep: args['onStep'] }
+                : {}),
         });
     }
     catch (error) {
@@ -602,6 +623,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 (continueAt !== undefined || (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 +663,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 +701,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) {
@@ -768,27 +796,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.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.
  *
@@ -53,6 +53,11 @@ 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;
     /**
      * Resume at this step: an index, or a step's `id` (which survives edits that shift indices).
      *
@@ -62,6 +67,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 +114,13 @@ 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, `at` picks up at one. Positive indices only. */
+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). */