@molecule/api-ai-tools 1.10.1 → 1.10.2

package/dist/utilities.js

@@ -343,8 +343,9 @@ const PRINTING_REPORTERS = new Set(['list', 'line', 'dot', 'basic', 'spec']);
  * inline the end-of-run repeat is suppressed with it (`epilogue(!printFailuresInline)`), so one
  * reporter still prints each failure exactly once.
  *
- * A background suite is put on `list` (see {@link streamingBackgroundCommand}) and this with it, so
- * the log names its causes WHILE it walks. Without it the log's only failure lines are `✘` rows:
+ * Every background command is given this (see {@link streamingBackgroundCommand}), so a suite the
+ * executor starts through its own wrapper is covered too — the wrapper passes the environment on
+ * to the Playwright process it spawns. Without it the log's only failure lines are `✘` rows:
  * X1 xr-molecule-flash-m99 (+19:27 → +21:00, 2026-10-16) was told to `grep -n -A 20 '<test name>'`
  * the log, got nothing back through four greps, inferred causes from the spec prose instead, and
  * edited `app/src` while the run was still walking — which voids the run.
@@ -398,10 +399,12 @@ function isStatusOnlyStep(step) {
  * `junit`) is the
  * executor's own and is left exactly as it is — so is any reporter this build does not know.
  *
