@reticlehq/server 3.3.0 → 3.4.0

package/dist/judgement/runs/artifact/replay-mapping.js

@@ -4,21 +4,52 @@
  * perspective a flow that drifted no longer behaves, so it must not read as green. The actionable
  * "why" is lifted from the replay's decision envelope (or its error) into failureReason.
  */
-import { ReplayStatus, RunFlowStatus, } from '@reticlehq/core';
+import { ReplayStatus, RUN_RECORDING_MAX_BYTES, RUN_STEP_RESULTS_MAX, RUN_TEXT_MAX, RunFlowStatus, } from '@reticlehq/core';
 import { SUCCESS_STEP_TOOL } from '../../../language/flows/flow-success.js';
 /** OK → PASS; DRIFT/ERROR → FAIL (a healed flow is produced by the heal path, not plain replay). */
 export function runFlowStatusOf(status) {
     return status === ReplayStatus.OK ? RunFlowStatus.PASS : RunFlowStatus.FAIL;
 }
+const clip = (text) => text.length > RUN_TEXT_MAX ? `${text.slice(0, RUN_TEXT_MAX - 1)}…` : text;
+/** One step as synced: what it did, where, and whether it held. */
+function stepResultOf(step) {
+    return {
+        step: step.step,
+        anchor: clip(step.anchor),
+        ok: step.ok,
+        ...(step.page === undefined ? {} : { page: step.page }),
+        ...(step.endPage === undefined ? {} : { endPage: step.endPage }),
+        ...(step.consequence === undefined ? {} : { consequence: clip(step.consequence) }),
+        ...(step.error === undefined ? {} : { error: clip(step.error) }),
+        ...(step.drift === undefined ? {} : { drift: step.drift.reasonKind }),
+    };
+}
+/**
+ * The flow as recorded, when it is small enough to travel — what lets a teammate replay this run
+ * from the cloud. Fill values were already redacted when the flow was saved.
+ */
+function recordingOf(flow) {
+    const recording = {
+        ...(flow.startPath === undefined ? {} : { startPath: flow.startPath }),
+        steps: flow.steps,
+    };
+    return Buffer.byteLength(JSON.stringify(recording)) > RUN_RECORDING_MAX_BYTES
+        ? { recordingOmitted: true }
+        : { recording };
+}
 /** Map one replay (plus its measured duration) into a RunFlowResult for the artifact's flows[]. */
