@reticlehq/server 3.6.0 → 3.7.0

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

@@ -1,6 +1,7 @@
-import { FlowErrorCode } from '@reticlehq/core';
+import { FlowErrorCode, NO_SUCH_FLOW, ReplayStatus, ReticleTool, Verified } from '@reticlehq/core';
 import { SAFE_SEGMENT_PATTERN } from '@reticlehq/core';
 import { FlowParseNote } from './flow-expect-grammar.js';
+import { isAmbient } from './recording/tape/recordings.js';
 /**
  * A project id that is safe to put in a path, or nothing.
  *
@@ -36,7 +37,7 @@ export function flowErrorMessage(code, detail) {
         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';
+            return `${NO_SUCH_FLOW} — run reticle_flow{action:"list"} to see saved flows`;
         case FlowErrorCode.PARSE_FAILED:
             return FlowParseNote.MALFORMED;
         case FlowErrorCode.NO_RECORDING:
@@ -49,3 +50,47 @@ export function flowErrorMessage(code, detail) {
             return (detail ?? 'the step to resume at is not in this flow — pass a 0-based index or a step id');
     }
 }
+/**
+ * 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 function replayVerdictEffect(name, status, assertsNothing) {
+    const verified = ReplayStatus.OK === status && !assertsNothing
+        ? Verified.YES
+        : ReplayStatus.ERROR === status
+            ? Verified.NO
+            : Verified.UNKNOWN;
+    return {
+        claim: `the flow "${name}" replays and its checks hold`,
+        verified,
+        declaredBeforeActing: true,
+        grade: REPLAY_GRADE,
+    };
+}
+/** The grade a replay's check is recorded with. */
+const REPLAY_GRADE = 'flow';
+/** Record a replay as one check of the session that ran it. A session double without a journal is skipped. */
+export function noteReplayCheck(session, name, status, assertsNothing) {
+    session.recordAction?.(ReticleTool.FLOW_REPLAY, { flowName: name }, replayVerdictEffect(name, status, assertsNothing));
+}
+/**
+ * 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.
+ */
+// A running recording has no compiled program yet, so a save refusal names it (#1551).
+export function stillRecording(active, name, explicitName, held) {
+    if (active.includes(name) && !isAmbient(name))
+        return name;
+    // The ambient tape is the daemon's own, never one the agent started, so it is neither named nor
+    // counted: with a named recording beside it, that one is still the only candidate.
+    const opened = active.filter((recording) => !isAmbient(recording));
+    if ((explicitName === undefined || 0 === explicitName.length) && 0 === held.length) {
+        return 1 === opened.length ? opened[0] : undefined;
+    }
+    return undefined;
+}
+export function stillRecordingMessage(recording) {
+    return (`'${recording}' is still recording, and flow_save only saves a stopped recording. ` +
+        `Stop it first with reticle_record{action:"stop", recordingName:"${recording}"}, then save again.`);
+}

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

@@ -1,6 +1,8 @@
 import { AnchorKind, type FlowAnchor, type FlowReplayResult, type FlowStep, type FlowStepResult, type Predicate } from '@reticlehq/core';
 import type { FlowReplaySession, Sleep } from './flow-replay-types.js';
 import { type Reresolved } from './flow-anchor.js';
+/** The live act_sequence tool gives each step this transport budget when none was supplied. */
+export declare const DEFAULT_SEQUENCE_STEP_TIMEOUT_MS = 8000;
 export declare function runRoleStep(session: FlowReplaySession, step: FlowStep, index: number, anchor: Extract<FlowAnchor, {
     kind: typeof AnchorKind.ROLE;
 }>, confirmDangerous: boolean, sleep: Sleep): Promise<FlowStepResult>;

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

@@ -16,6 +16,8 @@ import { anchorFieldName } from './flows.js';
 import { ambiguityDrift, refFor, anchorLabel, componentLabel, componentQueryArgs, expectElementDrift, reresolved, resolveQuery, testidDrift, } from './flow-anchor.js';
 import { nearestRoleName } from './role-anchor-nearest.js';
 import { roleDriftReason } from '../../judgement/outcome/role-drift-reason.js';
