explorbot 0.5.10 → 0.6.0

package/src/ai/tester.ts

@@ -11,16 +11,16 @@ import { Observability } from '../observability.ts';
 import { type StateTransition, normalizeUrl } from '../state-manager.ts';
 import { Stats } from '../stats.ts';
 import { type Test, TestResult, type TestResultType } from '../test-plan.ts';
-import { ErrorPageError, isErrorPage } from '../utils/error-page.ts';
+import { ErrorPageError, TestStartBlockedError, isErrorPage } from '../utils/error-page.ts';
 import { createDebug, tag } from '../utils/logger.ts';
 import { loop } from '../utils/loop.ts';
 import { compactErrorMessage } from '../utils/strings.ts';
+import { isSamePageIgnoringQuery } from '../utils/url-matcher.ts';
 import type { Agent, AgentDeps } from './agent.ts';
-import type { Captain } from './captain.ts';
 import type { Conversation } from './conversation.ts';
+import { pageEvidence } from './judge.ts';
 import { Navigator } from './navigator.ts';
 import type { Pilot } from './pilot.ts';
-import { Provider } from './provider.ts';
 import { Researcher } from './researcher.ts';
 import { actionRule, capabilityGroundingRule, dataProtectionRules, focusedElementRule, formRequirementsRule, locatorRule, multipleTabsRule, sectionContextRule } from './rules.ts';
 import { TaskAgent } from './task-agent.ts';
