explorbot 0.5.3 → 0.5.5

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

@@ -11,7 +11,7 @@ import { JUDGE_PAGE_CAP, UNDECIDED } from "../../../src/ai/judge.js";
 import { getPreviousResearch } from "../../../src/ai/researcher/cache.js";
 import { actionRule, locatorRule } from "../../../src/ai/rules.js";
 import { createAgentTools, createCodeceptJSTools, createRefTools } from "../../../src/ai/tools.js";
-import { getAliveEndpoint, launchServer, listInstances, stopServer } from "../../../src/browser-server.js";
+import { getAliveEndpoint, listInstances } from "../../../src/browser-server.js";
 import { ConfigCommand } from "../../../src/commands/config-command.js";
 import { ConfigMissingError, ConfigParser, EXPLORBOT_ENV_VARS, outputPath } from "../../../src/config.js";
 import { ExplorBot } from "../../../src/explorbot.js";
@@ -67,7 +67,6 @@ export class Prima {
     artifactsDir;
     hash;
     sessionUrl;
-    server = null;
     attached = null;
     session = null;
     constructor(options = {}) {
@@ -220,6 +219,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 +285,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 +371,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 +441,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,29 +454,18 @@ 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();
-        let show = config.playwright.show || false;
-        if (this.options.show)
-            show = true;
-        if (this.options.headless)
-            show = false;
-        this.server = await this.launchOwnServer({ browser: config.playwright.browser, show }, this.instanceName());
-    }
-    async browserStop(all = false) {
+    async browserCheck() {
         await this.loadConfig();
-        if (this.attached)
-            return false;
-        if (!all)
-            return this.stopInstance(this.instanceName());
-        let stopped = false;
-        for (const instance of listInstances()) {
-            if (await this.stopInstance(instance.name))
-                stopped = true;
-        }
-        return stopped;
+        const { match, candidates, browser } = await this.discover();
+        await browser?.close().catch(() => { });
+        if (!match)
+            throw this.missingSessionError(candidates);
+        return `browser: ${this.attachmentLabel(match)} at ${match.endpoint}`;
     }
     async config(json) {
         const [site] = listSites();
@@ -496,36 +514,6 @@ export class Prima {
             `upload:   TESTOMATIO=<apiKey> npx @testomatio/reporter replay ${file}`,
         ].join('\n');
     }
-    async browserStatus() {
-        await this.loadConfig();
-        const info = await this.instanceInfo();
-        const endpoint = await getAliveEndpoint(info.name);
-        const others = info.others.map((other) => other.name).join(', ') || 'none';
-        const lines = [`instance: ${info.name} (${info.tabs} ${pluralize(info.tabs, 'tab')}) | other instances: ${others}`];
-        if (!endpoint)
-            lines.push('browser: not running');
-        if (endpoint)
-            lines.push(`browser: running at ${endpoint}`);
-        return lines.join('\n');
-    }
-    async browserList() {
-        await this.loadConfig();
-        const lines = [];
-        for (const instance of listInstances()) {
-            const endpoint = await getAliveEndpoint(instance.name);
-            if (!endpoint)
-                continue;
-            lines.push(`prima --instance ${instance.name}  ${endpoint}`);
-        }
-        const discovery = await this.discover();
-        await discovery.browser?.close().catch(() => { });
-        for (const descriptor of discovery.candidates) {
-            lines.push(`playwright-cli --pw-session ${descriptor.title}  ${descriptor.endpoint}`);
-        }
-        if (!lines.length)
-            return 'no browser instances running';
-        return lines.join('\n');
-    }
     async instanceInfo() {
         const name = this.instanceName();
         const others = listInstances()
@@ -588,21 +576,25 @@ export class Prima {
         const { match, candidates, browser } = discovered || (await this.discover());
         if (match && (await this.attachToEndpoint(match, browser)))
             return;
-        if (!match && candidates.length) {
+        if (!match && candidates.length)
+            throw this.missingSessionError(candidates);
+        if (await this.connectOwnInstance())
+            return;
+        throw this.missingSessionError(candidates);
+    }
+    missingSessionError(candidates) {
+        if (candidates.length) {
             const titles = candidates.map((candidate) => candidate.title).join(', ');
-            throw new Error(dedent `
+            return new Error(dedent `
         Several playwright-cli sessions are open: ${titles}
         Pick one with --pw-session <title>.
       `);
         }
-        if (await this.connectOwnInstance())
-            return;
-        throw new Error(dedent `
-      No browser to drive for instance "${this.instanceName()}".
-      Open one first:
-        playwright-cli open <url>   prima attaches to this workspace session by default
-        prima browser start         starts a prima-owned browser instead
-      Prima never launches a browser implicitly.
+        return new Error(dedent `
+      No playwright-cli session is open for prima to drive.
+      Start one first:
+        playwright-cli open ${this.options.url || '<url>'}
+      Prima attaches to this workspace session by default and never launches a browser itself.
     `);
     }
     async discover(descriptors = readDescriptors()) {
@@ -670,17 +662,6 @@ export class Prima {
         this.session = { key: this.instanceName(), endpoint, title: `prima instance "${this.instanceName()}"` };
         return true;
     }
-    async launchOwnServer(opts, instance) {
-        return launchServer(opts, instance);
-    }
-    async stopInstance(instance) {
-        if (instance === this.instanceName()) {
-            const server = this.server;
-            this.server = null;
-            await server?.close();
-        }
-        return stopServer(instance);
-    }
     isUrlTarget(target) {
         const value = target.trim();
         if (value.startsWith('/'))

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.5",
   "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

@@ -7,6 +7,7 @@ import { normalizeUrl } from '../state-manager.js';
 import { isFatalBrowserError } from "../utils/browser-errors.js";
 import { getCliName } from "../utils/cli-name.js";
 import { extractCodeBlocks } from '../utils/code-extractor.js';
+import { isLoginPage } from "../utils/error-page.js";
 import { HooksRunner } from "../utils/hooks-runner.js";
 import { createDebug, pluralize, tag } from '../utils/logger.js';
 import { loop, pause } from '../utils/loop.js';
@@ -15,7 +16,7 @@ import { normalizeInlineText } from "../utils/strings.js";
 import { extractStatePath, isSameHostFamily, matchesNavigationUrl } from '../utils/url-matcher.js';
 import { JUDGE_PAGE_CAP, UNDECIDED } from "./judge.js";
 import { Researcher } from "./researcher.js";
-import { actionRule, locatorRule, unexpectedPopupRule } from './rules.js';
+import { actionRule, credentialsRule, locatorRule, unexpectedPopupRule } from './rules.js';
 import { isInteractive } from './task-agent.js';
 import { createLearnExperienceTool } from "./tools.js";
 const debugLog = createDebug('explorbot:navigator');
@@ -46,7 +47,7 @@ class Navigator {
     NEVER use executeScript, executeAsyncScript, or any JS evaluation to change the URL, bypass redirects, or fake the page state.
     If the target URL redirects to an authentication/login page, DO NOT try to force the original URL. Instead:
       1. Look for credentials in the provided knowledge/hint context and perform a real login through the form.
-      2. If no credentials are available, ask the user for credentials or ask the user to log in manually.
+      2. If no credentials are available, stop and name the credentials that are missing. Never guess them.
     A redirect to /login, /sign_in, /auth, or similar is a signal that authentication is required — treat it as such, never as an obstacle to bypass.
   </constraints>
   `;
@@ -119,10 +120,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 +132,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 +158,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 +257,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;
@@ -340,6 +345,9 @@ class Navigator {
         if (!experience && !actionResult.isInsideIframe) {
             experience = this.experienceTracker.renderExperienceFor(actionResult);
         }
+        let credentials = '';
+        if (isLoginPage(actionResult))
+            credentials = credentialsRule;
         return dedent `
       <message>
         ${message}
@@ -347,10 +355,6 @@ class Navigator {
 
       <page>
         ${actionResult.toAiContext()}
-
-        <page_html>
-        ${await actionResult.combinedHtml()}
-        </page_html>
       </page>
 
       <task>
@@ -360,6 +364,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>
 
@@ -367,6 +373,8 @@ class Navigator {
 
       ${unexpectedPopupRule}
 
+      ${credentials}
+
       ${RulesLoader.loadRules('navigator', ['multiple-locator', 'output'], actionResult.url || '').replace('{{maxAttempts}}', String(this.MAX_ATTEMPTS))}
 
       ${experience}
@@ -722,7 +730,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;
-}

package/dist/src/ai/pilot.js

@@ -4,7 +4,7 @@ import { z } from 'zod';
 import { ActionResult } from "../action-result.js";
 import { ConfigParser } from "../config.js";
 import { Stats } from "../stats.js";
-import { TestResult, TestStatus } from "../test-plan.js";
+import { SettledExpectation, TestResult, TestStatus } from "../test-plan.js";
 import { collectInteractiveNodes } from "../utils/aria.js";
 import { ErrorPageError } from "../utils/error-page.js";
 import { createDebug, tag } from "../utils/logger.js";
@@ -26,6 +26,11 @@ const OUTCOME_STATUS = {
     'The run shows this outcome happened.': 'passed',
     'The run shows this outcome did not happen.': 'failed',
 };
+const CONTRADICTION_RESOLUTION = {
+    '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 {
     emoji = '🧭';
     provider;
@@ -544,7 +549,7 @@ export class Pilot {
             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) }));
+            return task.expected.map((text) => new SettledExpectation(text, settledByJudge.get(text) || decided(text)));
         const schema = z.object({
             outcomes: z.array(z.object({
                 expectation: z.string().describe('The expected outcome, repeated exactly as it was given'),
@@ -607,17 +612,39 @@ export class Pilot {
         if (!response)
             response = await settle(userContent, this.provider.getAgenticModel('pilot'));
         const judged = new Map((response?.object?.outcomes || []).map((outcome) => [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 };
+                return new SettledExpectation(text, byJudge);
             if (!undecided.includes(text))
-                return { text, status: decided(text) };
+                return new SettledExpectation(text, decided(text));
             const outcome = judged.get(text);
             if (!outcome)
-                return { text, status: 'unverified' };
-            return { text, status: outcome.status || 'unverified', evidence: outcome.evidence };
+                return new SettledExpectation(text, 'unverified');
+            return new SettledExpectation(text, outcome.status || 'unverified', outcome.evidence);
         });
+        return this.resolveContradictions(settled, finalState);
+    }
+    async resolveContradictions(outcomes, finalState) {
+        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);
+        }));
     }
     async settleByJudge(task, expectations) {
         const settled = new Map();

package/dist/src/ai/researcher.js

@@ -77,7 +77,7 @@ export class Researcher extends ResearcherBase {
     `;
     }
     async research(state, opts = {}) {
-        const { screenshot = false, force = false, deep = false, data = false, fix = true } = opts;
+        const { screenshot = false, force = false, deep = false, data = false, fix = true, light = false } = opts;
         const maxRetries = this.settings.retries ?? 2;
         let retriesLeft = opts._retriesLeft ?? maxRetries;
         this.actionResult = ActionResult.fromState(state);
@@ -103,6 +103,8 @@ export class Researcher extends ResearcherBase {
         return Observability.run(sessionName, { tags: ['researcher'], sessionId: stateHash }, async () => {
             const displayUrl = state.fullUrl || state.url;
             tag('info').log(`Researching ${displayUrl} to understand the context...`);
+            if (light)
+                tag('info').log('Light research: single pass, locator verification skipped');
             setActivity(`${this.emoji} Researching...`, 'action');
             await this.ensureNavigated(displayUrl, screenshot && this.provider.hasVision());
             await this.hooksRunner.runBeforeHook('researcher', state.url);
@@ -135,7 +137,7 @@ export class Researcher extends ResearcherBase {
                 }
             }
             const isOnCurrentState = this.actionResult.getStateHash() === this.stateManager.getCurrentState()?.hash;
-            this.hasScreenshotToAnalyze = screenshot && this.provider.hasVision() && isOnCurrentState;
+            this.hasScreenshotToAnalyze = !light && screenshot && this.provider.hasVision() && isOnCurrentState;
             const conversation = this.provider.startConversation(this.getSystemMessage(), 'researcher');
             const prompt = await this.buildResearchPrompt();
             conversation.addUserText(prompt);
@@ -164,12 +166,12 @@ export class Researcher extends ResearcherBase {
             // Stage 2: Test containers + locators
             result.parseLocators();
             debugLog(`Extracted ${result.locators.length} locators from research`);
-            if (!interrupted() && result.locators.length === 0 && retriesLeft > 0) {
+            if (!light && !interrupted() && result.locators.length === 0 && retriesLeft > 0) {
                 tag('warning').log(`No locators parsed, retrying research (${maxRetries - retriesLeft + 1}/${maxRetries})...`);
                 await new Promise((r) => setTimeout(r, 1000));
                 return this.research(state, { ...opts, force: true, _retriesLeft: retriesLeft - 1 });
             }
-            if (!interrupted()) {
+            if (!light && !interrupted()) {
                 const brokenContainers = await this.resolveContainers(result);
                 const containerCount = result.containers.length;
                 if (containerCount > 0 && brokenContainers.length === containerCount && retriesLeft > 0) {
@@ -187,7 +189,7 @@ export class Researcher extends ResearcherBase {
                 await this.testLocators(toTest);
             }
             // Stage 3: Fix broken sections via AI conversation continuation
-            if (!interrupted() && fix && result.locators.some((l) => l.valid === false)) {
+            if (!light && !interrupted() && fix && result.locators.some((l) => l.valid === false)) {
                 await this.fixBrokenSections(result, activeConversation);
             }
             // Focused section: unified Playwright probe (HTML+CSS+visibility).
@@ -227,11 +229,11 @@ export class Researcher extends ResearcherBase {
                 }
             }
             // Stage 5: Backfill broken elements
-            if (!interrupted()) {
+            if (!light && !interrupted()) {
                 await this.backfillCoordinates(result);
                 await this.backfillBrokenLocators(result);
             }
-            if (!interrupted()) {
+            if (!light && !interrupted()) {
                 await this.detectPagination(result);
             }
             // Focused section: final fallback (vision-only — without a screenshot we don't infer focus)
@@ -258,7 +260,7 @@ export class Researcher extends ResearcherBase {
             }
             result.cleanup();
             let researchFile = null;
-            if (stateHash) {
+            if (stateHash && !light) {
                 researchFile = saveResearch(researchState, result.text, combinedHtml);
             }
             const summaryText = mdq(result.text).query('section2(/^summary/i)').query('paragraph[0]').text().trim();

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

@@ -3,6 +3,7 @@ export declare const locatorRule: string;
 export declare const drillLocatorRule: string;
 export declare const fileUploadRule: string;
 export declare const formRequirementsRule: string;
+export declare const credentialsRule: string;
 export declare const protectionRule: string;
 export declare const dataProtectionRules: string;
 export declare const capabilityGroundingRule: string;