@reticlehq/server 2.2.1 → 2.4.0

package/dist/events/stale-response.d.ts

@@ -0,0 +1,4 @@
+import { type ReticleEvent } from '@reticlehq/core';
+import type { Contradiction } from './contradictions.js';
+/** The one contradiction, or none. Reported once per window — a race is a fact about the window. */
+export declare function findStaleResponses(events: readonly ReticleEvent[]): Contradiction[];

package/dist/events/stale-response.js

@@ -0,0 +1,139 @@
+import { ContradictionKind, EventType } from '@reticlehq/core';
+function pathOf(url) {
+    const q = url.indexOf('?');
+    return q === -1 ? url : url.slice(0, q);
+}
+function queryOf(url) {
+    const q = url.indexOf('?');
+    return q === -1 ? '' : url.slice(q + 1);
+}
+/**
+ * Parameters that ENUMERATE a collection rather than select within it.
+ *
+ * Two overlapping reads that differ only in these are a fan-out, not a race: an app fetching page 0
+ * and page 5 in parallel wants both, and whichever lands last is not overwriting the other. Measured
+ * against a synthetic dashboard doing parallel pagination — every run reported a race, because the
+ * requests do overlap and do settle out of order, and the original rule looked no further than that.
+ *
+ * A filter race differs in a SELECTING parameter (`status`, `q`, a date range): the second request
+ * makes the first obsolete, both answer into the same view, and the slower one wins.
+ */
+const ENUMERATING_PARAMS = new Set([
+    'page',
+    'offset',
+    'cursor',
+    'limit',
+    'size',
+    'per_page',
+    'perPage',
+    'pageSize',
+    'after',
+    'before',
+    'start',
+    'end',
+]);
+/** Whether the two queries differ ONLY in how much of the same collection they ask for. */
+function differsOnlyByEnumeration(first, second) {
+    const a = new URLSearchParams(first);
+    const b = new URLSearchParams(second);
+    const keys = new Set([...a.keys(), ...b.keys()]);
+    let differed = false;
+    for (const key of keys) {
+        if (a.get(key) === b.get(key))
+            continue;
+        if (!ENUMERATING_PARAMS.has(key))
+            return false;
+        differed = true;
+    }
+    return differed;
+}
+/** Pair NET_PENDING with its NET_REQUEST by the id both carry. Unpaired events are still in flight. */
+function flights(events) {
+    const issued = new Map();
+    const out = [];
+    for (const event of events) {
+        const id = typeof event.data['id'] === 'string' ? event.data['id'] : undefined;
+        if (id === undefined)
+            continue;
+        const at = typeof event.t === 'number' ? event.t : 0;
+        if (event.type === EventType.NET_PENDING) {
+            const url = typeof event.data['url'] === 'string' ? event.data['url'] : '';
+            const method = typeof event.data['method'] === 'string' ? event.data['method'] : 'GET';
+            issued.set(id, { url, method, at });
+            continue;
+        }
+        if (event.type !== EventType.NET_REQUEST)
+            continue;
+        const start = issued.get(id);
+        if (start === undefined)
+            continue; // started before this window — its ordering is unknowable
+        out.push({
+            id,
+            url: start.url,
+            method: start.method.toUpperCase(),
+            issuedAt: start.at,
+            settledAt: at,
+        });
+    }
+    return out;
+}
+/**
+ * Most recent flights compared per endpoint.
+ *
+ * The comparison is pairwise, so an unbounded window is quadratic: measured at 548ms for 2000
+ * concurrent reads of one endpoint, paid on EVERY verdict. A verdict that costs half a second is a
+ * verdict agents stop asking for. Racing requests are adjacent in time by definition, so the most
+ * recent flights are where a race can be; older ones cannot overlap them anyway.
+ *
+ * Bounded rather than silent: this is a detection ceiling, not a truncation of reported data — a race
+ * among more than this many simultaneous reads of ONE endpoint goes unreported, and that is a
+ * deliberate trade for a hot path that runs on every assert.
+ */
+const MAX_FLIGHTS_PER_PATH = 60;
+/** The one contradiction, or none. Reported once per window — a race is a fact about the window. */
+export function findStaleResponses(events) {
+    // Grouped by path first: two reads of DIFFERENT endpoints can never race, and comparing them was
+    // the bulk of the work on any real page, which talks to many endpoints at once.
+    const byPath = new Map();
+    for (const flight of flights(events)) {
+        if (flight.method !== 'GET')
+            continue;
+        const path = pathOf(flight.url);
+        const group = byPath.get(path) ?? [];
+        group.push(flight);
+        byPath.set(path, group);
+    }
+    for (const group of byPath.values()) {
+        const reads = group.slice(-MAX_FLIGHTS_PER_PATH);
+        const found = raceIn(reads);
+        if (found !== undefined)
+            return [found];
+    }
+    return [];
+}
+function raceIn(reads) {
+    for (const first of reads) {
+        for (const second of reads) {
+            if (first.id === second.id)
+                continue;
+            if (second.issuedAt <= first.issuedAt)
+                continue; // `first` must be the earlier request
+            if (second.issuedAt >= first.settledAt)
+                continue; // sequential, not overlapping
+            if (second.settledAt >= first.settledAt)
+                continue; // settled in order — no race
+            if (queryOf(first.url) === queryOf(second.url))
+                continue; // a retry, not a superseding query
+            // Parallel pagination is not a race — see differsOnlyByEnumeration.
+            if (differsOnlyByEnumeration(queryOf(first.url), queryOf(second.url)))
+                continue;
+            return {
+                kind: ContradictionKind.STALE_RESPONSE_APPLIED,
+                claim: `both reads of ${pathOf(first.url)} returned successfully and the page settled`,
+                counter: `the SUPERSEDED request (${queryOf(first.url)}) settled ${String(Math.max(0, first.settledAt - second.settledAt))}ms AFTER the one that replaced it (${queryOf(second.url)}), so the screen is showing the older query's data`,
+                detail: 'a filter/search race: the newer request was issued while the older was still in flight, and the older answered last, so whichever query the server happens to be slower at wins — unless the app cancels superseded requests or drops responses that no longer match current state',
+            };
+        }
+    }
+    return undefined;
+}