@@ -48,7 +48,7 @@ export class Tester extends TaskAgent implements Agent {
   private testRun: TestRun | null = null;
   private currentConversation: Conversation | null = null;
   private pilot: Pilot | null = null;
-  private captain: Captain | null = null;
+  private supervisor: Supervisor | null = null;
 
   MAX_ITERATIONS = 30;
   MAX_EXTENSIONS = 2;
@@ -90,8 +90,8 @@ export class Tester extends TaskAgent implements Agent {
     this.pilot = pilot;
   }
 
-  setCaptain(captain: Captain): void {
-    this.captain = captain;
+  setSupervisor(supervisor: Supervisor): void {
+    this.supervisor = supervisor;
   }
 
   private getCurrentState(): ActionResult {
@@ -124,7 +124,6 @@ export class Tester extends TaskAgent implements Agent {
     this.previousRegionPresent = null;
     this.regionTransitioned = false;
     this.stateManager.clearHistory();
-    this.resetFailureCount();
     this.pilot?.reset();
 
     const requestStore = this.requestStore;
@@ -154,6 +153,11 @@ export class Tester extends TaskAgent implements Agent {
       offFailedRequest?.();
       return await this.abortStartedTestOnErrorPage(task, initialState);
     }
+    const startEvidence = { ...pageEvidence(initialState), scenario: task.scenario, expected: task.expected, plannedSteps: task.plannedSteps, notes: task.notesToString() };
+    if ((await this.judge?.assert('This is the right page to start the test', startEvidence)) === false) {
+      offFailedRequest?.();
+      throw new TestStartBlockedError(task.scenario, task.startUrl, initialState.url || '');
+    }
 
     const conversation = this.provider.startConversation(this.getSystemMessage(), 'tester');
     conversation.markLastMessageCacheable();
@@ -259,7 +263,7 @@ export class Tester extends TaskAgent implements Agent {
       shouldContinue = false;
 
       await loop(
-        async ({ stop, pause, iteration, userInput }) => {
+        async ({ stop, iteration, userInput }) => {
           if (opts.deadline != null && Date.now() >= opts.deadline) {
             deadlineReached = true;
             task.addNote('Time budget reached. Stopped');
@@ -267,17 +271,11 @@ export class Tester extends TaskAgent implements Agent {
             return;
           }
           debugLog('iteration', iteration);
-          if (!(await this.explorer.recover()).ok) {
-            task.addNote('Browser page is unavailable');
-            task.finish(TestResult.FAILED);
-            stop();
-            return;
-          }
           const currentState = this.getCurrentState();
 
           const tools = {
             ...codeceptjsTools,
-            ...this.createTestFlowTools(task, currentState, conversation),
+            ...this.createTestFlowTools(task, conversation),
             ...this.agentTools,
           };
           if (currentState.isInsideIframe) {
@@ -315,7 +313,7 @@ export class Tester extends TaskAgent implements Agent {
           conversation.compactToolResults(2);
 
           if (iteration > 1) {
-            const isNewPage = this.previousUrl !== null && this.previousUrl !== currentState.url;
+            const isNewPage = this.previousUrl !== null && !isSamePageIgnoringQuery(this.previousUrl, currentState.url);
             let nextStep = '';
             nextStep += await this.reinjectContextIfNeeded(iteration, currentState);
             nextStep += await this.prepareInstructionsForNextStep(task);
@@ -331,7 +329,6 @@ export class Tester extends TaskAgent implements Agent {
                 guidance = await this.pilot.periodicAnalyzeProgress(task, currentState, conversation);
               }
               if (guidance) nextStep += `\n\n${guidance}`;
-              this.consecutiveFailures = 0;
               this.lastAnalyzedStateHash = currentState.hash;
             }
             conversation.addUserText(nextStep);
@@ -357,14 +354,6 @@ export class Tester extends TaskAgent implements Agent {
           assertionPerformed = !!successfulToolNames.find((toolName: string) => this.ASSERTION_TOOLS.includes(toolName));
           const wasSuccessful = result?.toolExecutions?.every((execution: any) => execution.wasSuccessful);
 
-          this.trackToolExecutions(result?.toolExecutions || []);
-
-          if (this.consecutiveEmptyResults >= 5) {
-            task.addNote('AI model is not responding with actions. Stopped');
-            stop();
-            return;
-          }
-
           if (actionPerformed && !wasSuccessful) {
             const noted = new Set(Object.values(task.notes).map((note) => note.message));
             result?.toolExecutions
@@ -419,10 +408,10 @@ export class Tester extends TaskAgent implements Agent {
         {
           maxAttempts: this.MAX_ITERATIONS,
           interruptPrompt: 'Test interrupted. Enter new instruction (or "stop" to cancel):',
-          onInterrupt: this.captain
+          onInterrupt: this.supervisor
             ? async (userInput, context) => {
                 if (!userInput) return;
-                const result = await this.captain!.processSupervisorInterrupt(userInput, task);
+                const result = await this.supervisor!(userInput, task);
                 tag('info').log(`🧑‍✈️ Supervisor: ${result.action} — ${result.message}`);
 
                 const terminalResults: Record<string, (typeof TestResult)[keyof typeof TestResult]> = {
@@ -500,12 +489,10 @@ export class Tester extends TaskAgent implements Agent {
   }
 
   private get isStruggling(): boolean {
-    return this.consecutiveFailures >= 3 || this.consecutiveEmptyResults >= 2;
+    return this.stalledIterations >= this.MAX_STALLED_ITERATIONS - 1;
   }
 
   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.DELEGATED_ACTION_TOOLS, ...this.SPECIAL_CONTEXT_ACTION_TOOLS];
@@ -517,14 +504,7 @@ export class Tester extends TaskAgent implements Agent {
       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 further browser progress on unchanged page; requesting final review');
-    return true;
+    return this.shouldStopAfterStall(task, 'No further browser progress on unchanged page; requesting final review');
   }
 
   private async prepareInstructionsForNextStep(task: Test): Promise<string> {
@@ -948,9 +928,8 @@ export class Tester extends TaskAgent implements Agent {
     return '';
   }
 
-  private createTestFlowTools(task: Test, currentState: ActionResult, conversation: Conversation) {
+  private createTestFlowTools(task: Test, conversation: Conversation) {
     const resetUrl = task.startUrl;
-    const visitedUrls = task.getVisitedUrls();
     return {
       reset: tool({
         description: dedent`
@@ -1161,9 +1140,6 @@ export class Tester extends TaskAgent implements Agent {
             }
           }
 
-          const remainingExpectations = task.getRemainingExpectations();
-          // const suggestion = input.status !== null && remainingExpectations.length > 0 ? `Continue testing to check the remaining expected outcomes: ${remainingExpectations.join(', ')}` : 'Continue with your testing strategy based on these findings.';
-
           return {
             success: true,
             action: 'record',
@@ -1190,11 +1166,10 @@ export class Tester extends TaskAgent implements Agent {
     }
 
     if (result.recovered) {
-      this.resetFailureCount();
       this.previousUrl = null;
       this.previousStateHash = null;
       this.stalledIterations = 0;
-    } else if (this.shouldStopAfterStalledLoopError(task)) {
+    } else if (this.shouldStopAfterStall(task, 'No browser progress after repeated execution errors; requesting final review')) {
       return 'stop';
     }
 
@@ -1202,13 +1177,13 @@ export class Tester extends TaskAgent implements Agent {
     return 'continue';
   }
 
-  private shouldStopAfterStalledLoopError(task: Test): boolean {
+  private shouldStopAfterStall(task: Test, note: string): 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; requesting final review');
+    task.addNote(note);
     return true;
   }
 
@@ -1226,6 +1201,13 @@ interface TestSessionHandlers {
   offFailedRequest?: () => void;
 }
 
+export type Supervisor = (input: string, test: Test) => Promise<SupervisorAction>;
+
+export interface SupervisorAction {
+  action: 'inject' | 'stop' | 'pass' | 'skip';
+  message: string;
+}
+
 export interface TestOptions {
   startOnCurrentPage?: boolean;
   deadline?: number;

package/src/ai/tools.ts

@@ -1,7 +1,7 @@
 import { tool } from 'ai';
 import dedent from 'dedent';
 import { z } from 'zod';
-import { ActionResult, type PageDiff, type ToolResultMetadata } from '../action-result.ts';
+import { ActionResult, type PageDiff } from '../action-result.ts';
 import type { ExecutedStep } from '../action.ts';
 import { type ExperienceTracker, renderExperienceRecipes } from '../experience-tracker.ts';
 import { Stats } from '../stats.ts';
@@ -65,8 +65,8 @@ export function createCodeceptJSTools({ explorer, stateManager, judge }: ToolDep
           Never mix different elements — use separate click() calls instead.
           REQUIRED: include at least one command WITHOUT a container — a wrong or stale container always fails.
           Order by reliability:
-          1. I.click(text, container) - when the container is verified - e.g. I.click("Save", ".modal")
-          2. I.click(ARIA, container) - e.g. I.click({"role":"button","text":"Save"}, ".modal")
+          1. I.click(ARIA, container) - e.g. I.click({"role":"button","text":"Save"}, ".modal")
+          2. I.click(text, container) - when the container is verified - e.g. I.click("Save", ".modal")
           3. I.click(CSS, container) - e.g. I.click("#btn", ".modal")
           4. I.click(CSS) or I.click(XPath) - when locator already includes context (ID, XPath)
           After a result reporting multiple matches, reuse that locator with step.opts({ elementIndex: N }) as the last argument.
@@ -292,7 +292,7 @@ export function createCodeceptJSTools({ explorer, stateManager, judge }: ToolDep
           const normalizedKey = key.toLowerCase();
           const matchingStandardKey = Array.from(standardKeys).find((sk) => sk.toLowerCase() === normalizedKey);
           const isStandardKey = !!matchingStandardKey;
-          const keyToUse = matchingStandardKey || key;
+          const keyToUse = KEY_ALIASES[matchingStandardKey || ''] || matchingStandardKey || key;
 
           if (!isSingleChar && !isStandardKey) {
             const previousState = ActionResult.fromState(stateManager.getCurrentState()!);
@@ -480,7 +480,7 @@ export function createCodeceptJSTools({ explorer, stateManager, judge }: ToolDep
               commandsExecuted: lines.length,
               attempts: action.executedSteps,
               code: codeBlock,
-              suggestion: 'Verify the form was filled in correctly using see() tool. If needed to submit: try click() tool or form() with I.pressKey("Enter").',
+              suggestion: 'Check the filled values with verify() before submitting, then submit with click().',
             },
             action
           );
@@ -678,7 +678,7 @@ export function createAgentTools({ explorer, stateManager, ai, judge, researcher
       inputSchema: z.object({
         reason: z.string().describe('Why do you need fresh context? Required to prevent overuse.'),
       }),
-      execute: async ({ reason }) => {
+      execute: async () => {
         try {
           const currentState = stateManager.getCurrentState();
 
@@ -760,6 +760,7 @@ export function createAgentTools({ explorer, stateManager, ai, judge, researcher
           }
 
           return failedToolResult('verify', `Verification failed: ${assertion}`, {
+            attempts: result.results.map(({ code, passed, error }) => ({ code, passed, error })),
             suggestion: 'The assertion could not be verified. Check if the condition is actually present on the page or try a different assertion.',
           });
         } catch (error) {
@@ -793,7 +794,7 @@ export function createAgentTools({ explorer, stateManager, ai, judge, researcher
       inputSchema: z.object({
         reason: z.string().describe('Why do you need research? What information is missing from existing context?'),
       }),
-      execute: async ({ reason }) => {
+      execute: async () => {
         try {
           const currentState = stateManager.getCurrentState();
 
@@ -907,7 +908,7 @@ export function createAgentTools({ explorer, stateManager, ai, judge, researcher
         element: z.string().describe('Visual description of element to click (e.g., "blue Submit button in the modal footer", "Settings gear icon in top right")'),
         context: z.string().describe('What you already tried and why it failed - helps with accurate identification'),
       }),
-      execute: async ({ element, context }) => {
+      execute: async ({ element }) => {
         if (Stats.visionDisabled) {
           return failedToolResult('visualClick', 'Vision tools are disabled for this session. Use xpathCheck() to find the element, then click() with the discovered locator.');
         }
@@ -1058,7 +1059,7 @@ export function createAgentTools({ explorer, stateManager, ai, judge, researcher
         xpath: z.string().describe('XPath expression — use broad patterns to avoid missing the element'),
         reason: z.string().describe('What element you are looking for and why'),
       }),
-      execute: async ({ xpath, reason }) => {
+      execute: async ({ xpath }) => {
         const currentState = stateManager.getCurrentState();
 
         if (!currentState) {
@@ -1202,6 +1203,7 @@ const ARIA_OUTPUT_CAP = 4000;
 const HTML_OUTPUT_CAP = 6000;
 const ANALYSIS_OUTPUT_CAP = 2000;
 const JUDGE_RECENT_ACTIONS_LIMIT = 8;
+const KEY_ALIASES: Record<string, string> = { Esc: 'Escape', Del: 'Delete' };
 
 function cap(text: string | undefined | null, max: number): string {
   if (!text) return '';

package/src/application-spec.ts

@@ -10,6 +10,7 @@ import { loadMarkdownFiles } from './utils/markdown-files.ts';
 export class ApplicationSpec {
   private pages: ApplicationSpecPage[] = [];
   readonly sourcePath: string;
+  private totalMarkdownFiles = 0;
 
   constructor(sourcePath: string) {
     this.sourcePath = this.resolveSourcePath(sourcePath);
@@ -38,28 +39,27 @@ export class ApplicationSpec {
     return this.pages.length;
   }
 
+  get markdownFileCount(): number {
+    return this.totalMarkdownFiles;
+  }
+
   private load(): void {
     if (!existsSync(this.sourcePath)) {
       throw new Error(`Application spec not found: ${this.sourcePath}`);
     }
 
     const isDirectory = statSync(this.sourcePath).isDirectory();
-    if (!isDirectory && path.basename(this.sourcePath).toLowerCase() !== 'index.md') {
-      throw new Error(`Application spec file must be index.md: ${this.sourcePath}`);
-    }
-
     const bundlePath = isDirectory ? this.sourcePath : path.dirname(this.sourcePath);
+
+    const allFiles = loadMarkdownFiles(bundlePath, { recursive: true });
     const indexPath = path.join(bundlePath, 'index.md');
-    if (!existsSync(indexPath)) {
-      throw new Error(`Application spec index not found: ${indexPath}`);
-    }
+    this.totalMarkdownFiles = allFiles.filter((file) => path.resolve(file.filePath) !== path.resolve(indexPath)).length;
 
-    const pagesPath = path.join(bundlePath, 'pages');
-    if (!existsSync(pagesPath)) {
-      throw new Error(`Application spec pages directory not found: ${pagesPath}`);
-    }
+    for (const file of allFiles) {
+      if (path.resolve(file.filePath) === path.resolve(indexPath)) continue;
+
+      if (!file.data.url && file.data.format === undefined && file.data.version === undefined) continue;
 
-    for (const file of loadMarkdownFiles(pagesPath, { recursive: true })) {
       const parsed = APPLICATION_SPEC_PAGE_SCHEMA.safeParse(file.data);
       if (!parsed.success && parsed.error.issues.some((issue) => issue.path[0] === 'format')) {
         throw new Error(`Invalid application spec format in ${file.filePath}`);
@@ -73,8 +73,14 @@ export class ApplicationSpec {
       this.pages.push({ url: parsed.data.url, content: file.content.trim() });
     }
 
+    if (this.totalMarkdownFiles === 0) {
+      tag('warning').log(`No markdown files found in spec: ${bundlePath}`);
+      return;
+    }
+
     if (this.pages.length === 0) {
-      throw new Error(`Application spec contains no documented pages: ${pagesPath}`);
+      tag('debug').log(`${this.totalMarkdownFiles} spec files found in ${bundlePath}`);
+      return;
     }
   }
 

package/src/commands/clean-command.ts

@@ -1,5 +1,5 @@
 import { existsSync, readdirSync, rmSync, statSync, unlinkSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { join } from 'node:path';
 import { ConfigParser, outputPath } from '../config.js';
 import { tag } from '../utils/logger.js';
 import { BaseCommand, type Suggestion } from './base-command.js';

package/src/commands/context-command.ts

@@ -1,4 +1,3 @@
-import { ActionResult } from '../action-result.js';
 import { Researcher } from '../ai/researcher.js';
 import { visuallyAnnotateContainers } from '../ai/researcher/coordinates.js';
 import { outputPath } from '../config.js';

package/src/commands/context-experience-command.ts

@@ -9,7 +9,6 @@ export class ContextExperienceCommand extends BaseCommand {
   description = 'Print all matching experience for current page';
 
   async execute(_args: string): Promise<void> {
-    const explorer = this.explorBot.getExplorer();
     const state = this.explorBot.stateManager().getCurrentState();
 
     if (!state) {

package/src/commands/context-knowledge-command.ts

@@ -9,7 +9,6 @@ export class ContextKnowledgeCommand extends BaseCommand {
   description = 'Print all matching knowledge for current page';
 
   async execute(_args: string): Promise<void> {
-    const explorer = this.explorBot.getExplorer();
     const state = this.explorBot.stateManager().getCurrentState();
 
     if (!state) {

package/src/commands/explore-command.ts

@@ -6,7 +6,7 @@ import { Stats } from '../stats.js';
 import { type Plan, type Test, TestResult } from '../test-plan.js';
 import { browserErrorMessage } from '../utils/browser-errors.ts';
 import { getCliName } from '../utils/cli-name.ts';
-import { ErrorPageError, getStateErrorPageError } from '../utils/error-page.ts';
+import { BlockedError, ErrorPageError, getStateErrorPageError } from '../utils/error-page.ts';
 import { tag } from '../utils/logger.js';
 import { type NextStepSection, printNextSteps, relativeToCwd } from '../utils/next-steps.ts';
 import { keepSiteUrls, readSitemap } from '../utils/sitemap.ts';
@@ -14,6 +14,7 @@ import { parseSpecPairs } from '../utils/spec.ts';
 import { safeFilename } from '../utils/strings.ts';
 import { UrlFilter } from '../utils/url-filter.ts';
 import { type ArgumentCompletion, BaseCommand, type Suggestion } from './base-command.js';
+import { PlanCommand } from './plan-command.js';
 
 const MAX_SUB_PAGE_ATTEMPTS = 30;
 const PRIORITY_ORDER: Record<string, number> = { critical: 0, important: 1, high: 2, normal: 3, low: 4 };
@@ -136,7 +137,7 @@ export class ExploreCommand extends BaseCommand {
   }
 
   private async runFreshMode(mainUrl: string | undefined, feature: string | undefined, styles?: string[]): Promise<void> {
-    await this.runAllStyles(mainUrl, feature, undefined, undefined, styles);
+    await this.runAllStyles(mainUrl, feature, undefined, styles);
     this.rememberCurrentPlan();
     const mainPlan = this.explorBot.getCurrentPlan();
     if (!mainPlan) return;
@@ -320,7 +321,7 @@ export class ExploreCommand extends BaseCommand {
       tag('warning').log(`Skipping page: ${errorPage.message}`);
       return false;
     }
-    await this.runAllStyles(url, feature, parentPlan, this.completedPlans, styles);
+    await this.runAllStyles(url, feature, parentPlan, styles);
     const plan = this.explorBot.getCurrentPlan();
     if (plan?.tests.length && !this.completedPlans.includes(plan)) {
       this.completedPlans.push(plan);
@@ -333,14 +334,14 @@ export class ExploreCommand extends BaseCommand {
     for (const style of styleList) {
       if (this.isLimitReached()) break;
       this.explorBot.setCurrentPlan(existingPlan);
-      const opts: { fresh: boolean; style: string; completedPlans?: Plan[]; noSave?: boolean } = { fresh: false, style, completedPlans: this.completedPlans };
+      const opts: { fresh: boolean; style: string; noSave?: boolean } = { fresh: false, style };
       if (this.dryRun) opts.noSave = true;
       await this.planWithRetry(feature, opts, pageUrl);
       await this.runPendingTests();
     }
   }
 
-  private async runAllStyles(pageUrl?: string, feature?: string, parentPlan?: Plan, completedPlans?: Plan[], styles?: string[]): Promise<void> {
+  private async runAllStyles(pageUrl?: string, feature?: string, parentPlan?: Plan, styles?: string[]): Promise<void> {
     const styleList = styles ?? Object.keys(getStyles());
     let fresh = true;
     for (const style of styleList) {
@@ -348,7 +349,7 @@ export class ExploreCommand extends BaseCommand {
       if (!fresh && pageUrl && !this.dryRun) {
         await this.explorBot.visit(pageUrl);
       }
-      const opts: { fresh: boolean; style: string; extend?: Plan; completedPlans?: Plan[]; noSave?: boolean } = { fresh, style, completedPlans };
+      const opts: { fresh: boolean; style: string; extend?: Plan; noSave?: boolean } = { fresh, style };
       if (fresh && parentPlan) opts.extend = parentPlan;
       if (this.dryRun) opts.noSave = true;
       await this.planWithRetry(feature, opts, pageUrl);
@@ -371,10 +372,14 @@ export class ExploreCommand extends BaseCommand {
     this.completedPlans.push(plan);
   }
 
-  private async planWithRetry(feature: string | undefined, opts: { fresh: boolean; style: string; extend?: Plan; completedPlans?: Plan[]; noSave?: boolean }, pageUrl?: string): Promise<void> {
+  private async planWithRetry(feature: string | undefined, opts: { fresh: boolean; style: string; extend?: Plan; noSave?: boolean }, pageUrl?: string): Promise<void> {
     const before = new Set(this.explorBot.getCurrentPlan()?.tests ?? []);
 
     await this.explorBot.plan(feature, opts);
+    if (this.explorBot.lastPlanError instanceof BlockedError) {
+      tag('warning').log(`Skipping page: ${this.explorBot.lastPlanError.message}`);
+      return;
+    }
     if (this.explorBot.lastPlanError) {
       if (this.explorBot.lastPlanError instanceof ErrorPageError) {
         throw this.explorBot.lastPlanError;
@@ -388,12 +393,15 @@ export class ExploreCommand extends BaseCommand {
       }
     }
 
-    const planAfter = this.explorBot.getCurrentPlan();
-    if (!planAfter) return;
-    const added = planAfter.tests.filter((t) => !before.has(t));
-    if (added.length === 0) return;
+    this.printAddedTests(before, opts.style, pageUrl);
+  }
+
+  private printAddedTests(before: Set<Test>, style: string, pageUrl?: string): number {
+    const added = this.explorBot.getCurrentPlan()?.tests.filter((t) => !before.has(t)) ?? [];
+    if (added.length === 0) return 0;
     const urlNote = pageUrl ? ` for ${pageUrl}` : '';
-    this.printPreview(`Planner added ${added.length} new test(s) [style=${opts.style}]${urlNote}:`, added);
+    this.printPreview(`Planner added ${added.length} new test(s) [style=${style}]${urlNote}:`, added);
+    return added.length;
   }
 
   private parseConfigure(raw: string | undefined): ConfigureSpec {
@@ -545,16 +553,7 @@ export class ExploreCommand extends BaseCommand {
     const sections: NextStepSection[] = [];
 
     if (savedPlanPath) {
-      const relPlan = relativeToCwd(savedPlanPath);
-      sections.push({
-        label: 'Plan',
-        path: savedPlanPath,
-        commands: [
-          { label: 'Re-run', command: `${cli} test ${relPlan} 1` },
-          { label: 'Run all', command: `${cli} test ${relPlan} *` },
-          { label: 'Run range', command: `${cli} test ${relPlan} 1-3` },
-        ],
-      });
+      sections.push(PlanCommand.planSection(savedPlanPath));
     }
 
     const savedFiles = this.explorBot.agentHistorian().getSavedFiles();
@@ -594,6 +593,14 @@ export class ExploreCommand extends BaseCommand {
     printNextSteps(sections);
   }
 
+  private skipBlockedTest(test: Test, error: unknown): void {
+    if (!(error instanceof BlockedError)) throw error;
+    tag('warning').log(`Skipping test: ${error.message}`);
+    test.start();
+    test.addNote(error.message, TestResult.SKIPPED);
+    test.finish(TestResult.SKIPPED);
+  }
+
   private isLimitReached(): boolean {
     if (this.maxTests != null && this.testsRun >= this.maxTests) return true;
     return this.isDeadlineReached();
@@ -628,7 +635,13 @@ export class ExploreCommand extends BaseCommand {
       test.start();
       test.finish(TestResult.SKIPPED);
     } else {
-      await this.explorBot.agentTester().test(test, { deadline: this.hardDeadlineAt });
+      const run = () => this.explorBot.agentTester().test(test, { deadline: this.hardDeadlineAt });
+      await run()
+        .catch(async (err) => {
+          if (!(await this.explorBot.agentCaptain().resolveBlocker(err, () => this.explorBot.agentNavigator().isOn(test.startUrl)))) throw err;
+          return run();
+        })
+        .catch((err) => this.skipBlockedTest(test, err));
     }
     this.testsRun++;
   }

package/src/commands/help-json-command.ts

@@ -31,12 +31,14 @@ export class HelpJsonCommand {
         required: argument.required,
         variadic: argument.variadic,
       })),
-      options: helper.visibleOptions(cmd).map((option) => ({
-        flags: option.flags,
-        description: option.description,
-        default: option.defaultValue,
-        choices: option.argChoices,
-      })),
+      options: cmd.options
+        .filter((option) => !option.hidden)
+        .map((option) => ({
+          flags: option.flags,
+          description: option.description,
+          default: option.defaultValue,
+          choices: option.argChoices,
+        })),
       commands: helper.visibleCommands(cmd).map((sub) => HelpJsonCommand.data(sub)),
     };
 

package/src/commands/init-command.ts

@@ -343,11 +343,13 @@ function printInitNextSteps(options: { url?: string; siteCommands?: NextStepComm
     }
   );
 
+  sections.push({
+    label: 'Add knowledge (logins, credentials) — created on first use in ./knowledge',
+    commands: [{ command: `${cli} learn '*' 'to authorize use these credentials: admin@example.com / secret123'` }],
+  });
+
   printNextSteps(sections);
 
-  log('');
-  log('Add knowledge (logins, credentials) — created on first use in ./knowledge:');
-  tag('substep').log(chalk.yellow(`${cli} learn '*' 'to authorize use these credentials: admin@example.com / secret123'`));
   tag('substep').log('You can use ${env.LOGIN} and ${env.PASSWORD} to reference environment variables.');
 }
 

package/src/commands/learn-command.ts

@@ -13,7 +13,6 @@ export class LearnCommand extends BaseCommand {
 
     if (!note) {
       const AddKnowledge = (await import('../components/AddKnowledge.js')).default;
-      const explorer = this.explorBot.getExplorer();
       const state = this.explorBot.stateManager().getCurrentState();
       const initialUrl = state?.url || '';
 
@@ -32,7 +31,6 @@ export class LearnCommand extends BaseCommand {
       return;
     }
 
-    const explorer = this.explorBot.getExplorer();
     const state = this.explorBot.stateManager().getCurrentState();
 
     if (!state) {