-export function mapReplayToFlowResult(replay, durationMs) {
-    const status = runFlowStatusOf(replay.status);
-    const failureReason = status === RunFlowStatus.FAIL
-        ? (replay.decision?.whatChanged ??
-            replay.decision?.summary ??
-            replay.error?.message ??
-            'flow failed')
-        : undefined;
+export function mapReplayToFlowResult(replay, durationMs, flow) {
+    // A replay that could not start returns OK with no steps. Nothing ran, so it is SKIPPED — which
+    // every reader of a run (the verdict, the gate) already refuses to count as a pass.
+    const status = replay.unverifiable === undefined ? runFlowStatusOf(replay.status) : RunFlowStatus.SKIPPED;
+    const failureReason = replay.unverifiable !== undefined
+        ? replay.unverifiable.reason
+        : status === RunFlowStatus.FAIL
+            ? (replay.decision?.whatChanged ??
+                replay.decision?.summary ??
+                replay.error?.message ??
+                'flow failed')
+            : undefined;
     // A flow with a success oracle gets a synthetic 'success' step appended by replay; surface its label
     // as the run's `oracle` so the verdict counts this flow as consequence-backed (→ HIGH confidence),
     // not a bare smoke click. Without this, an oracle-backed pass reads as MEDIUM and undersells itself.
@@ -30,5 +61,9 @@ export function mapReplayToFlowResult(replay, durationMs) {
         durationMs,
         ...(oracle !== undefined ? { oracle } : {}),
         ...(failureReason !== undefined ? { failureReason } : {}),
+        ...(0 === replay.steps.length
+            ? {}
+            : { stepResults: replay.steps.slice(0, RUN_STEP_RESULTS_MAX).map(stepResultOf) }),
+        ...(flow === undefined ? {} : recordingOf(flow)),
     };
 }

package/dist/judgement/runs/verification-sync.d.ts

@@ -1,9 +1,11 @@
-import { type ProjectId, type FlowReplayResult } from '@reticlehq/core';
+import { type ProjectId, type FlowFile, type FlowReplayResult } from '@reticlehq/core';
 import type { ToolDeps } from '../../surface/tools/tool-kit.js';
 /** A replay plus the wall-clock time it took — the shape the verify handler already collects. */
 export interface TimedReplay {
     replay: FlowReplayResult;
     durationMs: number;
+    /** The flow file that was replayed, so the synced run can carry its recording. */
+    flow?: FlowFile;
 }
 /**
  * Persist the suite's run artifact and best-effort mirror it to the cloud. Never throws into the verify

package/dist/judgement/runs/verification-sync.js

@@ -23,7 +23,7 @@ import { rootForProjectId } from '../../memory/project/session-root.js';
 const RETICLE_MCP_AGENT_ID = 'reticle-mcp';
 /** Assemble the ReticleVerificationRun artifact for a verify suite (pure — no IO). */
 function assembleRun(deps, timed, projectId) {
-    const flows = timed.map((t) => mapReplayToFlowResult(t.replay, t.durationMs));
+    const flows = timed.map((t) => mapReplayToFlowResult(t.replay, t.durationMs, t.flow));
     const input = {
         runId: defaultRunId(),
         durationMs: flows.reduce((sum, f) => sum + f.durationMs, 0),

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

@@ -22,3 +22,12 @@ export interface AffectedResult {
  * a repo-relative change matches an absolute stamp and vice-versa.
  */
 export declare function affectedFlows(flows: readonly FlowSources[], changedFiles: readonly string[]): AffectedResult;
+export declare function isInteractiveSource(text: string): boolean;
+/**
+ * Changed interactive components that no saved flow's manifest names.
+ *
+ * `affectedFlows` starts from the flows, so a file no flow ever touched affects nothing — and a gate
+ * built only on it passed a brand-new feature that had never been driven. This starts from the
+ * change instead. `isInteractive` is injected so the decision stays pure; the CLI reads the file.
+ */
+export declare function unflowedFiles(flows: readonly FlowSources[], changedFiles: readonly string[], isInteractive: (file: string) => boolean): string[];

package/dist/language/flows/change/affected.js

@@ -33,3 +33,38 @@ export function affectedFlows(flows, changedFiles) {
     }
     return { affected, unknownProvenance };
 }
+/** A file a source stamper can put on an element — the only files a flow's manifest can ever name. */
+const COMPONENT_FILE = /\.(?:jsx|tsx|vue|svelte|astro)$/;
+/** Same test-file rule the stampers use, so a test is never demanded a flow. */
+const TEST_FILE = /(?:\.(?:test|spec)\.[^./]+$)|(?:^|\/)__tests__\//;
+/**
+ * Something a step could act on: a handler prop (`onClick=`, `@click`, `v-on:`, `on:submit`) or a
+ * native control.
+ *
+ * ponytail: a text heuristic, not a parse. A flow's manifest only names the file of the element a
+ * step ACTED on, so a display-only component can never be attributed and demanding a flow for one
+ * would block forever. A handler passed in from a parent under another name escapes it; upgrade to
+ * recording the source of the element an `expect` matched if that proves common.
+ */
+const INTERACTIVE = /\bon[A-Z]\w*=|@[a-z]+[=.]|\bv-on:|\bon:[a-z]+|<(?:button|input|select|textarea|form|a|summary)[\s>/]/;
+export function isInteractiveSource(text) {
+    return INTERACTIVE.test(text);
+}
+/**
+ * Changed interactive components that no saved flow's manifest names.
+ *
+ * `affectedFlows` starts from the flows, so a file no flow ever touched affects nothing — and a gate
+ * built only on it passed a brand-new feature that had never been driven. This starts from the
+ * change instead. `isInteractive` is injected so the decision stays pure; the CLI reads the file.
+ */
+export function unflowedFiles(flows, changedFiles, isInteractive) {
+    const sources = flows.flatMap((flow) => (flow.sources ?? []).map(normalize));
+    return changedFiles.filter((file) => {
+        const c = normalize(file);
+        if (!COMPONENT_FILE.test(c) || TEST_FILE.test(c))
+            return false;
+        if (sources.some((s) => c === s || c.endsWith(`/${s}`) || s.endsWith(`/${c}`)))
+            return false;
+        return isInteractive(file);
+    });
+}

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

@@ -22,6 +22,16 @@ interface GateInput {
     downgraded?: readonly DowngradedFlow[];
     /** Flows that covered a changed file but no longer exist — coverage deleted rather than satisfied. */
     deleted?: readonly string[];
+    /** Changed interactive components no saved flow touches — a change nothing has driven. */
+    unflowed?: readonly string[];
+    /** Coverage levels below the best they ever reached — something new appeared, nothing covered it. */
+    coverageRegressed?: readonly {
+        level: string;
+        was: number;
+        now: number;
+    }[];
+    /** Changed files the browser loaded and never ran a function of. */
+    unexecuted?: readonly string[];
 }
 interface GateResult {
     /** True when every affected, non-flaky flow has a passing artifact AND nothing was weakened/deleted. */
@@ -34,6 +44,16 @@ interface GateResult {
     downgraded: DowngradedFlow[];
     /** Deleted flows that covered changed files — BLOCKING for the same reason. */
     deleted: string[];
+    /** Changed interactive components no flow covers — BLOCKING: the change was never driven. */
+    unflowed: string[];
+    /** BLOCKING: the app grew something nothing has covered. */
+    coverageRegressed: {
+        level: string;
+        was: number;
+        now: number;
+    }[];
+    /** BLOCKING: changed code that never ran in any drive. */
+    unexecuted: string[];
 }
 export declare function gateDecision(input: GateInput): GateResult;
 export {};

package/dist/language/flows/change/gate.js

@@ -23,11 +23,22 @@ export function gateDecision(input) {
     // trivially gameable, which is the exact failure this gate exists to prevent.
     const downgraded = [...(input.downgraded ?? [])];
     const deleted = [...(input.deleted ?? [])];
+    const unflowed = [...(input.unflowed ?? [])];
+    const coverageRegressed = [...(input.coverageRegressed ?? [])];
+    const unexecuted = [...(input.unexecuted ?? [])];
     return {
-        pass: 0 === uncovered.length && 0 === downgraded.length && 0 === deleted.length,
+        pass: 0 === uncovered.length &&
+            0 === downgraded.length &&
+            0 === deleted.length &&
+            0 === unflowed.length &&
+            0 === coverageRegressed.length &&
+            0 === unexecuted.length,
         uncovered,
         quarantined,
         downgraded,
         deleted,
+        unflowed,
+        coverageRegressed,
+        unexecuted,
     };
 }

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

@@ -0,0 +1,7 @@
+import type { FlowFile } from '@reticlehq/core';
+/**
+ * Who is making a flow right now: the agent that announced itself over MCP, and the person signed in
+ * to Reticle on this machine. A key handed over in the environment names no person, so none is
+ * written — the cloud can still attribute the push by the key that sent it.
+ */
+export declare function flowAuthor(env?: NodeJS.ProcessEnv, home?: string): FlowFile['author'];

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

@@ -0,0 +1,19 @@
+import { homedir } from 'node:os';
+import { mcpClientIdentity } from '../../surface/mcp/peer/client-identity.js';
+import { readAccountState } from '../../memory/cloud/account-state.js';
+/**
+ * Who is making a flow right now: the agent that announced itself over MCP, and the person signed in
+ * to Reticle on this machine. A key handed over in the environment names no person, so none is
+ * written — the cloud can still attribute the push by the key that sent it.
+ */
+export function flowAuthor(env = process.env, home = homedir()) {
+    const agent = mcpClientIdentity().name;
+    const account = readAccountState(home, env);
+    const person = account.signedIn ? account.email : undefined;
+    if (agent === undefined && person === undefined)
+        return undefined;
+    return {
+        ...(agent === undefined ? {} : { agent }),
+        ...(person === undefined ? {} : { person }),
+    };
+}

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

@@ -215,7 +215,7 @@ export function parseFlowFileText(text) {
             ok: false,
             code: FlowErrorCode.WRONG_VERSION,
             detail: `this flow file is version ${String(declared)} and this Reticle reads versions ` +
-                `${[...READABLE_FLOW_VERSIONS].join(' and ')}. The file is not damaged, the reader is the ` +
+                `${[...READABLE_FLOW_VERSIONS].join(', ')}. The file is not damaged, the reader is the ` +
                 'wrong one. ' +
                 'Upgrade or downgrade Reticle rather than editing the flow.',
         };

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

@@ -0,0 +1,54 @@
+import { type FlowFile, type FlowStep, type Predicate } from '@reticlehq/core';
+/** A short, stable identity for a journey's shape: its start page and its steps. */
+export declare function journeyFingerprint(flow: Pick<FlowFile, 'startPath' | 'steps'>): string;
+/**
+ * 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 declare function mergeJourney(kept: FlowFile, other: FlowFile): FlowFile;
+/**
+ * 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 declare function journeyName(base: string, fingerprint: string, taken: ReadonlyMap<string, string>): string;
+/**
+ * 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 declare function routeClaims(startPath: string | undefined, steps: readonly FlowStep[]): {
+    requires?: Predicate[];
+    ensures?: Predicate[];
+};
+/**
+ * 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 declare function establishedState(flow: FlowFile): readonly Predicate[];
+/**
+ * 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 declare function samePath(observed: string, expected: string): boolean;

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[]>;