explorbot 0.1.28 → 0.1.30

package/src/ai/tester.ts

@@ -25,7 +25,7 @@ import { Navigator } from './navigator.ts';
 import type { Pilot } from './pilot.ts';
 import { Provider } from './provider.ts';
 import { Researcher } from './researcher.ts';
-import { actionRule, focusedElementRule, formRequirementsRule, locatorRule, multipleTabsRule, protectionRule, sectionContextRule } from './rules.ts';
+import { actionRule, capabilityGroundingRule, dataProtectionRules, focusedElementRule, formRequirementsRule, locatorRule, multipleTabsRule, sectionContextRule } from './rules.ts';
 import { TaskAgent } from './task-agent.ts';
 import { createCodeceptJSTools, createSpecialContextTools } from './tools.ts';
 
@@ -43,7 +43,7 @@ const SAMPLE_FILES: Record<string, string> = {
 };
 
 export class Tester extends TaskAgent implements Agent {
-  protected readonly ACTION_TOOLS = ['click', 'pressKey', 'form'];
+  protected readonly ACTION_TOOLS = ['click', 'hover', 'pressKey', 'form'];
   protected readonly SPECIAL_CONTEXT_ACTION_TOOLS = ['exitIframe'];
   emoji = '🧪';
   private explorer: Explorer;
@@ -66,6 +66,8 @@ export class Tester extends TaskAgent implements Agent {
   private hooksRunner: HooksRunner;
   private seenUiMapUrls = new Set<string>();
   private lastAnalyzedStateHash: string | null = null;
+  private stalledIterations = 0;
+  private readonly MAX_STALLED_ITERATIONS = 3;
 
   constructor(explorer: Explorer, provider: Provider, researcher: Researcher, navigator: Navigator, agentTools?: any) {
     super();
@@ -126,6 +128,7 @@ export class Tester extends TaskAgent implements Agent {
     this.pageActionResult = null;
     this.seenUiMapUrls.clear();
     this.lastAnalyzedStateHash = null;
+    this.stalledIterations = 0;
     this.explorer.getStateManager().clearHistory();
     this.resetFailureCount();
     this.pilot?.reset();
@@ -348,6 +351,11 @@ export class Tester extends TaskAgent implements Agent {
               });
           }
 
+          if (this.shouldStopForStalledExecution(task, currentState, result?.toolExecutions || [])) {
+            stop();
+            return;
+          }
+
           if (assertionPerformed) {
             const message = result?.toolExecutions?.find((execution: any) => execution.toolName === 'verify')?.output?.message || '';
             task.addNote(message, wasSuccessful ? TestResult.PASSED : TestResult.FAILED);
@@ -456,6 +464,31 @@ export class Tester extends TaskAgent implements Agent {
     return true;
   }
 
+  private shouldStopForStalledExecution(task: Test, previousState: ActionResult, toolExecutions: any[]): boolean {
+    if (task.hasFinished) return false;
+
+    const currentState = this.getCurrentState();
+    const stateChanged = previousState.url !== currentState.url || previousState.hash !== currentState.hash;
+    const actionTools = [...this.ACTION_TOOLS, ...this.SPECIAL_CONTEXT_ACTION_TOOLS];
+    const hasSuccessfulAction = toolExecutions.some((execution) => execution.wasSuccessful && actionTools.includes(execution.toolName));
+    const hasSuccessfulAssertion = toolExecutions.some((execution) => execution.wasSuccessful && this.ASSERTION_TOOLS.includes(execution.toolName));
+
+    if (stateChanged || hasSuccessfulAction || hasSuccessfulAssertion) {
+      this.stalledIterations = 0;
+      return false;
+    }
+
+    const hasNoBrowserProgress = toolExecutions.length === 0 || toolExecutions.every((execution) => !actionTools.includes(execution.toolName) || !execution.wasSuccessful);
+    if (!hasNoBrowserProgress) return false;
+
+    this.stalledIterations++;
+    if (this.stalledIterations < this.MAX_STALLED_ITERATIONS) return false;
+
+    task.addNote('No browser progress after repeated attempts on unchanged page', TestResult.FAILED);
+    task.finish(TestResult.FAILED);
+    return true;
+  }
+
   private async prepareInstructionsForNextStep(task: Test): Promise<string> {
     let outcomeStatus = dedent`
       <task>
@@ -464,6 +497,8 @@ export class Tester extends TaskAgent implements Agent {
   
       <rules>
       Use tools ${this.ACTION_TOOLS.join(', ')} to interact with the page.
+      Use tool names exactly as listed in this prompt. Do not invent combined tool names, aliases, or names with channel markers such as "commentary".
+      Match each tool input schema exactly. Do not invent parameter names or pass extra fields.
       Do not do unsuccesful clicks again.
       Do not run same tool calls with same parameters again.
       </rules>
@@ -746,6 +781,7 @@ export class Tester extends TaskAgent implements Agent {
     <rules>
     - Refer to UI Map from <page_ui_map> to understand the page structure and its main elements
     - Use only elements that exist in the provided ARIA tree or HTML, <page_aria> and <page_html>
+    - Use tool input schemas exactly as documented. Do not invent parameter names or add fields not listed by the tool schema.
     - Use click() for buttons, links, and clickable elements ONLY - do NOT include I.fillField() or I.type() commands in click() tool
     - click() commands array is for FALLBACK LOCATORS of the SAME element, NOT for clicking different elements in sequence. If you need to click two different elements, make two separate click() calls.
     - Use form() for text input (I.fillField, I.type), dropdown selection (I.selectOption), file uploads (I.attachFile), and multi-step form interactions
@@ -758,6 +794,7 @@ export class Tester extends TaskAgent implements Agent {
     - NEVER call record(status: "success") if your last verify() or see() call FAILED. A failed check means the outcome is NOT confirmed — use record(status: "fail") instead, or retry with a different approach.
     - Use finish() to complete the test, not record(). record() is for intermediate notes.
     - Call finish(verify) when all goals are achieved — provide an assertion to verify
+    - NEVER call finish() with a negative assertion that says the goal did NOT happen. If the goal cannot be achieved after real attempts, record the blocker and call stop().
     - ONLY call stop() if the scenario itself is completely irrelevant to this page and no expectations can be achieved
     - Use reset() ONLY as a last resort when the current page cannot host the scenario. Never reset after a successful flow just because an assertion or milestone did not match — verify differently or record() the finding instead. Reset is destructive and does not undo server-side side effects.
     - Be precise with locators (CSS or XPath)
@@ -771,6 +808,13 @@ export class Tester extends TaskAgent implements Agent {
     - When you interact with form with inputs, ensure that you click corresponding button to save its data
     - Follow <locator_priority> rules when selecting locators for all tools
     - Before retrying your actions check maybe they already achived expected results. Use see() tool for that
+    - If the current URL is already a create/edit/new form and the scenario is about creating/editing that entity, fill and submit that form. Do not click the list-page "New" button again from inside the form.
+    - If the scenario is about search/filter/sort/tabs/list inspection and the current URL is a create/edit/new form, go back or reset to the stable list page before interacting with list controls.
+    - When selecting related entities from a list, do not choose rows/options/cards marked as "0 items", "0 tests", or otherwise empty if the scenario requires selecting real content.
+    - In selection pickers, counters such as "Selected 0", "Matched tests 0", or disabled Save/Apply mean the selection did not register. Choose a non-empty item or change filters before submitting.
+    - A passed form/click command only means the command executed. If a required field remains empty, submit stays disabled, or the expected text is not visible, treat the action as not completed and correct the missing field/state.
+    - For filter/tab scenarios, success requires BOTH: the requested filter/tab is visibly active/selected AND the list content matches that filter. Do not finish from only one of these signals.
+    - Empty-state text such as "No matched items" only proves a filter when the requested filter/tab is active and the empty state belongs to the filtered list.
     - When filling complex form with lot of actions performed, use see() to look which fields were filled and which are not
     - When verify() fails, use see() to visually confirm the result — visual confirmation is equally valid evidence
     - For visual state verification (active tabs, selected items, counts, colors), prefer see() over DOM-based verify()
@@ -799,12 +843,17 @@ export class Tester extends TaskAgent implements Agent {
 
     ${formRequirementsRule}
 
+    ${capabilityGroundingRule}
+
+    ${dataProtectionRules}
+
     ${this.provider.getSystemPromptForAgent('tester', this.explorer.getStateManager().getCurrentState()?.url) || ''}
     `;
   }
 
   private buildScenarioBlock(task: Test, actionResult: ActionResult): string {
     const knowledge = this.getKnowledge(actionResult);
+    const experience = this.getExperience(actionResult);
 
     return dedent`
       <task>
@@ -822,16 +871,21 @@ export class Tester extends TaskAgent implements Agent {
       Try to achieve as many goals as possible.
       If goal is not achievable, log that and skip to next one.
       Do not hallucinate that goal was achieved when it was not.
+      If the scenario action could not be completed, do not finish with a verification of the failure state.
       When creating or editing items via form() or type() you should include ${task.sessionName} in the value (if it is not restricted by the application logic)
       Initial page URL: ${actionResult.url}
 
-      ${protectionRule}
+      ${capabilityGroundingRule}
+
+      ${dataProtectionRules}
 
       ${this.buildDeletionScope(task)}
 
       ${this.buildAvailableFiles()}
 
       ${knowledge}
+
+      ${experience}
     `;
   }
 
@@ -963,12 +1017,13 @@ export class Tester extends TaskAgent implements Agent {
       }),
       stop: tool({
         description: dedent`
-          Stop the current test because the scenario is fundamentally incompatible with the page.
-          Use this ONLY when the scenario cannot be executed on the current page or application.
-          Do NOT use this for failures — use reset() and retry instead.
+          Stop the current test because it cannot be completed in the current session.
+          Use this when the scenario is incompatible, required UI/data is absent, or repeated varied attempts
+          show that automation cannot complete the workflow.
+          Do NOT use this immediately after the first failed action — retry with a materially different approach first.
         `,
         inputSchema: z.object({
-          reason: z.string().describe('Explanation why the scenario is incompatible'),
+          reason: z.string().describe('Explanation why the scenario cannot be completed'),
         }),
         execute: async ({ reason }) => {
           task.addNote(`Stop requested: ${reason}`);
@@ -1003,6 +1058,7 @@ export class Tester extends TaskAgent implements Agent {
           Provide a specific assertion to verify the final state.
           The assertion MUST prove that YOUR ACTIONS changed the page state.
           Do NOT verify something that was already true before you started testing.
+          Do NOT provide an assertion that verifies absence, failure, an empty state, or that the goal did not happen.
 
           Examples of good assertions:
           - "New user 'john@example.com' is visible in the users list"
@@ -1135,12 +1191,26 @@ export class Tester extends TaskAgent implements Agent {
       this.resetFailureCount();
       this.previousUrl = null;
       this.previousStateHash = null;
+      this.stalledIterations = 0;
+    } else if (this.shouldStopAfterStalledLoopError(task)) {
+      return 'stop';
     }
 
     this.currentConversation?.addUserText(result.message);
     return 'continue';
   }
 
+  private shouldStopAfterStalledLoopError(task: Test): boolean {
+    if (task.hasFinished) return false;
+
+    this.stalledIterations++;
+    if (this.stalledIterations < this.MAX_STALLED_ITERATIONS) return false;
+
+    task.addNote('No browser progress after repeated execution errors', TestResult.FAILED);
+    task.finish(TestResult.FAILED);
+    return true;
+  }
+
   private async cleanupStartedTest(task: Test): Promise<void> {
     await this.finishTest(task);
     await this.explorer.stopTest(task, {

package/src/ai/tools.ts

@@ -18,7 +18,6 @@ import { isInteractive } from './task-agent.ts';
 
 const debugLog = createDebug('explorbot:tools');
 
-export const CODECEPT_TOOLS = ['click', 'pressKey', 'form'] as const;
 export const ASSERTION_TOOLS = ['verify'] as const;
 
 export function createCodeceptJSTools(explorer: Explorer, task: Task) {
@@ -160,6 +159,84 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
       },
     }),
 
+    hover: tool({
+      description: dedent`
+        Move the mouse cursor to an element to reveal hover-only controls.
+
+        Use this before clicking row actions, icon buttons, menus, or toolbars that appear only
+        when the user hovers a list item, table row, card, or tree node.
+
+        This tool ONLY accepts I.moveCursorTo(locator) commands. It does not click.
+        After hovering, use context(), see(), or click() the revealed control.
+      `,
+      inputSchema: z.object({
+        commands: z.array(z.string()).describe(dedent`
+          FALLBACK LOCATORS for ONE element to hover.
+          Order by reliability:
+          1. I.moveCursorTo(text, container)
+          2. I.moveCursorTo(ARIA, container)
+          3. I.moveCursorTo(CSS, container)
+          4. I.moveCursorTo(CSS) or I.moveCursorTo(XPath)
+        `),
+        explanation: z.string().describe('Why you are hovering this element'),
+      }),
+      execute: async ({ commands: rawCommands, explanation }) => {
+        const activeNote = task.startNote(explanation);
+
+        if (rawCommands.length === 0) {
+          activeNote.commit(TestResult.FAILED);
+          return failedToolResult('hover', 'No commands provided');
+        }
+
+        const invalidCommands = rawCommands.map((cmd) => cmd.trim()).filter((cmd) => cmd.startsWith('I.') && !cmd.startsWith('I.moveCursorTo'));
+
+        if (invalidCommands.length > 0) {
+          activeNote.commit(TestResult.FAILED);
+          return failedToolResult('hover', `Invalid commands: ${invalidCommands.join(', ')}. Hover tool only accepts I.moveCursorTo() commands.`, {
+            suggestion: 'Use click() to click elements, or form() for typing/selecting.',
+          });
+        }
+
+        const commands = rawCommands.map((cmd) => {
+          const trimmed = cmd.trim();
+          if (trimmed.startsWith('I.moveCursorTo')) return trimmed;
+          return `I.moveCursorTo(${JSON.stringify(trimmed)})`;
+        });
+
+        const previousState = ActionResult.fromState(stateManager.getCurrentState()!);
+        const action = explorer.createAction();
+        const attempts: Array<{ command: string; success: boolean; error?: string }> = [];
+
+        for (const command of commands) {
+          const success = await action.attempt(command, explanation, true);
+          attempts.push({
+            command,
+            success,
+            ...(action.lastError && { error: action.lastError.toString() }),
+          });
+
+          if (!success) continue;
+
+          const toolResult = await ActionResult.fromState(stateManager.getCurrentState()!).toToolResult(previousState, command);
+          activeNote.commit(TestResult.PASSED);
+          return successToolResult('hover', { ...toolResult, attempts, code: command }, action);
+        }
+
+        const toolResult = await ActionResult.fromState(stateManager.getCurrentState()!).toToolResult(previousState, commands[0]);
+        activeNote.commit(TestResult.FAILED);
+        return failedToolResult(
+          'hover',
+          'All hover commands failed',
+          {
+            ...toolResult,
+            attempts,
+            suggestion: 'Use xpathCheck() to locate the row/card/tree node, or visualClick() if the hover target is only visually identifiable.',
+          },
+          action.lastError
+        );
+      },
+    }),
+
     pressKey: tool({
       description: dedent`
         Press a keyboard key or key combination. Use this for special keys like Enter, Escape, Tab, Arrow keys, or key combinations with modifiers.
@@ -488,6 +565,7 @@ export function createAgentTools({
         Check the page contents based on current page state and screenshot.
         This tool will trigger visual research to check the page contents on request.
         Use it to verify the actions were performed correctly and the page is in the expected state.
+        Input schema has exactly one field: request. Do not pass text, reason, assertion, or other fields.
 
         <example>
         request: "Check current state of the Login form"

package/src/config.ts

@@ -22,6 +22,7 @@ interface PlaywrightConfig {
   waitForAction?: number;
   waitForNavigation?: 'load' | 'domcontentloaded' | 'networkidle';
   waitForTimeout?: number;
+  spinnerSelectors?: string[];
   ignoreHTTPSErrors?: boolean;
   userAgent?: string;
   viewport?: {
@@ -59,6 +60,7 @@ interface AgentConfig extends HooksConfig {
   systemPrompt?: string;
   rules?: RuleEntry[];
   providerOptions?: Record<string, any>;
+  reasoning?: 'provider-default' | 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
 }
 
 interface ResearcherAgentConfig extends AgentConfig {

package/src/experience-tracker.ts

@@ -3,12 +3,12 @@ import { basename, dirname, join } from 'node:path';
 import matter from 'gray-matter';
 import { type Tokens, marked } from 'marked';
 import type { ActionResult } from './action-result.js';
-import { isNonReusableCode } from './ai/historian/utils.ts';
 import { ConfigParser } from './config.js';
 import { KnowledgeTracker } from './knowledge-tracker.js';
 import type { WebPageState } from './state-manager.js';
 import { createDebug, tag } from './utils/logger.js';
 import { mdq } from './utils/markdown-query.js';
+import { isNonReusableCode } from './utils/step-analyzer.ts';
 import { extractStatePath } from './utils/url-matcher.js';
 
 const debugLog = createDebug('explorbot:experience');

package/src/explorbot.ts

@@ -25,12 +25,13 @@ import { ExperienceTracker } from './experience-tracker.ts';
 import Explorer from './explorer.ts';
 import { KnowledgeTracker } from './knowledge-tracker.ts';
 import { WebPageState } from './state-manager.ts';
+import { Stats } from './stats.ts';
 import type { Suite } from './suite.ts';
 import { Plan, type Test } from './test-plan.ts';
-import { parsePlansFromMarkdown } from './utils/test-plan-markdown.ts';
 import { setVerboseMode, tag } from './utils/logger.ts';
 import { relativeToCwd } from './utils/next-steps.ts';
 import { sanitizeFilename } from './utils/strings.ts';
+import { parsePlansFromMarkdown } from './utils/test-plan-markdown.ts';
 
 export interface ExplorBotOptions {
   from?: string;
@@ -220,7 +221,13 @@ export class ExplorBot {
       this.agents.tester = this.createAgent(({ ai, explorer }) => {
         const researcher = this.agentResearcher();
         const navigator = this.agentNavigator();
-        const tools = createAgentTools({ explorer, researcher, navigator });
+        const stateManager = explorer.getStateManager();
+        const experienceTracker = stateManager.getExperienceTracker();
+        const getState = () => {
+          const state = stateManager.getCurrentState();
+          return state ? ActionResult.fromState(state) : null;
+        };
+        const tools = createAgentTools({ explorer, researcher, navigator, experienceTracker, getState });
         return new Tester(explorer, ai, researcher, navigator, tools);
       });
 
@@ -494,7 +501,10 @@ export class ExplorBot {
 
       const reporter = this.explorer?.getReporter();
       if (reporter?.isEnabled()) {
-        await reporter.setRunDescription(markdown);
+        let description = markdown;
+        const modelsTable = Stats.modelsTable(this.provider.getConfiguredModels());
+        if (modelsTable) description = `${markdown}\n\n${modelsTable}`;
+        await reporter.setRunDescription(description);
       }
 
       this.lastReportedTestCount = tests.length;

package/src/explorer.ts

@@ -2,10 +2,10 @@ import { existsSync, mkdirSync } from 'node:fs';
 import path, { join } from 'node:path';
 // @ts-ignore
 import * as codeceptjs from 'codeceptjs';
-import dedent from 'dedent';
 import stepsListener from 'codeceptjs/lib/listener/steps';
 import storeListener from 'codeceptjs/lib/listener/store';
 import { createTest } from 'codeceptjs/lib/mocha/test';
+import dedent from 'dedent';
 import type { BrowserContextOptions } from 'playwright';
 import { ActionResult } from './action-result.ts';
 import Action from './action.js';
@@ -21,10 +21,11 @@ import { PlaywrightRecorder } from './playwright-recorder.ts';
 import { Reporter } from './reporter.ts';
 import { StateManager } from './state-manager.js';
 import { Test, TestResult } from './test-plan.ts';
+import { BrowserRecoveryError, isFatalBrowserError, isNavigationTransitionError } from './utils/browser-errors.ts';
 import { ELEMENT_EXTRACTION_CONFIG, getElementDataExtractorSource } from './utils/html.ts';
 import { createDebug, log, tag } from './utils/logger.js';
+import { waitForPageReadiness } from './utils/page-readiness.ts';
 import { WebElement } from './utils/web-element.ts';
-import { BrowserRecoveryError, isFatalBrowserError } from './utils/browser-errors.ts';
 
 declare global {
   namespace NodeJS {
@@ -314,13 +315,26 @@ class Explorer {
     try {
       return await operation();
     } catch (error) {
-      if (!this.isFatalBrowserError(error)) throw error;
+      let recoveryError = error;
+
+      if (isNavigationTransitionError(error)) {
+        tag('warning').log(`${label}: page is still navigating, waiting before retry...`);
+        await this.waitForPageReadiness();
+        try {
+          return await operation();
+        } catch (retryError) {
+          if (!isNavigationTransitionError(retryError) && !this.isFatalBrowserError(retryError)) throw retryError;
+          recoveryError = retryError;
+        }
+      }
+
+      if (!this.isFatalBrowserError(recoveryError)) throw recoveryError;
 
       tag('warning').log(`${label}: browser page is unavailable, recovering...`);
       let recovered = await this.recoverFromBrowserError();
       if (!recovered) recovered = await this.restartBrowser();
-      if (!recovered) throw new BrowserRecoveryError(label, error, false);
-      if (!(await this.waitForUsablePageDom())) throw new BrowserRecoveryError(label, error, true);
+      if (!recovered) throw new BrowserRecoveryError(label, recoveryError, false);
+      if (!(await this.waitForPageReadiness())) throw new BrowserRecoveryError(label, recoveryError, true);
 
       try {
         return await operation();
@@ -377,7 +391,7 @@ class Explorer {
         const msg = err instanceof Error ? err.message : String(err);
         if (!RECOVERABLE_NAVIGATION_ERRORS.test(msg)) throw err;
         tag('warning').log(`Navigation warning (continuing after load): ${msg.split('\n')[0]}`);
-        await this.playwrightHelper.page.waitForLoadState('domcontentloaded', { timeout: 10000 }).catch(() => {});
+        await this.waitForPageReadiness();
         await action.capturePageState();
       }
     }
@@ -488,11 +502,11 @@ class Explorer {
       if (url) {
         tag('warning').log(`Browser error detected, recovering by navigating to ${url}`);
         await this.playwrightHelper.page.goto(url, { waitUntil: 'domcontentloaded', timeout: 10000 });
-        return this.waitForUsablePageDom();
+        return this.waitForPageReadiness();
       }
       tag('warning').log('Browser error detected, reloading page');
       await this.playwrightHelper.page.reload({ waitUntil: 'domcontentloaded', timeout: 10000 });
-      return this.waitForUsablePageDom();
+      return this.waitForPageReadiness();
     } catch (err) {
       tag('error').log(`Browser recovery failed: ${err instanceof Error ? err.message : err}`);
       return false;
@@ -532,7 +546,7 @@ class Explorer {
 
       if (url) {
         await this.playwrightHelper.page.goto(url, { waitUntil: 'domcontentloaded', timeout: 10000 });
-        if (!(await this.waitForUsablePageDom())) return false;
+        if (!(await this.waitForPageReadiness())) return false;
       }
 
       tag('success').log('Browser restarted');
@@ -550,27 +564,14 @@ class Explorer {
     }
   }
 
-  private async waitForUsablePageDom(): Promise<boolean> {
+  private async waitForPageReadiness(): Promise<boolean> {
     const page = this.playwrightHelper?.page;
     if (!page) return false;
 
-    await page.waitForLoadState?.('domcontentloaded', { timeout: 5000 }).catch(() => {});
-    if (page.waitForFunction) {
-      const hasUsableDom = await page
-        .waitForFunction(
-          () => {
-            const body = document.body;
-            if (!body) return false;
-            return body.children.length > 0 || body.textContent?.trim().length > 0;
-          },
-          undefined,
-          { timeout: 5000 }
-        )
-        .then(() => true)
-        .catch(() => false);
-      if (!hasUsableDom) return false;
-    }
-    await page.waitForLoadState?.('networkidle', { timeout: 3000 }).catch(() => {});
+    await waitForPageReadiness(page, {
+      timeout: this.config.playwright.waitForTimeout,
+      spinnerSelectors: this.config.playwright.spinnerSelectors,
+    });
     return true;
   }
 

package/src/stats.ts

@@ -54,6 +54,24 @@ export class Stats {
     return String(num);
   }
 
+  static modelsTable(roleModels: Record<string, string>): string {
+    const usedModels = Object.entries(Stats.models).filter(([, tokens]) => tokens.total > 0);
+    if (usedModels.length === 0) return '';
+
+    const rolesByModel: Record<string, string[]> = {};
+    for (const [role, model] of Object.entries(roleModels)) {
+      if (!rolesByModel[model]) rolesByModel[model] = [];
+      rolesByModel[model].push(role);
+    }
+
+    const rows = usedModels.map(([model, tokens]) => {
+      const roles = rolesByModel[model]?.join(', ') || '-';
+      return `| ${roles} | ${model} | ${Stats.humanizeTokens(tokens.total)} |`;
+    });
+
+    return ['## Models', '', '| Role | Model | Tokens |', '| --- | --- | --- |', ...rows].join('\n');
+  }
+
   static hasActivity(): boolean {
     if (Stats.tests > 0 || Stats.plans > 0 || Stats.researches > 0) return true;
     const totalTokens = Object.values(Stats.models).reduce((sum, m) => sum + m.total, 0);

package/src/utils/aria.ts

@@ -334,6 +334,54 @@ const detectRenames = (prev: FlatEntry[], curr: FlatEntry[], prevTotals: Map<str
   return { added, removed };
 };
 
+// Interactive controls keep a stable role+name across a state flip; only an ARIA state
+// attribute changes. Report those flips on their own line so the model always sees
+// "now checked / now collapsed", in both directions, regardless of other page churn.
+const STATE_WORDS: Record<string, { on: string; off: string }> = {
+  checked: { on: 'checked', off: 'unchecked' },
+  selected: { on: 'selected', off: 'unselected' },
+  pressed: { on: 'pressed', off: 'unpressed' },
+  expanded: { on: 'expanded', off: 'collapsed' },
+};
+const STATE_ATTRS = Object.keys(STATE_WORDS);
+
+const stateWord = (attr: string, value: unknown): string => {
+  if (attr === 'checked' && value === 'mixed') return 'partially checked';
+  const words = STATE_WORDS[attr];
+  if (value === true || value === 'true') return words.on;
+  return words.off;
+};
+
+// Pair entries by path; when role and name match but a state attr differs, it's a toggle.
+const detectToggles = (prev: FlatEntry[], curr: FlatEntry[]): { toggled: string[]; togglePaths: Set<string> } => {
+  const toggled: string[] = [];
+  const togglePaths = new Set<string>();
+  const currByPath = new Map(curr.map((e) => [e.path, e]));
+
+  for (const before of prev) {
+    const after = currByPath.get(before.path);
+    if (!after) continue;
+    if (before.entry.role !== after.entry.role) continue;
+    if (before.entry.name !== after.entry.name) continue;
+
+    const transitions: string[] = [];
+    for (const attr of STATE_ATTRS) {
+      const was = stateWord(attr, before.entry[attr]);
+      const now = stateWord(attr, after.entry[attr]);
+      if (was === now) continue;
+      transitions.push(`${was} -> ${now}`);
+    }
+    if (transitions.length === 0) continue;
+
+    togglePaths.add(before.path);
+    let label = String(after.entry.role);
+    const name = after.entry.name;
+    if (typeof name === 'string' && name.trim()) label += ` "${name.trim()}"`;
+    toggled.push(`${label}: ${transitions.join(', ')}`);
+  }
+  return { toggled, togglePaths };
+};
+
 const TOP_DIFF_ITEMS = 10;
 
 const formatDiffSection = (label: string, items: string[]): string[] => {
@@ -358,9 +406,15 @@ const formatDiffSection = (label: string, items: string[]): string[] => {
   return lines;
 };
 
-const formatDiff = (added: string[], removed: string[]): string | null => {
-  if (added.length === 0 && removed.length === 0) return null;
-  return ['ariaDiff:', ...formatDiffSection('added', added), ...formatDiffSection('removed', removed)].join('\n');
+const formatDiff = (added: string[], removed: string[], toggled: string[]): string | null => {
+  if (added.length === 0 && removed.length === 0 && toggled.length === 0) return null;
+  const sections = ['ariaDiff:'];
+  if (toggled.length > 0) {
+    sections.push('  toggled:');
+    for (const line of toggled) sections.push(`    - ${line}`);
+  }
+  sections.push(...formatDiffSection('added', added), ...formatDiffSection('removed', removed));
+  return sections.join('\n');
 };
 
 // ─────────────────────────────────────────────────────────────────
@@ -437,13 +491,16 @@ export const diffAriaSnapshots = (previous: string | null, current: string | nul
     tree = dropEmpty(tree);
     return flatten(tree);
   };
-  const prev = flat(previous);
-  const curr = flat(current);
+  const prevAll = flat(previous);
+  const currAll = flat(current);
+  const { toggled, togglePaths } = detectToggles(prevAll, currAll);
+  const prev = prevAll.filter((e) => !togglePaths.has(e.path));
+  const curr = currAll.filter((e) => !togglePaths.has(e.path));
   const prevTotals = countBy(prev.map((e) => e.summary));
   const currTotals = countBy(curr.map((e) => e.summary));
   const byCount = diffByCount(prevTotals, currTotals);
   const renames = detectRenames(prev, curr, prevTotals, currTotals);
-  return formatDiff([...byCount.added, ...renames.added], [...byCount.removed, ...renames.removed]);
+  return formatDiff([...byCount.added, ...renames.added], [...byCount.removed, ...renames.removed], toggled);
 };
 
 export const detectFocusArea = (snapshot: string | null): FocusAreaResult => {

package/src/utils/browser-errors.ts

@@ -2,6 +2,7 @@
 // not typed exceptions. Keep those external message markers in one adapter so
 // recovery decisions are not duplicated across agents/actions.
 const FATAL_BROWSER_ERROR_MARKERS = ['Frame was detached', 'Target closed', 'Target page, context or browser has been closed', 'Execution context was destroyed', 'Protocol error', 'Session closed'];
+const NAVIGATION_TRANSITION_ERROR_MARKERS = ['most likely because of a navigation', 'navigating and changing the content'];
 
 export class BrowserRecoveryError extends Error {
   constructor(
@@ -20,6 +21,11 @@ export function isFatalBrowserError(error: unknown): boolean {
   return FATAL_BROWSER_ERROR_MARKERS.some((marker) => message.includes(marker.toLowerCase()));
 }
 
+export function isNavigationTransitionError(error: unknown): boolean {
+  const message = browserErrorMessage(error).toLowerCase();
+  return NAVIGATION_TRANSITION_ERROR_MARKERS.some((marker) => message.includes(marker.toLowerCase()));
+}
+
 export function browserErrorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }