@reticlehq/server 2.14.0 → 3.2.0

package/dist/language/flows/replay.js

@@ -0,0 +1,397 @@
+import { REDACTED_FILL, secretEnvKey } from './fields/flow-secret-field.js';
+import { DANGEROUS_ACTION_CONFIRM_ARG, ReticleCommand, QueryBy, } from '@reticlehq/core';
+import { ReticleTool } from '@reticlehq/core';
+import { formatStepAddress } from 'open-verification';
+import { predicateToExpect, enforcedOnReplay } from '../../judgement/outcome/predicate-to-expect.js';
+import { PredicateSchema } from '@reticlehq/engine/question/predicate/predicate.js';
+import { asRecord, asString } from '@reticlehq/core';
+/**
+ * The note attached when a testid resolves to multiple live elements (the first match is used).
+ * Shared by BOTH replay engines (replayProgram + flow-replay's step runner) so the phrasing — which
+ * an agent reads to judge a brittle locator — can never drift between them.
+ */
+export function ambiguousTestidNote(value) {
+    return `ambiguous testid '${value}', used first match`;
+}
+/**
+ * The live element refs a QUERY resolved to (empty when it failed or matched nothing). Shared by BOTH
+ * replay engines (replayProgram + flow-replay's step runner) so element extraction — the core of anchor
+ * resolution — can't drift between them.
+ */
+export function queryRefs(result) {
+    if (!result.ok)
+        return [];
+    const payload = asRecord(result.result);
+    const elements = Array.isArray(payload['elements']) ? payload['elements'] : [];
+    return elements.map((e) => asString(asRecord(e)['ref']) ?? '').filter((r) => r.length > 0);
+}
+/**
+ * A destructive-action confirmation is one-shot and must never persist into a recording.
+ *
+ * This is also where a REDACTED fill is supplied back. Stripping credentials out of a git-checked
+ * flow is only half a fix: sign-in still has to replay, and a flow that drifts at step two forever
+ * because its own password was removed is a flow nobody keeps — along with everything behind the
+ * login it guards. The value comes from the environment, the one place a secret can live that is
+ * neither the customer's repository nor our database.
+ *
+ * Left as the PLACEHOLDER when nothing supplies it, rather than blanked. The replay then fails at
+ * the login form with `<redacted: supply at replay>` visible in the field, which names its own fix;
+ * an empty box fails identically and tells the reader nothing.
+ */
+export function replayActionArgs(value, confirmDangerous = false, field) {
+    const args = { ...asRecord(value) };
+    delete args[DANGEROUS_ACTION_CONFIRM_ARG];
+    if (confirmDangerous)
+        args[DANGEROUS_ACTION_CONFIRM_ARG] = true;
+    if (REDACTED_FILL === args['value'] && field !== undefined) {
+        const supplied = process.env[secretEnvKey(field)];
+        if (supplied !== undefined && supplied.length > 0)
+            args['value'] = supplied;
+    }
+    return args;
+}
+/**
+ * The field a compiled recording step names — the same mapping `anchorFieldName` uses on a
+ * FlowAnchor, read off the `by`/`value`/`name` shape `compileAnchorArgs` emits.
+ */
+function recordedFieldName(step) {
+    const by = asString(step['by']);
+    if (QueryBy.TESTID === by)
+        return asString(step['value']);
+    if (QueryBy.ROLE === by)
+        return asString(step['name']);
+    return undefined;
+}
+/** The element's source location from an action result, when the framework stamped one. */
+function sourceFromResult(res) {
+    const source = asRecord(res['source']);
+    if (typeof source['file'] !== 'string' || typeof source['line'] !== 'number')
+        return undefined;
+    const out = { file: source['file'], line: source['line'] };
+    if ('number' === typeof source['column'])
+        out['column'] = source['column'];
+    return out;
+}
+/**
+ * Capture an act into every in-flight recording, or do nothing when none is running.
+ *
+ * Every tool that drives the page must call this. reticle_act_and_wait did not, which is the tool
+ * the documented agent recipe drives with — so "record start -> drive -> record stop -> flow_save"
+ * saved a flow with zero steps.
+ */
+export function captureAct(recordings, args, res, 
+/** Where this step ran, so the ambient tape can be cut into journeys. See RecordedStep.route. */
+route) {
+    // NO `active()` gate. `RecordingStore.capture` opens the AMBIENT tape on its first step, and that
+    // branch was unreachable from here: this returned early whenever nothing was open, and the only
+    // thing that opened anything was `reticle_record { action: "start" }`. So the comment on `capture`
+    // — "recording is a property of the system rather than a rule an agent has to remember" — was true
+    // about the intent and false about the code, and every drive nobody wrapped by hand was discarded.
+    //
+    // That is the whole supply of regression tests this product could have had for free: the corpus
+    // measures 3 of 33 flows mutation-testable and 6 of 112 steps declaring a consequence, and a drive
+    // that is never recorded cannot contribute to either.
+    const step = compileActStep(args, res);
+    // Keep the assertion the agent actually made. `act_and_wait { until }` IS the agent saying what
+    // success means — the large majority of calls carry one — and dropping it produced a flow graded
+    // "assertion-free: it will pass even if the feature is broken", which is the regression-suite
+    // story failing at its last step. Only kinds FlowExpect can express survive; see
+    // predicate-to-expect.ts.
+    const expect = enforceableExpect(args['until'] ?? args['predicate']);
+    if (expect !== undefined)
+        step.expect = expect;
+    recordings.capture(step, route);
+}
+/**
+ * A declared predicate, as a recorded expectation — or nothing.
+ *
+ * The ONE place this conversion happens, because it is the rule that decides whether a saved flow
+ * proves anything, and two copies of it would drift. Only kinds a replay actually CHECKS survive:
+ * recording an unenforced assertion grades the flow "asserted" while nothing verifies it, which is a
+ * false green inside the feature built to prevent them. See enforcedOnReplay.
+ */
+function enforceableExpect(raw) {
+    if (raw === undefined)
+        return undefined;
+    const parsed = PredicateSchema.safeParse(raw);
+    return parsed.success ? enforcedOnReplay(predicateToExpect(parsed.data)) : undefined;
+}
+/**
+ * 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
+ * component identity / source location (the AUTO-ANCHOR) keeps the step STABLE instead of degrading to
+ * a volatile ref. Only when neither is available is the step ref-bound (in-session only).
+ */
+export function compileActStep(args, res) {
+    const { args: compiled, stable } = compileAnchorArgs(asRecord(res), asString(args['ref']) ?? '', asString(args['action']) ?? '', replayActionArgs(args['args']));
+    return { tool: ReticleTool.ACT, stable, args: compiled };
+}
+/**
+ * The ONE anchor chooser: testid (gold) > role+name (identifies an instance) > component/source
+ * (the JSX site) > a volatile ref (in-session only).
+ *
+ * It is shared because it was not: `compileSequenceStep` understood only a testid, so every
+ * act_sequence sub-step on a testid-less app compiled to a ref, saved as the degraded `unresolved`
+ * sentinel, and drifted on every replay — while a single act on the very same element compiled a
+ * perfectly stable anchor.
+ */
+function compileAnchorArgs(r, ref, action, actArgs) {
+    const testid = asString(r['testid']);
+    const source = sourceFromResult(r);
+    if (testid !== undefined) {
+        // The testid anchors the step; source rides along purely so a failure can name a file. Carrying
+        // both was the point of separating anchor from provenance at capture time.
+        const testidArgs = {
+            by: QueryBy.TESTID,
+            value: testid,
+            action,
+            args: actArgs,
+        };
+        if (source !== undefined)
+            testidArgs['source'] = source;
+        return { args: testidArgs, stable: true };
+    }
+    // Role + NAME before component: a component/source anchor names the JSX site, so every row's copy
+    // of the same control collapses onto it. The accessible name separates them, and it is also the
+    // only stable anchor an app with no testids has. Measured: three rows' checkboxes compiled to one
+    // identical component anchor and replayed onto a single element.
+    const role = asString(r['role']);
+    const name = asString(r['name']);
+    if (role !== undefined && name !== undefined) {
+        const roleArgs = {
+            by: QueryBy.ROLE,
+            value: role,
+            name,
+            action,
+            args: actArgs,
+        };
+        if (source !== undefined)
+            roleArgs['source'] = source;
+        return { args: roleArgs, stable: true };
+    }
+    const component = asString(r['component']);
+    if (component !== undefined || source !== undefined) {
+        const componentArgs = { by: QueryBy.COMPONENT, action, args: actArgs };
+        if (component !== undefined)
+            componentArgs['component'] = component;
+        if (source !== undefined)
+            componentArgs['source'] = source;
+        return { args: componentArgs, stable: true };
+    }
+    return { args: { ref, action, args: actArgs }, stable: false };
+}
+/**
+ * Compile an reticle_act_sequence invocation, normalizing each sub-step through the SAME anchor
+ * priority a single act uses (see compileAnchorArgs) — not testid-or-nothing, which is what made
+ * every sequence unreplayable on an app without testids.
+ */
+export function compileSequenceStep(args, res) {
+    const inputSteps = Array.isArray(args['steps']) ? args['steps'] : [];
+    const resolved = Array.isArray(asRecord(res)['steps'])
+        ? asRecord(res)['steps']
+        : [];
+    let stable = inputSteps.length > 0;
+    const subSteps = inputSteps.map((raw, i) => {
+        const step = asRecord(raw);
+        const compiled = compileAnchorArgs(asRecord(resolved[i]), asString(step['ref']) ?? '', asString(step['action']) ?? '', replayActionArgs(step['args']));
+        if (!compiled.stable)
+            stable = false;
+        // Each sub-step keeps its OWN declared consequence. A sequence records one step and replays as
+        // one batch, but what each step CLAIMED is per step -- folding them together would let one
+        // signal answer for every click in the journey.
+        const expect = enforceableExpect(step['expect']);
+        return expect === undefined ? compiled.args : { ...compiled.args, expect };
+    });
+    return { tool: ReticleTool.ACT_SEQUENCE, stable, args: { steps: subSteps } };
+}
+/**
+ * Resolve a recorded step's element to a live ref, by whichever anchor the compiler chose.
+ *
+ * Every anchor the compiler can EMIT must be resolvable here. It could not be: `compileActStep`
+ * emits `by: component` steps (and marks them `stable: true`), and this function only understood
+ * `testid` — so every component-anchored step failed with "no testid or ref to resolve", and the
+ * `stable` flag on it was a claim the replayer could not honour. Measured on a console with 5 steps:
+ * the 2 with testids replayed, the 3 without were unreplayable, and the flow reported ok:false at
+ * the first of them.
+ */
+async function resolveRef(session, step) {
+    const by = asString(step.by);
+    const value = asString(step.value);
+    if (by === QueryBy.TESTID && value !== undefined) {
+        const result = await session.command(ReticleCommand.QUERY, { by, value });
+        if (!result.ok)
+            throw new Error(result.error ?? 'query failed');
+        const refs = queryRefs(result);
+        const ref = refs[0];
+        if (ref === undefined)
+            throw new Error(`testid '${value}' did not resolve in current page`);
+        return refs.length > 1 ? { ref, note: ambiguousTestidNote(value) } : { ref };
+    }
+    // Role + accessible NAME: the anchor that distinguishes one row's control from another's, which
+    // neither a testid-less app nor a shared JSX source location can do.
+    if (by === QueryBy.ROLE && value !== undefined) {
+        const name = asString(step.name);
+        const query = { by, value, ...(name === undefined ? {} : { name }) };
+        const result = await session.command(ReticleCommand.QUERY, query);
+        if (!result.ok)
+            throw new Error(result.error ?? 'query failed');
+        const ref = queryRefs(result)[0];
+        if (ref === undefined) {
+            throw new Error(`${value} named '${String(name)}' did not resolve in current page`);
+        }
+        return { ref };
+    }
+    if (by === QueryBy.COMPONENT) {
+        const component = asString(step.component);
+        const source = step.source;
+        const query = {
+            by,
+            ...(component === undefined ? {} : { component, value: component }),
+            ...(source === undefined ? {} : { source }),
+        };
+        const result = await session.command(ReticleCommand.QUERY, query);
+        if (!result.ok)
+            throw new Error(result.error ?? 'query failed');
+        const refs = queryRefs(result);
+        const ref = refs[0];
+        if (ref === undefined) {
+            throw new Error(`component '${String(component)}' did not resolve in current page`);
+        }
+        // A source location identifies a JSX SITE, not an instance: one `<input>` inside a row renders
+        // once per row and every one of them shares this anchor. Saying so is the difference between a
+        // replay that repeated itself and a replay that reports it might have.
+        return refs.length > 1
+            ? {
+                ref,
+                note: `component anchor matched ${String(refs.length)} elements — replayed the first`,
+            }
+            : { ref };
+    }
+    const ref = asString(step.ref);
+    if (ref === undefined || 0 === ref.length) {
+        throw new Error('step has no resolvable anchor (testid, role+name, component) and no ref');
+    }
+    return { ref, note: 'replayed by stale ref (not portable across sessions)' };
+}
+/** Re-execute every step of a compiled program in order, stopping at the first failure. */
+export async function replayProgram(session, program, confirmDangerous = false, 
+/**
+ * How to find an invoked document. Absent means this replayer cannot follow one — and an
+ * unfollowable invocation FAILS rather than being skipped, because a composite that reports green
+ * having silently not run a sub-journey is the false green this layer exists to prevent, arriving
+ * through the feature meant to strengthen it.
+ */
+resolve, 
+/** The invocation chain that reached this program, nearest caller first. Empty at the top. */
+via = []) {
+    const results = [];
+    let index = -1;
+    for (const step of program.steps) {
+        index += 1;
+        if (step.invoke !== undefined) {
+            const site = { flow: program.name, step: index, via };
+            const address = formatStepAddress(site);
+            const chain = [...via.map((v) => v.flow), program.name];
+            if (chain.includes(step.invoke)) {
+                // Typecheck catches this at rest and the replayer does not trust it: the document set can
+                // change between the check and the run, and an infinite replay is not a thing to find out
+                // about live.
+                results.push({
+                    tool: step.tool,
+                    ok: false,
+                    at: address,
+                    error: `invocation returns to a document already running: ${[...chain, step.invoke].join(' → ')}`,
+                });
+                break;
+            }
+            const sub = resolve?.(step.invoke);
+            if (sub === undefined) {
+                results.push({
+                    tool: step.tool,
+                    ok: false,
+                    at: address,
+                    error: `cannot replay "${step.invoke}": it was not found, so this journey would report green having never run it`,
+                });
+                break;
+            }
+            results.push({ tool: step.tool, ok: true, at: address, note: `entered ${step.invoke}` });
+            const nested = await replayProgram(session, sub, confirmDangerous, resolve, [
+                { flow: program.name, step: index },
+                ...via,
+            ]);
+            results.push(...nested);
+            if (nested.some((r) => !r.ok))
+                break;
+            continue;
+        }
+        try {
+            if (step.tool === ReticleTool.ACT_SEQUENCE) {
+                const subs = Array.isArray(step.args['steps']) ? step.args['steps'] : [];
+                const notes = [];
+                const liveSteps = [];
+                for (const raw of subs) {
+                    const sub = asRecord(raw);
+                    const { ref, note } = await resolveRef(session, sub);
+                    if (note !== undefined)
+                        notes.push(note);
+                    liveSteps.push({
+                        ref,
+                        action: asString(sub['action']) ?? '',
+                        args: replayActionArgs(sub['args'], confirmDangerous, recordedFieldName(sub)),
+                    });
+                }
+                // Attribute the step's effects to the step: unattributed effects are learned as ambient
+                // churn on the regions the flow exercises, which teaches the settle oracle to ignore them.
+                session.beginAction(ReticleTool.REPLAY, { steps: liveSteps.length });
+                let r;
+                try {
+                    // DIVERGENCE: replay sends one batched ACT_SEQUENCE command to the browser;
+                    // live (tools/act-tools.ts) sends N individual ACT commands for per-step timeout +
+                    // progress. A bug in either is invisible from the other.
+                    r = await session.command(ReticleCommand.ACT_SEQUENCE, { steps: liveSteps });
+                }
+                finally {
+                    session.finishAction();
+                }
+                results.push(buildResult(step.tool, r.ok, r.error, notes));
+                if (!r.ok)
+                    break;
+            }
+            else {
+                const { ref, note } = await resolveRef(session, step.args);
+                session.beginAction(ReticleTool.REPLAY, { ref });
+                let r;
+                try {
+                    r = await session.command(ReticleCommand.ACT, {
+                        ref,
+                        action: asString(step.args['action']) ?? '',
+                        args: replayActionArgs(step.args['args'], confirmDangerous, recordedFieldName(step.args)),
+                    });
+                }
+                finally {
+                    session.finishAction();
+                }
+                results.push(buildResult(step.tool, r.ok, r.error, note !== undefined ? [note] : []));
+                if (!r.ok)
+                    break;
+            }
+        }
+        catch (e) {
+            results.push({
+                tool: step.tool,
+                ok: false,
+                error: e instanceof Error ? e.message : String(e),
+            });
+            break;
+        }
+    }
+    return results;
+}
+function buildResult(tool, ok, error, notes) {
+    const base = { tool, ok };
+    if (!ok)
+        base.error = error ?? 'command failed';
+    if (notes.length > 0)
+        base.note = notes.join('; ');
+    return base;
+}

package/dist/language/flows/role-anchor-nearest.js

@@ -0,0 +1,45 @@
+/**
+ * The closest surviving control to a role+name anchor that no longer resolves.
+ *
+ * `runRoleStep` returned `nearest: null` as a literal, so `flow_heal` answered "no nearest match
+ * cleared the confidence floor" for every role-anchored drift — which reads as a judgement about
+ * candidates when in fact nothing had looked. Reported from a real sweep: a three-step flow failed
+ * on `button named 'Menu' did not resolve` and heal called it unhealable, however small the change.
+ *
+ * What this does NOT do is make role anchors auto-healable, and that restraint is the point. A
+ * testid is an identifier a developer put there deliberately; a role name is user-visible text where
+ * "Save" and "Save as" are one edit apart. Silently rebinding a step to a similar-looking control is
+ * precisely the wrong-element green this product exists to catch. So the bar here is deliberately
+ * higher than the testid path's: same role, unambiguous, and genuinely close — otherwise null, and
+ * the agent is told to add a testid.
+ */
+import { editDistance } from './flow-anchor.js';
+/**
+ * A name must be at least this similar to be worth showing: at most a third of it changed. A looser
+ * bar turns "no candidate" into "a confident wrong one", which is worse than saying nothing.
+ */
+const MAX_CHANGED_FRACTION = 1 / 3;
+export function nearestRoleName(role, missing, present) {
+    const sameRole = present.filter((candidate) => candidate.role === role);
+    if (0 === sameRole.length)
+        return null;
+    const budget = Math.floor(missing.length * MAX_CHANGED_FRACTION);
+    let best = null;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    let tied = false;
+    for (const candidate of sameRole) {
+        const distance = editDistance(missing, candidate.name);
+        if (distance < bestDistance) {
+            bestDistance = distance;
+            best = candidate.name;
+            tied = false;
+        }
+        else if (distance === bestDistance) {
+            tied = true;
+        }
+    }
+    // A tie is a coin flip between two live controls; naming one would be inventing confidence.
+    if (null === best || tied || bestDistance > budget)
+        return null;
+    return best;
+}

