explorbot 0.4.8 → 0.4.10

package/docs/superpowers/specs/2026-09-14-mdq-package-design.md

@@ -0,0 +1,397 @@
+# mdq — Markdown Query & Edit Package
+
+Date: 2026-09-14
+Status: Approved design, pending implementation
+
+## Goal
+
+Extract `src/utils/markdown-query.ts` into `src/utils/mdq/`, designed as a publishable
+standalone package: query markdown *and* update it, with a jq-like CLI planned as a
+second phase.
+
+The name `mdq` is unclaimed on npm (verified 404). Publishing is deferred; this change
+makes the package publish-ready but adds no `package.json` or build script.
+
+## Constraints
+
+- **Zero explorbot imports.** Two dependencies only: `marked` for markdown, `yaml` for
+  frontmatter. Both are already repo deps (`marked` ^16.2.0, `yaml` ^2.8.3).
+- **Two files**, per the module split below.
+- 54 in-repo call sites must keep working; a re-export shim carries them.
+
+## Architecture
+
+```
+src/utils/mdq/
+  query.ts   selector grammar - token index - MarkdownDoc - Selection (reads)
+  edit.ts    pure edits over (source, ranges): splicing - whitespace - renderers
+  README.md  public documentation
+src/utils/markdown-query.ts   re-export shim
+tests/unit/mdq/*.test.ts
+```
+
+`edit.ts` exports pure functions taking source text plus ranges or tokens, and returning
+new source text. It imports types from `query.ts` type-only and never references a class
+value. `query.ts` owns both classes and delegates each write verb to exactly one `edit.ts`
+call. This keeps the split acyclic by construction.
+
+Two types:
+
+- **`MarkdownDoc`** — a whole document. Returned by `mdq()` and by every write.
+- **`Selection`** — a set of matched ranges. Returned by `query()` and the sugar methods.
+
+One rule, stated in the README: **reads narrow, writes return the document.**
+
+## API
+
+### `mdq(source)`
+
+`mdq(source: string | MarkdownDoc): MarkdownDoc`
+
+Accepting a `MarkdownDoc` makes re-wrapping free.
+
+### `MarkdownDoc`
+
+| Method | Returns | Notes |
+|---|---|---|
+| `query(selector, matcher?)` | `Selection` | |
+| `frontmatter()` | `Record<string, unknown>` | `{}` when absent |
+| `setFrontmatter(key, value)` | `MarkdownDoc` | `null` value deletes the key |
+| `append(md)` | `MarkdownDoc` | add a block at end of document |
+| `prepend(md)` | `MarkdownDoc` | add a block at start of body, after frontmatter |
+| `toString()` / `valueOf()` | `string` | full document, frontmatter included |
+
+Plus the shared sugar layer.
+
+`append`/`prepend` exist because "add a section to the end of the document" otherwise has
+no clean path — only the `section().last().insertAfter(...)` workaround. There is a real
+call site: `deep-analysis.ts:131` builds it by hand today as
+`` `${cached.trimEnd()}\n\n# Extended Research\n\n...` ``.
+
+### `Selection` — reads
+
+Narrow or extract; never mutate.
+
+| Method | Returns | Replaces |
+|---|---|---|
+| `query(selector, matcher?)` | `Selection` | sub-query, unchanged |
+| `text()` | `string` | — (`get()` deprecated) |
+| `count()` | `number` | |
+| `exists()` | `boolean` | the `.count() > 0` idiom, 3 in-repo uses |
+| `first()` / `last()` | `Selection` | |
+| `at(n)` | `Selection` | new; sugar-path equivalent of DSL `[n]` |
+| `slice(from?, to?)` | `Selection` | new; sugar-path equivalent of DSL `[a:b]` |
+| `each()` | `Selection[]` | |
+| `nodes()` | `NodeInfo[]` | `meta()` |
+| `rows()` | `Record<string,string>[]` | `toJson()` — it only ever handled tables |
+| `entries()` | `Record<string,string>` | `keyValue()` |
+| `preceding()` / `following()` | `Selection` | `before()` / `after()` |
+
+`before`/`after` are renamed specifically to free those names from colliding with
+`insertBefore`/`insertAfter`.
+
+### `Selection` — writes
+
+Every write returns `MarkdownDoc`, so edits chain in one expression.
+
+| Method | Signature | Notes |
+|---|---|---|
+| `replace(md)` | `(Markdown) => MarkdownDoc` | |
+| `replaceEach(fn)` | `((Selection, number) => Markdown) => MarkdownDoc` | |
+| `remove()` | `() => MarkdownDoc` | node **plus its adjacent `space` token** |
+| `insertBefore(md)` | `(Markdown) => MarkdownDoc` | sibling |
+| `insertAfter(md)` | `(Markdown) => MarkdownDoc` | sibling |
+| `prepend(md)` | `(Markdown) => MarkdownDoc` | inside a section or list; `MdqOperationError` on a leaf node |
+| `append(md)` | `(Markdown) => MarkdownDoc` | inside a section or list; `MdqOperationError` on a leaf node |
+| `addRow(row)` | `(Record<string,string>) => MarkdownDoc` | table only; re-aligns columns |
+| `addItem(text)` | `(string) => MarkdownDoc` | list only; matches marker + indent |
+| `setEntry(key, value)` | `(string, string \| null) => MarkdownDoc` | `null` deletes |
+
+Naming now pairs: `rows()`/`addRow()`, `entries()`/`setEntry()`, `nodes()`.
+
+Every verb that *takes* markdown accepts `Markdown = string | MarkdownDoc`, mirroring
+`mdq()` itself. A `replaceEach` callback may therefore return a `MarkdownDoc` built by a
+nested edit, without a `.toString()` hop.
+
+### Sugar layer
+
+Eleven methods on both classes: `section` `heading` `paragraph` `table` `list` `item`
+`code` `blockquote` `comment` `html` `hr`.
+
+Each is `(matcher?, opts?) => Selection` and is *defined as* `query(sel, matcher)` —
+documented as sugar, not a parallel implementation. Defined once on a shared base that
+implements them in terms of an abstract `query()`, so the two classes do not duplicate it.
+
+Depth is an option rather than 12 near-duplicate methods:
+
+```js
+mdq(src).section('API', { depth: 2 })   // DSL: query('section2("API")')
+mdq(src).heading(/^f/i).at(0)           // DSL: query('heading(/^f/i)[0]')
+mdq(src).comment(/^test/)               // DSL: query('comment(/^test/)')
+```
+
+### Exported types
+
+Declared at the end of their file, per repo convention.
+
+```ts
+type Markdown = string | MarkdownDoc;
+type Matcher  = string | RegExp | ((text: string) => boolean);
+
+interface NodeInfo {
+  type: string;            // 'heading' | 'paragraph' | 'table' | 'comment' | ...
+  depth: number | null;    // heading level, else null
+  text: string;            // unwrapped text; comment bodies without <!-- -->
+}
+
+interface SelectorOptions {
+  depth?: 1 | 2 | 3 | 4 | 5 | 6;
+}
+```
+
+`Matcher` semantics:
+
+- `string` — exact match (mirrors DSL `"x"`)
+- `RegExp` — pattern, honoring its own flags
+- function — predicate; needs no escaping at all
+
+Note the consequence for `comment`: a `string` matcher is **exact**, and this repo's own
+test-plan comments are multi-line (`<!-- test\n  priority=critical\n-->`). So
+`comment('test')` matches only a bare `<!-- test -->`; reaching the multi-line ones needs
+`comment(/^test/)` or a predicate. Exactness is the consistent rule and is kept, but it is
+the one place the sugar is likely to surprise.
+
+This removes an existing wart. Today the repo hand-escapes to build selector strings:
+
+```js
+const escaped = section.name.replace(/"/g, '\\"');   // researcher/focus.ts:77
+mdq(result.text).query(`section2(~"${escaped}")`);
+```
+
+### Deprecated aliases
+
+`get` `toJson` `keyValue` `setKeyValue` `meta` `before` `after` are kept, marked
+`@deprecated`, and omitted from the README so the published surface reads clean.
+
+Aliases cover the read renames completely. They cannot shield the write return-type
+change — see Migration.
+
+## Selector grammar
+
+Unchanged, plus one addition and three fixes.
+
+### `comment` (new)
+
+`html` tokens filtered to those that are comments. Not an alias for `html`: `<div>x</div>`
+lexes as `html` too.
+
+- `comment` matches on the **inner** body, trimmed. `html` matches on raw.
+  This is required for anchored patterns — `/^test/` against `<!-- test id=1 -->` only
+  works if the text is `test id=1`.
+- Multi-line comments are a single token and keep their newlines in the matched text.
+- **Inline comments are out of scope for 1.0.** `para with <!-- x --> comment` lexes the
+  comment inside the paragraph token; it is not reachable as a block. Documented, not faked.
+
+`comment` and `html` together finish the `test-plan-markdown.ts` story: its hand-rolled
+line parser (`src/utils/test-plan-markdown.ts:122+`) exists only because mdq could not
+see `<!-- suite -->` and `<!-- test ... -->`.
+
+### Fixes
+
+1. **Regex flags are honored.** Today flags are parsed then discarded
+   (`markdown-query.ts:90`) and `'i'` is hardcoded (`markdown-query.ts:156`), so `/x/` is
+   case-insensitive while `"x"` and `~"x"` are case-sensitive. After the fix `/x/i` is
+   insensitive and `/x/` is not. One production call site relies on the old behavior:
+   `researcher.ts:316` `section2(/^summary/)` becomes `/^summary/i`. Tests already write
+   flags explicitly.
+2. **Unknown selectors throw.** Today `query('secton("A")')` silently matches nothing
+   (`markdown-query.ts:103-106`, `:356`). Unacceptable for a CLI.
+3. **Table text-match widens to headers plus cells.** Today `getTokenText` returns headers
+   only (`markdown-query.ts:181`), so `table(~"GET")` can never match a cell. No call site
+   uses table text-matching, so this is safe.
+
+## Update semantics
+
+`marked` separators are uneven, and every write rule follows from this:
+
+| Token | `raw` |
+|---|---|
+| `heading` | `"# A\n\n"` — separators baked in |
+| `paragraph` | `"para"` — no trailing newline |
+| `space` | `"\n\n"` — a separate token |
+
+The token index therefore records each node's range **and its adjacent `space` range**.
+
+> **Invariant: mdq never leaves zero blank lines between blocks, and never more than one.**
+
+- `remove()` takes the node plus its trailing `space` — or its leading `space` when it is
+  the last block. Without this, removing a paragraph leaves a four-newline crater. This is
+  the most likely bug in the feature and gets dedicated tests.
+- `insertAfter` / `append` normalize inserted markdown to one trailing `\n` and splice at
+  the boundary, never inside a space token.
+- `append` on a section inserts before the next same-or-shallower heading, reusing the
+  existing `computeSections` end boundary.
+- `addRow` re-renders the whole table so column pipes stay aligned.
+- `addItem` copies the list's existing marker (`-`, `*`, `1.`) and indent.
+
+## Frontmatter
+
+Every `knowledge/` and `experience/` file opens with `---\nurl: /login\n---`, which
+`marked` lexes as a setext h2 titled `url: /login`.
+
+mdq detects leading frontmatter, excludes it from the token index with offsets preserved
+so edits splice correctly, and exposes it as data.
+
+Reading and writing both go through `yaml`'s **Document API** (`YAML.parseDocument`), not
+`parse`/`stringify`. That buys two things a hand-rolled parser cannot: correctness on
+nested maps, lists and block scalars — the Jekyll/Astro/Obsidian files that justify the
+feature — and **comment preservation through a write**, verified:
+
+```yaml
+# a leading comment          <- survives setFrontmatter('wait', 2000)
+url: /login
+wait: 2000
+tags:
+  - auth
+  - smoke
+nested:
+  key: value # trailing note  <- also survives
+```
+
+`gray-matter` is deliberately not used: `knowledge-tracker.ts` keeps it for its own
+purposes, but a published package should not carry it to do what `yaml` already does.
+
+```js
+const doc = mdq(knowledgeFile);
+doc.frontmatter();                  // { url: '/login', wait: 1000, tags: ['auth'] }
+doc.query('h2').count();            // 0 — the --- block is not a heading
+doc.setFrontmatter('wait', 2000).toString();
+```
+
+## Errors
+
+`MdqError` base, with:
+
+- `MdqSelectorError` — malformed or unknown selector, carrying the offending index.
+- `MdqOperationError` — a verb applied to the wrong node type, e.g. `addRow` on a paragraph.
+
+An **empty selection is a safe no-op**: reads return `''` / `[]`, writes return the
+document unchanged. This preserves the existing "returns source unchanged when no matches"
+test.
+
+## CLI (phase 2)
+
+The selector is the program, the file or stdin is the input, markdown is the default output.
+
+A leading `.` is accepted and ignored, so muscle memory from jq (`mdq '.h2'`) works. It is
+sugar in the grammar, not a separate syntax — without it the new "unknown selectors throw"
+rule would reject the most natural thing a jq user types first.
+
+```bash
+mdq 'h2' README.md                           # raw markdown of matches
+cat plan.md | mdq 'section("API") table' -j  # rows() as JSON
+mdq 'comment(~"test")' plan.md --count
+mdq 'section("FAQ")' doc.md --remove -i      # edit in place
+mdq 'table[0]' api.md --add-row '{"Method":"GET","Path":"/users"}' -i
+```
+
+Flags mirror library verbs exactly: `--remove` `--replace` `--insert-before`
+`--insert-after` `--prepend` `--append` `--add-row` `--add-item` `--set k=v`, plus
+`-i/--in-place`, `-j/--json`, `-c/--count`, `-t/--text`, `--frontmatter`.
+
+Built with Commander, per repo convention. Exit codes compose like grep: **0** match,
+**1** no match, **2** usage or selector error.
+
+1.0 reads one file or stdin. Multi-file input is out of scope.
+
+## Testing
+
+Port the existing 801-line suite first — it is the regression net for all 54 call sites.
+Then add coverage for what is new or newly specified:
+
+- whitespace craters on `remove` (the invariant above)
+- chained multi-edits through `MarkdownDoc`
+- `addRow` column alignment; `addItem` marker and indent matching
+- frontmatter round-trip, including a file whose body has its own `---`
+- `comment` inner-text matching, multi-line comments, and `html` versus `comment`
+- `MdqSelectorError` on unknown selectors and malformed input
+- sugar equivalence: every sugar call equals its `query()` form
+
+## Migration
+
+Two steps. Only the second carries risk.
+
+1. `src/utils/markdown-query.ts` becomes a re-export shim. **All 54 call sites keep
+   working untouched.**
+2. A sweep updates imports, then fixes the call sites the return-type change breaks.
+
+Deprecated read aliases mean **no read call site changes**. Writes are not shielded: a
+verb that returned `string` now returns `MarkdownDoc`. That breaks four classes of site,
+at least eleven in total.
+
+**(a) Assignment into a `string`-typed target** — 7 sites, each needs `.toString()`:
+
+| Site | Target |
+|---|---|
+| `experience-tracker.ts:265` | `content` (inferred `string`) |
+| `experience-tracker.ts:289` | `combined` (inferred `string`) |
+| `researcher/deep-analysis.ts:129` | `let updated: string` |
+| `researcher/locators.ts:307` | `result.text` |
+| `researcher/locators.ts:309` | `result.text` |
+| `researcher/pagination.ts:61` | `result.text` |
+| `researcher/research-result.ts:57` | `section.rawMarkdown` |
+| `researcher/research-result.ts:58` | `this.text` |
+
+**(b) A string method called on the result** — 2 sites:
+
+- `planner.ts:304` — `.replace('').trim()`
+- `planner.ts:322` — `const kept = ...replace('')`, then `kept.trimEnd()` on line 324
+
+**(c) Returned from a `replaceEach` callback** — `deep-analysis.ts:542`. **Resolved by
+design**, not by migration: callbacks accept `Markdown`, so returning a `MarkdownDoc` is
+valid. No edit needed.
+
+**(d) Compared against a string — the dangerous one.** `research-result.ts:56`:
+
+```js
+const updated = sectionQuery.query('table').replace(`${newTable.trimEnd()}\n`);
+if (updated === this.text) return;     // MarkdownDoc === string is always false
+```
+
+This does not crash. The guard silently stops firing and the method starts doing work it
+used to skip. `tsc` does flag it — comparing types with no overlap is an error — which is
+precisely why the manual type-check below is not optional. Every `replace`/`setEntry`
+result used in an equality or truthiness test must be audited, not just the ones that fail
+to compile.
+
+Sites that flow the result straight back into `mdq()` — `planner.ts:303`, `planner.ts:405`
+— keep working unchanged, because `mdq()` accepts a `MarkdownDoc`.
+
+`tsc` is the complete detector for these breaks: every one surfaces as a type error. The migration step is therefore *run `tsc` over the changed files and fix
+what it reports*, with the table above as the expected result rather than the whole story.
+
+Also in the sweep: `researcher.ts:316` gains its `i` flag (`section2(/^summary/i)`).
+
+### Hazards
+
+- **`.claude/worktrees/**` holds four stale copies** of `markdown-query.ts` and its
+  consumers. Every grep or sed sweep must exclude that path.
+- **`tsc` runs with `--noCheck` in CI.** The nine breaks above are *exactly* the errors a
+  type-check would raise, and CI raises none of them — a fully green build proves nothing
+  here. Run `tsc` manually over the changed files before considering the sweep done.
+
+## Style compliance
+
+The current file violates several repo rules that the rewrite fixes: types belong at the
+end of the file, ternaries are banned (`markdown-query.ts:30`, `:34`, `:129-130`, `:295`),
+and the `switch` in `matchText` should be early returns.
+
+## Deliberately out of scope
+
+- Publishing: no `package.json`, no build script, no npm release in this change.
+- Frontmatter formats other than YAML (TOML `+++`, JSON) — detected and skipped from the
+  token index, but not parsed.
+- Row-level and item-level *selectors* (`addRow` has no `removeRow` partner). A future
+  `row(...)` selector is the right shape for that; guessing at it now is premature.
+- Inline HTML comments.
+- Multi-file CLI input.

