explorbot 0.1.12 → 0.1.15

package/dist/src/ai/provider.js

@@ -16,6 +16,16 @@ class AiError extends Error {
 }
 export class ContextLengthError extends Error {
 }
+function extractCachedTokens(usage) {
+    if (!usage)
+        return 0;
+    const direct = usage.cachedInputTokens ?? usage.inputTokenDetails?.cacheReadTokens;
+    if (typeof direct === 'number')
+        return direct;
+    const raw = usage.raw;
+    const fromRaw = raw?.prompt_tokens_details?.cached_tokens ?? raw?.promptTokensDetails?.cachedTokens;
+    return typeof fromRaw === 'number' ? fromRaw : 0;
+}
 function rejectAfterIdle(ms, signal) {
     return new Promise((_, reject) => {
         const tick = () => {
@@ -227,9 +237,10 @@ export class Provider {
             responseLog(response.text);
             if (response.usage) {
                 Stats.recordTokens(options.agentName || 'unknown', modelName, {
-                    input: response.usage.promptTokens || 0,
-                    output: response.usage.completionTokens || 0,
-                    total: response.usage.totalTokens || 0,
+                    input: response.usage.inputTokens ?? response.usage.promptTokens ?? 0,
+                    output: response.usage.outputTokens ?? response.usage.completionTokens ?? 0,
+                    total: response.usage.totalTokens ?? 0,
+                    cached: extractCachedTokens(response.usage),
                 });
             }
             return response;
@@ -311,9 +322,10 @@ export class Provider {
             responseLog(response.text);
             if (response.usage) {
                 Stats.recordTokens(options.agentName || 'unknown', modelName, {
-                    input: response.usage.promptTokens || 0,
-                    output: response.usage.completionTokens || 0,
-                    total: response.usage.totalTokens || 0,
+                    input: response.usage.inputTokens ?? response.usage.promptTokens ?? 0,
+                    output: response.usage.outputTokens ?? response.usage.completionTokens ?? 0,
+                    total: response.usage.totalTokens ?? 0,
+                    cached: extractCachedTokens(response.usage),
                 });
             }
             return response;
@@ -379,9 +391,10 @@ export class Provider {
             responseLog(response.object);
             if (response.usage) {
                 Stats.recordTokens(options.agentName || 'unknown', modelName, {
-                    input: response.usage.promptTokens || 0,
-                    output: response.usage.completionTokens || 0,
-                    total: response.usage.totalTokens || 0,
+                    input: response.usage.inputTokens ?? response.usage.promptTokens ?? 0,
+                    output: response.usage.outputTokens ?? response.usage.completionTokens ?? 0,
+                    total: response.usage.totalTokens ?? 0,
+                    cached: extractCachedTokens(response.usage),
                 });
             }
             return response;
@@ -555,9 +568,9 @@ export class Provider {
             responseLog(response.text);
             if (response.usage) {
                 Stats.recordTokens('vision', this.getModelName(this.config.visionModel), {
-                    input: response.usage.promptTokens || 0,
-                    output: response.usage.completionTokens || 0,
-                    total: response.usage.totalTokens || 0,
+                    input: response.usage.inputTokens ?? response.usage.promptTokens ?? 0,
+                    output: response.usage.outputTokens ?? response.usage.completionTokens ?? 0,
+                    total: response.usage.totalTokens ?? 0,
                 });
             }
             return response;

package/dist/src/ai/quartermaster.js

@@ -169,10 +169,10 @@ Focus on what would confuse a real user or caused the agent to make mistakes.`;
         const criticalViolations = report.axeViolations.filter((v) => v.impact === 'critical' || v.impact === 'serious');
         for (const v of criticalViolations.slice(0, 3)) {
             const nodeHtml = v.nodes[0]?.html.slice(0, 100) || '';
-            task.addNote(`🔴 A11Y [${v.impact}] ${v.id}: ${v.description} — ${nodeHtml}`);
+            task.addVerificationDetail(`🔴 A11Y [${v.impact}] ${v.id}: ${v.description} — ${nodeHtml}`);
         }
         for (const issue of report.semanticIssues.slice(0, 3)) {
-            task.addNote(`💡 UX [${issue.type}] ${issue.element}: ${issue.suggestion}`);
+            task.addVerificationDetail(`💡 UX [${issue.type}] ${issue.element}: ${issue.suggestion}`);
         }
     }
     saveReport(stateHash, report) {

package/dist/src/ai/rules.js

@@ -231,6 +231,8 @@ export function multipleTabsRule(tabs) {
 }
 export const actionRule = dedent `
   <actions>
+  \`faker\` (from @faker-js/faker) is available inside I.* calls for generating data, e.g. I.fillField('Bio', faker.lorem.paragraphs(5)).
+
   ### I.click
 
   clicks on the element by its locator
@@ -272,11 +274,9 @@ export const actionRule = dedent `
     I.fillField('Description', 'Hello world', '.editor'); // works for rich text / code editors too
   </example>
 
-  I.fillField handles plain inputs, textareas, contenteditable regions, and rich text / code editors
-  (Monaco, ProseMirror, CodeMirror, TipTap, Quill, Draft.js, Slate, etc.) transparently.
-  ALWAYS use I.fillField for rich editors — target the editor container or its nearest label/heading with a normal locator.
-  Do NOT open the editor with raw JS (executeScript, page.evaluate), do NOT dispatch synthetic events,
-  do NOT call the editor's own API (monaco.editor.setValue, view.dispatch, etc.) to write text.
+  I.fillField handles plain inputs, textareas, contenteditable regions, and rich text / code editors transparently.
+  ALWAYS use I.fillField for rich text / code editors — target the editor container or its nearest label/heading with a normal locator.
+  If I.fillField does not work, I.type into the focused element is the fallback.
 
   ### I.type
 

package/dist/src/ai/session-analyst.js

@@ -0,0 +1,122 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import dedent from 'dedent';
+import { outputPath } from "../config.js";
+import { Stats } from "../stats.js";
+export class SessionAnalyst {
+    emoji = '🧐';
+    provider;
+    constructor(provider) {
+        this.provider = provider;
+    }
+    async analyze(tests) {
+        const eligible = tests.filter((t) => t.startTime != null);
+        if (eligible.length === 0)
+            return '';
+        const model = this.provider.getAgenticModel('analyst');
+        const customPrompt = this.provider.getSystemPromptForAgent('analyst', undefined);
+        const systemPrompt = dedent `
+      You write a TERSE end-of-session report. Reader is a developer who wants to UNDERSTAND THE FEATURE — what works, what is broken, what is unclear. Every word must earn its place.
+
+      Output MARKDOWN. No JSON, no preamble, no closing summary.
+
+      NO EMOJI. No 🔴 🟡 🟢 ✅, no escape sequences like \\u2705. Use plain text severity tags: [High], [Medium], [Low] for defects.
+
+      ## Reporting unit
+
+      Report at the level of FEATURES / FLOWS / PAGES. Tests are evidence, not the unit. Several tests covering the same flow → ONE entry citing all of them.
+
+      ## Walk every test
+
+      PASSED test: did all steps run, was the goal actually verified, did the user-visible goal happen? All yes → contributes to What works. Any no → Execution issue (false positive).
+
+      FAILED test, first match wins: (1) goal achieved but mis-verified → Execution. (2) automation failure (locator/timeout/loop/modal/a11y) → Execution. (3) bad preconditions or data → Execution. (4) wrong URL/environment → Execution. (5) app contradicted expected outcome → Defect.
+
+      Crucial distinction: "the app misbehaved" vs "the automation could not interact with the app". ONLY the first is a Defect. If the automation gives up before the app responds — timeout, retries exhausted, dead loop / loop detected, could not click or find an element — that is an Execution issue regardless of what the log calls it. Failure inside the automation ≠ failure inside the product.
+
+      A solitary failure where adjacent tests on the same feature passed → Execution, not Defect.
+
+      ## Severity (defects only)
+      [High] blocks a core flow · [Medium] degrades a flow but workaround exists · [Low] cosmetic / edge case
+
+      ## Format
+
+      # Session Analysis
+
+      <ONE or TWO sentences describing the FEATURE STATE — what was explored, whether the core flow holds, what the standout problem is. NO test counts, NO "N tests run". Talk about the product, not the run.>
+
+      ## Coverage
+      - Pages: <paths>
+      - Features: <capabilities>
+
+      ## What works
+      - **<feature>** — #2, #7, #8
+
+      ## Defects
+
+      ### [Medium] <plain-English bug title>
+      Affects: #3, #5
+      Reproduce:
+        1. <concrete UI step>
+        2. <next>
+      Evidence: <one short observation>
+
+      ## UX issues
+      - **<feature>** — <what's confusing> (#7)
+
+      ## Execution Issues
+      - **#2 <scenario>** — <≤10 words, what was unreliable>
+
+      ## Brevity rules
+
+      - Headline: 2 sentences MAX. About the FEATURE, not the run. No counts, no "N tests", no "this session". Banned words: "exercised", "comprehensive", "notably", "this session", "module", "targeted", "covered creation".
+      - What works: feature name + test refs. NO parentheticals, NO caveats. If there's a caveat, the entry doesn't belong here.
+      - Defect title is the BUG ("Search returns non-matching results"), never the scenario name.
+      - Reproduce steps are imperative one-liners drawn from the log.
+      - Evidence is one short factual observation. Never quote the \`result\` field.
+      - Execution Issues: ONE line per test, ≤10 words, plain. Examples: "passed vacuously, no list assertion", "no file upload step in log", "dead loop on Save click". No prefixes, no nested explanation.
+      - Omit any empty section.
+      - Section order: Coverage → What works → Defects (severity desc) → UX issues → Execution Issues.
+
+      ${customPrompt || ''}
+    `;
+        const userPayload = dedent `
+      ${eligible.length} tests were executed in this session.
+
+      ${eligible.map((t, i) => this.serializeTest(t, i + 1)).join('\n\n')}
+    `;
+        const response = await this.provider.chat([
+            { role: 'system', content: systemPrompt },
+            { role: 'user', content: userPayload },
+        ], model, { agentName: 'analyst' });
+        return decodeEscapes((response?.text || '').trim());
+    }
+    writeReport(markdown) {
+        const filePath = outputPath('reports', `${Stats.sessionLabel()}.md`);
+        const dir = path.dirname(filePath);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        writeFileSync(filePath, markdown);
+        return filePath;
+    }
+    serializeTest(test, ref) {
+        const log = test
+            .getLog()
+            .slice(-30)
+            .map((entry) => `  - [${entry.type}] ${entry.content}`)
+            .join('\n');
+        return dedent `
+      <test ref="#${ref}">
+      url: ${test.startUrl || '/'}
+      scenario: ${test.scenario}
+      result: ${test.result || 'unknown'}
+      expected: ${test.expected.join(' | ') || '(none)'}
+      log:
+      ${log}
+      </test>
+    `;
+    }
+}
+function decodeEscapes(text) {
+    return text.replace(/\\u\{([0-9a-fA-F]+)\}/g, (_, hex) => String.fromCodePoint(Number.parseInt(hex, 16))).replace(/\\u([0-9a-fA-F]{4})/g, (_, hex) => String.fromCodePoint(Number.parseInt(hex, 16)));
+}

package/dist/src/ai/tester.js

@@ -49,6 +49,8 @@ export class Tester extends TaskAgent {
     pageStateHash = null;
     pageActionResult = null;
     hooksRunner;
+    seenUiMapUrls = new Set();
+    lastAnalyzedStateHash = null;
     constructor(explorer, provider, researcher, navigator, agentTools) {
         super();
         this.explorer = explorer;
@@ -80,7 +82,7 @@ export class Tester extends TaskAgent {
         return ActionResult.fromState(this.explorer.getStateManager().getCurrentState());
     }
     get progressCheckInterval() {
-        return this.explorer.getConfig().ai?.agents?.tester?.progressCheckInterval ?? 5;
+        return this.explorer.getConfig().ai?.agents?.tester?.progressCheckInterval ?? 3;
     }
     getConversation() {
         return this.currentConversation;
@@ -96,6 +98,8 @@ export class Tester extends TaskAgent {
         this.previousStateHash = null;
         this.pageStateHash = null;
         this.pageActionResult = null;
+        this.seenUiMapUrls.clear();
+        this.lastAnalyzedStateHash = null;
         this.explorer.getStateManager().clearHistory();
         this.resetFailureCount();
         this.pilot?.reset();
@@ -117,12 +121,18 @@ export class Tester extends TaskAgent {
         page?.on('console', onConsoleMessage);
         const initialState = ActionResult.fromState(state);
         const conversation = this.provider.startConversation(this.getSystemMessage(), 'tester');
+        conversation.markLastMessageCacheable();
         this.currentConversation = conversation;
         const outputDir = ConfigParser.getInstance().getOutputDir();
         this.executionLogFile = join(outputDir, `tester_${task.sessionName}.md`);
         // Note: Markdown saving functionality removed from Conversation class
-        const initialPrompt = await this.buildTestPrompt(task, initialState);
-        conversation.addUserText(initialPrompt);
+        const scenarioBlock = this.buildScenarioBlock(task, initialState);
+        conversation.addUserText(scenarioBlock);
+        conversation.markLastMessageCacheable();
+        conversation.protectPrefix(conversation.messages.length);
+        const pageContext = await this.reinjectContextIfNeeded(1, initialState);
+        if (pageContext)
+            conversation.addUserText(pageContext);
         return await Observability.run(`test: ${task.scenario}`, {
             sessionId: task.sessionName,
             tags: ['tester'],
@@ -138,6 +148,12 @@ export class Tester extends TaskAgent {
         if (this.pilot) {
             try {
                 const plan = await this.pilot.planTest(task, initialState);
+                if (task.hasFinished) {
+                    offFailedRequest?.();
+                    page?.off('pageerror', onPageError);
+                    page?.off('console', onConsoleMessage);
+                    return { success: task.isSuccessful };
+                }
                 if (plan) {
                     conversation.addUserText(`Pilot's test plan:\n${plan}\n\nFollow this plan while executing the test.`);
                 }
@@ -158,14 +174,18 @@ export class Tester extends TaskAgent {
         await this.explorer.startTest(task);
         debugLog(`Navigating to ${task.startUrl}`);
         await this.explorer.visit(task.startUrl);
-        const currentUrl = this.explorer.getStateManager().getCurrentState()?.url || task.startUrl || '';
+        const startState = this.explorer.getStateManager().getCurrentState();
+        if (startState)
+            task.addUrlNote(startState);
+        const currentUrl = startState?.url || task.startUrl || '';
         await this.hooksRunner.runBeforeHook('tester', currentUrl);
         const offStateChange = this.explorer.getStateManager().onStateChange((event) => {
             if (task.hasFinished)
                 return;
             if (event.toState?.url === event.fromState?.url)
                 return;
-            task.addNote(`Navigated to ${event.toState?.url}`, TestResult.PASSED);
+            if (event.toState)
+                task.addUrlNote(event.toState, event.fromState || undefined);
             task.states.push(event.toState);
         });
         const codeceptjsTools = createCodeceptJSTools(this.explorer, task);
@@ -203,33 +223,34 @@ export class Tester extends TaskAgent {
             The user has interrupted and wants to change direction. Follow the new instruction.
           `);
                 }
-                conversation.cleanupTag('page_aria', '...cleaned aria snapshot...', 2);
+                conversation.cleanupTag('page_aria', '...cleaned aria snapshot...', 1);
                 conversation.cleanupTag('page_html', '...cleaned HTML snapshot...', 1);
                 conversation.cleanupTag('experience', '...cleaned experience...', 1);
                 conversation.cleanupTag('applied_experience', '...cleaned past experience...', 1);
                 conversation.cleanupTag('page_ui_map', '...cleaned UI map...', 1);
                 conversation.cleanupTag('page_ui_map_overlay', '...cleaned UI overlay...', 1);
-                conversation.compactToolResults(3);
+                conversation.compactToolResults(2);
                 if (iteration > 1) {
                     const isNewPage = this.previousUrl !== null && this.previousUrl !== currentState.url;
                     let nextStep = '';
                     nextStep += await this.reinjectContextIfNeeded(iteration, currentState);
                     nextStep += await this.prepareInstructionsForNextStep(task);
                     if (isNewPage && this.pilot) {
-                        const guidance = await this.pilot.reviewNewPage(task, currentState);
+                        const guidance = await this.pilot.reviewNewPage(task, currentState, conversation);
                         if (guidance)
                             nextStep += `\n\n${guidance}`;
                     }
-                    else if ((iteration % this.progressCheckInterval === 0 || this.consecutiveFailures >= 3 || this.consecutiveEmptyResults >= 2) && this.pilot) {
+                    else if (this.shouldAnalyzeProgress(iteration, currentState) && this.pilot) {
                         const guidance = await this.pilot.analyzeProgress(task, currentState, conversation);
                         if (guidance)
                             nextStep += `\n\n${guidance}`;
                         this.consecutiveFailures = 0;
+                        this.lastAnalyzedStateHash = currentState.hash;
                     }
                     conversation.addUserText(nextStep);
                 }
                 const result = await this.provider.invokeConversation(conversation, tools, {
-                    maxToolRoundtrips: 5,
+                    maxToolRoundtrips: 3,
                     toolChoice: 'required',
                     stopWhen: () => task.hasFinished,
                 });
@@ -354,6 +375,17 @@ export class Tester extends TaskAgent {
             ...task,
         };
     }
+    shouldAnalyzeProgress(iteration, currentState) {
+        if (this.consecutiveFailures >= 3)
+            return true;
+        if (this.consecutiveEmptyResults >= 2)
+            return true;
+        if (iteration % this.progressCheckInterval !== 0)
+            return false;
+        if (this.lastAnalyzedStateHash === currentState.hash)
+            return false;
+        return true;
+    }
     async prepareInstructionsForNextStep(task) {
         let outcomeStatus = dedent `
       <task>
@@ -388,6 +420,7 @@ export class Tester extends TaskAgent {
         this.previousUrl = currentUrl;
         this.previousStateHash = currentStateHash;
         let context = '';
+        const focusArea = detectFocusArea(currentState.ariaSnapshot);
         const focusedElement = extractFocusedElement(currentState.ariaSnapshot);
         if (focusedElement) {
             const isTextInput = ['textbox', 'combobox', 'searchbox'].includes(focusedElement.role);
@@ -403,6 +436,17 @@ export class Tester extends TaskAgent {
         <no_focus>
         No element is focused
         </no_focus>
+      `;
+        }
+        if (focusArea.detected) {
+            const areaName = focusArea.name ? ` "${focusArea.name}"` : '';
+            context += dedent `
+        <focus_scope>
+        A ${focusArea.type}${areaName} is currently open above the page.
+        Scope all interactions to elements inside this ${focusArea.type}.
+        Page navigation, filters, and tabs that exist outside it are not actionable while it is open and may share names or roles with elements inside it — prefer the locator inside the ${focusArea.type}.
+        Use <page_aria> to confirm the element you target is actually inside the ${focusArea.type}.
+        </focus_scope>
       `;
         }
         if (currentState.isInsideIframe) {
@@ -420,19 +464,23 @@ export class Tester extends TaskAgent {
             this.explorer.clearOtherTabsInfo();
         }
         if (isNewUrl) {
+            const alreadySeenUiMap = this.seenUiMapUrls.has(currentUrl);
             let research = '';
-            try {
-                research = await this.researcher.research(currentState);
-            }
-            catch (err) {
-                if (!(err instanceof ErrorPageError))
-                    throw err;
-                tag('warning').log(`Research skipped: ${err.message}`);
+            if (!alreadySeenUiMap) {
+                try {
+                    research = await this.researcher.research(currentState);
+                }
+                catch (err) {
+                    if (!(err instanceof ErrorPageError))
+                        throw err;
+                    tag('warning').log(`Research skipped: ${err.message}`);
+                }
             }
             this.pageStateHash = currentStateHash;
             this.pageActionResult = currentState;
             let uiMapSection = '';
             if (research) {
+                this.seenUiMapUrls.add(currentUrl);
                 uiMapSection = dedent `
 
           Page UI Map
@@ -442,6 +490,9 @@ export class Tester extends TaskAgent {
           </page_ui_map>
         `;
             }
+            else if (alreadySeenUiMap) {
+                uiMapSection = `\n\n<page_ui_map>UI map for ${currentUrl} was shown earlier in this session — refer to it above.</page_ui_map>`;
+            }
             context += dedent `
         Context:
 
@@ -462,7 +513,6 @@ export class Tester extends TaskAgent {
       `;
             return context;
         }
-        const focusArea = detectFocusArea(currentState.ariaSnapshot);
         if (focusArea.detected && focusArea.name && this.pageStateHash && this.pageActionResult) {
             const overlaySection = await this.researcher.researchOverlay(currentState, this.pageActionResult, this.pageStateHash);
             if (overlaySection) {
@@ -640,9 +690,8 @@ export class Tester extends TaskAgent {
     ${this.provider.getSystemPromptForAgent('tester', this.explorer.getStateManager().getCurrentState()?.url) || ''}
     `;
     }
-    async buildTestPrompt(task, actionResult) {
+    buildScenarioBlock(task, actionResult) {
         const knowledge = this.getKnowledge(actionResult);
-        const pageContext = await this.reinjectContextIfNeeded(1, actionResult);
         return dedent `
       <task>
       SCENARIO GOAL: ${task.scenario}
@@ -669,8 +718,6 @@ export class Tester extends TaskAgent {
       ${this.buildAvailableFiles()}
 
       ${knowledge}
-
-      ${pageContext}
     `;
     }
     getDeletableSessionNames(task) {

package/dist/src/ai/tools.js

@@ -423,7 +423,7 @@ export function createAgentTools({ explorer, researcher, navigator, experienceTr
                         return failedToolResult('see', 'AI analysis failed to process the screenshot');
                     }
                     return successToolResult('see', {
-                        analysis: analysisResult,
+                        analysis: cap(analysisResult, ANALYSIS_OUTPUT_CAP),
                         message: `Successfully analyzed screenshot for: ${request}`,
                         suggestion: 'Visual confirmation is valid evidence for test results. Use record() to note the visual findings.',
                     });
@@ -469,8 +469,8 @@ export function createAgentTools({ explorer, researcher, navigator, experienceTr
                         url: currentState.url,
                         title: currentState.title,
                         suggestion: 'If not enough context received, call see() to visually identify elements in page contents',
-                        aria,
-                        html,
+                        aria: cap(aria, ARIA_OUTPUT_CAP),
+                        html: cap(html, HTML_OUTPUT_CAP),
                         reminder: 'Context provided. Do not call context() again until you perform actions or suspect page changed.',
                     });
                 }
@@ -556,7 +556,7 @@ export function createAgentTools({ explorer, researcher, navigator, experienceTr
                     const researchResult = await researcher.research(currentState, { screenshot: true, data: true });
                     return successToolResult('research', {
                         analysis: researchResult,
-                        aria: ActionResult.fromState(currentState).getInteractiveARIA(),
+                        aria: cap(ActionResult.fromState(currentState).getInteractiveARIA(), ARIA_OUTPUT_CAP),
                         message: `Successfully researched page: ${currentState.url}.`,
                         suggestion: dedent `
               You received comprehensive UI map report. Use it to understand the page structure and navigate to the elements. 
@@ -859,6 +859,16 @@ export function createAgentTools({ explorer, researcher, navigator, experienceTr
     return tools;
 }
 const PAGE_DIFF_SUGGESTION = 'Analyze page diff. htmlParts shows what changed and WHERE — each part has a container selector. Use the container as context when clicking elements from the diff.';
+const ARIA_OUTPUT_CAP = 4000;
+const HTML_OUTPUT_CAP = 6000;
+const ANALYSIS_OUTPUT_CAP = 2000;
+function cap(text, max) {
+    if (!text)
+        return '';
+    if (text.length <= max)
+        return text;
+    return `${text.slice(0, max)}\n[...truncated; ${text.length - max} chars omitted...]`;
+}
 function transformContainsCommand(command) {
     if (!command.includes(':contains('))
         return command;
@@ -897,9 +907,14 @@ function successToolResult(action, data, source) {
     if (data?.pageDiff) {
         let suggestion = PAGE_DIFF_SUGGESTION;
         const ariaChanges = data.pageDiff.ariaChanges || '';
+        const urlChanged = data.pageDiff.urlChanged === true;
+        const hasHtmlParts = Array.isArray(data.pageDiff.htmlParts) && data.pageDiff.htmlParts.length > 0;
         if (countAriaChanges(ariaChanges) >= 50) {
             suggestion = `MAJOR PAGE CHANGE. Page entered a different mode. Check htmlParts and iframes in pageDiff before next action. ${suggestion}`;
         }
+        else if (!urlChanged && !ariaChanges && !hasHtmlParts) {
+            suggestion = 'Action ran without error but produced no observable change (URL, ARIA and HTML all unchanged). The locator likely matched a non-interactive ancestor or an element outside the intended control. Re-locate via xpathCheck() or verify with see() before treating this as success.';
+        }
         else if (ariaChanges.includes('heading') && ariaChanges.includes('added')) {
             suggestion += ' WARNING: A new panel or modal may have appeared. If this was not the intended action, close it and try a different element.';
         }

package/dist/src/commands/base-command.js

@@ -19,17 +19,17 @@ export class BaseCommand {
         if (this.suggestions.length === 0)
             return;
         const prefix = isInteractive() ? '/' : `${getCliName()} `;
-        tag('info').log('');
-        tag('info').log(chalk.bold('Suggested:'));
+        const commandWidth = this.suggestions.reduce((max, s) => (s.command ? Math.max(max, prefix.length + s.command.length) : max), 0);
+        const lines = [chalk.bold('Suggested:')];
         for (const { command, hint } of this.suggestions) {
-            tag('info').log('');
             if (!command) {
-                tag('info').log(chalk.dim(hint));
+                lines.push(`  ${chalk.dim(hint)}`);
                 continue;
             }
-            tag('info').log(chalk.dim(`${hint}:`));
-            tag('info').log(`  ${chalk.yellow(`${prefix}${command}`)}`);
+            const cmd = `${prefix}${command}`.padEnd(commandWidth);
+            lines.push(`  ${chalk.yellow(cmd)}  ${chalk.dim(hint)}`);
         }
+        tag('info').log(lines.join('\n'));
     }
     parseArgs(args) {
         const cmd = new Command();

package/dist/src/commands/drill-command.js

@@ -2,6 +2,7 @@ import { BaseCommand } from './base-command.js';
 export class DrillCommand extends BaseCommand {
     name = 'drill';
     description = 'Drill all components on current page to learn interactions';
+    aliases = ['driller'];
     suggestions = [
         { command: 'research', hint: 'see UI map first' },
         { command: 'navigate <page>', hint: 'go to another page' },
@@ -13,7 +14,7 @@ export class DrillCommand extends BaseCommand {
         if (!state) {
             throw new Error('No active page to drill');
         }
-        await this.explorBot.agentBosun().drill({
+        await this.explorBot.agentDriller().drill({
             knowledgePath,
             maxComponents,
             interactive: true,
@@ -24,7 +25,7 @@ export class DrillCommand extends BaseCommand {
         return match ? match[1] : undefined;
     }
     parseMaxArg(args) {
-        const match = args.match(/--max\s+(\d+)/);
+        const match = args.match(/--max-components\s+(\d+)/);
         return match ? Number.parseInt(match[1], 10) : undefined;
     }
 }

package/dist/src/commands/exit-command.js

@@ -8,6 +8,7 @@ export class ExitCommand extends BaseCommand {
     description = 'Exit the application';
     aliases = ['quit'];
     async execute(_args) {
+        await this.explorBot.printSessionAnalysis();
         await this.explorBot.getExplorer().stop();
         if (Stats.hasActivity()) {
             await new Promise((resolve) => {

package/dist/src/commands/explore-command.js

@@ -1,6 +1,7 @@
 import figureSet from 'figures';
 import { getStyles } from '../ai/planner/styles.js';
 import { outputPath } from '../config.js';
+import { normalizeUrl } from '../state-manager.js';
 import { Stats } from '../stats.js';
 import { getCliName } from "../utils/cli-name.js";
 import { ErrorPageError } from "../utils/error-page.js";
@@ -9,6 +10,7 @@ import { jsonToTable } from '../utils/markdown-parser.js';
 import { printNextSteps, relativeToCwd } from "../utils/next-steps.js";
 import { safeFilename } from "../utils/strings.js";
 import { BaseCommand } from './base-command.js';
+const MAX_SUB_PAGE_ATTEMPTS = 30;
 export class ExploreCommand extends BaseCommand {
     name = 'explore';
     description = 'Start web exploration';
@@ -24,6 +26,7 @@ export class ExploreCommand extends BaseCommand {
     maxTests;
     testsRun = 0;
     completedPlans = [];
+    failedSubPages = new Set();
     async execute(args) {
         const { opts, args: remaining } = this.parseArgs(args);
         if (opts.maxTests) {
@@ -40,10 +43,12 @@ export class ExploreCommand extends BaseCommand {
         this.completedPlans.push(mainPlan);
         if (!feature && !this.isLimitReached()) {
             const planner = this.explorBot.agentPlanner();
-            while (true) {
+            let attempts = 0;
+            while (attempts < MAX_SUB_PAGE_ATTEMPTS) {
+                attempts++;
                 if (this.isLimitReached())
                     break;
-                const candidates = planner.collectSubPageCandidates(mainPlan, mainUrl || '/');
+                const candidates = planner.collectSubPageCandidates(mainPlan, mainUrl || '/').filter((c) => !this.failedSubPages.has(normalizeUrl(c.url)));
                 if (candidates.length === 0)
                     break;
                 const pick = await planner.pickNextSubPage(candidates);
@@ -59,6 +64,7 @@ export class ExploreCommand extends BaseCommand {
                     }
                 }
                 catch (err) {
+                    this.failedSubPages.add(normalizeUrl(pick.url));
                     tag('warning').log(`Sub-page exploration failed: ${err instanceof Error ? err.message : err}`);
                 }
             }
@@ -68,6 +74,7 @@ export class ExploreCommand extends BaseCommand {
             await this.explorBot.visit(mainUrl);
         const savedPath = this.explorBot.savePlans(this.completedPlans);
         this.printResults();
+        await this.explorBot.printSessionAnalysis();
         this.printNextSteps(savedPath);
     }
     async runAllStyles(pageUrl, feature, parentPlan, completedPlans) {

package/dist/src/components/AddRule.js

@@ -4,7 +4,7 @@ import { Box, Text, useInput } from 'ink';
 import React, { useEffect, useState } from 'react';
 import { AddRuleCommand } from '../commands/add-rule-command.js';
 import InputReadline from './InputReadline.js';
-const KNOWN_AGENTS = ['researcher', 'tester', 'planner', 'pilot', 'captain', 'bosun', 'navigator'];
+const KNOWN_AGENTS = ['researcher', 'tester', 'planner', 'pilot', 'captain', 'driller', 'navigator'];
 const AddRule = ({ initialAgent = '', initialName = '', onComplete, onCancel }) => {
     const [agent, setAgent] = useState(initialAgent);
     const [ruleName, setRuleName] = useState(initialName);