package/dist/language/flows/stores/assertion-tiers-store.d.ts

@@ -0,0 +1,26 @@
+import type { FileSystemPort } from '../../../memory/project/fs/fs-port.js';
+import type { StepExpect } from '../../../judgement/outcome/assertion-integrity.js';
+interface FlowBaseline {
+    steps: StepExpect[];
+    sources: string[];
+}
+type FlowTiers = Record<string, FlowBaseline>;
+/**
+ * The shape version of the file on disk.
+ *
+ * Exported so a test can pin it. Changing this number makes every baseline already on disk fail to
+ * parse, and because an unreadable baseline degrades to "no baseline" (see the note above), the
+ * anti-downgrade check would quietly stop checking anything with nothing going red to say so. If you
+ * change it, add a way to handle the old file in the same commit — convert it on load, or tell the
+ * user their baseline was reset.
+ */
+export declare const ASSERTION_TIERS_VERSION = 1;
+export declare class AssertionTiersStore {
+    #private;
+    constructor(fs: FileSystemPort, root: string);
+    load(): Promise<FlowTiers>;
+    save(tiers: FlowTiers): Promise<void>;
+    /** Record one flow's assertion shape + covered sources after it PASSED. Never breaks a replay. */
+    recordPassing(name: string, steps: readonly StepExpect[], sources?: readonly string[]): Promise<void>;
+}
+export {};

