explorbot 0.5.3 → 0.5.4

package/boat/doc-collector/src/config.ts

@@ -171,6 +171,7 @@ interface DocbotConfig {
     minCanActions?: number;
     minInteractiveElements?: number;
     interactive?: boolean;
+    research?: 'light' | 'full';
   };
 }
 

package/boat/doc-collector/src/docbot.ts

@@ -118,9 +118,11 @@ class DocBot {
           }
         }
 
+        const light = this.useLightResearch();
         const research = await this.explorBot.agentResearcher().research(state, {
-          screenshot: this.shouldUseScreenshots(),
+          screenshot: !light && this.shouldUseScreenshots(),
           force: true,
+          light,
         });
         const pagePath = this.getPageFilePath(state.url);
         const captureState = this.shouldUseScreenshots()
@@ -221,6 +223,13 @@ class DocBot {
     return true;
   }
 
+  private useLightResearch(): boolean {
+    const research = this.config.docs?.research;
+    if (research === 'light') return true;
+    if (research === 'full') return false;
+    return this.config.docs?.interactive !== true;
+  }
+
   private shouldCollapseTemplates(override?: boolean): boolean {
     if (override === false) {
       return false;

package/boat/prima/src/envelope.ts

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
+import type { SettledExpectation } from '../../../src/test-plan.ts';
 
 export const STATUS_FILE = 'status.json';
 
@@ -26,16 +27,16 @@ export interface EnvelopeData {
   ok: boolean;
   command: string;
   used?: string[];
-  page: { url: string; previousUrl?: string; title: string; state: string; visits: number };
+  page: { url: string; previousUrl?: string; redirectedFrom?: string; title: string; state: string; visits: number };
   changes?: string | null;
   steps?: Array<{ label: string; ok: boolean; unconfirmed?: boolean; proof: string }>;
-  expectations?: Array<{ text: string; status: 'passed' | 'failed' | 'unverified' | 'contradiction'; evidence?: string }>;
+  expectations?: SettledExpectation[];
   warning?: string;
   stepFiles?: string;
   value?: string;
   answer?: string;
   research?: string;
-  assertions?: Array<{ code: string; passed: boolean; proof: string[] }>;
+  assertions?: Array<{ code: string; passed: boolean; proof: string[]; error?: string }>;
   failure?: { error: string; compactAria?: string };
   instance: InstanceInfo;
   status?: string;
@@ -88,12 +89,13 @@ function renderResult(data: EnvelopeData): string {
 }
 
 function renderPage(data: EnvelopeData): string {
-  const { url, previousUrl, title, state, visits } = data.page;
+  const { url, previousUrl, redirectedFrom, title, state, visits } = data.page;
   const urlLabel = `url: ${url}`;
   const stateLabel = `state: ${state}`;
   const width = Math.max(urlLabel.length, stateLabel.length) + 3;
   let changedMarker = '';
   if (previousUrl && previousUrl !== url) changedMarker = `(changed: ${previousUrl} → ${url})`;
+  if (redirectedFrom) changedMarker = `(redirected: ${redirectedFrom} → ${url})`;
   const lines = [align(urlLabel, changedMarker, width), `title: ${title}`, align(stateLabel, `(visit #${visits})`, width)];
   return section('Page', lines.join('\n'));
 }
@@ -129,7 +131,8 @@ function renderExpectations(data: EnvelopeData): string | null {
   const lines: string[] = [];
   data.expectations.forEach((expectation, index) => {
     lines.push(`${index + 1}. ${EXPECTATION_LABELS[expectation.status]} ${expectation.text}`);
-    if (expectation.status !== 'contradiction' && expectation.status !== 'failed') return;
+    if (expectation.resolution) lines.push(`      resolved: ${expectation.resolution}`);
+    if (!expectation.contradicted && !expectation.failed && !expectation.resolution) return;
     for (const line of (expectation.evidence || '').split('\n').filter(Boolean)) lines.push(`      ${line}`);
   });
   return section('Expected outcomes', lines.join('\n'));
@@ -153,7 +156,10 @@ function renderOutcome(data: EnvelopeData): string | null {
       .map((line) => line.trim())
       .filter((line) => line && !line.startsWith('//'))
       .join(' ');
-    return `${code}  => ${assertion.passed ? 'PASSED' : 'FAILED'}`;
+    if (assertion.passed) return `${code}  => PASSED`;
+    const reason = assertion.error?.split('\n').find(Boolean);
+    if (!reason) return `${code}  => FAILED`;
+    return `${code}  => FAILED\n      ${reason}`;
   });
 
   const proof = data.assertions.flatMap((assertion) => assertion.proof);

package/boat/prima/src/help.ts

@@ -27,8 +27,10 @@ export const checkHelp = dedent`
               ### Expected outcomes as PASSED, FAILED, CONTRADICTION or not verified.
               "not verified" means never checked, not false.
   Proof is a full-page screenshot: what a user sees counts, the log only shows actions.
-  CONTRADICTION means screenshot and log disagree; judge the html, aria and
-  screenshot under ### Artifacts yourself.
+  When screenshot and log disagree, the page structure breaks the tie: the outcome
+  becomes PASSED or FAILED with a "resolved:" line naming the side that was wrong.
+  CONTRADICTION remains when it cannot be broken, or when the page holds something
+  it does not display; judge the html, aria and screenshot under ### Artifacts yourself.
   ok is false when any outcome FAILED or CONTRADICTED, or the run could not finish,
   reported as such rather than as an app failure.
   Side issues found on the way go under ### Answer, not as step failures.

package/boat/prima/src/prima.ts

@@ -239,6 +239,10 @@ export class Prima {
 
     if (aiError) return this.failureEnvelope(command, aiError, previousState);
 
+    if (trace.length && ledger.some((entry) => entry.status === 'open')) {
+      await this.judgeUnreportedInstructions(ledger, trace);
+    }
+
     if (trace.length && ledger.some((entry) => entry.status === 'open')) {
       await this.settleLedger(conversation, provider, ledger, trace);
     }
@@ -310,6 +314,32 @@ export class Prima {
     return true;
   }
 
+  private async judgeUnreportedInstructions(ledger: LedgerEntry[], trace: Array<{ label: string; ok: boolean; proof: string }>): Promise<void> {
+    const judge = this.bot.judge?.();
+    if (!judge) return;
+
+    const current = this.bot.stateManager().getCurrentState();
+    let page = '';
+    if (current) page = ((await this.refAriaSnapshot(ActionResult.fromState(current))) || '').slice(0, JUDGE_PAGE_CAP);
+    const actions = trace
+      .map((step) => {
+        if (step.ok) return `ok ${step.label}`;
+        return `FAIL ${step.label}`;
+      })
+      .join('\n');
+    const state = { actions, finalUrl: current?.url || '', finalPage: page };
+
+    const open = ledger.filter((entry) => entry.status === 'open');
+    const decisions = await Promise.all(open.map((entry) => judge.decide(`The actions that ran and the final page show this instruction was carried out: ${entry.text}`, null, state)));
+
+    open.forEach((entry, index) => {
+      if (decisions[index].rejected) return;
+      entry.status = 'done';
+      entry.proof = 'judged from the actions that ran and the final page';
+      trace.push({ label: `done: ${entry.text}`, ok: true, proof: entry.proof });
+    });
+  }
+
   private async settleLedger(conversation: any, provider: any, ledger: LedgerEntry[], trace: Array<{ label: string; ok: boolean; proof: string }>): Promise<void> {
     conversation.addUserText(dedent`
       The run is over and these instructions were never reported:
@@ -376,8 +406,8 @@ export class Prima {
       envelope.warning = 'These outcomes were settled from the run log alone — no screenshot backed them. Set ai.visionModel, or check anything visual with prima ask.';
     }
 
-    const unreached = envelope.expectations.filter((expectation) => expectation.status === 'failed');
-    const contradicted = envelope.expectations.filter((expectation) => expectation.status === 'contradiction');
+    const unreached = envelope.expectations.filter((expectation) => expectation.failed);
+    const contradicted = envelope.expectations.filter((expectation) => expectation.contradicted);
     envelope.ok = !unreached.length && !contradicted.length;
 
     const problems = [...unreached.map((expectation) => `not reached: ${expectation.text}`), ...contradicted.map((expectation) => `the picture and the run disagree about: ${expectation.text}`)];
@@ -455,9 +485,10 @@ export class Prima {
     }
 
     let navigationError: unknown = null;
+    let arrived = true;
 
     try {
-      await this.bot.agentNavigator().visit(target);
+      arrived = await this.bot.agentNavigator().visit(target, { recover: !isUrl });
     } catch (error) {
       navigationError = error;
     }
@@ -467,7 +498,9 @@ export class Prima {
     const used: string[] = [];
     if (isUrl) used.push(code);
     const result = await this.capturedResult(this.bot.stateManager().getCurrentState());
-    return this.successEnvelope(command, used, result, previousState);
+    const envelope = await this.successEnvelope(command, used, result, previousState);
+    if (!arrived) envelope.page.redirectedFrom = target;
+    return envelope;
   }
 
   async browserStart(): Promise<void> {

package/boat/prima/src/session-log.ts

@@ -4,7 +4,7 @@ import { outputPath } from '../../../src/config.ts';
 import { safeFilename } from '../../../src/utils/strings.ts';
 import { type EnvelopeData, renderEnvelope } from './envelope.ts';
 
-const EXPECTATION_STATUS = { passed: 'passed', failed: 'failed', unverified: 'skipped' };
+const EXPECTATION_STATUS = { passed: 'passed', failed: 'failed', unverified: 'skipped', contradiction: 'failed' };
 
 export function sessionsDir(): string {
   return outputPath('prima', 'sessions');
@@ -74,7 +74,7 @@ function commandSteps(envelope: EnvelopeData): any[] {
 
   for (const expectation of envelope.expectations || []) {
     const entry: any = { category: 'user', title: `expected: ${expectation.text}`, status: EXPECTATION_STATUS[expectation.status], duration: 0 };
-    if (expectation.status === 'failed') entry.error = 'the run did not reach this outcome';
+    if (expectation.failed) entry.error = 'the run did not reach this outcome';
     steps.push(entry);
   }
 
@@ -82,7 +82,7 @@ function commandSteps(envelope: EnvelopeData): any[] {
     const entry: any = { category: 'user', title: assertion.code, status: 'passed', duration: 0, log: assertion.proof.join('\n') };
     if (!assertion.passed) {
       entry.status = 'failed';
-      entry.error = 'the assertion did not hold on the page';
+      entry.error = assertion.error || 'the assertion did not hold on the page';
     }
     steps.push(entry);
   }

package/dist/boat/doc-collector/src/docbot.js

@@ -103,9 +103,11 @@ class DocBot {
                         continue;
                     }
                 }
+                const light = this.useLightResearch();
                 const research = await this.explorBot.agentResearcher().research(state, {
-                    screenshot: this.shouldUseScreenshots(),
+                    screenshot: !light && this.shouldUseScreenshots(),
                     force: true,
+                    light,
                 });
                 const pagePath = this.getPageFilePath(state.url);
                 const captureState = this.shouldUseScreenshots()
@@ -197,6 +199,14 @@ class DocBot {
         }
         return true;
     }
+    useLightResearch() {
+        const research = this.config.docs?.research;
+        if (research === 'light')
+            return true;
+        if (research === 'full')
+            return false;
+        return this.config.docs?.interactive !== true;
+    }
     shouldCollapseTemplates(override) {
         if (override === false) {
             return false;

package/dist/boat/prima/src/envelope.js

@@ -52,13 +52,15 @@ function renderResult(data) {
     return section('Result', lines.join('\n'));
 }
 function renderPage(data) {
-    const { url, previousUrl, title, state, visits } = data.page;
+    const { url, previousUrl, redirectedFrom, title, state, visits } = data.page;
     const urlLabel = `url: ${url}`;
     const stateLabel = `state: ${state}`;
     const width = Math.max(urlLabel.length, stateLabel.length) + 3;
     let changedMarker = '';
     if (previousUrl && previousUrl !== url)
         changedMarker = `(changed: ${previousUrl} → ${url})`;
+    if (redirectedFrom)
+        changedMarker = `(redirected: ${redirectedFrom} → ${url})`;
     const lines = [align(urlLabel, changedMarker, width), `title: ${title}`, align(stateLabel, `(visit #${visits})`, width)];
     return section('Page', lines.join('\n'));
 }
@@ -96,7 +98,9 @@ function renderExpectations(data) {
     const lines = [];
     data.expectations.forEach((expectation, index) => {
         lines.push(`${index + 1}. ${EXPECTATION_LABELS[expectation.status]} ${expectation.text}`);
-        if (expectation.status !== 'contradiction' && expectation.status !== 'failed')
+        if (expectation.resolution)
+            lines.push(`      resolved: ${expectation.resolution}`);
+        if (!expectation.contradicted && !expectation.failed && !expectation.resolution)
             return;
         for (const line of (expectation.evidence || '').split('\n').filter(Boolean))
             lines.push(`      ${line}`);
@@ -123,7 +127,12 @@ function renderOutcome(data) {
             .map((line) => line.trim())
             .filter((line) => line && !line.startsWith('//'))
             .join(' ');
-        return `${code}  => ${assertion.passed ? 'PASSED' : 'FAILED'}`;
+        if (assertion.passed)
+            return `${code}  => PASSED`;
+        const reason = assertion.error?.split('\n').find(Boolean);
+        if (!reason)
+            return `${code}  => FAILED`;
+        return `${code}  => FAILED\n      ${reason}`;
     });
     const proof = data.assertions.flatMap((assertion) => assertion.proof);
     if (proof.length)

package/dist/boat/prima/src/help.js

@@ -25,8 +25,10 @@ export const checkHelp = dedent `
               ### Expected outcomes as PASSED, FAILED, CONTRADICTION or not verified.
               "not verified" means never checked, not false.
   Proof is a full-page screenshot: what a user sees counts, the log only shows actions.
-  CONTRADICTION means screenshot and log disagree; judge the html, aria and
-  screenshot under ### Artifacts yourself.
+  When screenshot and log disagree, the page structure breaks the tie: the outcome
+  becomes PASSED or FAILED with a "resolved:" line naming the side that was wrong.
+  CONTRADICTION remains when it cannot be broken, or when the page holds something
+  it does not display; judge the html, aria and screenshot under ### Artifacts yourself.
   ok is false when any outcome FAILED or CONTRADICTED, or the run could not finish,
   reported as such rather than as an app failure.
   Side issues found on the way go under ### Answer, not as step failures.

package/dist/boat/prima/src/prima.js

@@ -220,6 +220,9 @@ export class Prima {
         }
         if (aiError)
             return this.failureEnvelope(command, aiError, previousState);
+        if (trace.length && ledger.some((entry) => entry.status === 'open')) {
+            await this.judgeUnreportedInstructions(ledger, trace);
+        }
         if (trace.length && ledger.some((entry) => entry.status === 'open')) {
             await this.settleLedger(conversation, provider, ledger, trace);
         }
@@ -283,6 +286,32 @@ export class Prima {
         }
         return true;
     }
+    async judgeUnreportedInstructions(ledger, trace) {
+        const judge = this.bot.judge?.();
+        if (!judge)
+            return;
+        const current = this.bot.stateManager().getCurrentState();
+        let page = '';
+        if (current)
+            page = ((await this.refAriaSnapshot(ActionResult.fromState(current))) || '').slice(0, JUDGE_PAGE_CAP);
+        const actions = trace
+            .map((step) => {
+            if (step.ok)
+                return `ok ${step.label}`;
+            return `FAIL ${step.label}`;
+        })
+            .join('\n');
+        const state = { actions, finalUrl: current?.url || '', finalPage: page };
+        const open = ledger.filter((entry) => entry.status === 'open');
+        const decisions = await Promise.all(open.map((entry) => judge.decide(`The actions that ran and the final page show this instruction was carried out: ${entry.text}`, null, state)));
+        open.forEach((entry, index) => {
+            if (decisions[index].rejected)
+                return;
+            entry.status = 'done';
+            entry.proof = 'judged from the actions that ran and the final page';
+            trace.push({ label: `done: ${entry.text}`, ok: true, proof: entry.proof });
+        });
+    }
     async settleLedger(conversation, provider, ledger, trace) {
         conversation.addUserText(dedent `
       The run is over and these instructions were never reported:
@@ -343,8 +372,8 @@ export class Prima {
         if (!result.screenshot || !this.visionEnabled()) {
             envelope.warning = 'These outcomes were settled from the run log alone — no screenshot backed them. Set ai.visionModel, or check anything visual with prima ask.';
         }
-        const unreached = envelope.expectations.filter((expectation) => expectation.status === 'failed');
-        const contradicted = envelope.expectations.filter((expectation) => expectation.status === 'contradiction');
+        const unreached = envelope.expectations.filter((expectation) => expectation.failed);
+        const contradicted = envelope.expectations.filter((expectation) => expectation.contradicted);
         envelope.ok = !unreached.length && !contradicted.length;
         const problems = [...unreached.map((expectation) => `not reached: ${expectation.text}`), ...contradicted.map((expectation) => `the picture and the run disagree about: ${expectation.text}`)];
         if (problems.length)
@@ -413,8 +442,9 @@ export class Prima {
                 return judged;
         }
         let navigationError = null;
+        let arrived = true;
         try {
-            await this.bot.agentNavigator().visit(target);
+            arrived = await this.bot.agentNavigator().visit(target, { recover: !isUrl });
         }
         catch (error) {
             navigationError = error;
@@ -425,7 +455,10 @@ export class Prima {
         if (isUrl)
             used.push(code);
         const result = await this.capturedResult(this.bot.stateManager().getCurrentState());
-        return this.successEnvelope(command, used, result, previousState);
+        const envelope = await this.successEnvelope(command, used, result, previousState);
+        if (!arrived)
+            envelope.page.redirectedFrom = target;
+        return envelope;
     }
     async browserStart() {
         const config = await this.loadConfig();

package/dist/boat/prima/src/session-log.js

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { outputPath } from "../../../src/config.js";
 import { safeFilename } from "../../../src/utils/strings.js";
 import { renderEnvelope } from "./envelope.js";
-const EXPECTATION_STATUS = { passed: 'passed', failed: 'failed', unverified: 'skipped' };
+const EXPECTATION_STATUS = { passed: 'passed', failed: 'failed', unverified: 'skipped', contradiction: 'failed' };
 export function sessionsDir() {
     return outputPath('prima', 'sessions');
 }
@@ -64,7 +64,7 @@ function commandSteps(envelope) {
     }
     for (const expectation of envelope.expectations || []) {
         const entry = { category: 'user', title: `expected: ${expectation.text}`, status: EXPECTATION_STATUS[expectation.status], duration: 0 };
-        if (expectation.status === 'failed')
+        if (expectation.failed)
             entry.error = 'the run did not reach this outcome';
         steps.push(entry);
     }
@@ -72,7 +72,7 @@ function commandSteps(envelope) {
         const entry = { category: 'user', title: assertion.code, status: 'passed', duration: 0, log: assertion.proof.join('\n') };
         if (!assertion.passed) {
             entry.status = 'failed';
-            entry.error = 'the assertion did not hold on the page';
+            entry.error = assertion.error || 'the assertion did not hold on the page';
         }
         steps.push(entry);
     }

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",

package/dist/rules/navigator/output.md

@@ -1,11 +1,11 @@
 <rules>
-Do not invent locators, focus only on locators from HTML PAGE.
+Do not invent locators, focus only on locators from the <page> context.
 Provide up to {{maxAttempts}} various code suggestions to achieve the result.
 If there was already successful solution in <experience> use it as a first solution.
 
 If no successful solution was found in <experience> propose codeblocks for each area that can help to achieve the result.
 Do not stick only to the first found element as it might be hidden or not availble on the page.
-If you think HTML contains several areas that can help to achieve the result, propose codeblocks for each such area.
+If you think the page contains several areas that can help to achieve the result, propose codeblocks for each such area.
 Use exact locators that can pick the elements from each areas.
 Detect such duplicated areas by looking for duplicate IDs, data-ids, forms, etc.
 
@@ -24,7 +24,7 @@ Your response must start explanation of what you are going to do to achive the r
 It is important to explain intention before proposing code.
 Response must also valid CodeceptJS code in code blocks.
 Propose codeblock from successful solutions in <experience> first if they exist.
-Use only locators from HTML PAGE that was passed in <page> context.
+Use only locators from the <page> context.
 </output>
 
 

package/dist/src/action.js

@@ -548,6 +548,10 @@ export const attachStepLogger = (target, assertionsTarget) => {
         if (batchFailed)
             return;
         const executed = { command: step.toCode(), success: !error };
+        if (Object.keys(step.opts || {}).length) {
+            const args = [step.humanizeArgs(), `step.opts(${JSON.stringify(step.opts)})`].filter(Boolean).join(', ');
+            executed.command = `${step.prefix}${step.actor}.${step.title}(${args})${step.suffix}`;
+        }
         if (error) {
             executed.error = errorToString(error);
             batchFailed = true;

package/dist/src/ai/driller.js

@@ -6,6 +6,7 @@ import { setActivity } from "../activity.js";
 import { Observability } from "../observability.js";
 import { Plan, Test, TestResult } from "../test-plan.js";
 import { collectInteractiveNodes } from "../utils/aria.js";
+import { splitTopLevel } from "../utils/code-extractor.js";
 import { EXPLORBOT_ATTRS, HTML_COMPOSITE_AREA_HINTS, HTML_COMPOSITE_TARGET_ROLES, HTML_EXTRACTION_LIMITS, HTML_FORM_CONTROL_ROLES, HTML_FORM_CONTROL_TAGS, HTML_INTERACTIVE_ROLES, HTML_SELECTORS, getComponentScopeHtmlExtractorSource, inferHtmlRole } from "../utils/html.js";
 import { createDebug, tag } from "../utils/logger.js";
 import { loop, pause } from "../utils/loop.js";
@@ -933,34 +934,7 @@ function countTopLevelArgCount(line) {
     const end = line.lastIndexOf(')');
     if (start === -1 || end === -1 || end <= start + 1)
         return 0;
-    const body = line.slice(start + 1, end);
-    let count = 1;
-    let depth = 0;
-    let quote = '';
-    for (let i = 0; i < body.length; i++) {
-        const char = body[i];
-        const escaped = body[i - 1] === '\\';
-        if (quote) {
-            if (char === quote && !escaped)
-                quote = '';
-            continue;
-        }
-        if (char === '"' || char === "'" || char === '`') {
-            quote = char;
-            continue;
-        }
-        if (char === '(' || char === '[' || char === '{') {
-            depth++;
-            continue;
-        }
-        if (char === ')' || char === ']' || char === '}') {
-            depth = Math.max(0, depth - 1);
-            continue;
-        }
-        if (char === ',' && depth === 0)
-            count++;
-    }
-    return count;
+    return splitTopLevel(line.slice(start + 1, end), ',').length;
 }
 function buildClassSelector(tag, classes) {
     const safeClasses = classes.filter((cls) => /^[a-z0-9_-]+$/i.test(cls)).slice(0, 5);

package/dist/src/ai/navigator.d.ts

@@ -35,8 +35,10 @@ declare class Navigator implements Agent {
     }, expectedUrl: string): string;
     isSameExpectedOrigin(expectedUrl: string, stateManager: any): boolean;
     isOnExpectedPage(expectedUrl: string, stateManager: any): boolean;
-    visit(url: string): Promise<void>;
-    visitOnce(url: string): Promise<void>;
+    visit(url: string, opts?: {
+        recover?: boolean;
+    }): Promise<boolean>;
+    visitOnce(url: string, recover: boolean): Promise<boolean>;
     navigationError(url: string, fallback: string): Error;
     failureReason(stopReason: string | null, knowledge: string, url: string): string | null;
     resolveState(message: string, actionResult: ActionResult, opts?: {
@@ -98,5 +100,6 @@ export type AssertionResult = {
     code: string;
     passed: boolean;
     proof: string[];
+    error?: string;
 };
 export { Navigator };

package/dist/src/ai/navigator.js

@@ -119,10 +119,10 @@ class Navigator {
         const currentUrl = this.getComparableCurrentUrl(stateManager, expectedUrl);
         return matchesNavigationUrl(expectedUrl, currentUrl);
     }
-    async visit(url) {
-        return this.visitOnce(url);
+    async visit(url, opts = {}) {
+        return this.visitOnce(url, opts.recover !== false);
     }
-    async visitOnce(url) {
+    async visitOnce(url, recover) {
         try {
             const action = this.explorer.action();
             await action.execute(`I.amOnPage('${url}')`);
@@ -131,7 +131,10 @@ class Navigator {
                 throw new Error(`Navigation to "${url}" opened an empty page. The target must be a valid URL path starting with "/".`);
             }
             await this.hooksRunner.runBeforeHook('navigator', url);
-            if (!this.isOnExpectedPage(url, action.stateManager)) {
+            if (!recover && action.lastError)
+                throw new Error(`Navigation to ${url} failed: ${action.lastError.message}`);
+            const arrived = this.isOnExpectedPage(url, action.stateManager);
+            if (recover && !arrived) {
                 const actualPath = action.stateManager.getCurrentState()?.url || '';
                 const actionResult = action.actionResult || ActionResult.fromState(action.stateManager.getCurrentState());
                 const originalMessage = `Navigate to: ${url}. Current page: ${actualPath}`;
@@ -154,6 +157,7 @@ class Navigator {
             }
             await this.explorer.capture({ screenshot: true });
             await this.hooksRunner.runAfterHook('navigator', url);
+            return arrived || recover;
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : String(error);
@@ -252,7 +256,7 @@ class Navigator {
                     return;
                 }
                 tag('operation').log('Feeding failures back to AI for a new batch...');
-                conversation.addUserText(await this.buildRetryFeedback(batchFailures, !htmlContextAdded, actionResult));
+                conversation.addUserText(await this.buildRetryFeedback(batchFailures, !htmlContextAdded, action.actionResult ?? actionResult));
                 htmlContextAdded = true;
                 codeBlocks = [];
                 batchFailures.length = 0;
@@ -347,10 +351,6 @@ class Navigator {
 
       <page>
         ${actionResult.toAiContext()}
-
-        <page_html>
-        ${await actionResult.combinedHtml()}
-        </page_html>
       </page>
 
       <task>
@@ -360,6 +360,8 @@ class Navigator {
         Propose different solutions to achieve the result.
         Solution should be valid CodeceptJS code.
         Use only data from the <page> context to plan the solution.
+        The page is given as an ARIA snapshot only: use ARIA and text locators from it.
+        Full HTML is provided if these solutions fail.
         Try various ways to achieve the result
       </task>
 
@@ -722,7 +724,10 @@ class Navigator {
                 await action.exitIframe();
                 const verified = await action.attempt(codeBlock, message);
                 const proof = action.assertionSteps.map(renderAssertion).filter(Boolean);
-                results.push({ code: codeBlock, passed: verified, proof });
+                const result = { code: codeBlock, passed: verified, proof };
+                if (!verified && action.lastError)
+                    result.error = action.lastError.message;
+                results.push(result);
                 if (verified) {
                     tag('success').log('Verification passed');
                     successfulCodes.push(codeBlock);

package/dist/src/ai/pilot.d.ts

@@ -3,7 +3,7 @@ import type { RequestStore } from '../api/request-store.js';
 import type Explorer from '../explorer.js';
 import type { PlaywrightRecorder } from '../playwright-recorder.js';
 import type { StateManager } from '../state-manager.js';
-import { type Test } from '../test-plan.js';
+import { SettledExpectation, type SettledStatus, type Test } from '../test-plan.js';
 import type { Agent, AgentDeps } from './agent.js';
 import type { Conversation } from './conversation.js';
 import type { Fisherman } from './fisherman.js';
@@ -44,6 +44,7 @@ export declare class Pilot implements Agent {
     periodicAnalyzeProgress(task: Test, currentState: ActionResult, testerConversation: Conversation): Promise<string>;
     analyzeProgress(task: Test, currentState: ActionResult, testerConversation: Conversation): Promise<string>;
     settleExpectations(task: Test, finalState?: ActionResult): Promise<SettledExpectation[]>;
+    resolveContradictions(outcomes: SettledExpectation[], finalState?: ActionResult): Promise<SettledExpectation[]>;
     settleByJudge(task: Test, expectations: string[]): Promise<Map<string, SettledStatus>>;
     formatExpectations(task: Test): string;
     sendToPilot(userText: string, functionId: string, opts: {
@@ -104,9 +105,3 @@ export declare class Pilot implements Agent {
     formatActions(toolCalls: any[]): string;
     getSystemPrompt(task: Test, initialState: ActionResult): string;
 }
-export type SettledStatus = 'passed' | 'failed' | 'unverified' | 'contradiction';
-export interface SettledExpectation {
-    text: string;
-    status: SettledStatus;
-    evidence?: string;
-}