@reticlehq/server 2.11.0 → 2.13.0

package/dist/flows/flow-intent.js

@@ -0,0 +1,123 @@
+import { InstrumentationGapKind, instrumentationGap, } from '@reticlehq/core';
+import { IntentStore } from '../intent/intent-store.js';
+import { classifyFlowAssertions } from './flow-classify.js';
+/**
+ * The link between a saved flow and the intent ledger — what the flow is FOR.
+ *
+ * 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
+ * → proved, and the verdict that discharged each one), so a flow does not need its own notion of
+ * intent. It needs an id.
+ *
+ * Nothing here derives an intent from step names. A flow that declares none reports that it declares
+ * none — a guessed intent puts words in the product owner's mouth and an agent will act on them,
+ * which is strictly worse than the honest absence.
+ */
+/** Namespaced so a flow-declared intent never collides with one an agent declared by hand. */
+const FLOW_INTENT_ID_PREFIX = 'flow:';
+const FLOW_VERDICT_ID_PREFIX = 'flow_replay:';
+const ID_SEPARATOR = ':';
+/** The ledger id a flow's own prose goal is declared under. */
+export function flowIntentId(flowName) {
+    return `${FLOW_INTENT_ID_PREFIX}${flowName}`;
+}
+/** The verdict that a replay of this flow, at this time, constitutes — what `provenBy` records. */
+export function flowReplayVerdictId(flowName, at) {
+    return `${FLOW_VERDICT_ID_PREFIX}${flowName}${ID_SEPARATOR}${String(at)}`;
+}
+/**
+ * Which ledger row this flow answers to, or nothing.
+ *
+ * An explicit `intentId` wins, so a flow can discharge an intent that was declared before it existed.
+ * Otherwise the flow's own prose implies one. A flow with neither has no intent, and says so.
+ */
+function intentIdOf(flow) {
+    if (flow.intentId !== undefined)
+        return flow.intentId;
+    // TRIMMED, not merely defined. `intent: "   "` satisfied `!== undefined` and silenced the gap, so
+    // a flow whose stated goal is whitespace looked identical on disk to one somebody thought about.
+    //
+    // The worse direction of the two: this gap is the ONLY thing that would ever tell anyone the flow
+    // has no goal, so suppressing it wrongly means the flow replays for months and the day it goes red
+    // the report names the broken step and nothing else — the precise failure it was written to
+    // prevent. Found by probing the seam rather than reading it.
+    return undefined === flow.intent || '' === flow.intent.trim()
+        ? undefined
+        : flowIntentId(flow.name);
+}
+/**
+ * Promote a flow's prose goal into the ledger and stamp the id back onto the flow.
+ *
+ * The binding is attached only when the flow asserts an observable consequence, because that is the
+ * only case where replaying it green proves anything. A flow that asserts nothing leaves its intent
+ * `declared` — and `dischargeIntent` refuses to prove an unbound intent, so an assertion-free flow
+ * can never discharge one. That is the whole guard, and it is the ledger's own rule, not a new one.
+ *
+ * Returns the flow unchanged (and writes nothing) when there is no intent, so a flow file saved
+ * before any of this existed keeps its exact bytes.
+ */
+export async function linkFlowIntent(store, flow) {
+    const id = intentIdOf(flow);
+    if (id === undefined)
+        return flow;
+    if (flow.intent !== undefined) {
+        await store.declare([{ id, statement: flow.intent, surface: { flow: flow.name } }]);
+    }
+    if (classifyFlowAssertions(flow).hasConsequenceAssertion) {
+        await store.bind(id, { flow: flow.name });
+    }
+    return { ...flow, intentId: id };
+}
+/**
+ * The nudge a flow saved without an intent earns, or nothing.
+ *
+ * Every save path routes through here, so the three of them cannot drift into three different ways
+ * of saying the same thing. It says it in the vocabulary the instrumentation gaps already use — what
+ * is missing, what it costs, and the one change that closes it — because "nobody said what this is
+ * for" is the same finding `undeclared-change` makes about an edit, one artifact later.
+ *
+ * Deliberately generic. It names no step, no assertion and not even the flow, for the reason this
+ * file already gives twice: anything specific enough to identify the goal is specific enough to be
+ * read AS the goal. It also never fails the save — a flow with no intent is still far better than no
+ * flow, and a verification tool that refuses to record work is one people route around.
+ */
+export function flowIntentGap(flow) {
+    if (intentIdOf(flow) !== undefined)
+        return undefined;
+    return instrumentationGap(InstrumentationGapKind.NO_FLOW_INTENT, 'this flow declares no intent, so nothing on disk says what it is meant to prove', 'it will replay for months, and the day it goes red the report can only name the step that broke — not the thing that stopped being true — so whoever reads it has to reconstruct the goal from the steps before they can tell a real regression from a moved button');
+}
+/**
+ * What the ledger currently says this flow is for, or undefined when nothing declared it.
+ *
+ * Read from the ledger rather than from the flow file's own copy: the ledger is where an amendment
+ * lands, and a report that quotes the stale copy would be the two-vocabularies problem all over
+ * again — one sentence in review, a different one in the failure message.
+ */
+export async function flowIntentStatement(store, flow) {
+    const id = intentIdOf(flow);
+    if (id === undefined)
+        return undefined;
+    const found = (await store.read()).find((intent) => intent.id === id);
+    return found?.statement ?? flow.intent;
+}
+/**
+ * Record that this replay proved the flow's intent. False when there was nothing to prove.
+ *
+ * Best-effort by construction: `IntentStore.discharge` returns false rather than throwing on an
+ * unknown or unbound id, because discharge runs off the back of a verdict and must never be the
+ * reason one fails to return.
+ */
+export async function dischargeFlowIntent(store, flow, proof) {
+    const id = intentIdOf(flow);
+    if (id === undefined)
+        return false;
+    try {
+        return await store.discharge(id, proof);
+    }
+    catch {
+        // A ledger that cannot be written is a small problem; a verdict that never returns because of
+        // one is a large problem. The replay already succeeded — the proof is simply not recorded.
+        return false;
+    }
+}

