explorbot 0.5.2 → 0.5.4

package/dist/src/test-plan.js

@@ -41,6 +41,27 @@ export class ActiveNote {
         return this.startTime;
     }
 }
+export class SettledExpectation {
+    text;
+    status;
+    evidence;
+    resolution;
+    constructor(text, status, evidence, resolution) {
+        this.text = text;
+        this.status = status;
+        this.evidence = evidence;
+        this.resolution = resolution;
+    }
+    get failed() {
+        return this.status === 'failed';
+    }
+    get contradicted() {
+        return this.status === 'contradiction';
+    }
+    resolve(status, resolution) {
+        return new SettledExpectation(this.text, status, this.evidence, resolution);
+    }
+}
 export class Task {
     id;
     description;

package/dist/src/utils/code-extractor.d.ts

@@ -1 +1,2 @@
 export declare function extractCodeBlocks(aiResponse: string): string[];
+export declare function splitTopLevel(code: string, separator: string): string[];

package/dist/src/utils/code-extractor.js

@@ -1,6 +1,9 @@
 import { createDebug } from './logger.js';
 const debugLog = createDebug('explorbot:code-extractor');
 const JS_LANGUAGES = new Set(['', 'js', 'javascript']);
+const QUOTES = ["'", '"', '`'];
+const OPENING_BRACKETS = ['(', '[', '{'];
+const CLOSING_BRACKETS = [')', ']', '}'];
 export function extractCodeBlocks(aiResponse) {
     const codeBlockRegex = /```([^\n`]*)\n([\s\S]*?)\n```/g;
     const codeBlocks = [];
@@ -22,3 +25,40 @@ export function extractCodeBlocks(aiResponse) {
     }
     return codeBlocks;
 }
+export function splitTopLevel(code, separator) {
+    const parts = [];
+    let current = '';
+    let depth = 0;
+    let quote = '';
+    for (let i = 0; i < code.length; i++) {
+        const char = code[i];
+        if (quote) {
+            current += char;
+            if (char === '\\')
+                current += code[++i] || '';
+            if (char === quote)
+                quote = '';
+            continue;
+        }
+        if (char === '/' && code[i + 1] === '/') {
+            while (i + 1 < code.length && code[i + 1] !== '\n')
+                i++;
+            continue;
+        }
+        if (char === separator && depth <= 0) {
+            parts.push(current);
+            current = '';
+            depth = 0;
+            continue;
+        }
+        current += char;
+        if (QUOTES.includes(char))
+            quote = char;
+        if (OPENING_BRACKETS.includes(char))
+            depth++;
+        if (CLOSING_BRACKETS.includes(char))
+            depth--;
+    }
+    parts.push(current);
+    return parts;
+}

package/dist/src/utils/html.d.ts

@@ -5,6 +5,7 @@ export declare const EXPLORBOT_ATTRS: {
     readonly coveredBy: "data-explorbot-covered-by";
     readonly context: "data-explorbot-context";
     readonly eidx: "data-explorbot-eidx";
+    readonly hidden: "data-explorbot-hidden";
     readonly hit: "data-explorbot-hit";
     readonly variant: "data-explorbot-variant";
 };
@@ -40,6 +41,7 @@ export declare const ELEMENT_EXTRACTION_CONFIG: {
         readonly coveredBy: "data-explorbot-covered-by";
         readonly context: "data-explorbot-context";
         readonly eidx: "data-explorbot-eidx";
+        readonly hidden: "data-explorbot-hidden";
         readonly hit: "data-explorbot-hit";
         readonly variant: "data-explorbot-variant";
     };

package/dist/src/utils/html.js

@@ -70,6 +70,7 @@ export const EXPLORBOT_ATTRS = {
     coveredBy: 'data-explorbot-covered-by',
     context: 'data-explorbot-context',
     eidx: 'data-explorbot-eidx',
+    hidden: 'data-explorbot-hidden',
     hit: 'data-explorbot-hit',
     variant: 'data-explorbot-variant',
 };
@@ -159,6 +160,20 @@ export function captureHtmlForSnapshot() {
                 .join(','));
         }
     }
+    const liveElements = Array.from(document.body?.querySelectorAll('*') || []);
+    const clonedElements = Array.from(clone.querySelector('body')?.querySelectorAll('*') || []);
+    for (let i = 0; i < liveElements.length; i++) {
+        const source = liveElements[i];
+        if (source.matches('input, textarea, select, option, optgroup'))
+            continue;
+        if (source.checkVisibility())
+            continue;
+        if (!source.parentElement?.checkVisibility())
+            continue;
+        if (getComputedStyle(source).display === 'contents')
+            continue;
+        clonedElements[i]?.setAttribute('data-explorbot-hidden', 'true');
+    }
     return clone.outerHTML;
 }
 export function extractElementData(el, config) {
@@ -1347,7 +1362,27 @@ function getAttribute(element, name) {
     const attr = element.attrs.find((a) => a.name === name);
     return attr?.value;
 }
+function getImgAlt(element) {
+    let alt = '';
+    function processNode(node) {
+        if (alt)
+            return;
+        if ('tagName' in node) {
+            const el = node;
+            if (el.tagName.toLowerCase() === 'img') {
+                alt = getAttribute(el, 'alt') || '';
+                return;
+            }
+        }
+        if ('childNodes' in node)
+            node.childNodes.forEach(processNode);
+    }
+    processNode(element);
+    return alt;
+}
 function hasHiddenClass(element) {
+    if (getAttribute(element, EXPLORBOT_ATTRS.hidden))
+        return true;
     const classAttr = element.attrs.find((attr) => attr.name === 'class');
     if (!classAttr)
         return false;
@@ -1393,7 +1428,7 @@ export function extractLinks(html) {
                 if (href) {
                     const shouldSkip = skipPrefixes.some((prefix) => href.startsWith(prefix));
                     if (!shouldSkip) {
-                        const rawTitle = getAttribute(element, 'aria-label') || getTextContent(element);
+                        const rawTitle = getAttribute(element, 'aria-label') || getTextContent(element) || getImgAlt(element);
                         const title = sanitizeLinkTitle(rawTitle);
                         if (title && title.length <= 100) {
                             const key = `${href}|${title}`;

package/dist/src/utils/mdq/cli.js

@@ -5,7 +5,7 @@ const EDIT_FLAGS = ['remove', 'replace', 'insertBefore', 'insertAfter', 'prepend
 export async function runMdq(argv, readStdin) {
     const program = new Command();
     program
-        .name('mdq')
+        .name('mdq-cli')
         .description('query and edit markdown')
         .argument('[selector]', 'markdown selector')
         .argument('[file]', 'file to read; stdin when omitted')
@@ -29,6 +29,8 @@ export async function runMdq(argv, readStdin) {
         program.parse(argv, { from: 'user' });
     }
     catch (error) {
+        if (error.code === 'commander.helpDisplayed')
+            return { output: program.helpInformation(), code: 0 };
         return { output: String(error.message), code: 2 };
     }
     const options = program.opts();

package/dist/src/utils/test-files.d.ts

@@ -1,4 +1,9 @@
 export declare function listTestFiles(testsDir: string): string[];
+/**
+ * Generated tests import `codeceptjs/steps`, but in global mode they lie in ~/.explorbot,
+ * far from any node_modules. Link the bot's own codeceptjs next to them so Node resolves it.
+ */
+export declare function ensureCodeceptResolvable(dir: string): void;
 export declare function loadTestSuites(testsDir: string): any[];
 export declare function printTestList(suites: any[]): void;
 export declare function dryRunTestFile(filePath: string): Promise<void>;

package/dist/src/utils/test-files.js

@@ -1,4 +1,5 @@
-import { existsSync, readdirSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, symlinkSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import path from 'node:path';
 import chalk from 'chalk';
 import { highlight } from 'cli-highlight';
@@ -8,6 +9,7 @@ import storeListener from 'codeceptjs/lib/listener/store';
 import store from 'codeceptjs/lib/store';
 import figureSet from 'figures';
 import { ConfigParser } from "../config.js";
+const nodeRequire = createRequire(import.meta.url);
 export function listTestFiles(testsDir) {
     if (!existsSync(testsDir))
         return [];
@@ -15,10 +17,34 @@ export function listTestFiles(testsDir) {
         .filter((f) => f.endsWith('.js'))
         .map((f) => path.resolve(testsDir, f));
 }
+/**
+ * Generated tests import `codeceptjs/steps`, but in global mode they lie in ~/.explorbot,
+ * far from any node_modules. Link the bot's own codeceptjs next to them so Node resolves it.
+ */
+export function ensureCodeceptResolvable(dir) {
+    const link = path.join(dir, 'node_modules', 'codeceptjs');
+    if (existsSync(link))
+        return;
+    let target;
+    try {
+        target = path.dirname(nodeRequire.resolve('codeceptjs/package.json'));
+    }
+    catch {
+        return;
+    }
+    try {
+        mkdirSync(path.dirname(link), { recursive: true });
+        symlinkSync(target, link, process.platform === 'win32' ? 'junction' : 'dir');
+    }
+    catch {
+        // Best effort: a project install already resolves codeceptjs without the link.
+    }
+}
 export function loadTestSuites(testsDir) {
     const jsFiles = listTestFiles(testsDir);
     if (jsFiles.length === 0)
         return [];
+    ensureCodeceptResolvable(testsDir);
     codeceptjs.container.createMocha();
     const mocha = codeceptjs.container.mocha();
     mocha.files = jsFiles;
@@ -79,6 +105,7 @@ export async function dryRunTestFile(filePath) {
     const mocha = codeceptjs.container.mocha();
     mocha.reporter(class {
     });
+    ensureCodeceptResolvable(path.dirname(absPath));
     mocha.files = [absPath];
     mocha.loadFiles();
     let currentSuite = '';

package/dist/src/utils/web-sandbox.js

@@ -1,16 +1,16 @@
 import { faker } from '@faker-js/faker';
 import { hopeThat, retryTo, tryTo, within } from 'codeceptjs/lib/effects';
 import step from 'codeceptjs/steps';
+import { splitTopLevel } from "./code-extractor.js";
 const SHADOWED_GLOBALS = ['process', 'global', 'globalThis', 'fetch', 'Bun', 'require', 'module', 'exports'];
 const ALLOWED_COMMAND_HEADS = ['I.', 'page.', 'await page.', 'await I.'];
 const PLAYWRIGHT_COMMAND_HEADS = ['page.', 'await page.'];
 const PLAYWRIGHT_ARG_NAMES = ['page'];
 const CODECEPT_ARG_NAMES = ['I', 'tryTo', 'retryTo', 'within', 'hopeThat', 'step', 'faker'];
 export function sanitizeCodeBlock(code) {
-    return code
-        .split('\n')
-        .map((line) => line.trim())
-        .filter((line) => ALLOWED_COMMAND_HEADS.some((head) => line.startsWith(head)))
+    return splitTopLevel(code, '\n')
+        .map((statement) => statement.trim())
+        .filter((statement) => ALLOWED_COMMAND_HEADS.some((head) => statement.startsWith(head)))
         .join('\n');
 }
 export function hasPlaywrightCommands(code) {

package/docs/doc-collection/basics.md

@@ -21,6 +21,19 @@ The collector starts at the path you give it. For each page it:
 
 It repeats this until the queue is empty or the page budget is spent. Only same-origin links are followed.
 
+## Research depth
+
+In static mode the Researcher runs in a **light, single pass**: one AI call maps the sections and interactive elements, and the locator validation, repair conversations, and screenshot annotation passes of a full research run are skipped. Docs describe pages rather than click them, so unverified locators are a fair trade for roughly one AI call per page.
+
+Interactive mode needs locators it can actually click, so it keeps the full pipeline: every locator is validated in the browser, broken ones get fixed, and a vision pass adds coordinates. Override the automatic choice with `research`:
+
+```ts
+docs: {
+  research: 'full', // always run the verified pipeline
+  // research: 'light', // single pass even in interactive mode
+}
+```
+
 ## Configure
 
 The collector runs on your regular Explorbot setup — the AI provider and browser come from `explorbot.config.js` (see [configuration](../reference/configuration.md)). Crawl behavior lives in a separate file: `docbot.config.ts` (`.js` and `.mjs` work too).

package/docs/reference/commands.md

@@ -66,11 +66,23 @@ Every CLI command that drives a browser accepts these options (`start`, `explore
 | `--debug` | Enable debug logging (same as `--verbose`) |
 | `-c, --config <path>` | Path to configuration file |
 | `-p, --path <path>` | Working directory path |