+/** The live act_sequence tool gives each step this transport budget when none was supplied. */
+export const DEFAULT_SEQUENCE_STEP_TIMEOUT_MS = 8_000;
 /** Query args for a NAMED role anchor — the handle that identifies an instance, not a JSX site. */
 function roleQueryArgs(anchor) {
     return {
@@ -134,11 +136,8 @@ function replayDestructiveActionHint(rawError) {
     return (`${rawError} — this is a flow REPLAY: a step's own args.confirmDangerous is stripped before ` +
         'dispatch and never persists, so editing the flow file does nothing. Pass it at the call level ' +
         `instead: ${ReticleTool.FLOW_REPLAY} { confirmDangerous: true } acknowledges every flagged step ` +
-        // `reticle_verify{action:"flows"}` (the batch suite runner) has no such argument today — naming
-        // it here would repeat the exact defect this message exists to fix, so the honest statement is
-        // that a flow with a flagged step currently has to be replayed on its own to pass it.
-        'for this run. The batch reticle_verify{action:"flows"} has no equivalent option yet, so a flow ' +
-        'with a flagged step has to be replayed on its own to acknowledge it.');
+        'for this run, as do reticle_verify{action:"flows", confirmDangerous: true} for a suite and ' +
+        '`reticle verify <url> --confirm-dangerous` from the command line.');
 }
 /**
  * Dispatch one already-resolved step. Shared so every anchor kind runs the action the same way —
@@ -467,7 +466,14 @@ dynamic = new Set()) {
     const send = async (steps) => {
         session.beginAction?.(ReticleTool.FLOW_REPLAY, { steps: steps.length });
         try {
-            return await session.command(ReticleCommand.ACT_SEQUENCE, { steps });
+            // A recorded zero means "do not wait for the element", not "abort the whole batch now".
+            // Keep the transport alive long enough for the sequence's default per-step budget, and give
+            // an omitted timeout the same aggregate budget as the live tool's independent step waits.
+            const perStepTimeout = undefined === step.timeoutMs || 0 === step.timeoutMs
+                ? DEFAULT_SEQUENCE_STEP_TIMEOUT_MS
+                : step.timeoutMs;
+            const timeoutMs = perStepTimeout * steps.length;
+            return await session.command(ReticleCommand.ACT_SEQUENCE, { steps }, timeoutMs);
         }
         finally {
             session.finishAction?.();

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

@@ -29,5 +29,9 @@ export function flowsForSession(deps, target) {
     if (resolved === undefined || resolved.root === deps.reticleRoot) {
         return { flows: deps.flows, root: deps.reticleRoot };
     }
-    return { flows: new FlowStore(deps.fs, resolved.root, { now: deps.now }), root: resolved.root };
+    const onWrote = deps.onRunPersisted;
+    return {
+        flows: new FlowStore(deps.fs, resolved.root, { now: deps.now }, onWrote === undefined ? {} : { onWrote }),
+        root: resolved.root,
+    };
 }

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

@@ -10,6 +10,16 @@ export { replayNamedFlow } from './flow-replay-run.js';
  * point; flows that need another page carry their own startPath.
  */
 export declare function leasableAppUrl(deps: ToolDeps, sessionId: string | undefined): string | undefined;
+/**
+ * The live session's own URL — what the fixture port must be looked up by.
+ *
+ * NOT `leasableAppUrl`. That returns an ORIGIN, and the input provider finds a page by comparing
+ * full URLs, so an origin matched no page: `suiteFixtureSeed` answered `undefined` on every run and
+ * every leased flow booted cold while the code read as if it were seeded. Silent, because every
+ * refusal on that path is deliberately silent — a fixture is an optimisation, and a suite must not
+ * die when one is unavailable.
+ */
+export declare function sessionUrlOf(deps: ToolDeps, sessionId: string | undefined): string | undefined;
 /** A flow whose leased context never came up is a suite ERROR, never a silent pass. */
 export declare function leaseFailureReplay(name: string, error: string | undefined): FlowReplayResult;
 export declare const FLOW_TOOLS: ToolDef[];

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

@@ -1,19 +1,24 @@
+import { CALL_SECRETS_ARG, callSecretsArg } from './fields/flow-secret-field.js';
 import { flowAuthor } from './flow-author.js';
 import { FLOW_MUTATE_TOOL } from './flow-mutate-tools.js';
-import { seedSchema } from '../../surface/tools/args/numeric-bounds.js';
+import { seedSchema, workerCountSchema } from '../../surface/tools/args/numeric-bounds.js';
+import { confirmDangerousArg } from '../../surface/tools/args/confirm-dangerous-arg.js';
 import { z } from 'zod';
 import { emptyFlowRefusal } from './empty-flow.js';
-import { aliasParam } from '../../surface/tools/args/alias-args.js';
+import { aliasParam, aliasUsed } from '../../surface/tools/args/alias-args.js';
+import { stillRecording, stillRecordingMessage } from './flow-result.js';
+import { resolveAnnotateTarget } from './annotate-notes/annotate-target.js';
 import { FlowErrorCode, RecordedSaveError, ReplayStatus, SuiteIsolation, } from '@reticlehq/core';
 import { recordSuiteFlakes } from './suite/suite-flakes.js';
 import { AppRuntime, ReticleTool } from '@reticlehq/core';
-import { asNumber, asString, mutationTargetsFor, perturbationFor } from '@reticlehq/core';
-import { workerCountSchema } from '../../surface/tools/args/numeric-bounds.js';
+import { asNumber, asString } from '@reticlehq/core';
 import { log } from '../../log.js';
 import { cloudFetch, syncFlowToCloud, SyncOutcome } from '../../memory/cloud/cloud-sync.js';
 import { mapWithConcurrency, resolveConcurrency } from './suite/parallel-suite.js';
-import { acquireLeasedSession, sessionPerturbationPort, suiteFixtureSeed, } from '../../surface/tools/lease-tools.js';
+import { acquireLeasedSession, suiteFixtureSeed } from '../../surface/tools/lease-tools.js';
 import { homedir } from 'node:os';
+import { withShotRun } from '../../judgement/runs/default-run-id.js';
+import { defaultRunId } from '../../judgement/runs/default-run-id.js';
 import { resolveProjectCloud } from '../../memory/cloud/cloud-config.js';
 import { buildSuiteVerdict } from './decision.js';
 import { classifyFlowAssertions, flattenSteps } from './flow-classify.js';
@@ -24,10 +29,12 @@ import { flowsForSession } from './flow-store-for-session.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 { flowErrorMessage, latestRecordedFlow, sessionProjectId } from './flow-replay-run.js';
 import { persistAndSyncVerificationRun, } from '../../judgement/runs/verification-sync.js';
 import { runServerVerify } from './suite/server-verify.js';
 import { healFlow } from './heal-run.js';
+import { RESULT_FIELD, resultField, suiteResult } from '../../surface/tools/reticle-result.js';
+import { replayOneFlow } from './single-replay.js';
 export { replayNamedFlow } from './flow-replay-run.js';
 import { replayAndLearn } from './flow-learning.js';
 /**
@@ -81,7 +88,7 @@ export function leasableAppUrl(deps, sessionId) {
  * refusal on that path is deliberately silent — a fixture is an optimisation, and a suite must not
  * die when one is unavailable.
  */
-function sessionUrlOf(deps, sessionId) {
+export function sessionUrlOf(deps, sessionId) {
     try {
         return deps.sessions.resolve(sessionId).url;
     }
@@ -118,15 +125,17 @@ export const FLOW_TOOLS = [
     FLOW_MUTATE_TOOL,
     {
         name: ReticleTool.FLOW_SAVE,
-        description: 'Persist the last/active recording (by name) as a git-checked, anchor-resolved flow at .reticle/flows/<name>.json. Each step is bound to a SEMANTIC anchor (testid/role/signal), never a volatile ref; steps without a resolvable testid are kept with degraded:true (a "add a data-testid here" marker) rather than dropped. Returns { name, stepCount, degraded, empty, assertions, warning? } — `assertions.grade` is asserted | presence-only | assertion-free: a flow that only acts (or only checks element presence) will pass even if the feature breaks, so when grade is not "asserted" follow assertions.warning and add a consequence assertion via reticle_annotate (assert-signal / assert-net / success-state). `warning` is present when the recording left a page and returned to it: replay has no navigation steps, so the next click will look for a control on a page the tab is no longer on.',
+        description: 'Persist a STOPPED recording (by name) as a git-checked, anchor-resolved flow at .reticle/flows/<name>.json. A recording that is still running is refused: stop it first with reticle_record{action:"stop"}, and the refusal names the exact call. Each step is bound to a SEMANTIC anchor (testid/role/signal), never a volatile ref; steps without a resolvable testid are kept with degraded:true (a "add a data-testid here" marker) rather than dropped. Returns { name, stepCount, degraded, empty, assertions, warning? } — `assertions.grade` is asserted | presence-only | assertion-free: a flow that only acts (or only checks element presence) will pass even if the feature breaks, so when grade is not "asserted" follow assertions.warning and add a consequence assertion via reticle_annotate (assert-signal / assert-net / success-state). `warning` is present when the recording left a page and returned to it: replay has no navigation steps, so the next click will look for a control on a page the tab is no longer on.',
         inputSchema: {
             flow: z
                 .string()
                 .optional()
                 .describe('Alias for `flowName` (the name reticle_annotate uses).'),
+            name: z.string().optional().describe('Alias for `flowName`.'),
             flowName: z
                 .string()
-                .describe('Which RECORDING to save — the name reticle_record{start} was called with. This is a lookup key, not the filename: pass `saveAs` to choose that.'),
+                .optional()
+                .describe('Which RECORDING to save — the name reticle_record{start} was called with ("last-journey" for the reticle_act {steps} just proved). Omit when only one is stopped. This is a lookup key, not the filename: pass `saveAs` to choose that.'),
             saveAs: z
                 .string()
                 .optional()
@@ -162,6 +171,7 @@ export const FLOW_TOOLS = [
             })
                 .optional(),
             intentGap: INTENT_GAP_FIELD,
+            normalized: z.array(z.string()).optional(),
             warning: z
                 .string()
                 .optional()
@@ -170,7 +180,12 @@ export const FLOW_TOOLS = [
             code: z.string().optional(),
         },
         handler: (deps, args) => {
-            const name = asString(aliasParam(args, 'flowName', ['flow'])['flowName']) ?? '';
+            const aliases = ['flow', 'name', 'recordingName'];
+            const normalized = aliasUsed(args, 'flowName', aliases);
+            const explicitName = asString(aliasParam(args, 'flowName', aliases)['flowName']);
+            // The one stopped recording when the call names none — the same defaulting record{stop} and
+            // annotate use. With several, nothing is picked: the refusal below names them.
+            const name = resolveAnnotateTarget(explicitName, deps.recordings.compiled());
             const program = deps.recordings.getCompiled(name);
             if (program === undefined) {
                 /*
@@ -183,6 +198,13 @@ export const FLOW_TOOLS = [
                  * before the names were compared.
                  */
                 const held = deps.recordings.compiled();
+                const running = stillRecording(deps.recordings.active(), name, explicitName, held);
+                if (running !== undefined) {
+                    return Promise.resolve({
+                        error: stillRecordingMessage(running),
+                        code: FlowErrorCode.NO_RECORDING,
+                    });
+                }
                 return Promise.resolve({
                     error: 0 === held.length
                         ? flowErrorMessage(FlowErrorCode.NO_RECORDING)
@@ -251,6 +273,7 @@ export const FLOW_TOOLS = [
                 const invoked = loaded.ok ? await loadInvoked(flows, loaded.value, projectId) : new Map();
                 return loaded.ok
                     ? {
+                        ...(0 === normalized.length ? {} : { normalized }),
                         ...res.value,
                         ...(path === undefined ? {} : { path }),
                         assertions: classifyFlowAssertions(loaded.value, invoked),
@@ -391,10 +414,8 @@ export const FLOW_TOOLS = [
             flowName: z
                 .string()
                 .describe('Flow file name (without .json extension) from reticle_flow{action:"list"}.'),
-            confirmDangerous: z
-                .boolean()
-                .optional()
-                .describe('Set true to allow destructive controls during this replay only.'),
+            [CALL_SECRETS_ARG]: callSecretsArg,
+            confirmDangerous: confirmDangerousArg('this replay'),
             from: z
                 .union([z.number().int().nonnegative(), z.string().min(1)])
                 .optional()
@@ -409,10 +430,10 @@ export const FLOW_TOOLS = [
             at: z
                 .number()
                 .int()
-                .positive()
+                .nonnegative()
                 .max(MAX_REPLAY_STEP)
                 .optional()
-                .describe('Continue at this step on the page as it is (after another flow ran `to` it).'),
+                .describe('Continue at this step on the page as it is (after another flow ran `to` it); 0 replays the whole flow on the page the flow before it left, with no reload.'),
             sweep: z
                 .boolean()
                 .optional()
@@ -430,10 +451,12 @@ export const FLOW_TOOLS = [
                 .array(z.unknown())
                 .optional()
                 .describe('Present when `seed` was given: which endpoints were delayed, and by how long.'),
+            [RESULT_FIELD]: z.string().optional(),
             // 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 | unverifiable'),
+            runId: z.string().optional().describe('The run this replay was written down as.'),
             steps: z.array(z.unknown()),
             proposals: z.array(z.unknown()).optional(),
             deviation: z
@@ -487,42 +510,7 @@ export const FLOW_TOOLS = [
         },
         // The decision envelope is attached by replayNamedFlow only on drift/fail (clean pass stays
         // token-flat). Single-flow replay and whole-suite verify share that one implementation.
-        handler: async (deps, args) => {
-            const seed = asNumber(args['seed']);
-            if (seed === undefined)
-                return await replayAndLearn(deps, args);
-            /*
-             * Seeded chaos, and always put the page back.
-             *
-             * The targets are the endpoints the FLOW declared it depends on, so the perturbation lands on
-             * traffic the flow claims to care about rather than on something it never mentioned. 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, and it would
-             * inherit it as a mystery — the same rule the mutation loop had to earn.
-             */
-            const sessionId = asString(args['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);
-            const port = 0 === rules.length
-                ? undefined
-                : await sessionPerturbationPort(deps.realInput, leasableAppUrl(deps, sessionId));
-            if (port === undefined)
-                return replayAndLearn(deps, args);
-            try {
-                await port.slow(rules);
-                const replay = await replayNamedFlow(deps, args);
-                return { ...replay, perturbed: rules };
-            }
-            finally {
-                await port.clear().catch(() => undefined);
-            }
-        },
+        handler: (deps, args) => replayOneFlow(deps, args, leasableAppUrl(deps, asString(args['sessionId']))),
     },
     {
         name: ReticleTool.FLOW_VERIFY,
@@ -532,6 +520,7 @@ export const FLOW_TOOLS = [
             'whatChanged, whereInSource, nextAction }] } plus `flaky` (flows seen to pass AND fail on unchanged code) — passing flows are counted, only failures carry ' +
             'detail (the actionable fix). One call replaces N hand-driven replays.',
         inputSchema: {
+            [CALL_SECRETS_ARG]: callSecretsArg,
             names: z
                 .array(z.string())
                 .optional()
@@ -543,6 +532,7 @@ export const FLOW_TOOLS = [
             parallel: workerCountSchema
                 .optional()
                 .describe('Run this many flows at once, each in its own isolated leased browser context (needs the browser pool). Clamped to the pool capacity and the flow count. Omit for the sequential single-tab run.'),
+            confirmDangerous: confirmDangerousArg('this run of the suite'),
             sessionId: z
                 .string()
                 .optional()
@@ -550,10 +540,12 @@ export const FLOW_TOOLS = [
         },
         outputSchema: {
             status: z.string().describe('pass | fail'),
+            runId: z.string().optional().describe('The run this suite was written down as.'),
             total: z.number(),
             passed: z.number(),
             failed: z.number(),
             summary: z.string(),
+            [RESULT_FIELD]: z.string().optional(),
             failures: z.array(z.unknown()),
             isolation: z
                 .string()
@@ -595,8 +587,10 @@ export const FLOW_TOOLS = [
             // feedback ask here or a validating profile strips it off the suite verdict.
             feedback_prompt: z.unknown().optional(),
         },
-        handler: async (deps, args) => {
+        // The run id is minted first, so each replayed step's screenshot is filed under the run.
+        handler: (deps, args) => withShotRun(defaultRunId(), async () => {
             const sessionId = asString(args['sessionId']);
+            const confirmed = true === args['confirmDangerous'] ? { confirmDangerous: true } : {};
             // "Replay all" means all of THIS app's flows (+ legacy), not every project's on a shared daemon.
             const target = sessionTarget(deps, sessionId);
             const { projectId } = target;
@@ -652,7 +646,11 @@ export const FLOW_TOOLS = [
                     const start = deps.now();
                     const lease = await acquireLeasedSession(pool, deps.sessions, appUrl, projectId, seed);
                     try {
-                        const replay = await replayAndLearn(deps, { flowName, sessionId: lease.sessionId });
+                        const replay = await replayAndLearn(deps, {
+                            flowName,
+                            sessionId: lease.sessionId,
+                            ...confirmed,
+                        });
                         return { replay, durationMs: deps.now() - start };
                     }
                     finally {
@@ -673,12 +671,14 @@ export const FLOW_TOOLS = [
                     durationMs: o.ok && o.value !== undefined ? o.value.durationMs : 0,
                 }));
                 const flaky = await recordSuiteFlakes(deps.fs, rootForTarget(deps, target), parallelRuns);
-                await persistAndSyncVerificationRun(deps, timed, target);
+                const runId = await persistAndSyncVerificationRun(deps, timed, target);
                 const verdict = buildSuiteVerdict(parallelRuns, selected.knownRoutes, SuiteIsolation.PER_FLOW_LEASE);
                 return {
                     ...verdict,
+                    ...(runId === undefined ? {} : { runId }),
                     ...(flaky.length > 0 ? { flaky: [...flaky] } : {}),
                     ...heldBack,
+                    ...resultField(() => suiteResult(rootForTarget(deps, target), verdict, timed, runId)),
                 };
             }
             // The flow FILE travels with each replay so the verdict can tell a green that verified
@@ -696,7 +696,7 @@ export const FLOW_TOOLS = [
             // (1 of 2 flows). Restoring two thirds of a session is worse than restoring none.
             for (const flowName of requested) {
                 const start = deps.now();
-                const replay = await replayAndLearn(deps, { flowName, sessionId });
+                const replay = await replayAndLearn(deps, { flowName, sessionId, ...confirmed });
                 const loaded = await flowsForSession(deps, target)
                     .flows.load(flowName, projectId)
                     .catch(() => null);
@@ -714,17 +714,19 @@ export const FLOW_TOOLS = [
             // one an agent uses was the blind half.
             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, target);
+            const runId = 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
             // break. Present only when the ledger has seen enough runs to say so.
             return {
                 ...verdict,
+                ...(runId === undefined ? {} : { runId }),
                 ...(flaky.length > 0 ? { flaky: [...flaky] } : {}),
                 ...heldBack,
+                ...resultField(() => suiteResult(rootForTarget(deps, target), verdict, timed, runId)),
             };
-        },
+        }),
     },
     {
         name: ReticleTool.FLOW_SAVE_RECORDED,
@@ -819,10 +821,7 @@ export const FLOW_TOOLS = [
                 .describe('Alias for `flowName` (the name reticle_annotate uses).'),
             flowName: z.string().describe('Flow file name to heal (from reticle_flow{action:"list"}).'),
             apply: z.boolean().optional(),
-            confirmDangerous: z
-                .boolean()
-                .optional()
-                .describe('Set true to allow destructive controls during this heal replay only.'),
+            confirmDangerous: confirmDangerousArg('this heal replay'),
             sessionId: z
                 .string()
                 .optional()

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

@@ -11,6 +11,14 @@ export declare function anchorForStep(args: Record<string, unknown>): {
     anchor: FlowAnchor;
     degraded: boolean;
 };
+/**
+ * The recorded steps as they may be SHOWN: every credential fill carries the placeholder.
+ *
+ * The same rule the saved flow is written by, applied to what a tool hands back. `record stop`
+ * returned the compiled program verbatim, so the password a saved flow never contained went into
+ * the agent's transcript instead. The store keeps the real value — an in-session replay types it.
+ */
+export declare function redactRecordedSteps(steps: readonly RecordedStep[]): RecordedStep[];
 /**
  * What the anchor CALLS the field it points at.
  *
@@ -58,7 +66,14 @@ export interface FlowAnnotations {
 /** Persists anchored flows to .reticle/flows/<name>.json. Filesystem + clock are injected. */
 export declare class FlowStore {
     #private;
-    constructor(fs: FileSystemPort, root: string, clock: Clock);
+    /**
+     * `onWrote` is told after a save lands, so cloud sync cycles on a new flow the way it does on a
+     * new run (`RunStore` takes the same callback). Without it a flow saved with no run behind it
+     * waited for the timer, and a daemon that exited first never sent it.
+     */
+    constructor(fs: FileSystemPort, root: string, clock: Clock, opts?: {
+        onWrote?: () => void;
+    });
     /**
      * Convert a CompiledProgram (testid-normalized) into an anchored, on-disk flow + write it.
      * Optionally fold structured annotations (per-step expect, dynamic[], success) onto

package/dist/language/flows/flows.js

@@ -1,15 +1,15 @@
 import { asFlowName, asProjectId, } from '@reticlehq/core';
-import { REDACTED_FILL } from './fields/flow-secret-field.js';
+import { REDACTED_FILL, SECRET_NAME_ARG, secretEnvKey } from './fields/flow-secret-field.js';
 export { REDACTED_FILL, secretEnvKey } from './fields/flow-secret-field.js';
 import { safeProjectId } from './flow-result.js';
 import { changeInPlace } from './narrow-write.js';
 import { AnchorKind, DEGRADED_ANCHOR_ROLE, FLOW_FILE_VERSION, flowFileVersionFor, FlowErrorCode, FlowFileSchema, FlowStepTool, QueryBy, defaultIsSensitiveKey, } from '@reticlehq/core';
-import { ReticleTool } from '@reticlehq/core';
+import { ReticleTool, flowJsonReplacer } from '@reticlehq/core';
 import { asRecord, asString } from '@reticlehq/core';
 import { applyHealChanges } from './heal.js';
 import { withLearnedSources } from './learned-sources.js';
 import { flowIntentGap, linkFlowIntent } from './flow-intent.js';
-import { journeyFingerprint, journeyName, mergeJourney, routeClaims } from './flow-journey.js';
+import { journeyFingerprint, journeyName, mergeJourney, routeClaims, withinJourney, } from './flow-journey.js';
 import { IntentStore } from '../../memory/intent/intent-store.js';
 import { flowDir, flowParentDir, flowPath, reticleDirPaths, isValidFlowName, } from '../../memory/project/dir/reticle-dir.js';
 import { describeFlowZodFailure, parseFlowFileText } from './flow-expect-grammar.js';
@@ -130,7 +130,32 @@ function redactSecretFill(anchor, args) {
     const field = anchorFieldName(anchor);
     if (field === undefined || !defaultIsSensitiveKey(field))
         return args;
-    return { ...args, value: REDACTED_FILL };
+    // The variable that supplies it, beside the placeholder: the file alone says what to set.
+    return { ...args, value: REDACTED_FILL, [SECRET_NAME_ARG]: secretEnvKey(field) };
+}
+/**
+ * The recorded steps as they may be SHOWN: every credential fill carries the placeholder.
+ *
+ * The same rule the saved flow is written by, applied to what a tool hands back. `record stop`
+ * returned the compiled program verbatim, so the password a saved flow never contained went into
+ * the agent's transcript instead. The store keeps the real value — an in-session replay types it.
+ */
+export function redactRecordedSteps(steps) {
+    return steps.map((step) => {
+        if (step.tool === ReticleTool.ACT_SEQUENCE && Array.isArray(step.args['steps'])) {
+            const subs = step.args['steps'].map((raw) => redactNormalizedArgs(asRecord(raw)));
+            return { ...step, args: { ...step.args, steps: subs } };
+        }
+        return { ...step, args: redactNormalizedArgs(step.args) };
+    });
+}
+/** One normalized act's args with its inner fill `args` redacted by the anchor it would save as. */
+function redactNormalizedArgs(normalized) {
+    const inner = normalized['args'];
+    if ('object' !== typeof inner || null === inner)
+        return normalized;
+    const redacted = redactSecretFill(anchorForStep(normalized).anchor, asRecord(inner));
+    return redacted === inner ? normalized : { ...normalized, args: redacted };
 }
 /**
  * What the anchor CALLS the field it points at.
@@ -169,6 +194,8 @@ function buildStep(tool, anchor, action, args, degraded) {
  */
 export function recordedStepToFlowStep(step) {
     const out = anchoredStep(step);
+    if (step.timeoutMs !== undefined)
+        out.timeoutMs = step.timeoutMs;
     if (step.page !== undefined)
         out.page = step.page;
     if (step.endPage !== undefined && step.endPage !== step.page)
@@ -238,10 +265,17 @@ export class FlowStore {
     #fs;
     #root;
     #clock;
-    constructor(fs, root, clock) {
+    #onWrote;
+    /**
+     * `onWrote` is told after a save lands, so cloud sync cycles on a new flow the way it does on a
+     * new run (`RunStore` takes the same callback). Without it a flow saved with no run behind it
+     * waited for the timer, and a daemon that exited first never sent it.
+     */
+    constructor(fs, root, clock, opts = {}) {
         this.#fs = fs;
         this.#root = root;
         this.#clock = clock;
+        this.#onWrote = opts.onWrote;
     }
     /**
      * The single byte-stable flow serializer: 2-space indent + one trailing newline. save,
@@ -250,7 +284,7 @@ export class FlowStore {
      */
     #serialize(flow) {
         const stamped = { ...flow, version: flowFileVersionFor(flow) };
-        return `${JSON.stringify(stamped, null, JSON_INDENT)}\n`;
+        return `${JSON.stringify(stamped, flowJsonReplacer, JSON_INDENT)}\n`;
     }
     /**
      * Register the flow's business goal in the intent ledger and stamp the row's id onto the flow.
@@ -324,6 +358,7 @@ export class FlowStore {
         const flow = await this.#linkIntent(base);
         await this.#fs.mkdir(flowParentDir(this.#root, program.name, pid));
         await this.#fs.writeFile(flowPath(this.#root, program.name, pid), this.#serialize(flow));
+        this.#onWrote?.();
         return { ok: true, value: this.#summary(flow) };
     }
     /**
@@ -340,19 +375,40 @@ export class FlowStore {
         const pid = safeProjectId(projectId);
         const fresh = this.#build(program, undefined, pid);
         const saved = [];
-        for (const name of (await this.list(pid)).filter((n) => n.startsWith(prefix))) {
+        const freshPrint = journeyFingerprint(fresh);
+        for (const name of await this.list(pid)) {
             const loaded = await this.load(name, pid);
-            if (loaded.ok)
+            if (!loaded.ok)
+                continue;
+            if (name.startsWith(prefix))
                 saved.push(loaded.value);
+            // The agent already saved this journey under its own name: one journey, one flow. A web drive
+            // saved its named flow and an automatic `drive-saved-<email>` beside it, every time.
+            else if (journeyFingerprint(loaded.value) === freshPrint) {
+                return { ok: true, value: this.#summary(loaded.value) };
+            }
         }
         const byPrint = new Map();
         for (const flow of saved) {
             const print = journeyFingerprint(flow);
             byPrint.set(print, [...(byPrint.get(print) ?? []), flow]);
         }
-        const print = journeyFingerprint(fresh);
+        const print = freshPrint;
         const taken = new Map(saved.map((flow) => [flow.name, journeyFingerprint(flow)]));
-        const named = { ...fresh, name: journeyName(fresh.name, print, taken) };
+        // The same name holding this journey driven with a step more or less: one file, the fuller drive.
+        const same = saved.find((flow) => flow.name === fresh.name && taken.get(flow.name) !== print);
+        if (same !== undefined && withinJourney(same, fresh))
+            return { ok: true, value: this.#summary(same) };
+        const extended = same !== undefined && withinJourney(fresh, same);
+        if (extended)
+            taken.delete(fresh.name);
+        const named = {
+            ...fresh,
+            ...(extended && fresh.intent === undefined && same.intent !== undefined
+                ? { intent: same.intent }
+                : {}),
+            name: journeyName(fresh.name, print, taken),
+        };
         byPrint.set(print, [...(byPrint.get(print) ?? []), named]);
         let result = named;
         for (const [groupPrint, group] of byPrint) {
@@ -370,6 +426,7 @@ export class FlowStore {
             if (groupPrint === print)
                 result = merged;
         }
+        this.#onWrote?.();
         return { ok: true, value: this.#summary(result) };
     }
     /** Write a flow where it already lives, or into its project's directory when it is new. */
@@ -404,6 +461,7 @@ export class FlowStore {
         const valid = await this.#linkIntent(parsed.data);
         await this.#fs.mkdir(flowParentDir(this.#root, asFlowName(valid.name), pid));
         await this.#fs.writeFile(flowPath(this.#root, asFlowName(valid.name), pid), this.#serialize(valid));
+        this.#onWrote?.();
         return { ok: true, value: this.#summary(valid) };
     }
     /**
@@ -422,6 +480,7 @@ export class FlowStore {
             resolvePath: (n, p) => this.#resolveReadPath(asFlowName(n), p),
             write: (path, contents) => this.#fs.writeFile(path, contents),
             serialize: (flow) => this.#serialize(flow),
+            readRaw: (path) => this.#fs.readFile(path),
         }, name, projectId, change);
     }
     /** Write back only what a replay LEARNED. See `#changeInPlace` for why it is not `saveFlow`. */