package/dist/flows/flow-memory-consult.d.ts

@@ -0,0 +1,55 @@
+/**
+ * What the team already knows about the flow being verified.
+ *
+ * ## Why a replay should ask at all
+ *
+ * Shared memory is written on every verification and, measured across this project's whole corpus,
+ * read essentially never: every subject on the dashboard showed `fetches: 0` and `readers: []`. Not
+ * because the data is useless — because consulting it is a SEPARATE act an agent has to remember to
+ * perform. Knowledge that must be deliberately fetched is a wiki, and wikis are not read.
+ *
+ * So verification asks on the agent's behalf. Replaying `checkout` returns what the project knows
+ * about checkout beside the verdict, which is the difference between memory the platform stores and
+ * memory the platform USES — and it is the only way the read counts on the coverage map ever become
+ * a real signal rather than a number nobody moves.
+ *
+ * ## Why this file is pure
+ *
+ * The fetch is the caller's. What a replay is ENTITLED to ask for — which subject, how much of it —
+ * is a rule worth testing without a network, and the rule is where the mistakes live.
+ */
+import type { FlowFile } from '@reticlehq/core';
+/**
+ * How many records travel back with a verdict.
+ *
+ * Small on purpose. This rides on every replay, and a verdict that arrives with fifty statements
+ * attached is one whose actual result is now below the fold. The subject page is one call away for
+ * an agent that wants the rest.
+ */
+export declare const MEMORY_CONSULT_LIMIT = 5;
+/**
+ * The subject a replay should ask about.
+ *
+ * The FLOW NAME, because a flow is a feature and that is the axis the store shards on — replaying
+ * `checkout` should surface what the team knows about checkout, not about the route it happens to
+ * start on. A flow whose name says nothing gets nothing: asking for `unsorted` would return the
+ * project's junk drawer on every verdict, which is worse than silence because it looks like an
+ * answer.
+ */
+export declare function consultSubjectFor(flow: FlowFile): string | undefined;
+/** One thing the project knows, as it travels back with a verdict. */
+export interface ConsultedMemory {
+    statement: string;
+    status: string;
+}
+/**
+ * Trim what came back to what is worth carrying.
+ *
+ * PROVED records first: a statement something has actually verified is stronger evidence about the
+ * feature than one somebody proposed and never checked. Beyond that the order is the server's, and
+ * anything without a statement is dropped rather than rendered as an empty line.
+ */
+export declare function selectConsulted(entries: readonly {
+    statement?: unknown;
+    status?: unknown;
+}[], limit?: number): ConsultedMemory[];

