@reticlehq/server 3.7.0 → 3.8.1

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

@@ -1,14 +1,12 @@
 import { resolveFlowUploads } from './fields/flow-upload-resolve.js';
+import { withLeaseKeyboard } from '../../surface/tools/real-input-attempt.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 { EventType, FLOW_SIGNAL_TIMEOUT_MS, FlowErrorCode, RecordedFlowSchema, ReplayStatus, 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 { navigablePath, routeOfEvent, routeOfUrl, } from '@reticlehq/engine/question/predicate/predicate-route.js';
-import { carryReticleIdentity } from '../../surface/tools/lease-tools.js';
+import { establishedState } from './flow-journey.js';
+import { asString } from '@reticlehq/core';
 import { partialStatus, replayFlow, replayWindow } from './flow-replay.js';
-import { anchorPrecondition, anchorQueryArgs, staleTargetResult } from './flow-step-runners.js';
-import { queryRefs } from './replay.js';
+import { staleTargetResult } from './flow-step-runners.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';
@@ -20,7 +18,7 @@ import { IntentStore } from '../../memory/intent/intent-store.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';
+import { appScope, stepEffect } from '@reticlehq/engine/evidence/step-effect.js';
 import { AssertionTiersStore } from './stores/assertion-tiers-store.js';
 import { toFlowSources } from './change/flow-sources.js';
 import { reportAndAccumulate } from '../../memory/journal/deviation-service.js';
@@ -28,21 +26,24 @@ 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 { memoryReadHeaders, readMemoryPages, 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';
+import { CROSS_STEP_INDEX, crossStepOnly, declaredIn } from './flow-cross-step.js';
+import { arriveAtStartPath, startPathMismatchHint, withStartPageWait } from './flow-start-path.js';
 export function latestRecordedFlow(events) {
     for (let i = events.length - 1; i >= 0; i--) {
         const event = events[i];
-        if (event?.type !== EventType.FLOW_RECORDED)
+        if (event?.type !== EventType.FLOW_RECORDED) {
             continue;
+        }
         const parsed = RecordedFlowSchema.safeParse(event.data);
-        if (parsed.success)
+        if (parsed.success) {
             return { name: parsed.data.name, flow: parsed.data.flow };
+        }
     }
     return undefined;
 }
@@ -80,43 +81,14 @@ recordRoot) {
     // it was worse here: a replay outcome that should have reached the dashboard silently did not,
     // because the daemon's own directory has no link file.
     const cloud = await resolveProjectCloud(deps.fs, recordRoot, homedir(), process.env);
-    if (null === cloud.config || !cloud.policy.memory)
-        return; // not attached / memory disabled → local only
+    if (null === cloud.config || !cloud.policy.memory) {
+        return;
+    } // not attached / memory disabled → local only
     const result = await syncRunRecordToCloud({ kind: RunKind.FLOW_REPLAY, name, status: runStatus, at: deps.now(), durationMs }, projectId, cloud.config, cloudFetch);
     if (result.outcome !== SyncOutcome.SYNCED) {
         log('cloud-run-record-sync-failed', { flow: name, status: result.status, error: result.error });
     }
 }
-/**
- * The route the tab is on now: the last observed route.change, falling back to the pathname of the
- * session's own URL. The fallback matters — a tab that hard-loaded its page emits no route event
- * (the route observer only sees pushState/replaceState/popstate), but the HELLO url still names
- * where it sits, and without it a wrong-page replay reported plain drift with no hint at all.
- */
-function currentPathOf(session) {
-    const routes = session.eventsSince(0).filter((e) => e.type === EventType.ROUTE_CHANGE);
-    const last = routes.at(-1);
-    // 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.
-    // Reticle's own params dropped, as the recording drops them from `startPath` (#1411).
-    const observed = last === undefined ? undefined : routeOfEvent(last);
-    if (observed !== undefined)
-        return navigablePath(observed);
-    if (session.url === undefined)
-        return undefined;
-    const fromUrl = routeOfUrl(session.url);
-    return fromUrl === undefined ? undefined : navigablePath(fromUrl);
-}
 /**
  * Ask the project what it already knows about this flow.
  *
@@ -131,36 +103,36 @@ function currentPathOf(session) {
  */
 async function consultProjectMemory(deps, flow, root) {
     const subject = consultSubjectFor(flow);
-    if (subject === undefined)
+    if (subject === undefined) {
         return undefined;
+    }
     try {
         // 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)
+        if (null === cloud.config || !cloud.policy.memory) {
             return undefined;
+        }
         // 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: memoryReadHeaders(cloud.config.apiKey),
+        const config = cloud.config;
+        const body = await readMemoryPages(config.url, { projectId: cloud.projectId, subject }, async (url) => {
+            const res = await cloudFetch(url, {
+                method: 'GET',
+                headers: memoryReadHeaders(config.apiKey),
+            });
+            // `res.json` is a METHOD: read as a property it silently made "the project knows nothing".
+            return 200 === res.status ? await res.json() : undefined;
         });
-        if (200 !== res.status)
+        if (body === undefined) {
             return undefined;
-        // `cloudFetch` hands back a real `Response`, so the body is a METHOD. Reading `res.json` as a
-        // 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();
-        // 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`.
+        }
+        // `undefined`: the response could not be shown to be this project's, so nothing is attached —
+        // a verdict carrying another repo's "established knowledge" is worse than none. See memory-scope.
         const entries = scopedMemoryEntries(body, cloud.projectId);
-        if (entries === undefined)
+        if (entries === undefined) {
             return undefined;
+        }
         const picked = selectConsulted(entries);
         return 0 === picked.length ? undefined : picked;
     }
@@ -169,211 +141,6 @@ async function consultProjectMemory(deps, flow, root) {
         return undefined;
     }
 }
