@reticlehq/server 3.6.0 → 3.7.0

package/dist/features/harness/goals.js

@@ -6,72 +6,325 @@
  * word for it is not evidence, so after every drive the harness checks each goal itself, with the
  * same assert any agent would make, and reports one verdict per goal.
  */
-import { PredicateKind, ReticleTool, Verified, asRecord } from '@reticlehq/core';
+import { PredicateKind, QueryBy, ReticleTool, Verified, VerifiedReason, asRecord, } from '@reticlehq/core';
 /** More than this and the persona is a document, not a set of goals. */
 const MAX_GOALS = 10;
 const MAX_GOAL_LENGTH = 200;
-/** A string the persona quoted: "straight" or “curly”. Single quotes are apostrophes too often. */
-const QUOTED = /"([^"\n]{1,200})"|“([^”\n]{1,200})”/g;
-/** The observable goals in a persona: whatever it quoted. */
-export function goalsIn(persona) {
+/**
+ * A string the persona quoted: "straight" or “curly”. Single quotes are apostrophes too often.
+ *
+ * A straight quote opens only after a space, a bracket or the start, and closes only before one or
+ * before sentence punctuation, so a goal that quotes text with quotes in it — the issue title
+ * `"Check failed: an element matching {"testid":"pay"}"` — stays one goal. Matching any `"` split
+ * that title into `{`, `:` and `}`, and graded the fragments.
+ */
+const QUOTED = /(?<![^\s([])"([^\n]{1,200}?)"(?![^\s.,;!?)\]])|“([^”\n]{1,200})”/g;
+/**
+ * A negation in the same clause just before a quote: "must not show "payments"". The window stops
+ * at the previous quote or clause end, so `doesn't show "X" until you click "Y"` negates X only. A
+ * comma ends the clause too: "place the order without the coupon, ending on "Order confirmed"" read
+ * its end as text that must be absent, and the journey failed with no goal to reach.
+ */
+const NEGATED_BEFORE = /(?:\b(?:not|never|no|nor|without|no longer)|n't)\b[^"“”.,;!?]{0,40}$/i;
+/** Said of a goal the page showed before the drive did anything. */
+const ALREADY_SHOWN = `${VerifiedReason.ALREADY_TRUE}: it was on the page before the drive started, so seeing it proves nothing`;
+/**
+ * Said of a goal the page the drive ended on never showed, even scrolled. Undecided, never `no`: the
+ * drive may not have reached the page that shows it, and a "no" there blamed the app for where the
+ * Harness stopped.
+ */
+const NOT_REACHED = `${VerifiedReason.INCONCLUSIVE}: not on the page the drive ended on, even scrolled; the drive may not have reached the page that shows it`;
+/** Said of a goal the page showed when looked at, which the text check nonetheless did not find. */
+const SHOWN_NOT_HELD = `${VerifiedReason.INCONCLUSIVE}: shown on the page when looked at, but the text check did not find it (a field's value, or text it cannot read)`;
+/** Said of an absence goal beside a goal the drive never reached: absent from the wrong page proves nothing. */
+const ABSENCE_UNREACHED = `${VerifiedReason.INCONCLUSIVE}: the drive did not reach the page it ends on, so its absence there proves nothing`;
+/** How the snapshot and the element reader end a text they cut short. */
+const CUT = '…';
+const collapse = (text) => text.replace(/\s+/g, ' ').trim();
+/**
+ * Whether `shown` — one element's text, maybe cut short with "…" — is text the Harness wrote itself
+ * rather than the app: one of `own` (its journey, the names of the plan and the flows it saved), in
+ * full or cut short, holding `goal`. A Harness asked to rename a plan stopped on the /plans list and
+ * was graded PROVED on every quote: the plan it had just saved was named after the journey, and the
+ * journey quoted them all. An element showing exactly the goal is the app's, whoever else wrote it.
+ */
+export function writtenByHarness(shown, goal, own) {
+    const full = collapse(shown);
+    const cut = full.endsWith(CUT);
+    const text = cut ? full.slice(0, -CUT.length).trimEnd() : full;
+    const wanted = collapse(goal);
+    if (text.length <= wanted.length)
+        return false;
+    return own.some((o) => {
+        const mine = collapse(o);
+        if (0 === mine.length || !mine.includes(wanted))
+            return false;
+        if (cut && mine.startsWith(text))
+            return true;
+        // Its own text first ("<journey> and 5 more"): what follows it is not the Harness's.
+        return text.startsWith(mine) && !text.slice(mine.length).includes(wanted);
+    });
+}
+/**
+ * Whether a snapshot shows `goal` anywhere but inside text the Harness wrote itself. Read as text,
+ * not parsed: the journey quotes its goals, so its quotes cut a parsed name short.
+ */
+function shownByApp(tree, goal, own) {
+    const wanted = collapse(goal);
+    const mine = own.map(collapse).filter((o) => wanted.length < o.length && o.includes(wanted));
+    if (0 === mine.length)
+        return tree.includes(goal);
+    return tree.split('\n').some((line) => {
+        let rest = collapse(line);
+        for (const o of mine) {
+            rest = rest.split(o).join('');
+            rest = withoutCutStart(rest, o, wanted.length);
+        }
+        return rest.includes(wanted);
+    });
+}
+/** `line` without each start of `own` the snapshot cut short with "…" (longer than `min`). */
+function withoutCutStart(line, own, min) {
+    let rest = line;
+    for (let at = rest.indexOf(CUT); -1 !== at; at = rest.indexOf(CUT, at + 1)) {
+        const before = rest.slice(0, at);
+        for (let n = Math.min(own.length, before.length); min < n; n -= 1) {
+            if (!before.endsWith(own.slice(0, n)))
+                continue;
+            rest = `${rest.slice(0, at - n)}${rest.slice(at + CUT.length)}`;
+            at -= n;
+            break;
+        }
+    }
+    return rest;
+}
+/** The end state a goal quotes: its last quoted text that it does not negate. */
+export function endOf(goal) {
+    return parseGoals(goal)
+        .filter((g) => true !== g.absent)
+        .at(-1)?.text;
+}
+/** The observable goals in a persona: whatever it quoted, each marked absent when it was negated. */
+export function parseGoals(persona) {
     if (persona === undefined)
         return [];
-    const found = [...persona.matchAll(QUOTED)].map((m) => (m[1] ?? m[2] ?? '').trim());
-    return [...new Set(found.filter((g) => 0 < g.length))].slice(0, MAX_GOALS);
+    const out = new Map();
+    for (const m of persona.matchAll(QUOTED)) {
+        const text = (m[1] ?? m[2] ?? '').trim();
+        if (0 === text.length || out.has(text))
+            continue;
+        const absent = NEGATED_BEFORE.test(persona.slice(0, m.index));
+        out.set(text, absent ? { text, absent } : { text });
+    }
+    return [...out.values()].slice(0, MAX_GOALS);
+}
+/** The texts a persona says must be on the page: the quoted goals it did not negate. */
+export function goalsIn(persona) {
+    return parseGoals(persona).flatMap((g) => (true === g.absent ? [] : [g.text]));
 }
 /**
  * Check each goal on the page the drive ended on, recording ONE assert for the drive.
  *
  * Each quote used to be its own assert, and every assert is a check in the drive's run, so a goal
  * that quotes where it starts ("from "Count is 0" to "Count is 1"") recorded a "no" for the start
- * text a working app had rightly replaced, and the run synced as a failing flow. The page is read
- * once to answer each quote; the one recorded assert covers the quotes shown, or all of them when
- * none is, so a goal the page never reached still leaves a failed check behind. A check that cannot
- * run is `unknown`, never skipped.
+ * text a working app had rightly replaced, and the run synced as a failing flow. The page is let
+ * settle, read once, and each goal is scrolled to by its text — one below the fold read `unknown`
+ * on a drive that never scrolled. The one recorded assert covers the goals found. A goal not found
+ * is undecided, not failed: nothing here knows the drive reached the page that would show it. A
+ * check that cannot run is `unknown`, never skipped.
  */
-export async function checkGoals(invoke, goals) {
-    const texts = [
-        ...new Set(goals.slice(0, MAX_GOALS).map((g) => g.trim().slice(0, MAX_GOAL_LENGTH))),
-    ].filter((t) => 0 < t.length);
-    if (0 === texts.length)
-        return [];
-    let page;
+export async function checkGoals(invoke, goals, 
+/** The page as it read before the drive: a goal it already showed proves nothing at the end. */
+opening, 
+/** Text the Harness wrote itself (its journey, its plan's and flows' names): never evidence. */
+own = []) {
+    const byText = new Map();
+    for (const goal of goals.slice(0, MAX_GOALS)) {
+        const g = 'string' === typeof goal ? { text: goal } : goal;
+        const text = g.text.trim().slice(0, MAX_GOAL_LENGTH);
+        if (0 < text.length && !byText.has(text))
+            byText.set(text, { ...g, text });
+    }
+    const all = [...byText.values()];
+    const before = new Set(all.filter((g) => true !== g.absent && true === opening?.includes(g.text)).map((g) => g.text));
+    const unchecked = (g, reason) => ({
+        text: g.text,
+        ...(true === g.absent ? { absent: true } : {}),
+        verified: Verified.UNKNOWN,
+        reason,
+    });
+    const todo = all.filter((g) => !before.has(g.text));
+    if (0 === todo.length)
+        return all.map((g) => unchecked(g, ALREADY_SHOWN));
+    await settle(invoke);
+    const page = await readOpening(invoke);
+    const found = new Set();
+    for (const g of todo) {
+        if (true === g.absent)
+            continue;
+        if ((await scrolledTo(invoke, g.text, own)) || shownByApp(page ?? '', g.text, own))
+            found.add(g.text);
+    }
+    const unreached = todo.some((g) => true !== g.absent && !found.has(g.text));
+    const absences = unreached ? [] : todo.filter((g) => true === g.absent);
+    const recorded = [...todo.filter((g) => found.has(g.text)), ...absences];
+    const verified = 0 < recorded.length ? await assertGoals(invoke, recorded) : Verified.UNKNOWN;
+    // One joint check that failed says only that SOMETHING did not hold: each goal is asked on its own,
+    // so a goal that held is not graded "no" for a neighbour that did not.
+    const each = new Map();
+    if (Verified.NO === verified && 1 < recorded.length)
+        for (const g of recorded)
+            each.set(g.text, await assertGoals(invoke, [g]));
+    const verdictOf = (g) => each.get(g.text) ?? verified;
+    return all.map((g) => {
+        if (before.has(g.text))
+            return unchecked(g, ALREADY_SHOWN);
+        if (true === g.absent) {
+            return unreached
+                ? unchecked(g, ABSENCE_UNREACHED)
+                : { text: g.text, absent: true, verified: verdictOf(g) };
+        }
+        if (!found.has(g.text))
+            return unchecked(g, NOT_REACHED);
+        // Seen on the page yet the text check says no: a field's value, or text the check cannot read.
+        return Verified.NO === verdictOf(g)
+            ? unchecked(g, SHOWN_NOT_HELD)
+            : { text: g.text, verified: verdictOf(g) };
+    });
+}
+/** The verdict of one assert over `goals`, or unknown when it could not be asked. */
+async function assertGoals(invoke, goals) {
+    try {
+        const result = asRecord(await invoke(ReticleTool.ASSERT, { predicate: allOf(goals) }));
+        return 'string' === typeof result['verified'] ? result['verified'] : Verified.UNKNOWN;
+    }
+    catch {
+        return Verified.UNKNOWN;
+    }
+}
+/**
+ * Whether the page shows `text` once it has settled, scrolled to if need be — how a person looks
+ * for something before saying it is not there. Records no check.
+ */
+export async function lookFor(invoke, text, 
+/** Text the Harness wrote itself: a match inside it is not the page showing the goal. */
+own = []) {
+    await settle(invoke);
+    if (shownByApp((await readOpening(invoke)) ?? '', text, own))
+        return true;
+    return scrolledTo(invoke, text, own);
+}
+/** Long enough for a lazy route to render; short enough that a page that never quiets costs little. */
+const SETTLE_MS = 3000;
+/** Scrolls spent looking for one goal: a long page, not an endless feed. */
+const GOAL_SCROLLS = 10;
+/** Let a page that is still changing finish, so a view still swapping in is not read half-drawn. */
+async function settle(invoke) {
+    try {
+        await invoke(ReticleTool.WAIT_FOR, {
+            predicate: { kind: PredicateKind.SETTLED },
+            timeout_ms: SETTLE_MS,
+            // From the session's start, not from this call: a request the drive's last click opened is
+            // in flight BEFORE this wait begins, and a window that starts now cannot see it. Driven over
+            // MCP: the drive ended on "Generating…", the page read as settled, and a journey whose end
+            // appeared a second later was failed. SETTLE_MS still bounds a request that never answers.
+            since: 0,
+        });
+    }
+    catch {
+        /* a page that never settles is still read as it stands */
+    }
+}
+/**
+ * Bring a goal's text into view, the way a person scrolls to it. True when it was found, and not
+ * inside text the Harness wrote itself.
+ */
+async function scrolledTo(invoke, text, own) {
+    try {
+        const result = asRecord(await invoke(ReticleTool.SCROLL_TO, {
+            by: QueryBy.TEXT,
+            value: text,
+            maxScrolls: GOAL_SCROLLS,
+        }));
+        const element = asRecord(result['element']);
+        const shown = element['text'] ?? element['name'];
+        return (true === result['found'] && !('string' === typeof shown && writtenByHarness(shown, text, own)));
+    }
+    catch {
+        return false;
+    }
+}
+const SNAPSHOT_FULL = 'full';
+/** The page as it reads now, or undefined when it cannot be read. Taken before a drive starts. */
+export async function readOpening(invoke) {
     try {
         const tree = asRecord(await invoke(ReticleTool.SNAPSHOT, { mode: SNAPSHOT_FULL }))['tree'];
-        if ('string' === typeof tree)
-            page = tree;
+        return 'string' === typeof tree ? tree : undefined;
     }
     catch {
-        /* unread: every quote rests on the assert below */
+        return undefined;
     }
-    const shown = texts.filter((t) => true === page?.includes(t));
-    const recorded = 0 < shown.length ? shown : texts;
+}
+function allOf(goals) {
+    const each = goals.map((g) => {
+        const shown = { kind: PredicateKind.TEXT, contains: g.text };
+        return true === g.absent ? { kind: PredicateKind.NOT, predicate: shown } : shown;
+    });
+    return 1 === each.length ? (each[0] ?? {}) : { kind: PredicateKind.ALL_OF, predicates: each };
+}
+/**
+ * The end state the caller declared, checked like any assert.
+ *
+ * Quoted text only proves some words are on the last page, which is how a drive that never used the
+ * app could pass: from the field, "it only checks that I have certain titles on my page". An `expect`
+ * names an OUTCOME — a route reached, a request made, state changed — in the same predicate grammar
+ * as reticle_assert, and is graded the same way. A check that cannot run is `unknown`.
+ */
+export async function checkExpect(invoke, predicate) {
     let verified = Verified.UNKNOWN;
     try {
-        const result = asRecord(await invoke(ReticleTool.ASSERT, { predicate: allOf(recorded) }));
+        const result = asRecord(await invoke(ReticleTool.ASSERT, { predicate }));
         if ('string' === typeof result['verified'])
             verified = result['verified'];
     }
     catch {
-        /* stays unknown: the goal was not proved */
+        /* stays unknown: the outcome was not proved */
     }
-    // A quote the page read did not show is a "no" only beside one it did: with none shown, every
-    // quote rests on the recorded assert.
-    return texts.map((text) => ({
-        text,
-        verified: 0 === shown.length || shown.includes(text) ? verified : Verified.NO,
-    }));
+    return { text: `expect ${JSON.stringify(predicate).slice(0, MAX_GOAL_LENGTH)}`, verified };
 }
-const SNAPSHOT_FULL = 'full';
-function allOf(texts) {
-    const each = texts.map((contains) => ({ kind: PredicateKind.TEXT, contains }));
-    return 1 === each.length ? (each[0] ?? {}) : { kind: PredicateKind.ALL_OF, predicates: each };
+/** Whether the drive met the goals it was given: undefined when it was given none. */
+export function goalsMet(checks) {
+    return 0 === checks.length ? undefined : checks.every((c) => Verified.YES === c.verified);
+}
+/**
+ * Whether the drive met its goal, as the answer and the run report it. The driver's own `goalMet`
+ * is its word, never evidence: a run answered `goalMet: true` after zero actions on a tab that
+ * already showed the end state, and another with both its goals `unknown`. With goals, met exactly
+ * when every one was proved; with none, the driver's word stands, and only after an action ran.
+ * Undefined when nothing judged it.
+ */
+export function goalOfDrive(claimed, checks, acted) {
+    // Proved goals are the evidence: a `yes` was not on the page before the drive (that reads
+    // already_true), so the run reached it, by the drive or by the hunt after it.
+    if (0 < checks.length)
+        return true === goalsMet(checks);
+    return claimed === undefined ? undefined : acted && claimed;
 }
 /** One line naming the goals the drive did not prove, or undefined when it proved them all. */
 export function unprovedGoals(checks) {
     const missed = checks.filter((c) => Verified.YES !== c.verified);
     if (0 === missed.length)
         return undefined;
-    return (`Not proved: ${missed.map((c) => `"${c.text}" (${c.verified})`).join(', ')}. ` +
+    return (`Not proved: ${missed.map((c) => `${true === c.absent ? 'no ' : ''}"${c.text}" (${c.reason ?? c.verified})`).join(', ')}. ` +
         'The drive did not finish the job it was given, whatever its own account says.');
 }
+/**
+ * The goals a drive is graded on: every quote, less a value the drive typed — an input, never
+ * evidence — except the journey's end (its last text to show), which stays even when typed: saving
+ * "Order 7" and then seeing it listed is the journey. Absence goals always stay.
+ */
+export function endGoalsOf(goals, typed) {
+    const end = goals.filter((g) => true !== g.absent).at(-1);
+    const inputs = new Set(typed.map((t) => t.trim()));
+    return goals.filter((g) => true === g.absent || g === end || !inputs.has(g.text.trim()));
+}

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

@@ -133,6 +133,8 @@ export interface HarnessResult {
      * held are not the goal reached: "open each section" passed on two presses of Sign in.
      */
     goalMet?: boolean;
+    /** The credits the platform says the drive spent; absent for a local model or an older platform. */
+    creditsSpent?: number;
 }
 /**
  * The answer to a `finish` that came before anything was proved. Sent once per drive: a real drive
@@ -140,6 +142,17 @@ export interface HarnessResult {
  * verifies nothing, which is the paid feature producing an empty pass.
  */
 export declare const MSG_FINISH_UNPROVED: string;
+/**
+ * The answer to a click repeated after it changed nothing. A persona drive clicked the logo four
+ * times on the page the logo leads to, each a wasted action and a wrong route guess.
+ */
+export declare const MSG_REPEAT_CHANGED_NOTHING: string;
+/**
+ * Said on a click whose route guess missed while it opened something on the page. A persona drive
+ * clicked the account button expecting to leave /overview; it opened a menu, the miss read as a
+ * failure, and the drive abandoned the route its plan named instead of choosing "Settings" in it.
+ */
+export declare const MSG_OPENED_IN_PLACE: string;
 /**
  * The one tool the harness adds to Reticle's surface.
  *
@@ -155,6 +168,22 @@ export interface HarnessOptions {
     focus?: string;
     /** How long one model turn may take. Injected so a test can prove the bound without waiting for it. */
     turnTimeoutMs?: number;
+    /** Asked before every turn: true ends the drive as STOPPED. Whoever started it may stop it. */
+    stopped?: () => boolean;
+    /** Asked before every turn: what somebody said to the drive since, handed over as user turns. */
+    inbox?: () => readonly string[];
+    /** The pages the app's map knows: named up front, and offered after a route guess misses. */
+    routes?: readonly string[];
+    /**
+     * The end the goal quotes, and the text the Harness wrote itself (never the app showing it): the
+     * drive stops once a check has held and the page shows it. Driven over MCP: a model that reached
+     * "Generated script for" kept going, navigated to a start page that signs the app out, and ended
+     * on a page without the result — a working journey failed by its own wandering.
+     */
+    endsAt?: {
+        readonly text: string;
+        readonly own: readonly string[];
+    };
 }
 export declare const DEFAULT_MAX_STEPS = 40;
 /**
@@ -170,7 +199,7 @@ export declare const DEFAULT_MAX_STEPS = 40;
  * deterministically for a few hundred tokens, forever. That is the whole economics of this feature,
  * so it is an instruction and not a hope.
  */
-export declare function systemPrompt(focus?: string): string;
+export declare function systemPrompt(focus?: string, routes?: readonly string[]): string;
 /**
  * Run the harness to completion.
  *

package/dist/features/harness/harness.js

@@ -17,8 +17,10 @@
  * 3. **Everything is injected** — the model, the tools, the clock. The loop below has no network in
  *    it, which is what lets the whole thing be tested against a scripted model with no API key.
  */
-import { ReticleTool, asRecord } from '@reticlehq/core';
+import { ReticleTool, Verified, WRITING_RULE, asRecord } from '@reticlehq/core';
+import { claimsOnlyRoute, knownPagesLine, routeHint } from './route-guess.js';
 import { withTimeout } from './with-timeout.js';
+import { lookFor } from './goals.js';
 /** Why a run stopped. Every one of these is a real outcome; none of them is an error. */
 export const StopReason = {
     /** The model called `finish` — it believes it is done. */
@@ -35,10 +37,14 @@ export const StopReason = {
 /** Thrown by a driver when a person, not a fault, ended the drive. */
 export class DriveStoppedError extends Error {
 }
-/** The finish's judgement of the goal, when it carried one. */
+/** The finish's judgement of the goal, and what the drive cost, when it carried them. */
 function goalMetOf(args) {
     const met = args['goalMet'];
-    return 'boolean' === typeof met ? { goalMet: met } : {};
+    const spent = args['creditsSpent'];
+    return {
+        ...('boolean' === typeof met ? { goalMet: met } : {}),
+        ...('number' === typeof spent ? { creditsSpent: spent } : {}),
+    };
 }
 /**
  * The answer to a `finish` that came before anything was proved. Sent once per drive: a real drive
@@ -48,6 +54,61 @@ function goalMetOf(args) {
 export const MSG_FINISH_UNPROVED = `Not finished: nothing has been proved yet. Before finishing, end the journey with ` +
     `${ReticleTool.ACT_AND_WAIT} and an \`until\` naming the end state it must reach, or ` +
     `${ReticleTool.ASSERT} on it. A drive that proves nothing replays as "verified nothing".`;
+/**
+ * The answer to a click repeated after it changed nothing. A persona drive clicked the logo four
+ * times on the page the logo leads to, each a wasted action and a wrong route guess.
+ */
+export const MSG_REPEAT_CHANGED_NOTHING = 'Not done again: the same action on the same control just changed nothing on the page — no ' +
+    'content, request, route or signal. Doing it again will not either. Look at the page and take ' +
+    'the next step the journey names.';
+/**
+ * Said on a click whose route guess missed while it opened something on the page. A persona drive
+ * clicked the account button expecting to leave /overview; it opened a menu, the miss read as a
+ * failure, and the drive abandoned the route its plan named instead of choosing "Settings" in it.
+ */
+export const MSG_OPENED_IN_PLACE = 'This click opened something on this page (a menu, a panel, a dialog) instead of going where you ' +
+    'guessed. That is progress, not a dead end: look at what it opened and act on the item the ' +
+    'journey names next.';
+/** A route-only guess that missed, on a click that added content: it opened something in place. */
+function openedInPlace(outcome) {
+    if (outcome.isError || ReticleTool.ACT_AND_WAIT !== outcome.name)
+        return false;
+    if (!claimsOnlyRoute(asRecord(outcome.args)['until']))
+        return false;
+    const result = asRecord(outcome.result);
+    if (Verified.YES === result['verified'])
+        return false;
+    const summary = asRecord(asRecord(result['trace'])['summary']);
+    return 0 < (Number(summary['domAdded']) || 0);
+}
+/** A route-only guess that missed: the known page to go to instead, when the map knows any. */
+function missedRouteHint(outcome, routes) {
+    if (outcome.isError || ReticleTool.ACT_AND_WAIT !== outcome.name)
+        return undefined;
+    const until = asRecord(outcome.args)['until'];
+    if (!claimsOnlyRoute(until) || Verified.YES === asRecord(outcome.result)['verified'])
+        return undefined;
+    return routeHint(until, routes);
+}
+/** The tools that act on one control, keyed by what they did to which control. */
+const ACTING_TOOLS = new Set([ReticleTool.ACT, ReticleTool.ACT_AND_WAIT]);
+/** What an action did to which control, or undefined for a call that does not act on one. */
+function actKey(name, args) {
+    if (!ACTING_TOOLS.has(name))
+        return undefined;
+    const target = args['ref'] ?? args['target'];
+    if (target === undefined)
+        return undefined;
+    return JSON.stringify([target, args['action'] ?? null, args['value'] ?? null]);
+}
+/** Whether a result's reaction digest says the page did nothing at all; undefined when it has none. */
+function changedNothing(result) {
+    const summary = asRecord(asRecord(asRecord(result)['trace'])['summary']);
+    if ('number' !== typeof summary['total'])
+        return undefined;
+    const moved = ['network', 'domAdded', 'domRemoved', 'domChanged', 'routeChanges', 'signals'].some((k) => 0 < (Number(summary[k]) || 0));
+    return !moved;
+}
 /** A check that ran: the only thing that turns a drive into evidence. */
 function isProof(outcome) {
     if (outcome.isError)
@@ -78,6 +139,10 @@ export const FINISH_TOOL = {
         additionalProperties: false,
     },
 };
+/** Why a drive ended before the model said so. */
+const msgReachedEnd = (end) => `Reached the end the goal names ("${end}") after a check held, so the drive stopped there.`;
+/** A check in this turn that came back yes: the moment worth looking for the end. */
+const heldCheck = (outcome) => isProof(outcome) && Verified.YES === asRecord(outcome.result)['verified'];
 export const DEFAULT_MAX_STEPS = 40;
 /**
  * How long a single model turn may take before the run gives up on it.
@@ -106,7 +171,7 @@ const OPENING = 'The app is loaded and connected. Begin by looking at the page,
  * deterministically for a few hundred tokens, forever. That is the whole economics of this feature,
  * so it is an instruction and not a hope.
  */
-export function systemPrompt(focus) {
+export function systemPrompt(focus, routes = []) {
     return [
         'You are driving a real web application through a verification tool, to find out whether it actually works.',
         '',
@@ -121,7 +186,9 @@ export function systemPrompt(focus) {
         'the app is broken underneath.',
         '',
         'Drive the app the way a user would: complete whole journeys, not single clicks. Submit the forms.',
-        'Follow the navigation. If something looks interactive, try it.',
+        'Follow the navigation. If something looks interactive, try it — unless the focus below says',
+        'not to: "without opening a run", "changes nothing" and the like bind the whole drive. Read the',
+        'list a journey says to read; do not open what it says to leave closed.',
         '',
         'RECORD WHAT YOU DRIVE. Before each journey call reticle_record { action: "start" }, drive it, then',
         'reticle_flow_save with a short descriptive name. A saved flow replays deterministically on every',
@@ -137,6 +204,14 @@ export function systemPrompt(focus) {
         'expectations as you go. Do not report bugs; drive the app.',
         '',
         'Call `finish` when you have covered the app or cannot get further.',
+        '',
+        WRITING_RULE,
+        ...(0 === routes.length
+            ? []
+            : [
+                '',
+                `Pages this app has: ${knownPagesLine(routes)}. To reach one, press its link or reticle_navigate to it; do not guess which control leads there.`,
+            ]),
         ...(focus === undefined ? [] : ['', `Focus for this run: ${focus}`]),
     ].join('\n');
 }
@@ -149,13 +224,29 @@ export function systemPrompt(focus) {
 export async function runHarness(driver, toolset, options = {}) {
     const maxSteps = options.maxSteps ?? DEFAULT_MAX_STEPS;
     const tools = [...toolset.tools, FINISH_TOOL];
-    const system = systemPrompt(options.focus);
+    const routes = options.routes ?? [];
+    const system = systemPrompt(options.focus, routes);
     const history = [{ role: 'user', text: OPENING }];
     const toolCalls = [];
     const usage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
     const proved = () => toolCalls.some(isProof);
     let askedToProve = false;
+    // Actions that just changed nothing; forgotten as soon as any action moves the page.
+    const inert = new Set();
     for (let step = 0; step < maxSteps; step += 1) {
+        if (true === options.stopped?.()) {
+            return {
+                stopReason: StopReason.STOPPED,
+                summary: '',
+                steps: step,
+                toolCalls,
+                usage,
+                proved: proved(),
+                goalMet: false,
+            };
+        }
+        for (const text of options.inbox?.() ?? [])
+            history.push({ role: 'user', text });
         let turn;
         try {
             turn = await withTimeout(driver.turn({ system, tools, history }), options.turnTimeoutMs ?? DEFAULT_TURN_TIMEOUT_MS, 'the model did not answer');
@@ -168,6 +259,9 @@ export async function runHarness(driver, toolset, options = {}) {
                 toolCalls,
                 usage,
                 proved: proved(),
+                // Cut off is not done: the checks that held before a refusal (credits gone, a 5xx) prove
+                // the steps before it, never the journey, and every verdict downstream reads this.
+                goalMet: false,
                 error: error instanceof Error ? error.message : String(error),
             };
         }
@@ -233,9 +327,49 @@ export async function runHarness(driver, toolset, options = {}) {
         // Every call the model asked for is answered, including ones that fail. A dropped result leaves
         // the model waiting on an answer that never comes, and it will usually re-ask — burning the
         // budget on a call that already ran, against an app it already changed.
-        const outcomes = await Promise.all(turn.calls.map((call) => invokeOne(toolset, call)));
+        const outcomes = await Promise.all(turn.calls.map((call) => {
+            const key = actKey(call.name, call.args);
+            return key !== undefined && inert.has(key)
+                ? Promise.resolve({
+                    id: call.id,
+                    name: call.name,
+                    args: call.args,
+                    result: { error: MSG_REPEAT_CHANGED_NOTHING },
+                    isError: true,
+                })
+                : invokeOne(toolset, call);
+        }));
+        for (const [i, outcome] of outcomes.entries()) {
+            const hint = openedInPlace(outcome) ? MSG_OPENED_IN_PLACE : missedRouteHint(outcome, routes);
+            if (hint !== undefined)
+                outcomes[i] = { ...outcome, result: { ...asRecord(outcome.result), next: hint } };
+        }
+        for (const outcome of outcomes) {
+            const key = actKey(outcome.name, outcome.args);
+            if (key === undefined || outcome.isError)
+                continue;
+            const nothing = changedNothing(outcome.result);
+            if (true === nothing)
+                inert.add(key);
+            else if (false === nothing)
+                inert.clear();
+        }
         toolCalls.push(...outcomes);
         history.push({ role: 'tool', outcomes });
+        const end = options.endsAt;
+        if (end !== undefined &&
+            outcomes.some(heldCheck) &&
+            (await lookFor((name, args) => toolset.invoke(name, args), end.text, end.own))) {
+            return {
+                stopReason: StopReason.FINISHED,
+                summary: msgReachedEnd(end.text),
+                steps: step + 1,
+                toolCalls,
+                usage,
+                proved: proved(),
+                goalMet: true,
+            };
+        }
     }
     return {
         stopReason: StopReason.BUDGET,