+| `--base-url <url>` | Run against this URL: its path scopes relative paths, its query params ride along with every page load |
 | `-s, --show` | Show browser window |
 | `--headless` | Run browser in headless mode |
 | `--incognito` | Run without recording experiences |
 | `--session [file]` | Save/restore browser session (cookies, localStorage) from file |
 
+### `--base-url`
+
+Points one run at one area of a site, leaving every config file alone. The origin selects the site, so the knowledge and experience already stored for that host still apply. The path prefixes every relative path a plan or a command gives, and the query params are added to each page load.
+
+```bash
+npx explorbot test tests/plans/runs.md '*' \
+  --base-url 'https://app.example.com/teams/acme/?preview=pr-42'
+```
+
+A plan whose tests start at `/runs` runs them at `/teams/acme/runs`, and every page load carries `?preview=pr-42` — enough to keep a preview deployment selected for a whole session. The param travels on the request rather than in the address bar, so Explorbot navigates to clean URLs, though an app that redirects can still echo the param back. Absolute URLs are never prefixed: `https://app.example.com/users/sign_in` still points outside the scoped area, as a login page usually must.
+
 ### `--knowledge`
 
 Passes facts to the run without creating a file in `knowledge/`. Plain text applies everywhere; add frontmatter to scope it to a page or an API endpoint. Repeat the flag for several facts. See [Knowledge](../workflow/knowledge.md#per-session-knowledge).

package/docs/web-testing/researcher.md

@@ -155,6 +155,14 @@ Expands hidden elements (dropdowns, accordions, tabs) to discover more UI. Click
 
 Extracts domain-specific content (articles, products, users) as structured data.
 
+#### Light Research
+
+```ts
+researcher.research(state, { light: true });
+```
+
+A single-pass mode for consumers that describe pages instead of acting on them. Stage 1 runs as usual; stages 2–5 (locator testing, AI fixing, the visual annotation pass, backfills, and pagination probing) are skipped, so the whole run is one AI call with no browser verification roundtrips. Locators in the UI map come straight from the model and are not verified; a light run never writes to the shared research cache, so it cannot replace a verified result. The [doc collector](../doc-collection/basics.md#research-depth) uses this mode by default.
+
 ## Page Sections
 
 The Researcher breaks each page into sections by UI purpose. Sections are identified in priority order:

package/package.json

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

package/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/src/action.ts

@@ -114,6 +114,7 @@ class Action {
       if (includeScreenshot) {
         const filename = safeFilename(`${stateHash}_${timestamp}`, '.png');
         const screenshotPath = join(statesDir, filename);
+        await page?.screencast?.hideOverlays().catch(() => {});
         screenshotFile = await page
           ?.screenshot({ path: screenshotPath, fullPage: true })
           .then(() => {
@@ -124,6 +125,7 @@ class Action {
             debugLog('Screenshot failed, continuing without it:', err);
             return undefined;
           });
+        await page?.screencast?.showOverlays().catch(() => {});
       }
 
       // Save HTML to file
@@ -587,6 +589,10 @@ export const attachStepLogger = (target: ExecutedStep[], assertionsTarget?: Arra
     if (batchFailed) return;
 
     const executed: ExecutedStep = { 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/src/ai/driller.ts

@@ -6,6 +6,7 @@ import { setActivity } from '../activity.ts';
 import { Observability } from '../observability.ts';
 import { Plan, Test, TestResult } from '../test-plan.ts';
 import { collectInteractiveNodes } from '../utils/aria.ts';
+import { splitTopLevel } from '../utils/code-extractor.ts';
 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.ts';
 import { createDebug, tag } from '../utils/logger.ts';
 import { loop, pause } from '../utils/loop.ts';
@@ -1011,39 +1012,7 @@ function countTopLevelArgCount(line: string): number {
   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: string, classes: string[]): string {

package/src/ai/historian/codeceptjs.ts

@@ -8,6 +8,7 @@ import { tag } from '../../utils/logger.ts';
 import { relativeToCwd } from '../../utils/next-steps.ts';
 import { CODECEPT_TOOLS, isNonReusableCode, stripComments } from '../../utils/step-analyzer.ts';
 import { safeFilename } from '../../utils/strings.ts';
+import { ensureCodeceptResolvable } from '../../utils/test-files.ts';
 import type { Conversation } from '../conversation.ts';
 import { ASSERTION_TOOLS } from '../tools.ts';
 import type { Constructor } from './mixin.ts';
@@ -99,6 +100,7 @@ export function WithCodeceptJS<T extends Constructor>(Base: T) {
 
       const testsDir = ConfigParser.getInstance().getTestsDir();
       mkdirSync(testsDir, { recursive: true });
+      ensureCodeceptResolvable(testsDir);
 
       const filePath = join(testsDir, safeFilename(plan.title, '.js'));
       writeFileSync(filePath, lines.join('\n'));

package/src/ai/judge-tool.ts

@@ -11,7 +11,11 @@ export function createJudgeTool(deps: ToolDeps, buildState: () => Promise<Record
   return {
     judge: tool({
       description: dedent`
-        Settle one judgement about the current page instead of guessing. Phrase it literally and concretely.
+        Fast yes/no or pick-one decision about the current page, answered from <page_aria> and your recent steps.
+        No screenshot, no HTML, produces no test code.
+        Use for in-flow judgements you would otherwise guess: did the last action already take effect, which of several similar elements the scenario means, is this the expected page or dialog.
+        Not for final assertions (use verify/finish) and not for anything page_aria does not show, such as styling or visual state (use see).
+        Phrase the question literally and concretely.
       `,
       inputSchema: z.object({
         question: z.string().describe('The statement to confirm, or the question the options answer'),

package/src/ai/navigator.ts

@@ -136,11 +136,11 @@ class Navigator implements Agent {
     return matchesNavigationUrl(expectedUrl, currentUrl);
   }
 
-  async visit(url: string): Promise<void> {
-    return this.visitOnce(url);
+  async visit(url: string, opts: { recover?: boolean } = {}): Promise<boolean> {
+    return this.visitOnce(url, opts.recover !== false);
   }
 
-  private async visitOnce(url: string): Promise<void> {
+  private async visitOnce(url: string, recover: boolean): Promise<boolean> {
     try {
       const action = this.explorer.action();
 
@@ -153,7 +153,10 @@ class Navigator implements Agent {
 
       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}`;
@@ -177,6 +180,7 @@ class Navigator implements Agent {
       }
       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);
       if (errorMessage.includes('ERR_CONNECTION_REFUSED')) {
@@ -284,7 +288,7 @@ class Navigator implements Agent {
             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;
@@ -384,10 +388,6 @@ class Navigator implements Agent {
 
       <page>
         ${actionResult.toAiContext()}
-
-        <page_html>
-        ${await actionResult.combinedHtml()}
-        </page_html>
       </page>
 
       <task>
@@ -397,6 +397,8 @@ class Navigator implements Agent {
         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>
 
@@ -813,7 +815,9 @@ class Navigator implements Agent {
 
           const verified = await action.attempt(codeBlock, message);
           const proof = action.assertionSteps.map(renderAssertion).filter(Boolean);
-          results.push({ code: codeBlock, passed: verified, proof });
+          const result: AssertionResult = { code: codeBlock, passed: verified, proof };
+          if (!verified && action.lastError) result.error = action.lastError.message;
+          results.push(result);
 
           if (verified) {
             tag('success').log('Verification passed');
@@ -862,6 +866,6 @@ class Navigator implements Agent {
 
 type BatchFailure = { code: string; error: string; ariaChanges?: string | null; urlAfter?: string };
 
-export type AssertionResult = { code: string; passed: boolean; proof: string[] };
+export type AssertionResult = { code: string; passed: boolean; proof: string[]; error?: string };
 
 export { Navigator };

package/src/ai/pilot.ts

@@ -8,7 +8,7 @@ import type Explorer from '../explorer.ts';
 import type { PlaywrightRecorder } from '../playwright-recorder.ts';
 import type { StateManager } from '../state-manager.ts';
 import { Stats } from '../stats.ts';
-import { type Test, TestResult, TestStatus } from '../test-plan.ts';
+import { SettledExpectation, type SettledStatus, type Test, TestResult, TestStatus } from '../test-plan.ts';
 import { collectInteractiveNodes } from '../utils/aria.ts';
 import { ErrorPageError } from '../utils/error-page.ts';
 import { createDebug, tag } from '../utils/logger.ts';
@@ -39,6 +39,12 @@ const OUTCOME_STATUS: Record<string, SettledStatus> = {
   'The run shows this outcome did not happen.': 'failed',
 };
 
+const CONTRADICTION_RESOLUTION: Record<string, { status: SettledStatus; resolution: string }> = {
+  'The page structure agrees with the screenshot, and the outcome happened.': { status: 'passed', resolution: 'the page structure agrees with the screenshot, so the run log was wrong' },
+  'The page structure agrees with the screenshot, and the outcome did not happen.': { status: 'failed', resolution: 'the page structure agrees with the screenshot, so the run log was wrong' },
+  'The page structure agrees with the run log: the page holds it, but the screenshot does not show it.': { status: 'contradiction', resolution: 'the page structure agrees with the run log: the page holds it but does not display it, a likely rendering bug' },
+};
+
 export class Pilot implements Agent {
   emoji = '🧭';
   private provider: Provider;
@@ -619,7 +625,7 @@ export class Pilot implements Agent {
     let settledByJudge = new Map<string, SettledStatus>();
     if (!image) settledByJudge = await this.settleByJudge(task, undecided);
     undecided = undecided.filter((text) => !settledByJudge.has(text));
-    if (!undecided.length) return task.expected.map((text) => ({ text, status: settledByJudge.get(text) || decided(text) }));
+    if (!undecided.length) return task.expected.map((text) => new SettledExpectation(text, settledByJudge.get(text) || decided(text)));
 
     const schema = z.object({
       outcomes: z.array(
@@ -691,14 +697,36 @@ export class Pilot implements Agent {
     if (!response) response = await settle(userContent, this.provider.getAgenticModel('pilot'));
 
     const judged = new Map((response?.object?.outcomes || []).map((outcome: any) => [outcome.expectation, outcome]));
-    return task.expected.map((text) => {
+    const settled = task.expected.map((text) => {
       const byJudge = settledByJudge.get(text);
-      if (byJudge) return { text, status: byJudge };
-      if (!undecided.includes(text)) return { text, status: decided(text) };
+      if (byJudge) return new SettledExpectation(text, byJudge);
+      if (!undecided.includes(text)) return new SettledExpectation(text, decided(text));
       const outcome = judged.get(text) as { status: SettledStatus; evidence?: string } | undefined;
-      if (!outcome) return { text, status: 'unverified' as SettledStatus };
-      return { text, status: outcome.status || 'unverified', evidence: outcome.evidence };
+      if (!outcome) return new SettledExpectation(text, 'unverified');
+      return new SettledExpectation(text, outcome.status || 'unverified', outcome.evidence);
     });
+    return this.resolveContradictions(settled, finalState);
+  }
+
+  private async resolveContradictions(outcomes: SettledExpectation[], finalState?: ActionResult): Promise<SettledExpectation[]> {
+    const judge = this.judge;
+    if (!judge || !finalState) return outcomes;
+    if (!outcomes.some((outcome) => outcome.contradicted)) return outcomes;
+
+    const page = finalState.getCompactARIA().slice(0, JUDGE_PAGE_CAP);
+    return Promise.all(
+      outcomes.map(async (outcome) => {
+        if (!outcome.contradicted) return outcome;
+        const decision = await judge.decide(`The screenshot and the run log disagree about the expected outcome: ${outcome.text}. Which side does the page structure support?`, [...Object.keys(CONTRADICTION_RESOLUTION), UNDECIDED], {
+          expectation: outcome.text,
+          disagreement: outcome.evidence || '',
+          page,
+        });
+        const resolved = CONTRADICTION_RESOLUTION[decision.value ?? ''];
+        if (!resolved) return outcome;
+        return outcome.resolve(resolved.status, resolved.resolution);
+      })
+    );
   }
 
   private async settleByJudge(task: Test, expectations: string[]): Promise<Map<string, SettledStatus>> {
@@ -1162,6 +1190,9 @@ export class Pilot implements Agent {
         const consoleError = t.output?.pageDiff?.consoleErrors?.[0];
         if (consoleError) line += `\n   console: ${consoleError.slice(0, PILOT_MESSAGE_MAX_LENGTH)}`;
 
+        const disabledReason = t.output?.disabledReason?.[0];
+        if (disabledReason) line += `\n   shown on hover of disabled target: ${disabledReason.slice(0, PILOT_MESSAGE_MAX_LENGTH)}`;
+
         return line;
       })
       .join('\n\n');
@@ -1272,11 +1303,3 @@ export class Pilot implements Agent {
     `;
   }
 }
-
-export type SettledStatus = 'passed' | 'failed' | 'unverified' | 'contradiction';
-
-export interface SettledExpectation {
-  text: string;
-  status: SettledStatus;
-  evidence?: string;
-}