explorbot 0.1.20 → 0.1.21

package/dist/src/ai/navigator.js

@@ -1,4 +1,6 @@
+import { tool } from 'ai';
 import dedent from 'dedent';
+import { z } from 'zod';
 import { ActionResult } from '../action-result.js';
 import { ExperienceTracker, renderExperienceToc } from '../experience-tracker.js';
 import { KnowledgeTracker } from '../knowledge-tracker.js';
@@ -213,7 +215,27 @@ class Navigator {
     `;
         const conversation = this.provider.startConversation(this.systemPrompt, 'navigator');
         conversation.addUserText(prompt);
-        const tools = undefined;
+        let stopReason = null;
+        const tools = {
+            stop: tool({
+                description: dedent `
+          Stop the navigation because no locator or strategy change can reach the goal.
+          Use this when reaching the goal requires something only the user can supply or that the
+          page cannot grant from the current state — for example: an authentication failure you
+          cannot guess past, a captcha or human-verification step, a permission the test cannot
+          satisfy, a piece of data not present in the available knowledge / hint context, or a
+          blocking error or dialog you cannot dismiss.
+          Do NOT use this for locator or strategy problems — for those, emit new code blocks instead.
+        `,
+                inputSchema: z.object({
+                    reason: z.string().describe('Short user-facing explanation. Quote what you observed (alert text, dialog title, status message, validation note) and name what is missing or required.'),
+                }),
+                execute: async ({ reason }) => {
+                    stopReason = reason;
+                    return { success: true, message: 'Recorded. Navigator will stop and surface the reason.' };
+                },
+            }),
+        };
         let codeBlocks = [];
         let htmlContextAdded = false;
         let codeBlockIndex = 0;
@@ -226,6 +248,12 @@ class Navigator {
                 const result = await this.provider.invokeConversation(conversation, tools);
                 if (!result)
                     return;
+                if (stopReason) {
+                    tag('error').log(`Navigator stopped: ${stopReason}`);
+                    resolved = false;
+                    stop();
+                    return;
+                }
                 const aiResponse = result?.response?.text;
                 debugLog('AI:', aiResponse?.split('\n')[0]);
                 debugLog('Received AI response:', aiResponse?.length ?? 0, 'characters');
@@ -245,14 +273,40 @@ class Navigator {
                 tag('substep').log('Feeding failures back to AI for a new batch...');
                 let contextMsg = 'Previous solutions did not work. Analyze the failures and try DIFFERENT strategies (not syntactic variants of the same locator).\n\n';
                 if (batchFailures.length > 0) {
-                    const lines = batchFailures.map((f) => `- \`${f.code.split('\n')[0]}\` → ${f.error}`).join('\n');
+                    const lines = batchFailures
+                        .map((f) => {
+                        const head = `- \`${f.code.split('\n')[0]}\` → ${f.error}`;
+                        if (!f.ariaChanges)
+                            return head;
+                        const trimmed = f.ariaChanges.split('\n').slice(0, 12).join('\n    ');
+                        return `${head}\n  • ARIA changes after the action:\n    ${trimmed}`;
+                    })
+                        .join('\n');
                     contextMsg += `<previous_failures>\n${lines}\n</previous_failures>\n\n`;
                 }
                 if (!htmlContextAdded) {
                     htmlContextAdded = true;
                     contextMsg += `Full HTML context:\n\n<page_html>\n${await actionResult.combinedHtml()}\n</page_html>\n\n`;
                 }
