@reticlehq/server 2.4.0 → 2.5.0

package/dist/flows/heal-run.js

@@ -12,7 +12,7 @@ import { replayFlow } from './flow-replay.js';
 import { applyHealChanges, collectProposals } from './heal.js';
 import { assertSuccess, dynamicTestids, successLabel } from './flow-success.js';
 import { flowErrorMessage, sessionProjectId } from './flow-replay-run.js';
-export const HEAL_MESSAGES = {
+const HEAL_MESSAGES = {
     NOTHING: 'nothing to heal — every anchor resolved on replay',
     HEALED: "rewrote drifted testid anchors to their nearest surviving match and re-verified the flow's success consequence still fires",
     DRIFT_DRY: 'confident rebind(s) proposed — re-run with apply:true to write them to disk',
@@ -25,7 +25,7 @@ function toChange(proposal) {
 }
 export async function healFlow(deps, args) {
     const name = asString(args['flowName']) ?? '';
-    const apply = args['apply'] === true;
+    const apply = true === args['apply'];
     const projectId = sessionProjectId(deps, asString(args['sessionId']));
     const loaded = await deps.flows.load(name, projectId);
     if (!loaded.ok) {
@@ -40,7 +40,7 @@ export async function healFlow(deps, args) {
         };
     }
     const session = deps.sessions.resolve(asString(args['sessionId']));
-    const steps = await replayFlow(session, loaded.value, waitForPredicate, FLOW_SIGNAL_TIMEOUT_MS, args['confirmDangerous'] === true);
+    const steps = await replayFlow(session, loaded.value, waitForPredicate, FLOW_SIGNAL_TIMEOUT_MS, true === args['confirmDangerous']);
     const drifted = steps.some((s) => s.drift !== undefined);
     const failed = steps.find((s) => !s.ok && s.drift === undefined);
     if (failed !== undefined) {
@@ -66,7 +66,7 @@ export async function healFlow(deps, args) {
         };
     }
     const proposals = collectProposals(steps);
-    if (proposals.length === 0) {
+    if (0 === proposals.length) {
         return {
             name,
             status: HealStatus.UNHEALABLE,
@@ -97,7 +97,7 @@ export async function healFlow(deps, args) {
         // Floor the success oracle at the start of the VERIFY replay so the earlier drift replay's signal
         // cannot fake the verification.
         const verifyFloor = session.elapsed();
-        const verifySteps = await replayFlow(session, toVerify, waitForPredicate, FLOW_SIGNAL_TIMEOUT_MS, args['confirmDangerous'] === true);
+        const verifySteps = await replayFlow(session, toVerify, waitForPredicate, FLOW_SIGNAL_TIMEOUT_MS, true === args['confirmDangerous']);
         const verifyClean = verifySteps.length > 0 && verifySteps.every((s) => s.ok && s.drift === undefined);
         const verdict = verifyClean
             ? await assertSuccess(session, healed.success, dynamicTestids(healed), waitForPredicate, FLOW_SIGNAL_TIMEOUT_MS, verifyFloor)

package/dist/flows/heal.js

@@ -23,7 +23,7 @@ export function confidenceFor(from, to) {
     if (from === to)
         return 1;
     const span = Math.max(from.length, to.length);
-    if (span === 0)
+    if (0 === span)
         return 1;
     const raw = 1 - editDistance(from, to) / span;
     if (raw >= 1)
@@ -62,10 +62,10 @@ function proposeRebindWith(drift, step, minConfidence) {
     // Never auto-heal an ambiguous drift: when two present testids tie at the minimum distance, the
     // `nearest` pick is arbitrary, so a rebind would be a coin-flip that can land on the wrong element
     // and ship a bug green. Surface it (the drift still carries `nearest`) and defer to a human.
-    if (drift.ambiguous === true)
+    if (true === drift.ambiguous)
         return undefined;
     const to = drift.nearest;
-    if (to === null)
+    if (null === to)
         return undefined;
     const confidence = confidenceFor(drift.anchor, to);
     if (confidence < minConfidence)

package/dist/flows/predicate-to-expect.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The assertion the agent MADE, in the shape a saved flow can keep.
+ *
+ * `reticle_act_and_wait { until }` is how agents assert — 12 of 14 calls in a day of telemetry
+ * carried an `until`. `compileActStep` recorded only the ACTION, so a flow saved after an asserted
+ * drive came back graded `assertion-free`: "performs actions but asserts no observable consequence —
+ * it will pass even if the feature is broken." The agent had already said what success meant;
+ * Reticle discarded it and then warned the agent that the flow asserts nothing.
+ *
+ * That is the regression-suite story failing at its last step. "Record once, verify forever" is only
+ * worth anything if the recorded flow can go RED, and locally 32 of 39 saved flows cannot.
+ *
+ * The inverse of `successToPredicate`. Only the kinds FlowExpect can express are carried: `settled`
+ * is a wait rather than a claim, and `route`/`animation`/`anyOf`/`not` have no representation at all.
+ * Inventing one would write an assertion into the file that the agent never made, which is worse
+ * than recording none — a flow that asserts something nobody chose is a false green with extra steps.
+ */
+import type { FlowExpect } from '@reticlehq/core';
+import type { Predicate } from '../events/predicate.js';
+export declare function predicateToExpect(predicate: Predicate): FlowExpect | undefined;
+/**
+ * The subset a REPLAY actually enforces today.
+ *
+ * `flow-replay` checks exactly two things per step: `expect.element.testid` is present after the
+ * action, and `expect.state` holds. A recorded `net` or `signal` expect is graded as a consequence
+ * assertion by `classifyFlowAssertions` and then never evaluated — so writing one into a flow file
+ * would make it report `grade: "asserted"` while nothing checks it.
+ *
+ * That is a false green, in the feature whose entire purpose is preventing them, produced by the
+ * change that was meant to strengthen it. So only the enforced kinds are recorded: a flow that says
+ * it asserts something must actually go red when that thing breaks.
+ *
+ * Lifting this is worth doing — net and signal are the assertions agents most often make, and the
+ * conversion above already handles them — but it requires replay to evaluate them per step (the
+ * machinery exists: successToPredicate + the predicate engine). Until then, recording them would
+ * trade a weak flow for a lying one.
+ */
+export declare function enforcedOnReplay(expect: FlowExpect | undefined): FlowExpect | undefined;

package/dist/flows/predicate-to-expect.js

@@ -0,0 +1,95 @@
+import { PredicateKind } from '@reticlehq/core';
+/** Merge two partial expectations; later keys win only where the earlier one said nothing. */
+function merge(into, from) {
+    return { ...from, ...into };
+}
+export function predicateToExpect(predicate) {
+    switch (predicate.kind) {
+        case PredicateKind.SIGNAL: {
+            if (predicate.name === undefined)
+                return undefined;
+            return predicate.dataMatches === undefined
+                ? { signal: predicate.name }
+                : { signal: predicate.name, signalData: predicate.dataMatches };
+        }
+        case PredicateKind.NET: {
+            const net = {};
+            if (predicate.method !== undefined)
+                net.method = predicate.method;
+            if (predicate.urlContains !== undefined)
+                net.urlContains = predicate.urlContains;
+            if (predicate.status !== undefined)
+                net.status = predicate.status;
+            if (predicate.count !== undefined)
+                net.count = predicate.count;
+            return 0 === Object.keys(net).length ? undefined : { net };
+        }
+        case PredicateKind.CONSOLE: {
+            const console_ = {};
+            if (predicate.level !== undefined)
+                console_.level = predicate.level;
+            if (predicate.absent !== undefined)
+                console_.absent = predicate.absent;
+            return 0 === Object.keys(console_).length ? undefined : { console: console_ };
+        }
+        case PredicateKind.ELEMENT: {
+            const element = {};
+            if (predicate.query.testid !== undefined)
+                element.testid = predicate.query.testid;
+            if (predicate.query.role !== undefined)
+                element.role = predicate.query.role;
+            if (predicate.query.name !== undefined)
+                element.name = predicate.query.name;
+            return 0 === Object.keys(element).length ? undefined : { element };
+        }
+        case PredicateKind.STATE: {
+            const state = { path: predicate.path };
+            if (predicate.store !== undefined)
+                state.store = predicate.store;
+            if (predicate.equals !== undefined)
+                state.equals = predicate.equals;
+            return { state };
+        }
+        case PredicateKind.ALL_OF: {
+            // `settled` members drop out on their own by returning undefined.
+            let combined;
+            for (const part of predicate.predicates) {
+                const expect = predicateToExpect(part);
+                if (expect === undefined)
+                    continue;
+                combined = combined === undefined ? expect : merge(combined, expect);
+            }
+            return combined;
+        }
+        default:
+            // settled | route | animation | anyOf | not — nothing FlowExpect can say honestly.
+            return undefined;
+    }
+}
+/**
+ * The subset a REPLAY actually enforces today.
+ *
+ * `flow-replay` checks exactly two things per step: `expect.element.testid` is present after the
+ * action, and `expect.state` holds. A recorded `net` or `signal` expect is graded as a consequence
+ * assertion by `classifyFlowAssertions` and then never evaluated — so writing one into a flow file
+ * would make it report `grade: "asserted"` while nothing checks it.
+ *
+ * That is a false green, in the feature whose entire purpose is preventing them, produced by the
+ * change that was meant to strengthen it. So only the enforced kinds are recorded: a flow that says
+ * it asserts something must actually go red when that thing breaks.
+ *
+ * Lifting this is worth doing — net and signal are the assertions agents most often make, and the
+ * conversion above already handles them — but it requires replay to evaluate them per step (the
+ * machinery exists: successToPredicate + the predicate engine). Until then, recording them would
+ * trade a weak flow for a lying one.
+ */
+export function enforcedOnReplay(expect) {
+    if (expect === undefined)
+        return undefined;
+    const kept = {};
+    if (expect.element?.testid !== undefined)
+        kept.element = expect.element;
+    if (expect.state !== undefined)
+        kept.state = expect.state;
+    return 0 === Object.keys(kept).length ? undefined : kept;
+}

package/dist/flows/replay.d.ts

@@ -15,6 +15,17 @@ export declare function ambiguousTestidNote(value: string): string;
 export declare function queryRefs(result: CommandResult): string[];
 /** A destructive-action confirmation is one-shot and must never persist into a recording. */
 export declare function replayActionArgs(value: unknown, confirmDangerous?: boolean): Record<string, unknown>;
+/**
+ * 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 declare function captureAct(recordings: {
+    active: () => string[];
+    capture: (step: RecordedStep) => void;
+}, args: Record<string, unknown>, res: unknown): void;
 /**
  * Compile a single reticle_act invocation into a normalized RecordedStep using the action result. Anchor
  * priority mirrors synthesizeAnchor: a data-testid is the gold standard; failing that, the element's
@@ -22,7 +33,11 @@ export declare function replayActionArgs(value: unknown, confirmDangerous?: bool
  * a volatile ref. Only when neither is available is the step ref-bound (in-session only).
  */
 export declare function compileActStep(args: Record<string, unknown>, res: unknown): RecordedStep;
-/** Compile an reticle_act_sequence invocation, normalizing each sub-step to its testid where resolvable. */
+/**
+ * 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 declare function compileSequenceStep(args: Record<string, unknown>, res: unknown): RecordedStep;
 interface ReplayStepResult {
     tool: string;

package/dist/flows/replay.js

@@ -1,5 +1,7 @@
 import { DANGEROUS_ACTION_CONFIRM_ARG, ReticleCommand, QueryBy, } from '@reticlehq/core';
 import { ReticleTool } from '../tools/tool-names.js';
+import { predicateToExpect, enforcedOnReplay } from './predicate-to-expect.js';
+import { PredicateSchema } from '../events/predicate.js';
 import { asString, asRecord } from '../tools/tools-helpers.js';
 /**
  * The note attached when a testid resolves to multiple live elements (the first match is used).
@@ -35,10 +37,38 @@ function sourceFromResult(res) {
     if (typeof source['file'] !== 'string' || typeof source['line'] !== 'number')
         return undefined;
     const out = { file: source['file'], line: source['line'] };
-    if (typeof source['column'] === 'number')
+    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) {
+    if (0 === recordings.active().length)
+        return;
+    const step = compileActStep(args, res);
+    // Keep the assertion the agent actually made. `act_and_wait { until }` IS the agent saying what
+    // success means — 12 of 14 calls in a day carried 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 until = args['until'] ?? args['predicate'];
+    if (until !== undefined) {
+        const parsed = PredicateSchema.safeParse(until);
+        // Only what a replay actually CHECKS — recording an unenforced assertion would grade the flow
+        // "asserted" while nothing verifies it, which is a false green in the feature built to prevent
+        // them. See enforcedOnReplay.
+        const expect = parsed.success ? enforcedOnReplay(predicateToExpect(parsed.data)) : undefined;
+        if (expect !== undefined)
+            step.expect = expect;
+    }
+    recordings.capture(step);
+}
 /**
  * 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
@@ -46,10 +76,20 @@ function sourceFromResult(res) {
  * a volatile ref. Only when neither is available is the step ref-bound (in-session only).
  */
 export function compileActStep(args, res) {
-    const r = asRecord(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 action = asString(args['action']) ?? '';
-    const actArgs = replayActionArgs(args['args']);
     const source = sourceFromResult(r);
     if (testid !== undefined) {
         // The testid anchors the step; source rides along purely so a failure can name a file. Carrying
@@ -62,7 +102,7 @@ export function compileActStep(args, res) {
         };
         if (source !== undefined)
             testidArgs['source'] = source;
-        return { tool: ReticleTool.ACT, stable: true, args: testidArgs };
+        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
@@ -80,7 +120,7 @@ export function compileActStep(args, res) {
         };
         if (source !== undefined)
             roleArgs['source'] = source;
-        return { tool: ReticleTool.ACT, stable: true, args: roleArgs };
+        return { args: roleArgs, stable: true };
     }
     const component = asString(r['component']);
     if (component !== undefined || source !== undefined) {
@@ -89,15 +129,15 @@ export function compileActStep(args, res) {
             componentArgs['component'] = component;
         if (source !== undefined)
             componentArgs['source'] = source;
-        return { tool: ReticleTool.ACT, stable: true, args: componentArgs };
+        return { args: componentArgs, stable: true };
     }
-    return {
-        tool: ReticleTool.ACT,
-        stable: false,
-        args: { ref: asString(args['ref']) ?? '', action, args: actArgs },
-    };
+    return { args: { ref, action, args: actArgs }, stable: false };
 }
-/** Compile an reticle_act_sequence invocation, normalizing each sub-step to its testid where resolvable. */
+/**
+ * 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'])
@@ -106,14 +146,10 @@ export function compileSequenceStep(args, res) {
     let stable = inputSteps.length > 0;
     const subSteps = inputSteps.map((raw, i) => {
         const step = asRecord(raw);
-        const action = asString(step['action']) ?? '';
-        const stepArgs = replayActionArgs(step['args']);
-        const testid = asString(asRecord(resolved[i])['testid']);
-        if (testid !== undefined) {
-            return { by: QueryBy.TESTID, value: testid, action, args: stepArgs };
-        }
-        stable = false;
-        return { ref: asString(step['ref']) ?? '', action, args: stepArgs };
+        const compiled = compileAnchorArgs(asRecord(resolved[i]), asString(step['ref']) ?? '', asString(step['action']) ?? '', replayActionArgs(step['args']));
+        if (!compiled.stable)
+            stable = false;
+        return compiled.args;
     });
     return { tool: ReticleTool.ACT_SEQUENCE, stable, args: { steps: subSteps } };
 }
@@ -181,7 +217,7 @@ async function resolveRef(session, step) {
             : { ref };
     }
     const ref = asString(step.ref);
-    if (ref === undefined || ref.length === 0) {
+    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)' };

package/dist/flows/role-anchor-nearest.d.ts

@@ -0,0 +1,6 @@
+/** Present controls, as role + accessible name. */
+export interface RoleCandidate {
+    role: string;
+    name: string;
+}
+export declare function nearestRoleName(role: string, missing: string, present: readonly RoleCandidate[]): string | null;

package/dist/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-replay.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/flows/server-verify.d.ts

@@ -7,7 +7,7 @@
  */
 import type { SuiteVerdict } from '@reticlehq/core';
 import type { ToolDeps } from '../tools/tools.js';
-import { type ProjectCloud } from './../cloud/cloud-config.js';
+import { type ProjectCloud } from '../cloud/cloud-config.js';
 import { type ServerVerification } from '../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;

package/dist/flows/server-verify.js

@@ -1,4 +1,4 @@
-import { VerifyMode } from './../cloud/cloud-config.js';
+import { VerifyMode } from '../cloud/cloud-config.js';
 import { submitServerVerification } from '../cloud/cloud-sync.js';
 const PASS = 'pass';
 const UNVERIFIED = 'unverified';
@@ -14,12 +14,12 @@ export function toSuiteVerdict(report) {
     }));
     const total = report.flows.length;
     const passed = total - failures.length;
-    const status = report.verdict === PASS && failures.length === 0 ? 'pass' : 'fail';
+    const status = report.verdict === PASS && 0 === failures.length ? 'pass' : 'fail';
     return { status, total, passed, failed: failures.length, summary: report.summary, failures };
 }
 /** Run the suite on the hosted runner, or null to signal the caller should replay locally. */
 export async function runServerVerify(deps, cloud, sessionId, flows) {
-    if (cloud.verify !== VerifyMode.SERVER || cloud.config === null)
+    if (cloud.verify !== VerifyMode.SERVER || null === cloud.config)
         return null;
     let previewUrl;
     try {
@@ -29,10 +29,10 @@ export async function runServerVerify(deps, cloud, sessionId, flows) {
         previewUrl = undefined;
     }
     // The server hits the URL itself; with no URL (or a localhost one it can't reach) fall back to local.
-    if (previewUrl === undefined || previewUrl.length === 0)
+    if (previewUrl === undefined || 0 === previewUrl.length)
         return null;
     const report = await submitServerVerification({ previewUrl, flows, source: SOURCE }, cloud.config, (url, init) => fetch(url, init));
-    if (report === null)
+    if (null === report)
         return null;
     // The hosted runner said it couldn't actually verify (e.g. it's not enabled yet). Never surface that as
     // a pass or a fail — fall back to the real local replay so the verdict reflects a browser that ran.

package/dist/flows/verify-change-tools.js

@@ -1,14 +1,15 @@
 import { z } from 'zod';
+import { verdictForSuite } from './verify-change-verdict.js';
+import { attributedFailures } from './attributed-failure.js';
 import { Verified } from '@reticlehq/core';
 import { ReticleTool } from '../tools/tool-names.js';
 import { asNumber, asRecord, asString } from '../tools/tools-helpers.js';
-import { loadNamedFlows, resolveChangedFiles } from '../cli-flow-commands.js';
+import { loadNamedFlows, resolveChangedFiles } from '../cli/cli-flow-commands.js';
 import { affectedSavedFlows } from './flow-sources.js';
 import { FLOW_TOOLS } from './flow-tools.js';
 import { findContradictions } from '../events/contradictions.js';
 import { parseControls } from '../tools/coverage-tools.js';
 import { ReticleCommand, SnapshotMode } from '@reticlehq/core';
-const PASS = 'pass';
 export const VERIFY_CHANGE_TOOLS = [
     {
         name: ReticleTool.VERIFY_CHANGE,
@@ -57,13 +58,13 @@ export const VERIFY_CHANGE_TOOLS = [
         },
         handler: async (deps, args) => {
             const files = Array.isArray(args['files'])
-                ? args['files'].filter((f) => typeof f === 'string')
+                ? args['files'].filter((f) => 'string' === typeof f)
                 : [];
             const since = asString(args['since']);
             const changedFiles = await resolveChangedFiles(files, since);
             const flows = await loadNamedFlows(deps.fs, deps.reticleRoot);
             const { affected, unknownProvenance } = affectedSavedFlows(flows, changedFiles);
-            if (changedFiles.length === 0) {
+            if (0 === changedFiles.length) {
                 return {
                     verified: Verified.UNKNOWN,
                     because: 'no changed files were given, so there was nothing to decide about',
@@ -77,10 +78,10 @@ export const VERIFY_CHANGE_TOOLS = [
             }
             // The guard: an uncovered change is UNKNOWN. Reporting `yes` here would mean "your change is
             // fine" on the strength of having run nothing at all.
-            if (affected.length === 0) {
+            if (0 === affected.length) {
                 return {
                     verified: Verified.UNKNOWN,
-                    because: `no saved flow covers ${changedFiles.length === 1 ? 'this file' : 'these files'} — record one with reticle_record { action: "start" } then reticle_flow_save, or verify by driving the app directly`,
+                    because: `no saved flow covers ${1 === changedFiles.length ? 'this file' : 'these files'} — record one with reticle_record { action: "start" } then reticle_flow_save, or verify by driving the app directly`,
                     changedFiles,
                     flowsRun: [],
                     unknownProvenance,
@@ -104,11 +105,32 @@ export const VERIFY_CHANGE_TOOLS = [
             }));
             const failed = suite.failed ?? 0;
             const passed = suite.passed ?? 0;
-            const failedSuite = suite.status !== PASS || failed > 0;
-            if (failedSuite) {
+            // `unverifiable` is NOT a failure — the suite ran and proved nothing, which is the same fact
+            // this tool answers UNKNOWN for an uncovered change. Treating it as a red emitted a bug_found
+            // that nothing earned. See verify-change-verdict.
+            const verdict = verdictForSuite(String(suite.status), failed);
+            // A NO must be EARNED by a failing flow genuinely tied to the changed files. `affectedSavedFlows`
+            // re-runs any flow whose sources it cannot determine — over-running beats skipping — and those
+            // land in `unknownProvenance`. Judging the change on them produced a negative verdict whose own
+            // explanation admitted the evidence was not tied to the file. See attributed-failure.
+            const failingNames = Array.isArray(suite.failures)
+                ? suite.failures
+                    .map((f) => 'object' === typeof f && f !== null ? asString(asRecord(f)['flow']) : undefined)
+                    .filter((n) => n !== undefined)
+                : // No per-failure detail: the failure is somewhere in the set that ran, so ask the question
+                    // of all of them rather than guessing which.
+                    affected;
+            const attributed = attributedFailures(failingNames, unknownProvenance);
+            const earnedNo = verdict === Verified.NO && attributed.length > 0;
+            const reported = verdict === Verified.NO && !earnedNo ? Verified.UNKNOWN : verdict;
+            if (reported !== Verified.YES) {
                 return {
-                    verified: Verified.NO,
-                    because: `${String(failed)} of ${String(suite.total ?? affected.length)} covering flows failed${provenanceNote}`,
+                    verified: reported,
+                    because: earnedNo
+                        ? `${String(failed)} of ${String(suite.total ?? affected.length)} covering flows failed, including ${attributed.join(', ')}, which cover the changed files${provenanceNote}`
+                        : verdict === Verified.NO
+                            ? `flows failed, but Reticle cannot tell which sources any of them cover (${failingNames.join(', ')}) — so this says nothing about the files you changed. Re-record them so their sources are stamped, or read the replay yourself`
+                            : `the covering flows ran but proved nothing (${String(suite.status)}) — they assert no observable consequence, so a green from them would not have meant your change is safe${provenanceNote}`,
                     changedFiles,
                     flowsRun: affected,
                     suite,

package/dist/flows/verify-change-verdict.d.ts

@@ -0,0 +1,15 @@
+/**
+ * What a replayed suite's status entitles `verify_change` to claim.
+ *
+ * This was `suite.status !== 'pass'` meaning failure. That was true while the only statuses were
+ * pass and fail — but `flow_verify` now reports `unverifiable` for a suite that ran and proved
+ * nothing (an empty suite used to report `pass`, which was a false green). Under the old test,
+ * `unverifiable` fell into the failure branch: a suite that proved nothing came back as proof the
+ * change was broken, and emitted a `bug_found` for it.
+ *
+ * `unverifiable` is the same fact this tool already handles elsewhere as "no saved flow covers this
+ * change" — answered UNKNOWN, with the comment calling it "the honest answer, never a green: nothing
+ * ran, so nothing was proved". A red nothing earned is the mirror image of that green.
+ */
+import { Verified } from '@reticlehq/core';
+export declare function verdictForSuite(status: string, failedCount: number): Verified;

package/dist/flows/verify-change-verdict.js

@@ -0,0 +1,25 @@
+/**
+ * What a replayed suite's status entitles `verify_change` to claim.
+ *
+ * This was `suite.status !== 'pass'` meaning failure. That was true while the only statuses were
+ * pass and fail — but `flow_verify` now reports `unverifiable` for a suite that ran and proved
+ * nothing (an empty suite used to report `pass`, which was a false green). Under the old test,
+ * `unverifiable` fell into the failure branch: a suite that proved nothing came back as proof the
+ * change was broken, and emitted a `bug_found` for it.
+ *
+ * `unverifiable` is the same fact this tool already handles elsewhere as "no saved flow covers this
+ * change" — answered UNKNOWN, with the comment calling it "the honest answer, never a green: nothing
+ * ran, so nothing was proved". A red nothing earned is the mirror image of that green.
+ */
+import { Verified } from '@reticlehq/core';
+const PASS = 'pass';
+const FAIL = 'fail';
+export function verdictForSuite(status, failedCount) {
+    // A real failure outranks everything: flows ran and some went red.
+    if (failedCount > 0 || status === FAIL)
+        return Verified.NO;
+    if (status === PASS)
+        return Verified.YES;
+    // `unverifiable`, or any status added later. Nothing was proved, so nothing is claimed.
+    return Verified.UNKNOWN;
+}

package/dist/flows/watch-batcher.d.ts

@@ -4,10 +4,10 @@
  * a quiet window, so we compute affected flows once per edit, not per keystroke. The scheduler (setTimeout)
  * is injected, keeping the batching logic pure and unit-testable.
  */
-export interface WatchBatcher {
+interface WatchBatcher {
     onChange(file: string): void;
 }
-export interface WatchBatcherOptions {
+interface WatchBatcherOptions {
     debounceMs: number;
     /** Injected scheduler (setTimeout) — deterministic in tests. */
     schedule: (fn: () => void, ms: number) => void;
@@ -15,3 +15,4 @@ export interface WatchBatcherOptions {
     onFlush: (files: string[]) => void;
 }
 export declare function createWatchBatcher(options: WatchBatcherOptions): WatchBatcher;
+export {};

package/dist/honesty/already-true.d.ts

@@ -0,0 +1,2 @@
+import type { Predicate } from '../events/predicate.js';
+export declare function readsDomState(predicate: Predicate): boolean;