package/dist/flows/flow-memory-consult.js

@@ -0,0 +1,38 @@
+/**
+ * How many records travel back with a verdict.
+ *
+ * Small on purpose. This rides on every replay, and a verdict that arrives with fifty statements
+ * attached is one whose actual result is now below the fold. The subject page is one call away for
+ * an agent that wants the rest.
+ */
+export const MEMORY_CONSULT_LIMIT = 5;
+/**
+ * The subject a replay should ask about.
+ *
+ * The FLOW NAME, because a flow is a feature and that is the axis the store shards on — replaying
+ * `checkout` should surface what the team knows about checkout, not about the route it happens to
+ * start on. A flow whose name says nothing gets nothing: asking for `unsorted` would return the
+ * project's junk drawer on every verdict, which is worse than silence because it looks like an
+ * answer.
+ */
+export function consultSubjectFor(flow) {
+    const name = flow.name;
+    if ('string' !== typeof name || 0 === name.trim().length)
+        return undefined;
+    return name.trim();
+}
+/**
+ * Trim what came back to what is worth carrying.
+ *
+ * PROVED records first: a statement something has actually verified is stronger evidence about the
+ * feature than one somebody proposed and never checked. Beyond that the order is the server's, and
+ * anything without a statement is dropped rather than rendered as an empty line.
+ */
+export function selectConsulted(entries, limit = MEMORY_CONSULT_LIMIT) {
+    const usable = entries.flatMap((e) => 'string' === typeof e.statement && e.statement.trim().length > 0
+        ? [{ statement: e.statement, status: 'string' === typeof e.status ? e.status : 'unknown' }]
+        : []);
+    const proved = usable.filter((e) => 'proved' === e.status);
+    const rest = usable.filter((e) => 'proved' !== e.status);
+    return [...proved, ...rest].slice(0, limit);
+}

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