-                contextMsg += 'Propose new solutions. If errors mention "intercepts pointer events" or timeouts on visible elements, an overlay is blocking — dismiss it first (Escape, click outside, Close button) before retrying the original action.';
+                const pageReacted = batchFailures.some((f) => f.ariaChanges);
+                if (pageReacted) {
+                    contextMsg += dedent `
+              Some steps in the previous batch did not throw, but the URL did not change to the expected target and the page changed in other ways — the ARIA diff for each such step is listed in <previous_failures> above.
+
+              Read those diffs and judge what each step actually triggered. Different action types produce different reactions; the diff is your only evidence of what happened. A diff might show, for example: a new alert / alertdialog / status / validation message appearing near a field or at page level; a modal, dialog, or wizard step opening; a banner, toast, or notification region appearing; a section expanding or collapsing; a tab or accordion switching content. A diff might also be empty or unrelated to the step — that is also a signal.
+
+              Choose exactly ONE path based on what the diffs actually show — do not assume the previous step submitted any particular kind of data:
+
+              A. The diff indicates the application requires something only the user can supply — for example: an authentication failure you cannot guess past, a captcha, a permission the test cannot satisfy, or knowledge that is not present in the provided context. Call the stop() tool and quote what you saw in the diff and what is needed.
+
+              B. The diff indicates the next step is something you can perform from the existing knowledge / hint context — for example: re-emit a step with a value that exists in the knowledge but was used incorrectly; dismiss an unexpected modal; accept a confirmation; take a follow-up step the page now requires. Emit code blocks for that next step. Do NOT change the locator of a step that already produced a reaction.
+
+              C. The diff is empty or unrelated to your step — the action likely missed its target. Propose a different locator strategy.
+            `;
+                }
+                else {
+                    contextMsg += 'Propose new solutions. If errors mention "intercepts pointer events" or timeouts on visible elements, an overlay is blocking — dismiss it first (Escape, click outside, Close button) before retrying the original action.';
+                }
                 conversation.addUserText(contextMsg);
                 codeBlocks = [];
                 batchFailures.length = 0;