package/dist/language/flows/stores/assertion-tiers-store.js

@@ -0,0 +1,107 @@
+import { dirname } from 'node:path';
+import { z } from 'zod';
+import { reticleDirPaths } from '../../../memory/project/dir/reticle-dir.js';
+import { withFileLock } from '../../../memory/project/file-lock.js';
+/**
+ * The anti-reward-hacking baseline. Detecting an assertion DOWNGRADE requires knowing what the
+ * flow asserted the last time it PASSED — otherwise a weakened flow simply looks like a flow that always
+ * asserted little. Flows are git-checked and agent-editable, so we cannot trust the file itself as its own
+ * history.
+ *
+ * So: on every passing replay we record that flow's per-step assertion shape here, and the gate diffs the
+ * current file against it. Recorded only on PASS, deliberately — a failing run must never become the
+ * baseline a later weakening is measured against.
+ *
+ * Loads never throw: a missing/corrupt ledger degrades to "no baseline", which means no downgrade can be
+ * claimed. Failing OPEN is right here — accusing an agent of gaming the gate on the strength of an
+ * unreadable file would be worse than missing one downgrade.
+ */
+const AssertionTiersFileSchema = z.object({
+    version: z.literal(1),
+    flows: z.record(z.object({
+        steps: z.array(z.object({ step: z.number(), expect: z.unknown().optional() })),
+        /** Source files this flow covered when it last passed — lets the gate scope DELETION findings to
+         * the files that actually changed, instead of flagging every intentionally-removed flow. */
+        sources: z.array(z.string()).default([]),
+    })),
+});
+/**
+ * The shape version of the file on disk.
+ *
+ * Exported so a test can pin it. Changing this number makes every baseline already on disk fail to
+ * parse, and because an unreadable baseline degrades to "no baseline" (see the note above), the
+ * anti-downgrade check would quietly stop checking anything with nothing going red to say so. If you
+ * change it, add a way to handle the old file in the same commit — convert it on load, or tell the
+ * user their baseline was reset.
+ */
+export const ASSERTION_TIERS_VERSION = 1;
+export class AssertionTiersStore {
+    #fs;
+    #path;
+    constructor(fs, root) {
+        this.#fs = fs;
+        this.#path = reticleDirPaths(root).tiers;
+    }
+    async load() {
+        let text;
+        try {
+            text = await this.#fs.readFile(this.#path);
+        }
+        catch (error) {
+            if (this.#fs.isNotFound(error))
+                return {};
+            throw error;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            return {};
+        }
+        const result = AssertionTiersFileSchema.safeParse(parsed);
+        if (!result.success)
+            return {};
+        const out = {};
+        for (const [name, entry] of Object.entries(result.data.flows)) {
+            out[name] = {
+                steps: entry.steps.map((s) => ({
+                    step: s.step,
+                    ...(s.expect === undefined ? {} : { expect: s.expect }),
+                })),
+                sources: entry.sources,
+            };
+        }
+        return out;
+    }
+    async save(tiers) {
+        await this.#fs.mkdir(dirname(this.#path));
+        const body = `${JSON.stringify({ version: ASSERTION_TIERS_VERSION, flows: tiers }, null, 2)}\n`;
+        const tmp = `${this.#path}.tmp`;
+        await this.#fs.writeFile(tmp, body);
+        await this.#fs.rename(tmp, this.#path);
+    }
+    /** Record one flow's assertion shape + covered sources after it PASSED. Never breaks a replay. */
+    async recordPassing(name, steps, sources = []) {
+        try {
+            // Serialized per file: a fresh store instance is created per flow (flow-replay-run), so parallel
+            // passing replays would otherwise each load the same baseline, add only THEIR flow, and the last
+            // save would drop every other flow's baseline — the downgrade-detection gate silently losing
+            // coverage. The lock is keyed by path, so it serializes across those distinct instances.
+            await withFileLock(this.#path, async () => {
+                const all = await this.load();
+                all[name] = {
+                    steps: steps.map((s) => ({
+                        step: s.step,
+                        ...(s.expect === undefined ? {} : { expect: s.expect }),
+                    })),
+                    sources: [...sources],
+                };
+                await this.save(all);
+            });
+        }
+        catch {
+            // a ledger write must never fail a green replay
+        }
+    }
+}

