explorbot 0.1.32-beta.1 → 0.2.1

package/src/ai/quartermaster.ts

@@ -1,8 +1,9 @@
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { z } from 'zod';
 import type { ActionResult } from '../action-result.ts';
-import { ConfigParser } from '../config.ts';
+import { outputPath } from '../config.ts';
+import type Explorer from '../explorer.ts';
 import type { StateManager, StateTransition, WebPageState } from '../state-manager.ts';
 import type { Task } from '../test-plan.ts';
 import { createDebug, tag } from '../utils/logger.ts';
@@ -12,56 +13,25 @@ import type { Provider } from './provider.ts';
 
 const debugLog = createDebug('explorbot:quartermaster');
 
-interface AxeViolation {
-  id: string;
-  impact: 'critical' | 'serious' | 'moderate' | 'minor';
-  description: string;
-  helpUrl: string;
-  nodes: Array<{ html: string; target: string[] }>;
-}
-
-interface PageAnalysis {
-  url: string;
-  stateHash: string;
-  timestamp: string;
-  axeViolations: AxeViolation[];
-}
-
-interface SemanticIssue {
-  type: 'unclear_intention' | 'confusing_naming' | 'hard_to_interact';
-  element: string;
-  issue: string;
-  suggestion: string;
-}
-
-interface AnalysisReport {
-  scenario: string;
-  timestamp: string;
-  url: string;
-  axeViolations: AxeViolation[];
-  semanticIssues: SemanticIssue[];
-}
-
 export class Quartermaster {
   private provider: Provider;
   private model?: any;
   private outputDir: string;
   private pageAnalyses: Map<string, PageAnalysis> = new Map();
   private unsubscribe: (() => void) | null = null;
-  private playwrightHelper: any = null;
+  private explorer: Explorer | null = null;
   private pendingAnalyses: Promise<void>[] = [];
 
   constructor(provider: Provider, options?: { model?: any }) {
     this.provider = provider;
     this.model = options?.model;
 
-    const configParser = ConfigParser.getInstance();
-    this.outputDir = join(configParser.getOutputDir(), 'a11y');
+    this.outputDir = outputPath('a11y');
   }
 
-  start(playwrightHelper: any, stateManager: StateManager): void {
-    this.playwrightHelper = playwrightHelper;
-    this.ensureDirectory();
+  start(explorer: Explorer, stateManager: StateManager): void {
+    this.explorer = explorer;
+    mkdirSync(this.outputDir, { recursive: true });
 
     this.unsubscribe = stateManager.onStateChange((event) => {
       this.onPageChange(event);
@@ -78,12 +48,6 @@ export class Quartermaster {
     debugLog('Quartermaster stopped');
   }
 
-  private ensureDirectory(): void {
-    if (!existsSync(this.outputDir)) {
-      mkdirSync(this.outputDir, { recursive: true });
-    }
-  }
-
   private onPageChange(event: StateTransition): void {
     const state = event.toState;
     if (!state?.hash) return;
@@ -97,7 +61,7 @@ export class Quartermaster {
   }
 
   private async runAxeAnalysis(state: WebPageState): Promise<void> {
-    const page = this.playwrightHelper?.page;
+    const page = this.explorer?.page;
     if (!page || !state.hash) {
       debugLog('No page available for axe analysis');
       return;
@@ -284,3 +248,33 @@ Focus on what would confuse a real user or caused the agent to make mistakes.`;
     return content;
   }
 }
+
+interface AxeViolation {
+  id: string;
+  impact: 'critical' | 'serious' | 'moderate' | 'minor';
+  description: string;
+  helpUrl: string;
+  nodes: Array<{ html: string; target: string[] }>;
+}
+
+interface PageAnalysis {
+  url: string;
+  stateHash: string;
+  timestamp: string;
+  axeViolations: AxeViolation[];
+}
+
+interface SemanticIssue {
+  type: 'unclear_intention' | 'confusing_naming' | 'hard_to_interact';
+  element: string;
+  issue: string;
+  suggestion: string;
+}
+
+interface AnalysisReport {
+  scenario: string;
+  timestamp: string;
+  url: string;
+  axeViolations: AxeViolation[];
+  semanticIssues: SemanticIssue[];
+}

package/src/ai/rerunner.ts

@@ -12,16 +12,13 @@ import figureSet from 'figures';
 import { z } from 'zod';
 import { ActionResult } from '../action-result.ts';
 import { setActivity } from '../activity.ts';
-import type { ExperienceTracker } from '../experience-tracker.ts';
-import type Explorer from '../explorer.ts';
-import type { KnowledgeTracker } from '../knowledge-tracker.ts';
 import { Stats } from '../stats.ts';
 import { Task, Test, TestResult } from '../test-plan.ts';
+import { formatHeadings } from '../utils/context-formatter.ts';
 import { createDebug, tag } from '../utils/logger.ts';
 import { loop } from '../utils/loop.ts';
 import { RulesLoader } from '../utils/rules-loader.ts';
-import { loadTestSuites, printTestList } from '../utils/test-files.ts';
-import type { Agent } from './agent.ts';
+import type { Agent, AgentDeps } from './agent.ts';
 import { toolExecutionLabel } from './conversation.ts';
 import type { Navigator } from './navigator.ts';
 import { Provider } from './provider.ts';
@@ -35,16 +32,13 @@ export class Rerunner extends TaskAgent implements Agent {
   protected readonly ACTION_TOOLS = ['click', 'pressKey', 'form'];
   emoji = '🔄';
 
-  private explorer: Explorer;
-  private provider: Provider;
   private agentTools: any;
-  private healedSteps: Array<{ test: string; original: string; healed: string }> = [];
+  private healedSteps: Array<{ original: string; healed: string }> = [];
   private traceDir = '';
+  private static pluginsWired = false;
 
-  constructor(explorer: Explorer, provider: Provider, agentTools?: any) {
-    super();
-    this.explorer = explorer;
-    this.provider = provider;
+  constructor(deps: AgentDeps, agentTools?: any) {
+    super(deps);
     this.agentTools = agentTools;
   }
 
@@ -52,20 +46,8 @@ export class Rerunner extends TaskAgent implements Agent {
     throw new Error('Rerunner does not use Navigator');
   }
 
-  protected getExperienceTracker(): ExperienceTracker {
-    return this.explorer.getStateManager().getExperienceTracker();
-  }
-
-  protected getKnowledgeTracker(): KnowledgeTracker {
-    return this.explorer.getKnowledgeTracker();
-  }
-
-  protected getProvider(): Provider {
-    return this.provider;
-  }
-
   private get rerunnerConfig(): Record<string, any> {
-    return (this.explorer.getConfig().ai?.agents?.rerunner as any) || {};
+    return (this.config.ai?.agents?.rerunner as any) || {};
   }
 
   private get healLimit(): number {
@@ -76,10 +58,6 @@ export class Rerunner extends TaskAgent implements Agent {
     return this.rerunnerConfig.healMaxIterations ?? 3;
   }
 
-  listTests(testsDir: string): void {
-    printTestList(loadTestSuites(testsDir));
-  }
-
   async rerun(filePath: string, options?: { testIndices?: number[] }): Promise<RerunResult> {
     const absPath = resolve(filePath);
     if (!existsSync(absPath)) {
@@ -219,7 +197,6 @@ export class Rerunner extends TaskAgent implements Agent {
 
   private setupPlugins(): void {
     const healMod = heal.default || heal;
-    healMod.connectToEvents();
 
     healMod.addRecipe('explorbot-ai-healer', {
       priority: 10,
@@ -233,21 +210,29 @@ export class Rerunner extends TaskAgent implements Agent {
       healMod.addRecipe(name, recipe);
     }
 
+    const outputDir = (global as any).output_dir || 'output';
+    this.traceDir = `${outputDir}/rerun-traces`;
+
+    if (Rerunner.pluginsWired) return;
+    Rerunner.pluginsWired = true;
+
+    healMod.connectToEvents();
+
     let currentTest: any = null;
     let healTries = 0;
     let isHealing = false;
     let caughtError: any = null;
-    const healLimit = this.healLimit;
 
     codeceptjs.event.dispatcher.on('test.before', (test: any) => {
       currentTest = test;
       healTries = 0;
       caughtError = null;
+      isHealing = false;
     });
 
     codeceptjs.event.dispatcher.on('step.after', (step: any) => {
       if (isHealing) return;
-      if (healTries >= healLimit) return;
+      if (healTries >= this.healLimit) return;
       if (!healMod.hasCorrespondingRecipes(step)) return;
 
       codeceptjs.recorder.catchWithoutStop(async (err: any) => {
@@ -286,10 +271,6 @@ export class Rerunner extends TaskAgent implements Agent {
       factor: 1.5,
     });
 
-    const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
-    const outputDir = (global as any).output_dir || 'output';
-    this.traceDir = `${outputDir}/rerun_${timestamp}`;
-
     const aiTrace = aiTracePlugin.default || aiTracePlugin;
     aiTrace(this.rerunnerConfig.aiTrace || { output: this.traceDir });
 
@@ -303,9 +284,9 @@ export class Rerunner extends TaskAgent implements Agent {
 
   private teardownHealing(): void {
     const healMod = heal.default || heal;
-    healMod.recipes['explorbot-ai-healer'] = undefined;
+    Reflect.deleteProperty(healMod.recipes, 'explorbot-ai-healer');
     for (const name of Object.keys(this.rerunnerConfig.recipes || {})) {
-      healMod.recipes[name] = undefined;
+      Reflect.deleteProperty(healMod.recipes, name);
     }
   }
 
@@ -325,7 +306,7 @@ export class Rerunner extends TaskAgent implements Agent {
       });
 
       const healTask = new Task(`Heal: ${failedCode}`);
-      const codeceptTools = createCodeceptJSTools(this.explorer, healTask);
+      const codeceptTools = createCodeceptJSTools(this.toolDeps, healTask);
 
       let healed = false;
       let healedCommand = '';
@@ -345,9 +326,9 @@ export class Rerunner extends TaskAgent implements Agent {
               healTask.addNote(note);
               tag('substep').log(note);
             }
-            const action = this.explorer.createAction();
+            const action = this.explorer.action();
             await action.execute(`I.wait(${seconds})`);
-            const state = this.explorer.getStateManager().getCurrentState();
+            const state = this.stateManager.getCurrentState();
             const ar = state ? ActionResult.fromState(state) : null;
             return {
               success: true,
@@ -432,14 +413,14 @@ export class Rerunner extends TaskAgent implements Agent {
         throw new Error(`Could not heal: ${failedCode}`);
       }
 
-      this.healedSteps.push({ test: '', original: failedCode, healed: healedCommand });
+      this.healedSteps.push({ original: failedCode, healed: healedCommand });
       console.log(chalk.green(`    ${figureSet.tick} Healed: ${healedCommand}`));
     };
   }
 
   private getHealSystemPrompt(): string {
-    const customRules = this.provider.getSystemPromptForAgent('rerunner', this.explorer.getStateManager().getCurrentState()?.url) || '';
-    const currentUrl = this.explorer.getStateManager().getCurrentState()?.url || '';
+    const customRules = this.provider.getSystemPromptForAgent('rerunner', this.stateManager.getCurrentState()?.url) || '';
+    const currentUrl = this.stateManager.getCurrentState()?.url || '';
     const approach = RulesLoader.loadRules('rerunner', ['healing-approach'], currentUrl);
 
     return dedent`
@@ -474,14 +455,10 @@ export class Rerunner extends TaskAgent implements Agent {
   }
 
   private getHealUserPrompt(failedCode: string, error: Error): string {
-    const state = this.explorer.getStateManager().getCurrentState();
+    const state = this.stateManager.getCurrentState();
     const actionResult = state ? ActionResult.fromState(state) : null;
 
-    const headings: string[] = [];
-    if (state?.h1) headings.push(`H1: ${state.h1}`);
-    if (state?.h2) headings.push(`H2: ${state.h2}`);
-    if (state?.h3) headings.push(`H3: ${state.h3}`);
-    if (state?.h4) headings.push(`H4: ${state.h4}`);
+    const headings = formatHeadings(state || {});
 
     return dedent`
       A test step failed and needs healing.

package/src/ai/researcher/cache.ts

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'no
 import { join } from 'node:path';
 import { Worker } from 'node:worker_threads';
 import { outputPath } from '../../config.ts';
+import { TTLCache } from '../../utils/cache.ts';
 import { computeHtmlFingerprint } from '../../utils/html-diff.ts';
 import { debugLog } from './mixin.ts';
 
@@ -10,8 +11,7 @@ const FINGERPRINT_MAX_AGE_MS = 60 * 60 * 1000; // 1 hour
 const FINGERPRINT_WORKER_TIMEOUT_MS = 10_000;
 const SIMILARITY_THRESHOLD = 90;
 
-const memoryCache: Record<string, string> = {};
-const memoryCacheTimestamps: Record<string, number> = {};
+const memoryCache = new TTLCache<string>(CACHE_TTL_MS);
 
 let fingerprintWorker: Worker | null = null;
 
@@ -28,25 +28,20 @@ function getFingerprintWorker(): Worker {
 }
 
 export function clearResearchCache(): void {
-  for (const key of Object.keys(memoryCache)) delete memoryCache[key];
-  for (const key of Object.keys(memoryCacheTimestamps)) delete memoryCacheTimestamps[key];
+  memoryCache.clear();
 }
 
 export function getCachedResearch(hash: string): string {
   if (!hash) return '';
-  const now = Date.now();
-  const timestamp = memoryCacheTimestamps[hash];
-  if (timestamp && now - timestamp <= CACHE_TTL_MS) {
-    return memoryCache[hash] || '';
-  }
+  const cached = memoryCache.get(hash);
+  if (cached !== undefined) return cached;
   const researchFile = outputPath('research', `${hash}.md`);
   if (!existsSync(researchFile)) return '';
   const stats = statSync(researchFile);
-  if (now - stats.mtimeMs > CACHE_TTL_MS) return '';
-  const cached = readFileSync(researchFile, 'utf8');
-  memoryCache[hash] = cached;
-  memoryCacheTimestamps[hash] = now;
-  return cached;
+  if (Date.now() - stats.mtimeMs > CACHE_TTL_MS) return '';
+  const fromDisk = readFileSync(researchFile, 'utf8');
+  memoryCache.set(hash, fromDisk);
+  return fromDisk;
 }
 
 export function getPreviousResearch(hash: string): string {
@@ -61,8 +56,7 @@ export function saveResearch(hash: string, text: string, combinedHtml?: string):
   const researchFile = join(researchDir, `${hash}.md`);
   if (!existsSync(researchDir)) mkdirSync(researchDir, { recursive: true });
   writeFileSync(researchFile, text);
-  memoryCache[hash] = text;
-  memoryCacheTimestamps[hash] = Date.now();
+  memoryCache.set(hash, text);
   debugLog(`Research saved to ${researchFile}`);
 
   if (combinedHtml) {

package/src/ai/researcher/coordinates.ts

@@ -4,6 +4,7 @@ import type { ActionResult } from '../../action-result.js';
 import type Explorer from '../../explorer.ts';
 import { tag } from '../../utils/logger.js';
 import { mdq } from '../../utils/markdown-query.ts';
+import { eidxByLocator } from '../../utils/web-eidx.ts';
 import { WebElement } from '../../utils/web-element.ts';
 import type { Provider } from '../provider.js';
 import { type Constructor, debugLog } from './mixin.ts';
@@ -81,7 +82,7 @@ export function WithCoordinates<T extends Constructor>(Base: T) {
     }
 
     async visuallyAnnotateElements(opts?: { containers?: Array<{ css: string; label: string }> }): Promise<number> {
-      return this.explorer.visuallyAnnotateElements(opts);
+      return this.explorer.withPage((page) => visuallyAnnotateContainers(page, opts?.containers || []));
     }
 
     private async _analyzeScreenshotForVisualProps(): Promise<VisualAnalysisResult> {
@@ -177,7 +178,7 @@ export function WithCoordinates<T extends Constructor>(Base: T) {
           let eidx = el.eidx || null;
           if (!eidx) {
             const locator = el.css || el.xpath || (el.aria ? `role=${el.aria.role}[name="${el.aria.text}"]` : null);
-            if (locator) eidx = await this.explorer.getEidxByLocator(locator, section.containerCss);
+            if (locator) eidx = await this.explorer.withPage((page) => eidxByLocator(page, locator, section.containerCss));
           }
           if (!eidx) continue;
 
@@ -202,7 +203,7 @@ export function WithCoordinates<T extends Constructor>(Base: T) {
       }
       if (eidxWithoutCoords.length === 0) return;
 
-      const webElements = await this.explorer.runWithBrowserRecovery('backfillCoordinates', () => WebElement.fromEidxList(this.explorer.playwrightHelper.page, eidxWithoutCoords));
+      const webElements = await this.explorer.withPage((page) => WebElement.fromEidxList(page, eidxWithoutCoords));
       if (webElements.length === 0) return;
 
       const rectMap = new Map(webElements.map((w) => [w.eidx!, w]));

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

@@ -1,5 +1,6 @@
 import dedent from 'dedent';
 import { ActionResult, type Diff } from '../../action-result.js';
+import type { ExplorbotConfig } from '../../config.ts';
 import { executionController } from '../../execution-controller.ts';
 import type Explorer from '../../explorer.ts';
 import type { StateManager } from '../../state-manager.js';
@@ -21,13 +22,14 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
     declare explorer: Explorer;
     declare provider: Provider;
     declare stateManager: StateManager;
+    declare config: ExplorbotConfig;
     declare actionResult: ActionResult | undefined;
 
     async performDeepAnalysis(state: WebPageState, result: ResearchResult): Promise<void> {
       tag('info').log('Starting deep analysis of expandable elements');
       await (this as any).navigateTo(state.fullUrl || state.url);
 
-      const maxClicks = (this.explorer.getConfig().ai?.agents?.researcher as any)?.maxExpandableClicks ?? DEFAULT_MAX_EXPANDABLE_CLICKS;
+      const maxClicks = (this.config.ai?.agents?.researcher as any)?.maxExpandableClicks ?? DEFAULT_MAX_EXPANDABLE_CLICKS;
 
       const expandedSections: string[] = [];
       const navigationLinks: Array<{ code: string; url: string }> = [];
@@ -98,7 +100,6 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
       }
 
       const diff = await current.diff(previous);
-      await diff.calculate();
 
       if (!diff.ariaChanged && diff.htmlParts.length === 0) {
         debugLog(`No diff between current and previous state for overlay "${focusArea.name}"`);
@@ -359,13 +360,12 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
           const isCoordinateClick = el.commands[0].startsWith('I.clickXY(');
           if (!isCoordinateClick) {
             const hoverCmd = el.commands[0].replace('I.click(', 'I.moveCursorTo(');
-            await this.explorer.attemptAction(hoverCmd, undefined, false);
+            await this.explorer.action().attempt(hoverCmd);
             await new Promise((r) => setTimeout(r, 500));
 
-            await this.explorer.capturePageState();
+            await this.explorer.capture();
             const hoverAR = ActionResult.fromState(this.stateManager.getCurrentState()!);
             const hoverDiff = await hoverAR.diff(previousState);
-            await hoverDiff.calculate();
             const hoverHtmlSize = hoverDiff.htmlParts.reduce((sum, p) => sum + p.subtree.length, 0);
             const hoverRevealed = hoverDiff.ariaChanged && hoverHtmlSize > 500;
 
@@ -403,9 +403,9 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
       const previousState = ActionResult.fromState(this.stateManager.getCurrentState()!);
 
       let clickCode: string | null = null;
-      const action = this.explorer.createAction();
+      const action = this.explorer.action();
       for (const cmd of commands) {
-        if (await action.attempt(cmd, undefined, false)) {
+        if (await action.attempt(cmd, undefined)) {
           clickCode = cmd;
           break;
         }
@@ -419,10 +419,9 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
 
       let diff: Diff;
       try {
-        await this.explorer.createAction().capturePageState();
+        await this.explorer.capture();
         const currAR = ActionResult.fromState(this.stateManager.getCurrentState()!);
         diff = await currAR.diff(previousState);
-        await diff.calculate();
       } catch (err) {
         tag('warning').log(`State capture failed after click: ${err instanceof Error ? err.message : err}`);
         await this._restorePageState(state.url, originalAria);
@@ -451,9 +450,9 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
     private async _restorePageState(url: string, originalAria: string): Promise<void> {
       try {
         await (this as any).cancelInUi();
-        await this.explorer.capturePageState();
+        await this.explorer.capture();
         const currentAria = this.stateManager.getCurrentState()?.ariaSnapshot || '';
-        if (!diffAriaSnapshots(originalAria, currentAria)) return;
+        if (!diffAriaSnapshots(originalAria, currentAria).text) return;
       } catch (err) {
         tag('warning').log(`State capture failed after cancelInUi: ${err instanceof Error ? err.message : err}`);
       }

package/src/ai/researcher/locators.ts

@@ -6,6 +6,7 @@ import { parseAriaLocator } from '../../utils/aria.ts';
 import { tag } from '../../utils/logger.js';
 import { mdq } from '../../utils/markdown-query.ts';
 import { WebElement } from '../../utils/web-element.ts';
+import { isDynamicId } from '../../utils/xpath.ts';
 import type { Conversation } from '../conversation.ts';
 import type { Provider } from '../provider.js';
 import { locatorRule as generalLocatorRuleText } from '../rules.js';
@@ -38,7 +39,7 @@ export function WithLocators<T extends Constructor>(Base: T) {
     declare provider: Provider;
     declare actionResult: ActionResult | undefined;
 
-    async testLocators(locators: Locator[]): Promise<void> {
+    async testLocators(locators: Locator[], opts: { scope?: boolean } = {}): Promise<void> {
       let broken = 0;
       for (const loc of locators) {
         if (executionController.isInterrupted()) break;
@@ -51,20 +52,21 @@ export function WithLocators<T extends Constructor>(Base: T) {
           continue;
         }
         try {
-          const count = await this.explorer.playwrightLocatorCount((page) => {
+          const count = await this.explorer.withPage((page) => {
             const base = loc.container ? page.locator(loc.container) : page;
             if (loc.type === 'aria') {
               const parsed = parseAriaLocator(loc.locator);
-              if (!parsed) return page.locator('__invalid__');
-              return base.getByRole(parsed.role as any, { name: parsed.text });
+              if (!parsed) return page.locator('__invalid__').count();
+              return base.getByRole(parsed.role as any, { name: parsed.text }).count();
             }
             const converted = loc.locator.replace(/:contains\(/g, ':has-text(');
             if (converted !== loc.locator) {
               loc.locator = converted;
             }
-            return base.locator(loc.locator);
+            return base.locator(loc.locator).count();
           });
           loc.valid = count === 1;
+          if (opts.scope && count > 1) loc.valid = true;
           loc.pwLocator = buildPwLocatorString(loc);
           if (!loc.valid) {
             loc.error = count === 0 ? '0 elements' : `${count} elements`;
@@ -194,7 +196,7 @@ export function WithLocators<T extends Constructor>(Base: T) {
       }
 
       if (needsXpath.length > 0) {
-        const webElements = await this.explorer.runWithBrowserRecovery('backfillBrokenLocators', () => WebElement.fromEidxList(this.explorer.playwrightHelper.page, needsXpath));
+        const webElements = await this.explorer.withPage((page) => WebElement.fromEidxList(page, needsXpath));
         const changedSections = new Set<(typeof sections)[0]>();
         for (const w of webElements) {
           const entry = needsXpathEls.get(w.eidx!);
@@ -209,6 +211,60 @@ export function WithLocators<T extends Constructor>(Base: T) {
       await this.validateContainers(result);
     }
 
+    async resolveContainers(result: ResearchResult): Promise<Locator[]> {
+      const containerLocs = result.containerLocators;
+      await this.testLocators(containerLocs, { scope: true });
+      for (const loc of containerLocs.filter((l) => l.valid === false)) {
+        if (await this.recoverContainerFromChildren(result, loc.locator)) loc.valid = true;
+      }
+      return containerLocs.filter((l) => l.valid === false);
+    }
+
+    private async recoverContainerFromChildren(result: ResearchResult, css: string): Promise<boolean> {
+      const sections = parseResearchSections(result.text).filter((s) => s.containerCss === css);
+      let recovered = 0;
+
+      for (const section of sections) {
+        const eidxList = section.elements.map((el) => el.eidx).filter(Boolean) as string[];
+        if (eidxList.length < 2) continue;
+
+        const ancestor = await this.explorer.runWithBrowserRecovery('recoverContainerFromChildren', () => WebElement.commonAncestor(this.explorer.playwrightHelper.page, eidxList));
+        if (!ancestor) continue;
+
+        const candidates: string[] = [];
+        const id = ancestor.attrs.id;
+        if (id && !isDynamicId(id)) candidates.push(`#${id}`);
+        for (const cls of ancestor.filteredClasses) {
+          if (!/^[\w-]+$/.test(cls)) continue;
+          candidates.push(`${ancestor.tag}.${cls}`);
+        }
+
+        let unique: string | null = null;
+        let multiple: string | null = null;
+        for (const candidate of candidates) {
+          let count = 0;
+          try {
+            count = await this.explorer.playwrightLocatorCount((page) => page.locator(candidate));
+          } catch {}
+          if (count === 1) {
+            unique = candidate;
+            break;
+          }
+          if (count > 1 && !multiple) multiple = candidate;
+        }
+
+        const newCss = unique || multiple;
+        if (!newCss) continue;
+
+        debugLog(`Recovered container: '${css}' → '${newCss}' in "${section.name}"`);
+        this.updateSectionContainer(result, section, newCss);
+        recovered++;
+      }
+
+      if (recovered > 0 && recovered < sections.length) debugLog(`Container '${css}' recovered in ${recovered}/${sections.length} sections, still broken for the rest`);
+      return recovered > 0 && recovered === sections.length;
+    }
+
     private async validateContainers(result: ResearchResult): Promise<void> {
       const sections = parseResearchSections(result.text);
 
@@ -217,7 +273,7 @@ export function WithLocators<T extends Constructor>(Base: T) {
 
         let count = 0;
         try {
-          count = await this.explorer.playwrightLocatorCount((page) => page.locator(section.containerCss!));
+          count = await this.explorer.withPage((page) => page.locator(section.containerCss!).count());
         } catch {}
 
         if (count >= 1) continue;
@@ -226,7 +282,7 @@ export function WithLocators<T extends Constructor>(Base: T) {
         if (simplified) {
           let simplifiedCount = 0;
           try {
-            simplifiedCount = await this.explorer.playwrightLocatorCount((page) => page.locator(simplified));
+            simplifiedCount = await this.explorer.withPage((page) => page.locator(simplified).count());
           } catch {}
 
           if (simplifiedCount >= 1) {
@@ -275,7 +331,8 @@ export interface Locator {
 }
 
 export interface LocatorMethods {
-  testLocators(locators: Locator[]): Promise<void>;
+  testLocators(locators: Locator[], opts?: { scope?: boolean }): Promise<void>;
   fixBrokenSections(result: ResearchResult, conversation: Conversation): Promise<void>;
   backfillBrokenLocators(result: ResearchResult): Promise<void>;
+  resolveContainers(result: ResearchResult): Promise<Locator[]>;
 }

package/src/ai/researcher/parser.ts

@@ -94,7 +94,7 @@ export function extractContainerFromBlockquote(sectionMarkdown: string): string
 }
 
 export function parseResearchSections(markdown: string): ResearchSection[] {
-  const hasExtendedResearch = markdown.includes('\n# Extended Research') || markdown.startsWith('# Extended Research');
+  const hasExtendedResearch = mdq(markdown).query('section1(~"Extended Research")').count() > 0;
 
   return parseSections(markdown)
     .filter((s) => !SKIP_SECTIONS.has(s.name.toLowerCase()) && !s.name.toLowerCase().includes('data:'))

package/src/ai/researcher/research-result.ts

@@ -46,24 +46,6 @@ export class ResearchResult {
     }));
   }
 
-  updateSection(sectionName: string, locators: Locator[]): void {
-    const sections = parseResearchSections(this.text);
-    const section = sections.find((s) => s.name === sectionName);
-    if (!section) return;
-
-    for (const el of section.elements) {
-      const elLocators = locators.filter((l) => l.element === el.name);
-      for (const loc of elLocators) {
-        const value = loc.valid === false ? null : loc.locator || null;
-        if (loc.type === 'css') el.css = value;
-        if (loc.type === 'xpath') el.xpath = value;
-        if (loc.type === 'aria') el.aria = value ? parseAriaLocator(value) : null;
-      }
-    }
-
-    this.rebuildSectionInText(section);
-  }
-
   rebuildSectionInText(section: ResearchSection): void {
     if (section.elements.length === 0) return;
     const newTable = rebuildSectionMarkdown(section);