@reticlehq/server 3.8.0 → 3.8.2

package/dist/language/flows/flow-start-path.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Replay's arrival at a flow's start page: navigate (or reload) before step 1, wait for the session
+ * the SDK reconnects as, and say what happened when it does not.
+ */
+import { type CommandResult, type FlowFile, type FlowReplayResult, type ReticleEvent, type StartPageWait } 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';
+/** The slice of a session the start-path logic reads: the live URL plus the event buffer. */
+interface StartPathSession {
+    url?: string;
+    eventsSince(cursor: number): ReticleEvent[];
+}
+/**
+ * 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 declare function startPathMismatchHint(flow: FlowFile, session: StartPathSession): string | undefined;
+/** What replay learned on its way to step 0. Both fields absent = the tab was left exactly as it was. */
+export interface StartPathArrival {
+    /** The successor session replay must continue on. Absent when nothing was navigated, or arrival timed out. */
+    session?: Session;
+    /** Set when the RESET itself is why step 1 cannot start — the reason a step-1 red is not drift. */
+    resetCost?: string;
+    /** 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;
+    /** Set when the page's loading kept replay waiting past the step budget. */
+    wait?: StartPageWait;
+}
+/** The replay result, with how long replay waited for its start page when that went past the budget. */
+export declare function withStartPageWait<R extends FlowReplayResult>(result: R, arrival: StartPathArrival): R;
+/**
+ * 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 declare function arriveAtStartPath(sessions: SessionManager, session: StartPathSession & {
+    id: string;
+    command(name: string, args?: Record<string, unknown>): Promise<CommandResult>;
+}, flow: FlowFile, timeoutMs?: number, clock?: ArrivalClock, 
+/** Whether the tab is still loading. Replay passes one for a pool lease, the only tab it can ask. */
+stillLoading?: () => Promise<boolean>, loadingCapMs?: number): Promise<StartPathArrival>;
+/**
+ * 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.
+ */
+/**
+ * How a navigate ended: target, redirect, refusal (untouched tab), or no successor. `wait` is set
+ * when the page's loading earned it time past the budget.
+ */
+export type NavigateOutcome = {
+    kind: 'arrived';
+    session: Session;
+    wait?: StartPageWait;
+} | {
+    kind: 'redirected';
+    session: Session;
+    wait?: StartPageWait;
+} | {
+    kind: 'refused';
+} | {
+    kind: 'lost';
+    waitedMs: number;
+    stillLoading: boolean;
+    wait?: StartPageWait;
+};
+export declare function navigateAndAwait(sessions: SessionManager, session: {
+    id: string;
+    /** Optional because a session's URL is, and `carryReticleIdentity` already handles its absence. */
+    url?: string;
+    command(name: string, args?: Record<string, unknown>): Promise<CommandResult>;
+}, destination: string, expectedPath: string, timeoutMs: number, clock?: ArrivalClock, 
+/** True when the destination is the page we are already on — see `arrivedSuccessor`. */
+isReload?: boolean, 
+/** Whether the navigated page is still loading; absent when it cannot be asked. */
+stillLoading?: () => Promise<boolean>, loadingCapMs?: number): Promise<NavigateOutcome>;
+export {};

package/dist/language/flows/flow-start-path.js

