@reticlehq/server 2.12.0 → 2.13.0

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

@@ -1,6 +1,9 @@
-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';
@@ -16,7 +19,9 @@ import { EnvelopeStore } from '../journal/envelope-store.js';
 import { homedir } from 'node:os';
 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];
@@ -54,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,
@@ -67,7 +74,10 @@ 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, cloudFetch);
@@ -75,27 +85,212 @@ async function recordReplayRun(deps, name, status, driftSteps, durationMs, proje
         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
@@ -114,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,
@@ -127,13 +324,19 @@ export async function replayNamedFlow(deps, args) {
     // 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.
-    const intents = new IntentStore(deps.fs, sessionRoot(deps, asString(args['sessionId'])), {
-        now: deps.now,
-    });
+    /*
+     * 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 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".
+    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.
@@ -157,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) {
@@ -182,6 +385,16 @@ export async function replayNamedFlow(deps, args) {
     }
     // 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 = {
@@ -194,9 +407,13 @@ export async function replayNamedFlow(deps, args) {
         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

package/dist/flows/flow-replay.js

@@ -1,4 +1,5 @@
 import { span } from '../trace.js';
+import { routePathOf } from '../events/predicate-route.js';
 import { AnchorKind, DriftReason, EventType, ReticleCommand, QueryBy, PredicateKind, } from '@reticlehq/core';
 import { asRecord, asString } from '../tools/tools-helpers.js';
 import { replayActionArgs, ambiguousTestidNote, queryRefs } from './replay.js';
@@ -198,8 +199,14 @@ function currentRoute(session) {
     if (last === undefined)
         return undefined;
     const data = last.data ?? {};
+    // The ROUTER's path. This field answers "which page did this step run on", and the document
+    // pathname is `/` on every page of a hash-routed app — so a whole desktop replay reported `/` for
+    // every step. Sixth place the same reading was wrong; see routePathOf.
     const pathname = asString(data['pathname']) ?? asString(data['to']);
-    return pathname !== undefined && pathname.length > 0 ? pathname : undefined;
+    if (pathname === undefined || 0 === pathname.length)
+        return undefined;
+    const routed = routePathOf(pathname, asString(data['hash']) ?? '');
+    return routed.length > 0 ? routed : undefined;
 }
 /** Pathname only (drop origin + query) so a net URL stays terse in the journey. */
 function trimUrl(url) {
@@ -294,7 +301,9 @@ async function runTestidStep(session, step, index, value, dynamic, confirmDanger
         act = await session.command(ReticleCommand.ACT, {
             ref,
             action: step.action ?? '',
-            args: replayActionArgs(step.args, confirmDangerous),
+            // `value` is the anchor's own name — the field this step types into — so a redacted fill can
+            // be supplied from RETICLE_SECRET_<FIELD> without the flow carrying the secret.
+            args: replayActionArgs(step.args, confirmDangerous, value),
         });
     }
     finally {

package/dist/flows/flow-step-runners.d.ts

@@ -30,6 +30,14 @@ export declare function runComponentStep(session: FlowReplaySession, step: FlowS
  */
 export declare function isDegradedAnchor(anchor: FlowAnchor): boolean;
 export declare function degradedStepResult(step: FlowStep, index: number, label: string): FlowStepResult;
+/**
+ * QUERY args for an element anchor — null when the anchor addresses no element.
+ *
+ * Exported for `arriveAtStartPath`, which has to ask "can step 1 resolve where we already are?"
+ * before deciding to navigate. Sharing this mapping rather than repeating it keeps that question and
+ * the step runner's own resolution asking the same thing of the same anchor.
+ */
+export declare function anchorQueryArgs(anchor: FlowAnchor): Record<string, unknown> | null;
 /**
  * Run an act_sequence step: resolve every sub-step's OWN anchor, then dispatch the whole thing as one
  * ACT_SEQUENCE — the same shape `replayProgram` already uses, so a recorded sequence and a saved one

package/dist/flows/flow-step-runners.js

@@ -181,8 +181,14 @@ export function degradedStepResult(step, index, label) {
         },
     };
 }
-/** QUERY args for an element anchor — null when the anchor addresses no element. */
-function anchorQueryArgs(anchor) {
+/**
+ * QUERY args for an element anchor — null when the anchor addresses no element.
+ *
+ * Exported for `arriveAtStartPath`, which has to ask "can step 1 resolve where we already are?"
+ * before deciding to navigate. Sharing this mapping rather than repeating it keeps that question and
+ * the step runner's own resolution asking the same thing of the same anchor.
+ */
+export function anchorQueryArgs(anchor) {
     if (anchor.kind === AnchorKind.TESTID)
         return { by: QueryBy.TESTID, value: anchor.value };
     if (anchor.kind === AnchorKind.COMPONENT)

package/dist/flows/flow-store-for-session.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The flow store a SESSION's flows belong in.
+ *
+ * `deps.flows` is bound to the daemon's own root at construction, which is right only when the
+ * daemon happens to have been started in the project it is driving. A user-scoped MCP registration
+ * is the common case and the editor starts it wherever it likes, so "where the daemon was launched"
+ * and "which app is being verified" are usually different directories.
+ *
+ * This used to live inside flow-tools and was applied at exactly ONE of ten call sites. The result
+ * is the half-applied state `sessionRoot` warns about in its own comment, reached in practice:
+ *
+ *   - the HUD listed the daemon repo's flows while driving somebody else's app — Electron and Tauri
+ *     flows shown over a React dashboard, none of which existed in the checkout being verified
+ *   - `flow_replay` answered `flow_not_found` for a flow sitting on disk, because it looked in the
+ *     daemon's root while `reticle verify` (which roots itself at cwd) replayed the same flow fine
+ *   - and the two save paths disagreed with each other, so where a flow landed depended on which
+ *     tool wrote it
+ *
+ * Reported as "running the daemon from here but taking the directory from there", which is exactly
+ * what it was.
+ *
+ * Rebinding is cheap — a FlowStore is a filesystem port, a root and a clock — and the common case
+ * allocates nothing: when no resolver is wired, or it names the root already in use, `deps.flows` is
+ * returned unchanged.
+ */
+import { FlowStore } from './flows.js';
+import type { ToolDeps } from '../tools/tool-kit.js';
+export declare function flowsForSession(deps: ToolDeps, projectId: string | undefined): {
+    flows: FlowStore;
+    root: string;
+};

package/dist/flows/flow-store-for-session.js

@@ -0,0 +1,33 @@
+/**
+ * The flow store a SESSION's flows belong in.
+ *
+ * `deps.flows` is bound to the daemon's own root at construction, which is right only when the
+ * daemon happens to have been started in the project it is driving. A user-scoped MCP registration
+ * is the common case and the editor starts it wherever it likes, so "where the daemon was launched"
+ * and "which app is being verified" are usually different directories.
+ *
+ * This used to live inside flow-tools and was applied at exactly ONE of ten call sites. The result
+ * is the half-applied state `sessionRoot` warns about in its own comment, reached in practice:
+ *
+ *   - the HUD listed the daemon repo's flows while driving somebody else's app — Electron and Tauri
+ *     flows shown over a React dashboard, none of which existed in the checkout being verified
+ *   - `flow_replay` answered `flow_not_found` for a flow sitting on disk, because it looked in the
+ *     daemon's root while `reticle verify` (which roots itself at cwd) replayed the same flow fine
+ *   - and the two save paths disagreed with each other, so where a flow landed depended on which
+ *     tool wrote it
+ *
+ * Reported as "running the daemon from here but taking the directory from there", which is exactly
+ * what it was.
+ *
+ * Rebinding is cheap — a FlowStore is a filesystem port, a root and a clock — and the common case
+ * allocates nothing: when no resolver is wired, or it names the root already in use, `deps.flows` is
+ * returned unchanged.
+ */
+import { FlowStore } from './flows.js';
+export function flowsForSession(deps, projectId) {
+    const resolved = deps.artifactRootFor?.(projectId);
+    if (resolved === undefined || resolved.root === deps.reticleRoot) {
+        return { flows: deps.flows, root: deps.reticleRoot };
+    }
+    return { flows: new FlowStore(deps.fs, resolved.root, { now: deps.now }), root: resolved.root };
+}