@reticlehq/server 3.3.0 → 3.5.0

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

@@ -0,0 +1,119 @@
+import { createHash } from 'node:crypto';
+import { PredicateKind } from '@reticlehq/core';
+/**
+ * One journey, however many times it was driven.
+ *
+ * Every browser session saves its own flow at teardown, so a journey driven in five sessions was
+ * five near-identical files. Two flows are the SAME journey when they start on the same page and
+ * take the same steps: same tool, action, anchor and invocation, in the same order. What was typed
+ * and what was claimed do not decide it — a re-drive that fills a different value or declares one
+ * more consequence is the same journey, better described.
+ */
+/** The anchor minus its source location, which moves when an unrelated line is edited. */
+function anchorShape(anchor) {
+    const { source: _source, ...rest } = anchor;
+    return rest;
+}
+function stepShape(step) {
+    return [
+        step.tool,
+        step.action ?? null,
+        anchorShape(step.anchor),
+        step.invoke ?? null,
+        (step.steps ?? []).map(stepShape),
+    ];
+}
+const FINGERPRINT_LENGTH = 12;
+/** A short, stable identity for a journey's shape: its start page and its steps. */
+export function journeyFingerprint(flow) {
+    return createHash('sha256')
+        .update(JSON.stringify([flow.startPath ?? null, flow.steps.map(stepShape)]))
+        .digest('hex')
+        .slice(0, FINGERPRINT_LENGTH);
+}
+/** `kept` wins wherever it says something; `other` fills only what `kept` left unsaid. */
+function fillStep(kept, other) {
+    if (other === undefined)
+        return kept;
+    const merged = { ...other, ...kept };
+    if (kept.steps !== undefined) {
+        merged.steps = kept.steps.map((sub, i) => fillStep(sub, other.steps?.[i]));
+    }
+    return merged;
+}
+/**
+ * Fold two copies of one journey into one file.
+ *
+ * Gap-filling, never overwriting: whatever the kept flow already says — its name, its intent, a
+ * step's declared consequence, a quarantine a person wrote — survives, and the other copy only
+ * supplies what is missing. So a merge can add an assertion or an intent and can never remove one.
+ */
+export function mergeJourney(kept, other) {
+    return {
+        ...other,
+        ...kept,
+        steps: kept.steps.map((step, i) => fillStep(step, other.steps[i])),
+    };
+}
+/**
+ * The name a new journey saves under.
+ *
+ * Its readable name when that is free or already this journey's; otherwise the same name with the
+ * fingerprint's head, so two different journeys that share an intent never overwrite each other.
+ */
+export function journeyName(base, fingerprint, taken) {
+    const owner = taken.get(base);
+    return owner === undefined || owner === fingerprint ? base : `${base}-${fingerprint.slice(0, 6)}`;
+}
+/**
+ * What must hold before a journey and what it leaves behind, read from where it started and ended.
+ *
+ * Routes only: the page is the one piece of state every recorded step knows for certain, and a
+ * claim written from a guess about the rest would be a precondition nobody met. Written in the
+ * exact form `canFollow` compares by value, so A-then-B is answerable from the two files alone.
+ */
+export function routeClaims(startPath, steps) {
+    const first = startPath ?? steps[0]?.page;
+    const last = steps.at(-1);
+    const end = last?.endPage ?? last?.page;
+    return {
+        ...(first === undefined ? {} : { requires: [{ kind: PredicateKind.ROUTE, pathname: first }] }),
+        ...(end === undefined ? {} : { ensures: [{ kind: PredicateKind.ROUTE, pathname: end }] }),
+    };
+}
+/**
+ * The preconditions only another flow can establish.
+ *
+ * A route claim on the page the flow starts on is not one of them: replay navigates there itself, so
+ * it neither opts the flow out of the reset nor gates the run. That is the claim a saved drive writes
+ * for the map (see routeClaims) — reading it as "starts from leftover state" would stop every
+ * auto-saved flow from ever being reset.
+ */
+export function establishedState(flow) {
+    const start = flow.startPath;
+    return (flow.requires ?? []).filter((claim) => !(start !== undefined &&
+        PredicateKind.ROUTE === claim.kind &&
+        claim.pathname !== undefined &&
+        samePath(claim.pathname, start)));
+}
+/**
+ * Is the tab where the flow asked to start? Up to a trailing slash, and up to the query the flow
+ * did not ask about.
+ *
+ * `startPath` is the SPECIFICATION, so it decides what counts. A query it recorded is compared:
+ * `?tab=wrap` and `?tab=summary` are different pages, and a replay that starts on the wrong one
+ * proves nothing about the right one. A query it did NOT record is ignored: the tab carrying
+ * `?next=%2F` on a login page, or the identity params Reticle puts on a leased tab, are not the flow
+ * being elsewhere, and navigating to strip them costs a session for nothing.
+ *
+ * The asymmetry is the whole point and the reason `observed` and `expected` are named rather than
+ * `a` and `b`. Comparing with the query on both sides always re-navigated a query-bearing
+ * `startPath` (#1059, which killed the session mid-flow); comparing with it on neither side reads a
+ * tab on `?tab=summary` as already at `?tab=wrap`.
+ */
+export function samePath(observed, expected) {
+    const trimmed = (path) => path.replace(/\/$/, '');
+    const withoutQuery = (path) => path.replace(/\?[^#]*/, '');
+    const comparable = expected.includes('?') ? observed : withoutQuery(observed);
+    return trimmed(comparable) === trimmed(expected);
+}

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

@@ -1,4 +1,4 @@
-import { FlowErrorCode, type CommandResult, type FlowFile, type FlowReplayResult, type Contradiction, type FlowStepResult, type ReticleEvent } from '@reticlehq/core';
+import { type CommandResult, type FlowFile, type FlowReplayResult, type Contradiction, type FlowStepResult, type ReticleEvent } from '@reticlehq/core';
 import type { ArrivalClock } from '../../surface/tools/act/navigation/navigate-arrival.js';
 import type { SessionManager } from '../../portal/session/session-manager.js';
 import type { Session } from '../../portal/session/session.js';
@@ -8,8 +8,7 @@ export declare function latestRecordedFlow(events: ReticleEvent[]): {
     name: string;
     flow: import('@reticlehq/core').FlowFile;
 } | undefined;
-/** Map a structured FlowErrorCode to a legible one-line message for the agent. */
-export declare function flowErrorMessage(code: FlowErrorCode, detail?: string): string;
+export { flowErrorMessage } from './flow-result.js';
 /** The slice of a session the start-path logic reads: the live URL plus the event buffer. */
 interface StartPathSession {
     url?: string;

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

@@ -2,6 +2,7 @@ import { resolveFlowUploads } from './fields/flow-upload-resolve.js';
 import { learnFromRun } from '@reticlehq/engine/evidence/learned-guards.js';
 import { EventType, FLOW_SIGNAL_TIMEOUT_MS, FlowErrorCode, RecordedFlowSchema, ReplayStatus, ReticleCommand, RunKind, RunStatus, } from '@reticlehq/core';
 import { haltedFrom } from './recording/replay-halt.js';
+import { establishedState, samePath } from './flow-journey.js';
 import { asRecord, asString } from '@reticlehq/core';
 import { routeOfEvent, routeOfUrl } from '@reticlehq/engine/question/predicate/predicate-route.js';
 import { carryReticleIdentity } from '../../surface/tools/lease-tools.js';
@@ -11,7 +12,7 @@ import { queryRefs } from './replay.js';
 import { assertSuccess, dynamicTestids, successLabel, SUCCESS_STEP_TOOL } from './flow-success.js';
 import { buildDecision, unverifiableReason } from './decision.js';
 import { unsuppliedSecrets } from './fields/flow-secret-field.js';
-import { assertStepExpect, DocumentLostDuringReplay, } from './flow-replay.js';
+import { assertStepExpect, DocumentLostDuringReplay, resumeArg, unresolvedResume, } from './flow-replay.js';
 import { isDocumentGoneError } from '../../portal/session/facts/session-replaced.js';
 import { classifyFlowAssertions, flattenSteps } from './flow-classify.js';
 import { dischargeFlowIntent, flowIntentStatement, flowReplayVerdictId } from './flow-intent.js';
@@ -31,7 +32,6 @@ import { consultSubjectFor, selectConsulted } from './flow-memory-consult.js';
 import { log } from '../../log.js';
 import { flowsForSession } from './flow-store-for-session.js';
 import { projectForRoot } from '../../memory/project/project-for-root.js';
-import { FlowParseNote } from './flow-expect-grammar.js';
 export function latestRecordedFlow(events) {
     for (let i = events.length - 1; i >= 0; i--) {
         const event = events[i];
@@ -43,28 +43,8 @@ export function latestRecordedFlow(events) {
     }
     return undefined;
 }
-/** Map a structured FlowErrorCode to a legible one-line message for the agent. */
-export function flowErrorMessage(code, detail) {
-    if (FlowErrorCode.PARSE_FAILED === code && undefined !== detail)
-        return detail;
-    // The detail names both versions and the remedy, so it beats anything generic this could say.
-    if (FlowErrorCode.WRONG_VERSION === code && undefined !== detail)
-        return detail;
-    switch (code) {
-        case FlowErrorCode.INVALID_NAME:
-            return 'invalid flow name — use a single safe segment (letters/digits/-/_), no path separators';
-        case FlowErrorCode.NOT_FOUND:
-            return 'no such flow on disk — run reticle_flow{action:"list"} to see saved flows';
-        case FlowErrorCode.PARSE_FAILED:
-            return FlowParseNote.MALFORMED;
-        case FlowErrorCode.NO_RECORDING:
-            return 'no compiled recording by that name — record one (reticle_record{action:"start"|"stop"}) first';
-        // Never "regenerate it": the file is intact and the reader is the wrong one. Telling somebody
-        // to rewrite an undamaged flow is the failure this code was split out of PARSE_FAILED to stop.
-        case FlowErrorCode.WRONG_VERSION:
-            return 'this flow file was written in a different flow-file format — the file is not damaged, this Reticle cannot read that version. Upgrade or downgrade Reticle rather than editing the flow';
-    }
-}
+export { flowErrorMessage } from './flow-result.js';
+import { flowErrorMessage } from './flow-result.js';
 /** Map the wire ReplayStatus onto the persisted RunStatus (ok→pass). */
 function replayToRunStatus(status) {
     switch (status) {
@@ -133,27 +113,6 @@ function currentPathOf(session) {
     const fromUrl = routeOfUrl(session.url);
     return fromUrl === undefined ? undefined : `${fromUrl.docPath}${fromUrl.search}${fromUrl.hash}`;
 }
-/**
- * Is the tab where the flow asked to start? Up to a trailing slash, and up to the query the flow
- * did not ask about.
- *
- * `startPath` is the SPECIFICATION, so it decides what counts. A query it recorded is compared:
- * `?tab=wrap` and `?tab=summary` are different pages, and a replay that starts on the wrong one
- * proves nothing about the right one. A query it did NOT record is ignored: the tab carrying
- * `?next=%2F` on a login page, or the identity params Reticle puts on a leased tab, are not the flow
- * being elsewhere, and navigating to strip them costs a session for nothing.
- *
- * The asymmetry is the whole point and the reason `observed` and `expected` are named rather than
- * `a` and `b`. Comparing with the query on both sides always re-navigated a query-bearing
- * `startPath` (#1059, which killed the session mid-flow); comparing with it on neither side reads a
- * tab on `?tab=summary` as already at `?tab=wrap`.
- */
-function samePath(observed, expected) {
-    const trimmed = (path) => path.replace(/\/$/, '');
-    const withoutQuery = (path) => path.replace(/\?[^#]*/, '');
-    const comparable = expected.includes('?') ? observed : withoutQuery(observed);
-    return trimmed(comparable) === trimmed(expected);
-}
 /**
  * Ask the project what it already knows about this flow.
  *
@@ -321,7 +280,7 @@ export async function arriveAtStartPath(sessions, session, flow, timeoutMs = STA
     if (current === undefined)
         return {};
     // The declared opt-out, both directions. See above.
-    if (0 < (flow.requires?.length ?? 0))
+    if (0 < establishedState(flow).length)
         return {};
     const here = samePath(current, target);
     // A route mismatch that step 1 can start from anyway is not worth a page load: navigating away
@@ -457,7 +416,7 @@ async function loadInvokedFlows(deps, flow, projectId) {
  * a consequence of the first being absent.
  */
 async function firstUnmetPrecondition(session, flow, since) {
-    for (const claim of flow.requires ?? []) {
+    for (const claim of establishedState(flow)) {
         // Zero budget: a precondition is a claim about the state you are starting FROM. Waiting for one
         // turns "was it true" into "did it become true", which is a different and much weaker question.
         let drift;
@@ -608,6 +567,12 @@ observe = (s) => s) {
             },
         };
     }
+    const from = resumeArg(args['from']);
+    const badResume = unresolvedResume(from, replayable.steps);
+    if (badResume !== undefined) {
+        const error = { code: FlowErrorCode.STEP_NOT_FOUND, message: badResume };
+        return { name: replayable.name, status: ReplayStatus.ERROR, steps: [], error };
+    }
     const unmet = await firstUnmetPrecondition(session, replayable, replayFloor);
     if (unmet !== undefined) {
         return {
@@ -629,6 +594,7 @@ observe = (s) => s) {
             // Bug-sweep mode: keep going past a step whose action ran and whose consequence merely did
             // not hold, so one flow reports one verdict per step instead of stopping at the first defect.
             sweep: true === args['sweep'],
+            ...(from === undefined ? {} : { from }),
         });
     }
     catch (error) {

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

@@ -1,4 +1,4 @@
-export { anchorLabel, componentLabel, componentQueryArgs, editDistance, expectElementDrift, nearestIsAmbiguous, nearestTestid, resolveQuery, testidDrift, } from './flow-anchor.js';
+export { nearestIsAmbiguous, nearestTestid, resolveQuery } from './flow-anchor.js';
 import type { FlowReplaySession, WaitForSignal, Sleep } from './flow-replay-types.js';
 export type { FlowReplaySession, WaitForSignal, Sleep } from './flow-replay-types.js';
 import { type Drift, type FlowFile, type FlowStep, type FlowStepResult } from '@reticlehq/core';
@@ -50,15 +50,18 @@ export declare function assertStepExpect(session: FlowReplaySession, expect: Non
  * results. This is the "whose fault is it" contract, not a blind "command failed".
  */
 /**
- * How a replay is loaded and how far it goes — not WHERE it starts.
- *
- * It carried a `from` (and a `surface` that existed only to gate it): replay from step N, re-driving
- * the prefix silently. The machinery was built, tested and reachable from nothing at all — no tool
- * argument, no CLI flag, no caller anywhere. Deleted rather than wired: unreachable code is read as
- * current by the next person and maintained forever, its passing tests make it look load-bearing,
- * and nobody has asked for resume-from-step. The history keeps it if it is ever wanted.
+ * How a replay is loaded, where it starts reporting, and how far it goes.
  */
 export interface ReplayFromOptions {
+    /**
+     * Resume at this step: an index, or a step's `id` (which survives edits that shift indices).
+     *
+     * There is no state to restore, so the steps before it are re-driven — quickly, as setup: their
+     * actions run, their declared consequences are not checked and their results are not reported.
+     * The one exception is a setup step that FAILS: the resume never reached the step it was asked
+     * for, and swallowing that would report the run as starting where it did not.
+     */
+    from?: number | string;
     /**
      * How to load a flow this one INVOKES. Absent means invocations cannot be followed.
      *
@@ -89,4 +92,15 @@ export interface ReplayFromOptions {
      */
     sweep?: boolean;
 }
+/**
+ * The index a replay resumes at, or `undefined` when `from` names no step of this flow.
+ *
+ * A step declared `commits` in the prefix refuses the resume (0 = replay everything): re-driving it
+ * is not setup, it is a second charge, a second email, a second record.
+ */
+export declare function resumeIndex(from: number | string | undefined, steps: readonly FlowStep[]): number | undefined;
+/** The `from` argument, narrowed: a step index or a step id. */
+export declare function resumeArg(raw: unknown): number | string | undefined;
+/** Why `from` cannot be resumed at, or undefined when it can (or was not given). */
+export declare function unresolvedResume(from: number | string | undefined, steps: readonly FlowStep[]): string | undefined;
 export declare function replayFlow(session: FlowReplaySession, flow: FlowFile, waitForSignal: WaitForSignal, signalTimeoutMs: number, confirmDangerous?: boolean, sleep?: Sleep, options?: ReplayFromOptions): Promise<FlowStepResult[]>;

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

@@ -2,10 +2,10 @@ import { formatStepAddress } from 'open-verification';
 import { assertsState, expectLabel, expectedElementTestid, withoutClauses } from '@reticlehq/core';
 import { span } from '../../trace.js';
 import { anchorLabel, expectElementDrift, resolveTestid, testidDrift, ambiguousAnchorDrift, } from './flow-anchor.js';
-export { anchorLabel, componentLabel, componentQueryArgs, editDistance, expectElementDrift, nearestIsAmbiguous, nearestTestid, resolveQuery, testidDrift, } from './flow-anchor.js';
-import { routeOfEvent } from '@reticlehq/engine/question/predicate/predicate-route.js';
+export { nearestIsAmbiguous, nearestTestid, resolveQuery } from './flow-anchor.js';
+import { routeOfEvent, routeOfUrl } from '@reticlehq/engine/question/predicate/predicate-route.js';
 import { stepEffect } from '@reticlehq/engine/evidence/step-effect.js';
-import { AnchorKind, DriftReason, EventType, FlowStepTool, PredicateKind, } from '@reticlehq/core';
+import { AnchorKind, DriftReason, EventType, FlowStepTool, StepEffect, PredicateKind, } from '@reticlehq/core';
 import { asString, isConsequenceDrift } from '@reticlehq/core';
 import { anchorFieldName } from './fields/flow-secret-field.js';
 import { degradedStepResult, isDegradedAnchor, runComponentStep, runRoleStep, runSequenceStep, } from './flow-step-runners.js';
@@ -48,8 +48,11 @@ const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 function currentRoute(session) {
     const routes = session.eventsSince(0).filter((e) => e.type === EventType.ROUTE_CHANGE);
     const last = routes.at(-1);
-    if (last === undefined)
-        return undefined;
+    // A page that loaded and never navigated has no route event; its URL is still where it is.
+    if (last === undefined) {
+        const loaded = session.url === undefined ? undefined : routeOfUrl(session.url);
+        return loaded !== undefined && loaded.routePath.length > 0 ? loaded.routePath : undefined;
+    }
     // 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 routeOfEvent.
@@ -280,6 +283,30 @@ async function runSignalStep(session, step, index, name, waitForSignal, signalTi
         },
     };
 }
+/**
+ * The index a replay resumes at, or `undefined` when `from` names no step of this flow.
+ *
+ * A step declared `commits` in the prefix refuses the resume (0 = replay everything): re-driving it
+ * is not setup, it is a second charge, a second email, a second record.
+ */
+export function resumeIndex(from, steps) {
+    if (from === undefined)
+        return 0;
+    const at = 'number' === typeof from ? from : steps.findIndex((step) => step.id === from);
+    if (at < 0 || at >= steps.length || !Number.isInteger(at))
+        return undefined;
+    return steps.slice(0, at).some((step) => StepEffect.COMMITS === step.effect) ? 0 : at;
+}
+/** The `from` argument, narrowed: a step index or a step id. */
+export function resumeArg(raw) {
+    return 'number' === typeof raw || ('string' === typeof raw && raw.length > 0) ? raw : undefined;
+}
+/** Why `from` cannot be resumed at, or undefined when it can (or was not given). */
+export function unresolvedResume(from, steps) {
+    if (resumeIndex(from, steps) !== undefined)
+        return undefined;
+    return `cannot resume at ${JSON.stringify(from)}: this flow has ${String(steps.length)} step(s) and no step by that id`;
+}
 /**
  * Run an `invoke` step: load the named flow and replay it, or fail saying why.
  *
@@ -291,7 +318,7 @@ async function runSignalStep(session, step, index, name, waitForSignal, signalTi
  * own, and the sub-journey's outcome is summarised on the invocation, so a reader sees the shape
  * they recorded rather than a flattened list that has lost every boundary.
  */
-async function runInvokeStep(session, flow, step, index, waitForSignal, signalTimeoutMs, confirmDangerous, sleep, options) {
+async function runInvokeStep(session, flow, step, index, waitForSignal, signalTimeoutMs, confirmDangerous, sleep, options, setup = false) {
     const name = step.invoke ?? '';
     const via = options.via ?? [];
     const here = { flow: flow.name, step: index, via };
@@ -313,7 +340,10 @@ async function runInvokeStep(session, flow, step, index, waitForSignal, signalTi
             error: `cannot replay "${name}": it was not found, so this journey would report green having never run it`,
         };
     }
-    const carried = options;
+    // `from` is an offset into the CALLER's steps. A sub-journey invoked from the setup prefix runs
+    // whole and unchecked (from = its length); one invoked at or after the resume point runs normally.
+    const { from: _outer, ...rest } = options;
+    const carried = setup ? { ...rest, from: sub.steps.length } : rest;
     const nested = await replayFlow(session, sub, waitForSignal, signalTimeoutMs, confirmDangerous, sleep, {
         ...carried,
         via: [{ flow: flow.name, step: index }, ...via],
@@ -331,6 +361,9 @@ async function runInvokeStep(session, flow, step, index, waitForSignal, signalTi
 }
 export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs, confirmDangerous = false, sleep = realSleep, options = {}) {
     const results = [];
+    // Steps before this index are setup. `from` was validated by the caller; an unresolvable one
+    // resumes nowhere rather than everywhere, so it cannot silently widen into a full replay.
+    const from = resumeIndex(options.from, flow.steps) ?? flow.steps.length;
     // testids whose region is LLM-dynamic — their expect-presence is NOT asserted.
     const dynamic = new Set((flow.dynamic ?? [])
         .filter((a) => a.kind === AnchorKind.TESTID)
@@ -347,8 +380,10 @@ export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs,
     try {
         for (const step of flow.steps) {
             if (step.invoke !== undefined) {
-                results.push(await runInvokeStep(session, flow, step, index, waitForSignal, signalTimeoutMs, confirmDangerous, sleep, options));
+                results.push(await runInvokeStep(session, flow, step, index, waitForSignal, signalTimeoutMs, confirmDangerous, sleep, options, index < from));
                 const last = results[results.length - 1];
+                if (last !== undefined && index < from && last.ok)
+                    results.pop();
                 if (last !== undefined && false === last.ok)
                     break;
                 index += 1;
@@ -404,7 +439,9 @@ export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs,
              * replay path and belongs in its own commit.
              */
             const declared = [step.expect, ...(step.steps ?? []).map((sub) => sub.expect)].filter((expectation) => expectation !== undefined);
-            for (const expectation of declared) {
+            // A setup step's consequence is not checked: it is re-driven to get somewhere, not to prove it.
+            const checked = index < from ? [] : declared;
+            for (const expectation of checked) {
                 if (!result.ok || result.drift !== undefined)
                     break;
                 const expectDrift = await assertStepExpect(session, expectation, waitForSignal, waitFor(step), cursorBefore);
@@ -415,6 +452,9 @@ export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs,
             }
             if (page !== undefined)
                 result.page = page;
+            const endPage = currentRoute(session);
+            if (endPage !== undefined && endPage !== page)
+                result.endPage = endPage;
             const windowEvents = session.eventsSince(cursorBefore).filter((e) => e.t >= cursorBefore);
             const consequence = summarizeConsequence(windowEvents);
             if (consequence !== undefined)
@@ -437,6 +477,12 @@ export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs,
             // forget the rule and quietly re-introduce the cost. Spelled out only when it is NOT the default.
             if (FlowStepTool.ACT === result.tool)
                 delete result.tool;
+            if (index < from && result.ok && result.drift === undefined) {
+                index += 1;
+                continue;
+            }
+            if (index < from)
+                result.note = `setup step for resuming at step ${String(from)} failed`;
             results.push(result);
             // Under `sweep`, a failure whose action still RAN does not stop the run — the page is where the
             // step left it, so the next step is as meaningful as it was going to be. Anything else halts.

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

@@ -33,3 +33,5 @@ export type FlowResult<T> = {
  * hold the distinction — this is the fourth id joined into a path, and the one that file missed.
  */
 export declare const safeProjectId: (projectId?: ProjectId) => ProjectId | undefined;
+/** Map a structured FlowErrorCode to a legible one-line message for the agent. */
+export declare function flowErrorMessage(code: FlowErrorCode, detail?: string): string;

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

@@ -1,5 +1,6 @@
 import { FlowErrorCode } from '@reticlehq/core';
 import { SAFE_SEGMENT_PATTERN } from '@reticlehq/core';
+import { FlowParseNote } from './flow-expect-grammar.js';
 /**
  * A project id that is safe to put in a path, or nothing.
  *
@@ -24,3 +25,27 @@ import { SAFE_SEGMENT_PATTERN } from '@reticlehq/core';
  * hold the distinction — this is the fourth id joined into a path, and the one that file missed.
  */
 export const safeProjectId = (projectId) => projectId !== undefined && SAFE_SEGMENT_PATTERN.test(projectId) ? projectId : undefined;
+/** Map a structured FlowErrorCode to a legible one-line message for the agent. */
+export function flowErrorMessage(code, detail) {
+    if (FlowErrorCode.PARSE_FAILED === code && undefined !== detail)
+        return detail;
+    // The detail names both versions and the remedy, so it beats anything generic this could say.
+    if (FlowErrorCode.WRONG_VERSION === code && undefined !== detail)
+        return detail;
+    switch (code) {
+        case FlowErrorCode.INVALID_NAME:
+            return 'invalid flow name — use a single safe segment (letters/digits/-/_), no path separators';
+        case FlowErrorCode.NOT_FOUND:
+            return 'no such flow on disk — run reticle_flow{action:"list"} to see saved flows';
+        case FlowErrorCode.PARSE_FAILED:
+            return FlowParseNote.MALFORMED;
+        case FlowErrorCode.NO_RECORDING:
+            return 'no compiled recording by that name — record one (reticle_record{action:"start"|"stop"}) first';
+        // Never "regenerate it": the file is intact and the reader is the wrong one. Telling somebody
+        // to rewrite an undamaged flow is the failure this code was split out of PARSE_FAILED to stop.
+        case FlowErrorCode.WRONG_VERSION:
+            return 'this flow file was written in a different flow-file format — the file is not damaged, this Reticle cannot read that version. Upgrade or downgrade Reticle rather than editing the flow';
+        case FlowErrorCode.STEP_NOT_FOUND:
+            return (detail ?? 'the step to resume at is not in this flow — pass a 0-based index or a step id');
+    }
+}

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

@@ -1,3 +1,4 @@
+import { flowAuthor } from './flow-author.js';
 import { FLOW_MUTATE_TOOL } from './flow-mutate-tools.js';
 import { seedSchema } from '../../surface/tools/args/numeric-bounds.js';
 import { z } from 'zod';
@@ -217,7 +218,12 @@ export const FLOW_TOOLS = [
             if (emptyRefusal !== undefined)
                 return Promise.resolve(emptyRefusal);
             const { flows, root } = flowsForSession(deps, projectId);
-            const toSave = saveAs === undefined ? program : { ...program, name: saveAs };
+            const author = flowAuthor();
+            const toSave = {
+                ...program,
+                ...(saveAs === undefined ? {} : { name: saveAs }),
+                ...(author === undefined ? {} : { author }),
+            };
             return flows.save(toSave, annotations, projectId).then(async (res) => {
                 if (!res.ok)
                     return { error: flowErrorMessage(res.code, res.detail), code: res.code };
@@ -382,6 +388,10 @@ export const FLOW_TOOLS = [
                 .boolean()
                 .optional()
                 .describe('Set true to allow destructive controls during this replay only.'),
+            from: z
+                .union([z.number().int().nonnegative(), z.string().min(1)])
+                .optional()
+                .describe('Resume at this step (index or step id). Earlier steps re-run as unchecked, unreported setup; a setup step marked effect:"commits" refuses the resume.'),
             sweep: z
                 .boolean()
                 .optional()
@@ -636,9 +646,7 @@ export const FLOW_TOOLS = [
                     return flow === undefined ? { replay } : { replay, flow };
                 }));
                 const timed = outcomes.map((o, i) => ({
-                    replay: o.ok && o.value !== undefined
-                        ? o.value.replay
-                        : leaseFailureReplay(requested[i] ?? '', o.error),
+                    ...(parallelRuns[i] ?? { replay: leaseFailureReplay(requested[i] ?? '', o.error) }),
                     durationMs: o.ok && o.value !== undefined ? o.value.durationMs : 0,
                 }));
                 const flaky = await recordSuiteFlakes(deps.fs, rootForProjectId(deps, projectId), parallelRuns);
@@ -671,7 +679,11 @@ export const FLOW_TOOLS = [
                     .catch(() => null);
                 const flow = loaded !== null && loaded.ok ? loaded.value : undefined;
                 runs.push(flow === undefined ? { replay } : { replay, flow });
-                timed.push({ replay, durationMs: deps.now() - start });
+                timed.push({
+                    replay,
+                    durationMs: deps.now() - start,
+                    ...(flow === undefined ? {} : { flow }),
+                });
             }
             // The flake ledger the CLI gate already keeps — see FlakeStore. It was only ever written by
             // `reticle flow` on the command line, so an AGENT running this tool a hundred times learned

package/dist/language/flows/flows.d.ts

@@ -1,5 +1,5 @@
 import { type Predicate, type ProjectId } from '@reticlehq/core';
-export { REDACTED_FILL } from './fields/flow-secret-field.js';
+export { REDACTED_FILL, secretEnvKey } from './fields/flow-secret-field.js';
 import { type FlowResult } from './flow-result.js';
 export type { FlowResult } from './flow-result.js';
 import type { FlowAnchor, FlowFile, FlowStep, HealChange, InstrumentationGap } from '@reticlehq/core';
@@ -65,6 +65,15 @@ export declare class FlowStore {
      * the flow before writing. Omitting `annotations` reproduces the same bytes.
      */
     save(program: CompiledProgram, annotations?: FlowAnnotations, projectId?: ProjectId): Promise<FlowResult<SaveSummary>>;
+    /**
+     * Save a flow the session drove, folded into any saved copy of the same journey.
+     *
+     * Every session saves its own drive, so one journey arrived as a near-copy per session. Flows
+     * under `prefix` (the auto-saved ones — a hand-named flow is never merged or removed) that start
+     * on the same page and take the same steps become ONE file: the oldest keeps its name, the others
+     * fill its gaps and are removed. The same scan collapses copies saved before this existed.
+     */
+    saveJourney(program: CompiledProgram, projectId: ProjectId | undefined, prefix: string): Promise<FlowResult<SaveSummary>>;
     /**
      * Persist an already-anchored FlowFile captured in-page (no recompilation). The
      * browser resolved every semantic anchor at capture time; here we only validate the name +