@reticlehq/server 3.6.0 → 3.7.0

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

@@ -8,12 +8,14 @@
  * lighter per-flow RunRecord that feeds regression memory is synced separately in flow-replay-run.ts.
  * Both are best-effort + opt-in: no creds → the artifact still lands on disk, nothing leaves the machine.
  */
-import { mcpClientIdentity } from '../../surface/mcp/peer/client-identity.js';
-import { RunAgentKind, RunFramework, RunProfile, RunTrigger, } from '@reticlehq/core';
+import { callerClientName } from '../../hooks/coding-agents.js';
+import { currentDrivenBy } from '../../hooks/driven-by.js';
+import { RunAgentKind, RunFramework, RunProfile, RunTrigger, asRunId, } from '@reticlehq/core';
 import { homedir } from 'node:os';
 import { buildVerificationRun, } from './artifact/build-verification-run.js';
 import { mapReplayToFlowResult } from './artifact/replay-mapping.js';
 import { defaultRunId } from './default-run-id.js';
+import { currentShotRun } from './default-run-id.js';
 import { RunStore } from './artifact/run-store.js';
 import { cloudFetch, syncRunToCloud, SyncOutcome } from '../../memory/cloud/cloud-sync.js';
 import { resolveProjectCloud } from '../../memory/cloud/cloud-config.js';
@@ -21,29 +23,43 @@ import { log } from '../../log.js';
 import { rootForTarget } from '../../memory/project/session-root.js';
 /** The author of record when no MCP peer introduced itself — a CLI run, or a client that skipped the handshake. */
 const RETICLE_MCP_AGENT_ID = 'reticle-mcp';
+/** The MCP client name `reticle verify` (the command line, CI's path) connects to a daemon as. */
+export const CLI_CLIENT_NAME = 'reticle-cli';
+/**
+ * Who ran a suite, and why. The command line is the pipeline, whichever daemon replays for it:
+ * through a running daemon its runs read as a coding agent, trigger manual, credited to whoever
+ * minted the key, while the path that boots its own daemon said pipeline.
+ */
+function agentAndTrigger(client) {
+    return CLI_CLIENT_NAME === client
+        ? { agent: { id: client, kind: RunAgentKind.OEM_PIPELINE }, trigger: { kind: RunTrigger.OEM } }
+        : {
+            agent: { id: client ?? RETICLE_MCP_AGENT_ID, kind: RunAgentKind.CODING_AGENT },
+            trigger: { kind: RunTrigger.MANUAL },
+        };
+}
 /** Assemble the ReticleVerificationRun artifact for a verify suite (pure — no IO). */
