@reticlehq/server 3.5.0 → 3.6.0

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

@@ -6,7 +6,7 @@ import { emptyFlowRefusal } from './empty-flow.js';
 import { aliasParam } from '../../surface/tools/args/alias-args.js';
 import { FlowErrorCode, RecordedSaveError, ReplayStatus, SuiteIsolation, } from '@reticlehq/core';
 import { recordSuiteFlakes } from './suite/suite-flakes.js';
-import { ReticleTool } from '@reticlehq/core';
+import { AppRuntime, ReticleTool } from '@reticlehq/core';
 import { asNumber, asString, mutationTargetsFor, perturbationFor } from '@reticlehq/core';
 import { workerCountSchema } from '../../surface/tools/args/numeric-bounds.js';
 import { log } from '../../log.js';
@@ -21,7 +21,8 @@ import { recordingBacktrackWarning } from './recording/recording-backtrack.js';
 import { isValidFlowName, flowPath } from '../../memory/project/dir/reticle-dir.js';
 import {} from './flows.js';
 import { flowsForSession } from './flow-store-for-session.js';
-import { rootForProjectId } from '../../memory/project/session-root.js';
+import { rootForTarget, sessionTarget } from '../../memory/project/session-root.js';
+import { originOf } from '../../portal/session/session-manager.js';
 import { resolveSuiteSelection } from './suite-selection.js';
 import { replayNamedFlow, flowErrorMessage, latestRecordedFlow, sessionProjectId, } from './flow-replay-run.js';
 import { persistAndSyncVerificationRun, } from '../../judgement/runs/verification-sync.js';
@@ -34,19 +35,21 @@ import { replayAndLearn } from './flow-learning.js';
  * set). Fire-and-forget: resolves the config, POSTs via the platform fetch, and logs the outcome. Any
  * failure is swallowed so a network hiccup never affects the local save.
  */
