@reticlehq/server 3.5.0 → 3.6.0

package/dist/features/crawl/crawl-tools.js

@@ -87,6 +87,10 @@ export const CRAWL_TOOLS = [
                 .optional()
                 .describe('Present only when the page exceeded one snapshot, so controls past the cap were never listed. When present, a zero-anomaly result does NOT mean the app is clean.'),
             truncated: z.boolean(),
+            notJudged: z
+                .array(z.object({ ref: z.string(), desc: z.string(), reason: z.string() }))
+                .optional()
+                .describe('Controls clicked whose silence could not be judged, e.g. on a background tab. They are NOT reported as dead, and they are not known to work either.'),
             // Only on `exhaustive` — see features/exhaust/exhaust-run.ts. Loose: it carries the levels.
             exhaustive: z.record(z.unknown()).optional(),
         },

package/dist/features/crawl/crawl.d.ts

@@ -81,6 +81,12 @@ export interface CrawlReport {
     truncated: boolean;
     /** Present only when the snapshot itself was capped, i.e. controls exist that were never listed. */
     coverageNote?: string;
+    /** Controls whose silence could not be judged, present only when non-empty. */
+    notJudged?: {
+        ref: string;
+        desc: string;
+        reason: string;
+    }[];
 }
 export interface CrawlOptions {
     maxSteps?: number;

package/dist/features/crawl/crawl.js

@@ -33,6 +33,8 @@ function revealedControlsNote(count) {
         'started were never visited — interactiveFound is a floor, not a total; re-run the crawl from ' +
         'the state you are now in to cover them');
 }