-function assembleRun(deps, timed, projectId) {
+function assembleRun(deps, timed, 
+/** The dashboard project this checkout is linked to, else the session's own id. */
+projectName) {
     const flows = timed.map((t) => mapReplayToFlowResult(t.replay, t.durationMs, t.flow));
     const input = {
-        runId: defaultRunId(),
+        // The run its replays' screenshots were filed under, when the verify minted one first.
+        runId: asRunId(currentShotRun() ?? defaultRunId()),
         durationMs: flows.reduce((sum, f) => sum + f.durationMs, 0),
         profile: RunProfile.DEV,
-        project: { name: projectId ?? 'reticle', framework: RunFramework.OTHER },
+        project: { name: projectName ?? 'reticle', framework: RunFramework.OTHER },
         /*
          * WHICH agent drove this, not merely THAT one did.
          *
          * This was hardcoded to 'reticle-mcp', so every run in every workspace claimed the same author.
          * A dashboard built on it could say "an agent verified this" and never "Claude Code verified
          * this, Cursor broke it" — which is the question a team actually has once more than one agent
-         * touches the repo. The name is the client's own claim from the MCP handshake; a plain CLI run
-         * with no MCP peer keeps the old id, because inventing a vendor there would be worse than
-         * admitting we do not know.
+         * touches the repo. The name is the client's own claim from the MCP handshake, for the call that
+         * ran this suite only; a plain CLI run, or a dashboard Re-verify no agent made, keeps the old id,
+         * because inventing a vendor there would be worse than admitting we do not know.
          */
-        agent: {
-            id: mcpClientIdentity().name ?? RETICLE_MCP_AGENT_ID,
-            kind: RunAgentKind.CODING_AGENT,
-        },
-        trigger: { kind: RunTrigger.MANUAL },
+        ...agentAndTrigger(callerClientName()),
         changedFiles: [],
         flows,
         checks: [],
@@ -61,6 +77,10 @@ export async function persistAndSyncVerificationRun(deps, timed, target) {
     const { projectId } = target;
     if (0 === timed.length)
         return undefined;
+    // A replay the Harness made inside its own drive is part of that drive's run: written on its own
+    // it was a second row ("Passed · Flow replay · Your agent") beside the plan run it belonged to.
+    if (currentDrivenBy() !== undefined)
+        return undefined;
     let run;
     // The project the suite ran for, not the directory the daemon was started in. Both halves below
     // take it: the artifact `reticle_run` reads back through `sessionRoot`, and the cloud link that
@@ -68,8 +88,10 @@ export async function persistAndSyncVerificationRun(deps, timed, target) {
     // a misrouted read silently meant "not attached" — and where it DID have one, the run was pushed
     // to a dashboard belonging to whoever that checkout was linked to.
     const root = rootForTarget(deps, target);
+    const cloud = await resolveProjectCloud(deps.fs, root, homedir(), process.env);
     try {
-        run = assembleRun(deps, timed, projectId);
+        // Named after the dashboard project the checkout is linked to: a Re-verify run read "reticle".
+        run = assembleRun(deps, timed, cloud.projectId ?? projectId);
         await new RunStore(deps.fs, root).write(run);
     }
     catch (error) {
@@ -79,7 +101,6 @@ export async function persistAndSyncVerificationRun(deps, timed, target) {
         return undefined;
     }
     // Per-project cloud: only push when THIS project has cloud attached AND its policy allows runs.
-    const cloud = await resolveProjectCloud(deps.fs, root, homedir(), process.env);
     if (null === cloud.config || !cloud.policy.runs)
         return run.runId; // not attached / runs disabled → local only
     const result = await syncRunToCloud(run, cloud.config, cloudFetch);

package/dist/language/flows/decision.js

@@ -165,7 +165,8 @@ invoked = new Map()) {
             ...(fix !== undefined ? { suggestedFix: fix } : {}),
             nextAction: fix !== undefined
                 ? `${fix}, or update the flow if the change was intended.`
-                : `inspect ${where ?? 'the step'} — the anchored element is gone; rebind or update the flow.`,
+                : `inspect ${where ?? 'the step'} — the anchored element is not on the page and nothing there looks like a rename. ` +
+                    'If the replay began somewhere the recording did not (signed out, another route), record the steps that reach this one; otherwise rebind or update the flow.',
         };
     }
     // status error: an action failed, or the success oracle was not satisfied (green-but-wrong).

package/dist/language/flows/fields/flow-secret-field.d.ts

@@ -1,4 +1,6 @@
+import { z } from 'zod';
 import { type FlowAnchor, type FlowFile } from '@reticlehq/core';
+import { CALL_SECRETS_ARG } from '../../../surface/tools/tool-kit.js';
 /**
  * What the anchor CALLS the field it points at.
  *
@@ -20,6 +22,8 @@ export declare function anchorFieldName(anchor: FlowAnchor): string | undefined;
  * reader what to do: the value belongs in the environment, not in a file they are about to commit.
  */
 export declare const REDACTED_FILL = "<redacted: supply at replay>";
+/** The arg a saved redacted fill names its variable in. Dropped before the step reaches the page. */
+export declare const SECRET_NAME_ARG = "secret";
 /**
  * The environment variable that supplies one redacted field.
  *
@@ -33,6 +37,14 @@ export declare const REDACTED_FILL = "<redacted: supply at replay>";
  * saying it had to stay together.
  */
 export declare const secretEnvKey: (field: string) => string;
+/** The schema of that argument, shared by every tool that replays a flow. */
+export { CALL_SECRETS_ARG };
+export declare const callSecretsArg: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+/**
+ * One secret's value: supplied with this call (by field or by variable name), else from the
+ * daemon's environment.
+ */
+export declare function secretValue(envKey: string, env: Record<string, string | undefined>): string | undefined;
 /** One field a flow needs supplied, and the variable that supplies it. */
 export interface UnsuppliedSecret {
     field: string;

package/dist/language/flows/fields/flow-secret-field.js

@@ -1,4 +1,6 @@
+import { z } from 'zod';
 import { AnchorKind } from '@reticlehq/core';
+import { CALL_SECRETS_ARG, callSecrets } from '../../../surface/tools/tool-kit.js';
 /**
  * What the anchor CALLS the field it points at.
  *
@@ -28,6 +30,10 @@ export function anchorFieldName(anchor) {
  * reader what to do: the value belongs in the environment, not in a file they are about to commit.
  */
 export const REDACTED_FILL = '<redacted: supply at replay>';
+/** The arg a saved redacted fill names its variable in. Dropped before the step reaches the page. */
+export const SECRET_NAME_ARG = 'secret';
+/** The prefix every secret's variable carries. */
+const SECRET_ENV_PREFIX = 'RETICLE_SECRET_';
 /**
  * The environment variable that supplies one redacted field.
  *
@@ -40,7 +46,24 @@ export const REDACTED_FILL = '<redacted: supply at replay>';
  * rules must not be able to drift. It used to sit in `replay.ts`, one import away from the sentence
  * saying it had to stay together.
  */
-export const secretEnvKey = (field) => `RETICLE_SECRET_${field.replace(/[^a-zA-Z0-9]+/g, '_').toUpperCase()}`;
+export const secretEnvKey = (field) => `${SECRET_ENV_PREFIX}${field.replace(/[^a-zA-Z0-9]+/g, '_').toUpperCase()}`;
+/** The schema of that argument, shared by every tool that replays a flow. */
+export { CALL_SECRETS_ARG };
+export const callSecretsArg = z
+    .record(z.string())
+    .optional()
+    .describe('Redacted fields\' values, this call only, never kept: { "auth-password": "…" }');
+/**
+ * One secret's value: supplied with this call (by field or by variable name), else from the
+ * daemon's environment.
+ */
+export function secretValue(envKey, env) {
+    for (const [key, value] of Object.entries(callSecrets() ?? {})) {
+        if (envKey === (key.startsWith(SECRET_ENV_PREFIX) ? key : secretEnvKey(key)))
+            return value;
+    }
+    return env[envKey];
+}
 /**
  * Every credential this flow will replay as the literal placeholder.
  *
@@ -63,7 +86,7 @@ export function unsuppliedSecrets(flow, env) {
         if (field === undefined)
             continue;
         const envKey = secretEnvKey(field);
-        const supplied = env[envKey];
+        const supplied = secretValue(envKey, env);
         if (supplied !== undefined && supplied.length > 0)
             continue;
         if (seen.has(envKey))

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

@@ -16,8 +16,13 @@ import type { FlowReplaySession, Sleep } from './flow-replay-types.js';
 export declare function editDistance(a: string, b: string): number;
 /**
  * The closest present testid to a missing one, by case-insensitive edit distance, ties broken
- * by shortest length then lexically. Returns null only when nothing is present — so a drift
- * record always names a fix when one exists ("whose fault is it": here is the closest survivor).
+ * by shortest length then lexically — when it is close enough to be a rename. Null when nothing
+ * present is, so a drift record names a fix only when one plausibly exists.
+ *
+ * It used to name the closest survivor however far away it was. A replay that started signed out
+ * missed `compose-prompt` on the login screen and advised rebinding it to `login-submit`: eleven
+ * edits away, a different control on a different page, offered as the fix. Half the longer name is
+ * the ceiling — `chat-send` → `chat-submit` and `checkout-btn` → `checkout-button` stay in.
  */
 export declare function nearestTestid(missing: string, present: string[]): string | null;
 /**

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

@@ -35,8 +35,13 @@ export function editDistance(a, b) {
 }
 /**
  * The closest present testid to a missing one, by case-insensitive edit distance, ties broken
- * by shortest length then lexically. Returns null only when nothing is present — so a drift
- * record always names a fix when one exists ("whose fault is it": here is the closest survivor).
+ * by shortest length then lexically — when it is close enough to be a rename. Null when nothing
+ * present is, so a drift record names a fix only when one plausibly exists.
+ *
+ * It used to name the closest survivor however far away it was. A replay that started signed out
+ * missed `compose-prompt` on the login screen and advised rebinding it to `login-submit`: eleven
+ * edits away, a different control on a different page, offered as the fix. Half the longer name is
+ * the ceiling — `chat-send` → `chat-submit` and `checkout-btn` → `checkout-button` stay in.
  */
 export function nearestTestid(missing, present) {
     let best = null;
@@ -53,7 +58,9 @@ export function nearestTestid(missing, present) {
             bestDistance = distance;
         }
     }
-    return best;
+    if (null === best)
+        return null;
+    return bestDistance <= Math.max(missing.length, best.length) / 2 ? best : null;
 }
 /**
  * Bounded settle for anchor re-resolution. A testid step queries the live DOM for the anchor; if a

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

@@ -49,4 +49,5 @@ export declare function dischargeFlowIntent(store: IntentStore, flow: FlowFile,
     verdictId: string;
     grade: string;
     at: number;
+    runId?: string;
 }): Promise<boolean>;

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

@@ -1,6 +1,12 @@
 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;
+/**
+ * Whether `shorter` is `longer` driven with steps left out: same start, and its steps appear in
+ * `longer` in the same order. A re-drive that retried a step, or stopped one short, is the same
+ * journey; two flows that share only a name and a page are not.
+ */
+export declare function withinJourney(longer: Pick<FlowFile, 'startPath' | 'steps'>, shorter: Pick<FlowFile, 'startPath' | 'steps'>): boolean;
 /**
  * Fold two copies of one journey into one file.
  *

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

@@ -31,6 +31,26 @@ export function journeyFingerprint(flow) {
         .digest('hex')
         .slice(0, FINGERPRINT_LENGTH);
 }
+/**
+ * Whether `shorter` is `longer` driven with steps left out: same start, and its steps appear in
+ * `longer` in the same order. A re-drive that retried a step, or stopped one short, is the same
+ * journey; two flows that share only a name and a page are not.
+ */
+export function withinJourney(longer, shorter) {
+    if ((longer.startPath ?? null) !== (shorter.startPath ?? null))
+        return false;
+    const shapes = longer.steps.map((step) => JSON.stringify(stepShape(step)));
+    let at = 0;
+    for (const step of shorter.steps) {
+        const wanted = JSON.stringify(stepShape(step));
+        while (at < shapes.length && shapes[at] !== wanted)
+            at += 1;
+        if (at === shapes.length)
+            return false;
+        at += 1;
+    }
+    return true;
+}
 /** `kept` wins wherever it says something; `other` fills only what `kept` left unsaid. */
 function fillStep(kept, other) {
     if (other === undefined)

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

@@ -53,3 +53,7 @@ export declare function replayAndLearn(deps: ToolDeps,
 args: Record<string, unknown>): Promise<FlowReplayResult>;
 /** Write back the files a clean replay's anchors resolved to. Best-effort, as `persistLearning` is. */
 export declare function persistSources(deps: ToolDeps, args: Record<string, unknown>, sources: Parameters<typeof withLearnedSources>[1]): Promise<void>;
+/** A replay, under seeded perturbation when `seed` asks for one; the page is always put back. */
+export declare function replaySeededOrNot(deps: ToolDeps, args: Record<string, unknown>, 
+/** Where the perturbation port finds the page: the app's origin. */
+appUrl: string | undefined): Promise<FlowReplayResult>;

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

@@ -1,4 +1,6 @@
-import { asString } from '@reticlehq/core';
+import { runSavedFlow } from '../../hooks/driven-by.js';
+import { asNumber, asString, mutationTargetsFor, perturbationFor } from '@reticlehq/core';
+import { sessionPerturbationPort } from '../../surface/tools/lease-tools.js';
 import { flowsForSession } from './flow-store-for-session.js';
 import { safeSessionTarget } from '../../memory/project/session-root.js';
 import { replayNamedFlow } from './flow-replay-run.js';
@@ -73,10 +75,11 @@ export async function replayAndLearn(deps,
  */
 args) {
     let recorded;
-    const result = await replayNamedFlow(deps, args, (session) => {
+    // A saved flow's steps were asked for by whoever recorded it: no outward gate on them.
+    const result = await runSavedFlow(() => replayNamedFlow(deps, args, (session) => {
         recorded = recordingSources(session);
         return recorded.session;
-    });
+    }));
     // Only a clean run teaches a file: a drifted step may have resolved to the wrong element.
     if (result.status === ReplayStatus.OK && recorded !== undefined && recorded.sources.size > 0) {
         await persistSources(deps, args, recorded.sources);
@@ -102,3 +105,34 @@ export async function persistSources(deps, args, sources) {
         // Bookkeeping only.
     }
 }
+/** A replay, under seeded perturbation when `seed` asks for one; the page is always put back. */
+export async function replaySeededOrNot(deps, args, 
+/** Where the perturbation port finds the page: the app's origin. */
+appUrl) {
+    const seed = asNumber(args['seed']);
+    if (seed === undefined)
+        return await replayAndLearn(deps, args);
+    /*
+     * The targets are the endpoints the FLOW declared it depends on, so the perturbation lands on
+     * traffic the flow claims to care about. No declared endpoints means nothing to slow, and the
+     * replay runs clean rather than pretending a seed did something. `finally` is not tidiness: a
+     * page left slowed is damage the NEXT run inherits, as a mystery.
+     */
+    const target = targetOf(deps, args);
+    const loaded = await flowsForSession(deps, target)
+        .flows.load(asString(args['flowName']) ?? asString(args['flow']) ?? '', target.projectId)
+        .catch(() => null);
+    const targets = loaded !== null && loaded.ok ? mutationTargetsFor(loaded.value) : [];
+    const rules = perturbationFor(seed, targets);
+    const port = 0 === rules.length ? undefined : await sessionPerturbationPort(deps.realInput, appUrl);
+    if (port === undefined)
+        return replayAndLearn(deps, args);
+    try {
+        await port.slow(rules);
+        const replay = await runSavedFlow(() => replayNamedFlow(deps, args));
+        return { ...replay, perturbed: rules };
+    }
+    finally {
+        await port.clear().catch(() => undefined);
+    }
+}

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

@@ -4,7 +4,7 @@ import { EventType, FLOW_SIGNAL_TIMEOUT_MS, FlowErrorCode, RecordedFlowSchema, R
 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 { navigablePath, routeOfEvent, routeOfUrl, } from '@reticlehq/engine/question/predicate/predicate-route.js';
 import { carryReticleIdentity } from '../../surface/tools/lease-tools.js';
 import { partialStatus, replayFlow, replayWindow } from './flow-replay.js';
 import { anchorPrecondition, anchorQueryArgs, staleTargetResult } from './flow-step-runners.js';
@@ -28,9 +28,10 @@ import { EnvelopeStore } from '../../memory/journal/envelope-store.js';
 import { homedir } from 'node:os';
 import { cloudFetch, syncRunRecordToCloud, SyncOutcome } from '../../memory/cloud/cloud-sync.js';
 import { resolveProjectCloud } from '../../memory/cloud/cloud-config.js';
-import { memoryReadUrl, scopedMemoryEntries } from '../../memory/cloud/memory-scope.js';
+import { memoryReadHeaders, memoryReadUrl, scopedMemoryEntries, } from '../../memory/cloud/memory-scope.js';
 import { consultSubjectFor, selectConsulted } from './flow-memory-consult.js';
 import { log } from '../../log.js';
+import { replayStepShooter } from '../../features/visual/step-shots.js';
 import { flowsForSession } from './flow-store-for-session.js';
 import { projectForRoot } from '../../memory/project/project-for-root.js';
 import { CROSS_STEP_INDEX, crossStepOnly } from './flow-cross-step.js';
@@ -46,7 +47,7 @@ export function latestRecordedFlow(events) {
     return undefined;
 }
 export { flowErrorMessage } from './flow-result.js';
-import { flowErrorMessage } from './flow-result.js';
+import { flowErrorMessage, noteReplayCheck } from './flow-result.js';
 /** Map the wire ReplayStatus onto the persisted RunStatus (ok→pass). */
 function replayToRunStatus(status) {
     switch (status) {
@@ -107,13 +108,14 @@ function currentPathOf(session) {
     // query usually decides what the page renders, so a tab on `?tab=summary` would read as "already
     // at `?tab=wrap`" and the replay would start on the wrong page with nothing saying so. Both sides
     // carry it, which keeps a real difference visible and stops the false one.
+    // Reticle's own params dropped, as the recording drops them from `startPath` (#1411).
     const observed = last === undefined ? undefined : routeOfEvent(last);
     if (observed !== undefined)
-        return `${observed.docPath}${observed.search}${observed.hash}`;
+        return navigablePath(observed);
     if (session.url === undefined)
         return undefined;
     const fromUrl = routeOfUrl(session.url);
-    return fromUrl === undefined ? undefined : `${fromUrl.docPath}${fromUrl.search}${fromUrl.hash}`;
+    return fromUrl === undefined ? undefined : navigablePath(fromUrl);
 }
 /**
  * Ask the project what it already knows about this flow.
@@ -132,11 +134,7 @@ async function consultProjectMemory(deps, flow, root) {
     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.
+        // The APP's root, not the daemon's (wherever it was launched): its link file is this project's.
         const cloud = await resolveProjectCloud(deps.fs, root, homedir(), process.env);
         if (null === cloud.config || !cloud.policy.memory)
             return undefined;
@@ -146,7 +144,7 @@ async function consultProjectMemory(deps, flow, root) {
         const url = memoryReadUrl(cloud.config.url, { projectId: cloud.projectId, subject });
         const res = await cloudFetch(url, {
             method: 'GET',
-            headers: { authorization: `Bearer ${cloud.config.apiKey}` },
+            headers: memoryReadHeaders(cloud.config.apiKey),
         });
         if (200 !== res.status)
             return undefined;
@@ -574,8 +572,8 @@ observe = (s) => s) {
             status: ReplayStatus.UNVERIFIABLE,
             steps: [],
             unverifiable: {
-                reason: `this flow fills a redacted field and nothing supplied it, so nothing ran and nothing ` +
-                    `was proved. Set ${names} in the environment the daemon runs in, then replay. Until then ` +
+                reason: `this flow fills a redacted field and nothing supplied it, so nothing ran and nothing was ` +
+                    `proved. Pass it with this call — secrets: { ${missing.map((each) => `"${each.field}": "…"`).join(', ')} } — or set ${names} where the daemon runs and restart it. Until then ` +
                     `the value typed would be the placeholder itself, and any failure after it would be ` +
                     `about this and not about the application.`,
             },
@@ -613,6 +611,7 @@ observe = (s) => s) {
             ...(continueAt === undefined ? {} : { at: continueAt }),
             // The HUD's replay chip, when the human pressed ▶. In-process only: an agent's arguments
             // arrive as JSON and can never carry a function.
+            onStepResult: replayStepShooter(deps, session.id),
             ...('function' === typeof args['onStep']
                 ? { onStep: args['onStep'] }
                 : {}),
@@ -624,7 +623,7 @@ observe = (s) => s) {
         return lostDocumentResult(name, error);
     }
     // Only part of the journey was driven here: its steps were checked, nothing about the whole flow.
-    if (continueAt !== undefined || (to !== undefined && to < loaded.value.steps.length))
+    if (0 < (continueAt ?? 0) || (to !== undefined && to < loaded.value.steps.length))
         return { name, status: partialStatus(steps), steps };
     // Computed HERE, before the synthetic success row is appended below: once that row is pushed,
     // `steps.length` no longer counts only the flow's own steps and the arithmetic is wrong.
@@ -728,13 +727,12 @@ observe = (s) => s) {
         result.halted = halted;
     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
-    // drift, and the sibling tools would then disagree about the same flow.
+    // A green that cannot go red is not a pass: the same judgement `reticle_flow_verify` makes.
     const cannotFail = status === ReplayStatus.OK ? unverifiableReason(loaded.value, invokedFlows) : undefined;
     if (cannotFail !== undefined)
         result.unverifiable = { reason: cannotFail };
+    // One check of the session that ran it, so its end does not say "nothing was checked".
+    noteReplayCheck(session, name, status, cannotFail !== undefined);
     if (status !== ReplayStatus.OK)
         result.decision = buildDecision(result, loaded.value, intentSaid, invokedFlows);
     applyStartPathHint(result, startPathHint);

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

@@ -12,7 +12,7 @@ import type { EvalResult } from '@reticlehq/engine/question/predicate/predicate.
  * (via the injected waitForPredicate). Mirrors PredicateSession so the same fake drives both.
  */
 export interface FlowReplaySession {
-    command(name: string, args?: Record<string, unknown>): Promise<CommandResult>;
+    command(name: string, args?: Record<string, unknown>, timeoutMs?: number): Promise<CommandResult>;
     /**
      * Attribution window around each replayed step. Optional so a minimal test double still satisfies the
      * interface, but a real session MUST supply it: without a window the step's own effects carry no

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

@@ -43,6 +43,15 @@ export declare function runTestidStep(session: FlowReplaySession, step: FlowStep
  * state it was never meant to run in.
  */
 export declare function assertStepExpect(session: FlowReplaySession, expect: NonNullable<FlowStep['expect']>, waitForSignal: WaitForSignal, timeoutMs: number, since: number): Promise<Drift | undefined>;
+/**
+ * A text check that missed only on case says so, with what would hold. Text checks match case
+ * exactly now, so a flow saved when they did not goes red on capitalisation alone; the person
+ * reading its replay needs the fix (`ignoreCase: true`, or re-record), not a bare "did not hold".
+ */
+export declare function withCaseOnly(reason: string, verdict: {
+    caseOnlyMiss?: boolean;
+    wouldHold?: string;
+}): string;
 /**
  * Replay a loaded flow by RE-RESOLVING every step's semantic anchor against the live DOM — never
  * a stale ref. A testid anchor is re-found by reticle_query; a signal anchor waits on a predicate.
@@ -58,6 +67,11 @@ export interface ReplayFromOptions {
      * The HUD's replay chip draws its progress from this; it must never throw into the replay.
      */
     onStep?: (done: number, total: number, held: boolean) => void;
+    /**
+     * Told each reported step the moment its outcome is decided, before it is kept, so a caller can
+     * add to it (the step's screenshot). Never allowed to fail the replay.
+     */
+    onStepResult?: (result: FlowStepResult, flow: string) => Promise<void>;
     /**
      * Resume at this step: an index, or a step's `id` (which survives edits that shift indices).
      *
@@ -114,7 +128,10 @@ export interface ReplayFromOptions {
  * 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;
-/** How far a replay drives: `to` stops before a step, `at` picks up at one. Positive indices only. */
+/**
+ * How far a replay drives: `to` stops before a step (positive), `at` picks up at one on the page as
+ * it is. `at: 0` is the whole flow continuing the page the flow before it left, with no reload.
+ */
 export declare function replayWindow(args: Record<string, unknown>): {
     to?: number;
     at?: number;

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

@@ -7,7 +7,7 @@ import { routeOfEvent, routeOfUrl } from '@reticlehq/engine/question/predicate/p
 import { evalConsole } from '@reticlehq/engine/question/predicate/predicate-console.js';
 import { stepEffect } from '@reticlehq/engine/evidence/step-effect.js';
 import { AnchorKind, DriftReason, EventType, FlowStepTool, StepEffect, PredicateKind, ReplayStatus, } from '@reticlehq/core';
-import { asString, isConsequenceDrift } from '@reticlehq/core';
+import { asString, invokedFlowMissing, isConsequenceDrift } from '@reticlehq/core';
 import { anchorFieldName } from './fields/flow-secret-field.js';
 import { degradedStepResult, isDegradedAnchor, runComponentStep, runRoleStep, runSequenceStep, } from './flow-step-runners.js';
 import { inFlightRequestLabels } from '../../surface/tools/act/settle-in-flight.js';
@@ -282,11 +282,22 @@ export async function assertStepExpect(session, expect, waitForSignal, timeoutMs
                 : DriftReason.SIGNAL_NOT_OBSERVED,
         reason: namedInFlight
             ? `${IN_FLIGHT_AT_BUDGET_END} (${openRequests.join(', ')})`
-            : (verdict.failureReason ?? "the step's declared consequence did not hold"),
+            : withCaseOnly(verdict.failureReason ?? "the step's declared consequence did not hold", verdict),
         anchor: expectLabel(expect),
         nearest: null,
     };
 }
+/**
+ * A text check that missed only on case says so, with what would hold. Text checks match case
+ * exactly now, so a flow saved when they did not goes red on capitalisation alone; the person
+ * reading its replay needs the fix (`ignoreCase: true`, or re-record), not a bare "did not hold".
+ */
+export function withCaseOnly(reason, verdict) {
+    if (true !== verdict.caseOnlyMiss)
+        return reason;
+    const shown = verdict.wouldHold === undefined ? '' : ` ("${verdict.wouldHold}")`;
+    return `${reason} — the page shows it in another case${shown}. Text checks match case exactly: if any case is meant, add ignoreCase: true to this check, or re-record the flow.`;
+}
 /** Run one signal-anchored step: wait for the signal predicate, else drift (no nearest for signals). */
 async function runSignalStep(session, step, index, name, waitForSignal, signalTimeoutMs, since) {
     // Scope to THIS replay's floor, not the whole buffer.
@@ -328,11 +339,14 @@ export function resumeIndex(from, steps) {
         return undefined;
     return steps.slice(0, at).some((step) => StepEffect.COMMITS === step.effect) ? 0 : at;
 }
-/** How far a replay drives: `to` stops before a step, `at` picks up at one. Positive indices only. */
+/**
+ * How far a replay drives: `to` stops before a step (positive), `at` picks up at one on the page as
+ * it is. `at: 0` is the whole flow continuing the page the flow before it left, with no reload.
+ */
 export function replayWindow(args) {
-    const index = (raw) => 'number' === typeof raw && Number.isInteger(raw) && 0 < raw ? raw : undefined;
-    const to = index(args['to']);
-    const at = index(args['at']);
+    const index = (raw, least) => 'number' === typeof raw && Number.isInteger(raw) && least <= raw ? raw : undefined;
+    const to = index(args['to'], 1);
+    const at = index(args['at'], 0);
     return { ...(to === undefined ? {} : { to }), ...(at === undefined ? {} : { at }) };
 }
 /** A part-way replay's status, from the steps it drove. */
@@ -381,7 +395,7 @@ async function runInvokeStep(session, flow, step, index, waitForSignal, signalTi
         return {
             ...base,
             ok: false,
-            error: `cannot replay "${name}": it was not found, so this journey would report green having never run it`,
+            error: invokedFlowMissing(name),
         };
     }
     // `from` is an offset into the CALLER's steps. A sub-journey invoked from the setup prefix runs
@@ -555,6 +569,7 @@ export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs,
             }
             if (index < from)
                 result.note = `setup step for resuming at step ${String(from)} failed`;
+            await options.onStepResult?.(result, flow.name).catch(() => undefined);
             results.push(result);
             tell(result);
             // Under `sweep`, a failure whose action still RAN does not stop the run — the page is where the

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

@@ -1,4 +1,4 @@
-import { FlowErrorCode } from '@reticlehq/core';
+import { FlowErrorCode, ReplayStatus, Verified } from '@reticlehq/core';
 import { type ProjectId } from '@reticlehq/core';
 /** Discriminated result so callers never branch on free strings. */
 export type FlowResult<T> = {
@@ -35,3 +35,24 @@ export type FlowResult<T> = {
 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;
+/**
+ * A replay as one check of the session that ran it: held when it replayed clean, failed when a step
+ * failed, undecided when it drifted or its flow asserts nothing. A session whose only work was a
+ * failing replay ended "nothing was checked" beside the replay's own failure.
+ */
+export declare function replayVerdictEffect(name: string, status: ReplayStatus, assertsNothing: boolean): {
+    claim: string;
+    verified: Verified;
+    declaredBeforeActing: true;
+    grade: string;
+};
+/** Record a replay as one check of the session that ran it. A session double without a journal is skipped. */
+export declare function noteReplayCheck(session: {
+    recordAction?: (tool: string, args: Record<string, unknown>, effect?: unknown) => string;
+}, name: string, status: ReplayStatus, assertsNothing: boolean): void;
+/**
+ * The active recording a refused `reticle_flow_save` was most likely about: the one it named, or
+ * the only one running when it named none and nothing is stopped yet.
+ */
+export declare function stillRecording(active: readonly string[], name: string, explicitName: string | undefined, held: readonly string[]): string | undefined;
+export declare function stillRecordingMessage(recording: string): string;