explorbot 0.5.10 → 0.6.0

package/dist/src/utils/markdown-terminal.js

@@ -21,10 +21,9 @@ if (renderer) {
         const originalListitem = renderer.listitem;
         renderer.listitem = function (text) {
             if (typeof text === 'object') {
-                const item = text;
                 const parser = this.parser;
                 const originalParse = parser.parse.bind(parser);
-                parser.parse = (tokens, loose) => parser.parseInline(tokens);
+                parser.parse = (tokens) => parser.parseInline(tokens);
                 const result = originalListitem.call(this, text);
                 parser.parse = originalParse;
                 return result;

package/dist/src/utils/next-steps.js

@@ -1,4 +1,6 @@
 import path from 'node:path';
+import chalk from 'chalk';
+import figures from 'figures';
 import { tag } from './logger.js';
 export function relativeToCwd(absPath) {
     const rel = path.relative(process.cwd(), absPath);
@@ -7,25 +9,27 @@ export function relativeToCwd(absPath) {
 export function printNextSteps(sections) {
     if (sections.length === 0)
         return;
-    const blocks = [];
+    const lines = [''];
+    let isDefault = true;
     for (const section of sections) {
-        const lines = [];
         const headerPath = section.path ? relativeToCwd(section.path) : '';
-        lines.push(headerPath ? `${section.label}: ${headerPath}` : section.label);
-        const commands = section.commands || [];
-        if (commands.length > 0) {
-            const labeled = commands.filter((c) => c.label);
-            const maxLabel = labeled.length > 0 ? Math.max(...labeled.map((c) => c.label.length)) : 0;
-            for (const cmd of commands) {
-                if (!cmd.label) {
-                    lines.push(`  ${cmd.command}`);
-                    continue;
-                }
-                const padded = `${cmd.label}:`.padEnd(maxLabel + 2);
-                lines.push(`  ${padded} ${cmd.command}`);
+        lines.push(headerPath ? `${chalk.bold(section.label)}  ${chalk.gray(headerPath)}` : `${chalk.bold(section.label)}`);
+        for (const cmd of section.commands || []) {
+            if (cmd.label)
+                lines.push(BLANK);
+            if (isDefault) {
+                if (cmd.label)
+                    lines.push(chalk.bold.yellow(`${figures.pointer} ${cmd.label}`));
+                lines.push(chalk.bold(`    ${cmd.command}`));
+                isDefault = false;
+                continue;
             }
+            if (cmd.label)
+                lines.push(chalk.dim(`  ${cmd.label}`));
+            lines.push(`  ${cmd.command}`);
         }
-        blocks.push(lines.join('\n'));
+        lines.push(BLANK);
     }
-    tag('multiline').log(blocks.join('\n\n'), { maxLines: 18 });
+    tag('info').log(lines.join('\n'));
 }
+const BLANK = ' ';

package/dist/src/utils/page-readiness.d.ts

@@ -1,4 +1,5 @@
-export declare function waitForPageReadiness(page: any, options?: PageReadinessOptions): Promise<void>;
+export declare function waitForPageReadiness(page: any, options?: PageReadinessOptions): Promise<boolean>;
+export declare function waitForDomChange(page: any, timeout: number): Promise<boolean>;
 export declare function sleep(ms: number): Promise<void>;
 interface PageReadinessOptions {
     timeout?: number;

package/dist/src/utils/page-readiness.js

@@ -1,10 +1,27 @@
 export async function waitForPageReadiness(page, options = {}) {
     if (!page)
-        return;
+        return false;
     const timeout = options.timeout ?? 6000;
     await page.waitForLoadState?.('domcontentloaded', { timeout })?.catch(() => { });
     await Promise.race([waitForNetworkIdle(page, timeout), waitForDomQuiet(page, timeout), waitForVisibleSpinnersHidden(page, options.spinnerSelectors || [], timeout), sleep(timeout)]).catch(() => { });
-    await waitForPageBodyContent(page, timeout);
+    return waitForPageBodyContent(page, timeout);
+}
+export function waitForDomChange(page, timeout) {
+    if (!page?.evaluate)
+        return Promise.resolve(false);
+    return page
+        .evaluate((ms) => new Promise((resolve) => {
+        const observer = new MutationObserver(() => {
+            observer.disconnect();
+            resolve(true);
+        });
+        observer.observe(document, { subtree: true, childList: true, attributes: true, characterData: true });
+        setTimeout(() => {
+            observer.disconnect();
+            resolve(false);
+        }, ms);
+    }), timeout)
+        .catch(() => true);
 }
 const DOM_QUIET_MS = 350;
 function waitForDomQuiet(page, timeout) {
@@ -50,15 +67,17 @@ async function waitForVisibleSpinnersHidden(page, selectors, timeout) {
 }
 function waitForPageBodyContent(page, timeout) {
     if (!page?.waitForFunction)
-        return Promise.resolve();
+        return Promise.resolve(true);
     return page
         .waitForFunction(() => {
         const body = document.body;
         if (!body)
             return false;
-        return body.children.length > 0 || body.textContent?.trim().length > 0;
+        if (body.innerText.trim().length > 0)
+            return true;
+        return !!body.querySelector('input, button, select, textarea, img, svg, canvas, iframe, video');
     }, undefined, { timeout })
-        .catch(() => { });
+        .then(() => true, () => false);
 }
 export function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));

package/dist/src/utils/test-plan-markdown.d.ts

@@ -2,6 +2,9 @@ import { Plan } from '../test-plan.js';
 export declare function planToCompactAiContext(plan: Plan): string;
 export declare function parsePlanFromMarkdown(filePath: string): Plan;
 export declare function parsePlansFromMarkdown(filePath: string): Plan[];
+export declare function parsePlansFromMarkdownText(content: string): Plan[];
+export declare function findPlanMarkdownProblems(markdown: string): string[];
+export declare function readPlanMarkdownComment(markdown: string, key: string): string | null;
 export declare function savePlanToMarkdown(plan: Plan, filePath: string): void;
 export declare function savePlansToMarkdown(plans: Plan[], filePath: string): void;
 export declare function planToAiContext(plan: Plan, options?: {

package/dist/src/utils/test-plan-markdown.js

@@ -2,6 +2,7 @@ import { readFileSync, writeFileSync } from 'node:fs';
 import { Plan, Test } from "../test-plan.js";
 import { mdq } from "./markdown-query.js";
 const NOISE_PREFIXES = ['Test started', 'Finish requested:', 'Session name:'];
+const CURRENT_PAGE = 'Current page';
 function isNoiseNote(message) {
     return NOISE_PREFIXES.some((prefix) => message.startsWith(prefix));
 }
@@ -118,7 +119,9 @@ export function parsePlanFromMarkdown(filePath) {
     return main;
 }
 export function parsePlansFromMarkdown(filePath) {
-    const content = readFileSync(filePath, 'utf-8');
+    return parsePlansFromMarkdownText(readFileSync(filePath, 'utf-8'));
+}
+export function parsePlansFromMarkdownText(content) {
     const lines = content.split('\n');
     const plans = [];
     let currentPlan = null;
@@ -184,7 +187,8 @@ export function parsePlansFromMarkdown(filePath) {
             continue;
         }
         if (currentTest && inRequirements && line && !line.startsWith('##')) {
-            currentTest.startUrl = line;
+            if (line !== CURRENT_PAGE)
+                currentTest.startUrl = line;
             continue;
         }
         if (currentTest && inSteps && line.startsWith('* ')) {
@@ -207,7 +211,7 @@ export function parsePlansFromMarkdown(filePath) {
             continue;
         const nextSuite = content.indexOf('<!-- suite -->', suiteStart + 1);
         const suiteContent = nextSuite === -1 ? content.slice(suiteStart) : content.slice(suiteStart, nextSuite);
-        const firstItem = mdq(suiteContent).query('section[0] item[0]').text().trim();
+        const firstItem = mdq(suiteContent).query('section[0] item[0]').nodes()[0]?.text.trim() || '';
         const urlMatch = firstItem.match(/^URL:\s*(.+)/);
         if (urlMatch) {
             plan.url = urlMatch[1].replace(/\*\*|`|\*|_|~~?/g, '').trim();
@@ -219,6 +223,33 @@ export function parsePlansFromMarkdown(filePath) {
     }
     return plans;
 }
+export function findPlanMarkdownProblems(markdown) {
+    const doc = mdq(markdown);
+    const problems = [];
+    const headings = doc.query('h1').nodes();
+    if (!doc.query('comment(/^suite/)').exists() || headings.length === 0) {
+        problems.push('Missing <!-- suite --> comment followed by the plan name heading');
+    }
+    const scenarioCount = Math.max(headings.length - 1, 0);
+    const testComments = doc.query('comment(/^test/)').count();
+    if (testComments !== scenarioCount) {
+        problems.push(`Found ${scenarioCount} scenario headings but ${testComments} <!-- test --> comments`);
+    }
+    for (const section of doc.query('section1').each().slice(1)) {
+        const title = section.query('heading').nodes()[0]?.text;
+        if (!section.query('section2("Steps") item').exists())
+            problems.push(`Scenario "${title}" has no ## Steps items`);
+        if (!section.query('section2("Expected") item').exists())
+            problems.push(`Scenario "${title}" has no ## Expected items`);
+    }
+    return problems;
+}
+export function readPlanMarkdownComment(markdown, key) {
+    const body = mdq(markdown).query(`comment(/^${key}:/)`).nodes()[0]?.text;
+    if (!body)
+        return null;
+    return body.slice(key.length + 1).trim() || null;
+}
 function formatPlanSuite(plan) {
     let content = `<!-- suite -->\n# ${plan.title}\n\n`;
     if (plan.url) {
@@ -231,7 +262,7 @@ function formatPlanSuite(plan) {
         content += `<!-- test\npriority: ${test.priority}\n-->\n`;
         content += `# ${test.scenario}\n\n`;
         content += '## Requirements\n';
-        content += `${test.startUrl || 'Current page'}\n\n`;
+        content += `${test.startUrl || CURRENT_PAGE}\n\n`;
         if (test.plannedSteps.length > 0) {
             content += '## Steps\n';
             for (const step of test.plannedSteps) {

package/dist/src/utils/url-matcher.d.ts

@@ -1,6 +1,7 @@
 export declare function isDynamicSegment(segment: string): boolean;
 export declare function hasDynamicUrlSegment(url: string): boolean;
 export declare function isSamePageFamily(urlA: string, urlB: string): boolean;
+export declare function isSamePageIgnoringQuery(urlA: string, urlB: string): boolean;
 export declare function generalizeSegment(segment: string): string;
 export declare function generalizeUrl(url: string, replaceSegment?: (segment: string) => string): string;
 export declare function matchesUrl(pattern: string, path: string): boolean;

package/dist/src/utils/url-matcher.js

@@ -51,6 +51,11 @@ export function isSamePageFamily(urlA, urlB) {
     }
     return true;
 }
+export function isSamePageIgnoringQuery(urlA, urlB) {
+    const a = new URL(urlA, 'http://localhost');
+    const b = new URL(urlB, 'http://localhost');
+    return a.pathname === b.pathname && a.hash === b.hash;
+}
 export function generalizeSegment(segment) {
     if (/^\d+$/.test(segment))
         return '\\d+';

package/docs/basics/providers.md

@@ -59,7 +59,7 @@ export default {
     model: openrouter('openai/gpt-oss-20b:nitro'),
     visionModel: openrouter('openai/gpt-5.6-luna'),
     agenticModel: openrouter('anthropic/claude-haiku-5.5'),
-    decisionModel: { provider: 'openrouter', model: 'typesafe/jev-latest' },
+    decisionModel: { provider: 'openrouter', model: '~typesafe/jev-latest' },
   },
 };
 ```

package/docs/contributing/regression-tests.md

@@ -28,6 +28,14 @@ The plan (`tests/regression/seeds/vault-plan.md`) describes *what* to do but nev
 
 > The code is carried in a knowledge file, not only experience, on purpose. Knowledge is Explorbot's prominent, deterministic channel for page-specific data — the same mechanism scenario A uses for login credentials. Empirically, cheap models followed an experience-only code recipe only occasionally, so an experience-only gate was a coin-flip; knowledge makes the gate reliable while the experience file still exercises recipe reuse.
 
+### Scenario C — late-rendering start page (`regression:slow`)
+
+Runs scenario A again with the fixture's slow start on: on the first visit of a session `/issues` arrives as an empty shell and renders client-side 12 seconds later, longer than the page-readiness wait. Scenario A's assertions must still hold, which proves the Researcher waited for the real page instead of researching the blank shell. It executes one test instead of five (`--max-tests 1`, at least one passing): research and planning are what it checks, and scenario A already covers running the plan.
+
+### Scenario D — sign-in form at the start URL (`regression:gated`)
+
+Runs scenario A's assertions against `explore /workspace`. Signed out, `/workspace` shows the sign-in form at its own URL instead of redirecting to `/login`, and signing in there keeps you on `/workspace`. The planner reports the page blocked by a sign-in form, so explore must hand the report to Captain, sign in with the credentials in `seeds/knowledge/workspace.md` and plan the page again. Like scenario C, it executes one test.
+
 ## The fixture app — "Trackly"
 
 A self-contained issue tracker served in-process by `tests/regression/fixture/server.ts` (`Bun.serve`, ephemeral port, fresh in-memory store per attempt). No external network, no database.
@@ -40,6 +48,7 @@ A self-contained issue tracker served in-process by `tests/regression/fixture/se
 | `/issues/:id` | yes | detail, change-status menu, comment form, delete modal |
 | `/settings` | yes | Profile/Preferences tabs + an activity iframe |
 | `/vault` | no | scenario B access-code gate |
+| `/workspace` | no / yes | scenario D: the sign-in form when signed out, the issue list when signed in |
 | `/api/*` | cookie | REST API over the same store, `+ /api/openapi.json` |
 
 The REST API mirrors the store and is served for a future API-testing scenario; the current scenarios do not exercise it.
@@ -68,7 +77,9 @@ bunx bunosh regression:serve
 export OPENROUTER_API_KEY=sk-...
 bunx bunosh regression:experience --retries 0   # cheapest AI path
 bunx bunosh regression:basic --retries 0
-bunx bunosh regression:all                       # both scenarios, default retries
+bunx bunosh regression:slow --retries 0
+bunx bunosh regression:gated --retries 0
+bunx bunosh regression:all                       # all scenarios, default retries
 ```
 
 Each attempt runs in an isolated throwaway directory under `tests/regression/.runs/` (gitignored). Inspect `tests/regression/.runs/<scenario>-<variant>-a<n>/output/` for the research, plans, and reporter markdown a run produced, and `tests/regression/.runs/report.md` for the summary.
@@ -83,9 +94,13 @@ bunx bunosh regression:variants --scenario basic --variants native,aria,plain
 
 ## CI and the approval gate
 
-`.github/workflows/regression.yml` runs on `pull_request` and `workflow_dispatch`. The job uses the `regression` GitHub environment, which holds `OPENROUTER_API_KEY` behind a **required reviewer**. Every run — including fork PRs — pauses at the environment gate before the secret is exposed. The job runs the PR's own code, so the reviewer must read the PR diff (workflow, Bunoshfile, fixture, lib) before approving; that review is the security boundary. The workflow never uses `pull_request_target`.
+`.github/workflows/regression.yml` runs on `pull_request` and `workflow_dispatch`. `regression:all` runs the scenarios in parallel inside one job, so a run lasts as long as its slowest scenario and needs one approval. The job uses the `regression` GitHub environment, which holds `OPENROUTER_API_KEY` behind a **required reviewer**. Every run — including fork PRs — pauses at the environment gate before the secret is exposed. The job runs the PR's own code, so the reviewer must read the PR diff (workflow, Bunoshfile, fixture, lib) before approving; that review is the security boundary. The workflow never uses `pull_request_target`.
+
+Every attempt writes a `record.json` into its run directory. `regression:report` merges those records and posts the report as a sticky PR comment (on `pull_request`) or a `Regression Reports` GitHub Discussion (on `workflow_dispatch`). Fork PRs get a read-only token, so comment posting may fail; the report is also written to the step summary.
+
+### Speed comparison
 
-The report is posted as a sticky PR comment (on `pull_request`) or a `Regression Reports` GitHub Discussion (on `workflow_dispatch`). Fork PRs get a read-only token, so comment posting may fail; the report is also written to the job step summary and uploaded as the `regression-runs` artifact.
+The report's `Time` column is the duration of the passing attempt. `Previous median` is the median of that scenario's passing time over the last 5 runs, and `Change` flags a difference of 20% or more. The job uploads the run's records as the `regression-summary` artifact (the run directories go to `regression-runs`) (kept 90 days), and the next run downloads the latest five to compare against. Which tests the planner picks changes a run's time, so read one flagged run as a hint and a trend over several as a regression.
 
 The report also embeds the **Session Analysis** from the fresh-explore run — Explorbot's Analyst agent writes a prose summary of what works, defects, UX issues, and execution issues, which the harness reads from `output/reports/<label>.md` and appends to the comment. The Analyst is enabled in the config template (`ai.agents.analyst.enabled: true`); it adds one AI call per basic run.
 
@@ -93,7 +108,7 @@ The report also embeds the **Session Analysis** from the fresh-explore run — E
 
 - **Thresholds** (`MIN_PLANNED_TESTS`, `MIN_PASSED`, `MIN_KEYWORD_HITS`, `MIN_FEATURE_GROUPS`) live at the top of `tests/regression/lib/assertions.ts`.
 - **Models** live in `tests/regression/fixture/explorbot.config.js`. If cheap models are too flaky, promote a stronger model to `ai.model` or lower `MIN_PASSED`.
-- **Run size** — adjust `--max-tests` in `runBasicScenario` and the per-CLI `timeout` values in `Bunoshfile.js`.
+- **Run size** — adjust `maxTests` / `minPassed` on the scenario constants and the per-CLI `timeout` values in `Bunoshfile.js`.
 
 ## Owner prerequisites (one-time)
 

package/docs/reference/commands.md

@@ -34,7 +34,7 @@ Inside the TUI, use the matching slash command: `/explore`, `/research`, `/plan`
 | List saved plans | `npx explorbot plans [plan]` | `/plans [plan]` | Show plans and their tests |
 | Navigate to a URL | `npx explorbot navigate <url>` | `/navigate <target>` | Reachability probe + session capture |
 | Drill page components | `npx explorbot drill <url>` | `/drill [--save-knowledge <path>] [--max-components <n>]` | Learn interactions |
-| Execute plan tests | `npx explorbot test <planfile> [index]` | `/test [scenario\|number\|*]` | Run scenarios |
+| Execute plan tests | `npx explorbot test <planfile> [index]` | `/test [planfile] [scenario\|number\|*]` | Run scenarios |
 | Re-run generated tests | `npx explorbot rerun <file> [index]` | `/rerun <file> [index]` | With AI auto-healing |
 | List generated tests | `npx explorbot runs [file]` | `/runs [file]` | Index + dry-run |
 | Store domain knowledge | `npx explorbot learn [url] [note]` | `/learn [note]` | Persisted to `knowledge/` |
@@ -454,6 +454,8 @@ Execute test scenarios using the Tester agent.
 ```bash
 # CLI
 npx explorbot test output/plans/login.md          # run all enabled tests
+npx explorbot test login                          # same, plan looked up in output/plans
+npx explorbot test login --path example           # plan looked up in example/output/plans
 npx explorbot test output/plans/login.md 3        # run test #3
 npx explorbot test output/plans/login.md 1-5      # range
 npx explorbot test output/plans/login.md 1,3,7    # selection
@@ -463,9 +465,11 @@ npx explorbot test 3 --from-plan output/plans/login.md   # index first, plan via
 
 ```
 # TUI
-/test              # Run next pending test
+/test              # Run next pending test of the current plan
 /test *            # Run all pending tests
 /test 2            # Run test #2 from plan
+/test login.md     # Load plan file and run all its tests
+/test login.md 2   # Load plan file and run test #2
 /test login        # Run tests matching "login"
 /test User can logout successfully   # Create and run ad-hoc test
 ```

package/docs/reference/configuration.md

@@ -218,7 +218,7 @@ The Researcher takes all standard agent options plus options that control intera
 | Option | Type | Description |
 |--------|------|-------------|
 | `maxExpandableClicks` | `number` | Maximum expandable elements clicked during deep analysis (default: 10) |
-| `errorPageTimeout` | `number` | Seconds to wait for a loading page to settle before error-page detection (default: 10, `0` disables the wait) |
+| `errorPageTimeout` | `number` | Seconds to wait for a blank or barely rendered page to finish loading before research; uses the same readiness checks as every action, and the judge when `ai.decisionModel` is set (default: 10, `0` disables the wait) |
 | `focusSections` | `string[]` | CSS selectors that narrow research to a matching element when present (e.g. an open modal or drawer). First match wins. Applies only to the per-section fallback used after a truncated research response. |
 
 ```javascript

package/docs/web-testing/agents.md

@@ -125,6 +125,14 @@ The Captain steps in when a slash command isn't enough — answering questions a
 
 When a test hits a fatal browser error, the Captain tries to recover — reload, restart the browser, open a fresh tab, or close extra tabs — before the test is stopped, then tells the Tester how to continue. It runs on explicit TUI requests and on test interrupts (stop, pass, skip, or redirect a running test).
 
+Wherever Explorbot opens a page, plans a page or starts a test, including in `explore` and `freesail`, the Captain also takes over when another agent reports it is blocked:
+
+- the Planner can't plan a page, for example because it shows a sign-in form
+- the Navigator can't reach a page after all its attempts
+- the page open at a test's start isn't where that test can start; this check needs [`ai.decisionModel`](../reference/configuration.md)
+
+The Captain gets what the agent was asked to do, where it stopped and why, and what was already tried. It works out from the browser session how to get past the blocker. Then the planning, the page or the test continues. If the Captain can't resolve it, the page or test is skipped, and the same blocker isn't handed to it again in that run.
+
 ## Per-Agent Model Configuration
 
 Use different models for different agents to control cost:

package/docs/web-testing/customization.md

@@ -27,6 +27,8 @@ Log in with these credentials:
 
 Explorbot reads this when it opens the login page and signs in on its own. See [Knowledge](../workflow/knowledge.md).
 
+Some apps show the sign-in form at the page you asked for instead of redirecting to `/login`. When the planner reports that the page is blocked by a sign-in form, `explore` hands that report to Captain. Captain looks at the browser session, decides how to get past the form with this knowledge, and re-plans the page itself. If Captain adds no tests, the page is skipped with the planner's reason. Set the knowledge file's `url` to that page so the credentials load there.
+
 ## Stay logged in between runs
 
 Logging in on every run is slow. Use `--session` to save cookies and local storage, then restore them next time:

package/docs/web-testing/researcher.md

@@ -39,7 +39,7 @@ ai: {
 | `sections` | `string[]` | all sections | Page sections to identify (order = priority) |
 | `focusSections` | `string[]` | `[]` | CSS selectors used in the truncated-response fallback, when research is split into per-section requests (first match wins). The matching element becomes the container for the focused section — see [Handling Truncated Responses](#handling-truncated-responses). |
 | `maxExpandableClicks` | `number` | `10` | Max expandable elements clicked during deep research |
-| `errorPageTimeout` | `number` | `10` | Seconds to wait for the page to settle before research; error pages detected during this wait abort research. Set `0` to skip the wait |
+| `errorPageTimeout` | `number` | `10` | Seconds to wait for a blank or barely rendered page to settle before research. Uses the same readiness checks as every action (network idle, quiet DOM, `playwright.spinnerSelectors`, visible content), so a small page that has rendered stops the wait early. With `ai.decisionModel` set, the judge decides whether a page that still looks unfinished is loading, an error page or loaded, and Explorbot waits for the page to change before asking again. Error pages detected during this wait abort research. Set `0` to skip the wait |
 | `retries` | `number` | `2` | Retries when most locators are broken in Stage 2 |
 | `reasoning` | `string` | `'low'` | AI SDK v7 reasoning effort: `'none'`, `'minimal'`, `'low'`, `'medium'`, `'high'`, `'xhigh'`, `'provider-default'` |
 | `providerOptions` | `object` | - | Provider-specific options. Reasoning keys here take precedence over `reasoning`. |

package/models.json

@@ -3,7 +3,7 @@
     "model": "openai/gpt-oss-20b:nitro",
     "visionModel": "openai/gpt-5.6-luna",
     "agenticModel": "anthropic/claude-haiku-5.5",
-    "decisionModel": "typesafe/jev-latest"
+    "decisionModel": "~typesafe/jev-latest"
   },
   "poolside": {
     "model": "poolside/laguna-xs-2.1"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.5.10",
+  "version": "0.6.0",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",
@@ -131,6 +131,7 @@
     "sambanova-ai-provider": "^1.2.2",
     "strip-ansi": "^7.1.2",
     "turndown": "^7.2.1",
+    "wrap-ansi": "^9.0.2",
     "unique-names-generator": "^4.7.1",
     "yaml": "^2.8.3",
     "yargs": "^17.7.2",

package/rules/navigator/output.md

@@ -65,14 +65,8 @@ Trying to fill the form on the page
 ```
 
 ```js
-  I.fillField('/html/body/div/div/div/form/input[@name="name"]', 'Value');
+  I.fillField('//html/body//form//input[@name="name"]', 'Value');
 ```
 </example_output>
 
-If you don't know the answer, answer as:
-
-<example_output>
-```js
-  throw new Error('No resolution');
-```
-</example_output>
+If no solution is possible, call stop() with the reason instead of proposing code.

package/rules/navigator/verification-actions.md

@@ -26,6 +26,10 @@ Prefer ARIA locators for reliable element detection.
   I.seeElement('.success-message');
 </example>
 
+To assert text inside element via `has-text` CSS, prefer using I.see() instead:
+
+Prefer `I.see('Collection', '.users')` over `I.seeElement(".users div:has-text("Collection")")` 
+
 ### I.seeInField
 
 I.seeInField(<locator>, <value>, <context>)
@@ -141,8 +145,8 @@ NEVER use `:has-text(...)` inside a seeElement/dontSeeElement locator. Checking
 NEVER emit two assertions that check the same fact with different shapes. `I.see(text, locator)` and `I.seeElement("<locator>:has-text('text')")` verify the same thing — pick one (prefer I.see). One claim, one assertion.
 </verification_rules>
 
-[DO NEVER USE OTHER CODECEPTJS COMMANDS THAN PROPOSED HERE]
+[Prefer the commands listed here; use other CodeceptJS I.* commands when none of these fits]
 [INTERACT ONLY WITH ELEMENTS THAT ARE ON THE PAGE HTML OR ARIA SNAPSHOT]
 [DO NOT USE WAIT FUNCTIONS]
 
-</actions>
+</actions>

package/rules/planner/ignored-pages.md

@@ -3,4 +3,5 @@ Do not plan tests for these pages, return an empty scenarios list:
 - sign in
 - sign up
 - password recovery
+If the page shows a sign-in form instead of the content its URL is for, also set prerequisite.
 </ignored_pages>

package/src/action-result.ts

@@ -1,5 +1,4 @@
 import fs from 'node:fs';
-import { join } from 'node:path';
 import { ConfigParser, type HtmlConfig, outputPath } from './config.ts';
 import type { Link, WebPageState } from './state-manager.ts';
 import { LARGE_ARIA_CHANGE_THRESHOLD, compactAriaSnapshot, diffAriaSnapshots } from './utils/aria.ts';
@@ -742,7 +741,7 @@ export class Diff {
   async calculate(): Promise<void> {
     if (!this.previous) return;
 
-    this._htmlDiffResult = await htmlDiff(this.previous.html, this.current.html, ConfigParser.getInstance().getConfig().html);
+    this._htmlDiffResult = await htmlDiff(this.previous.html, this.current.html);
 
     if (!this._isSameUrl) {
       this._messages = liveRegionMessages(this.previous.html, this.current.html);

package/src/action.ts

@@ -34,8 +34,6 @@ class Action {
   public actionResult: ActionResult | null = null;
   private config: ExplorbotConfig;
 
-  // action info
-  private action: string | null = null;
   public lastError: Error | null = null;
   public playwrightHelper: any;
   public playwrightGroupId: string | null = null;
@@ -389,8 +387,6 @@ class Action {
   }
 
   private async executeOnce(code: string, verbatim = false): Promise<Action> {
-    let error: Error | null = null;
-
     setActivity('🔎 Browsing...', 'action');
 
     let codeString = code.replace(/^\(I\) => /, '').trim();
@@ -441,7 +437,6 @@ class Action {
       this.assertionSteps = assertionSteps;
     } catch (err) {
       debugLog('Action error', errorToString(err));
-      error = err as Error;
       if (!isPlaywright) {
         await recorder.reset();
         await recorder.start();

package/src/ai/captain/idle-mode.ts

@@ -3,7 +3,9 @@ import { createBashTool } from 'bash-tool';
 import dedent from 'dedent';
 import { z } from 'zod';
 import { ConfigParser } from '../../config.ts';
-import { Test } from '../../test-plan.ts';
+import { Plan, Test } from '../../test-plan.ts';
+import { getStyles } from '../planner/styles.ts';
+import { PlanningBlockedError } from '../../utils/error-page.ts';
 import { listRecentArtifacts, readCaptainFile } from './file-tools.ts';
 import { type Constructor, type ModeContext, resolveProjectRoot } from './mixin.ts';
 
@@ -36,11 +38,18 @@ export function WithIdleMode<T extends Constructor>(Base: T) {
       }
 
       const tools: Record<string, any> = {
-        updatePlan: tool({
-          description: 'Update the current plan by replacing or appending tests',
+        plan: tool({
+          description: dedent`
+            Plan tests for the current page. Adds them to the current plan when it is for this page, otherwise starts a new plan.
+            Without tests, the Planner writes the tests. With tests, exactly those tests are added and the Planner does not run: use it for tests the user dictates.
+            Returns how many tests were added, or why planning failed.
+          `,
           inputSchema: z.object({
-            action: z.enum(['replace', 'append']).optional().describe('replace clears existing tests, append keeps them'),
-            title: z.string().optional().describe('New plan title'),
+            feature: z.string().optional().describe('Focus area for the Planner'),
+            style: z
+              .enum(Object.keys(getStyles()) as [string, ...string[]])
+              .optional()
+              .describe('Planning style for the Planner; omit to let it choose'),
             tests: z
               .array(
                 z.object({
@@ -49,33 +58,36 @@ export function WithIdleMode<T extends Constructor>(Base: T) {
                   expected: z.array(z.string()).optional(),
                 })
               )
-              .optional(),
+              .optional()
+              .describe('Tests to add as written, without running the Planner'),
+            replace: z.boolean().optional().describe('Remove the tests already in this page plan first'),
+            title: z.string().optional().describe('New plan title'),
           }),
-          execute: async ({ action, title, tests }) => {
+          execute: async ({ feature, style, tests, replace, title }) => {
+            if (ctx.blocker instanceof PlanningBlockedError) {
+              feature = ctx.blocker.feature;
+              style = ctx.blocker.style;
+            }
+            const url = ctx.explorBot.stateManager().getCurrentState()?.url || '';
             let plan = ctx.explorBot.getCurrentPlan();
-            if (!plan) {
-              plan = await ctx.explorBot.plan();
+            if (plan?.url && plan.url !== url) plan = undefined;
+            if (replace) plan?.tests.splice(0);
+            const before = new Set(plan?.tests ?? []);
+            if (!tests?.length) {
+              plan = await ctx.explorBot.plan(feature, { style });
+              const error = ctx.explorBot.lastPlanError;
+              if (error) return { success: false, message: error.message };
             }
             if (!plan) {
-              return { success: false, message: 'Plan unavailable' };
-            }
-            if (title) {
-              plan.title = title;
+              plan = new Plan(url);
+              ctx.explorBot.setCurrentPlan(plan);
             }
-            if (tests?.length) {
-              if (!action || action === 'replace') {
-                plan.tests.length = 0;
-              }
-              const currentUrl = ctx.explorBot.stateManager().getCurrentState()?.url || '';
-              for (const testInput of tests) {
-                const priority = testInput.priority || 'normal';
-                const expected = testInput.expected?.length ? testInput.expected : [];
-                const test = new Test(testInput.scenario, priority, expected, currentUrl);
-                plan.addTest(test);
-              }
+            for (const t of tests ?? []) {
+              plan.addTest(new Test(t.scenario, t.priority || 'normal', t.expected ?? [], url));
             }
+            if (title) plan.title = title;
             plan.updateStatus();
-            return { success: true, tests: plan.tests.length };
+            return { success: true, testsAdded: plan.tests.filter((t) => !before.has(t)).length, tests: plan.tests.length };
           },
         }),
         project: tool({
@@ -144,7 +156,7 @@ export function WithIdleMode<T extends Constructor>(Base: T) {
 
       return dedent`
         <idle_capabilities>
-        - Plan management: updatePlan() — replace or append tests in the current plan
+        - Plan management: plan() — run the Planner on the current page, or add tests you write yourself
         - readFile() — read specific report, plan, log, generated test, knowledge, or experience file content
         - bash() — discover files and inspect file metadata
           - READ from: ${knowledgeDir}/, ${experienceDir}/, ${outputDir}/

package/src/ai/captain/mixin.ts

@@ -1,7 +1,7 @@
-import { dirname } from 'node:path';
 import { ConfigParser } from '../../config.ts';
 import type { ExplorBot } from '../../explorbot.ts';
 import type { Task } from '../../test-plan.ts';
+import type { BlockedError } from '../../utils/error-page.ts';
 import { createDebug } from '../../utils/logger.js';
 
 export type Constructor<T = object> = new (...args: any[]) => T;
@@ -13,6 +13,7 @@ export type CaptainMode = 'idle' | 'web' | 'test' | 'heal';
 export interface ModeContext {
   explorBot: ExplorBot;
   task: Task;
+  blocker: BlockedError | null;
 }
 
 export function resolveProjectRoot(): string | null {