package/dist/events/unit-mismatch.d.ts

@@ -0,0 +1,16 @@
+import { type ReticleEvent } from '@reticlehq/core';
+import type { Contradiction } from './contradictions.js';
+/**
+ * @param prior events from BEFORE the window, used only to learn what the API has stated.
+ *
+ * The scale error is a disagreement with a value the API gave EARLIER — by definition before the
+ * action that sends it back. `reticle_assert` scopes its window to the last act's cursor, so the
+ * stating response falls outside it and `known` is empty exactly when it matters. Measured live on
+ * the payments panel: `reticle_observe` over a wide window reported the mismatch while `assert` on
+ * the same session reported none — the verdict tool, the one an agent gates on, was the blind one.
+ *
+ * Prior events TEACH, they are never themselves findings: widening the window instead would make
+ * every other rule blame this action for events it did not cause, and would re-report every earlier
+ * mistake on every assert.
+ */
+export declare function findUnitMismatches(events: readonly ReticleEvent[], prior?: readonly ReticleEvent[]): Contradiction[];

package/dist/events/unit-mismatch.js

@@ -0,0 +1,167 @@
+import { ContradictionKind, EventType } from '@reticlehq/core';
+/**
+ * The app sent a money value back in a DIFFERENT unit than the API gave it.
+ *
+ * Payment APIs overwhelmingly speak minor units — Stripe, Razorpay, Adyen, PayPal all state amounts
+ * in paise/cents as integers. A UI renders that as a major-unit string, and the bug is writing the
+ * rendered number back into the field the integer came from.
+ *
+ * Measured on a real payments dashboard: `GET /payments` returns `amount: 118701` for a payment, the
+ * row renders "₹1,187.01", and the refund posts `{"amount": 1187.01}` into the same field. The server
+ * takes 1187 paise and answers `200 {"status": "processed"}`. That is a 100x UNDER-REFUND, and every
+ * channel agrees it worked: the status is 200, the payload says processed, the UI advances, the page
+ * settles, and the number in the request is exactly the number on the screen. Nothing disagrees,
+ * because the disagreement is with a value the API returned EARLIER in the session.
+ *
+ * Which is the point: this is only visible to something holding the whole request timeline with
+ * bodies. A snapshot cannot see it, a status column cannot see it, and a human reading the request
+ * sees the amount they expected.
+ *
+ * Not a heuristic about decimals. Firing on "an amount had a fractional part" would accuse every API
+ * that legitimately uses major units. This fires only when the SAME field of the SAME entity was
+ * observed at a different scale — a comparison, not a guess.
+ */
+/** Fields worth comparing. Deliberately short: money, not every number an app sends. */
+const MONEY_FIELDS = new Set(['amount', 'value', 'price', 'total', 'fee', 'cost', 'balance']);
+/**
+ * Scales that indicate a minor/major confusion. 100 covers two-decimal currencies; 1000 covers the
+ * three-decimal ones (KWD, BHD, JOD, TND).
+ */
+const SCALES = [100, 1000];
+/**
+ * Prefixed ids (`pay_NkT10001`) and uuids, matched anywhere in a URL or a string field.
+ *
+ * Numeric ids are handled separately by path segment: `/api/orders/9/capture` is at least as common
+ * as a prefixed id, and a bare `9` cannot be pattern-matched out of arbitrary text without matching
+ * every other number too.
+ */
+const ID_PATTERN = /[A-Za-z]{2,}_[A-Za-z0-9]{2,}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}/g;
+function parse(raw) {
+    if (typeof raw !== 'string' || raw.length === 0)
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Every (id, field, value) triple in a payload, from objects that carry an id of their own. */
+function moneyByEntity(node, into) {
+    if (Array.isArray(node)) {
+        for (const item of node)
+            moneyByEntity(item, into);
+        return;
+    }
+    if (typeof node !== 'object' || node === null)
+        return;
+    const record = node;
+    // An id may arrive as a number (`{"id": 9}`) — normalised so a numeric path segment matches it.
+    const raw = record['id'];
+    const id = typeof raw === 'string' ? raw : typeof raw === 'number' ? String(raw) : undefined;
+    if (id !== undefined) {
+        for (const [key, value] of Object.entries(record)) {
+            if (!MONEY_FIELDS.has(key) || typeof value !== 'number')
+                continue;
+            const fields = into.get(id) ?? new Map();
+            fields.set(key, value);
+            into.set(id, fields);
+        }
+    }
+    for (const value of Object.values(record))
+        moneyByEntity(value, into);
+}
+/** Ids named anywhere in a URL or a request payload — how a write says which entity it targets. */
+function idsIn(url, body) {
+    const found = new Set(url.match(ID_PATTERN) ?? []);
+    // Numeric path segments: `/api/orders/9/capture` names entity 9.
+    for (const segment of url.split('?')[0]?.split('/') ?? []) {
+        if (segment.length > 0 && /^\d+$/.test(segment))
+            found.add(segment);
+    }
+    if (typeof body === 'object' && body !== null) {
+        for (const value of Object.values(body)) {
+            if (typeof value === 'string')
+                for (const id of value.match(ID_PATTERN) ?? [])
+                    found.add(id);
+        }
+    }
+    return Array.from(found);
+}
+/** The scale between a known value and a sent one, or undefined when they are consistent. */
+function scaleBetween(known, sent) {
+    if (sent === 0 || known === 0)
+        return undefined;
+    for (const scale of SCALES) {
+        // A tolerance, because the major-unit form is a rounded render of the minor one.
+        if (Math.abs(known - sent * scale) <= scale / 2)
+            return scale;
+    }
+    return undefined;
+}
+/**
+ * @param prior events from BEFORE the window, used only to learn what the API has stated.
+ *
+ * The scale error is a disagreement with a value the API gave EARLIER — by definition before the
+ * action that sends it back. `reticle_assert` scopes its window to the last act's cursor, so the
+ * stating response falls outside it and `known` is empty exactly when it matters. Measured live on
+ * the payments panel: `reticle_observe` over a wide window reported the mismatch while `assert` on
+ * the same session reported none — the verdict tool, the one an agent gates on, was the blind one.
+ *
+ * Prior events TEACH, they are never themselves findings: widening the window instead would make
+ * every other rule blame this action for events it did not cause, and would re-report every earlier
+ * mistake on every assert.
+ */
+export function findUnitMismatches(events, prior = []) {
+    // What the API has told us about each entity so far, in the API's own units.
+    const known = new Map();
+    for (const event of prior) {
+        if (event.type !== EventType.NET_REQUEST)
+            continue;
+        const body = parse(event.data['responseBody']);
+        if (body !== undefined)
+            moneyByEntity(body, known);
+    }
+    const found = [];
+    const seen = new Set();
+    for (const event of events) {
+        if (event.type !== EventType.NET_REQUEST)
+            continue;
+        const url = typeof event.data['url'] === 'string' ? event.data['url'] : '';
+        const requestBody = parse(event.data['requestBody']);
+        // Compare BEFORE recording this call's own response, or a request that echoes its own reply
+        // would compare against itself.
+        if (typeof requestBody === 'object' && requestBody !== null) {
+            const sentFields = requestBody;
+            for (const id of idsIn(url, requestBody)) {
+                const fields = known.get(id);
+                if (fields === undefined)
+                    continue;
+                for (const [key, sent] of Object.entries(sentFields)) {
+                    if (!MONEY_FIELDS.has(key) || typeof sent !== 'number')
+                        continue;
+                    const priorValue = fields.get(key);
+                    if (priorValue === undefined)
+                        continue;
+                    const scale = scaleBetween(priorValue, sent);
+                    if (scale === undefined)
+                        continue;
+                    const key2 = `${id}:${key}`;
+                    if (seen.has(key2))
+                        continue;
+                    seen.add(key2);
+                    found.push({
+                        kind: ContradictionKind.UNIT_MISMATCH,
+                        claim: `the request sent ${key}=${String(sent)} and the server accepted it`,
+                        counter: `the API reports ${key}=${String(priorValue)} for ${id} — the value sent is ${String(scale)}x SMALLER, i.e. a major-unit number written into a minor-unit field`,
+                        detail: `${url} — at this scale the operation moves ${String(sent)} minor units instead of ${String(priorValue)}; nothing else can see this, because the number sent is exactly the number rendered on screen`,
+                    });
+                }
+            }
+        }
+        const responseBody = parse(event.data['responseBody']);
+        if (responseBody !== undefined)
+            moneyByEntity(responseBody, known);
+    }
+    return found;
+}

package/dist/flows/affected-tools.d.ts

@@ -0,0 +1,18 @@
+import type { ToolDef } from '../tools/tools.js';
+/**
+ * `reticle_affected` — which saved flows must re-verify for a set of changed files.
+ *
+ * This logic already existed as `reticle affected`, deliberately kept off the MCP surface because an
+ * advertised tool costs tokens on every turn whether or not it is used. That reasoning is right, and
+ * this does not change it: the tool is NOT advertised by any profile. It is reachable through
+ * `reticle_run`, so it costs nothing per turn and is still discoverable via `reticle_tools`.
+ *
+ * What the reasoning missed is who holds the question. The AGENT is the one that just edited files
+ * and has to decide what to re-check; a shell command it may not be able to run is not an answer for
+ * an MCP client that has no shell. Leaving it CLI-only meant the party with the diff could not ask
+ * the party with the index.
+ *
+ * Unknown-provenance flows are returned as affected (fail-safe) AND listed separately, so "re-verify
+ * this" is never confused with "this definitely touches your change".
+ */
+export declare const AFFECTED_TOOLS: ToolDef[];

package/dist/flows/affected-tools.js

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+import { ReticleTool } from '../tools/tool-names.js';
+import { loadNamedFlows, resolveChangedFiles } from '../cli-flow-commands.js';
+import { affectedSavedFlows } from './flow-sources.js';
+/**
+ * `reticle_affected` — which saved flows must re-verify for a set of changed files.
+ *
+ * This logic already existed as `reticle affected`, deliberately kept off the MCP surface because an
+ * advertised tool costs tokens on every turn whether or not it is used. That reasoning is right, and
+ * this does not change it: the tool is NOT advertised by any profile. It is reachable through
+ * `reticle_run`, so it costs nothing per turn and is still discoverable via `reticle_tools`.
+ *
+ * What the reasoning missed is who holds the question. The AGENT is the one that just edited files
+ * and has to decide what to re-check; a shell command it may not be able to run is not an answer for
+ * an MCP client that has no shell. Leaving it CLI-only meant the party with the diff could not ask
+ * the party with the index.
+ *
+ * Unknown-provenance flows are returned as affected (fail-safe) AND listed separately, so "re-verify
+ * this" is never confused with "this definitely touches your change".
+ */
+export const AFFECTED_TOOLS = [
+    {
+        name: ReticleTool.AFFECTED,
+        description: 'Which saved flows must re-verify for a set of changed files. Pass the files you edited (and/or `since` for a git ref to diff against). Returns { changedFiles, affected, unknownProvenance } — `affected` is what to re-run, and `unknownProvenance` are flows included only because Reticle cannot tell which sources they cover, so they are re-verified by default rather than silently skipped.',
+        example: { files: ['src/App.tsx'] },
+        inputSchema: {
+            files: z
+                .array(z.string())
+                .optional()
+                .describe('Changed file paths, repo-relative (e.g. ["src/App.tsx"]).'),
+            since: z
+                .string()
+                .optional()
+                .describe('Git ref to diff against (e.g. "HEAD~1", "main"). Unioned with `files`.'),
+        },
+        outputSchema: {
+            changedFiles: z.array(z.string()),
+            affected: z.array(z.string()),
+            unknownProvenance: z.array(z.string()),
+        },
+        handler: async (deps, args) => {
+            const files = Array.isArray(args['files'])
+                ? args['files'].filter((f) => typeof f === 'string')
+                : [];
+            const since = typeof args['since'] === 'string' ? args['since'] : undefined;
+            const changedFiles = await resolveChangedFiles(files, since);
+            const flows = await loadNamedFlows(deps.fs, deps.reticleRoot);
+            const result = affectedSavedFlows(flows, changedFiles);
+            return { changedFiles, ...result };
+        },
+    },
+];

package/dist/flows/affected.d.ts

@@ -22,4 +22,3 @@ export interface AffectedResult {
  * a repo-relative change matches an absolute stamp and vice-versa.
  */
 export declare function affectedFlows(flows: readonly FlowSources[], changedFiles: readonly string[]): AffectedResult;
-//# sourceMappingURL=affected.d.ts.map

package/dist/flows/affected.js

@@ -33,4 +33,3 @@ export function affectedFlows(flows, changedFiles) {
     }
     return { affected, unknownProvenance };
 }
-//# sourceMappingURL=affected.js.map

package/dist/flows/annotate-tools.d.ts

@@ -13,4 +13,3 @@ import type { ToolDef } from '../tools/tools.js';
  * agent that annotates at the wrong moment gets a clear error rather than a crash.
  */
 export declare const ANNOTATE_TOOLS: ToolDef[];
-//# sourceMappingURL=annotate-tools.d.ts.map

package/dist/flows/annotate-tools.js

@@ -1,5 +1,14 @@
 import { z } from 'zod';
 import { AnnotationErrorCode, AnnotationSchema } from '@reticlehq/core';
+import { RECOVERY } from '../tools/error-recovery.js';
+/**
+ * An unknown kind is almost always a free-text annotation, which this tool deliberately refuses to
+ * guess into a predicate. Naming the six kinds turns a dead end into one retry.
+ */
+const UNKNOWN_KIND_RECOVERY = 'Annotations are structured, never free text. Pass one of: ' +
+    '{ kind: "assert-signal", name }, { kind: "assert-visible", testid }, ' +
+    '{ kind: "assert-state", statePath }, { kind: "mark-dynamic", testid }, ' +
+    '{ kind: "success-state", signal|testid }, or { kind: "intent", text }.';
 import { ReticleTool } from '../tools/tool-names.js';
 import { asString } from '../tools/tools-helpers.js';
 import { compileAnnotation } from './annotate.js';
@@ -20,6 +29,7 @@ const DEFAULT_RECORDING = 'default';
 export const ANNOTATE_TOOLS = [
     {
         name: ReticleTool.ANNOTATE,
+        example: { kind: 'assert-signal', name: 'todos:loaded' },
         description: 'Attach a STRUCTURED annotation to the active recording, compiling it into the flow. kind: ' +
             'assert-signal { name, dataMatches? } → the last step asserts that signal; assert-visible ' +
             '{ testid } → the last step asserts that element is present; assert-state ' +
@@ -98,6 +108,7 @@ export const ANNOTATE_TOOLS = [
         },
         outputSchema: {
             ok: z.boolean(),
+            recovery: z.string().optional(),
             target: z.string().optional(),
             compiled: z.string().optional(),
             code: z.string().optional(),
@@ -107,12 +118,20 @@ export const ANNOTATE_TOOLS = [
             // Structured boundary: a free NL string / unknown kind fails the schema → UNKNOWN_KIND.
             const parsed = AnnotationSchema.safeParse(args);
             if (!parsed.success) {
-                return Promise.resolve({ ok: false, code: AnnotationErrorCode.UNKNOWN_KIND });
+                return Promise.resolve({
+                    ok: false,
+                    code: AnnotationErrorCode.UNKNOWN_KIND,
+                    recovery: UNKNOWN_KIND_RECOVERY,
+                });
             }
             const stepCount = deps.recordings.stepCount(name);
             const compiled = deps.recordings.getCompiled(name) !== undefined;
             if (stepCount === undefined && !compiled) {
-                return Promise.resolve({ ok: false, code: AnnotationErrorCode.NO_ACTIVE_RECORDING });
+                return Promise.resolve({
+                    ok: false,
+                    code: AnnotationErrorCode.NO_ACTIVE_RECORDING,
+                    recovery: RECOVERY.MISSING_RECORDING,
+                });
             }
             const outcome = compileAnnotation(parsed.data, stepCount ?? 0);
             if (!outcome.result.ok)
@@ -133,4 +152,3 @@ export const ANNOTATE_TOOLS = [
         },
     },
 ];
-//# sourceMappingURL=annotate-tools.js.map

package/dist/flows/annotate.d.ts

@@ -19,4 +19,3 @@ export declare function compileAnnotation(a: Annotation, stepCount: number): Ann
  * e.g. `will assert signal diff:shown`. The leading word is the named COMPILED_PREDICATE_PREFIX.
  */
 export declare function describeCompiled(a: Annotation): string;
-//# sourceMappingURL=annotate.d.ts.map

package/dist/flows/annotate.js

@@ -131,4 +131,3 @@ export function describeCompiled(a) {
             return `${COMPILED_PREDICATE_PREFIX} intent: ${a.text}`;
     }
 }
-//# sourceMappingURL=annotate.js.map

package/dist/flows/annotation-store.d.ts

@@ -20,4 +20,3 @@ export declare class AnnotationStore {
     /** Drop a recording's annotations (called after reticle_flow_save folds them onto disk). */
     clear(name: string): void;
 }
-//# sourceMappingURL=annotation-store.d.ts.map

package/dist/flows/annotation-store.js

@@ -48,4 +48,3 @@ export class AnnotationStore {
         this.#byName.delete(name);
     }
 }
-//# sourceMappingURL=annotation-store.js.map

package/dist/flows/assertion-integrity.d.ts

@@ -21,4 +21,3 @@ export interface DowngradeFinding {
  * lives with the affected index.
  */
 export declare function detectDowngrades(before: readonly StepExpect[], after: readonly StepExpect[]): DowngradeFinding[];
-//# sourceMappingURL=assertion-integrity.d.ts.map

package/dist/flows/assertion-integrity.js

@@ -24,4 +24,3 @@ export function detectDowngrades(before, after) {
     }
     return findings;
 }
-//# sourceMappingURL=assertion-integrity.js.map

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

@@ -77,4 +77,3 @@ export declare class AssertionTiersStore {
     /** 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>;
 }
-//# sourceMappingURL=assertion-tiers-store.d.ts.map

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

@@ -96,4 +96,3 @@ export class AssertionTiersStore {
         }
     }
 }
-//# sourceMappingURL=assertion-tiers-store.js.map

package/dist/flows/buddy-status.d.ts

@@ -22,4 +22,3 @@ export interface BuddyStatusInput {
  * `✗ 2 deviations: checkout, billing · 39 nominal · 1 flaky quarantined`
  */
 export declare function formatBuddyStatus(input: BuddyStatusInput): string;
-//# sourceMappingURL=buddy-status.d.ts.map

package/dist/flows/buddy-status.js

@@ -30,4 +30,3 @@ export function formatBuddyStatus(input) {
     }
     return parts.join(' · ');
 }
-//# sourceMappingURL=buddy-status.js.map

package/dist/flows/coverage.d.ts

@@ -25,4 +25,3 @@ export interface Coverage {
     overallPct: number;
 }
 export declare function computeCoverage(declared: DeclaredSurface, exercised: DeclaredSurface): Coverage;
-//# sourceMappingURL=coverage.d.ts.map

package/dist/flows/coverage.js

@@ -19,4 +19,3 @@ export function computeCoverage(declared, exercised) {
     const overallPct = total === 0 ? 100 : Math.round((covered / total) * 100);
     return { testids, signals, flows, overallPct };
 }
-//# sourceMappingURL=coverage.js.map

package/dist/flows/decision.d.ts

@@ -1,13 +1,6 @@
 import { type FlowFile, type FlowReplayResult, type ReplayDecision, type SuiteVerdict } from '@reticlehq/core';
 export declare function buildDecision(result: FlowReplayResult, flow?: FlowFile): ReplayDecision;
-/**
- * Aggregate per-flow replays into one suite verdict — the autonomous loop's consolidated answer
- * after a build: did anything break, and what's the prioritized fix list. Pure: pass the already
- * decision-annotated replay results + their flows. Passing flows are counted; only failures carry
- * detail (token-cheap), each with the actionable decision so the agent fixes without re-querying.
- */
 export declare function buildSuiteVerdict(runs: ReadonlyArray<{
     replay: FlowReplayResult;
     flow?: FlowFile;
 }>): SuiteVerdict;
-//# sourceMappingURL=decision.d.ts.map

package/dist/flows/decision.js

@@ -1,5 +1,5 @@
 import { AnchorKind, ReplayStatus, } from '@reticlehq/core';
-import { classifyFlowAssertions } from './flow-classify.js';
+import { classifyFlowAssertions, FlowAssertionGrade } from './flow-classify.js';
 import { SUCCESS_STEP_TOOL } from './flow-success.js';
 /**
  * Turn a replay result into the autonomy DECISION envelope — the judgement a human reviewer used to
@@ -92,12 +92,39 @@ function suiteVerdictOf(status) {
  * decision-annotated replay results + their flows. Passing flows are counted; only failures carry
  * detail (token-cheap), each with the actionable decision so the agent fixes without re-querying.
  */
+/**
+ * Why a green replay still verified nothing, or undefined when it genuinely did.
+ *
+ * A flow with no steps, or one that asserts no observable consequence, replays green no matter what
+ * the app does — the grader already knows this at save time and says so. Counting it as `passed`
+ * turned that warning into "all 1 flow pass", which is a false green in the exact feature sold as
+ * the regression suite. Classified only when the flow file is available; never guessed.
+ */
+function unverifiableReason(flow) {
+    if (flow === undefined)
+        return undefined;
+    if (flow.steps.length === 0) {
+        return 'the flow has no steps — it replays green whatever the app does. Record it again, or add steps with reticle_annotate.';
+    }
+    const c = classifyFlowAssertions(flow);
+    if (c.grade !== FlowAssertionGrade.ASSERTION_FREE)
+        return undefined;
+    return (c.warning ??
+        'the flow asserts no observable consequence, so it passes even when the feature is broken.');
+}
 export function buildSuiteVerdict(runs) {
     const failures = [];
+    const unverifiable = [];
     let passed = 0;
     for (const { replay, flow } of runs) {
         if (replay.status === ReplayStatus.OK) {
-            passed += 1;
+            const reason = unverifiableReason(flow);
+            // A green that cannot go red is not a pass. Counted apart, so `passed` stays a count of things
+            // actually verified rather than of replays that merely completed.
+            if (reason !== undefined)
+                unverifiable.push({ flow: replay.name, reason });
+            else
+                passed += 1;
             continue;
         }
         const decision = replay.decision ?? buildDecision(replay, flow);
@@ -111,10 +138,23 @@ export function buildSuiteVerdict(runs) {
     }
     const total = runs.length;
     const failed = failures.length;
-    const status = failed === 0 ? 'pass' : 'fail';
+    // A real failure outranks an unverifiable flow: a broken flow is worse news than an empty one.
+    const status = failed > 0 ? 'fail' : unverifiable.length > 0 ? 'unverifiable' : 'pass';
+    const cannotFail = unverifiable.length === 0
+        ? ''
+        : ` — ${String(unverifiable.length)} verified nothing (${unverifiable.map((u) => u.flow).join(', ')})`;
     const summary = failed === 0
-        ? `all ${total} flow${total === 1 ? '' : 's'} pass`
-        : `${passed}/${total} flows pass — ${failed} need attention: ${failures.map((f) => f.flow).join(', ')}`;
-    return { status, total, passed, failed, summary, failures };
+        ? unverifiable.length === 0
+            ? `all ${total} flow${total === 1 ? '' : 's'} pass`
+            : `${String(passed)}/${String(total)} flows verified${cannotFail}`
+        : `${passed}/${total} flows pass — ${failed} need attention: ${failures.map((f) => f.flow).join(', ')}${cannotFail}`;
+    return {
+        status,
+        total,
+        passed,
+        failed,
+        summary,
+        failures,
+        ...(unverifiable.length > 0 ? { unverifiable } : {}),
+    };
 }
-//# sourceMappingURL=decision.js.map

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

@@ -17,4 +17,3 @@ export declare class FlakeStore {
     /** The flows currently quarantined as flaky — what the gate excludes from blocking. */
     flakyFlows(): Promise<string[]>;
 }
-//# sourceMappingURL=flake-store.d.ts.map