@reticlehq/server 3.1.0 → 3.3.0

package/dist/language/flows/annotate-notes/annotate.js

@@ -1,4 +1,4 @@
-import { AnnotationErrorCode, AnnotationKind, AnnotationTarget, COMPILED_PREDICATE_PREFIX, flowExpectHasConsequence, flowExpectIsPresenceOnly, } from '@reticlehq/core';
+import { AnnotationErrorCode, AnnotationKind, AnnotationTarget, COMPILED_PREDICATE_PREFIX, flowExpectHasConsequence, flowExpectIsPresenceOnly, PredicateKind, } from '@reticlehq/core';
 /**
  * The PURE compiler at the heart of the annotation facet. A structured annotation +
  * the current captured-step count → an AnnotateOutcome (a result envelope + the patch to apply to
@@ -14,35 +14,71 @@ import { AnnotationErrorCode, AnnotationKind, AnnotationTarget, COMPILED_PREDICA
  * compilation is explicitly FUTURE — an NL string never reaches here (AnnotationSchema
  * rejects it upstream; the tool maps that to UNKNOWN_KIND). No NL parser exists or is faked.
  */
+/**
+ * A network annotation as a predicate, `count` included.
+ *
+ * Written once because it is compiled on two paths — a step gate and a flow's success oracle — and
+ * the first version of this migration wrote it twice and dropped `count` from both. The schema's own
+ * comment says why that matters: presence says the request fired, cardinality catches the
+ * double-submit that fired it twice, and `count` is the point of the annotation.
+ *
+ * A counted assertion also gates on `settled`. A wait-until-true evaluator satisfies `count: 1` the
+ * instant the FIRST request lands, which is before a duplicate arrives — so without the gate the
+ * guard passes on exactly the bug it exists to catch.
+ */
+function netPredicate(net) {
+    const clause = {
+        kind: PredicateKind.NET,
+    };
+    if (net.method !== undefined)
+        clause.method = net.method;
+    if (net.urlContains !== undefined)
+        clause.urlContains = net.urlContains;
+    if (net.status !== undefined)
+        clause.status = net.status;
+    if (net.count === undefined)
+        return clause;
+    clause.count = net.count;
+    return { kind: PredicateKind.ALL_OF, predicates: [{ kind: PredicateKind.SETTLED }, clause] };
+}
 export function compileAnnotation(a, stepCount) {
     switch (a.kind) {
         case AnnotationKind.ASSERT_SIGNAL: {
             if (0 === stepCount)
                 return noStep();
-            const expect = { signal: a.name };
+            const signal = {
+                kind: PredicateKind.SIGNAL,
+                name: a.name,
+            };
             if (a.dataMatches !== undefined)
-                expect.signalData = a.dataMatches;
-            return stepPatch(a, stepCount, expect);
+                signal.dataMatches = a.dataMatches;
+            return stepPatch(a, stepCount, signal);
         }
         case AnnotationKind.ASSERT_VISIBLE: {
             if (0 === stepCount)
                 return noStep();
-            return stepPatch(a, stepCount, { element: { testid: a.testid } });
+            return stepPatch(a, stepCount, {
+                kind: PredicateKind.ELEMENT,
+                query: { testid: a.testid },
+            });
         }
         case AnnotationKind.ASSERT_STATE: {
             if (0 === stepCount)
                 return noStep();
-            const state = { path: a.statePath };
+            const state = {
+                kind: PredicateKind.STATE,
+                path: a.statePath,
+            };
             if (a.store !== undefined)
                 state.store = a.store;
             if (a.equals !== undefined)
                 state.equals = a.equals;
-            return stepPatch(a, stepCount, { state });
+            return stepPatch(a, stepCount, state);
         }
         case AnnotationKind.ASSERT_NET: {
             if (0 === stepCount)
                 return noStep();
-            return stepPatch(a, stepCount, { net: a.net });
+            return stepPatch(a, stepCount, netPredicate(a.net));
         }
         case AnnotationKind.MARK_DYNAMIC:
             return {
@@ -53,39 +89,51 @@ export function compileAnnotation(a, stepCount) {
             // Precedence: signal > state > net > console > testid (a consequence end-condition beats a
             // presence check). None of them → MISSING_FIELD.
             if (a.signal !== undefined) {
-                return flowSuccess(a, { signal: a.signal });
+                return flowSuccess(a, { kind: PredicateKind.SIGNAL, name: a.signal });
             }
             if (a.statePath !== undefined) {
-                const state = { path: a.statePath };
+                const state = {
+                    kind: PredicateKind.STATE,
+                    path: a.statePath,
+                };
                 if (a.store !== undefined)
                     state.store = a.store;
                 if (a.equals !== undefined)
                     state.equals = a.equals;
-                if (a.hold !== undefined)
-                    state.hold = a.hold;
-                return flowSuccess(a, { state });
+                // `hold` was a v1 flag meaning "this must STILL be true after the page settles". A predicate
+                // says that by composing: the settle gate is a clause, not a boolean on another clause.
+                return flowSuccess(a, true === a.hold
+                    ? { kind: PredicateKind.ALL_OF, predicates: [{ kind: PredicateKind.SETTLED }, state] }
+                    : state);
             }
             if (a.net !== undefined) {
-                return flowSuccess(a, { net: a.net });
+                return flowSuccess(a, netPredicate(a.net));
             }
             if (a.console !== undefined) {
-                return flowSuccess(a, { console: a.console });
+                return flowSuccess(a, {
+                    kind: PredicateKind.CONSOLE,
+                    ...(a.console.level === undefined ? {} : { level: a.console.level }),
+                    ...(a.console.absent === undefined ? {} : { absent: a.console.absent }),
+                });
             }
             if (a.testid !== undefined) {
-                return flowSuccess(a, { element: { testid: a.testid } });
+                return flowSuccess(a, { kind: PredicateKind.ELEMENT, query: { testid: a.testid } });
             }
             // Last, and above only MISSING_FIELD. An element is a locator and text is content; where a
             // caller offered both, the locator is the more stable anchor. But text beats nothing at all,
             // which is what an app whose only observable is a rendered value used to get (#811).
             if (a.text !== undefined) {
-                const text = { contains: a.text.contains };
+                const text = {
+                    kind: PredicateKind.TEXT,
+                    contains: a.text.contains,
+                };
                 if (a.text.scope !== undefined)
                     text.scope = a.text.scope;
                 if (a.text.absent !== undefined)
                     text.absent = a.text.absent;
                 if (a.text.visible !== undefined)
                     text.visible = a.text.visible;
-                return flowSuccess(a, { text });
+                return flowSuccess(a, text);
             }
             return { result: { ok: false, code: AnnotationErrorCode.MISSING_FIELD } };
         }

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

@@ -28,6 +28,18 @@ export declare function nearestTestid(missing: string, present: string[]): strin
 export declare function nearestIsAmbiguous(missing: string, present: string[]): boolean;
 /** Build the legible-drift record for a testid anchor that resolved to zero live elements. */
 export declare function testidDrift(value: string, hint: QueryEmptyHint | undefined): Drift;
+/**
+ * Build the drift for a step whose anchor matched MORE THAN ONE live element.
+ *
+ * `ambiguous: true` is set because that is exactly what it is, and it is the field heal already
+ * reads to refuse an auto-rebind -- an ambiguous drift must never be healed to an arbitrary pick,
+ * which is the same reasoning that made this a drift instead of a note in the first place.
+ *
+ * `nearest` is null on purpose. There is no nearest: the anchor was found, several times over, and
+ * proposing one of the matches as "the" match would re-make the guess this reason exists to stop.
+ * The fix is a NARROWER anchor, and only a human or an agent looking at the page can choose it.
+ */
+export declare function ambiguousAnchorDrift(value: string, matches: number): Drift;
 /**
  * Build the drift for a step whose `expect.element` testid was absent after the action ran.
  *

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

@@ -139,6 +139,26 @@ export function testidDrift(value, hint) {
         drift.ambiguous = true;
     return drift;
 }
+/**
+ * Build the drift for a step whose anchor matched MORE THAN ONE live element.
+ *
+ * `ambiguous: true` is set because that is exactly what it is, and it is the field heal already
+ * reads to refuse an auto-rebind -- an ambiguous drift must never be healed to an arbitrary pick,
+ * which is the same reasoning that made this a drift instead of a note in the first place.
+ *
+ * `nearest` is null on purpose. There is no nearest: the anchor was found, several times over, and
+ * proposing one of the matches as "the" match would re-make the guess this reason exists to stop.
+ * The fix is a NARROWER anchor, and only a human or an agent looking at the page can choose it.
+ */
+export function ambiguousAnchorDrift(value, matches) {
+    return {
+        reasonKind: DriftReason.ANCHOR_AMBIGUOUS,
+        reason: `testid "${value}" matched ${String(matches)} live elements — which one the recording meant is not decidable; anchor this step to something unique`,
+        anchor: value,
+        nearest: null,
+        ambiguous: true,
+    };
+}
 /**
  * Build the drift for a step whose `expect.element` testid was absent after the action ran.
  *

package/dist/language/flows/flow-expect-grammar.d.ts

@@ -18,9 +18,8 @@ export declare const FlowParseNote: {
     readonly NOT_JSON: "flow file is not valid JSON — fix the syntax or regenerate it with reticle_flow_save";
     readonly MALFORMED: "flow file is malformed — fix or regenerate it with reticle_flow_save";
     readonly UNSUPPORTED_SHAPE: "valid JSON, unsupported expect shape";
-    readonly UNENFORCED: "valid JSON, but this expect uses a predicate kind a saved flow cannot enforce (settled, route, animation, anyOf, not)";
 };
-export type CoerceExpectResult = {
+type CoerceExpectResult = {
     ok: true;
     value: unknown;
 } | {
@@ -31,3 +30,4 @@ export declare function coerceFlowExpect(raw: unknown): CoerceExpectResult;
 export declare function coerceFlowFileExpects(raw: unknown): CoerceExpectResult;
 export declare function describeFlowZodFailure(error: ZodError): string;
 export declare function parseFlowFileText(text: string): FlowResult<FlowFile>;
+export {};

package/dist/language/flows/flow-expect-grammar.js

@@ -11,14 +11,11 @@
  * re-save writes the canonical shape. A kind a saved flow cannot enforce is refused, not stripped
  * to an empty expect that would grade asserted-while-unchecked.
  */
-import { FlowErrorCode, FlowFileSchema } from '@reticlehq/core';
-import { PredicateSchema } from '@reticlehq/engine/question/predicate/predicate.js';
-import { predicateToExpect } from '../../judgement/outcome/predicate-to-expect.js';
+import { FlowExpectSchema, FlowPredicateSchema, READABLE_FLOW_VERSIONS, FlowErrorCode, FlowFileSchema, } from '@reticlehq/core';
 export const FlowParseNote = {
     NOT_JSON: 'flow file is not valid JSON — fix the syntax or regenerate it with reticle_flow_save',
     MALFORMED: 'flow file is malformed — fix or regenerate it with reticle_flow_save',
     UNSUPPORTED_SHAPE: 'valid JSON, unsupported expect shape',
-    UNENFORCED: 'valid JSON, but this expect uses a predicate kind a saved flow cannot enforce (settled, route, animation, anyOf, not)',
 };
 function isRecord(value) {
     return 'object' === typeof value && null !== value && !Array.isArray(value);
@@ -43,20 +40,44 @@ function flattenSignalObject(raw) {
 }
 export function coerceFlowExpect(raw) {
     if (isRecord(raw) && 'kind' in raw) {
-        const parsed = PredicateSchema.safeParse(raw);
+        const parsed = FlowPredicateSchema.safeParse(raw);
         if (!parsed.success) {
             return { ok: false, detail: describePredicateExpectFailure(parsed.error) };
         }
-        const expect = predicateToExpect(parsed.data);
-        if (undefined === expect)
-            return { ok: false, detail: FlowParseNote.UNENFORCED };
-        return { ok: true, value: expect };
+        // Kept AS the predicate. There is nothing to convert to any more, so nothing to refuse for
+        // being inexpressible — the shape an agent wrote is the shape the file holds.
+        return { ok: true, value: parsed.data };
     }
     if (!isRecord(raw))
         return { ok: true, value: raw };
-    return { ok: true, value: flattenSignalObject(raw) };
+    const flattened = flattenSignalObject(raw);
+    /*
+     * A v1 expect is validated HERE so a misspelling is named.
+     *
+     * The schema accepts both formats as a union, and a union rejection reports every branch's
+     * complaint at once — so `{ signal: 'x', signl: 'typo' }` came back as "flow file is malformed"
+     * without the word `signl` in it. The file was still refused, which is the half that matters, but
+     * the reader was left to find a one-character typo by eye. Checking the v1 shape on its own, on
+     * the path that already knows this is a v1 expect, puts the key back in the message.
+     */
+    const asV1 = FlowExpectSchema.safeParse(flattened);
+    if (!asV1.success) {
+        return { ok: false, detail: describePredicateExpectFailure(asV1.error) };
+    }
+    return { ok: true, value: flattened };
 }
 function describePredicateExpectFailure(error) {
+    const refused = error.issues.find((one) => 'custom' === one.code);
+    if (refused !== undefined)
+        return `${FlowParseNote.UNSUPPORTED_SHAPE}: ${refused.message}`;
+    // An unrecognized key FIRST: a strict object reports it on the object's own path with the names
+    // in `keys`, so reading `path[0]` misses the one thing worth saying. A misspelling is the failure
+    // this whole check exists to catch, and naming it is the difference between a fix and a hunt.
+    const unknownKey = error.issues.find((one) => 'unrecognized_keys' === one.code);
+    if (unknownKey !== undefined && 'unrecognized_keys' === unknownKey.code) {
+        const named = unknownKey.keys.map((k) => `"${k}"`).join(', ');
+        return `${FlowParseNote.UNSUPPORTED_SHAPE} key ${named}`;
+    }
     const issue = error.issues[0];
     if (undefined === issue)
         return FlowParseNote.UNSUPPORTED_SHAPE;
@@ -102,8 +123,48 @@ export function coerceFlowFileExpects(raw) {
     }
     return { ok: true, value: next };
 }
+/**
+ * The issues a union rejection buries.
+ *
+ * `expect` accepts a predicate OR a v1 expect, and zod reports a union failure as one
+ * `invalid_union` issue whose branch errors live inside `unionErrors`. The one that matters is the
+ * v1 branch's `unrecognized_keys` — the misspelled field. Without this the file was still correctly
+ * REFUSED and the message said only "malformed", which sends the author back to hunt a
+ * one-character typo we had already identified.
+ */
+function flatten(issues) {
+    return issues.flatMap((issue) => 'invalid_union' === issue.code
+        ? [issue, ...flatten(issue.unionErrors.flatMap((e) => e.issues))]
+        : [issue]);
+}
 export function describeFlowZodFailure(error) {
-    const issue = error.issues[0];
+    const all = flatten(error.issues);
+    /*
+     * The most SPECIFIC complaint wins, wherever in the union it was reported.
+     *
+     * An unrecognized key names the typo. Failing that, an issue whose path reaches INTO an expect
+     * names the field that was the wrong type — `{ signal: { count: 1 } }`, a signal object with no
+     * name, is reported on `steps.0.expect.signal` and that path is the whole answer. The union's own
+     * top-level `invalid_union` says only "malformed", which is true and useless.
+     */
+    const named = (one) => {
+        // NOT the discriminator complaint. `invalid_union_discriminator` on `expect.kind` is the
+        // PREDICATE branch objecting that a v1 expect has no `kind` — which is true of every v1 expect
+        // ever written and tells the author nothing. The useful issue is the one from the branch they
+        // were actually writing.
+        if ('invalid_union_discriminator' === one.code)
+            return false;
+        return (('steps' === one.path[0] && 'expect' === one.path[2] && one.path.length > 3) ||
+            ('success' === one.path[0] && one.path.length > 1));
+    };
+    // A refinement carries its own reason (a session ref, named by field), and that reason IS the fix.
+    const refused = all.find((one) => 'custom' === one.code);
+    if (refused !== undefined && 'steps' === refused.path[0] && 'number' === typeof refused.path[1]) {
+        return `${FlowParseNote.UNSUPPORTED_SHAPE} at step ${String(refused.path[1])}: ${refused.message}`;
+    }
+    if (refused !== undefined)
+        return `${FlowParseNote.UNSUPPORTED_SHAPE}: ${refused.message}`;
+    const issue = all.find((one) => 'unrecognized_keys' === one.code) ?? all.find(named) ?? error.issues[0];
     if (undefined === issue)
         return FlowParseNote.MALFORMED;
     const path = issue.path;
@@ -139,6 +200,26 @@ export function parseFlowFileText(text) {
     catch {
         return { ok: false, code: FlowErrorCode.PARSE_FAILED, detail: FlowParseNote.NOT_JSON };
     }
+    /*
+     * Version BEFORE schema. When the format does not match, nothing else in the file can be trusted
+     * to mean what this reader thinks it means, so the first unrelated field that happens to fail
+     * would be noise about the wrong thing -- and `version` is a `z.literal`, so the schema's own
+     * complaint about it is indistinguishable from a typo.
+     *
+     * Only a NUMBER that is not ours counts. A missing or non-numeric `version` is a damaged field
+     * rather than a different format, and stays PARSE_FAILED.
+     */
+    const declared = isRecord(parsed) ? parsed['version'] : undefined;
+    if ('number' === typeof declared && !READABLE_FLOW_VERSIONS.has(declared)) {
+        return {
+            ok: false,
+            code: FlowErrorCode.WRONG_VERSION,
+            detail: `this flow file is version ${String(declared)} and this Reticle reads versions ` +
+                `${[...READABLE_FLOW_VERSIONS].join(' and ')}. The file is not damaged, the reader is the ` +
+                'wrong one. ' +
+                'Upgrade or downgrade Reticle rather than editing the flow.',
+        };
+    }
     const coerced = coerceFlowFileExpects(parsed);
     if (!coerced.ok) {
         return { ok: false, code: FlowErrorCode.PARSE_FAILED, detail: coerced.detail };

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

@@ -6,7 +6,7 @@ import { classifyFlowAssertions } from './flow-classify.js';
  *
  * A replay used to report only in the language of the DOM: step 3 drifted, this assertion failed.
  * True, actionable, and illegible — the reader still had to reconstruct what stopped working. The
- * ledger in `.reticle/intent.json` already holds the other half (prose statements, declared → bound
+ * ledger in `.reticle/intent/` already holds the other half (prose statements, declared → bound
  * → proved, and the verdict that discharged each one), so a flow does not need its own notion of
  * intent. It needs an id.
  *

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

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

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

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

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

@@ -2,6 +2,7 @@ import { FlowErrorCode, type CommandResult, type FlowFile, type FlowReplayResult
 import type { ArrivalClock } from '../../surface/tools/act/navigation/navigate-arrival.js';
 import type { SessionManager } from '../../portal/session/session-manager.js';
 import type { Session } from '../../portal/session/session.js';
+import { DocumentLostDuringReplay, type FlowReplaySession } from './flow-replay.js';
 import type { ToolDeps } from '../../surface/tools/tool-kit.js';
 export declare function latestRecordedFlow(events: ReticleEvent[]): {
     name: string;
@@ -24,21 +25,39 @@ interface StartPathSession {
  * navigation was refused or the SDK never reconnected in the window.
  */
 export declare function startPathMismatchHint(flow: FlowFile, session: StartPathSession): string | undefined;
+/** What replay learned on its way to step 0. Both fields absent = the tab was left exactly as it was. */
+export interface StartPathArrival {
+    /** The successor session replay must continue on. Absent when nothing was navigated, or arrival timed out. */
+    session?: Session;
+    /** Set when the RESET itself is why step 1 cannot start — the reason a step-1 red is not drift. */
+    resetCost?: string;
+}
 /**
- * Replay's half of the FlowFile contract: navigate to the flow's `startPath` before step 1.
+ * Replay's half of the FlowFile contract: put the tab on the flow's `startPath` before step 1, and
+ * RELOAD it if it is already there.
+ *
+ * The reload is the state contract. Replaying "add a task" twice against a tab nobody reset gives
+ * the second run a world the recording never saw, and its assertions then describe the first run
+ * rather than the app. Our own `replay-determinism.mjs` has always refreshed before every run — the
+ * determinism we measured was never the determinism a user got.
+ *
+ * `requires` is the declared opt-out, and its first caller. A flow that says it starts from state
+ * another flow established is the one flow a page load would destroy, so it is never reset — here
+ * or from the wrong page. Silence is not an opt-out: a flow that depends on leftovers without
+ * saying so is a flow whose green means nothing on a fresh machine, and CI is a fresh machine.
  *
  * A full-page load tears down the session socket, so the navigation must happen here — before any
  * step runs — and the replay continues on the session the SDK reconnects as (found via the same
  * tombstone rebind that lets `resolve(oldId)` answer after any navigation). Best-effort by design:
- * when the flow carries no startPath, the tab is already there, the current route is unobservable,
- * the navigation is refused, or the SDK never reconnects in the window, it returns undefined and
- * replay proceeds on the connected session as before — with startPathMismatchHint turning any
- * resulting drift into an actionable next move rather than a mystifying one.
+ * when the flow carries no startPath, the current route is unobservable, the navigation is refused,
+ * or the SDK never reconnects in the window, replay proceeds on the connected session as before —
+ * with startPathMismatchHint turning any resulting drift into an actionable next move rather than a
+ * mystifying one.
  */
 export declare function arriveAtStartPath(sessions: SessionManager, session: StartPathSession & {
     id: string;
     command(name: string, args?: Record<string, unknown>): Promise<CommandResult>;
-}, flow: FlowFile, timeoutMs?: number, clock?: ArrivalClock): Promise<Session | undefined>;
+}, flow: FlowFile, timeoutMs?: number, clock?: ArrivalClock): Promise<StartPathArrival>;
 /**
  * Send a tab somewhere and wait for the session that comes back.
  *
@@ -56,13 +75,39 @@ export declare function navigateAndAwait(sessions: SessionManager, session: {
     /** Optional because a session's URL is, and `carryReticleIdentity` already handles its absence. */
     url?: string;
     command(name: string, args?: Record<string, unknown>): Promise<CommandResult>;
-}, destination: string, expectedPath: string, timeoutMs?: number, clock?: ArrivalClock): Promise<Session | undefined>;
-export declare function replayNamedFlow(deps: ToolDeps, args: Record<string, unknown>): Promise<FlowReplayResult>;
+}, destination: string, expectedPath: string, timeoutMs?: number, clock?: ArrivalClock, 
+/** True when the destination is the page we are already on — see `arrivedSuccessor`. */
+isReload?: boolean): Promise<Session | undefined>;
+/**
+ * The honest answer when the document replay was driving went away mid-run.
+ *
+ * Not a pass: nothing graded the journey, and the steps in hand are only the ones the departed
+ * document answered. Not a failure either — the app was never observed doing anything wrong, and
+ * reporting one would be the false red that sends a reader into product code that is fine. So it
+ * lands in the bucket this engine already has for "nothing was proved", the same one an unmet
+ * precondition uses, with the steps that DID answer attached and no row invented for the one that
+ * did not.
+ *
+ * Why replay reports rather than follows: the successor cannot be identified at the moment the
+ * socket closes. `SessionManager.remove` runs from the close handler, writes the tombstone a
+ * successor is later matched against, and has nothing to match yet — so the rejection is a plain
+ * transport failure by design, and a step in the middle of a journey has no budget to sit and poll
+ * with. `navigateAndAwait` CAN wait, because it knows it asked for the navigation, and it does.
+ */
+export declare function lostDocumentResult(name: string, lost: DocumentLostDuringReplay): FlowReplayResult;
+export declare function replayNamedFlow(deps: ToolDeps, args: Record<string, unknown>, 
+/** 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
  * documented to work headless), so a missing/unknown session degrades to the global/legacy store.
+ *
+ * Re-exported, not re-implemented. This file carried a BYTE-IDENTICAL second copy, and the two
+ * drifted the moment `ProjectId` was threaded: `session-root`'s copy returned the brand while this
+ * one returned `string`, so every flow tool importing from here was handed a widened value and lost
+ * the brand one line after it was minted. Exactly the weak-annotation failure the brand's own doc
+ * records against `RunStore.list()`.
  */
-export declare function sessionProjectId(deps: ToolDeps, sessionId: string | undefined): string | undefined;
-export {};
+export { sessionProjectId } from '../../memory/project/session-root.js';