package/package.json

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

package/src/action.ts

@@ -16,7 +16,9 @@ import { createDebug, setStepSpanParent, tag } from './utils/logger.js';
 import { Overlay, OverlayPage } from './utils/overlay.js';
 import { sleep, waitForPageReadiness } from './utils/page-readiness.ts';
 import type { Region } from './utils/region.js';
+import { isInternalStep } from './utils/step-analyzer.ts';
 import { safeFilename } from './utils/strings.ts';
+import { isSameHostFamily } from './utils/url-matcher.js';
 import { codeceptJSSandbox, hasPlaywrightCommands, playwrightSandbox, sanitizeCodeBlock } from './utils/web-sandbox.ts';
 
 const debugLog = createDebug('explorbot:action');
@@ -317,7 +319,7 @@ class Action {
 
     const url = URL.parse(request.url());
     if (!url) return;
-    if (url.origin !== this.baseOrigin) return;
+    if (!isSameHostFamily(url.href, this.baseOrigin)) return;
 
     const call: NetworkCall = { method: request.method(), path: url.pathname, status };
     if (this.networkRequests.some((r) => r.method === call.method && r.path === call.path && r.status === call.status)) return;
@@ -563,7 +565,7 @@ export const attachStepLogger = (target: ExecutedStep[], assertionsTarget?: Arra
   let batchFailed = false;
   const listener: StepListener = (step, error) => {
     if (!step?.toCode) return;
-    if (step.name?.startsWith('grab')) return;
+    if (isInternalStep(step)) return;
 
     const existing = recorded.get(step);
     if (existing) {

package/src/ai/fisherman/tools.ts

@@ -221,13 +221,19 @@ export function createAskApiTool(fisherman: Fisherman | null, task: Test) {
   return {
     askApi: tool({
       description: dedent`
-        Ask what data already exists, changing nothing.
-        Ask a question about existing records: which ones are there, what they are called, whether a particular one exists.
-        Use it before precondition() to see whether suitable data is already available, and whenever a step needs the exact name or id of a record that is already there.
+        Read the app's data over the API, changing nothing.
+        Answers questions about records: which ones are there, what they are called, whether a particular one exists.
+
+        Use it to:
+        - check whether suitable data already exists, before precondition() creates any
+        - get the exact name or id of a record a step must act on
+        - find out whether an action was stored, when the app reported success but the page does not show the result
+        - find out whether data exists at all, when a list or dropdown is empty
+
         It never creates, edits or deletes anything — precondition() does that.
       `,
       inputSchema: z.object({
-        question: z.string().describe('What to find out about data that already exists'),
+        question: z.string().describe('What to find out about the data'),
       }),
       execute: async ({ question }) => {
         tag('info').log(`Ask API: ${question}`);

package/src/ai/navigator.ts

@@ -18,7 +18,7 @@ import { createDebug, pluralize, tag } from '../utils/logger.js';
 import { loop, pause } from '../utils/loop.js';
 import { RulesLoader } from '../utils/rules-loader.ts';
 import { normalizeInlineText } from '../utils/strings.ts';
-import { extractStatePath, matchesNavigationUrl } from '../utils/url-matcher.js';
+import { extractStatePath, isSameHostFamily, matchesNavigationUrl } from '../utils/url-matcher.js';
 import type { Agent, AgentDeps } from './agent.js';
 import type { Conversation } from './conversation.js';
 import type { Provider } from './provider.js';
@@ -99,15 +99,6 @@ class Navigator implements Agent {
     return this.config.ai?.agents?.navigator?.verifyTimeout ?? 1500;
   }
 
-  private getBaseOrigin(): string | null {
-    const baseUrl = this.config.playwright.url;
-    try {
-      return new URL(baseUrl).origin;
-    } catch {
-      return null;
-    }
-  }
-
   private getComparableCurrentUrl(stateManager: any, expectedUrl: string): string {
     const currentState = stateManager.getCurrentState();
     if (!currentState) return '';
@@ -126,18 +117,12 @@ class Navigator implements Agent {
     const currentFullUrl = currentState.fullUrl || currentState.url || '';
     if (!currentFullUrl) return false;
 
-    try {
-      const currentOrigin = new URL(currentFullUrl).origin;
-      if (/^https?:\/\//i.test(expectedUrl)) {
-        return currentOrigin === new URL(expectedUrl).origin;
-      }
+    if (!/^https?:\/\//i.test(currentFullUrl)) return !/^https?:\/\//i.test(expectedUrl);
+    if (/^https?:\/\//i.test(expectedUrl)) return isSameHostFamily(currentFullUrl, expectedUrl);
 
-      const baseOrigin = this.getBaseOrigin();
-      if (!baseOrigin) return true;
-      return currentOrigin === baseOrigin;
-    } catch {
-      return !/^https?:\/\//i.test(expectedUrl);
-    }
+    const baseUrl = this.config.playwright.url;
+    if (!baseUrl) return true;
+    return isSameHostFamily(currentFullUrl, baseUrl);
   }
 
   private isOnExpectedPage(expectedUrl: string, stateManager: any): boolean {
@@ -325,8 +310,9 @@ class Navigator implements Agent {
               lastFailure = `Reached ${check.freshState.url} but the page state did not change`;
               tag('warning').log(`Page state did not change at ${check.freshState.url}`);
             } else {
-              lastFailure = `Reached ${check.freshState.url}, expected ${expectedUrl}`;
-              tag('warning').log(`URL verification failed: expected ${expectedUrl}, got ${check.freshState.url}`);
+              const reachedUrl = check.freshState.fullUrl || check.freshState.url;
+              lastFailure = `Reached ${reachedUrl}, expected ${expectedUrl}`;
+              tag('warning').log(`URL verification failed: expected ${expectedUrl}, got ${reachedUrl}`);
             }
             batchFailures.push({
               code: codeBlock,

package/src/ai/pilot.ts

@@ -118,7 +118,9 @@ export class Pilot implements Agent {
     }
 
     const schema = z.object({
-      decision: z.enum(['pass', 'fail', 'continue', 'skipped']).describe('pass = test succeeded, fail = test failed, continue = tester should keep going, skipped = scenario is irrelevant OR systematic execution failures prevented testing'),
+      decision: z
+        .enum(['pass', 'fail', 'continue', 'skipped'])
+        .describe('pass = scenario goal accomplished, fail = the app misbehaved, continue = tester should keep going, skipped = the scenario cannot be judged against this app (its premise does not hold, it is irrelevant, or systematic execution failures prevented testing)'),
       reason: z.string().describe('Concise user-facing reason, maximum 1 short sentence and 120 characters. Do NOT repeat the decision status; explain only the evidence. For continue: explain why rejected and suggest alternatives.'),
       guidance: z.string().nullable().describe('Required for "continue": specific actionable instruction for the tester — what exactly to verify, retry differently, or complete next. Be concrete.'),
       requestVerification: z
@@ -407,9 +409,13 @@ export class Pilot implements Agent {
         DOM assertion can't be made.
         Do not pass when Tester achieved only a related navigation/filter/tab/status outcome instead of the
         requested action, workflow, or entity detail goal.
-      - "fail": goal not achieved and no further step toward it is available on the current page.
-      - "skipped": scenario is irrelevant to the app, OR systematic infrastructure failures (LLM errors,
-        crashes) prevented testing. NOT for "test failed to interact" — that's "fail" or "continue".
+      - "fail": the app misbehaved — the scenario's action ran against the right target and the app
+        produced a wrong, broken, or missing outcome. Not reaching the goal is not by itself a fail.
+      - "skipped": the scenario cannot be judged against this app — the page shows its premise does not
+        hold (the assumed constraint, field, or behaviour is designed differently), the target entity or
+        feature is not the one here, the scenario is irrelevant, OR systematic infrastructure failures
+        (LLM errors, crashes) prevented testing. NOT for "test failed to interact" — that's "fail" or
+        "continue".
       - "continue": goal incomplete but the control for the NEXT step is present on the current page, or a
         concrete missing check would change your verdict. Guidance must name that step.
         If a verify() asserted a state that was ALREADY TRUE before the test, it proves nothing — reject.
@@ -1016,14 +1022,14 @@ export class Pilot implements Agent {
   private formatSuccessfulAssertions(currentState: ActionResult, testerConversation: Conversation): string {
     const lines: string[] = [];
     for (const [assertion, passed] of Object.entries(currentState.verifications ?? {})) {
-      if (passed) lines.push(`state verification (passed): ${assertion}`);
+      if (passed) lines.push(`verify: ${assertion}`);
     }
 
     for (const exec of testerConversation.getToolExecutions()) {
       if (!EVIDENCE_TOOLS.includes(exec.toolName) || !exec.wasSuccessful) continue;
       const description = exec.input?.assertion || exec.input?.request || truncateJson(exec.input);
-      const result = exec.output?.message || exec.output?.analysis || exec.output?.result;
-      lines.push(`CHECK ${exec.toolName} (executed successfully): ${description}${result ? ` -> ${result}` : ''}`);
+      const analysis = exec.output?.analysis;
+      lines.push(`${exec.toolName}: ${description}${analysis ? ` -> ${analysis}` : ''}`);
     }
 
     return [...new Set(lines)].join('\n');
@@ -1157,9 +1163,14 @@ export class Pilot implements Agent {
 
       YOUR Pilot-only tools, both over the API:
 
-      askApi(question) — ask what data already exists. It changes nothing. Use it to check whether
-      suitable data is already there before creating any, and to get the exact name or id of an existing
-      record a step must act on.
+      askApi(question) — read the app's data over the API. It changes nothing. Use when:
+
+      - Before precondition() — check whether suitable data already exists.
+      - A step needs the exact name or id of an existing record.
+      - The app reported success but the page does not show the result — ask whether it was stored.
+      - A list or dropdown is empty — ask whether the data exists at all.
+
+      The page is not the only witness. A record missing from the page may still exist.
 
       precondition(description) — create FRESH disposable test data. Never request users. Use when:
 

package/src/ai/rerunner.ts

@@ -18,6 +18,7 @@ import { formatHeadings } from '../utils/context-formatter.ts';
 import { createDebug, tag } from '../utils/logger.ts';
 import { loop } from '../utils/loop.ts';
 import { RulesLoader } from '../utils/rules-loader.ts';
+import { isInternalStep } from '../utils/step-analyzer.ts';
 import type { Agent, AgentDeps } from './agent.ts';
 import { toolExecutionLabel } from './conversation.ts';
 import type { Navigator } from './navigator.ts';
@@ -85,6 +86,7 @@ export class Rerunner extends TaskAgent implements Agent {
 
     const onStepStarted = (step: any) => {
       if (!step.toCode) return;
+      if (isInternalStep(step)) return;
       const code = highlight(step.toCode(), { language: 'javascript' });
       console.log(chalk.dim(`    ${code}`));
     };
@@ -92,12 +94,14 @@ export class Rerunner extends TaskAgent implements Agent {
     const onStepPassed = (step: any) => {
       const task = this.getCurrentTask(testMap);
       if (!task || !step.toCode) return;
+      if (isInternalStep(step)) return;
       task.addStep(step.toCode(), step.duration, 'passed');
     };
 
     const onStepFailed = (step: any, error: any) => {
       const task = this.getCurrentTask(testMap);
       if (!task || !step.toCode) return;
+      if (isInternalStep(step)) return;
       task.addStep(step.toCode(), step.duration, 'failed', error?.message);
       console.log(chalk.red(`    ${figureSet.cross} ${step.toCode()} — ${error?.message || 'failed'}`));
     };

package/src/ai/tools.ts

@@ -1368,16 +1368,22 @@ async function extractWebElements(error: Error | null | undefined): Promise<Matc
 
 function formatElementList(matched: MatchedElement[] | null): string {
   if (!matched) return 'Could not fetch element details. Repeat the action to get better info.';
-  return matched
+  const keys = matched.map((el) => `${el.text}::${el.visible}::${el.html}`);
+  const list = matched
     .map((el, i) => {
       const lines = [`Element ${i + 1}:`, `Text: "${el.text}"`];
       if (el.visible !== undefined) lines.push(`Visible: ${el.visible}`);
       const wrapped = matched.map((_, j) => j).filter((j) => j !== i && matched[j].xpath.startsWith(`${el.xpath}/`));
       if (wrapped.length) lines.push(`Wraps: element ${wrapped.map((j) => j + 1).join(', ')}`);
+      const same = keys.map((_, j) => j).filter((j) => j !== i && keys[j] === keys[i]);
+      if (same.length) lines.push(`Identical to element ${same.map((j) => j + 1).join(', ')}`);
       lines.push(`XPath: ${el.xpath}`, `HTML: ${el.html}`);
       return lines.join('\n');
     })
     .join('\n\n');
+
+  if (new Set(keys).size === matched.length) return list;
+  return `${list}\n\nIdentical matches are not told apart by their number — picking one is a guess. Click the one you mean by appearance with visualClick().`;
 }
 
 export async function formatMatchedElements(error: Error | null | undefined): Promise<string | null> {

package/src/api/xhr-capture.ts

@@ -1,3 +1,4 @@
+import { isSameHostFamily } from '../utils/url-matcher.js';
 import { RequestResult, generateRequestId } from './request-result.ts';
 import type { RequestStore } from './request-store.ts';
 
@@ -39,7 +40,7 @@ export class XhrCapture {
 
     const method = request.method();
     const url = request.url();
-    if (!url.startsWith(this.baseOrigin)) return;
+    if (!isSameHostFamily(url, this.baseOrigin)) return;
 
     const status = response.status();