- * A run put on `list` is also given {@link PLAYWRIGHT_FAILURES_INLINE_ENV}, so each failure's own
- * error is in the log as that test fails rather than only at the end: a suite that is still walking
- * is exactly when the executor reads the log, and without it a running log carries `✘` rows and
- * nothing else (xr-molecule-flash-m99 spent ~90 s on greps of one, then fixed what it guessed).
+ * Every background command that is not a no-test invocation is also given
+ * {@link PLAYWRIGHT_FAILURES_INLINE_ENV} (inert except for Playwright's `list` reporter), so each
+ * failure's own error is in the log as that test fails rather than only at the end: a suite that is
+ * still walking is exactly when the executor reads the log, and without it a running log carries
+ * `✘` rows and nothing else (xr-molecule-flash-m99 spent ~90 s on greps of one, then fixed what it
+ * guessed; m191's wrapper-launched run lost 6.5 minutes to the same shape).
  *
  * Only the step that runs the suite is touched, and only its reporter, and only when that step
  * runs something: `npx playwright test --list` takes two seconds and writes nothing per test, so
@@ -604,16 +607,26 @@ export function streamingBackgroundCommand(command, context) {
         changes.push('Added `--reporter=list` so each test result is written to the log as it finishes ' +
             '(the config reporter may print nothing until the end).');
     }
-    // The run's failures, in the log as they fail (see PLAYWRIGHT_FAILURES_INLINE_ENV). Only for a
-    // run that ends on `list` — a run whose only reporters are machine formats has no failure lines
-    // to make inline, and this is inert for one — and set as an `export` at the head of the whole
-    // command, never mid-command: the last step may be a wrapper (`timeout 280 npx playwright test`)
-    // or start a line of its own (a multi-line command's last line), and an assignment written in
-    // front of either would be read as the program to run.
+    // The run's failures, in the log as they fail (see PLAYWRIGHT_FAILURES_INLINE_ENV), on EVERY
+    // background command that is not a no-test invocation — not only the ones whose text this
+    // reader can place the runner in. The executor starts the suite through its own wrapper often
+    // (`node scripts/run-realworld-e2e.mjs`, `npm run e2e`), and the wrapper passes its environment
+    // on to the Playwright process it spawns; keying the switch on a recognized `playwright test`
+    // step withheld it from exactly those runs, whose logs then carried `✘` rows and nothing else
+    // while the executor waited (xr-molecule-flash-m191 +12:20 → +19:40: 65 failures and ONE cause,
+    // named at the last failure instead of at the third — 6.5 minutes lost). It is inert for
+    // anything but Playwright's `list` reporter, which is the only reader of it.
+    //
+    // Set as an `export` at the head of the whole command, never mid-command: the last step may be
+    // a wrapper (`timeout 280 npx playwright test`) or start a line of its own (a multi-line
+    // command's last line), and an assignment written in front of either would be read as the
+    // program to run.
+    out = `export ${PLAYWRIGHT_FAILURES_INLINE_ENV}=1; ${out}`;
+    // The sentence is only true of a run this reader put on `list` — a command it cannot place (a
+    // wrapper, `npm run build`) gets the switch silently, and that is all it needs.
     const endsOnListReporter = finalPlaywrightRun &&
         (reporters === null || reporters.values.some((v) => PRINTING_REPORTERS.has(v)));
     if (endsOnListReporter) {
-        out = `export ${PLAYWRIGHT_FAILURES_INLINE_ENV}=1; ${out}`;
         changes.push('Each failure’s own error is now written into the log as that test fails, not only in the ' +
             'summary at the end — so a run that is still walking already says what its failures are, ' +
             'and you need not wait for it to end to start on them.');
@@ -809,6 +822,61 @@ export function suiteRunBudgetCommand(command, flags) {
     }
     return { command: out, placed, unplaced };
 }
+/** The config flag and the separator before its value, as a run may write it. */
+const CONFIG_ARGUMENT = /(?:^|[\s;&|(])(?:--config|-c)(?:=|\s+)/g;
+/**
+ * A command with the derived config put on the LAST suite runner's own arguments, replacing the
+ * config the run names or added when it names none.
+ *
+ * Some of the suite's settings have no Playwright flag (`expect.timeout`, `use.actionTimeout`,
+ * `use.navigationTimeout`), so a config the executor wrote cannot be corrected from the command
+ * line. The consumer writes a derived config OUTSIDE the supplied suite that re-imports the one
+ * the run selected and pins those settings ({@link SuiteBudgetPin.config}); pointing the runner at
+ * it is the one way to carry them, and it belongs on the runner itself for the same reasons
+ * {@link suiteRunBudgetCommand}'s flags do (last suite step, before a pipe or group closer).
+ *
+ * A command whose runner cannot be placed is returned exactly as written with `placed: false`, so
+ * the caller never claims a config it did not point the run at.
+ *
+ * @param command - The shell command about to run.
+ * @param config - The config to run, as the runner takes it (`--config <path>`).
+ * @returns The command to run and whether the config was placed.
+ */
+export function suiteRunConfigCommand(command, config) {
+    const run = suiteRunnerArguments(command);
+    if (run === null)
+        return { command, placed: false };
+    const text = command.slice(run.start, run.at);
+    CONFIG_ARGUMENT.lastIndex = 0;
+    let last = null;
+    for (let m = CONFIG_ARGUMENT.exec(text); m !== null; m = CONFIG_ARGUMENT.exec(text)) {
+        const start = m.index + m[0].length;
+        const quote = text[start];
+        if (quote === '"' || quote === "'") {
+            const close = text.indexOf(quote, start + 1);
+            if (close === -1)
+                continue;
+            last = { start: start + 1, end: close };
+            // The value may not continue into a second quoted word: resume after the closer.
+            CONFIG_ARGUMENT.lastIndex = close + 1;
+        }
+        else {
+            const value = /^[^\s;&|)]*/.exec(text.slice(start))?.[0] ?? '';
+            if (value === '')
+                continue;
+            last = { start, end: start + value.length };
+        }
+    }
+    if (last === null) {
+        return {
+            command: `${command.slice(0, run.at)} --config=${config}${command.slice(run.at)}`,
+            placed: true,
+        };
+    }
+    const from = run.start + last.start;
+    const to = run.start + last.end;
+    return { command: `${command.slice(0, from)}${config}${command.slice(to)}`, placed: true };
+}
 /**
  * The command with the `timeout <N>` wrapper lifted off the statement that runs the suite, and the
  * bound that was lifted.
@@ -2287,6 +2355,40 @@ export function repeatingFailure(log) {
     const mean = best.reduce((sum, t) => sum + t.seconds, 0) / best.length;
     return { count: best.length, message: null, seconds: Math.round(mean * 10) / 10, tests: best };
 }
+/**
+ * Whether the log read so far carries a failure's own body under a `✘` row — the evidence that a
+ * run prints each failure's error as that test fails ({@link PLAYWRIGHT_FAILURES_INLINE_ENV}).
+ *
+ * `wait_for_task` promises the executor that each failure's report sits right under its `✘` line
+ * only when the log proves it. The command's shape cannot answer: the launch sets the switch on
+ * every background command (the executor's wrapper script inherits it), so a wrapper this reader
+ * cannot place is exactly as covered as `npx playwright test` ({@link streamingBackgroundCommand}).
+ * The log is the evidence — a `1) [project] › spec › title ───` block whose test the log also
+ * printed with `✘` ({@link failureBlocks}).
+ *
+ * A block alone is not enough: a FINISHED run's end-of-run summary carries the same blocks, and a
+ * running wait must not be told "as it fails" about a log whose bodies only appear at the end.
+ * During a wait the run has not ended (the exit file is read first), so a block beside a `✘` row
+ * is one the reporter printed inline.
+ *
+ * @param log - A log, or the slice of one a wait reads.
+ * @returns True when a `✘` row's own test has a failure body under it.
+ */
+export function logShowsInlineFailureBodies(log) {
+    const text = log.replace(ANSI_SGR, '');
+    const failed = new Set(distinctTests(failedTests(text)).map(retrylessTestKey));
+    if (failed.size === 0)
+        return false;
+    for (const block of failureBlocks(text)) {
+        const m = FAILURE_BLOCK_HEADER.exec(block.split('\n')[0] ?? '');
+        if (m === null)
+            continue;
+        const { where, title } = splitTitlePath(m[1] ?? '');
+        if (failed.has(retrylessTestKey({ where, title, seconds: null })))
+            return true;
+    }
+    return false;
+}
 /** How many of a repeating cause's failures the note lists before it says "and N more". */
 export const REPEATING_FAILURE_LISTED = 5;
 /**
@@ -2392,11 +2494,12 @@ export const UNIVERSAL_CAUSE_FILES = 3;
  * (m177: 18 tests, ~4.2 minutes, on a page whose thrown error was visible in the first
  * `pageerror`). Three is the smallest count that is not one page's own bug: the cause additionally
  * needs three DISTINCT spec files (`UNIVERSAL_CAUSE_FILES`, or the files a narrowed run selected),
- * each spec waiting for its OWN first element, and no test passing after the first failure. A page
- * that renders misses elements, but three unrelated specs in three files failing at three
- * different first locators with nothing passing in between is the page, not three bugs. At the
- * suite's own 5 s action timeout that verdict lands ~20 s into the walk, so the early stop costs
- * about one test's worth of time instead of fifteen.
+ * no failure showing a locator RESOLVING ({@link ELEMENT_FOUND} — a blank page cannot resolve
+ * one), and no test passing after the first failure. A page that renders misses elements, but
+ * three unrelated specs in three files failing at three different locators that never resolved,
+ * with nothing passing in between, is the page, not three bugs. At the suite's own 5 s action
+ * timeout that verdict lands ~20 s into the walk, so the early stop costs about one test's worth
+ * of time instead of fifteen.
  */
 export const EMPTY_PAGE_CAUSE_TESTS = 3;
 /**
@@ -2406,6 +2509,19 @@ export const EMPTY_PAGE_CAUSE_TESTS = 3;
  * test's own code — is a different failure and leaves this reading nothing.
  */
 const LOCATOR_WAIT = /waiting for locator\(|element\(s\) not found|toBeVisible\(\) failed/;
+/**
+ * A failure body that shows the page PAINTED: Playwright's call log RESOLVED the locator to an
+ * element (`locator resolved to <i …>`, `resolved to 2 elements`) and only then found it
+ * unusable (`element is not visible` / `not enabled` / `not stable` / `not attached`, `outside
+ * of the viewport`). A blank page cannot resolve a locator, so one of these anywhere in a run
+ * disproves {@link emptyPageCause}.
+ *
+ * xr-molecule-flash-m187 (+15:39 and +18:54) narrowed two re-runs to the tests that had just
+ * failed, and both were stopped as "the app is rendering NOTHING" while every block in the log
+ * carried `locator resolved to <i class="ion-close-circled"></i>` followed by `element is not
+ * visible` — the page was drawn, and only an icon had no box.
+ */
+const ELEMENT_FOUND = /locator resolved to (?:<|[1-9]\d* elements?\b)|element is (?:not (?:visible|enabled|stable|attached)\b|outside of the viewport)/;
 /** An uncaught page error, as a run that listens for `pageerror` prints it. */
 const PAGE_ERROR_LINE = /^\s*(?:\[pageerror\]|pageerror:)\s*(.+)$/m;
 /** An uncaught page error, in the browser's own `Uncaught …` wording. */
@@ -2425,7 +2541,18 @@ function pageErrorInLog(text) {
  * The "nothing has passed and nothing renders" cause: the run's FIRST consecutive failures — from
  * its first failed test, with no pass since — are all locator waits, at least
  * {@link EMPTY_PAGE_CAUSE_TESTS} of them across {@link UNIVERSAL_CAUSE_FILES} different spec
- * files, and each waits for its own spec's first element.
+ * files, and NO failure block shows the page resolving the locator it waited for
+ * ({@link ELEMENT_FOUND}).
+ *
+ * "No locator resolved" is the check that says the page painted nothing; it replaced an
+ * earlier claim that each failure waits for its own spec's FIRST element, which the code never
+ * verified and the log alone cannot verify (Playwright prints only the failing line, not the
+ * spec's first one). A narrowed re-run of known failures meets every other condition by
+ * construction — every test in it failed last time at a locator wait — so the page-painted
+ * evidence is what keeps it from reading as an empty page. When the command names the
+ * individual tests (`file:line`), a re-run of exactly those is also skipped
+ * ({@link selectedTestRefs}): the executor is verifying fixes, and the stop would throw away
+ * the verdict the re-run exists to give.
  *
  * The file span stays at {@link UNIVERSAL_CAUSE_FILES} whatever the run selected: "the page
  * renders nothing" is a claim about the APP, and one file's failures can be that file's own setup
@@ -2445,9 +2572,11 @@ function pageErrorInLog(text) {
  *
  * @param text - The log (ANSI already stripped).
  * @param found - The repeating cause {@link repeatingFailure} found, when it found one.
+ * @param command - How the run was started, when the caller knows it: a command naming the
+ *   individual tests it selects marks a re-run of known failures ({@link selectedTestRefs}).
  * @returns The cause, or null when the log is not this shape.
  */
-function emptyPageCause(text, found) {
+function emptyPageCause(text, found, command) {
     const marks = resultMarks(text);
     const firstFailure = marks.indexOf('✘');
     if (firstFailure === -1 || marks.slice(firstFailure).includes('✓'))
@@ -2455,12 +2584,26 @@ function emptyPageCause(text, found) {
     const blocks = failureBlocks(text);
     if (blocks.length === 0 || !blocks.every((block) => LOCATOR_WAIT.test(block)))
         return null;
+    // A blank page cannot RESOLVE a locator: `locator resolved to …` (or an actionability outcome
+    // like `element is not visible`) means the page painted and only the element's box or
+    // visibility was wrong. xr-molecule-flash-m187 stopped two narrowed re-runs on exactly this.
+    if (blocks.some((block) => ELEMENT_FOUND.test(block)))
+        return null;
     // Both readings of the same failures: a `list` line carries the test and its duration, a
     // numbered block carries its body. The larger is the count — a failure that has a block but
     // whose result line the poll had not reached yet is still a failure.
     const byList = distinctTests(failedTests(text));
     const byBlock = distinctTests(failureBlockTests(text));
     const tests = byBlock.length >= byList.length ? byBlock : byList;
+    // A run whose command names individual tests, and whose every failure is one of them, is a
+    // re-run of known failures, never an empty-page stop: the executor is checking fixes it just
+    // made, and stopping it throws away that verdict (xr-molecule-flash-m187, twice).
+    const selected = command ? selectedTestRefs(command) : null;
+    if (selected !== null &&
+        tests.length > 0 &&
+        tests.every((test) => selected.some((ref) => sameTestRef(ref, test.where)))) {
+        return null;
+    }
     // One signature already covers every failure: that is the signature cause, and its wording
     // (which names the repeated error) says more than "the page renders nothing" would.
     if (found !== null && found.message !== null && found.count >= tests.length)
@@ -2572,6 +2715,62 @@ export function specFilesSelected(command) {
     }
     return null;
 }
+/**
+ * The individual tests a `playwright test` command names (`file:line` positionals), or null when
+ * it selects whole files, a directory, a glob, a bare filter, or nothing at all.
+ *
+ * A command that names `file:line` tests is a re-run of tests that already failed — the shape
+ * {@link emptyPageCause} must not read as "the page renders nothing", because the executor is
+ * verifying fixes and the stop throws that verdict away (xr-molecule-flash-m187, twice).
+ *
+ * @param command - The run's command.
+ * @returns The selected test references, or null when the selection is not per-test.
+ */
+function selectedTestRefs(command) {
+    for (const segment of commandSegments(command)) {
+        if (!/^playwright\s+test\b/.test(segment.text))
+            continue;
+        const refs = [];
+        let flagValue = false;
+        for (const word of segment.args.slice(1)) {
+            const token = word.replace(/^(['"])(.*)\1$/, '$2');
+            if (flagValue) {
+                flagValue = false;
+                continue;
+            }
+            if (token.startsWith('-')) {
+                const flag = token.includes('=') ? token.slice(0, token.indexOf('=')) : token;
+                flagValue = !token.includes('=') && PLAYWRIGHT_VALUE_FLAGS.has(flag);
+                continue;
+            }
+            const m = /^(.*\.(?:spec|test)\.[cm]?[jt]sx?):(\d+)(?::\d+)?$/.exec(token);
+            if (!m)
+                return null;
+            refs.push({ path: m[1], line: Number(m[2]) });
+        }
+        return refs.length > 0 ? refs : null;
+    }
+    return null;
+}
+/**
+ * Whether a failing test (`file:line`, as the log printed it) is the test one of the command's
+ * `file:line` selectors names.
+ *
+ * Paths are compared by suffix: the log prints the path from the suite root
+ * (`fixtures/conduit-spec/specs/e2e/articles.spec.ts:229`) while the command names it from its
+ * own cwd (`articles.spec.ts:229`), so neither is a prefix of the other.
+ *
+ * @param ref - One selected test reference.
+ * @param where - The failed test's `file:line` (see {@link splitTitlePath}).
+ * @returns True when they name the same test.
+ */
+function sameTestRef(ref, where) {
+    const m = /^(.*\.(?:spec|test)\.[cm]?[jt]sx?):(\d+)$/.exec(where);
+    if (!m || Number(m[2]) !== ref.line)
+        return false;
+    const path = m[1];
+    return path === ref.path || path.endsWith(`/${ref.path}`) || ref.path.endsWith(`/${path}`);
+}
 /**
  * Whether a repeating cause is failing the whole run — the one case where stopping it is the
  * right call.
@@ -2608,9 +2807,9 @@ export function universalCause(log, found, command) {
     // can never span three of them, however whole its failure is.
     const selected = command ? specFilesSelected(command) : null;
     const threshold = selected === null ? UNIVERSAL_CAUSE_FILES : Math.min(UNIVERSAL_CAUSE_FILES, selected);
-    // Nothing has passed and nothing renders: EVERY spec so far is waiting for its own first
-    // element, so the signatures differ while the cause does not (xr-molecule-flash-m141).
-    const emptyPage = emptyPageCause(text, found);
+    // Nothing has passed and nothing renders: EVERY spec so far is waiting for an element the
+    // page never painted, so the signatures differ while the cause does not (xr-molecule-flash-m141).
+    const emptyPage = emptyPageCause(text, found, command);
     if (emptyPage)
         return emptyPage;
     if (!found)
@@ -2957,6 +3156,178 @@ function noBaseUrlConfigNote(causes, run, excluded) {
                 'with `--config`; this command names none. ') +
         (command ? `Send exactly this: \`${command}\`` : ''));
 }
+/**
+ * A selector that names the page's navigation landmark: the `nav` tag, a `navbar`/`nav-*` class,
+ * or `role=navigation`. `a.navbar-brand` names it through its class — the brand link is the
+ * navbar's own child in every theme this reader has seen.
+ */
+const NAVIGATION_SELECTOR = /(?:^|[\s>+~,(])nav(?=$|[\s.#:[>+~,)])|\.navbar(?:-[a-z-]+)?(?![\w-])|\[role\s*=\s*['"]?navigation['"]?\]/i;
+/** A selector that names the page's header landmark: the `header` tag or `role=banner`. */
+const HEADER_SELECTOR = /(?:^|[\s>+~,(])header(?=$|[\s.#:[>+~,)])|\[role\s*=\s*['"]?banner['"]?\]/i;
+/**
+ * The quoted argument of each `locator(...)` call in a failure block. Both quote styles are
+ * matched separately: a selector routinely carries the OTHER quote inside it
+ * (`locator('nav a[href="/"]')`), which one shared backreferenced class would cut short.
+ */
+const QUOTED_LOCATORS = [/locator\(\s*'([^']*)'/g, /locator\(\s*"([^"]*)"/g];
+/** The role a `getByRole(...)` call names, when the role is a landmark this reader knows. */
+const QUOTED_ROLE = /getByRole\(\s*(['"])(navigation|banner)\1/gi;
+/** The path an `[href="…"]` / `[to="…"]` filter names, when it is a root-relative route. */
+const HREF_FILTER = /\[(?:href|to)\s*=\s*(['"])([^'"]+)\1\]/g;
+/**
+ * The landmark a selector requires as an ANCESTOR (or names as its own role), or null when it
+ * names no landmark at all (`h1`, `.article-preview`, `a[href="/profile/x"]`).
+ *
+ * @param selector - One CSS selector or `getByRole` role from a failure's call log.
+ * @returns The landmark, or null.
+ */
+export function requiredLandmark(selector) {
+    if (NAVIGATION_SELECTOR.test(selector))
+        return 'navigation';
+    if (HEADER_SELECTOR.test(selector))
+        return 'banner';
+    return null;
+}
+/**
+ * The route a selector names through an `[href="…"]`/`[to="…"]` filter (`nav a[href="/"]` → `/`),
+ * or null when it names none. The query string and hash are dropped: the route is the path.
+ *
+ * @param selector - One CSS selector from a failure's call log.
+ * @returns The path, or null.
+ */
+function routeNamedBySelector(selector) {
+    for (const match of selector.matchAll(HREF_FILTER)) {
+        const value = match[2] ?? '';
+        if (!value.startsWith('/') || value.startsWith('//'))
+            continue;
+        const path = value.split(/[?#]/)[0] ?? value;
+        return path === '' ? '/' : path;
+    }
+    return null;
+}
+/**
+ * The failures whose own selector requires a landmark — the rows {@link missingHeaderNote}
+ * compares against their page snapshots.
+ *
+ * @param text - The run's output, ANSI already stripped.
+ * @returns The failures, in the order the run printed them.
+ */
+function missingLandmarkFailures(text) {
+    const out = [];
+    for (const block of failureBlocks(text)) {
+        const header = FAILURE_BLOCK_HEADER.exec(block.split('\n')[0] ?? '');
+        const { where } = splitTitlePath(header?.[1] ?? '');
+        const selectors = [];
+        // The block's own words, without the code frame: a `12 | await page.locator('header')` line
+        // is the spec's SOURCE beside the failure, not the locator it waited for.
+        const words = failureBody(block).join('\n');
+        for (const pattern of QUOTED_LOCATORS)
+            for (const match of words.matchAll(pattern))
+                selectors.push(match[1]);
+        for (const match of words.matchAll(QUOTED_ROLE))
+            selectors.push(`[role="${match[2]}"]`);
+        const distinct = [...new Set(selectors)];
+        const needing = distinct.filter((selector) => requiredLandmark(selector) !== null);
+        if (needing.length === 0)
+            continue;
+        // Navigation outranks banner for a selector that names both (a `header nav …` chain): the
+        // finding's own sentence is about the missing navigation.
+        const landmark = needing.some((selector) => requiredLandmark(selector) === 'navigation')
+            ? 'navigation'
+            : 'banner';
+        const route = needing.map(routeNamedBySelector).find((candidate) => candidate !== null) ?? null;
+        out.push({ where, landmark, selectors: needing, route });
+    }
+    return out;
+}
+/**
+ * The snapshot a failure's own `error-context.md` produced, keyed the way the log and the
+ * artifact both spell the test's location. The log writes the path relative to the command's
+ * cwd and the artifact read keys it the same way, but a caller that shortened one side is
+ * matched on its tail rather than losing the reading.
+ *
+ * @param where - The failure's location.
+ * @param pageErrors - The snapshots the caller read.
+ * @returns The entry, or undefined when this test has none.
+ */
+function pageSnapshotFor(where, pageErrors) {
+    const exact = pageErrors.find((entry) => entry.where === where);
+    if (exact !== undefined)
+        return exact;
+    return pageErrors.find((entry) => (where !== '' && entry.where.endsWith(`/${where}`)) ||
+        (entry.where !== '' && where.endsWith(`/${entry.where}`)));
+}
+/** How the sentence names the landmark: the finding's words, one per role. */
+const LANDMARK_WORD = {
+    navigation: 'navigation',
+    banner: 'header',
+};
+/**
+ * The sentence for a run whose navigational elements are all missing from pages that otherwise
+ * painted — the missing shared header the executor must check BEFORE rewriting auth.
+ *
+ * xr-molecule-flash-m193 (+13:54 → +20:00): four failures on `/` — `a[href="/profile/…"]`,
+ * `a.navbar-brand`, `nav a[href="/"]`, `nav .user-pic` — while every `error-context.md` snapshot
+ * showed the feed, sidebar and footer with no navigation at all. `Home.tsx` imported and
+ * re-exported `Navbar` but never rendered it, and `App.tsx` mounted `<Home />` in a bare route.
+ * The cause list named four unrelated symptoms, so the run rewrote `Navbar`'s auth logic and then
+ * the HTTP bond across two whole walks (~6 minutes) instead of mounting the header.
+ *
+ * The reading is per FAILURE and per SNAPSHOT: each failure's own selector must require the
+ * landmark, its own snapshot must have been read AND show populated page content, and that
+ * snapshot must not contain the landmark. Two or more such failures on ONE route (the route a
+ * selector names, e.g. `nav a[href="/"]` → `/`; failures whose selector names none ride along)
+ * are the group. A page that shows the navigation and merely misses a signed-in link is not this
+ * shape — its snapshots contain the landmark, so nothing is said.
+ *
+ * This never stops the run and never claims the page is blank: it is one sentence prepended to
+ * the causes note ({@link failureCausesNote}).
+ *
+ * @param log - The run's output.
+ * @param pageErrors - The page snapshot facts the caller read per failing test.
+ * @returns The sentence, or null when the failures do not share a missing landmark.
+ */
+export function missingHeaderNote(log, pageErrors = []) {
+    if (pageErrors.length === 0)
+        return null;
+    const failures = missingLandmarkFailures(log.replace(ANSI_SGR, ''));
+    for (const landmark of ['navigation', 'banner']) {
+        const needing = failures.filter((failure) => failure.landmark === landmark);
+        if (needing.length < 2)
+            continue;
+        // One route is what the sentence can name; two named routes are two pages, not one group.
+        const routes = [...new Set(needing.map((failure) => failure.route).filter(Boolean))];
+        if (routes.length !== 1)
+            continue;
+        const route = routes[0];
+        const group = needing.filter((failure) => failure.route === null || failure.route === route);
+        if (group.length < 2)
+            continue;
+        // Every snapshot in the group must have been READ, and each must show populated content
+        // without the landmark. A snapshot that is missing, blank, or carries the landmark leaves
+        // the reading unproven.
+        const proven = group.every((failure) => {
+            const snapshot = pageSnapshotFor(failure.where, pageErrors);
+            if (snapshot === undefined || snapshot.landmarks === undefined)
+                return false;
+            if (snapshot.populated !== true)
+                return false;
+            return !snapshot.landmarks.includes(landmark);
+        });
+        if (!proven)
+            continue;
+        const selectors = [...new Set(group.flatMap((failure) => failure.selectors))];
+        const named = selectors.map((selector) => `\`${selector}\``);
+        const list = named.length <= 1
+            ? (named[0] ?? '')
+            : `${named.slice(0, -1).join(', ')} and ${named[named.length - 1]}`;
+        return (`The \`${route}\` snapshots contain populated main content but no ` +
+            `${LANDMARK_WORD[landmark]} landmark. These ${list} failures share the missing header; ` +
+            `check whether the route actually renders its shared header before changing authentication ` +
+            `or the header component’s internals.`);
+    }
+    return null;
+}
 /**
  * The one-line-per-cause summary of a finished run's failures, or null when the run named fewer
  * than two of them.
@@ -2984,7 +3355,14 @@ function noBaseUrlConfigNote(causes, run, excluded) {
  *   the "left out" sentence greps when more causes exist than the result has room for.
  * @returns The note, or null.
  */
-export function failureCausesNote(log, excluded = [], run, pageErrors = []) {
+export function failureCausesNote(log, excluded = [], run, pageErrors = [], 
+/**
+ * Spec files whose selector-contract rows an edit broke since the last whole walk, when the
+ * caller knows them: the narrowed re-run names them beside the failing tests. A green re-run of
+ * the failure alone would certify a tree it never measured, and the specs selecting the
+ * element the edit removed were never walked (xr-molecule-flash-m187 shipped that).
+ */
+regressedSpecs = []) {
     const { causes, ignored, flaky } = groupFailures(log, excluded, pageErrors);
     const total = causes.reduce((n, c) => n + c.tests.length, 0);
     if (total < 2)
@@ -2997,8 +3375,14 @@ export function failureCausesNote(log, excluded = [], run, pageErrors = []) {
     // (xr-molecule-flash-m101 +12:13 re-ran all 139, ~4 minutes, to check two). The command is the
     // run's own invocation narrowed by the ONE composer the mid-run note also uses
     // ({@link rerunOfRunningSuite}), with the request's exclusions inverted out so the re-run
-    // cannot report them again.
-    const locations = [...new Set(causes.flatMap((c) => c.tests.map((t) => t.where)).filter(Boolean))];
+    // cannot report them again. The regressed specs ride the same set: a re-run of the failures
+    // alone does not measure what an edit removed from the markup those specs select (m187).
+    const locations = [
+        ...new Set([
+            ...causes.flatMap((c) => c.tests.map((t) => t.where)).filter(Boolean),
+            ...regressedSpecs,
+        ]),
+    ];
     const rerun = run ? rerunOfRunningSuite(run, locations, excluded) : null;
     // A document the browser could not load explains every failure at once, and it is not in the
     // app: m118 (+37:09) read 14 `page.goto` timeouts as app failures while the page load had ended
@@ -3041,13 +3425,20 @@ export function failureCausesNote(log, excluded = [], run, pageErrors = []) {
     // (2026-10-17). The root fix is to hand this function the whole log; this says so when a
     // caller cannot.
     const clipped = /^…\((\d+) earlier characters omitted\)/.exec(log);
-    const header = clipped !== null
-        ? `${total} failure${total === 1 ? '' : 's'} in the LAST part of this run’s log — its ` +
-            `first ${clipped[1]} characters were clipped, so a cause that failed earlier is ` +
-            `missing here. Fix every cause below${connections.length > 0 ? ' the app’s code can produce, and re-send the connection error once as it is' : ''}, ` +
-            `and read the whole run log before concluding:\n`
-        : `${total} failure${total === 1 ? '' : 's'} in this run, grouped by cause — fix every cause ` +
-            `below${connections.length > 0 ? ' the app’s code can produce, and re-send the connection error once as it is' : ' before the next deploy'}:\n`;
+    // The missing-header reading leads the list: four unrelated locators failing while every
+    // snapshot shows the page painted and un-navigated is ONE fact about the route, and the list
+    // below would otherwise read as four separate defects (xr-molecule-flash-m193 rewrote the
+    // navbar's auth logic and then the HTTP bond across two walks, ~6 minutes, for a page that
+    // never rendered `<Navbar />`).
+    const missingHeader = missingHeaderNote(log, pageErrors);
+    const header = (missingHeader === null ? '' : `${missingHeader}\n`) +
+        (clipped !== null
+            ? `${total} failure${total === 1 ? '' : 's'} in the LAST part of this run’s log — its ` +
+                `first ${clipped[1]} characters were clipped, so a cause that failed earlier is ` +
+                `missing here. Fix every cause below${connections.length > 0 ? ' the app’s code can produce, and re-send the connection error once as it is' : ''}, ` +
+                `and read the whole run log before concluding:\n`
+            : `${total} failure${total === 1 ? '' : 's'} in this run, grouped by cause — fix every cause ` +
+                `below${connections.length > 0 ? ' the app’s code can produce, and re-send the connection error once as it is' : ' before the next deploy'}:\n`);
     // The flaky sentence sits before the ignored one: the ignored sentence is the LAST thing the
     // note says, and callers assert on that ending.
     const tail = (rerun ? ` Re-run just these once they are fixed: \`${rerun}\`` : '') +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-ai-tools",
-  "version": "1.10.1",
+  "version": "1.10.2",
   "description": "Shared AI agent tools with backend abstraction for sandbox and local execution",
   "type": "module",
   "main": "dist/index.js",