+/** Why a silent control on a throttled page is not reported as dead. */
+const BACKGROUND_TAB_NOT_JUDGED = 'not judged: the page is throttled (its tab is in the background, or it has not been heard from recently), so a reaction may not show inside the sample window; bring the tab to the front and crawl again';
 /** Any buffer event that proves the app reacted to a click (vs a dead/no-op control). */
 function isActivity(e) {
     return (e.type === EventType.NET_REQUEST ||
@@ -255,6 +257,7 @@ export async function crawl(session, opts, sleep) {
     // `truncated:false` would positively assert that nothing was cut.
     const coverageCapped = true === snapshot.truncated;
     const anomalies = [];
+    const notJudged = [];
     const visited = [];
     const counts = { consoleErrors: 0, failedRequests: 0, deadControls: 0, contradictions: 0 };
     const seen = new Set();
@@ -401,7 +404,11 @@ export async function crawl(session, opts, sleep) {
                 //
                 // A second click costs one round trip on the rare control that looked dead, and nothing at all
                 // on every control that did not. A genuinely dead control is silent twice; the flake is not.
-                if (await stillSilent(session, item, settleMs, confirm, sleep)) {
+                // A throttled page may defer DOM observer flushes, so silence cannot prove a dead control.
+                if (true === session.throttled?.()) {
+                    notJudged.push({ ref: item.ref, desc: item.desc, reason: BACKGROUND_TAB_NOT_JUDGED });
+                }
+                else if (await stillSilent(session, item, settleMs, confirm, sleep)) {
                     counts.deadControls += 1;
                     anomalies.push({
                         kind: CrawlAnomalyKind.DEAD_CONTROL,
@@ -435,6 +442,7 @@ export async function crawl(session, opts, sleep) {
         anomalies,
         counts,
         visited,
+        ...(0 === notJudged.length ? {} : { notJudged }),
         // True when coverage was bounded for EITHER reason: the step budget ran out, or the page was
         // bigger than one snapshot. Conflating "I stopped early" with "I saw everything" is what turns a
         // partial sweep into "all controls healthy".

package/dist/features/exhaust/ledger.d.ts

@@ -158,6 +158,13 @@ export interface LevelReport {
     /** How many more are missing than `missing` names. */
     missingOverflow?: number;
 }
+/**
+ * Each level's percentage for the project at `reticleRoot`, for the HUD: numbers only, and only the
+ * levels with an honest denominator. Undefined when nothing has been measured yet.
+ *
+ * Synchronous because the impact snapshot it feeds is: one small file read per snapshot.
+ */
+export declare function coveragePercents(reticleRoot: string): Record<string, number> | undefined;
 export declare function emptyLedger(): AppLedger;
 export declare function mergeLedger(into: AppLedger, delta: LedgerDelta): AppLedger;
 export declare function levelsOf(ledger: AppLedger): LevelReport[];

package/dist/features/exhaust/ledger.js

@@ -18,6 +18,7 @@
  * Union-only. A later drive can add coverage and never remove it, so the number only moves down when
  * the app grows something nobody has covered yet — which is precisely what the ratchet is for.
  */
+import { readFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { z } from 'zod';
 import { writeFileAtomic } from '../../memory/project/fs/write-atomic.js';
@@ -45,6 +46,39 @@ const LedgerSchema = z.object({
     codeTaken: z.record(z.number()).default({}),
     best: z.record(z.number()),
 });
+/** A ledger file's text, or an empty ledger for anything unreadable: coverage never throws. */
+function parseLedger(text) {
+    try {
+        const parsed = z
+            .object({ version: z.literal(LEDGER_VERSION), ledger: LedgerSchema })
+            .safeParse(JSON.parse(text));
+        return parsed.success ? parsed.data.ledger : emptyLedger();
+    }
+    catch {
+        return emptyLedger();
+    }
+}
+/**
+ * Each level's percentage for the project at `reticleRoot`, for the HUD: numbers only, and only the
+ * levels with an honest denominator. Undefined when nothing has been measured yet.
+ *
+ * Synchronous because the impact snapshot it feeds is: one small file read per snapshot.
+ */
+export function coveragePercents(reticleRoot) {
+    let text;
+    try {
+        text = readFileSync(reticleDirPaths(reticleRoot).coverage, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    const out = {};
+    for (const report of levelsOf(parseLedger(text))) {
+        if (report.pct !== undefined)
+            out[report.level] = report.pct;
+    }
+    return 0 < Object.keys(out).length ? out : undefined;
+}
 export function emptyLedger() {
     return {
         routes: { discovered: [], reached: [] },
@@ -213,15 +247,7 @@ export class LedgerStore {
                 return emptyLedger();
             throw error;
         }
-        try {
-            const parsed = z
-                .object({ version: z.literal(LEDGER_VERSION), ledger: LedgerSchema })
-                .safeParse(JSON.parse(text));
-            return parsed.success ? parsed.data.ledger : emptyLedger();
-        }
-        catch {
-            return emptyLedger();
-        }
+        return parseLedger(text);
     }
     /**
      * Fold a delta in, raise the best, persist, and hand back the result. Under the file's lock: two

package/dist/features/harness/app-findings.d.ts

@@ -0,0 +1,2 @@
+import type { ToolOutcome } from './harness.js';
+export declare function appFindings(toolCalls: readonly ToolOutcome[]): string[];

package/dist/features/harness/app-findings.js

@@ -0,0 +1,52 @@
+/**
+ * What a drive found that no single click's check could: the page rendering something other than
+ * what the API sent (`reticle_reconcile`, run on each page the Harness reaches), and the crawl's
+ * anomalies (blank routes, dead controls, console errors, contradictions).
+ *
+ * Listed in the drive's report beside the verdict, because the agent reading it reports what it is
+ * shown: a defect the drive saw and the report left out is a defect nobody hears about.
+ */
+import { ReticleTool, asRecord, asString } from '@reticlehq/core';
+/** Enough to act on without burying the verdict. */
+const MAX_FINDINGS = 20;
+export function appFindings(toolCalls) {
+    const seen = new Set();
+    const lines = [];
+    const add = (key, line) => {
+        if (seen.has(key) || MAX_FINDINGS <= lines.length)
+            return;
+        seen.add(key);
+        lines.push(line);
+    };
+    for (const call of toolCalls) {
+        if (call.isError)
+            continue;
+        const result = asRecord(call.result);
+        if (ReticleTool.RECONCILE === call.name) {
+            const mismatches = result['mismatches'];
+            for (const raw of Array.isArray(mismatches) ? mismatches : []) {
+                const m = asRecord(raw);
+                const entity = asString(m['entity']) ?? '?';
+                const field = asString(m['field']) ?? '?';
+                const shown = asString(m['rendered']);
+                add(`r:${entity}:${field}`, `  RENDERED ≠ API: ${entity} ${field} — the API says ${String(m['api'])}${shown === undefined ? '' : `, the page shows ${shown}`} (${asString(m['why']) ?? ''})`);
+            }
+        }
+        if (ReticleTool.CRAWL === call.name) {
+            const anomalies = result['anomalies'];
+            for (const raw of Array.isArray(anomalies) ? anomalies : []) {
+                const a = asRecord(raw);
+                const kind = asString(a['kind']) ?? 'anomaly';
+                const desc = asString(a['desc']) ?? '';
+                const detail = asString(a['detail']);
+                add(`c:${kind}:${desc}`, `  CRAWL ${kind}: ${desc}${detail === undefined ? '' : ` — ${detail}`}`);
+            }
+        }
+    }
+    return 0 === lines.length
+        ? []
+        : [
+            'Found beyond the clicks (each page compared with the API, and a crawl of the app):',
+            ...lines,
+        ];
+}

package/dist/features/harness/drive-report.d.ts

@@ -37,7 +37,15 @@ export interface DrivenStep {
      * noise, and the report is read every drive.
      */
     claimed: string | undefined;
+    /**
+     * What the engine saw that decided it: each channel that disagreed, and any write the app sent
+     * that failed. The act's own result carries all of it; a report that kept only the verdict word
+     * handed the caller "unit-mismatch" and left it unable to say what was wrong.
+     */
+    evidence: string[];
 }
+/** Driving calls that ran with the destructive-action permission: these really changed the app. */
+export declare function confirmedDestructive(toolCalls: readonly ToolOutcome[]): number;
 /**
  * Replays this drive ran, and what each came back with.
  *
@@ -54,6 +62,8 @@ export declare const ReplayOutcome: {
     readonly OK: "ok";
     readonly DRIFT: "drift";
     readonly ERROR: "error";
+    /** Stopped at a step the flow marks destructive: not run, which is not a regression. */
+    readonly GUARDED: "guarded";
 };
 export declare function replayedFlows(toolCalls: readonly ToolOutcome[]): {
     name: string;
@@ -61,4 +71,20 @@ export declare function replayedFlows(toolCalls: readonly ToolOutcome[]): {
 }[];
 /** Reduce the raw call log to the actions that actually drove the app. */
 export declare function drivenSteps(toolCalls: readonly ToolOutcome[]): DrivenStep[];
-export declare function describeDrive(toolCalls: readonly ToolOutcome[], savedFlows: readonly string[]): string;
+/** How the drive's checks came out: act_and_wait with an `until`, and asserts. */
+export declare function checkTally(toolCalls: readonly ToolOutcome[]): {
+    held: number;
+    failed: number;
+    undecided: number;
+};
+/**
+ * The first line a caller reads, and the one the HUD ends on. A drive whose only passing check was
+ * a page change, beside a refund that failed, is NOT "proved its checks"; that line ended a run
+ * where the journey it was asked to prove had failed.
+ */
+export declare function verdictLine(tally: {
+    held: number;
+    failed: number;
+    undecided: number;
+}): string;
+export declare function describeDrive(toolCalls: readonly ToolOutcome[], savedFlows: readonly string[], unverifiedFlows?: readonly string[]): string;

package/dist/features/harness/drive-report.js

@@ -17,9 +17,72 @@
  * that is what a coding agent has to gate on, and it says "not proved" in those words rather than
  * leaving a verdict of `unknown` to be read as a pass.
  */
+import { appFindings } from './app-findings.js';
 import { asRecord, asString, ReticleTool, Verified } from '@reticlehq/core';
+function refusedAsDestructive(call) {
+    const error = asString(asRecord(call.result)['error']) ?? '';
+    return call.isError && error.includes(DESTRUCTIVE_REFUSAL);
+}
+/** Driving calls that ran with the destructive-action permission: these really changed the app. */
+export function confirmedDestructive(toolCalls) {
+    return toolCalls.filter((call) => DRIVING_TOOLS.has(call.name) &&
+        !call.isError &&
+        true === asRecord(asRecord(call.args)['args'])[DESTRUCTIVE_REFUSAL]).length;
+}
+/**
+ * A failed claim whose page then showed a dialog: the control opens a confirmation, and the drive
+ * guessed it would send the request itself. Reported as a defect, a row's "Refund" button that opens
+ * the "Refund now" dialog sent the caller looking for a dead control.
+ */
+function openedADialog(result, after) {
+    if (Verified.NO !== result['verified'])
+        return [];
+    const next = after.find((call) => ReticleTool.SNAPSHOT === call.name);
+    const dialogs = asRecord(asRecord(next?.result)['status'])['visibleDialogs'];
+    return Array.isArray(dialogs) && 0 < dialogs.length
+        ? [
+            'it opened a dialog instead: likely the drive guessed the consequence wrong, not an app defect',
+        ]
+        : [];
+}
+/** Characters of a response body quoted in the evidence: enough for an error message. */
+const MAX_BODY_CHARS = 200;
+/** Contradictions quoted per step. */
+const MAX_EVIDENCE = 3;
+/** The deciding evidence an act result carries, as short lines. */
+function evidenceOf(result) {
+    const lines = [];
+    const contradictions = result['contradictions'];
+    if (Array.isArray(contradictions)) {
+        for (const raw of contradictions.slice(0, MAX_EVIDENCE)) {
+            const c = asRecord(raw);
+            const parts = [asString(c['counter']), asString(c['detail'])].filter((part) => part !== undefined && 0 < part.length);
+            lines.push(`${asString(c['kind']) ?? 'contradiction'}: ${parts.join(' — ')}`);
+        }
+    }
+    const verdict = asRecord(result['verdict']);
+    const seen = asRecord(verdict['evidence']);
+    const status = seen['status'];
+    if ('number' === typeof status && 400 <= status) {
+        const body = asString(seen['responseBody']);
+        lines.push(`${asString(seen['method']) ?? ''} ${asString(seen['url']) ?? ''} → ${String(status)}` +
+            (body === undefined ? '' : ` ${body.slice(0, MAX_BODY_CHARS)}`));
+    }
+    const observed = asString(verdict['observed']);
+    if (false === verdict['pass'] && observed !== undefined)
+        lines.push(`observed: ${observed}`);
+    return lines;
+}
+/** The permission a destructive action needs, named in the gate's refusal and carried on a retry. */
+const DESTRUCTIVE_REFUSAL = 'confirmDangerous';
 /** How many steps are listed before the account starts counting instead of naming. */
 const MAX_LISTED = 12;
+/**
+ * Failures are listed first, and up to this many of them however long the run. Listed in drive
+ * order, a whole-app run named 12 of 70 actions and left its failures in "… and 58 more", so the
+ * agent reading it could not say what any of them was.
+ */
+const MAX_FAILED = 40;
 /** Actions that change the app. Reads are not part of the story of what was driven. */
 const DRIVING_TOOLS = new Set([
     ReticleTool.ACT,
@@ -61,16 +124,27 @@ function targetOf(args, result) {
  * resolving — the app moved under a recording, which is a finding about the RECORDING rather than
  * proof the feature broke, and collapsing it into "failed" would send somebody to fix working code.
  */
-export const ReplayOutcome = { OK: 'ok', DRIFT: 'drift', ERROR: 'error' };
+export const ReplayOutcome = {
+    OK: 'ok',
+    DRIFT: 'drift',
+    ERROR: 'error',
+    /** Stopped at a step the flow marks destructive: not run, which is not a regression. */
+    GUARDED: 'guarded',
+};
 export function replayedFlows(toolCalls) {
     const out = [];
     for (const call of toolCalls) {
         if (ReticleTool.FLOW_REPLAY !== call.name)
             continue;
         const name = asString(asRecord(call.args)['flowName']) ?? 'a flow';
+        const result = asRecord(call.result);
+        const message = asString(asRecord(result['error'])['message']) ?? asString(result['error']) ?? '';
+        const status = call.isError ? ReplayOutcome.ERROR : asString(result['status']);
         out.push({
             name,
-            status: call.isError ? ReplayOutcome.ERROR : asString(asRecord(call.result)['status']),
+            status: ReplayOutcome.ERROR === status && message.includes(DESTRUCTIVE_REFUSAL)
+                ? ReplayOutcome.GUARDED
+                : status,
         });
     }
     return out;
@@ -109,11 +183,15 @@ function describeClaim(until) {
 /** Reduce the raw call log to the actions that actually drove the app. */
 export function drivenSteps(toolCalls) {
     const steps = [];
-    for (const call of toolCalls) {
+    for (const [index, call] of toolCalls.entries()) {
         if (!DRIVING_TOOLS.has(call.name))
             continue;
         const args = asRecord(call.args);
         const result = asRecord(call.result);
+        // The gate's refusal never reached the app; listed beside the confirmed retry, it read as "the
+        // refund was blocked" to the agent reading this, about a refund that had gone through.
+        if (refusedAsDestructive(call))
+            continue;
         const action = ReticleTool.NAVIGATE === call.name ? 'navigate' : (asString(args['action']) ?? 'act');
         steps.push({
             action,
@@ -121,6 +199,9 @@ export function drivenSteps(toolCalls) {
             verified: call.isError ? 'error' : asString(result['verified']),
             because: call.isError ? asString(result['error']) : asString(result['because']),
             claimed: describeClaim(args['until']),
+            evidence: call.isError
+                ? []
+                : [...evidenceOf(result), ...openedADialog(result, toolCalls.slice(index + 1))],
         });
     }
     return steps;
@@ -134,19 +215,66 @@ export function drivenSteps(toolCalls) {
  * rather than as a failure — it calls for a better check, not a code change, and collapsing the two
  * would send an agent to rewrite working code.
  */
+/** Every `__reticle_*` query parameter, wherever it sits in the route. */
+const RETICLE_PARAMS = /[?&]__reticle_[^&#]*/g;
 /** The pages the drive's own snapshots reported, in order, each distinct page once. */
 function pagesReached(toolCalls) {
     const pages = [];
     for (const call of toolCalls) {
         if (ReticleTool.SNAPSHOT !== call.name || call.isError)
             continue;
-        const route = asString(asRecord(asRecord(call.result)['status'])['route']);
+        const raw = asString(asRecord(asRecord(call.result)['status'])['route']);
+        // Reticle's own parameters (a leased tab's session and project) are not part of the page.
+        const route = raw?.replace(RETICLE_PARAMS, '').replace(/^\/\?(?=#|$)/, '/');
         if (route !== undefined && !pages.includes(route))
             pages.push(route);
     }
     return pages;
 }
-export function describeDrive(toolCalls, savedFlows) {
+/** How the drive's checks came out: act_and_wait with an `until`, and asserts. */
+export function checkTally(toolCalls) {
+    // One check per control and claim, at its worst: a live drive pressed "Sign in" fifteen times and
+    // reported "15 of 15 check(s) held" for one fact proved fifteen times over.
+    const worst = new Map();
+    for (const call of toolCalls) {
+        const args = asRecord(call.args);
+        const isCheck = ReticleTool.ASSERT === call.name ||
+            (ReticleTool.ACT_AND_WAIT === call.name && args['until'] !== undefined);
+        if (!isCheck || call.isError)
+            continue;
+        const result = asRecord(call.result);
+        const effect = asRecord(result['effect']);
+        const control = asString(effect['testid']) ??
+            `${asString(effect['role']) ?? ''} ${asString(effect['name']) ?? asString(args['ref']) ?? ''}`;
+        const key = `${call.name}|${control}|${JSON.stringify(args['until'] ?? args['predicate'] ?? null)}`;
+        const verified = asString(result['verified']);
+        const now = Verified.YES === verified ? 'held' : Verified.NO === verified ? 'failed' : 'undecided';
+        const before = worst.get(key);
+        if (before === undefined || 'failed' === now || ('undecided' === now && 'held' === before))
+            worst.set(key, now);
+    }
+    const tally = { held: 0, failed: 0, undecided: 0 };
+    for (const verdict of worst.values())
+        tally[verdict] += 1;
+    return tally;
+}
+/**
+ * The first line a caller reads, and the one the HUD ends on. A drive whose only passing check was
+ * a page change, beside a refund that failed, is NOT "proved its checks"; that line ended a run
+ * where the journey it was asked to prove had failed.
+ */
+export function verdictLine(tally) {
+    const total = tally.held + tally.failed + tally.undecided;
+    if (0 === total)
+        return 'NOT PROVED: the drive ran no check.';
+    const counts = `${String(tally.held)} of ${String(total)} check(s) held, ${String(tally.failed)} failed, ${String(tally.undecided)} undecided`;
+    if (0 < tally.failed)
+        return `NOT PROVED — ${counts}. The failures below are findings.`;
+    if (0 < tally.undecided)
+        return `NOT PROVED — ${counts}.`;
+    return `PROVED — ${counts}.`;
+}
+export function describeDrive(toolCalls, savedFlows, unverifiedFlows = []) {
     const steps = drivenSteps(toolCalls);
     const replays = replayedFlows(toolCalls);
     /*
@@ -162,12 +290,16 @@ export function describeDrive(toolCalls, savedFlows) {
             const held = replays.filter((r) => ReplayOutcome.OK === r.status);
             const failed = replays.filter((r) => ReplayOutcome.ERROR === r.status);
             const drifted = replays.filter((r) => ReplayOutcome.DRIFT === r.status);
+            const guarded = replays.filter((r) => ReplayOutcome.GUARDED === r.status);
             const lines = [
                 `Replayed ${String(replays.length)} recorded journey(s) with NO model in the loop: ` +
-                    `${String(held.length)} still hold, ${String(failed.length)} failed, ${String(drifted.length)} drifted.`,
+                    `${String(held.length)} still hold, ${String(failed.length)} failed, ${String(drifted.length)} drifted` +
+                    `${0 === guarded.length ? '' : `, ${String(guarded.length)} not run`}.`,
             ];
             if (0 < failed.length)
                 lines.push(`  FAILED: ${failed.map((r) => r.name).join(', ')} — regressions in journeys that used to pass.`);
+            if (0 < guarded.length)
+                lines.push(`  NOT RUN: ${guarded.map((r) => r.name).join(', ')} — stopped at a step marked destructive. Not a regression: replay with confirmDangerous to run it.`);
             if (0 < drifted.length)
                 lines.push(`  DRIFTED: ${drifted.map((r) => r.name).join(', ')} — the app moved under these recordings; the flow needs re-anchoring, not the app fixing.`);
             return lines.join('\n');
@@ -180,6 +312,7 @@ export function describeDrive(toolCalls, savedFlows) {
     const undecided = steps.filter((step) => Verified.YES !== step.verified && Verified.NO !== step.verified);
     const pages = pagesReached(toolCalls);
     const lines = [
+        verdictLine(checkTally(toolCalls)),
         ...(replayLine === undefined ? [] : [replayLine]),
         `Drove ${String(steps.length)} action(s): ${String(proved.length)} proved, ` +
             `${String(failed.length)} failed, ${String(undecided.length)} not decided.`,
@@ -188,8 +321,10 @@ export function describeDrive(toolCalls, savedFlows) {
         ...(0 === pages.length
             ? []
             : [`Reached ${String(pages.length)} page(s): ${pages.join(' → ')}.`]),
+        ...appFindings(toolCalls),
     ];
-    for (const step of steps.slice(0, MAX_LISTED)) {
+    const listed = [...failed, ...proved, ...undecided].slice(0, Math.max(MAX_LISTED, Math.min(failed.length, MAX_FAILED)));
+    for (const step of listed) {
         const verdict = step.verified ?? 'nothing declared';
         const because = step.because === undefined ? '' : ` — ${step.because}`;
         // The claim, on failures only: it is what separates "the app is broken" from "the drive guessed
@@ -201,14 +336,30 @@ export function describeDrive(toolCalls, savedFlows) {
             ? ` (claimed ${step.claimed})`
             : '';
         lines.push(`  ${step.action} ${step.target}: ${verdict}${claimed}${because}`);
+        for (const line of step.evidence)
+            lines.push(`      ${line}`);
+    }
+    if (listed.length < steps.length) {
+        const unlistedFailed = Math.max(0, failed.length - MAX_FAILED);
+        lines.push(`  … and ${String(steps.length - listed.length)} more` +
+            (0 === unlistedFailed
+                ? ', none of them failed.'
+                : `, ${String(unlistedFailed)} of them failed.`));
     }
-    if (MAX_LISTED < steps.length)
-        lines.push(`  … and ${String(steps.length - MAX_LISTED)} more.`);
+    const confirmed = confirmedDestructive(toolCalls);
+    if (0 < confirmed)
+        lines.push(`${String(confirmed)} destructive action(s) were confirmed and REALLY RAN against the app (the drive confirms one only after the gate refuses it; the refusal itself changed nothing).`);
     if (0 < failed.length)
         lines.push(`${String(failed.length)} action(s) FAILED — the app did not do what the drive declared it would. These are findings.`);
     if (0 < undecided.length)
         lines.push(`${String(undecided.length)} action(s) were NOT PROVED. That is undecided evidence, not a failure: it calls for a better check, not a code change.`);
-    if (0 < savedFlows.length)
-        lines.push(`Replay any of this without a model: reticle_verify { action: "flows" } — saved ${savedFlows.join(', ')}.`);
+    // A flow with no step that asserts anything replays as "verified nothing": offered as a replay it
+    // reads as evidence, so it is named for what it is instead.
+    const empty = new Set(unverifiedFlows);
+    const replayable = savedFlows.filter((name) => !empty.has(name));
+    if (0 < replayable.length)
+        lines.push(`Replay any of this without a model: reticle_verify { action: "flows" } — saved ${replayable.join(', ')}.`);
+    for (const name of unverifiedFlows)
+        lines.push(`Saved ${name}, but ${name} checks nothing: no step asserts a consequence, so its replay will verify nothing. Drive again naming the end state, or add an expect to its last step.`);
     return lines.join('\n');
 }

package/dist/features/harness/drivers.d.ts

@@ -1,19 +1,15 @@
 /**
- * The names of the drivers the harness can be asked for.
+ * The Harness's driver names.
  *
- * A leaf module on purpose. These used to be re-exported from `harness-explore.ts`, which sits in
- * the tool surface and is reached, through the toolset and the tool table, from the very tool that
- * needs to declare them as an enum — a cycle that left the list `[undefined, undefined]` at the
- * moment zod read it, and failed inside a JSON-schema parser rather than anywhere near the cause.
- * Nothing here imports anything, so nothing can be half-initialised when it is read.
+ * A leaf module on purpose: the tool table reads these while the tool surface is still loading, and
+ * a module that imports nothing cannot be read half-initialised.
+ *
+ * There is one driver. Every Harness decision, its models and its planning run on the Reticle
+ * platform, on the workspace's monthly Harness credits; this machine executes what it is told.
  */
-/** Generates its tool calls as text, and names the journeys it records. The default. */
-export declare const ANTHROPIC_DRIVER_NAME = "anthropic";
-/** Answers typed questions; picks from the elements on the page and cannot invent one. */
-export declare const JEV_DRIVER_NAME = "jev";
-/** Generates its tool calls, over Chat Completions. Here so an A/B has a third arm. */
-export declare const OPENAI_DRIVER_NAME = "openai";
-/** What a caller may name. Order is the order a reader sees them in the tool description. */
-export declare const DRIVER_NAMES: readonly ["anthropic", "jev", "openai"];
+/** The platform's Harness: it decides on its side, this machine executes. See server-driver.ts. */
+export declare const SERVER_DRIVER = "server";
 /** An injected driver: not selectable, because only a caller in-process can supply one. */
 export declare const CUSTOM_DRIVER_NAME = "custom";
+/** What a drive needs, said once for every place that tells somebody. */
+export declare const EXPLORE_NEEDS = "Runs on the Reticle platform: needs a linked project (`reticle connect`); Free has credits.";

package/dist/features/harness/drivers.js

@@ -1,19 +1,15 @@
 /**
- * The names of the drivers the harness can be asked for.
+ * The Harness's driver names.
  *
- * A leaf module on purpose. These used to be re-exported from `harness-explore.ts`, which sits in
- * the tool surface and is reached, through the toolset and the tool table, from the very tool that
- * needs to declare them as an enum — a cycle that left the list `[undefined, undefined]` at the
- * moment zod read it, and failed inside a JSON-schema parser rather than anywhere near the cause.
- * Nothing here imports anything, so nothing can be half-initialised when it is read.
+ * A leaf module on purpose: the tool table reads these while the tool surface is still loading, and
+ * a module that imports nothing cannot be read half-initialised.
+ *
+ * There is one driver. Every Harness decision, its models and its planning run on the Reticle
+ * platform, on the workspace's monthly Harness credits; this machine executes what it is told.
  */
-/** Generates its tool calls as text, and names the journeys it records. The default. */
-export const ANTHROPIC_DRIVER_NAME = 'anthropic';
-/** Answers typed questions; picks from the elements on the page and cannot invent one. */
-export const JEV_DRIVER_NAME = 'jev';
-/** Generates its tool calls, over Chat Completions. Here so an A/B has a third arm. */
-export const OPENAI_DRIVER_NAME = 'openai';
-/** What a caller may name. Order is the order a reader sees them in the tool description. */
-export const DRIVER_NAMES = [ANTHROPIC_DRIVER_NAME, JEV_DRIVER_NAME, OPENAI_DRIVER_NAME];
+/** The platform's Harness: it decides on its side, this machine executes. See server-driver.ts. */
+export const SERVER_DRIVER = 'server';
 /** An injected driver: not selectable, because only a caller in-process can supply one. */
 export const CUSTOM_DRIVER_NAME = 'custom';
+/** What a drive needs, said once for every place that tells somebody. */
+export const EXPLORE_NEEDS = 'Runs on the Reticle platform: needs a linked project (`reticle connect`); Free has credits.';