explorbot 0.1.11 → 0.1.13

package/src/ai/historian/codeceptjs.ts

@@ -6,6 +6,7 @@ import { KnowledgeTracker } from '../../knowledge-tracker.ts';
 import type { Plan } from '../../test-plan.ts';
 import { tag } from '../../utils/logger.ts';
 import { relativeToCwd } from '../../utils/next-steps.ts';
+import { safeFilename } from '../../utils/strings.ts';
 import type { Conversation } from '../conversation.ts';
 import { ASSERTION_TOOLS, CODECEPT_TOOLS } from '../tools.ts';
 import type { Constructor } from './mixin.ts';
@@ -97,8 +98,7 @@ export function WithCodeceptJS<T extends Constructor>(Base: T) {
       const testsDir = ConfigParser.getInstance().getTestsDir();
       mkdirSync(testsDir, { recursive: true });
 
-      const filename = plan.title.replace(/[^a-zA-Z0-9]/g, '_').toLowerCase();
-      const filePath = join(testsDir, `${filename}.js`);
+      const filePath = join(testsDir, safeFilename(plan.title, '.js'));
       writeFileSync(filePath, lines.join('\n'));
       this.savedFiles.add(filePath);
 

package/src/ai/historian/experience.ts

@@ -2,7 +2,6 @@ import dedent from 'dedent';
 import { z } from 'zod';
 import { ActionResult } from '../../action-result.ts';
 import { ExperienceTracker, type SessionStep } from '../../experience-tracker.ts';
-import type { PlaywrightRecorder } from '../../playwright-recorder.ts';
 import type { Reporter, ReporterStep } from '../../reporter.ts';
 import type { StateManager } from '../../state-manager.ts';
 import { type Task, Test } from '../../test-plan.ts';
@@ -24,10 +23,10 @@ export function WithExperience<T extends Constructor>(Base: T) {
     declare experienceTracker: ExperienceTracker;
     declare reporter: Reporter | undefined;
     declare stateManager: StateManager | undefined;
-    declare recorder: PlaywrightRecorder | undefined;
     declare isPlaywrightFramework: () => boolean;
     declare toCode: (conversation: Conversation, scenario: string) => string;
     declare toPlaywrightCode: (conversation: Conversation, scenario: string) => Promise<string>;
+    declare stopScreencast: () => Promise<void>;
 
     async saveSession(task: Task, initialState: ActionResult, conversation: Conversation): Promise<void> {
       debugLog('Saving session experience');
@@ -55,6 +54,8 @@ export function WithExperience<T extends Constructor>(Base: T) {
         await this.reportSession(task, steps);
       }
 
+      await this.stopScreencast();
+
       tag('substep').log(`Historian saved session for: ${task.description}`);
     }
 

package/src/ai/historian/playwright.ts

@@ -7,6 +7,7 @@ import { type PlaywrightRecorder, type TraceCall, renderAssertion, renderCall }
 import type { Plan } from '../../test-plan.ts';
 import { tag } from '../../utils/logger.ts';
 import { relativeToCwd } from '../../utils/next-steps.ts';
+import { safeFilename } from '../../utils/strings.ts';
 import type { Conversation } from '../conversation.ts';
 import { ASSERTION_TOOLS, CODECEPT_TOOLS } from '../tools.ts';
 import type { Constructor } from './mixin.ts';
@@ -21,14 +22,14 @@ export interface PlaywrightMethods {
 
 export function WithPlaywright<T extends Constructor>(Base: T) {
   return class extends Base {
-    declare recorder: PlaywrightRecorder | undefined;
+    declare playwright: { recorder: PlaywrightRecorder; helper: any } | undefined;
     declare savedFiles: Set<string>;
 
     async toPlaywrightCode(conversation: Conversation, scenario: string): Promise<string> {
       const toolExecutions = conversation.getToolExecutions();
       const successfulSteps = toolExecutions.filter((exec) => exec.wasSuccessful && PLAYWRIGHT_EMITTED_TOOLS.includes(exec.toolName as any));
 
-      const callsByGroup = this.recorder ? await this.recorder.exportChunk() : new Map<string, TraceCall[]>();
+      const callsByGroup = this.playwright?.recorder ? await this.playwright.recorder.exportChunk() : new Map<string, TraceCall[]>();
 
       const stepLines: string[] = [];
       for (const exec of successfulSteps) {
@@ -59,7 +60,7 @@ export function WithPlaywright<T extends Constructor>(Base: T) {
         }
       }
 
-      const pilotVerifications = this.recorder ? this.recorder.drainVerifications() : [];
+      const pilotVerifications = this.playwright?.recorder ? this.playwright.recorder.drainVerifications() : [];
       if (pilotVerifications.length > 0) {
         const assertionLines: string[] = [];
         for (const step of pilotVerifications) {
@@ -135,8 +136,7 @@ export function WithPlaywright<T extends Constructor>(Base: T) {
       const testsDir = ConfigParser.getInstance().getTestsDir();
       mkdirSync(testsDir, { recursive: true });
 
-      const filename = plan.title.replace(/[^a-zA-Z0-9]/g, '_').toLowerCase();
-      const filePath = join(testsDir, `${filename}.spec.ts`);
+      const filePath = join(testsDir, safeFilename(plan.title, '.spec.ts'));
       writeFileSync(filePath, lines.join('\n'));
       this.savedFiles.add(filePath);
 

package/src/ai/historian/screencast.ts

@@ -0,0 +1,133 @@
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+// @ts-ignore
+import * as codeceptjs from 'codeceptjs';
+import { outputPath } from '../../config.ts';
+import type { ExplorbotConfig } from '../../config.ts';
+import type { PlaywrightRecorder } from '../../playwright-recorder.ts';
+import { tag } from '../../utils/logger.ts';
+import { relativeToCwd } from '../../utils/next-steps.ts';
+import { safeFilename } from '../../utils/strings.ts';
+import { type Constructor, debugLog } from './mixin.ts';
+
+export interface ScreencastMethods {
+  attachScreencast(): void;
+  isScreencastActive(): boolean;
+  stopScreencast(): Promise<void>;
+}
+
+export function WithScreencast<T extends Constructor>(Base: T) {
+  return class extends Base {
+    declare config: ExplorbotConfig | undefined;
+    declare savedFiles: Set<string>;
+    declare playwright: { recorder: PlaywrightRecorder; helper: any } | undefined;
+
+    private screencastPage: any = null;
+    private screencastActive = false;
+    private screencastPath: string | null = null;
+    private screencastListenersInstalled = false;
+    private screencastTask: any = null;
+    private screencastLastChapter: string | null = null;
+    private onTestBefore?: (test: any) => void;
+    private onStepPassed?: (step: any) => void;
+    private onTestAfter?: () => void;
+
+    isScreencastActive(): boolean {
+      return this.screencastActive;
+    }
+
+    attachScreencast(): void {
+      if (this.screencastListenersInstalled) return;
+      if (!this.config?.ai?.agents?.historian?.screencast) return;
+      if (!this.playwright?.helper) return;
+
+      this.onTestBefore = (test: any) => {
+        void this.startScreencast(test);
+      };
+      this.onStepPassed = (step: any) => {
+        void this.emitChapter(step);
+      };
+      this.onTestAfter = () => {
+        void this.stopScreencast();
+      };
+
+      codeceptjs.event.dispatcher.on('test.before', this.onTestBefore);
+      codeceptjs.event.dispatcher.on('step.passed', this.onStepPassed);
+      codeceptjs.event.dispatcher.on('test.after', this.onTestAfter);
+
+      this.screencastListenersInstalled = true;
+    }
+
+    private async startScreencast(test: any): Promise<void> {
+      if (this.screencastActive) return;
+      const page = this.playwright?.helper?.page;
+      if (!page?.screencast?.start) return;
+
+      const task = test?._explorbotTest;
+      const scenarioName = task?.scenario || test?.title || 'scenario';
+      const planTitle: string | undefined = task?.plan?.title;
+      const planTests: any[] | undefined = task?.plan?.tests;
+      const index = planTests && task ? planTests.indexOf(task) + 1 : 0;
+
+      const parts: string[] = [];
+      if (planTitle) parts.push(safeFilename(planTitle));
+      if (index > 0) parts.push(String(index));
+      parts.push(safeFilename(scenarioName));
+
+      const dir = outputPath('screencasts');
+      mkdirSync(dir, { recursive: true });
+      const filePath = join(dir, `${parts.join('-')}.webm`);
+
+      const screencastConfig = this.config?.ai?.agents?.historian?.screencast;
+      const screencastOpts = typeof screencastConfig === 'object' ? screencastConfig : {};
+      const size = screencastOpts.size ?? page.viewportSize?.() ?? undefined;
+      const quality = screencastOpts.quality ?? 95;
+
+      try {
+        await page.screencast.start({ path: filePath, quality, size });
+        await page.screencast.showActions({ position: 'top-left' });
+        this.screencastPage = page;
+        this.screencastPath = filePath;
+        this.screencastActive = true;
+        this.screencastTask = test?._explorbotTest || null;
+        this.screencastLastChapter = null;
+      } catch (err) {
+        tag('substep').log(`Screencast start failed: ${(err as Error).message}`);
+      }
+    }
+
+    private async emitChapter(_step: any): Promise<void> {
+      if (!this.screencastActive) return;
+      const explanation = this.screencastTask?.activeNote?.getMessage?.();
+      if (!explanation) return;
+      if (explanation === this.screencastLastChapter) return;
+      this.screencastLastChapter = explanation;
+      try {
+        await this.screencastPage.screencast.showChapter(explanation);
+      } catch (err) {
+        debugLog('screencast.showChapter failed:', err);
+      }
+    }
+
+    async stopScreencast(): Promise<void> {
+      if (!this.screencastActive) return;
+      const path = this.screencastPath;
+      const task = this.screencastTask;
+      try {
+        await this.screencastPage.screencast.stop();
+      } catch (err) {
+        tag('substep').log(`Screencast stop failed: ${(err as Error).message}`);
+      }
+      this.screencastActive = false;
+      this.screencastPage = null;
+      this.screencastPath = null;
+      this.screencastTask = null;
+      this.screencastLastChapter = null;
+      if (path) {
+        this.savedFiles.add(path);
+        task?.addArtifact?.(path);
+        tag('substep').log(`Saved screencast: ${relativeToCwd(path)}`);
+      }
+    }
+  };
+}

package/src/ai/historian.ts

@@ -10,13 +10,14 @@ import { relativeToCwd } from '../utils/next-steps.ts';
 import { type CodeceptJSMethods, WithCodeceptJS } from './historian/codeceptjs.ts';
 import { type ExperienceMethods, WithExperience } from './historian/experience.ts';
 import { type PlaywrightMethods, WithPlaywright } from './historian/playwright.ts';
+import { type ScreencastMethods, WithScreencast } from './historian/screencast.ts';
 import type { Provider } from './provider.ts';
 
 export { isNonReusableCode } from './historian/utils.ts';
 
-const HistorianBase = WithPlaywright(WithCodeceptJS(WithExperience(Object as unknown as new (...args: any[]) => object)));
+const HistorianBase = WithScreencast(WithPlaywright(WithCodeceptJS(WithExperience(Object as unknown as new (...args: any[]) => object))));
 
-export interface Historian extends ExperienceMethods, CodeceptJSMethods, PlaywrightMethods {}
+export interface Historian extends ExperienceMethods, CodeceptJSMethods, PlaywrightMethods, ScreencastMethods {}
 
 export class Historian extends HistorianBase {
   declare provider: Provider;
@@ -24,18 +25,19 @@ export class Historian extends HistorianBase {
   declare reporter: Reporter | undefined;
   declare stateManager: StateManager | undefined;
   declare config: ExplorbotConfig | undefined;
-  declare recorder: PlaywrightRecorder | undefined;
+  declare playwright: { recorder: PlaywrightRecorder; helper: any } | undefined;
   declare savedFiles: Set<string>;
 
-  constructor(provider: Provider, experienceTracker?: ExperienceTracker, reporter?: Reporter, stateManager?: StateManager, config?: ExplorbotConfig, recorder?: PlaywrightRecorder) {
+  constructor(provider: Provider, experienceTracker?: ExperienceTracker, reporter?: Reporter, stateManager?: StateManager, config?: ExplorbotConfig, playwright?: { recorder: PlaywrightRecorder; helper: any }) {
     super();
     this.provider = provider;
     this.experienceTracker = experienceTracker || new ExperienceTracker();
     this.reporter = reporter;
     this.stateManager = stateManager;
     this.config = config;
-    this.recorder = recorder;
+    this.playwright = playwright;
     this.savedFiles = new Set();
+    this.attachScreencast();
   }
 
   isPlaywrightFramework(): boolean {

package/src/ai/pilot.ts

@@ -89,15 +89,16 @@ export class Pilot implements Agent {
     const notes = task.notesToString() || 'No notes recorded.';
 
     let visualAnalysis = '';
+    let screenshotState: ActionResult | null = null;
     if (this.provider.hasVision()) {
       try {
         const action = this.explorer.createAction();
-        const screenshotState = await action.caputrePageWithScreenshot();
+        screenshotState = await action.caputrePageWithScreenshot();
         if (screenshotState.screenshot) {
           visualAnalysis = (await this.researcher.answerQuestionAboutScreenshot(screenshotState, `Describe current page state relevant to: ${task.scenario}`)) || '';
         }
       } catch {
-        // vision not available, continue without
+        screenshotState = null;
       }
     }
 
@@ -167,26 +168,23 @@ export class Pilot implements Agent {
         return false;
       }
 
-      if (result.requestVerification && navigator) {
+      if (result.decision === 'pass' && result.requestVerification && navigator) {
         tag('substep').log(`Pilot requesting verification: ${result.requestVerification}`);
-        try {
-          const verifyResult = await navigator.verifyState(result.requestVerification, currentState);
-          if (verifyResult.verified) {
-            if (verifyResult.assertionSteps?.length) {
-              this.explorer.getPlaywrightRecorder().recordVerification(verifyResult.assertionSteps);
-            }
-            tag('substep').log(`Pilot verified: ${result.requestVerification}`);
-          } else {
-            tag('substep').log(`Pilot verification failed: ${result.requestVerification}`);
-            if (result.decision === 'pass') {
-              const flipMessage = `Verification "${result.requestVerification}" did not match the page. Adjust approach and re-verify before finishing.`;
-              result.decision = 'continue';
-              result.reason = flipMessage;
-              result.guidance = result.guidance ?? flipMessage;
-            }
+        const verifyResult = await navigator.verifyState(result.requestVerification, currentState).catch(() => null);
+        if (verifyResult?.verified) {
+          if (verifyResult.assertionSteps?.length) {
+            this.explorer.getPlaywrightRecorder().recordVerification(verifyResult.assertionSteps);
+          }
+        } else {
+          let answer: string | null = null;
+          if (screenshotState?.screenshot) {
+            answer = await this.researcher.answerQuestionAboutScreenshot(screenshotState, `Does the screen confirm: "${result.requestVerification}"? Answer YES or NO only.`);
+          }
+          if (!(answer || '').trim().toUpperCase().startsWith('YES')) {
+            task.addNote(`Pilot: verification failed — ${result.requestVerification}`, TestResult.FAILED);
+            task.finish(TestResult.FAILED);
+            return false;
           }
-        } catch (verifyErr: any) {
-          tag('warning').log(`Pilot verification errored: ${verifyErr.message}`);
         }
       }
 
@@ -389,6 +387,8 @@ export class Pilot implements Agent {
       - If no verification was done → prefer "continue" with guidance telling tester what to verify.
       - If verify assertion describes a state that was ALREADY TRUE before the test started, the verification proves nothing — reject with "continue".
 
+      requestVerification — pick assertions DOM can actually express. Some content is not assertable via DOM (iframe text, canvas, custom widgets, Monaco/CodeMirror editors). When the scenario goal lives in such a region, target a STABLE LANDMARK (container element, ARIA role, the parent that wraps the widget) rather than literal text inside it. Your "pass" verdict is honored even if the DOM assertion can't be made — pick the strongest landmark you can.
+
       GUIDANCE FIELD: When decision is "continue", you MUST provide "guidance" — a specific actionable instruction:
       - If evidence is insufficient: tell tester to verify with see()/verify(), specify WHAT to check
       - If approach was wrong: tell tester to try a different method, suggest which one
@@ -470,7 +470,7 @@ export class Pilot implements Agent {
     );
   }
 
-  async reviewNewPage(task: Test, currentState: ActionResult): Promise<string> {
+  async reviewNewPage(task: Test, currentState: ActionResult, testerConversation: Conversation): Promise<string> {
     if (!this.conversation) return '';
 
     tag('substep').log('Pilot reviewing new page...');
@@ -481,8 +481,14 @@ export class Pilot implements Agent {
     if (!pageSummary) return '';
 
     const stateContext = this.buildStateContext(currentState);
+    const toolCalls = testerConversation
+      .getToolExecutions()
+      .filter((t: any) => t.wasSuccessful)
+      .slice(-this.stepsToReview);
+    const actionsContext = this.formatActions(toolCalls);
 
     this.conversation.cleanupTag('page_summary', '...trimmed...', 1);
+    this.conversation.cleanupTag('recent_actions', '...trimmed...', 2);
 
     return this.sendToPilot(
       dedent`
@@ -497,6 +503,10 @@ export class Pilot implements Agent {
         ${pageSummary}
         </page_summary>
 
+        <recent_actions>
+        ${actionsContext || 'None'}
+        </recent_actions>
+
         ${this.formatExpectations(task)}
 
         First: evaluate whether this navigation makes sense for the scenario goal. If the page is unrelated, instruct Tester to back() or reset(). Then plan next steps.

package/src/ai/rules.ts

@@ -282,11 +282,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/src/ai/session-analyst.ts

@@ -0,0 +1,133 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import dedent from 'dedent';
+import { outputPath } from '../config.ts';
+import { Stats } from '../stats.ts';
+import type { Test } from '../test-plan.ts';
+import type { Agent } from './agent.ts';
+import type { Provider } from './provider.ts';
+
+export class SessionAnalyst implements Agent {
+  emoji = '🧐';
+  private provider: Provider;
+
+  constructor(provider: Provider) {
+    this.provider = provider;
+  }
+
+  async analyze(tests: Test[]): Promise<string> {
+    const eligible = tests.filter((t) => t.startTime != null);
+    if (eligible.length === 0) return '';
+
+    const model = this.provider.getModelForAgent('analyst');
+    const customPrompt = this.provider.getSystemPromptForAgent('analyst', undefined);
+
+    const systemPrompt = dedent`
+      You write a brief end-of-session report after autonomous exploratory testing. Your reader is a developer who needs to know in seconds: what is broken, how to reproduce it, and which results were inconclusive.
+
+      Output MARKDOWN. No JSON, no preamble, no closing remarks. Start with the heading.
+
+      ## Clustering
+      Group by ROOT CAUSE, not by scenario. If three tests fail for the same dropdown, that is ONE defect listing all three test refs (#3, #5, #7). Do not produce one cluster per test.
+
+      ## Bucketing
+      Use the FINAL verdict (the test's \`result\` field) as the starting point. Mid-test errors that the automation recovered from do NOT make a passed test unreliable.
+
+      - **Defect** — real product bug. \`result: failed\` AND the failure reflects the app misbehaving (not the automation). The automation completed its interactions, the app contradicted the expected outcome. Severity required.
+      - **UX issue** — app works but the UI is ambiguous, controls are hidden, or labels are unclear. Worth flagging to design.
+      - **Execution issue** — the FINAL verdict is unreliable. Only two cases:
+        1. \`result: failed\` AND the failure was automation, environment, or UI/UX (locator missing, timeout, AI loop, navigation stuck, modal trapped focus, no accessible label) — i.e. the test could not conclude whether the app works.
+        2. \`result: passed\` AND clear evidence in the log shows the user-visible goal was NOT achieved (no confirmation visible, no state change verified, the assertion was vacuous).
+
+      A test that passed and shows no contrary evidence belongs in NO section. Do not list passed tests just because the log contains intermediate retries or recovered failures.
+
+      ## Severity emoji (defects only)
+      - 🔴 critical or high — core flow blocked, data loss, security
+      - 🟡 medium — partial breakage with workaround
+      - 🟢 low — cosmetic
+
+      ## Required format
+
+      # Session Analysis
+
+      <one sentence: total tests, defect count, headline finding>
+
+      ## Defects
+
+      ### 🔴 <plain-English title of the BUG, not the scenario name>
+      Affects: #3, #5, #7
+      Reproduce:
+        1. <concrete UI step a person can replay>
+        2. <next step>
+      Evidence: <one short observation from the test log>
+
+      ### 🟡 <next defect>
+      ...
+
+      ## UX issues
+
+      - **<title>** — #4
+        <one short evidence line>
+
+      ## Execution Issues
+
+      - **<short test name or scenario phrase>** — <plain-English one-liner: what made the result unreliable>
+      - **<…>** — <…>
+
+      ## Rules
+      - Defects first, sorted by severity descending. Omit any section that has zero entries.
+      - Defect title describes the BUG ("Run-type dropdown does not filter"), never the scenario name.
+      - Reproduce steps are concrete UI actions derived from the log: URL + clicks + inputs. Imperative, one short line each.
+      - Evidence is the smallest factual observation from notes/steps that supports the claim — what was OBSERVED in the page (HTML, message, missing element). Never quote the test's \`result\` field as evidence; that is a tautology.
+      - **Execution Issues** entries must explain what actually went wrong in concrete terms a human understands: "could not find a Submit button after navigation", "page reloaded before the assertion ran", "passed without ever seeing a confirmation message", "marked failed but the new item appears in the list", "modal trapped focus and tests could not click outside", "ARIA tree had no labelled controls". Avoid jargon like "locator failed" without context. Never write category prefixes ("execution:", "false-positive:") — the section header already says it. No emoji on these entries.
+      - Do NOT include a passed test in any section unless evidence proves its goal was not achieved. Intermediate retries or recovered errors in the log are not grounds for listing a passed test.
+      - No editorialising, no restating the scenario verbatim, no closing summary.
+
+      ${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 (response?.text || '').trim();
+  }
+
+  writeReport(markdown: string): string {
+    const filePath = outputPath('reports', `${Stats.sessionLabel()}.md`);
+    const dir = path.dirname(filePath);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    writeFileSync(filePath, markdown);
+    return filePath;
+  }
+
+  private serializeTest(test: Test, ref: number): string {
+    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>
+    `;
+  }
+}

package/src/ai/tester.ts

@@ -268,7 +268,7 @@ export class Tester extends TaskAgent implements Agent {
             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) {
               const guidance = await this.pilot.analyzeProgress(task, currentState, conversation);
@@ -463,6 +463,8 @@ export class Tester extends TaskAgent implements Agent {
 
     let context = '';
 
+    const focusArea = detectFocusArea(currentState.ariaSnapshot);
+
     const focusedElement = extractFocusedElement(currentState.ariaSnapshot);
     if (focusedElement) {
       const isTextInput = ['textbox', 'combobox', 'searchbox'].includes(focusedElement.role);
@@ -480,6 +482,18 @@ export class Tester extends TaskAgent implements Agent {
       `;
     }
 
+    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) {
       const iframeInfo = currentState.iframeURL || this.explorer.getCurrentIframeInfo() || 'iframe context active';
       context += dedent`
@@ -539,7 +553,6 @@ export class Tester extends TaskAgent implements Agent {
       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) {

package/src/commands/base-command.ts

@@ -38,17 +38,17 @@ export abstract class BaseCommand {
   printSuggestions(): void {
     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'));
   }
 
   protected parseArgs(args: string): { opts: Record<string, string | boolean>; args: string[] } {

package/src/commands/drill-command.ts

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

package/src/commands/exit-command.ts

@@ -10,6 +10,7 @@ export class ExitCommand extends BaseCommand {
   aliases = ['quit'];
 
   async execute(_args: string): Promise<void> {
+    await this.explorBot.printSessionAnalysis();
     await this.explorBot.getExplorer().stop();
 
     if (Stats.hasActivity()) {