package/dist/language/flows/stores/flake-store.d.ts

@@ -0,0 +1,18 @@
+import type { FileSystemPort } from '../../../memory/project/fs/fs-port.js';
+import { type FlakeLedger } from '../recording/flake.js';
+/**
+ * Persists the per-flow flake ledger at `.reticle/flake.json`. Local single-project memory (stays OSS —
+ * OSS-VS-SERVER). Loads never throw: missing/malformed/wrong-version degrades to an empty ledger, so
+ * a bad file never blocks a gate — it just re-learns flakiness. `record` accrues one unchanged-code
+ * replay outcome; `flakyFlows` is what the gate quarantines.
+ */
+export declare class FlakeStore {
+    #private;
+    constructor(fs: FileSystemPort, root: string);
+    load(): Promise<FlakeLedger>;
+    save(ledger: FlakeLedger): Promise<void>;
+    /** Accrue one unchanged-code replay outcome for a flow and persist. */
+    record(flow: string, passed: boolean): Promise<void>;
+    /** The flows currently quarantined as flaky — what the gate excludes from blocking. */
+    flakyFlows(): Promise<string[]>;
+}

package/dist/language/flows/stores/flake-store.js

@@ -0,0 +1,58 @@
+import { dirname } from 'node:path';
+import { reticleDirPaths } from '../../../memory/project/dir/reticle-dir.js';
+import { FlakeFileSchema, emptyRecord, isFlaky, recordOutcome, } from '../recording/flake.js';
+const FLAKE_FILE_VERSION = 1;
+/**
+ * Persists the per-flow flake ledger at `.reticle/flake.json`. Local single-project memory (stays OSS —
+ * OSS-VS-SERVER). Loads never throw: missing/malformed/wrong-version degrades to an empty ledger, so
+ * a bad file never blocks a gate — it just re-learns flakiness. `record` accrues one unchanged-code
+ * replay outcome; `flakyFlows` is what the gate quarantines.
+ */
+export class FlakeStore {
+    #fs;
+    #path;
+    constructor(fs, root) {
+        this.#fs = fs;
+        this.#path = reticleDirPaths(root).flake;
+    }
+    async load() {
+        let text;
+        try {
+            text = await this.#fs.readFile(this.#path);
+        }
+        catch (error) {
+            if (this.#fs.isNotFound(error))
+                return {};
+            throw error;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            return {};
+        }
+        const result = FlakeFileSchema.safeParse(parsed);
+        return result.success ? result.data.flows : {};
+    }
+    async save(ledger) {
+        await this.#fs.mkdir(dirname(this.#path));
+        const body = `${JSON.stringify({ version: FLAKE_FILE_VERSION, flows: ledger }, null, 2)}\n`;
+        const tmp = `${this.#path}.tmp`;
+        await this.#fs.writeFile(tmp, body);
+        await this.#fs.rename(tmp, this.#path);
+    }
+    /** Accrue one unchanged-code replay outcome for a flow and persist. */
+    async record(flow, passed) {
+        const ledger = await this.load();
+        ledger[flow] = recordOutcome(ledger[flow] ?? emptyRecord(), passed);
+        await this.save(ledger);
+    }
+    /** The flows currently quarantined as flaky — what the gate excludes from blocking. */
+    async flakyFlows() {
+        const ledger = await this.load();
+        return Object.entries(ledger)
+            .filter(([, record]) => isFlaky(record))
+            .map(([flow]) => flow);
+    }
+}

package/dist/language/flows/suite/server-verify.d.ts

@@ -0,0 +1,15 @@
+/**
+ * verify:server delegation. When a project's cloud config sets `verify: 'server'`, the FLOW_VERIFY tool
+ * runs the suite on the hosted runner (POST /v1/verifications) instead of replaying in the local browser,
+ * and maps the server's report back into the SAME SuiteVerdict the local path returns — so the agent's
+ * contract is identical either way. Falls back to local (returns null) when not attached, wrong mode, or
+ * there is no reachable preview URL for the server to hit.
+ */
+import type { SuiteVerdict } from '@reticlehq/core';
+import type { ToolDeps } from '../../../surface/tools/tool-kit.js';
+import { type ProjectCloud } from '../../../memory/cloud/cloud-config.js';
+import { type ServerVerification } from '../../../memory/cloud/cloud-sync.js';
+/** Map the hosted runner's report onto the local suite-verdict shape (status/total/passed/failed/failures). */
+export declare function toSuiteVerdict(report: ServerVerification): SuiteVerdict;
+/** Run the suite on the hosted runner, or null to signal the caller should replay locally. */
+export declare function runServerVerify(deps: ToolDeps, cloud: ProjectCloud, sessionId: string | undefined, flows: string[]): Promise<SuiteVerdict | null>;