@@ -1,4 +1,7 @@
-import { FlowErrorCode, type FlowFile, type FlowReplayResult, type ReticleEvent } from '@reticlehq/core';
+import { FlowErrorCode, type CommandResult, type FlowFile, type FlowReplayResult, type ReticleEvent } from '@reticlehq/core';
+import type { ArrivalClock } from '../tools/navigate-arrival.js';
+import type { SessionManager } from '../session/session-manager.js';
+import type { Session } from '../session/session.js';
 import type { ToolDeps } from '../tools/tools.js';
 export declare function latestRecordedFlow(events: ReticleEvent[]): {
     name: string;
@@ -6,18 +9,25 @@ export declare function latestRecordedFlow(events: ReticleEvent[]): {
 } | undefined;
 /** Map a structured FlowErrorCode to a legible one-line message for the agent. */
 export declare function flowErrorMessage(code: FlowErrorCode): string;
+/** 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 (no route event) — never a false alarm. Replay itself does NOT
- * navigate: a full-page load mid-replay tears down the session socket; the agent navigates between
- * tool calls (reticle_navigate) where the session is re-resolved fresh.
+ * current route is unobservable — never a false alarm. Replay normally never gets here on a
+ * wrong page (arriveAtStartPath navigates before step 1); this is the fallback for when that
+ * navigation was refused or the SDK never reconnected in the window.
  */
-export declare function startPathMismatchHint(flow: FlowFile, session: {
-    eventsSince(cursor: number): ReticleEvent[];
-}): string | undefined;
+export declare function startPathMismatchHint(flow: FlowFile, session: StartPathSession): string | undefined;
+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>;
 /**
  * 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
@@ -30,3 +40,4 @@ export declare function replayNamedFlow(deps: ToolDeps, args: Record<string, unk
  * documented to work headless), so a missing/unknown session degrades to the global/legacy store.
  */
 export declare function sessionProjectId(deps: ToolDeps, sessionId: string | undefined): string | undefined;
+export {};

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

@@ -1,8 +1,15 @@
-import { EventType, FLOW_SIGNAL_TIMEOUT_MS, FlowErrorCode, RecordedFlowSchema, ReplayStatus, RunKind, RunStatus, } from '@reticlehq/core';
-import { asString } from '../tools/tools-helpers.js';
+import { EventType, FLOW_SIGNAL_TIMEOUT_MS, FlowErrorCode, RecordedFlowSchema, ReplayStatus, ReticleCommand, RunKind, RunStatus, } from '@reticlehq/core';
+import { asRecord, asString } from '../tools/tools-helpers.js';
+import { carryReticleIdentity } from '../tools/lease-tools.js';
 import { replayFlow } from './flow-replay.js';
+import { anchorQueryArgs } from './flow-step-runners.js';
+import { queryRefs } from './replay.js';
 import { assertSuccess, dynamicTestids, successLabel, SUCCESS_STEP_TOOL } from './flow-success.js';
 import { buildDecision, unverifiableReason } from './decision.js';
+import { classifyFlowAssertions } from './flow-classify.js';
+import { dischargeFlowIntent, flowIntentStatement, flowReplayVerdictId } from './flow-intent.js';
+import { IntentStore } from '../intent/intent-store.js';
+import { sessionRoot } from '../project/session-root.js';
 import { waitForPredicate } from '../events/predicate.js';
 import { computeSegments } from '../journal/rollups.js';
 import { AssertionTiersStore } from './assertion-tiers-store.js';
@@ -10,9 +17,11 @@ import { toFlowSources } from './flow-sources.js';
 import { reportAndAccumulate } from '../journal/deviation-service.js';
 import { EnvelopeStore } from '../journal/envelope-store.js';
 import { homedir } from 'node:os';
-import { syncRunRecordToCloud, SyncOutcome } from '../cloud/cloud-sync.js';
+import { cloudFetch, syncRunRecordToCloud, SyncOutcome } from '../cloud/cloud-sync.js';
 import { resolveProjectCloud } from '../cloud/cloud-config.js';
+import { consultSubjectFor, selectConsulted } from './flow-memory-consult.js';
 import { log } from '../log.js';
+import { flowsForSession } from './flow-store-for-session.js';
 export function latestRecordedFlow(events) {
     for (let i = events.length - 1; i >= 0; i--) {
         const event = events[i];
@@ -50,10 +59,12 @@ function replayToRunStatus(status) {
 }
 /**
  * Append a flow-replay outcome to .reticle/project.json (never throws into replay) and, when logged in,
- * best-effort mirror it to Reticle Cloud so the team's server-side regression history stays current. The
+ * best-effort mirror it to Reticle so the team's server-side regression history stays current. The
  * cloud push is fire-and-forget: not logged in → skipped, a network failure is logged and swallowed.
  */
-async function recordReplayRun(deps, name, status, driftSteps, durationMs, projectId) {
+async function recordReplayRun(deps, name, status, driftSteps, durationMs, projectId, 
+/** The APP's `.reticle`, resolved from the session — never the daemon's own. */
+recordRoot) {
     const runStatus = replayToRunStatus(status);
     await deps.project.recordRun({
         kind: RunKind.FLOW_REPLAY,
@@ -63,35 +74,223 @@ async function recordReplayRun(deps, name, status, driftSteps, durationMs, proje
         durationMs,
     });
     // Per-project cloud: push memory outcomes only when cloud is attached AND memory sync is enabled.
-    const cloud = await resolveProjectCloud(deps.fs, deps.reticleRoot, homedir(), process.env);
+    // Rooted at the APP, not the daemon — see consultProjectMemory. This call had the same defect and
+    // 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
-    const result = await syncRunRecordToCloud({ kind: RunKind.FLOW_REPLAY, name, status: runStatus, at: deps.now(), durationMs }, projectId, cloud.config, (url, init) => fetch(url, init));
+    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 data = routes.at(-1)?.data ?? {};
+    // pathname + 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.
+    const observed = asString(data['pathname']) ?? asString(data['to']);
+    if (observed !== undefined)
+        return `${observed}${asString(data['hash']) ?? ''}`;
+    if (session.url === undefined)
+        return undefined;
+    try {
+        const parsed = new URL(session.url);
+        return `${parsed.pathname}${parsed.hash}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Pathname equality up to a trailing slash — a router normalising one must not read as "elsewhere". */
+function samePath(a, b) {
+    return a.replace(/\/$/, '') === b.replace(/\/$/, '');
+}
+/**
+ * Ask the project what it already knows about this flow.
+ *
+ * Best-effort in the strongest sense: an unlinked project, a disabled memory policy, an offline
+ * laptop and a server that answers nonsense all reach the same place — the verdict returns without
+ * a memory block. A verification that FAILED because the knowledge lookup failed would be a worse
+ * product than one that never looked, and this is the path every replay takes.
+ *
+ * The read is also what makes the coverage map's fetch counts mean anything: they were zero across
+ * the entire corpus, not because memory is useless but because consulting it was a separate act
+ * nobody performed. Now the platform performs it.
+ */
+async function consultProjectMemory(deps, flow, root) {
+    const subject = consultSubjectFor(flow);
+    if (subject === undefined)
+        return undefined;
+    try {
+        // The APP's root, not the daemon's. `deps.reticleRoot` is wherever the daemon was launched,
+        // which for a user-scoped MCP registration is almost never the project being verified — so the
+        // link file it reads is the wrong one, or absent, and every project silently reads as
+        // "not attached". Same class of bug as the flow store resolving per daemon instead of per
+        // session, and it is invisible: the feature simply never appears.
+        const cloud = await resolveProjectCloud(deps.fs, root, homedir(), process.env);
+        if (null === cloud.config || !cloud.policy.memory)
+            return undefined;
+        const url = `${cloud.config.url}/v1/memory?subject=${encodeURIComponent(subject)}`;
+        const res = await cloudFetch(url, {
+            method: 'GET',
+            headers: { authorization: `Bearer ${cloud.config.apiKey}` },
+        });
+        if (200 !== res.status)
+            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());
+        const entries = body?.entries;
+        if (!Array.isArray(entries))
+            return undefined;
+        const picked = selectConsulted(entries);
+        return 0 === picked.length ? undefined : picked;
+    }
+    catch {
+        // See the note above: never the reason a verdict fails to return.
+        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 (no route event) — never a false alarm. Replay itself does NOT
- * navigate: a full-page load mid-replay tears down the session socket; the agent navigates between
- * tool calls (reticle_navigate) where the session is re-resolved fresh.
+ * current route is unobservable — never a false alarm. Replay normally never gets here on a
+ * wrong page (arriveAtStartPath navigates before step 1); this is the fallback for when that
+ * navigation was refused or the SDK never reconnected in the window.
  */
 export function startPathMismatchHint(flow, session) {
     const startPath = flow.startPath;
     if (startPath === undefined || 0 === startPath.length)
         return undefined;
-    const routes = session.eventsSince(0).filter((e) => e.type === EventType.ROUTE_CHANGE);
-    const last = routes.at(-1);
-    const data = last?.data ?? {};
-    const current = asString(data['pathname']) ?? asString(data['to']);
-    if (current === undefined || current === startPath)
+    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 — but only once it actually sits on `target`. Undefined while
+ * the tab is still travelling (or in the gap between teardown and the successor's HELLO, when
+ * `resolve` throws). Keyed to the navigated tab's own identity on purpose: matching "any session at
+ * the target page" would happily hand replay an unrelated tab that was already sitting there.
+ */
+function arrivedSuccessor(sessions, oldId, target) {
+    try {
+        const candidate = sessions.resolve(oldId);
+        const path = currentPathOf(candidate);
+        return path !== undefined && samePath(path, target) ? candidate : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Replay's half of the FlowFile contract: navigate to the flow's `startPath` before step 1.
+ *
+ * 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.
+ */
+/**
+ * Can step 1 start from where the tab already is?
+ *
+ * `startPathMismatchHint` states the premise the navigation below exists to serve: on the wrong
+ * route "the anchor simply isn't on this page yet". That is the condition worth a page load — and
+ * it was never the condition checked. `arriveAtStartPath` fired on a route mismatch ALONE, so a
+ * flow whose first anchor lives somewhere persistent (a sidebar, a header, a nav rail — present on
+ * every route) was navigated for a problem it did not have.
+ *
+ * A navigation is a full page load, which tears the session down and brings the app back in its
+ * cold state. For the ordinary case of a flow recorded after signing in, that cold state is the
+ * LOGIN SCREEN: step 1 then reports its anchor missing and names the component that holds it, which
+ * is a correct sentence about a file that is completely fine. Found by the benchmark, on two flows
+ * with identical steps where the first replayed clean and the second — run after it, with the tab
+ * drifted off `/` — did not.
+ *
+ * So the question is asked directly. A best-effort step that can leave the caller WORSE off than
+ * skipping it is not best-effort; checking first is what makes the description true.
+ *
+ * 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;
+    }
+}
+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 undefined;
+    const current = currentPathOf(session);
+    if (current === undefined || samePath(current, target))
+        return undefined;
+    // The route differs — but that only matters if it stops the flow starting. See above.
+    if (await firstStepResolvesHere(session, flow))
+        return undefined;
+    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.
+        destination = new URL(target, session.url).toString();
+    }
+    catch {
+        return undefined; // no usable base URL — nowhere to navigate from
+    }
+    // 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 undefined;
+    }
+    catch {
+        return undefined;
+    }
+    const deadline = clock.now() + timeoutMs;
+    for (;;) {
+        const arrived = arrivedSuccessor(sessions, session.id, target);
+        if (arrived !== undefined)
+            return arrived;
+        if (clock.now() >= deadline)
+            return undefined;
+        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
@@ -110,9 +309,11 @@ export async function replayNamedFlow(deps, args) {
     catch {
         projectId = undefined;
     }
-    const loaded = await deps.flows.load(name, projectId);
+    // The app's store, not the daemon's: this load answering `flow_not_found` for a flow plainly on
+    // disk is what made replay unusable from a daemon started outside the project.
+    const loaded = await flowsForSession(deps, projectId).flows.load(name, projectId);
     if (!loaded.ok) {
-        await recordReplayRun(deps, name, ReplayStatus.ERROR, 0, deps.now() - startedAt, projectId);
+        await recordReplayRun(deps, name, ReplayStatus.ERROR, 0, deps.now() - startedAt, projectId, sessionRoot(deps, asString(args['sessionId'])));
         return {
             name,
             status: ReplayStatus.ERROR,
@@ -120,9 +321,22 @@ export async function replayNamedFlow(deps, args) {
             error: { code: loaded.code, message: flowErrorMessage(loaded.code) },
         };
     }
-    const session = deps.sessions.resolve(asString(args['sessionId']));
-    // Captured before replay: if the tab isn't on the flow's start page, a step-1 drift is a wrong-page
-    // symptom, not a regression — surface that on the decision instead of a bare "a step no longer matches".
+    // What this flow is FOR, from the shared ledger — so a failure can report the business outcome
+    // that stopped being true before the step that stopped being green. Undefined when nothing
+    // declared one, which the decision then says plainly rather than inventing a goal from step names.
+    /*
+     * The APP's `.reticle`, resolved once. Everything below that reaches the project's own files —
+     * the intent ledger, the cloud link, the memory consultation — takes THIS, not `deps.reticleRoot`,
+     * which is wherever the daemon happened to be launched.
+     */
+    const replayRoot = sessionRoot(deps, asString(args['sessionId']));
+    const intents = new IntentStore(deps.fs, replayRoot, { now: deps.now });
+    const intentSaid = await flowIntentStatement(intents, loaded.value);
+    const connected = deps.sessions.resolve(asString(args['sessionId']));
+    // The FlowFile contract: replay navigates to the flow's startPath before step 1, and the steps run
+    // on the session the SDK reconnects as. When arrival can't be confirmed, replay proceeds on the
+    // connected session — and the hint below turns the wrong-page drift into an actionable next move.
+    const session = (await arriveAtStartPath(deps.sessions, connected, loaded.value)) ?? connected;
     const startPathHint = startPathMismatchHint(loaded.value, session);
     // Floor the success oracle at the start of THIS replay so a stale signal from a prior run
     // in the same session can't fake a pass.
@@ -146,7 +360,7 @@ export async function replayNamedFlow(deps, args) {
     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;
-    await recordReplayRun(deps, name, status, driftSteps, deps.now() - startedAt, projectId);
+    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.
     if (status === ReplayStatus.OK) {
@@ -156,9 +370,31 @@ export async function replayNamedFlow(deps, args) {
         })), 
         // Record what this flow COVERS so a later deletion can be scoped to the files that changed.
         toFlowSources([{ name, steps: loaded.value.steps }])[0]?.sources ?? []);
+        // The ledger learns what this run proved. Only a flow that COULD have gone red discharges: an
+        // assertion-free flow is never bound, and `dischargeIntent` refuses an unbound intent, so the
+        // guard here is the cheap half of a rule the ledger already enforces. `grade` is what makes a
+        // later weakening visible — an intent re-proved by a weaker flow says so in the git diff.
+        if (unverifiableReason(loaded.value) === undefined) {
+            const provedAt = deps.now();
+            await dischargeFlowIntent(intents, loaded.value, {
+                verdictId: flowReplayVerdictId(name, provedAt),
+                grade: classifyFlowAssertions(loaded.value).grade,
+                at: provedAt,
+            });
+        }
     }
     // Push-default: the deviation report over this drive's segments, learned across runs. Best-effort.
     const deviation = await computeReplayDeviation(deps, session, replayFloor);
+    /*
+     * What the team already knows about this flow, fetched on the agent's behalf.
+     *
+     * Attached to the FAILING path as well as the clean one, deliberately: a drift is exactly the
+     * moment somebody needs to know what this feature is supposed to do and who established it. A
+     * knowledge base you only see when everything is already fine is decoration.
+     */
+    // No projectId argument: the API key is already bound to one project server-side, so passing a
+    // second opinion about which project this is would only create a way for the two to disagree.
+    const knows = await consultProjectMemory(deps, loaded.value, replayRoot);
     const failed = steps.find((step) => !step.ok && step.drift === undefined);
     if (failed !== undefined) {
         const errored = {
@@ -167,13 +403,17 @@ export async function replayNamedFlow(deps, args) {
             steps,
             error: { code: ReplayStatus.ERROR, message: failed.error ?? 'flow action failed' },
         };
-        errored.decision = buildDecision(errored, loaded.value);
+        errored.decision = buildDecision(errored, loaded.value, intentSaid);
         applyStartPathHint(errored, startPathHint);
         if (deviation !== undefined)
             errored.deviation = deviation;
+        if (knows !== undefined)
+            errored.knows = knows;
         return errored;
     }
     const result = { name, status, steps };
+    if (knows !== undefined)
+        result.knows = knows;
     // A green that cannot go red is not a pass. `reticle_flow_verify` already refuses to count these,
     // via this same function -- a single-flow caller saw a bare `ok` and had no way to learn the flow
     // asserts nothing. Derived from the same helper on purpose: two copies of this judgement would
@@ -182,7 +422,7 @@ export async function replayNamedFlow(deps, args) {
     if (cannotFail !== undefined)
         result.unverifiable = { reason: cannotFail };
     if (status !== ReplayStatus.OK)
-        result.decision = buildDecision(result, loaded.value);
+        result.decision = buildDecision(result, loaded.value, intentSaid);
     applyStartPathHint(result, startPathHint);
     if (deviation !== undefined)
         result.deviation = deviation;