explorbot 0.5.9 → 0.6.0

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

@@ -1,6 +1,5 @@
 import { ActionResult } from '../action-result.js';
 import type { ExperienceTracker } from '../experience-tracker.js';
-import type Explorer from '../explorer.js';
 import type { StateManager } from '../state-manager.js';
 import { Suite } from '../suite.js';
 import { Plan, Test } from '../test-plan.js';
@@ -9,7 +8,7 @@ import { Conversation } from './conversation.js';
 import type { Fisherman } from './fisherman.js';
 import type { Provider } from './provider.js';
 import { type Researcher } from './researcher.js';
-import type { Scout } from './scout.js';
+import { type Scout } from './scout.js';
 declare const PlannerBase: {
     new (...args: any[]): {
         currentPlan: Plan | null;
@@ -47,13 +46,14 @@ declare const PlannerBase: {
 } & (new (...args: any[]) => object);
 export declare class Planner extends PlannerBase implements Agent {
     emoji: string;
-    explorer: Explorer;
     provider: Provider;
     stateManager: StateManager;
     experienceTracker: ExperienceTracker;
     knowledgeTracker: AgentDeps['knowledgeTracker'];
     MIN_TASKS: number;
     MAX_TASKS: number;
+    minTasksOverride?: number;
+    maxTasksOverride?: number;
     currentPlan: Plan | null;
     freshStart: boolean;
     lastStyleName: string;
@@ -66,14 +66,19 @@ export declare class Planner extends PlannerBase implements Agent {
     setScout(scout: Scout): void;
     get sectionOrder(): string[];
     get docsWeight(): number;
+    get effectiveMinTasks(): number;
+    get effectiveMaxTasks(): number;
+    setTestCount(opts: {
+        minTests?: number;
+        maxTests?: number;
+    }): void;
     getDefaultStartUrl(state: {
         url: string;
-        fullUrl?: string;
     }): string;
     getSystemMessage(feature?: string): string;
     setPlan(plan: Plan): void;
     static getCachedPlan(url: string): Plan | null;
-    plan(feature?: string, style?: string, parentPlan?: Plan, completedPlans?: Plan[]): Promise<Plan>;
+    plan(feature?: string, style?: string, parentPlan?: Plan): Promise<Plan>;
     getSuite(): Suite | null;
     addNewTests(tests: Test[], defaultStartUrl: string): Test[];
     getExistingTestFileScenarios(currentUrl?: string): Set<string>;
@@ -81,5 +86,7 @@ export declare class Planner extends PlannerBase implements Agent {
     buildApproach(style?: string): string;
     buildConversation(state: ActionResult, style?: string, parentPlan?: Plan, feature?: string): Promise<Conversation>;
     getTasksMessage(): string;
+    collectResearch(state: ActionResult): Promise<string>;
+    collectDocs(state: ActionResult, feature?: string): Promise<string>;
 }
 export {};

package/dist/src/ai/planner.js

@@ -1,16 +1,17 @@
 import dedent from 'dedent';
-import { z } from 'zod';
 import { ActionResult } from "../action-result.js";
 import { setActivity } from "../activity.js";
 import { ConfigParser } from "../config.js";
 import { Observability } from "../observability.js";
 import { Stats } from "../stats.js";
 import { Suite } from "../suite.js";
-import { Plan, Test } from "../test-plan.js";
+import { Plan } from "../test-plan.js";
+import { PlanningBlockedError } from "../utils/error-page.js";
 import { createDebug, tag } from '../utils/logger.js';
+import { loop } from "../utils/loop.js";
 import { jsonToTable } from "../utils/markdown-parser.js";
 import { mdq } from '../utils/markdown-query.js';
-import { planToCompactAiContext } from "../utils/test-plan-markdown.js";
+import { findPlanMarkdownProblems, parsePlansFromMarkdownText, planToCompactAiContext, readPlanMarkdownComment } from "../utils/test-plan-markdown.js";
 import { Conversation } from "./conversation.js";
 import { WithSessionDedup } from "./planner/session-dedup.js";
 import { getActiveStyle } from "./planner/styles.js";
@@ -20,32 +21,20 @@ import { findSimilarStateHash } from "./researcher/cache.js";
 import { hasFocusedSection } from "./researcher/focus.js";
 import { RulesLoader } from "../utils/rules-loader.js";
 import { capabilityGroundingRule, dataProtectionRules, fileUploadRule } from "./rules.js";
+import { ScoutQuery } from "./scout.js";
 const debugLog = createDebug('explorbot:planner');
-const TasksSchema = z.object({
-    planName: z.string().describe('Short descriptive name for the test plan (e.g., "User Authentication Testing", "Product Catalog Navigation", "Form Validation Tests")'),
-    scenarios: z
-        .array(z.object({
-        scenario: z.string().describe('A single sentence describing the behavior to test.'),
-        priority: z.enum(['critical', 'important', 'high', 'normal', 'low']).describe('Priority of the task based on business importance'),
-        startUrl: z.string().nullable().describe('Start URL for the test if different from plan URL. Use only stable feature/list/detail pages, not transient create/edit/modal URLs unless the scenario specifically starts inside that form.'),
-        steps: z.array(z.string()).describe('List of steps to perform for this scenario. Each step should be a specific action (e.g., "Open the form", "Enter required data", "Submit the form"). Keep steps atomic and actionable.'),
-        expectedOutcomes: z
-            .array(z.string())
-            .describe('List of expected outcomes that can be verified. Each outcome should be simple, specific, and easy to check (e.g., "Success message appears", "URL changes to /dashboard", "Form field shows error"). Keep outcomes atomic - do not combine multiple checks into one.'),
-    }))
-        .describe('List of testing scenarios'),
-    notPlannableReason: z.string().nullish().describe('When scenarios is empty, one sentence saying why this page has nothing to test; otherwise null.'),
-});
+const MAX_FORMAT_ATTEMPTS = 3;
 const PlannerBase = WithSessionDedup(WithSubPages(Object));
 export class Planner extends PlannerBase {
     emoji = '📋';
-    explorer;
     provider;
     stateManager;
     experienceTracker;
     knowledgeTracker;
     MIN_TASKS = 3;
     MAX_TASKS = 12;
+    minTasksOverride;
+    maxTasksOverride;
     currentPlan = null;
     freshStart = false;
     lastStyleName = '';
@@ -55,7 +44,6 @@ export class Planner extends PlannerBase {
     scout = null;
     constructor(deps, researcher) {
         super();
-        this.explorer = deps.explorer;
         this.provider = deps.ai;
         this.researcher = researcher;
         this.stateManager = deps.stateManager;
@@ -75,8 +63,24 @@ export class Planner extends PlannerBase {
         const value = ConfigParser.getInstance().getConfig().ai?.agents?.planner?.docsWeight ?? 70;
         return Math.max(0, Math.min(100, value));
     }
+    get effectiveMinTasks() {
+        if (this.minTasksOverride !== undefined)
+            return this.minTasksOverride;
+        return ConfigParser.getInstance().getConfig().ai?.agents?.planner?.minTests ?? this.MIN_TASKS;
+    }
+    get effectiveMaxTasks() {
+        if (this.maxTasksOverride !== undefined)
+            return this.maxTasksOverride;
+        return ConfigParser.getInstance().getConfig().ai?.agents?.planner?.maxTests ?? this.MAX_TASKS;
+    }
+    setTestCount(opts) {
+        if (opts.minTests !== undefined)
+            this.minTasksOverride = opts.minTests;
+        if (opts.maxTests !== undefined)
+            this.maxTasksOverride = opts.maxTests;
+    }
     getDefaultStartUrl(state) {
-        return state.fullUrl || state.url;
+        return state.url;
     }
     getSystemMessage(feature) {
         const currentUrl = this.stateManager.getCurrentState()?.url;
@@ -126,7 +130,7 @@ export class Planner extends PlannerBase {
     static getCachedPlan(url) {
         return getRegisteredPlan(url)?.plan || null;
     }
-    async plan(feature, style, parentPlan, completedPlans) {
+    async plan(feature, style, parentPlan) {
         Stats.plans++;
         const state = this.stateManager.getCurrentState();
         debugLog('Planning:', state?.url);
@@ -175,17 +179,37 @@ export class Planner extends PlannerBase {
             else {
                 tag('step').log('Focusing on main content of this page');
             }
-            debugLog('Sending planning prompt to AI provider with structured output');
-            const aiResult = await this.provider.generateObject(conversation.messages, TasksSchema, conversation.model);
-            if (!aiResult?.object?.scenarios) {
-                throw new Error('No tasks were created successfully');
+            debugLog('Sending planning prompt to AI provider');
+            let markdown = '';
+            await loop(async ({ stop, iteration }) => {
+                const response = await this.provider.chat(conversation.messages, conversation.model, { agentName: 'planner' });
+                markdown = response.text;
+                const problems = findPlanMarkdownProblems(markdown);
+                if (problems.length === 0)
+                    stop();
+                if (iteration >= MAX_FORMAT_ATTEMPTS)
+                    throw new Error(`Planner output does not match the plan format: ${problems.join('; ')}`);
+                debugLog('Plan format problems: %o', problems);
+                conversation.addAssistantText(markdown);
+                conversation.addUserText(dedent `
+            Your plan does not match the required format:
+            ${problems.map((problem) => `- ${problem}`).join('\n')}
+            Rewrite the whole plan in the format from <output_format>. Keep the same scenarios; fix only the structure.
+          `);
+            }, { maxAttempts: MAX_FORMAT_ATTEMPTS, interruptible: false });
+            const defaultStartUrl = this.getDefaultStartUrl(state);
+            markdown = mdq(markdown).query('h1').first().insertAfter(`### Prerequisite\n\n* URL: ${defaultStartUrl}`).toString();
+            const parsedPlan = parsePlansFromMarkdownText(markdown)[0];
+            const fromPlanning = parsedPlan?.tests || [];
+            const blockedBy = readPlanMarkdownComment(markdown, 'blocked');
+            const prerequisite = readPlanMarkdownComment(markdown, 'prerequisite');
+            if (!this.currentPlan && fromPlanning.length === 0 && blockedBy) {
+                tag('warning').log(`Page is not plannable: ${blockedBy}`);
             }
-            if (!this.currentPlan && aiResult.object.scenarios.length === 0 && aiResult.object.notPlannableReason) {
-                tag('warning').log(`Page is not plannable: ${aiResult.object.notPlannableReason}`);
+            if (!this.currentPlan && fromPlanning.length === 0 && prerequisite) {
+                throw new PlanningBlockedError(state.url, prerequisite, feature, style);
             }
-            const defaultStartUrl = this.getDefaultStartUrl(state);
-            const fromPlanning = aiResult.object.scenarios.map((s) => new Test(s.scenario, s.priority, s.expectedOutcomes, s.startUrl || defaultStartUrl, s.steps || []));
-            return { tests: fromPlanning, planName: aiResult.object.planName };
+            return { tests: fromPlanning, planName: parsedPlan?.title };
         });
         const tests = result.tests;
         debugLog('Created tests:', tests);
@@ -304,9 +328,6 @@ export class Planner extends PlannerBase {
     async buildConversation(state, style, parentPlan, feature) {
         const model = this.provider.getAgenticModel('planner');
         const conversation = new Conversation([], model);
-        conversation.autoTrimTag('page_research', 20000);
-        conversation.autoTrimTag('tested_scenarios', 10000);
-        conversation.autoTrimTag('docs_context', 8000);
         conversation.addUserText(this.getSystemMessage(feature));
         let ignoredPagesRule = '';
         if (!feature)
@@ -337,23 +358,25 @@ export class Planner extends PlannerBase {
       If exact wording is unknown, describe the expected result generically, for example "an authentication error is shown" or "the user stays on the login page" instead of guessing the literal text.
       If exact redirect destination is unknown, describe the destination by visible page identity, for example "the dashboard page opens" or "the current workspace home page opens" instead of inventing a URL slug.
       Only propose scenarios whose prerequisites are evident from page research, visited pages, or API data preparation context.
-      If a scenario needs existing records, recipients, results, notifications, or other target data, propose it only when that data is visible, API preconditions can create it, or the scenario itself creates the record as its setup.
-      If the page appears read-only, degraded, demo-limited, maintenance-like, or lacks write controls, prefer read-only scenarios such as opening panels, inspecting visible lists, filtering, searching, or verifying current state.
+      If a scenario needs existing records or other target data, propose using api if <api_data_preparation> section is set or reuired record is visible on page or can be created via UI.
+      If the page appears read-only, degraded, demo-limited, maintenance-like, or lacks UI controls skip that page.
       Do not assume hidden data exists just because a control is present.
       Do not put record IDs or unique record names in test plans. Describe which record is needed and let Pilot choose it during execution; name a specific record only when research shows a small, complete list of available records.
       If the list is empty or no concrete item names are visible, do not invent "known" or "existing" items. Prefer empty-state, no-match search, clear-search, or read-only list behavior scenarios.
-      Search, filter, sorting, tab, and list scenarios must start from a stable page where those controls are visible; avoid transient create/edit/new URLs unless the scenario tests that form.
-      For option values and list items, use only visible or previously observed data; do not add create/update/delete setup unless the user explicitly requests that workflow.
-      Detail-view scenarios must target visible data entities from list rows, cards, tree nodes, or detail links; do not use filter tabs, counters, status tabs, breadcrumbs, or navigation controls as detail targets.
-      DO NOT propose "verification-only" tests that merely open a UI element (modal, dropdown, panel) and check it exists.
+
+      <meaningful_tests>
       Every test must complete a meaningful action that changes application state or produces a business outcome.
+      DO NOT propose "verification-only" tests that have only assertions and no real state change
       Opening a modal is NOT a test — performing an action INSIDE the modal IS a test.
       Clicking a dropdown is NOT a test — selecting an option and verifying the result IS a test.
+      </meaningful_tests>
+
       <priority_order>
       Tests that change application data are MORE valuable than tests that only change the UI display.
       Prioritize interactions that create, update, or delete data — these test real application behavior.
       Tests that only switch views, toggle filters, or paginate are LESS valuable — propose them only after data-changing tests are covered.
       If multiple ways to create or modify data exist (different types, different forms), propose a separate test for each.
+      If <docs_content> is provided make sure you incorporate app knowledge into planning
       </priority_order>
       ${capabilityGroundingRule}
       ${dataProtectionRules}
@@ -362,28 +385,7 @@ export class Planner extends PlannerBase {
     `;
         conversation.addUserText(planningPrompt);
         conversation.addUserText(this.getTasksMessage());
-        const currentState = this.stateManager.getCurrentState();
-        const research = await this.researcher.research(currentState || state, {
-            deep: true,
-        });
-        let docsPromise = null;
-        if (this.scout && this.docsWeight > 0) {
-            docsPromise = this.scout.collectDocs({ url: state.url, title: state.title, feature, excludeUrls: this.knowledgeTracker.applicationSpecUrls(state) });
-        }
-        let plannerResearch = mdq(research).query('code').replace('').toString();
-        plannerResearch = mdq(plannerResearch)
-            .query('table')
-            .replaceEach((table) => {
-            const rows = table.toJson();
-            if (rows.length === 0 || !rows[0].Element)
-                return table.text();
-            const elementWithType = rows.map((r) => ({
-                Element: r.Element,
-                Type: r.Type || '',
-            }));
-            return jsonToTable(elementWithType, ['Element', 'Type']);
-        })
-            .toString();
+        const [plannerResearch, docs] = await Promise.all([this.collectResearch(state), this.collectDocs(state, feature)]);
         const hasFocusedOverlay = hasFocusedSection(plannerResearch);
         const focusNote = hasFocusedOverlay ? "IMPORTANT: One section is marked as **Focused** — this is the user's current focus area. Concentrate testing on the Focused section FIRST — test all interactions inside it before planning tests for the rest of the page." : '';
         const featureFilter = feature ? `FOCUS FILTER: Only propose scenarios using elements relevant to "${feature}". Ignore all other elements.` : '';
@@ -401,21 +403,22 @@ export class Planner extends PlannerBase {
         const applicationContext = this.knowledgeTracker.renderApplicationSpec(state);
         if (applicationContext) {
             conversation.addUserText(applicationContext);
+            const words = applicationContext.split(/\s+/).filter(Boolean).length;
+            tag('info').log(`Added application spec to planning: ${words} words for ${state.url}`);
         }
-        if (docsPromise) {
-            const docs = await docsPromise;
-            if (docs) {
-                conversation.addUserText(dedent `
-          <docs_context>
-          Documentation retrieved from the collected corpus by the Scout agent.
-          Ground scenarios in these documented capabilities where they apply; treat them as supporting context, not a script.
+        if (docs) {
+            conversation.addUserText(dedent `
+        <docs_context>
+        Documentation retrieved from the collected corpus by the Scout agent.
+        Ground scenarios in these documented capabilities where they apply; treat them as supporting context, not a script.
 
-          Aim for roughly ${this.docsWeight}% of the scenarios to exercise behavior documented above; the remainder may explore beyond the documentation.
+        Aim for roughly ${this.docsWeight}% of the scenarios to exercise behavior documented above; the remainder may explore beyond the documentation.
 
-          ${docs}
-          </docs_context>
-        `);
-            }
+        ${docs}
+        </docs_context>
+      `);
+            const words = docs.split(/\s+/).filter(Boolean).length;
+            tag('info').log(`Added spec to planning (${words} words)`);
         }
         let activeRegion = '';
         if (state.overlay.isOpen)
@@ -579,20 +582,14 @@ export class Planner extends PlannerBase {
     getTasksMessage() {
         return dedent `
     <task>
-      Provide testing scenarios as structured data with the following requirements:
+      Provide testing scenarios with the following requirements:
       1. Create a short, descriptive plan name that summarizes what will be tested (e.g., "User Authentication Testing", "Product Catalog Navigation", "Form Validation Tests")
-      2. Assign priorities based on business importance:
-         - CRITICAL: Core business functionality that defines the page purpose
-         - IMPORTANT: Key user flows, primary features, CRUD operations
-         - HIGH: Secondary features, edge cases for critical flows
-         - NORMAL: Supporting actions, settings, configuration
-         - LOW: Cosmetic checks, boundary testing, minor interactions
-      3. Propose tests following research section order: ${this.sectionOrder.join(', ')}
+      2. Propose tests following research section order: ${this.sectionOrder.join(', ')}
          Cover sections in this order — first propose tests for elements from earlier sections, then later ones.
          Extended Research sections come after the main sections.
-      4. Focus on interactive elements of the page. Skip navigation links that lead away from current page.
-      5. Focus on tests you are 100% sure relevant to this page and can be achived from UI.
-      6. For each task, provide BOTH steps and expected outcomes as separate arrays:
+      3. Focus on interactive elements of the page. Skip navigation links that lead away from current page.
+      4. Focus on tests you are 100% sure relevant to this page and can be achived from UI.
+      5. For each task, provide BOTH steps and expected outcomes as separate lists:
 
          STEPS - actionable commands:
          - Each step should be a specific action to perform
@@ -623,8 +620,63 @@ export class Planner extends PlannerBase {
          - Do not wrap text in ** or * quotes, ( or ) brackets.
          - Avoid using emojis or special characters.
       7. Only tests that can be tested from web UI should be proposed.
-      8. For a fresh plan propose at least ${this.MIN_TASKS} tests; when expanding an existing plan return ONLY new scenarios not in the tested list, and an empty array if none remain.
+      8. For a fresh plan propose at least ${this.effectiveMinTasks} and at most ${this.effectiveMaxTasks} tests; when expanding an existing plan return ONLY new scenarios not in the tested list, and no scenarios if none remain.
     </task>
+
+    <output_format>
+    Reply with the plan as markdown in exactly this format and nothing else:
+
+    <!-- suite -->
+    # {short plan name summarizing what is tested}
+
+    <!-- test -->
+    # {one sentence describing the behavior to test}
+
+    ## Steps
+    * {first action}
+    * {next action}
+    * {one bullet per action, as many as the workflow needs}
+
+    ## Expected
+    * {first verifiable outcome}
+    * {one bullet per outcome, as many as the scenario verifies}
+
+    Repeat the block from <!-- test to ## Expected for every scenario.
+    Every scenario needs its own <!-- test --> comment, its steps and its expected outcomes.
+    Steps list every action of the workflow in order, one action per bullet, from the starting page to the final action.
+    Expected lists every outcome to verify, one outcome per bullet.
+
+    When there is nothing to test, write no scenarios; after the plan name add one comment instead:
+    <!-- prerequisite: {step that must be done first} --> when the page shows a sign-in form or another required step instead of the content its URL is for
+    <!-- blocked: {one sentence why the page has nothing to test} --> otherwise
+    </output_format>
     `;
     }
+    async collectResearch(state) {
+        const currentState = this.stateManager.getCurrentState();
+        const research = await this.researcher.research(currentState || state, { deep: true });
+        let plannerResearch = mdq(research).query('code').replace('').toString();
+        plannerResearch = mdq(plannerResearch)
+            .query('table')
+            .replaceEach((table) => {
+            const rows = table.toJson();
+            if (rows.length === 0 || !rows[0].Element)
+                return table.text();
+            const elementWithType = rows.map((r) => ({
+                Element: r.Element,
+                Type: r.Type || '',
+            }));
+            return jsonToTable(elementWithType, ['Element', 'Type']);
+        })
+            .toString();
+        return plannerResearch;
+    }
+    async collectDocs(state, feature) {
+        if (!this.scout || this.docsWeight <= 0)
+            return '';
+        const query = ScoutQuery.fromState(state);
+        query.feature = feature;
+        query.exclude = this.knowledgeTracker.applicationSpecUrls(state);
+        return this.scout.collectDocs(query);
+    }
 }

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

@@ -23,7 +23,7 @@ export declare class Provider {
     stop(): Promise<void>;
     getModelForAgent(agentName?: string): any;
     setJudge(judge: Judge | null): void;
-    oracle(statement: string, state: unknown, options?: any): Promise<boolean>;
+    oracle(statement: string, state: unknown, options?: any): Promise<boolean | null>;
     getAgenticModel(agentName?: string): any;
     getVisionModel(): any;
     getConfiguredModels(): Record<string, string>;

package/dist/src/ai/provider.js

@@ -138,13 +138,24 @@ export class Provider {
         this.judge = judge;
     }
     async oracle(statement, state, options = {}) {
-        const judged = await this.judge?.assert(statement, state);
+        const { screenshot, ...generateOptions } = options;
+        let judgeState = state;
+        if (screenshot)
+            judgeState = { ...state, screenshot: `data:image/png;base64,${screenshot.toString('base64')}` };
+        const judged = await this.judge?.assert(statement, judgeState);
         if (typeof judged === 'boolean')
             return judged;
         const schema = z.object({ holds: z.boolean().describe('whether the statement is true') });
-        const content = `${statement}\n\n${JSON.stringify(state, null, 2)}`;
-        const response = await this.generateObject([{ role: 'user', content }], schema, this.getAgenticModel(options.agentName), options).catch(() => null);
-        return response?.object?.holds === true;
+        let content = `${statement}\n\n${JSON.stringify(state, null, 2)}`;
+        if (screenshot)
+            content = [
+                { type: 'text', text: content },
+                { type: 'file', mediaType: 'image/png', data: screenshot },
+            ];
+        const response = await this.generateObject([{ role: 'user', content }], schema, this.getAgenticModel(generateOptions.agentName), generateOptions).catch(() => null);
+        if (!response)
+            return null;
+        return response.object?.holds === true;
     }
     getAgenticModel(agentName) {
         if (agentName) {
@@ -471,7 +482,7 @@ export class Provider {
             // Log tool usage summary
             if (response.toolCalls && response.toolCalls.length > 0) {
                 responseLog(response.toolCalls);
-                response.toolCalls.forEach((call, index) => {
+                response.toolCalls.forEach((call) => {
                     tag('debug').log(`${call.toolName} > ${Object.values(call?.input || []).join(', ')}`);
                 });
             }

package/dist/src/ai/rerunner.js

@@ -267,7 +267,7 @@ export class Rerunner extends TaskAgent {
     async healStep(step, error) {
         const failedCode = step.toCode?.() || '';
         console.log(chalk.yellow(`    ${figureSet.arrowRight} Healing: ${failedCode}`));
-        return async ({ I }) => {
+        return async () => {
             const bashTool = await createBashTool({
                 destination: this.traceDir,
                 onBeforeBashCall: ({ command }) => {

package/dist/src/ai/researcher/cache.js

@@ -12,6 +12,7 @@ const FINGERPRINT_WORKER_TIMEOUT_MS = 10_000;
 const SIMILARITY_THRESHOLD = 90;
 const memoryCache = new TTLCache(CACHE_TTL_MS);
 let fingerprintWorker = null;
+let fingerprintRequestId = 0;
 export function researchPath(hash) {
     return outputPath('research', `${hash}.md`);
 }
@@ -84,13 +85,13 @@ function findSimilarMatch(combinedHtml, url) {
     if (!existsSync(statesDir))
         return Promise.resolve(null);
     const worker = getFingerprintWorker();
+    const id = ++fingerprintRequestId;
     return new Promise((resolve) => {
-        const timeout = setTimeout(() => {
-            debugLog('Fingerprint worker timed out');
-            resolve(null);
-        }, FINGERPRINT_WORKER_TIMEOUT_MS);
-        worker.on('message', (data) => {
+        const onMessage = (data) => {
+            if (data.id !== id)
+                return;
             clearTimeout(timeout);
+            worker.off('message', onMessage);
             const { matchHash, similarity } = data;
             if (!matchHash) {
                 resolve(null);
@@ -98,8 +99,15 @@ function findSimilarMatch(combinedHtml, url) {
             }
             debugLog(`Similar fingerprint found: ${matchHash} (${similarity}% similar)`);
             resolve({ hash: matchHash, similarity, url: data.url });
-        });
+        };
+        const timeout = setTimeout(() => {
+            worker.off('message', onMessage);
+            debugLog('Fingerprint worker timed out');
+            resolve(null);
+        }, FINGERPRINT_WORKER_TIMEOUT_MS);
+        worker.on('message', onMessage);
         worker.postMessage({
+            id,
             html: combinedHtml,
             statesDir,
             maxAgeMs: FINGERPRINT_MAX_AGE_MS,

package/dist/src/ai/researcher/deep-analysis.d.ts

@@ -14,6 +14,7 @@ export declare function WithDeepAnalysis<T extends Constructor>(Base: T): {
         stateManager: StateManager;
         config: ExplorbotConfig;
         actionResult: ActionResult | undefined;
+        researchedOverlays: Set<string>;
         performDeepAnalysis(state: WebPageState, result: ResearchResult): Promise<void>;
         researchOverlay(current: ActionResult, previous: ActionResult, pageStateHash: string): Promise<string | null>;
         _loadPreviousExtendedSections(hash: string): PreviousSection[];
@@ -26,7 +27,7 @@ export declare function WithDeepAnalysis<T extends Constructor>(Base: T): {
             code: string;
             url: string;
         }>): void;
-        _discoverExpandables(researchText: string, missing?: PreviousSection[], verifiedCodes?: string[]): Promise<ExpandableElement[]>;
+        _discoverExpandables(researchText: string, missing?: PreviousSection[]): Promise<ExpandableElement[]>;
         _buildClickCommands(el: ExpandableElement): string[];
         _selectExpandables(expandables: ExpandableElement[], url: string, maxClicks: number): Promise<ExpandableElement[]>;
         _clickExpandableElements(elements: Array<{

package/dist/src/ai/researcher/deep-analysis.js

@@ -14,6 +14,7 @@ const DEFAULT_MAX_EXPANDABLE_CLICKS = 10;
 const MAX_HTML_DIFF_CHARS = 20_000;
 export function WithDeepAnalysis(Base) {
     return class extends Base {
+        researchedOverlays = new Set();
         async performDeepAnalysis(state, result) {
             tag('info').log('Starting deep analysis of expandable elements');
             await this.navigateTo(state.fullUrl || state.url);
@@ -36,7 +37,7 @@ export function WithDeepAnalysis(Base) {
                     return;
                 }
             }
-            let expandables = await this._discoverExpandables(result.text, missing, verifiedCodes);
+            let expandables = await this._discoverExpandables(result.text, missing);
             if (expandables.length > maxClicks) {
                 expandables = await this._selectExpandables(expandables, state.fullUrl || state.url, maxClicks);
                 tag('substep').log(`Selected ${expandables.length} expandables to click (max: ${maxClicks})`);
@@ -68,6 +69,10 @@ export function WithDeepAnalysis(Base) {
             const region = current.overlay;
             if (!region.isOpen || !region.name)
                 return null;
+            const overlayKey = `${pageStateHash}:${region.name}`;
+            if (this.researchedOverlays.has(overlayKey))
+                return null;
+            this.researchedOverlays.add(overlayKey);
             const cached = getCachedResearch(pageStateHash);
             if (!cached)
                 return null;
@@ -162,7 +167,7 @@ export function WithDeepAnalysis(Base) {
                 result.text += `\n\n## Navigation Links\n\n${links}`;
             }
         }
-        async _discoverExpandables(researchText, missing = [], verifiedCodes = []) {
+        async _discoverExpandables(researchText, missing = []) {
             const allElements = new Map();
             for (const section of parseResearchSections(researchText)) {
                 for (const el of section.elements) {

package/dist/src/ai/researcher/fingerprint-worker.js

@@ -5,14 +5,14 @@ import { computeHtmlFingerprint } from "../../utils/html-diff.js";
 import { isSamePageFamily } from "../../utils/url-matcher.js";
 import { diceSimilarity } from "../../utils/similarity.js";
 parentPort.on('message', (data) => {
-    const { html, statesDir, maxAgeMs, threshold, url } = data;
+    const { id, html, statesDir, maxAgeMs, threshold, url } = data;
     if (!existsSync(statesDir)) {
-        parentPort.postMessage({ matchHash: null, similarity: 0 });
+        parentPort.postMessage({ id, matchHash: null, similarity: 0 });
         return;
     }
     const currentFingerprint = new Set(computeHtmlFingerprint(html));
     if (currentFingerprint.size === 0) {
-        parentPort.postMessage({ matchHash: null, similarity: 0 });
+        parentPort.postMessage({ id, matchHash: null, similarity: 0 });
         return;
     }
     const now = Date.now();
@@ -37,7 +37,7 @@ parentPort.on('message', (data) => {
         }
     }
     const matched = bestSimilarity >= threshold;
-    parentPort.postMessage({ matchHash: matched ? bestHash : null, similarity: bestSimilarity, url: matched ? bestUrl : undefined });
+    parentPort.postMessage({ id, matchHash: matched ? bestHash : null, similarity: bestSimilarity, url: matched ? bestUrl : undefined });
 });
 function readFingerprint(filePath) {
     const content = readFileSync(filePath, 'utf8');