@reticlehq/server 3.5.0 → 3.7.0

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

@@ -17,6 +17,7 @@
  * 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 { Verified } from '@reticlehq/core';
 import type { ToolOutcome } from './harness.js';
 /** One driven action, reduced to what a reader needs: what was done, and what it proved. */
 export interface DrivenStep {
@@ -26,6 +27,8 @@ export interface DrivenStep {
     target: string;
     /** The engine's verdict for this step, when the step declared anything. */
     verified: string | undefined;
+    /** A route claim that missed: the driver's own guess, or a menu it opened. Never a check. */
+    guess?: true;
     /** The one sentence naming the deciding evidence. */
     because: string | undefined;
     /**
@@ -37,7 +40,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 +65,10 @@ 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";
+    /** Not saved on this computer: nothing ran, which is not a regression either. */
+    readonly MISSING: "missing";
 };
 export declare function replayedFlows(toolCalls: readonly ToolOutcome[]): {
     name: string;
@@ -61,4 +76,49 @@ 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;
+/** Whether the drive did anything to the app: an action that ran, or a flow it replayed. */
+export declare function actedOnApp(toolCalls: readonly ToolOutcome[]): boolean;
+/** The pages the drive's own snapshots reported, in order, each distinct page once. */
+export declare function pagesReached(toolCalls: readonly ToolOutcome[]): string[];
+/** The values the drive's acts filled or typed, sequence steps included. */
+export declare function typedValues(toolCalls: readonly ToolOutcome[]): 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;
+};
+/** A plan journey's status, as far as the run's verdict reads it. */
+export interface JourneyStatus {
+    status: string;
+}
+/** A run's verdict and the line that says it: the word is decided once, never read back out of the line. */
+export interface RunVerdict {
+    verified: Verified;
+    line: string;
+}
+/**
+ * The first line a caller reads, and the one the HUD ends on, with the verdict it states. 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 runVerdict(tally: {
+    held: number;
+    failed: number;
+    undecided: number;
+}, goalMet?: boolean, 
+/** A plan's journeys: when there are any, their verdict is the run's. */
+journeys?: readonly JourneyStatus[]): RunVerdict;
+/** The line alone. */
+export declare function verdictLine(tally: {
+    held: number;
+    failed: number;
+    undecided: number;
+}, goalMet?: boolean, journeys?: readonly JourneyStatus[]): string;
+/** Whether the run is proved, exactly as its headline says: the `proved` an answer carries. */
+export declare function runProved(tally: {
+    held: number;
+    failed: number;
+    undecided: number;
+}, goalMet?: boolean, journeys?: readonly JourneyStatus[]): boolean;
+export declare function describeDrive(toolCalls: readonly ToolOutcome[], savedFlows: readonly string[], unverifiedFlows?: readonly string[], goalMet?: boolean, journeys?: readonly JourneyStatus[]): string;

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

@@ -17,9 +17,76 @@
  * 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 { asRecord, asString, ReticleTool, Verified } from '@reticlehq/core';
+import { appFindings } from './app-findings.js';
+import { MSG_OPENED_MENU, MSG_ROUTE_GUESS_MISSED, claimsOnlyRoute } from './route-guess.js';
+import { asRecord, asString, ActionType, NO_SUCH_FLOW, ReplayStatus, ReticleTool, ScriptStatus, Verified, } from '@reticlehq/core';
+import { supersededChecks } from '@reticlehq/engine/evidence/superseded-checks.js';
+import { PredicateSchema } from '@reticlehq/engine/question/predicate/predicate-schema.js';
+import { describeWaitTarget } from '@reticlehq/engine/evidence/unsettled.js';
+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 +128,33 @@ 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',
+    /** Not saved on this computer: nothing ran, which is not a regression either. */
+    MISSING: 'missing',
+};
 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
+                ? status
+                : message.includes(DESTRUCTIVE_REFUSAL)
+                    ? ReplayOutcome.GUARDED
+                    : message.includes(NO_SUCH_FLOW)
+                        ? ReplayOutcome.MISSING
+                        : status,
         });
     }
     return out;
@@ -106,25 +190,134 @@ function describeClaim(until) {
         return 'a request or a signal';
     return kind;
 }