@@ -0,0 +1,313 @@
+/**
+ * Replay's arrival at a flow's start page: navigate (or reload) before step 1, wait for the session
+ * the SDK reconnects as, and say what happened when it does not.
+ */
+import { EventType, ReticleCommand, } from '@reticlehq/core';
+import { establishedState, samePath, startPathBudgetMs } from './flow-journey.js';
+import { asRecord } from '@reticlehq/core';
+import { navigablePath, routeOfEvent, routeOfUrl, } from '@reticlehq/engine/question/predicate/predicate-route.js';
+import { carryReticleIdentity } from '../../surface/tools/lease-tools.js';
+import { anchorPrecondition, anchorQueryArgs } from './flow-step-runners.js';
+import { queryRefs } from './replay.js';
+import { isDocumentGoneError } from '../../portal/session/facts/session-replaced.js';
+/**
+ * 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);
+}
+/**
+ * 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 often replay looks for the SDK on the start page; how long is `startPathBudgetMs`. */
+const START_PATH_POLL_MS = 100;
+/**
+ * How long replay keeps waiting past the step budget while the page says it is still loading
+ * (#1705). The bound keeps a page that never finishes from holding the replay forever.
+ */
+const START_PATH_LOADING_CAP_MS = 30_000;
+/** A probe that fails counts as loaded, so it can only end the wait, never stretch it. */
+async function pageStillLoading(probe) {
+    try {
+        return true === (await probe());
+    }
+    catch {
+        return false;
+    }
+}
+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;
+    }
+}
+/** The replay result, with how long replay waited for its start page when that went past the budget. */
+export function withStartPageWait(result, arrival) {
+    return arrival.wait === undefined ? result : { ...result, startPageWait: arrival.wait };
+}
+/** The `wait` an outcome carries, ready to spread into an arrival. */
+function waitOf(outcome) {
+    return outcome.wait === undefined ? {} : { wait: outcome.wait };
+}
+/**
+ * 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 = startPathBudgetMs(flow), clock = REAL_ARRIVAL_CLOCK, 
+/** Whether the tab is still loading. Replay passes one for a pool lease, the only tab it can ask. */
+stillLoading, loadingCapMs = START_PATH_LOADING_CAP_MS) {
+    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, stillLoading, loadingCapMs);
+    if ('lost' === outcome.kind) {
+        const why = outcome.stillLoading
+            ? 'The page was still loading when replay stopped waiting: check that the app finishes loading, then replay'
+            : 'A slow or backgrounded tab can take longer to come back: bring it to the front and replay';
+        return {
+            lost: `replay ${here ? 'reloaded' : 'navigated to'} ${target} before step 1 and no page was connected ` +
+                `after ${String(outcome.waitedMs)}ms, so the session it was driving is gone and nothing ran. ${why}`,
+            ...waitOf(outcome),
+        };
+    }
+    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`,
+            ...waitOf(outcome),
+        };
+    }
+    const arrived = outcome.session;
+    if (!resolvedBefore || (await firstStepResolvesHere(arrived, flow))) {
+        return { session: arrived, ...waitOf(outcome) };
+    }
+    return {
+        session: arrived,
+        resetCost: resetCostHint(flow, target),
+        ...waitOf(outcome),
+    };
+}
+/**
+ * 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, clock = REAL_ARRIVAL_CLOCK, 
+/** True when the destination is the page we are already on — see `arrivedSuccessor`. */
+isReload = false, 
+/** Whether the navigated page is still loading; absent when it cannot be asked. */
+stillLoading, loadingCapMs = START_PATH_LOADING_CAP_MS) {
+    // 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 start = clock.now();
+    const deadline = start + timeoutMs;
+    const cap = start + Math.max(timeoutMs, loadingCapMs);
+    let loading = false;
+    let extended = false;
+    const extendedWait = () => extended
+        ? { wait: { waitedMs: clock.now() - start, budgetMs: timeoutMs, stillLoading: loading } }
+        : {};
+    for (;;) {
+        const arrived = arrivedSuccessor(sessions, session.id, expectedPath, session, isReload);
+        if (true === arrived?.matches) {
+            return { kind: 'arrived', session: arrived.session, ...extendedWait() };
+        }
+        if (clock.now() >= deadline) {
+            // A live redirect is a different result from no SDK reconnection at all.
+            if (arrived !== undefined) {
+                return { kind: 'redirected', session: arrived.session, ...extendedWait() };
+            }
+            // Past the budget, only a page that says it is still loading earns more time (#1705).
+            loading = stillLoading !== undefined && (await pageStillLoading(stillLoading));
+            extended ||= loading;
+            if (!loading || clock.now() >= cap) {
+                return {
+                    kind: 'lost',
+                    waitedMs: clock.now() - start,
+                    stillLoading: loading,
+                    ...extendedWait(),
+                };
+            }
+        }
+        await clock.sleep(START_PATH_POLL_MS);
+    }
+}

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

@@ -1,25 +1,4 @@
-import { type FlowReplayResult } from '@reticlehq/core';
-import type { ToolDef, ToolDeps } from '../../surface/tools/tool-kit.js';
+import type { ToolDef } from '../../surface/tools/tool-kit.js';
 export { replayNamedFlow } from './flow-replay-run.js';
-/**
- * The URL a leased context should open: the app's ORIGIN, not the live tab's current location.
- *
- * The live tab drifts — every replay navigates it — so using its full URL made each lease start wherever
- * the previous run happened to finish (observed: leases opening /deployments and failing to find the
- * login control that only exists at the root). A lease must be a FRESH visit to a deterministic entry
- * point; flows that need another page carry their own startPath.
- */
-export declare function leasableAppUrl(deps: ToolDeps, sessionId: string | undefined): string | undefined;
-/**
- * The live session's own URL — what the fixture port must be looked up by.
- *
- * NOT `leasableAppUrl`. That returns an ORIGIN, and the input provider finds a page by comparing
- * full URLs, so an origin matched no page: `suiteFixtureSeed` answered `undefined` on every run and
- * every leased flow booted cold while the code read as if it were seeded. Silent, because every
- * refusal on that path is deliberately silent — a fixture is an optimisation, and a suite must not
- * die when one is unavailable.
- */
-export declare function sessionUrlOf(deps: ToolDeps, sessionId: string | undefined): string | undefined;
-/** A flow whose leased context never came up is a suite ERROR, never a silent pass. */
-export declare function leaseFailureReplay(name: string, error: string | undefined): FlowReplayResult;
+export { leasableAppUrl, leaseFailureReplay, sessionUrlOf } from './flow-lease.js';
 export declare const FLOW_TOOLS: ToolDef[];

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

@@ -9,9 +9,9 @@ import { emptyFlowRefusal } from './empty-flow.js';
 import { aliasParam, aliasUsed } from '../../surface/tools/args/alias-args.js';
 import { stillRecording, stillRecordingMessage } from './flow-result.js';
 import { resolveAnnotateTarget } from './annotate-notes/annotate-target.js';
-import { FlowErrorCode, RecordedSaveError, ReplayStatus, SuiteIsolation, } from '@reticlehq/core';
+import { FlowErrorCode, RecordedSaveError, SuiteIsolation, } from '@reticlehq/core';
 import { recordSuiteFlakes } from './suite/suite-flakes.js';
-import { AppRuntime, ReticleTool } from '@reticlehq/core';
+import { ReticleTool } from '@reticlehq/core';
 import { asNumber, asString } from '@reticlehq/core';
 import { log } from '../../log.js';
 import { cloudFetch, syncFlowToCloud, SyncOutcome } from '../../memory/cloud/cloud-sync.js';
@@ -38,6 +38,8 @@ import { RESULT_FIELD, resultField, suiteResult } from '../../surface/tools/reti
 import { replayOneFlow } from './single-replay.js';
 export { replayNamedFlow } from './flow-replay-run.js';
 import { replayAndLearn } from './flow-learning.js';
+import { leasableAppUrl, leaseFailureReplay, sessionUrlOf } from './flow-lease.js';
+export { leasableAppUrl, leaseFailureReplay, sessionUrlOf } from './flow-lease.js';
 /**
  * Best-effort mirror of a just-saved flow to Reticle (only when logged in — both cloud env vars
  * set). Fire-and-forget: resolves the config, POSTs via the platform fetch, and logs the outcome. Any
@@ -49,8 +51,9 @@ async function syncSavedFlowToCloud(deps, flow, target) {
     // `flowsForSession`, and reading the credential from a different tree is how one project's work
     // reaches another project's dashboard.
     const cloud = await resolveProjectCloud(deps.fs, rootForTarget(deps, target), homedir(), process.env);
-    if (null === cloud.config || !cloud.policy.flows)
-        return; // not attached / flows disabled → local only
+    if (null === cloud.config || !cloud.policy.flows) {
+        return;
+    } // not attached / flows disabled → local only
     const result = await syncFlowToCloud(flow, cloud.config, target.projectId, cloudFetch);
     if (result.outcome !== SyncOutcome.SYNCED) {
         log('cloud-flow-sync-failed', { flow: flow.name, status: result.status, error: result.error });
@@ -58,57 +61,6 @@ async function syncSavedFlowToCloud(deps, flow, target) {
 }
 /** A step index no recorded flow reaches; bounds `to` and `at`. */
 const MAX_REPLAY_STEP = 10_000;
-/**
- * The URL a leased context should open: the app's ORIGIN, not the live tab's current location.
- *
- * The live tab drifts — every replay navigates it — so using its full URL made each lease start wherever
- * the previous run happened to finish (observed: leases opening /deployments and failing to find the
- * login control that only exists at the root). A lease must be a FRESH visit to a deterministic entry
- * point; flows that need another page carry their own startPath.
- */
-export function leasableAppUrl(deps, sessionId) {
-    try {
-        const session = deps.sessions.resolve(sessionId);
-        if (AppRuntime.WEB !== (session.runtime ?? AppRuntime.WEB))
-            return undefined; // desktop: no IPC in a lease
-        const url = session.url;
-        if (typeof url !== 'string' || 0 === url.length)
-            return undefined;
-        return new URL(url).origin;
-    }
-    catch {
-        return undefined; // no live session (or an unparseable URL) → sequential path
-    }
-}
-/**
- * The live session's own URL — what the fixture port must be looked up by.
- *
- * NOT `leasableAppUrl`. That returns an ORIGIN, and the input provider finds a page by comparing
- * full URLs, so an origin matched no page: `suiteFixtureSeed` answered `undefined` on every run and
- * every leased flow booted cold while the code read as if it were seeded. Silent, because every
- * refusal on that path is deliberately silent — a fixture is an optimisation, and a suite must not
- * die when one is unavailable.
- */
-export function sessionUrlOf(deps, sessionId) {
-    try {
-        return deps.sessions.resolve(sessionId).url;
-    }
-    catch {
-        return undefined;
-    }
-}
-/** A flow whose leased context never came up is a suite ERROR, never a silent pass. */
-export function leaseFailureReplay(name, error) {
-    return {
-        name,
-        status: ReplayStatus.ERROR,
-        steps: [],
-        error: {
-            code: ReplayStatus.ERROR,
-            message: `could not run in a leased context: ${error ?? 'unknown error'}`,
-        },
-    };
-}
 /** Stand-in path for a flow whose name fails the path-segment guard — never a real join. */
 const INVALID_FLOW_NAME_PATH = '(invalid flow name — not a usable path)';
 /**
@@ -247,8 +199,9 @@ export const FLOW_TOOLS = [
             // A zero-step recording is not a flow. Saving it wrote a file the suite reports "unverifiable"
             // forever while telling the agent it had saved a regression test — see empty-flow.
             const emptyRefusal = emptyFlowRefusal(program.steps.length, name);
-            if (emptyRefusal !== undefined)
+            if (emptyRefusal !== undefined) {
                 return Promise.resolve(emptyRefusal);
+            }
             const { flows, root } = flowsForSession(deps, target);
             const author = flowAuthor();
             const toSave = {
@@ -257,8 +210,9 @@ export const FLOW_TOOLS = [
                 ...(author === undefined ? {} : { author }),
             };
             return flows.save(toSave, annotations, projectId).then(async (res) => {
-                if (!res.ok)
+                if (!res.ok) {
                     return { error: flowErrorMessage(res.code, res.detail), code: res.code };
+                }
                 deps.annotations.clear(name);
                 // Grade the saved flow's assertions so the agent learns immediately if it just saved a flow
                 // that asserts nothing observable (passes even when the feature is broken).
@@ -350,8 +304,9 @@ export const FLOW_TOOLS = [
             return flows
                 .load(asString(aliasParam(args, 'flowName', ['flow'])['flowName']) ?? '', projectId)
                 .then((res) => {
-                if (!res.ok)
+                if (!res.ok) {
                     return { error: flowErrorMessage(res.code, res.detail), code: res.code };
+                }
                 const { name, ...rest } = res.value;
                 return { flowName: name, ...rest };
             });
@@ -382,8 +337,9 @@ export const FLOW_TOOLS = [
             return flows
                 .remove(asString(aliasParam(args, 'flowName', ['flow'])['flowName']) ?? '', projectId)
                 .then((res) => {
-                if (!res.ok)
+                if (!res.ok) {
                     return { error: flowErrorMessage(res.code, res.detail), code: res.code };
+                }
                 return { deleted: true };
             });
         },
@@ -399,7 +355,8 @@ export const FLOW_TOOLS = [
             'document) — neither pass nor fail, treat as UNKNOWN. ' +
             'An ok replay of a flow asserting no consequence also carries unverifiable:{reason} — do not ' +
             'treat as proof. ' +
-            'Early halt carries halted:{atStep, notAttempted}: `steps` is shorter because replay stopped.',
+            'Early halt carries halted:{atStep, notAttempted}: `steps` is shorter because replay stopped. ' +
+            'A start page that kept loading past the step budget carries startPageWait:{waitedMs, budgetMs, stillLoading}.',
         inputSchema: {
             flow: FLOW_NAME_ALIAS,
             flowName: z
@@ -461,6 +418,11 @@ export const FLOW_TOOLS = [
                 .object({ atStep: z.number(), notAttempted: z.number() })
                 .optional()
                 .describe('Set when the replay STOPPED at a failing step: `steps` is shorter than the flow, and this says where it stopped and how many steps were never attempted. Absent means every step ran.'),
+            // Declared for the same reason as `halted`: an undeclared field is stripped.
+            startPageWait: z
+                .object({ waitedMs: z.number(), budgetMs: z.number(), stillLoading: z.boolean() })
+                .optional()
+                .describe('Set when replay waited past the step budget because the start page was still loading. stillLoading is what the tab said the last time replay asked. Absent means the wait stayed inside the budget.'),
             // Declared here or a validating profile strips it -- the same way `name` was stripped once.
             // A field the handler sets and the schema omits arrives as nothing, silently.
             /*
@@ -602,8 +564,9 @@ export const FLOW_TOOLS = [
             // verify:server — hand the whole suite to the hosted runner; it records the verification itself.
             const cloud = await resolveProjectCloud(deps.fs, rootForTarget(deps, target), homedir(), process.env);
             const server = await runServerVerify(deps, cloud, sessionId, requested);
-            if (server !== null)
+            if (server !== null) {
                 return server;
+            }
             // PARALLEL: flows race the DOM only when they share ONE tab. Given the lease pool, each
             // flow gets its own isolated context, so a large suite finishes in interactive time. Opt-in via
             // `parallel`; a missing prerequisite (no pool, unknown app URL) falls back to the sequential path
@@ -774,15 +737,17 @@ export const FLOW_TOOLS = [
             // The store stamps the project into the file AND routes it to the per-project subdir (a shared
             // daemon serves many apps), so location and content agree from one source of truth.
             const emptyRecorded = emptyFlowRefusal(flow.steps.length, flow.name);
-            if (emptyRecorded !== undefined)
+            if (emptyRecorded !== undefined) {
                 return emptyRecorded;
+            }
             // Resolved like every other path now. This save used to go to the daemon's root while the
             // recorded-flow save resolved per session, so where a flow landed depended on which tool wrote
             // it — and the pair that disagreed were the two ways to save the same thing.
             const target = { projectId: session.projectId, origin: originOf(session.url) };
             const res = await flowsForSession(deps, target).flows.saveFlow(flow, session.projectId);
-            if (!res.ok)
+            if (!res.ok) {
                 return { error: flowErrorMessage(res.code, res.detail), code: res.code };
+            }
             // If logged in to Reticle, mirror the saved flow to the team's regression suite. Best-effort
             // and non-blocking: the flow is already on disk, so a sync failure never fails the save.
             void syncSavedFlowToCloud(deps, flow, target);
@@ -841,16 +806,19 @@ async function loadInvoked(flows, flow, projectId) {
     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 flows.load(name, projectId);
-            if (!sub.ok || sub.value === undefined)
+            if (!sub.ok || sub.value === undefined) {
                 continue;
+            }
             out.set(name, sub.value);
             queue.push(sub.value);
         }