-/**
- * When a flow records the page its journey started on (`startPath`) and the tab is currently on a
- * different route, step 1 drifts for a reason that has nothing to do with the app regressing — the
- * 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 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;
-    if (startPath === undefined || 0 === startPath.length)
-        return undefined;
-    const current = currentPathOf(session);
-    if (current === undefined || samePath(current, startPath))
-        return undefined;
-    return `this flow's journey starts on ${startPath} but the tab is on ${current} — navigate there (reticle_navigate { url: "${startPath}" }), then replay`;
-}
-/** How long replay waits for the SDK to reconnect on the start page before falling back to the hint. */
-const START_PATH_ARRIVAL_TIMEOUT_MS = 5_000;
-const START_PATH_POLL_MS = 100;
-const REAL_ARRIVAL_CLOCK = {
-    now: () => Date.now(),
-    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
-};
-/**
- * The session `oldId` denotes right now — itself, or the tombstone successor `resolve` rebinds to
- * 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. */
-issuedBy, isReload) {
-    try {
-        const candidate = sessions.resolve(oldId);
-        // 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);
-        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;
-    }
-}
-/**
- * Can step 1 start from where the tab already is?
- *
- * A route mismatch is NOT on its own a reason to navigate. The condition worth a page load is that
- * the first anchor is not reachable from here — and a flow whose first anchor lives somewhere
- * persistent (a sidebar, a header, a nav rail) is reachable from every route.
- *
- * Navigating anyway is expensive in the one direction that matters: a full page load tears the
- * session down and brings the app back COLD, which for a flow recorded after signing in is the
- * login screen. Step 1 then reports its anchor missing and blames a file that is completely fine.
- * A best-effort step that can leave the caller WORSE off than skipping it is not best-effort.
- *
- * Unresolvable either way (no anchor we can query, a failed query) reads as "cannot tell", and the
- * navigation goes ahead — the pre-existing behaviour, and the safe direction for a check whose whole
- * job is to avoid making things worse.
- */
-async function firstStepResolvesHere(session, flow) {
-    const first = flow.steps?.[0];
-    if (first === undefined)
-        return false;
-    const args = anchorQueryArgs(first.anchor);
-    if (null === args)
-        return false;
-    try {
-        return 0 < queryRefs(await session.command(ReticleCommand.QUERY, args)).length;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * 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 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;
-    if (target === undefined || 0 === target.length)
-        return {};
-    const current = currentPathOf(session);
-    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. 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 {}; // no usable base URL — nowhere to navigate from
-    }
-    // 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 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 {
-        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`);
-}
-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 {
-        const outcome = await session.command(ReticleCommand.NAVIGATE, { url });
-        if (!outcome.ok || true !== asRecord(outcome.result)['ok'])
-            return { kind: 'refused' };
-    }
-    catch (error) {
-        // A navigation that unloads the page rejects the very command that asked for it — the transport
-        // dies with the document. Reading that as "the navigate failed" skipped the arrival poll below
-        // 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 { kind: 'refused' };
-    }
-    const deadline = clock.now() + timeoutMs;
-    for (;;) {
-        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 arrived === undefined
-                ? { kind: 'lost' }
-                : { kind: 'redirected', session: arrived.session };
-        await clock.sleep(START_PATH_POLL_MS);
-    }
-}
 /**
  * Replay one named flow end to end: load → re-resolve+run each step → assert the success oracle →
  * status + decision. Shared by reticle_flow_replay (single flow) and reticle_flow_verify (whole suite) so
@@ -393,16 +160,19 @@ async function loadInvokedFlows(deps, flow, target) {
     const seen = new Set([flow.name]);
     while (queue.length > 0) {
         const current = queue.shift();
-        if (current === undefined)
+        if (current === undefined) {
             continue;
+        }
         for (const step of flattenSteps(current.steps)) {
             const name = step.invoke;
-            if (name === undefined || seen.has(name))
+            if (name === undefined || seen.has(name)) {
                 continue;
+            }
             seen.add(name);
             const sub = await flowsForSession(deps, target).flows.load(name, target.projectId);
-            if (!sub.ok)
+            if (!sub.ok) {
                 continue;
+            }
             out.set(name, sub.value);
             queue.push(sub.value);
         }
@@ -429,8 +199,9 @@ async function firstUnmetPrecondition(session, flow, since) {
             drift = await assertStepExpect(session, claim, waitForPredicate, 0, since);
         }
         catch (error) {
-            if (!isDocumentGoneError(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) {
@@ -509,16 +280,21 @@ observe = (s) => s) {
     // connected session — and the hint below turns the wrong-page drift into an actionable next move.
     // 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) : {};
+    const pool = deps.pool;
+    // Only a pool lease can say its page is still loading; any other tab keeps the step budget.
+    const stillLoading = pool === undefined ? undefined : () => pool.leaseLoading(connected.id);
+    const arrival = continueAt === undefined
+        ? await arriveAtStartPath(deps.sessions, connected, loaded.value, undefined, undefined, stillLoading)
+        : {};
     // 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 {
+        return withStartPageWait({
             name: loaded.value.name,
             status: ReplayStatus.UNVERIFIABLE,
             steps: [],
             unverifiable: { reason },
-        };
+        }, arrival);
     }
     const session = arrival.session ?? connected;
     // The reset's own cost outranks the wrong-page hint: if the reload is why step 1 cannot start,
@@ -527,9 +303,9 @@ observe = (s) => s) {
     // 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();
-    // A recorded upload names a path on disk; the browser can only take bytes. Resolved once, before
-    // step 1, through the same helper the live `reticle_act` uses. See resolveFlowUploads.
-    const replayable = await resolveFlowUploads(deps, loaded.value);
+    // An upload path becomes bytes once, before step 1, against the app's project (#1769).
+    const uploadDeps = { fs: deps.fs, reticleRoot: replayRoot };
+    const replayable = await resolveFlowUploads(uploadDeps, loaded.value);
     // 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.
@@ -567,7 +343,7 @@ observe = (s) => s) {
     const missing = unsuppliedSecrets(replayable, process.env);
     if (missing.length > 0) {
         const names = missing.map((each) => each.envKey).join(', ');
-        return {
+        return withStartPageWait({
             name: replayable.name,
             status: ReplayStatus.UNVERIFIABLE,
             steps: [],
@@ -577,31 +353,31 @@ observe = (s) => s) {
                     `the value typed would be the placeholder itself, and any failure after it would be ` +
                     `about this and not about the application.`,
             },
-        };
+        }, arrival);
     }
     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 };
+        return withStartPageWait({ name: replayable.name, status: ReplayStatus.ERROR, steps: [], error }, arrival);
     }
     const unmet = await firstUnmetPrecondition(session, replayable, replayFloor);
     if (unmet !== undefined) {
-        return {
+        return withStartPageWait({
             name: replayable.name,
             status: ReplayStatus.UNVERIFIABLE,
             steps: [],
             unverifiable: { reason: unmet },
-        };
+        }, arrival);
     }
     let steps;
     try {
-        steps = await replayFlow(observe(session), replayable, waitForPredicate, FLOW_SIGNAL_TIMEOUT_MS, true === args['confirmDangerous'], undefined, {
+        steps = await replayFlow(observe(withLeaseKeyboard(deps, 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) => {
                 const sub = await flowsForSession(deps, target).flows.load(invoked, projectId);
-                return sub.ok ? await resolveFlowUploads(deps, sub.value) : undefined;
+                return sub.ok ? await resolveFlowUploads(uploadDeps, 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.
@@ -618,26 +394,28 @@ observe = (s) => s) {
         });
     }
     catch (error) {
-        if (!(error instanceof DocumentLostDuringReplay))
+        if (!(error instanceof DocumentLostDuringReplay)) {
             throw error;
-        return lostDocumentResult(name, error);
+        }
+        return withStartPageWait(lostDocumentResult(name, error), arrival);
     }
     // 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 };
+    if (0 < (continueAt ?? 0) || (to !== undefined && to < loaded.value.steps.length)) {
+        return withStartPageWait({ name, status: partialStatus(steps), steps }, arrival);
+    }
     // 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);
     /*
-     * The whole-span pass, run once the journey is over. Best-effort by construction: a session stub
-     * without `eventsSince` must not be able to abort a healthy replay, and a missing cross-step
-     * finding is a smaller loss than a run that dies computing one.
+     * The whole-span pass, run once the journey is over. Best-effort: a session stub without
+     * `eventsSince` must not abort a healthy replay. A missing cross-step finding costs less.
      */
     const crossStep = (() => {
         try {
             const span = { since: replayFloor, until: session.elapsed() };
             const events = session.eventsSince(replayFloor).filter((e) => e.t >= replayFloor);
-            return crossStepOnly(stepEffect(events, span).contradictions ?? [], steps);
+            const scope = { ...appScope(session), declared: declaredIn(loaded.value.steps) };
+            return crossStepOnly(stepEffect(events, span, scope).contradictions ?? [], steps);
         }
         catch {
             return [];
@@ -663,11 +441,21 @@ observe = (s) => s) {
         steps.push(row);
     }
     const staleTarget = staleTargetResult(name, steps);
-    if (staleTarget !== undefined)
-        return staleTarget;
+    if (staleTarget !== undefined) {
+        return withStartPageWait(staleTarget, arrival);
+    }
     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;
+    let status;
+    if (driftSteps > 0) {
+        status = ReplayStatus.DRIFT;
+    }
+    else if (allOk) {
+        status = ReplayStatus.OK;
+    }
+    else {
+        status = ReplayStatus.ERROR;
+    }
     await recordReplayRun(deps, name, status, driftSteps, deps.now() - startedAt, projectId, replayRoot);
     // Anti-reward-hacking baseline: record what this flow asserted ONLY when it passed clean. A
     // failing run must never become the baseline a later weakening is measured against.
@@ -714,32 +502,41 @@ observe = (s) => s) {
         };
         errored.decision = buildDecision(errored, loaded.value, intentSaid, invokedFlows);
         applyStartPathHint(errored, startPathHint);
-        if (deviation !== undefined)
+        if (deviation !== undefined) {
             errored.deviation = deviation;
-        if (knows !== undefined)
+        }
+        if (knows !== undefined) {
             errored.knows = knows;
-        if (crossStep.length > 0)
+        }
+        if (crossStep.length > 0) {
             errored.crossStep = crossStep;
-        return errored;
+        }
+        return withStartPageWait(errored, arrival);
     }
     const result = { name, status, steps };
-    if (halted !== undefined)
+    if (halted !== undefined) {
         result.halted = halted;
-    if (knows !== undefined)
+    }
+    if (knows !== undefined) {
         result.knows = knows;
+    }
     // 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)
+    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)
+    if (status !== ReplayStatus.OK) {
         result.decision = buildDecision(result, loaded.value, intentSaid, invokedFlows);
+    }
     applyStartPathHint(result, startPathHint);
-    if (deviation !== undefined)
+    if (deviation !== undefined) {
         result.deviation = deviation;
-    if (crossStep.length > 0)
+    }
+    if (crossStep.length > 0) {
         result.crossStep = crossStep;
+    }
     /*
      * What this run taught the flow.
      *
@@ -776,10 +573,12 @@ observe = (s) => s) {
         observed: steps.some((step) => step.digest !== undefined),
     });
     result.learned = learning.guards;
-    if (learning.promoted.length > 0)
+    if (learning.promoted.length > 0) {
         result.promoted = learning.promoted;
-    if (learning.regressed.length > 0)
+    }
+    if (learning.regressed.length > 0) {
         result.regressed = learning.regressed;
+    }
     /*
      * Write it back, or none of the above compounds.
      *
@@ -792,7 +591,7 @@ observe = (s) => s) {
      * lesson is smaller than losing the run that produced it. Skipped entirely when nothing moved,
      * so a clean replay of a flow with nothing to learn does not rewrite a file for no reason.
      */
-    return result;
+    return withStartPageWait(result, arrival);
 }
 /**
  * The deviation report over a replay's route segments — compared against the learned envelope, which is
@@ -803,8 +602,9 @@ async function computeReplayDeviation(deps, session, floor,
 root) {
     try {
         const segments = computeSegments(session.eventsSince(floor));
-        if (0 === segments.length)
+        if (0 === segments.length) {
             return undefined;
+        }
         return await reportAndAccumulate(new EnvelopeStore(deps.fs, root), segments);
     }
     catch {
@@ -813,8 +613,9 @@ root) {
 }
 /** Fold a start-page-mismatch hint onto a non-passing replay's decision (the actionable next move). */
 function applyStartPathHint(result, hint) {
-    if (hint === undefined || result.decision === undefined)
+    if (hint === undefined || result.decision === undefined) {
         return;
+    }
     result.decision.suggestedFix = hint;
     result.decision.nextAction = hint;
 }