+/** The declared consequence: `until`, or `predicate`, its alias on act_and_wait and on assert. */
+function untilOf(args) {
+    return args['until'] ?? args['predicate'];
+}
+/** A `no` on a click whose only claim was a route: the driver's guess, not the app (route-guess.ts). */
+function routeGuessMissed(args, result) {
+    return Verified.NO === result['verified'] && claimsOnlyRoute(untilOf(args));
+}
+/** The line a re-press graded undecided carries instead of the raw `no`. */
+const MSG_REPRESS = "a second press of a control whose claim already held: the Harness's own extra action, not the app";
+/** Every check in drive order: act_and_wait with an `until` and asserts, through reticle_run too. */
+function gradedChecks(toolCalls) {
+    const heldPresses = new Set();
+    const out = [];
+    const checks = toolCalls.flatMap((made, index) => {
+        const call = throughRun(made);
+        const args = asRecord(call.args);
+        const until = untilOf(args);
+        const isCheck = ReticleTool.ASSERT === call.name ||
+            (ReticleTool.ACT_AND_WAIT === call.name && until !== undefined);
+        if (!isCheck || call.isError)
+            return [];
+        const predicate = PredicateSchema.safeParse(until);
+        const key = predicate.success
+            ? `${predicate.data.kind}|${describeWaitTarget(predicate.data)}`
+            : JSON.stringify(until ?? null);
+        return [{ index, call, args, result: asRecord(call.result), key }];
+    });
+    const superseded = supersededChecks(checks.map(({ call, result, key }) => ({
+        key,
+        passive: ReticleTool.ASSERT === call.name,
+        held: Verified.YES === asString(result['verified']),
+        failed: Verified.NO === asString(result['verified']),
+    })));
+    for (const [at, { index, args, result, key }] of checks.entries()) {
+        // The driver's own wrong guess about the route checked the driver, not the app.
+        if (routeGuessMissed(args, result))
+            continue;
+        const verified = asString(result['verified']);
+        // A passive assert that read too early: see superseded-checks.ts.
+        if (superseded.has(at))
+            continue;
+        // A second press of a control whose claim already held is the Harness's own extra action.
+        const ref = asString(args['ref']);
+        const pressed = ref === undefined ? undefined : `${ref}|${key}`;
+        const repress = Verified.NO === verified && pressed !== undefined && heldPresses.has(pressed);
+        if (Verified.YES === verified && pressed !== undefined)
+            heldPresses.add(pressed);
+        const outcome = Verified.YES === verified
+            ? 'held'
+            : Verified.NO === verified && !repress
+                ? 'failed'
+                : 'undecided';
+        out.push({ index, key, outcome, repress });
+    }
+    return out;
+}
+/**
+ * A `reticle_run` call as the tool it ran. A navigation made through it was recorded under the
+ * run's name, and a run that navigated between two pages said it made no action against the app.
+ */
+function throughRun(call) {
+    if (ReticleTool.RUN !== call.name)
+        return call;
+    const args = asRecord(call.args);
+    const name = asString(args['tool']);
+    return name === undefined ? call : { ...call, name, args: asRecord(args['args']) };
+}
 /** Reduce the raw call log to the actions that actually drove the app. */
 export function drivenSteps(toolCalls) {
     const steps = [];
-    for (const call of toolCalls) {
+    const represses = new Set(gradedChecks(toolCalls)
+        .filter((check) => check.repress)
+        .map((check) => check.index));
+    for (const [index, made] of toolCalls.entries()) {
+        const call = throughRun(made);
         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');
+        const guessMissed = !call.isError && routeGuessMissed(args, result);
+        if (represses.has(index)) {
+            steps.push({
+                action,
+                target: targetOf(args, result),
+                verified: Verified.UNKNOWN,
+                because: MSG_REPRESS,
+                claimed: describeClaim(untilOf(args)),
+                evidence: [],
+            });
+            continue;
+        }
+        // A menu or dialog it opened is the way to the route it named, not a wrong guess.
+        const opened = guessMissed && 0 < openedADialog(result, toolCalls.slice(index + 1)).length;
         steps.push({
+            ...(guessMissed ? { guess: true } : {}),
             action,
             target: targetOf(args, result),
-            verified: call.isError ? 'error' : asString(result['verified']),
-            because: call.isError ? asString(result['error']) : asString(result['because']),
-            claimed: describeClaim(args['until']),
+            verified: call.isError
+                ? 'error'
+                : guessMissed
+                    ? Verified.UNKNOWN
+                    : asString(result['verified']),
+            because: call.isError
+                ? asString(result['error'])
+                : opened
+                    ? MSG_OPENED_MENU
+                    : guessMissed
+                        ? MSG_ROUTE_GUESS_MISSED
+                        : asString(result['because']),
+            claimed: describeClaim(untilOf(args)),
+            evidence: call.isError || opened
+                ? []
+                : [...evidenceOf(result), ...openedADialog(result, toolCalls.slice(index + 1))],
         });
     }
     return steps;
 }
+/** Whether the drive did anything to the app: an action that ran, or a flow it replayed. */
+export function actedOnApp(toolCalls) {
+    return (drivenSteps(toolCalls).some((step) => 'error' !== step.verified) ||
+        0 < replayedFlows(toolCalls).length);
+}
 /**
  * The account, as lines.
  *
@@ -134,19 +327,147 @@ 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) {
+export 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) {
+/** The values the drive's acts filled or typed, sequence steps included. */
+export function typedValues(toolCalls) {
+    const out = [];
+    const read = (act) => {
+        const inner = asRecord(act['args']);
+        const value = asString(inner['value']) ?? asString(inner['text']);
+        if (value !== undefined &&
+            (ActionType.FILL === act['action'] || ActionType.TYPE === act['action']))
+            out.push(value);
+    };
+    for (const call of toolCalls) {
+        const steps = call.args['steps'];
+        if (Array.isArray(steps))
+            for (const step of steps)
+                read(asRecord(step));
+        else
+            read(call.args);
+    }
+    return out;
+}
+/** How the drive's checks came out: act_and_wait with an `until`, and asserts. */
+export function checkTally(toolCalls) {
+    // One check per (kind, claim, outcome), exactly as the platform counts a run's checks: a live
+    // drive pressed "Sign in" fifteen times and read "15 of 15 check(s) held" for one fact, and an
+    // answer that counted by control said "2 of 2" beside a dashboard counting the same run otherwise.
+    const seen = new Set();
+    const tally = { held: 0, failed: 0, undecided: 0 };
+    const count = (key, now) => {
+        if (seen.has(`${key}|${now}`))
+            return;
+        seen.add(`${key}|${now}`);
+        tally[now] += 1;
+    };
+    for (const check of gradedChecks(toolCalls))
+        count(check.key, check.outcome);
+    // A replayed flow is a check too: its own expects decided it. A passed replay counted as "no
+    // check" and its run read NOT PROVED beside a dashboard that said Passed.
+    for (const replay of replayedFlows(toolCalls)) {
+        const now = REPLAY_CHECK[replay.status ?? ''];
+        if (now === undefined)
+            continue;
+        count(`${ReticleTool.FLOW_REPLAY}|${replay.name}`, now);
+    }
+    return tally;
+}
+/** A replay as a check. Guarded and missing never ran, so they are no check at all. */
+const REPLAY_CHECK = {
+    [ReplayOutcome.OK]: 'held',
+    [ReplayOutcome.ERROR]: 'failed',
+    [ReplayOutcome.DRIFT]: 'undecided',
+    [ReplayStatus.UNVERIFIABLE]: 'undecided',
+};
+/** Statuses that leave a plan proved: passed, or a side road deliberately not taken (named in its line). */
+const SETTLED_JOURNEY = new Set([ScriptStatus.PASSED, ScriptStatus.NOT_TAKEN]);
+/**
+ * A plan run's verdict is its journeys', decided as the platform decides it (`planRunVerdict`): any
+ * failed → failed; every journey passed (or deliberately not taken) → proved; some passed beside
+ * journeys left undecided or blocked → not proved. Undefined when there is no plan.
+ *
+ * "Any passed → proved" read PROVED for a plan whose other journeys a credit cut-off had blocked:
+ * one journey proved and the rest never decided, reported as the whole plan proved.
+ */
+function journeysVerdict(journeys, counts) {
+    if (0 === journeys.length)
+        return undefined;
+    const of = (status) => journeys.filter((j) => status === j.status).length;
+    const total = String(journeys.length);
+    const passed = of(ScriptStatus.PASSED);
+    if (0 < of(ScriptStatus.FAILED))
+        return {
+            verified: Verified.NO,
+            line: `NOT PROVED — ${String(of(ScriptStatus.FAILED))} of ${total} journey(s) failed${counts}.`,
+        };
+    if (0 < passed && journeys.every((j) => SETTLED_JOURNEY.has(j.status)))
+        return {
+            verified: Verified.YES,
+            line: `PROVED — ${String(passed)} of ${total} journey(s) passed${counts}.`,
+        };
+    if (0 < passed)
+        return {
+            verified: Verified.UNKNOWN,
+            line: `NOT PROVED — ${String(passed)} of ${total} journey(s) passed and the rest were not decided${counts}.`,
+        };
+    return { verified: Verified.UNKNOWN, line: `NOT PROVED — no journey passed${counts}.` };
+}
+/**
+ * The first line a caller reads, and the one the HUD ends on, with the verdict it states. 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 runVerdict(tally, goalMet, 
+/** A plan's journeys: when there are any, their verdict is the run's. */
+journeys = []) {
+    const total = tally.held + tally.failed + tally.undecided;
+    const counts = `${String(tally.held)} of ${String(total)} check(s) held, ${String(tally.failed)} failed, ${String(tally.undecided)} undecided`;
+    const planned = journeysVerdict(journeys, 0 === total ? '' : `; ${counts}`);
+    const not = (line) => ({ verified: Verified.UNKNOWN, line });
+    // Journeys that passed are not the run's goal reached: the goals the run was asked decide it too.
+    if (Verified.YES === planned?.verified && false === goalMet)
+        return not(`NOT PROVED — ${planned.line.slice('PROVED — '.length).replace(/\.$/, '')}, but the goal was not reached.`);
+    if (planned !== undefined)
+        return planned;
+    if (0 === total)
+        return not('NOT PROVED: the drive ran no check.');
+    if (0 < tally.failed)
+        return {
+            verified: Verified.NO,
+            line: `NOT PROVED — ${counts}. The failures below are findings.`,
+        };
+    if (0 < tally.undecided)
+        return not(`NOT PROVED — ${counts}.`);
+    // Checks that held on the way are not the journey done.
+    if (false === goalMet)
+        return not(`NOT PROVED — ${counts}, but the goal was not reached.`);
+    return { verified: Verified.YES, line: `PROVED — ${counts}.` };
+}
+/** The line alone. */
+export function verdictLine(tally, goalMet, journeys = []) {
+    return runVerdict(tally, goalMet, journeys).line;
+}
+/** Whether the run is proved, exactly as its headline says: the `proved` an answer carries. */
+export function runProved(tally, goalMet, journeys = []) {
+    return Verified.YES === runVerdict(tally, goalMet, journeys).verified;
+}
+export function describeDrive(toolCalls, savedFlows, unverifiedFlows = [], goalMet, journeys = []) {
     const steps = drivenSteps(toolCalls);
     const replays = replayedFlows(toolCalls);
     /*
@@ -162,34 +483,59 @@ 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 missing = replays.filter((r) => ReplayOutcome.MISSING === 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`}` +
+                    `${0 === missing.length ? '' : `, ${String(missing.length)} not on this computer`}.`,
             ];
+            if (0 < missing.length)
+                lines.push(`  MISSING: ${missing.map((r) => r.name).join(', ')} — not saved on this computer, or calls a flow that is not, so it never ran. Not a regression: pull or record them here first.`);
             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');
         })();
-    if (0 === steps.length)
-        return (replayLine ??
-            'Nothing was driven and nothing was replayed: the run made no action against the app.');
+    // A plan run leads with its journeys' verdict even when the model drove nothing: its replays, or
+    // a journey a guard stopped, are a result, never "no action against the app".
+    if (0 === steps.length) {
+        const lead = 0 === journeys.length ? undefined : verdictLine(checkTally(toolCalls), goalMet, journeys);
+        return [
+            lead,
+            replayLine ??
+                (lead === undefined
+                    ? 'Nothing was driven and nothing was replayed: the run made no action against the app.'
+                    : undefined),
+        ]
+            .filter((line) => line !== undefined)
+            .join('\n');
+    }
     const proved = steps.filter((step) => Verified.YES === step.verified);
     const failed = steps.filter((step) => Verified.NO === step.verified);
-    const undecided = steps.filter((step) => Verified.YES !== step.verified && Verified.NO !== step.verified);
+    // The driver's own route guesses are no check (as `checkTally` counts), so not "not decided".
+    const guesses = steps.filter((step) => true === step.guess);
+    const undecided = steps.filter((step) => true !== step.guess && Verified.YES !== step.verified && Verified.NO !== step.verified);
     const pages = pagesReached(toolCalls);
     const lines = [
+        verdictLine(checkTally(toolCalls), goalMet, journeys),
         ...(replayLine === undefined ? [] : [replayLine]),
-        `Drove ${String(steps.length)} action(s): ${String(proved.length)} proved, ` +
-            `${String(failed.length)} failed, ${String(undecided.length)} not decided.`,
+        // The outcomes are counted once, in the checks line above: no second breakdown here.
+        `Drove ${String(steps.length)} action(s)` +
+            (0 === guesses.length ? '.' : `; ${String(guesses.length)} guess of its own, not a check.`),
         // How DEEP it got. An action count reads the same for a checkout walked to its receipt and for
         // eleven clicks on the home page; the pages reached are what tell them apart.
         ...(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, ...guesses].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 +547,36 @@ 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.`);
-    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(', ')}.`);
+    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).`);
+    // Counted from the same graded checks as the checks line, never from the raw step verdicts: an
+    // answer read "0 failed" beside "1 action(s) FAILED … These are findings" about one re-press.
+    const tally = checkTally(toolCalls);
+    if (0 < tally.failed)
+        lines.push(`${String(tally.failed)} check(s) FAILED — the app did not do what the drive declared it would. These are findings.`);
+    if (0 < tally.undecided)
+        lines.push(`${String(tally.undecided)} check(s) undecided. That is undecided evidence, not a failure: it calls for a better check, not a code change.`);
+    const undeclared = undecided.filter((step) => step.claimed === undefined).length;
+    if (0 < undeclared)
+        lines.push(`${String(undeclared)} action(s) declared no consequence, so they prove nothing either way: not a check, not a failure.`);
+    // 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');
 }