-async function syncSavedFlowToCloud(deps, flow, projectId) {
+async function syncSavedFlowToCloud(deps, flow, target) {
     // Per-project cloud: sync a saved flow only when cloud is attached AND flow sync is enabled.
     // The link file of the project this flow belongs to — the flow itself was already saved through
     // `flowsForSession`, and reading the credential from a different tree is how one project's work
     // reaches another project's dashboard.
-    const cloud = await resolveProjectCloud(deps.fs, rootForProjectId(deps, projectId), homedir(), process.env);
+    const cloud = await resolveProjectCloud(deps.fs, rootForTarget(deps, target), homedir(), process.env);
     if (null === cloud.config || !cloud.policy.flows)
         return; // not attached / flows disabled → local only
-    const result = await syncFlowToCloud(flow, cloud.config, projectId, cloudFetch);
+    const result = await syncFlowToCloud(flow, cloud.config, target.projectId, cloudFetch);
     if (result.outcome !== SyncOutcome.SYNCED) {
         log('cloud-flow-sync-failed', { flow: flow.name, status: result.status, error: result.error });
     }
 }
+/** A step index no recorded flow reaches; bounds `to` and `at`. */
+const MAX_REPLAY_STEP = 10_000;
 /**
  * The URL a leased context should open: the app's ORIGIN, not the live tab's current location.
  *
@@ -57,7 +60,10 @@ async function syncSavedFlowToCloud(deps, flow, projectId) {
  */
 export function leasableAppUrl(deps, sessionId) {
     try {
-        const url = deps.sessions.resolve(sessionId).url;
+        const session = deps.sessions.resolve(sessionId);
+        if (AppRuntime.WEB !== (session.runtime ?? AppRuntime.WEB))
+            return undefined; // desktop: no IPC in a lease
+        const url = session.url;
         if (typeof url !== 'string' || 0 === url.length)
             return undefined;
         return new URL(url).origin;
@@ -211,13 +217,14 @@ export const FLOW_TOOLS = [
                 ...(success !== undefined ? { success } : {}),
                 ...(intent !== undefined ? { intent } : {}),
             };
-            const projectId = sessionProjectId(deps, asString(args['sessionId']));
+            const target = sessionTarget(deps, asString(args['sessionId']));
+            const { projectId } = target;
             // A zero-step recording is not a flow. Saving it wrote a file the suite reports "unverifiable"
             // forever while telling the agent it had saved a regression test — see empty-flow.
             const emptyRefusal = emptyFlowRefusal(program.steps.length, name);
             if (emptyRefusal !== undefined)
                 return Promise.resolve(emptyRefusal);
-            const { flows, root } = flowsForSession(deps, projectId);
+            const { flows, root } = flowsForSession(deps, target);
             const author = flowAuthor();
             const toSave = {
                 ...program,
@@ -275,10 +282,11 @@ export const FLOW_TOOLS = [
         // (the prior bug) made schema-validating MCP clients reject the result ("expected object,
         // received string") — caught driving the live demo.
         handler: (deps, args) => {
-            const projectId = sessionProjectId(deps, asString(args['sessionId']));
+            const target = sessionTarget(deps, asString(args['sessionId']));
+            const { projectId } = target;
             // The APP's flows, not the daemon's. Listing where the daemon was launched is what showed a
             // React dashboard a HUD full of Electron and Tauri flows from an unrelated checkout.
-            const { flows: store, root } = flowsForSession(deps, projectId);
+            const { flows: store, root } = flowsForSession(deps, target);
             return store.list(projectId).then((names) => ({
                 // `list` deliberately returns invalid names so they are reported rather than silently
                 // dropped — but the declared outputSchema requires `path` on EVERY entry, and omitting it made
@@ -366,16 +374,15 @@ export const FLOW_TOOLS = [
     {
         name: ReticleTool.FLOW_REPLAY,
         description: "Replay a git-checked flow from .reticle/flows/<name>.json. RE-RESOLVES each step's semantic " +
-            'anchor (testid via reticle_query; signal via predicate) against the LIVE DOM — never reuses a ' +
-            'stale ref. On an anchor MISS returns legible DRIFT { step, anchor, drift:{ reasonKind, reason, ' +
-            'nearest } } (the closest surviving testid) and stops — the "whose fault is it" contract. ' +
-            'Returns { name, status: ok|drift|error, steps:[...] }; missing/malformed files and action ' +
-            'failures are status:error with a structured code (distinct from contract-changed drift). ' +
-            'An ok replay of a flow that asserts no consequence also carries unverifiable:{reason} — it ' +
-            'would read ok even if the feature were broken, so do NOT treat that ok as proof. ' +
-            'A run that stops early carries halted:{atStep, notAttempted}: `steps` is SHORTER than the ' +
-            'flow because replay stopped, not because a step was skipped — do not read a missing step as ' +
-            'an action that failed to dispatch.',
+            'anchor (testid via reticle_query; signal via predicate) against LIVE DOM. On anchor MISS returns ' +
+            'DRIFT { step, anchor, drift:{ reasonKind, reason, nearest } } and stops. ' +
+            'Returns { name, status: ok|drift|error|unverifiable, steps:[...] }. ' +
+            'Action failures are status:error. ' +
+            'Status unverifiable means flow could not be graded (missing secrets, unmet preconditions, lost ' +
+            'document) — neither pass nor fail, treat as UNKNOWN. ' +
+            'An ok replay of a flow asserting no consequence also carries unverifiable:{reason} — do not ' +
+            'treat as proof. ' +
+            'Early halt carries halted:{atStep, notAttempted}: `steps` is shorter because replay stopped.',
         inputSchema: {
             flow: z
                 .string()
@@ -392,6 +399,20 @@ export const FLOW_TOOLS = [
                 .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.'),
+            to: z
+                .number()
+                .int()
+                .positive()
+                .max(MAX_REPLAY_STEP)
+                .optional()
+                .describe('Stop before this step (drive only to a point journeys branch from).'),
+            at: z
+                .number()
+                .int()
+                .positive()
+                .max(MAX_REPLAY_STEP)
+                .optional()
+                .describe('Continue at this step on the page as it is (after another flow ran `to` it).'),
             sweep: z
                 .boolean()
                 .optional()
@@ -412,7 +433,7 @@ export const FLOW_TOOLS = [
             // The flow's name — always present in FlowReplayResult (the description promises `{ name, … }`),
             // but omitted here, so a validating profile stripped it and a replay result arrived anonymous.
             name: z.string(),
-            status: z.string().describe('ok | drift | error'),
+            status: z.string().describe('ok | drift | error | unverifiable'),
             steps: z.array(z.unknown()),
             proposals: z.array(z.unknown()).optional(),
             deviation: z
@@ -482,8 +503,9 @@ export const FLOW_TOOLS = [
              * inherit it as a mystery — the same rule the mutation loop had to earn.
              */
             const sessionId = asString(args['sessionId']);
-            const loaded = await flowsForSession(deps, sessionProjectId(deps, sessionId))
-                .flows.load(asString(args['flowName']) ?? asString(args['flow']) ?? '', sessionProjectId(deps, sessionId))
+            const target = sessionTarget(deps, sessionId);
+            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);
@@ -576,8 +598,9 @@ export const FLOW_TOOLS = [
         handler: async (deps, args) => {
             const sessionId = asString(args['sessionId']);
             // "Replay all" means all of THIS app's flows (+ legacy), not every project's on a shared daemon.
-            const projectId = sessionProjectId(deps, sessionId);
-            const selected = await resolveSuiteSelection(deps, projectId, args);
+            const target = sessionTarget(deps, sessionId);
+            const { projectId } = target;
+            const selected = await resolveSuiteSelection(deps, target, args);
             const requested = selected.run;
             /** Named rather than subtracted — a suite that returns fewer than were asked for must say so. */
             const heldBack = {
@@ -587,7 +610,7 @@ export const FLOW_TOOLS = [
                 ...(selected.unsatisfied === undefined ? {} : { unsatisfied: selected.unsatisfied }),
             };
             // verify:server — hand the whole suite to the hosted runner; it records the verification itself.
-            const cloud = await resolveProjectCloud(deps.fs, rootForProjectId(deps, projectId), homedir(), process.env);
+            const cloud = await resolveProjectCloud(deps.fs, rootForTarget(deps, target), homedir(), process.env);
             const server = await runServerVerify(deps, cloud, sessionId, requested);
             if (server !== null)
                 return server;
@@ -639,7 +662,7 @@ export const FLOW_TOOLS = [
                 const parallelRuns = await Promise.all(outcomes.map(async (o, i) => {
                     const name = requested[i] ?? '';
                     const replay = o.ok && o.value !== undefined ? o.value.replay : leaseFailureReplay(name, o.error);
-                    const loaded = await flowsForSession(deps, projectId)
+                    const loaded = await flowsForSession(deps, target)
                         .flows.load(name, projectId)
                         .catch(() => null);
                     const flow = loaded !== null && loaded.ok ? loaded.value : undefined;
@@ -649,8 +672,8 @@ export const FLOW_TOOLS = [
                     ...(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);
-                await persistAndSyncVerificationRun(deps, timed, projectId);
+                const flaky = await recordSuiteFlakes(deps.fs, rootForTarget(deps, target), parallelRuns);
+                await persistAndSyncVerificationRun(deps, timed, target);
                 const verdict = buildSuiteVerdict(parallelRuns, selected.knownRoutes, SuiteIsolation.PER_FLOW_LEASE);
                 return {
                     ...verdict,
@@ -674,7 +697,7 @@ export const FLOW_TOOLS = [
             for (const flowName of requested) {
                 const start = deps.now();
                 const replay = await replayAndLearn(deps, { flowName, sessionId });
-                const loaded = await flowsForSession(deps, projectId)
+                const loaded = await flowsForSession(deps, target)
                     .flows.load(flowName, projectId)
                     .catch(() => null);
                 const flow = loaded !== null && loaded.ok ? loaded.value : undefined;
@@ -689,9 +712,9 @@ export const FLOW_TOOLS = [
             // `reticle flow` on the command line, so an AGENT running this tool a hundred times learned
             // nothing about which flows are intermittent. Same product, same ledger, two surfaces, and the
             // one an agent uses was the blind half.
-            const flaky = await recordSuiteFlakes(deps.fs, rootForProjectId(deps, projectId), runs);
+            const flaky = await recordSuiteFlakes(deps.fs, rootForTarget(deps, target), runs);
             // Emit the consolidated run artifact (Runs tab) + best-effort cloud push. Never blocks the verdict.
-            await persistAndSyncVerificationRun(deps, timed, projectId);
+            await persistAndSyncVerificationRun(deps, timed, target);
             const verdict = buildSuiteVerdict(runs, selected.knownRoutes, SuiteIsolation.SHARED_SESSION);
             // A flow that has both passed and failed on UNCHANGED code is a different thing from a
             // regression, and an agent that cannot tell them apart either chases a ghost or ignores a real
@@ -766,12 +789,13 @@ export const FLOW_TOOLS = [
             // Resolved like every other path now. This save used to go to the daemon's root while the
             // recorded-flow save resolved per session, so where a flow landed depended on which tool wrote
             // it — and the pair that disagreed were the two ways to save the same thing.
-            const res = await flowsForSession(deps, session.projectId).flows.saveFlow(flow, session.projectId);
+            const target = { projectId: session.projectId, origin: originOf(session.url) };
+            const res = await flowsForSession(deps, target).flows.saveFlow(flow, session.projectId);
             if (!res.ok)
                 return { error: flowErrorMessage(res.code, res.detail), code: res.code };
             // If logged in to Reticle, mirror the saved flow to the team's regression suite. Best-effort
             // and non-blocking: the flow is already on disk, so a sync failure never fails the save.
-            void syncSavedFlowToCloud(deps, flow, session.projectId);
+            void syncSavedFlowToCloud(deps, flow, target);
             // Return the SaveSummary as-is ({ name, stepCount, degraded, empty }) — the outputSchema
             // declares `name`, so the old `flowName` key was silently stripped by schema-strict clients.
             return res.value;

package/dist/language/flows/flows.js

@@ -76,8 +76,11 @@ export function anchorForStep(args) {
     if (by === QueryBy.ROLE && value !== undefined) {
         const name = asString(args['name']);
         if (name !== undefined && name.length > 0) {
-            // The schema carries role + name only; provenance lives on the step, not the anchor.
-            return { anchor: { kind: AnchorKind.ROLE, role: value, name }, degraded: false };
+            // Provenance lives on the step, not the anchor; the position among namesakes is identity.
+            const nth = args['nth'];
+            const of = args['of'];
+            const among = 'number' === typeof nth && 'number' === typeof of ? { nth, of } : {};
+            return { anchor: { kind: AnchorKind.ROLE, role: value, name, ...among }, degraded: false };
         }
     }
     if (by === QueryBy.COMPONENT) {

package/dist/language/flows/heal-run.js

@@ -12,7 +12,8 @@ import { replayFlow } from './flow-replay.js';
 import { applyHealChanges, collectProposals } from './heal.js';
 import { healPrecondition } from './heal-precondition.js';
 import { assertSuccess, dynamicTestids, successLabel } from './flow-success.js';
-import { flowErrorMessage, sessionProjectId } from './flow-replay-run.js';
+import { flowErrorMessage } from './flow-replay-run.js';
+import { sessionTarget } from '../../memory/project/session-root.js';
 import { flowsForSession } from './flow-store-for-session.js';
 const HEAL_MESSAGES = {
     NOTHING: 'nothing to heal — every anchor resolved on replay',
@@ -48,8 +49,9 @@ function toChange(proposal) {
 export async function healFlow(deps, args) {
     const name = asString(args['flowName']) ?? '';
     const apply = true === args['apply'];
-    const projectId = sessionProjectId(deps, asString(args['sessionId']));
-    const loaded = await flowsForSession(deps, projectId).flows.load(name, projectId);
+    const target = sessionTarget(deps, asString(args['sessionId']));
+    const { projectId } = target;
+    const loaded = await flowsForSession(deps, target).flows.load(name, projectId);
     if (!loaded.ok) {
         return {
             name,
@@ -163,7 +165,7 @@ export async function healFlow(deps, args) {
     }
     // Healing WRITES, so it must land where the load came from — a heal that read the app's flow and
     // wrote the daemon's copy would silently fork the two.
-    const written = await flowsForSession(deps, projectId).flows.heal(name, proposals.map(toChange), projectId);
+    const written = await flowsForSession(deps, target).flows.heal(name, proposals.map(toChange), projectId);
     if (!written.ok) {
         return {
             name,

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

@@ -31,17 +31,17 @@ export declare const FlakeFileSchema: z.ZodObject<{
         fails: number;
     }>>;
 }, "strip", z.ZodTypeAny, {
-    version: 1;
     flows: Record<string, {
         runs: number;
         fails: number;
     }>;
-}, {
     version: 1;
+}, {
     flows: Record<string, {
         runs: number;
         fails: number;
     }>;
+    version: 1;
 }>;
 export declare function emptyRecord(): FlakeRecord;
 /** Accrue one unchanged-code replay outcome. */

package/dist/language/flows/recording/tape/recordings.d.ts

@@ -33,9 +33,21 @@ export interface RecordedStep {
     endPage?: string;
     /** Why the agent took this step: the `intent` it declared on the action. Names the saved flow. */
     intent?: string;
+    /**
+     * Why a consequence this step PROVED is not in the flow: the flow file could not express it (a
+     * session ref such as `e12` means nothing on a later page). Said at stop, so a weaker flow is
+     * never saved silently.
+     */
+    unkeptExpect?: string;
 }
 interface ActiveRecording {
     cursor: number;
+    /**
+     * The session (tab) that started it. Only that session's steps join it: one daemon serves every
+     * agent and app on the machine, and capturing into every open recording put a click from an
+     * unrelated app into somebody else's saved flow (#988). Absent: takes every session's steps.
+     */
+    session?: string;
     steps: RecordedStep[];
     /** The route the journey began on. See CompiledProgram.startPath. */
     startPath?: string;
@@ -91,7 +103,10 @@ export declare const INVOKE_TOOL: string;
 export declare const AMBIENT_RECORDING = "__ambient__";
 export declare class RecordingStore {
     #private;
-    start(name: string, cursor: number, startPath?: string): void;
+    private readonly byHarness;
+    /** `byHarness`: whether the step being captured was driven by the Harness, which tapes its own. */
+    constructor(byHarness?: () => boolean);
+    start(name: string, cursor: number, startPath?: string, session?: string): void;
     isRecording(name: string): boolean;
     /**
      * Number of steps captured so far in the named ACTIVE recording (0 if it
@@ -112,7 +127,7 @@ export declare class RecordingStore {
      * Opened lazily on the first step rather than in the constructor: a store that never records
      * anything should not carry an empty tape, and "did anything happen at all" stays answerable.
      */
-    capture(step: RecordedStep, route?: string): void;
+    capture(step: RecordedStep, route?: string, session?: string): void;
     /**
      * Add a consequence to the last captured step of every active recording.
      *
@@ -120,20 +135,31 @@ export declare class RecordingStore {
      * reached the recorder — only the act tools called `capture` — so the flow kept the click and lost
      * the proof. What the step already declared is kept; the new check joins it under `allOf`.
      */
-    attachExpect(expect: Predicate): void;
+    attachExpect(expect: Predicate, session?: string): void;
     /**
      * A navigation happened. Navigating records no step, so until the next one is captured, a check
      * proved now is about the page the navigation opened, not about the last step — and kept on that
      * step, replay would ask it right after the click, of a page it was never true on.
      */
     markNavigated(): void;
+    /**
+     * Take the expectation off the ambient tape's last step, because the verdict on it came back no.
+     *
+     * A step is captured at dispatch, before anything is judged, so a claim that turned out false is
+     * already on the tape as that step's `expect`. Cut into a journey it becomes a flow that is red for
+     * ever, on an expectation nobody but the agent's wrong guess made. The failure is not lost: it is
+     * filed as a capsule, the artifact built for "this should hold and does not". The ACTION stays,
+     * since the steps after it ran on the page it produced. A recording somebody opened deliberately
+     * is left as they drove it.
+     */
+    unassertLast(): void;
     /**
      * The page the step just captured ended on, once its action settled.
      *
      * Fills only a step that has none, so calling it after an action that captured nothing leaves the
      * previous step's own answer alone.
      */
-    markEnded(page: string | undefined): void;
+    markEnded(page: string | undefined, session?: string): void;
     /**
      * Returns the active recording (cursor + steps) and clears it, or undefined if not recording.
      *

package/dist/language/flows/recording/tape/recordings.js

@@ -29,21 +29,31 @@ export const AMBIENT_RECORDING = '__ambient__';
  */
 const AMBIENT_STEP_CAP = 400;
 export class RecordingStore {
+    byHarness;
     #active = new Map();
     #compiled = new Map();
     /** A navigation came after the last captured step — see markNavigated. */
     #navigatedSinceStep = false;
-    start(name, cursor, startPath) {
+    /** `byHarness`: whether the step being captured was driven by the Harness, which tapes its own. */
+    constructor(byHarness = () => false) {
+        this.byHarness = byHarness;
+    }
+    start(name, cursor, startPath, session) {
         const openedOver = new Map();
-        for (const [outer, rec] of this.#active)
+        for (const [outer, rec] of this.#targets(session))
             openedOver.set(outer, rec.steps.length);
         this.#active.set(name, {
             cursor,
             steps: [],
             openedOver,
             ...(startPath === undefined ? {} : { startPath }),
+            ...(session === undefined ? {} : { session }),
         });
     }
+    /** The open recordings a step from `session` belongs to. See ActiveRecording.session. */
+    #targets(session) {
+        return [...this.#active].filter(([, rec]) => rec.session === undefined || session === undefined || rec.session === session);
+    }
     isRecording(name) {
         return this.#active.has(name);
     }
@@ -68,7 +78,7 @@ export class RecordingStore {
      * Opened lazily on the first step rather than in the constructor: a store that never records
      * anything should not carry an empty tape, and "did anything happen at all" stays answerable.
      */
-    capture(step, route) {
+    capture(step, route, session) {
         this.#navigatedSinceStep = false;
         if (!this.#active.has(AMBIENT_RECORDING)) {
             this.#active.set(AMBIENT_RECORDING, {
@@ -77,7 +87,7 @@ export class RecordingStore {
                 openedOver: new Map(),
             });
         }
-        for (const [name, rec] of this.#active) {
+        for (const [name, rec] of this.#targets(session)) {
             // The ambient tape is opened by the system and closed by nobody, so it is the one recording
             // with no human deciding when it has seen enough. Bounded here rather than left to grow for
             // the length of a daemon's life. Appending STOPS at the cap instead of dropping the oldest: a
@@ -86,6 +96,10 @@ export class RecordingStore {
             // opened on purpose is not capped — they said when it starts and they say when it stops.
             if (AMBIENT_RECORDING === name && rec.steps.length >= AMBIENT_STEP_CAP)
                 continue;
+            // The Harness saves its own recordings. Taping its steps too saved every drive twice: once as
+            // the Harness's flow and again, at session end, as a `drive-*` copy with a guessed name.
+            if (AMBIENT_RECORDING === name && this.byHarness())
+                continue;
             // A step nobody marked ended where the next one began.
             const previous = rec.steps.at(-1);
             if (previous !== undefined && previous.endPage === undefined && step.page !== undefined) {
@@ -104,10 +118,10 @@ export class RecordingStore {
      * reached the recorder — only the act tools called `capture` — so the flow kept the click and lost
      * the proof. What the step already declared is kept; the new check joins it under `allOf`.
      */
-    attachExpect(expect) {
+    attachExpect(expect, session) {
         if (this.#navigatedSinceStep)
             return;
-        for (const rec of this.#active.values()) {
+        for (const [, rec] of this.#targets(session)) {
             const last = rec.steps.at(-1);
             if (last === undefined)
                 continue;
@@ -128,16 +142,34 @@ export class RecordingStore {
     markNavigated() {
         this.#navigatedSinceStep = true;
     }
+    /**
+     * Take the expectation off the ambient tape's last step, because the verdict on it came back no.
+     *
+     * A step is captured at dispatch, before anything is judged, so a claim that turned out false is
+     * already on the tape as that step's `expect`. Cut into a journey it becomes a flow that is red for
+     * ever, on an expectation nobody but the agent's wrong guess made. The failure is not lost: it is
+     * filed as a capsule, the artifact built for "this should hold and does not". The ACTION stays,
+     * since the steps after it ran on the page it produced. A recording somebody opened deliberately
+     * is left as they drove it.
+     */
+    unassertLast() {
+        const tape = this.#active.get(AMBIENT_RECORDING);
+        const last = tape?.steps.at(-1);
+        if (tape === undefined || last === undefined || last.expect === undefined)
+            return;
+        const { expect: _dropped, ...kept } = last;
+        tape.steps[tape.steps.length - 1] = kept;
+    }
     /**
      * The page the step just captured ended on, once its action settled.
      *
      * Fills only a step that has none, so calling it after an action that captured nothing leaves the
      * previous step's own answer alone.
      */
-    markEnded(page) {
+    markEnded(page, session) {
         if (page === undefined)
             return;
-        for (const rec of this.#active.values()) {
+        for (const [, rec] of this.#targets(session)) {
             const last = rec.steps.at(-1);
             if (last !== undefined && last.endPage === undefined)
                 last.endPage = page;

package/dist/language/flows/replay-from-hud.d.ts

@@ -0,0 +1,20 @@
+import { ReticleCommand } from '@reticlehq/core';
+import type { FlowReplayResult } from '@reticlehq/core';
+import type { ToolDeps } from '../../surface/tools/tool-kit.js';
+/** The session a HUD replay reports to. Resolved per message: a replay usually reloads the page. */
+interface ProgressTarget {
+    pushNarration(text: string): void;
+    pushView(name: typeof ReticleCommand.FLOW_PROGRESS, args: object): void;
+}
+/** A human-facing one-liner for a panel replay verdict — ✓ passed / ⚠ drifted / ✗ errored / ? unverifiable. */
+export declare function replayVerdictLine(result: FlowReplayResult): string;
+/**
+ * Replay a saved flow because a person pressed ▶ in the HUD, with no agent involved.
+ *
+ * The chip they pressed shows the replay as it runs: a progress push after every step, and the
+ * verdict at the end, sent to whichever session holds the tab at that moment (a replay reloads the
+ * page, and the session object from before the reload no longer has a socket). The verdict also
+ * lands in the Agent Log as a line, where the "See the logs" link on the chip leads.
+ */
+export declare function replayFromHud(deps: ToolDeps, resolve: (sessionId: string) => ProgressTarget | undefined, sessionId: string, flowName: string): Promise<void>;
+export {};

package/dist/language/flows/replay-from-hud.js

@@ -0,0 +1,51 @@
+import { FlowProgressStatus, ReplayStatus, ReticleCommand } from '@reticlehq/core';
+import { replayAndLearn } from './flow-learning.js';
+/** A human-facing one-liner for a panel replay verdict — ✓ passed / ⚠ drifted / ✗ errored / ? unverifiable. */
+export function replayVerdictLine(result) {
+    if (result.status === ReplayStatus.OK)
+        return `✓ "${result.name}" passed`;
+    if (result.status === ReplayStatus.DRIFT)
+        return `⚠ "${result.name}" drifted — a step no longer matches`;
+    if (result.status === ReplayStatus.UNVERIFIABLE)
+        return `? "${result.name}" unverifiable — ${result.unverifiable?.reason ?? 'could not be graded'}`;
+    return `✗ "${result.name}" failed — ${result.error?.message ?? 'could not replay'}`;
+}
+/**
+ * Replay a saved flow because a person pressed ▶ in the HUD, with no agent involved.
+ *
+ * The chip they pressed shows the replay as it runs: a progress push after every step, and the
+ * verdict at the end, sent to whichever session holds the tab at that moment (a replay reloads the
+ * page, and the session object from before the reload no longer has a socket). The verdict also
+ * lands in the Agent Log as a line, where the "See the logs" link on the chip leads.
+ */
+export async function replayFromHud(deps, resolve, sessionId, flowName) {
+    const progress = (done, total, status) => resolve(sessionId)?.pushView(ReticleCommand.FLOW_PROGRESS, {
+        name: flowName,
+        done,
+        total,
+        status,
+    });
+    resolve(sessionId)?.pushNarration(`▶ Replaying "${flowName}"…`);
+    progress(0, 0, FlowProgressStatus.PLAYING);
+    let total = 0;
+    let done = 0;
+    try {
+        const result = await replayAndLearn(deps, {
+            flowName,
+            sessionId,
+            onStep: (stepsDone, stepsTotal) => {
+                done = stepsDone;
+                total = stepsTotal;
+                progress(done, total, FlowProgressStatus.PLAYING);
+            },
+        });
+        const passed = ReplayStatus.OK === result.status;
+        progress(passed ? total : done, total, passed ? FlowProgressStatus.PASSED : FlowProgressStatus.FAILED);
+        resolve(sessionId)?.pushNarration(replayVerdictLine(result));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        progress(done, total, FlowProgressStatus.FAILED);
+        resolve(sessionId)?.pushNarration(`✗ Replay "${flowName}" failed — ${message}`);
+    }
+}

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

@@ -35,6 +35,8 @@ export declare function replayActionArgs(value: unknown, confirmDangerous?: bool
  * a hash-routed app makes meaningless in the document location — see routeOfEvent.
  */
 export declare function pathOf(url: string | undefined): string | undefined;
+/** What a saved flow could not keep, and the fix. See RecordedStep.unkeptExpect. */
+export declare const UNKEPT_EXPECT: string;
 /**
  * Capture an act into every in-flight recording, or do nothing when none is running.
  *
@@ -44,21 +46,23 @@ export declare function pathOf(url: string | undefined): string | undefined;
  */
 export declare function captureAct(recordings: {
     active: () => string[];
-    capture: (step: RecordedStep, route?: string) => void;
+    capture: (step: RecordedStep, route?: string, session?: string) => void;
 }, args: Record<string, unknown>, res: unknown, 
 /** Where this step ran, so the ambient tape can be cut into journeys. See RecordedStep.route. */
-route?: string): void;
+route?: string, 
+/** The session that acted: only recordings it started take the step. */
+session?: string): void;
 /**
  * Capture an act_and_wait once its verdict is known, keeping `until` as the step's expectation only
  * on a yes. Recorded before the verdict, a step kept an `until` that came back `no` or `no-fault` —
  * a regression test asserting something never once observed to hold because of the action. The
  * action itself is always recorded: it happened, and replay needs it to reach the next step.
  */
-export declare function captureVerdictedAct(recordings: Parameters<typeof captureAct>[0], args: Record<string, unknown>, res: unknown, route: string | undefined, verified: string | undefined): void;
+export declare function captureVerdictedAct(recordings: Parameters<typeof captureAct>[0], args: Record<string, unknown>, res: unknown, route: string | undefined, verified: string | undefined, session?: string): void;
 /** Fold a PASSING standalone assertion into the step it proved. See RecordingStore.attachExpect. */
 export declare function captureAssertion(recordings: {
-    attachExpect: (expect: Predicate) => void;
-}, raw: unknown): void;
+    attachExpect: (expect: Predicate, session?: string) => void;
+}, raw: unknown, session?: string): void;
 /**
  * Compile a single reticle_act invocation into a normalized RecordedStep using the action result. Anchor
  * priority mirrors synthesizeAnchor: a data-testid is the gold standard; failing that, the element's