@@ -261,7 +315,8 @@ class Navigator {
             codeBlockIndex++;
             totalAttempts++;
             await this.explorer.switchToMainFrame();
-            const prevHash = action.actionResult?.getStateHash() ?? actionResult.getStateHash();
+            const prevActionResult = action.actionResult ?? actionResult;
+            const prevHash = prevActionResult.getStateHash();
             debugLog(`Attempting resolution: ${codeBlock}`);
             const attemptOk = await action.attempt(codeBlock, message);
             const page = action.playwrightHelper?.page;
@@ -294,6 +349,23 @@ class Navigator {
                 const stateChanged = freshState.getStateHash() !== actionResult.getStateHash();
                 resolved = urlMatches && stateChanged;
                 if (!resolved && attemptOk) {
+                    let ariaChanges = null;
+                    if (freshState.getStateHash() !== prevHash) {
+                        try {
+                            const diff = await freshState.diff(prevActionResult);
+                            await diff.calculate();
+                            ariaChanges = diff.ariaChanged;
+                        }
+                        catch (err) {
+                            debugLog('Failed to compute pageDiff for failed URL verification:', err);
+                        }
+                    }
+                    batchFailures.push({
+                        code: codeBlock,
+                        error: `URL did not change (still ${freshState.url})`,
+                        ariaChanges,
+                        urlAfter: freshState.url,
+                    });
                     tag('warning').log(`URL verification failed: expected ${expectedUrl}, got ${freshState.url}`);
                 }
                 if (freshState.getStateHash() !== prevHash && (attemptOk || urlMatches)) {
@@ -343,11 +415,15 @@ class Navigator {
                 tag('success').log('Navigation resolved after delayed redirect');
             }
         }
-        if (!resolved && totalAttempts > 0) {
+        if (!resolved && stopReason) {
+            tag('error').log(`Navigator stopped: ${stopReason}`);
+        }
+        else if (!resolved && totalAttempts > 0) {
             tag('error').log(`Navigation failed after ${totalAttempts} attempts`);
         }
         if (!resolved && isInteractive()) {
-            const userInput = await pause(`Navigator failed to resolve. Current: ${action.stateManager.getCurrentState()?.url}\n` + `Target: ${expectedUrl ?? '(none)'}\nEnter CodeceptJS commands (or press Enter to skip):`);
+            const stopLine = stopReason ? `Navigator stopped: ${stopReason}\n` : '';
+            const userInput = await pause(`${stopLine}Navigator failed to resolve. Current: ${action.stateManager.getCurrentState()?.url}\n` + `Target: ${expectedUrl ?? '(none)'}\nEnter CodeceptJS commands (or press Enter to skip):`);
             if (userInput?.trim()) {
                 resolved = await action.attempt(userInput, message);
                 if (resolved && expectedUrl) {

package/dist/src/commands/index.js

@@ -24,6 +24,7 @@ import { PlanEditCommand } from './plan-edit-command.js';
 import { PlanLoadCommand } from './plan-load-command.js';
 import { PlanReloadCommand } from './plan-reload-command.js';
 import { PlanSaveCommand } from './plan-save-command.js';
+import { PlansCommand } from './plans-command.js';
 import { RerunCommand } from './rerun-command.js';
 import { ResearchCommand } from './research-command.js';
 import { RunsCommand } from './runs-command.js';
@@ -42,6 +43,7 @@ const commandClasses = [
     PlanCommand,
     PlanSaveCommand,
     PlanLoadCommand,
+    PlansCommand,
     PlanReloadCommand,
     PlanClearCommand,
     PlanEditCommand,

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

@@ -0,0 +1,83 @@
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { Plan } from '../test-plan.js';
+import { getCliName } from '../utils/cli-name.js';
+import { tag } from '../utils/logger.js';
+import { relativeToCwd } from '../utils/next-steps.js';
+import { BaseCommand } from './base-command.js';
+export class PlansCommand extends BaseCommand {
+    name = 'plans';
+    description = 'List saved plans and show their test scenarios';
+    options = [{ flags: '--from-plan <file>', description: 'Plan file to show' }];
+    async execute(args) {
+        const { opts, args: remaining } = this.parseArgs(args);
+        const files = this.getPlanFiles();
+        const target = String(opts.fromPlan || remaining[0] || '').trim();
+        if (!target) {
+            this.printPlans(files);
+            return;
+        }
+        const file = this.resolvePlanFile(target, files);
+        const plan = Plan.fromMarkdown(file.path);
+        this.printPlanDetails(plan, file);
+    }
+    getPlanFiles() {
+        const plansDir = this.explorBot.getPlansDir();
+        if (!existsSync(plansDir))
+            return [];
+        return readdirSync(plansDir)
+            .filter((file) => file.endsWith('.md'))
+            .map((file) => {
+            const filePath = path.join(plansDir, file);
+            const stat = statSync(filePath);
+            return {
+                name: file,
+                path: filePath,
+                modifiedAt: stat.mtimeMs,
+            };
+        })
+            .sort((left, right) => right.modifiedAt - left.modifiedAt);
+    }
+    printPlans(files) {
+        if (files.length === 0) {
+            tag('info').log(`No saved plans found in ${relativeToCwd(this.explorBot.getPlansDir())}`);
+            return;
+        }
+        tag('info').log('Saved plans:');
+        for (let i = 0; i < files.length; i++) {
+            const file = files[i];
+            const plan = Plan.fromMarkdown(file.path);
+            tag('info').log(`${i + 1}. ${plan.title} (${plan.tests.length} tests) - ${file.name}`);
+        }
+        tag('info').log('');
+        tag('info').log(`View plan tests: ${getCliName()} plans <number>`);
+    }
+    printPlanDetails(plan, file) {
+        tag('info').log(`${plan.title} (${plan.tests.length} tests)`);
+        for (let i = 0; i < plan.tests.length; i++) {
+            const test = plan.tests[i];
+            tag('info').log(`${i + 1}. ${test.scenario}`);
+        }
+        tag('info').log('');
+        tag('info').log('Run test from this plan as:');
+        tag('info').log(`${getCliName()} test 1 --from-plan ${file.name}`);
+    }
+    resolvePlanFile(target, files) {
+        const index = Number.parseInt(target, 10);
+        if (!Number.isNaN(index) && String(index) === target) {
+            const file = files[index - 1];
+            if (!file)
+                throw new Error(`Plan #${target} not found. Available: 1-${files.length}`);
+            return file;
+        }
+        const resolved = this.explorBot.resolvePlanPath(target);
+        if (!existsSync(resolved)) {
+            throw new Error(`Plan file not found: ${resolved}`);
+        }
+        return {
+            name: path.basename(resolved),
+            path: resolved,
+            modifiedAt: statSync(resolved).mtimeMs,
+        };
+    }
+}

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

@@ -5,12 +5,18 @@ import { BaseCommand } from './base-command.js';
 export class TestCommand extends BaseCommand {
     name = 'test';
     description = 'Launch tester agent to execute test scenarios';
+    options = [{ flags: '--from-plan <file>', description: 'Load plan file before selecting tests' }];
     suggestions = [
         { command: 'test', hint: 'run next test' },
         { command: 'plan', hint: 'create new plan' },
     ];
     async execute(args) {
+        const { opts, args: remaining } = this.parseArgs(args);
+        if (opts.fromPlan) {
+            this.explorBot.loadPlan(String(opts.fromPlan));
+        }
         const plan = this.explorBot.getCurrentPlan();
+        const selector = remaining.join(' ');
         Stats.mode = 'test';
         Stats.focus = plan?.title;
         const toExecute = [];
@@ -19,25 +25,25 @@ export class TestCommand extends BaseCommand {
                 throw new Error('No plan found. Please run /plan first to create test scenarios.');
             return plan;
         };
-        if (!args) {
+        if (!selector) {
             const pending = requirePlan().getPendingTests();
             if (pending.length === 0) {
                 throw new Error('All tests are already complete. Please run /plan to create new test scenarios.');
             }
             toExecute.push(pending[0]);
         }
-        else if (args === '*' || args === 'all') {
+        else if (selector === '*' || selector === 'all') {
             toExecute.push(...requirePlan().getPendingTests());
         }
-        else if (args.match(/^[\d,\-\s]+$/)) {
+        else if (selector.match(/^[\d,\-\s]+$/)) {
             const visible = requirePlan().tests.filter((t) => t.enabled);
-            const indices = parseTestIndices(args, visible.length);
+            const indices = parseTestIndices(selector, visible.length);
             for (const idx of indices) {
                 toExecute.push(visible[idx]);
             }
         }
         else {
-            const matching = plan?.getPendingTests().filter((test) => test.scenario.toLowerCase().includes(args.toLowerCase())) || [];
+            const matching = plan?.getPendingTests().filter((test) => test.scenario.toLowerCase().includes(selector.toLowerCase())) || [];
             if (matching.length > 0) {
                 toExecute.push(...matching);
             }
@@ -46,13 +52,13 @@ export class TestCommand extends BaseCommand {
                 if (!state) {
                     throw new Error('No page loaded. Please navigate to a page first.');
                 }
-                const newTest = new Test(args, 'unknown', [], state.url);
+                const newTest = new Test(selector, 'unknown', [], state.url);
                 if (plan) {
                     plan.addTest(newTest);
-                    tag('info').log(`Created new test: "${args}" and added to current plan.`);
+                    tag('info').log(`Created new test: "${selector}" and added to current plan.`);
                 }
                 else {
-                    tag('info').log(`Created ad-hoc test: "${args}"`);
+                    tag('info').log(`Created ad-hoc test: "${selector}"`);
                 }
                 toExecute.push(newTest);
             }

package/dist/src/playwright-recorder.js

@@ -1,6 +1,5 @@
+import { createRequire } from 'node:module';
 import { readFile } from 'node:fs/promises';
-// @ts-ignore — package ships a .js re-export without typings for this sub-path
-import * as playwrightUtils from 'playwright-core/lib/utils';
 import { createDebug } from "./utils/logger.js";
 const debugLog = createDebug('explorbot:playwright-recorder');
 const RECORDABLE = {
@@ -8,11 +7,26 @@ const RECORDABLE = {
     Page: new Set(['goBack', 'goForward', 'reload', 'keyboardPress', 'keyboardType', 'keyboardDown', 'keyboardUp', 'keyboardInsertText', 'mouseClick', 'mouseDblclick', 'mouseMove', 'mouseDown', 'mouseUp', 'mouseWheel']),
 };
 const PLAYWRIGHT_INCOMPATIBLE = "Playwright output is not compatible with this Playwright version (playwright-core/lib/utils does not expose asLocator). Use output.framework: 'codeceptjs' instead, or pin Playwright to a version shipping lib/utils/isomorphic/locatorGenerators.js.";
+let cachedAsLocator = null;
+let asLocatorLoadAttempted = false;
+const nodeRequire = typeof require === 'function' ? require : createRequire(import.meta.url);
 function getAsLocator() {
-    const fn = playwrightUtils?.asLocator;
-    if (typeof fn !== 'function')
+    if (cachedAsLocator)
+        return cachedAsLocator;
+    if (asLocatorLoadAttempted)
         throw new Error(PLAYWRIGHT_INCOMPATIBLE);
-    return fn;
+    asLocatorLoadAttempted = true;
+    try {
+        const mod = nodeRequire('playwright-core/lib/utils');
+        if (typeof mod?.asLocator === 'function') {
+            cachedAsLocator = mod.asLocator;
+            return cachedAsLocator;
+        }
+    }
+    catch {
+        // Module not exported or not found
+    }
+    throw new Error(PLAYWRIGHT_INCOMPATIBLE);
 }
 export class PlaywrightRecorder {
     context = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.1.20",
+  "version": "0.1.21",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",

package/src/ai/navigator.ts

@@ -1,4 +1,6 @@
+import { tool } from 'ai';
 import dedent from 'dedent';
+import { z } from 'zod';
 import { ActionResult } from '../action-result.js';
 import type Action from '../action.ts';
 import { ExperienceTracker, renderExperienceToc } from '../experience-tracker.js';
@@ -238,14 +240,34 @@ class Navigator implements Agent {
     const conversation = this.provider.startConversation(this.systemPrompt, 'navigator');
     conversation.addUserText(prompt);
 
-    const tools = undefined;
+    let stopReason: string | null = null;
+    const tools = {
+      stop: tool({
+        description: dedent`
+          Stop the navigation because no locator or strategy change can reach the goal.
+          Use this when reaching the goal requires something only the user can supply or that the
+          page cannot grant from the current state — for example: an authentication failure you
+          cannot guess past, a captcha or human-verification step, a permission the test cannot
+          satisfy, a piece of data not present in the available knowledge / hint context, or a
+          blocking error or dialog you cannot dismiss.
+          Do NOT use this for locator or strategy problems — for those, emit new code blocks instead.
+        `,
+        inputSchema: z.object({
+          reason: z.string().describe('Short user-facing explanation. Quote what you observed (alert text, dialog title, status message, validation note) and name what is missing or required.'),
+        }),
+        execute: async ({ reason }) => {
+          stopReason = reason;
+          return { success: true, message: 'Recorded. Navigator will stop and surface the reason.' };
+        },
+      }),
+    };
 
     let codeBlocks: string[] = [];
     let htmlContextAdded = false;
     let codeBlockIndex = 0;
     let totalAttempts = 0;
     const progressBlocks: string[] = [];
-    const batchFailures: Array<{ code: string; error: string }> = [];
+    const batchFailures: Array<{ code: string; error: string; ariaChanges?: string | null; urlAfter?: string }> = [];
 
     let resolved = false;
     await loop(
@@ -253,6 +275,12 @@ class Navigator implements Agent {
         if (codeBlocks.length === 0) {
           const result = await this.provider.invokeConversation(conversation, tools);
           if (!result) return;
+          if (stopReason) {
+            tag('error').log(`Navigator stopped: ${stopReason}`);
+            resolved = false;
+            stop();
+            return;
+          }
           const aiResponse = result?.response?.text;
           debugLog('AI:', aiResponse?.split('\n')[0]);
           debugLog('Received AI response:', aiResponse?.length ?? 0, 'characters');
@@ -274,14 +302,38 @@ class Navigator implements Agent {
           tag('substep').log('Feeding failures back to AI for a new batch...');
           let contextMsg = 'Previous solutions did not work. Analyze the failures and try DIFFERENT strategies (not syntactic variants of the same locator).\n\n';
           if (batchFailures.length > 0) {
-            const lines = batchFailures.map((f) => `- \`${f.code.split('\n')[0]}\` → ${f.error}`).join('\n');
+            const lines = batchFailures
+              .map((f) => {
+                const head = `- \`${f.code.split('\n')[0]}\` → ${f.error}`;
+                if (!f.ariaChanges) return head;
+                const trimmed = f.ariaChanges.split('\n').slice(0, 12).join('\n    ');
+                return `${head}\n  • ARIA changes after the action:\n    ${trimmed}`;
+              })
+              .join('\n');
             contextMsg += `<previous_failures>\n${lines}\n</previous_failures>\n\n`;
           }
           if (!htmlContextAdded) {
             htmlContextAdded = true;
             contextMsg += `Full HTML context:\n\n<page_html>\n${await actionResult.combinedHtml()}\n</page_html>\n\n`;
           }
-          contextMsg += 'Propose new solutions. If errors mention "intercepts pointer events" or timeouts on visible elements, an overlay is blocking — dismiss it first (Escape, click outside, Close button) before retrying the original action.';
+          const pageReacted = batchFailures.some((f) => f.ariaChanges);
+          if (pageReacted) {
+            contextMsg += dedent`
+              Some steps in the previous batch did not throw, but the URL did not change to the expected target and the page changed in other ways — the ARIA diff for each such step is listed in <previous_failures> above.
+
+              Read those diffs and judge what each step actually triggered. Different action types produce different reactions; the diff is your only evidence of what happened. A diff might show, for example: a new alert / alertdialog / status / validation message appearing near a field or at page level; a modal, dialog, or wizard step opening; a banner, toast, or notification region appearing; a section expanding or collapsing; a tab or accordion switching content. A diff might also be empty or unrelated to the step — that is also a signal.
+
+              Choose exactly ONE path based on what the diffs actually show — do not assume the previous step submitted any particular kind of data:
+
+              A. The diff indicates the application requires something only the user can supply — for example: an authentication failure you cannot guess past, a captcha, a permission the test cannot satisfy, or knowledge that is not present in the provided context. Call the stop() tool and quote what you saw in the diff and what is needed.
+
+              B. The diff indicates the next step is something you can perform from the existing knowledge / hint context — for example: re-emit a step with a value that exists in the knowledge but was used incorrectly; dismiss an unexpected modal; accept a confirmation; take a follow-up step the page now requires. Emit code blocks for that next step. Do NOT change the locator of a step that already produced a reaction.
+
+              C. The diff is empty or unrelated to your step — the action likely missed its target. Propose a different locator strategy.
+            `;
+          } else {
+            contextMsg += 'Propose new solutions. If errors mention "intercepts pointer events" or timeouts on visible elements, an overlay is blocking — dismiss it first (Escape, click outside, Close button) before retrying the original action.';
+          }
           conversation.addUserText(contextMsg);
           codeBlocks = [];
           batchFailures.length = 0;
@@ -292,7 +344,8 @@ class Navigator implements Agent {
 
         await this.explorer.switchToMainFrame();
 
-        const prevHash = action.actionResult?.getStateHash() ?? actionResult.getStateHash();
+        const prevActionResult = action.actionResult ?? actionResult;
+        const prevHash = prevActionResult.getStateHash();
 
         debugLog(`Attempting resolution: ${codeBlock}`);
         const attemptOk = await action.attempt(codeBlock, message);
@@ -328,6 +381,22 @@ class Navigator implements Agent {
           resolved = urlMatches && stateChanged;
 
           if (!resolved && attemptOk) {
+            let ariaChanges: string | null = null;
+            if (freshState.getStateHash() !== prevHash) {
+              try {
+                const diff = await freshState.diff(prevActionResult);
+                await diff.calculate();
+                ariaChanges = diff.ariaChanged;
+              } catch (err) {
+                debugLog('Failed to compute pageDiff for failed URL verification:', err);
+              }
+            }
+            batchFailures.push({
+              code: codeBlock,
+              error: `URL did not change (still ${freshState.url})`,
+              ariaChanges,
+              urlAfter: freshState.url,
+            });
             tag('warning').log(`URL verification failed: expected ${expectedUrl}, got ${freshState.url}`);
           }
           if (freshState.getStateHash() !== prevHash && (attemptOk || urlMatches)) {
@@ -380,12 +449,15 @@ class Navigator implements Agent {
       }
     }
 
-    if (!resolved && totalAttempts > 0) {
+    if (!resolved && stopReason) {
+      tag('error').log(`Navigator stopped: ${stopReason}`);
+    } else if (!resolved && totalAttempts > 0) {
       tag('error').log(`Navigation failed after ${totalAttempts} attempts`);
     }
 
     if (!resolved && isInteractive()) {
-      const userInput = await pause(`Navigator failed to resolve. Current: ${action.stateManager.getCurrentState()?.url}\n` + `Target: ${expectedUrl ?? '(none)'}\nEnter CodeceptJS commands (or press Enter to skip):`);
+      const stopLine = stopReason ? `Navigator stopped: ${stopReason}\n` : '';
+      const userInput = await pause(`${stopLine}Navigator failed to resolve. Current: ${action.stateManager.getCurrentState()?.url}\n` + `Target: ${expectedUrl ?? '(none)'}\nEnter CodeceptJS commands (or press Enter to skip):`);
 
       if (userInput?.trim()) {
         resolved = await action.attempt(userInput, message);

package/src/commands/index.ts

@@ -26,6 +26,7 @@ import { PlanEditCommand } from './plan-edit-command.js';
 import { PlanLoadCommand } from './plan-load-command.js';
 import { PlanReloadCommand } from './plan-reload-command.js';
 import { PlanSaveCommand } from './plan-save-command.js';
+import { PlansCommand } from './plans-command.js';
 import { RerunCommand } from './rerun-command.js';
 import { ResearchCommand } from './research-command.js';
 import { RunsCommand } from './runs-command.js';
@@ -48,6 +49,7 @@ const commandClasses: CommandClass[] = [
   PlanCommand,
   PlanSaveCommand,
   PlanLoadCommand,
+  PlansCommand,
   PlanReloadCommand,
   PlanClearCommand,
   PlanEditCommand,

package/src/commands/plans-command.ts

@@ -0,0 +1,99 @@
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { Plan } from '../test-plan.js';
+import { getCliName } from '../utils/cli-name.js';
+import { tag } from '../utils/logger.js';
+import { relativeToCwd } from '../utils/next-steps.js';
+import { BaseCommand } from './base-command.js';
+
+export class PlansCommand extends BaseCommand {
+  name = 'plans';
+  description = 'List saved plans and show their test scenarios';
+  options = [{ flags: '--from-plan <file>', description: 'Plan file to show' }];
+
+  async execute(args: string): Promise<void> {
+    const { opts, args: remaining } = this.parseArgs(args);
+    const files = this.getPlanFiles();
+    const target = String(opts.fromPlan || remaining[0] || '').trim();
+
+    if (!target) {
+      this.printPlans(files);
+      return;
+    }
+
+    const file = this.resolvePlanFile(target, files);
+    const plan = Plan.fromMarkdown(file.path);
+    this.printPlanDetails(plan, file);
+  }
+
+  private getPlanFiles(): PlanFile[] {
+    const plansDir = this.explorBot.getPlansDir();
+    if (!existsSync(plansDir)) return [];
+
+    return readdirSync(plansDir)
+      .filter((file) => file.endsWith('.md'))
+      .map((file) => {
+        const filePath = path.join(plansDir, file);
+        const stat = statSync(filePath);
+        return {
+          name: file,
+          path: filePath,
+          modifiedAt: stat.mtimeMs,
+        };
+      })
+      .sort((left, right) => right.modifiedAt - left.modifiedAt);
+  }
+
+  private printPlans(files: PlanFile[]): void {
+    if (files.length === 0) {
+      tag('info').log(`No saved plans found in ${relativeToCwd(this.explorBot.getPlansDir())}`);
+      return;
+    }
+
+    tag('info').log('Saved plans:');
+    for (let i = 0; i < files.length; i++) {
+      const file = files[i];
+      const plan = Plan.fromMarkdown(file.path);
+      tag('info').log(`${i + 1}. ${plan.title} (${plan.tests.length} tests) - ${file.name}`);
+    }
+    tag('info').log('');
+    tag('info').log(`View plan tests: ${getCliName()} plans <number>`);
+  }
+
+  private printPlanDetails(plan: Plan, file: PlanFile): void {
+    tag('info').log(`${plan.title} (${plan.tests.length} tests)`);
+    for (let i = 0; i < plan.tests.length; i++) {
+      const test = plan.tests[i];
+      tag('info').log(`${i + 1}. ${test.scenario}`);
+    }
+    tag('info').log('');
+    tag('info').log('Run test from this plan as:');
+    tag('info').log(`${getCliName()} test 1 --from-plan ${file.name}`);
+  }
+
+  private resolvePlanFile(target: string, files: PlanFile[]): PlanFile {
+    const index = Number.parseInt(target, 10);
+    if (!Number.isNaN(index) && String(index) === target) {
+      const file = files[index - 1];
+      if (!file) throw new Error(`Plan #${target} not found. Available: 1-${files.length}`);
+      return file;
+    }
+
+    const resolved = this.explorBot.resolvePlanPath(target);
+    if (!existsSync(resolved)) {
+      throw new Error(`Plan file not found: ${resolved}`);
+    }
+
+    return {
+      name: path.basename(resolved),
+      path: resolved,
+      modifiedAt: statSync(resolved).mtimeMs,
+    };
+  }
+}
+
+interface PlanFile {
+  name: string;
+  path: string;
+  modifiedAt: number;
+}