@molecule/api-ai-tools 1.9.2 → 1.9.4

package/dist/utilities.js

@@ -5,7 +5,7 @@
  * @module
  */
 import { posix } from 'path';
-import { commandSegments, locatedCommandSegments } from './command-position.js';
+import { commandSegments, locatedCommandSegments, statementArgumentEnd, } from './command-position.js';
 import { classifyRunFailure } from './failure-kind.js';
 import { commandRunsNoTests } from './no-test-run.js';
 import { isDiagnosisRun, scopedRerunCommand, suiteCommandTarget, suiteRunInTheWay, withoutHeredocs, withSuiteConfig, } from './suite-overlap.js';
@@ -422,7 +422,18 @@ export function streamingBackgroundCommand(command) {
         out = out.slice(0, head.index);
         changes.push(`Dropped the trailing \`${head[0].trim()}\`: Playwright prints its pass/fail count last, and it would be cut.`);
     }
-    const lastStep = out.split(/&&|\|\||;/).at(-1) ?? '';
+    // The last step that RUNS something. A trailing group closer is punctuation, not a step: a
+    // brace group writes it after a `;` (`{ …; }`), so reading the split's last part literally
+    // made `}` the step and withheld every rewrite from a run inside a group.
+    const parts = out.split(/&&|\|\||;/);
+    let stepIndex = parts.length - 1;
+    while (stepIndex > 0 && /^[\s)}]*$/.test(parts[stepIndex] ?? ''))
+        stepIndex -= 1;
+    const rawLastStep = parts[stepIndex] ?? '';
+    // The step's own text, with the punctuation that closes the group it sits in taken off — the
+    // options are parsed and placed against this text, while the closer is kept in the command.
+    const lastStep = rawLastStep.replace(/[\s)}]+$/, '');
+    const stepStart = rawLastStep === '' ? out.length : Math.max(0, out.lastIndexOf(rawLastStep));
     // The last step runs Playwright — whether or not anything is piped from it. Keying this on
     // "nothing is piped out of the last step" withheld the reporter, the inline-failure switch and
     // `--retries=0` from exactly the runs whose output was filtered (xr-molecule-flash-m101
@@ -433,19 +444,27 @@ export function streamingBackgroundCommand(command) {
     /**
      * Add a word to the suite runner's own arguments; false when the runner could not be placed.
      *
-     * A pipe this rewrite could not drop still follows the runner (`| tee run.log`), so appending at
-     * the end of the whole command would make the word an operand of the filter — m102's dangling
-     * `--trace` flag, in the same shape. A suite inside a nested `sh -c '<command>'` string has no
-     * offsets in this command (they are positions in THAT string), so the command is left exactly as
-     * written and the caller reports no rewrite: appending at the end would hand the flag to the
-     * shell, outside the quotes.
+     * The word goes where the runner's own arguments end ({@link statementArgumentEnd}), never at
+     * the end of the command's text: a pipe this rewrite could not drop still follows the runner
+     * (`| tee run.log`), and a statement can end on a group closer (`( … )`, `{ …; }`) or a
+     * redirection (`… 2>&1`). Appending after the `)` of a subshell was a shell syntax error that
+     * killed the run at once (`sh: Syntax error: word unexpected`) and pushed the model off the
+     * platform's runner shape (xr-molecule-flash-m129 +34:29); appending after a pipe hands the
+     * word to the filter (m102's dangling `--trace` flag, in the same shape).
+     *
+     * A suite the parse could not place — one inside a nested `sh -c '<command>'` string, whose
+     * offsets are positions in THAT string, or a runner that is not the command's last step — is
+     * left exactly as written and the caller reports no rewrite. There is nowhere in this command
+     * the word belongs, and guessing at the text is what produced both failures above.
      */
     const addToRun = (flag) => {
         const pipeline = lastSuitePipeline(out);
         const runner = pipeline ? pipeline.located[pipeline.at] : undefined;
-        if (runner && runner.end === null)
+        if (!runner)
+            return false;
+        const at = statementArgumentEnd(out, runner.start, runner.end);
+        if (at === null)
             return false;
-        const at = runner?.end ?? out.trimEnd().length;
         out = `${out.slice(0, at)} ${flag}${out.slice(at)}`;
         return true;
     };
@@ -479,12 +498,15 @@ export function streamingBackgroundCommand(command) {
                 return 'list';
             })
                 .filter((v) => v !== null);
-            // Only the last step is rewritten, and `lastStep` is a suffix of `out`.
+            // Only the last step is rewritten, and its offsets are the parse's own. The punctuation
+            // after the step (`; }`, or the `)` attached to it) is kept verbatim.
             out =
-                out.slice(0, out.length - lastStep.length) +
+                out.slice(0, stepStart) +
                     lastStep.slice(0, reporters.start) +
                     `--reporter${reporters.separator}${kept.join(',')}` +
-                    lastStep.slice(reporters.end);
+                    lastStep.slice(reporters.end) +
+                    rawLastStep.slice(lastStep.length) +
+                    out.slice(stepStart + rawLastStep.length);
             changes.push(
             // `list` was already there and a second printer sat beside it: that one is dropped. When
             // no `list` was named at all, the printer is SWITCHED to it (flash-m62's `line`).
@@ -679,6 +701,31 @@ function isOutputOnlyFilter(segment) {
  * @returns The located segments and the last suite stage's index among them, or null.
  */
 function lastSuitePipeline(command) {
+    const run = lastSuiteRun(command);
+    if (run === null)
+        return null;
+    for (let i = run.at + 1; i < run.located.length; i += 1) {
+        if ((run.located[i]?.between ?? '').trim() !== '|')
+            return null;
+    }
+    return run;
+}
+/**
+ * The command's last suite stage, and the parse's segments around it — whatever follows that
+ * statement.
+ *
+ * {@link lastSuitePipeline} refuses a suite that is not the command's last step, because the code
+ * the command exits with is then the following statement's. That is the right answer to "whose
+ * exit code is this", and the wrong one to "which stages filter this run's output": a
+ * `… --reporter=list 2>&1 | tail -5; echo done` still pipes its log through a tail, and the tail
+ * still throws away every failure line the run printed (xr-molecule-flash-m121 +09:14, where the
+ * platform's own hold handed that shape back and the first 95-second walk's log held only the
+ * tally).
+ *
+ * @param command - The shell command.
+ * @returns The located segments and the last suite stage's index among them, or null.
+ */
+function lastSuiteRun(command) {
     if (commandRunsNoTests(command))
         return null;
     const located = locatedSegments(command);
@@ -688,13 +735,7 @@ function lastSuitePipeline(command) {
         if (segment && SUITE_RUN_COMMANDS.some((re) => re.test(segment.text)))
             at = i;
     }
-    if (at < 0)
-        return null;
-    for (let i = at + 1; i < located.length; i += 1) {
-        if ((located[i]?.between ?? '').trim() !== '|')
-            return null;
-    }
-    return { located, at };
+    return at < 0 ? null : { located, at };
 }
 /**
  * Drop the output-only filters piped after the command's suite runner.
@@ -710,35 +751,55 @@ function lastSuitePipeline(command) {
  * caller that reports the run's exit code must then treat it as unknown
  * ({@link suiteRunPipedAfterRunner}).
  *
+ * A statement after the run's own pipeline (`; echo done`, `&& echo ok`) does not protect the
+ * filters before it: the filter is thrown away and the trailing statement is kept, so the log the
+ * run writes still holds every failure (xr-molecule-flash-m121 — a `| tail -5; echo done` kept its
+ * tail, and a 95-second walk's log held only the tally while the platform's own hold had handed
+ * that command back).
+ *
  * @param command - The shell command.
  * @returns The rewritten command and the stages dropped.
  */
 export function stripTrailingSuiteFilters(command) {
-    const pipeline = lastSuitePipeline(command);
-    if (pipeline === null)
+    const run = lastSuiteRun(command);
+    if (run === null)
         return { command, dropped: '' };
-    const { located, at } = pipeline;
-    let first = located.length;
-    for (let i = located.length - 1; i > at; i -= 1) {
+    const { located, at } = run;
+    // Where the suite's own pipeline ends: the first stage after the runner that is not joined to
+    // its predecessor by a single `|`. Everything from there on is another statement, kept as it is.
+    let end = at;
+    for (let i = at + 1; i < located.length; i += 1) {
+        if ((located[i]?.between ?? '').trim() !== '|')
+            break;
+        end = i;
+    }
+    let first = end + 1;
+    for (let i = end; i > at; i -= 1) {
         const stage = located[i];
         if (!stage || !isOutputOnlyFilter(stage.segment))
             break;
         first = i;
     }
-    if (first === located.length)
+    if (first === end + 1)
         return { command, dropped: '' };
     const previous = located[first - 1];
     const stage = located[first];
-    if (!previous || !stage)
+    const lastDropped = located[end];
+    if (!previous || !stage || !lastDropped)
         return { command, dropped: '' };
     // A stage inside a nested `sh -c` string has no offsets in this command: nothing can be cut.
-    if (previous.end === null || stage.start === null)
+    if (previous.end === null || stage.start === null || lastDropped.end === null)
         return { command, dropped: '' };
     const pipe = stage.between.indexOf('|');
     if (pipe < 0)
         return { command, dropped: '' };
     const cut = previous.end + pipe;
-    return { command: command.slice(0, cut).trimEnd(), dropped: command.slice(cut).trim() };
+    // The stages dropped are a middle slice when a statement follows, so the text after them is
+    // kept — `; echo done` still runs.
+    return {
+        command: `${command.slice(0, cut).trimEnd()}${command.slice(lastDropped.end)}`,
+        dropped: command.slice(cut, lastDropped.end).trim(),
+    };
 }
 /**
  * Where the suite runner's exit code comes from: the runner itself, or a stage piped after it.
@@ -1744,6 +1805,17 @@ const FAILURE_EVIDENCE_CHARS = 200;
  */
 function failureEvidence(body, message) {
     const carried = (line) => message !== null && message.includes(line);
+    // A strict-mode violation lists the elements it resolved to, and that list is the fix's own
+    // address: `1) <button class="… action-btn">` and `2) <button class="…">` name where each
+    // duplicate is written. They were dropped here (the first body line is the signature, and the
+    // only later `Error:` line this read for is absent), so xr-molecule-flash-m122's run read
+    // "resolved to 2 elements:" followed by nothing and fixed a duplicate on a page its failing
+    // test never visits. Kept whole — a locator list is what the executor has to match to a file.
+    if (message !== null && /resolved to \d+ elements?/i.test(message)) {
+        const elements = body.filter((line) => /^\d+\)\s/.test(line));
+        if (elements.length > 0)
+            return elements.slice(0, 2);
+    }
     const expected = body.find((l) => /^Expected\b/.test(l));
     const received = body.find((l) => /^Received\b/.test(l));
     if (expected !== undefined && received !== undefined)
@@ -2051,29 +2123,135 @@ function failureBlockTests(text) {
  * property of the run rather than of a page.
  */
 export const UNIVERSAL_CAUSE_FILES = 3;
+/**
+ * How many tests a connection-class cause must cover before the run is stopped even when they
+ * are all in one file — see {@link universalCause}.
+ */
+export const CONNECTION_CAUSE_TESTS = 3;
+/**
+ * The failures that mean the browser never reached the app: neither the page's code nor a
+ * selector can be the cause, and every remaining test can only repeat it.
+ */
+const CONNECTION_CAUSE = /\bpage\.goto\b[^\n]*\btimeout\b|\bnet::ERR_[A-Z0-9_]+\b|\bECONNREFUSED\b/i;
+/** A Playwright positional argument that names one test file (`e2e/auth.spec.ts:19:3`). */
+const SPEC_FILE_ARG = /\.(?:spec|test)\.[cm]?[jt]sx?(?::\d+(?::\d+)?)?$/;
+/**
+ * The `playwright test` flags that take the next word as their value when they are not written
+ * `--flag=value`. A flag NOT in this set is a switch (`--headed`, `--last-failed`), so the word
+ * after it is a positional filter and not a value.
+ */
+const PLAYWRIGHT_VALUE_FLAGS = new Set([
+    '-c',
+    '-g',
+    '-j',
+    '-x',
+    '--config',
+    '--global-timeout',
+    '--grep',
+    '--grep-invert',
+    '--max-failures',
+    '--output',
+    '--project',
+    '--repeat-each',
+    '--reporter',
+    '--retries',
+    '--shard',
+    '--timeout',
+    '--trace',
+    '--ui-host',
+    '--ui-port',
+    '--workers',
+]);
+/**
+ * How many test FILES a Playwright run's own command narrows it to, or null when it selects the
+ * whole suite (or its selection cannot be read).
+ *
+ * {@link universalCause}'s file threshold is written for a whole-suite run, which a narrowed run
+ * can never reach. xr-molecule-flash-m119 (+42:08) re-ran ONE spec file against a hand-started
+ * `vite preview` the browser could not reach, and every test in it failed `page.goto: Timeout` —
+ * but one file is below {@link UNIVERSAL_CAUSE_FILES}, so the wait sat out its entire 280 s
+ * budget on a run that had already measured all it could.
+ *
+ * The command is read through {@link commandSegments}, so a `playwright test` named as an
+ * argument is not a run. A {@link PLAYWRIGHT_VALUE_FLAGS} flag written without `=` takes the next
+ * word as its value, so a `--config app/e2e-suite.config.ts` is never counted as a spec file; a
+ * directory or a bare substring filter names files the command does not list, which answers null
+ * (the whole-suite threshold) rather than a count of the wrong files.
+ *
+ * @param command - The run's command.
+ * @returns The number of distinct test files it names, or null when it names none (the whole
+ *   suite) or the selection cannot be told.
+ */
+export function specFilesSelected(command) {
+    for (const segment of commandSegments(command)) {
+        if (!/^playwright\s+test\b/.test(segment.text))
+            continue;
+        const files = new Set();
+        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;
+            }
+            if (SPEC_FILE_ARG.test(token)) {
+                files.add(token.replace(/:\d+(?::\d+)?$/, ''));
+                continue;
+            }
+            // A directory (`e2e/`), a glob, or a bare substring filter (`npx playwright test login`):
+            // the command does not name the files it selects, so there is no count to take.
+            return null;
+        }
+        return files.size > 0 ? files.size : null;
+    }
+    return null;
+}
 /**
  * Whether a repeating cause is failing the whole run — the one case where stopping it is the
  * right call.
  *
- * The test is: the cause accounts for every failure the log names, it has hit
- * {@link UNIVERSAL_CAUSE_FILES} spec files or more, and nothing has passed since its first
- * failure. An app that is not up, a 5xx on every request, or a selector that is missing on every
- * page all look like that, and every remaining test will fail the same way — so the run's
- * remaining minutes measure nothing. Anything less is NOT this: a cause that stops at one file,
- * or that leaves other tests passing, or that shares the run with failures of another shape,
- * leaves the run with something to say, and the run is the only thing that will say it. X1
- * flash-m83 (2026-10-16) stopped eight local runs at their first repeating cause over 14.5
- * minutes and never finished one; three of its deploys each fixed a single cause that a finished
- * run would have listed alongside the others.
+ * The test is: the cause accounts for every failure the log names, it has hit the spec-file
+ * threshold, and nothing has passed since its first failure. The threshold is
+ * {@link UNIVERSAL_CAUSE_FILES} for a whole-suite run but the number of files the command
+ * SELECTED for a narrowed one ({@link specFilesSelected}): a one-file run can never span three,
+ * and xr-molecule-flash-m119 (+42:08) waited out its whole budget on exactly that shape. An app
+ * that is not up, a 5xx on every request, or a selector that is missing on every page all look
+ * like that, and every remaining test will fail the same way — so the run's remaining minutes
+ * measure nothing. A CONNECTION-class cause ({@link CONNECTION_CAUSE}) needs no file span at all:
+ * three tests that could not reach the app, with nothing passing since, is the app-unreachable
+ * case however few files the run walks.
+ *
+ * Anything less is NOT this: a cause that stops at one file of a multi-file run, or that leaves
+ * other tests passing, or that shares the run with failures of another shape, leaves the run with
+ * something to say, and the run is the only thing that will say it. X1 flash-m83 (2026-10-16)
+ * stopped eight local runs at their first repeating cause over 14.5 minutes and never finished
+ * one; three of its deploys each fixed a single cause that a finished run would have listed
+ * alongside the others.
  *
  * @param log - The log so far.
  * @param found - The repeating cause {@link repeatingFailure} found in it.
+ * @param command - How the run was started, when the caller knows it: its spec-file selection
+ *   scales the file threshold ({@link specFilesSelected}).
  * @returns The cause's count and files, or null when the run is not failing whole.
  */
-export function universalCause(log, found) {
+export function universalCause(log, found, command) {
     const text = log.replace(ANSI_SGR, '');
     const files = [...new Set(found.tests.map((t) => specFile(t.where)).filter(Boolean))];
-    if (files.length < UNIVERSAL_CAUSE_FILES)
+    // The threshold is what THIS run selects, not the suite's total: a run narrowed to one file
+    // 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);
+    // The app never answered: three tests of that with nothing passing since is the whole of what
+    // a whole-suite run would have said, whatever the file count (xr-molecule-flash-m119).
+    const unreachable = found.message !== null &&
+        CONNECTION_CAUSE.test(found.message) &&
+        found.count >= CONNECTION_CAUSE_TESTS;
+    if (!unreachable && files.length < threshold)
         return null;
     // Every failure the log names has to be this cause: another cause anywhere in the run means
     // the run still has something to say, and stopping it throws that away.
@@ -2094,8 +2272,10 @@ export function universalCause(log, found) {
  *
  * Both halves are load-bearing, each of them learned from a run that lost minutes to the other.
  *
- * - **Failing the WHOLE run** is {@link universalCause}: every failure the log names, across
- *   {@link UNIVERSAL_CAUSE_FILES} spec files or more, with nothing passing since the first — the
+ * - **Failing the WHOLE run** is {@link universalCause}: every failure the log names, across the
+ *   spec-file threshold — {@link UNIVERSAL_CAUSE_FILES}, or the files a narrowed run's own
+ *   command selects, or {@link CONNECTION_CAUSE_TESTS} tests of an app that never answered — with
+ *   nothing passing since the first. That is the
  *   dont-stop-runs rule. X1 flash-m83 (2026-10-16) stopped eight local runs at their first
  *   repeating cause in 14.5 minutes and never finished one, and a run that still has other causes
  *   left to name is the only thing that will name them.
@@ -2236,7 +2416,7 @@ function flakyTestsDeclared(text) {
  * @returns The causes to fix, the distinct tests dropped as excluded, and the distinct tests the
  *   runner counted as flaky (a retried pass is not a cause to fix).
  */
-function groupFailures(log, excluded) {
+function groupFailures(log, excluded, pageErrors = []) {
     const text = log.replace(ANSI_SGR, '');
     const flakyTests = flakyTestsDeclared(text);
     const flaky = new Set(flakyTests.map(testKey));
@@ -2272,9 +2452,21 @@ function groupFailures(log, excluded) {
             });
     }
     const causes = [];
+    // The page's own words for a test, keyed the way both sides spell the location: the log's
+    // `file:line` and the artifact's `file:line` are the same string from one run.
+    const showedBy = new Map();
+    for (const entry of pageErrors)
+        if (entry.items.length > 0)
+            showedBy.set(entry.where, entry.items);
     for (const [message, group] of byMessage) {
         const tests = distinctTests(group.tests);
-        if (tests.length > 0)
+        if (tests.length > 0) {
+            // The first test of the cause that has page errors speaks for it: tests grouped under one
+            // error were failing the same way, and every one of m122's eight snapshots carried the same
+            // two blank-field alerts.
+            const showed = tests
+                .map((t) => showedBy.get(t.where))
+                .find((items) => items !== undefined);
             causes.push({
                 message,
                 seconds: null,
@@ -2284,7 +2476,9 @@ function groupFailures(log, excluded) {
                 // no layer of its own is read as an assertion (unknown is never `connection`).
                 kind: group.kind,
                 ...(group.budgetMs === null ? {} : { budgetMs: group.budgetMs }),
+                ...(showed === undefined ? {} : { pageShowed: [...showed] }),
             });
+        }
     }
     // The failures with no body of their own — a `list` log with no error blocks in it, from a run
     // not started in the background — are grouped by how long they took: a band is opened by its
@@ -2329,6 +2523,20 @@ function groupFailures(log, excluded) {
  * xr-molecule-flash-m113 (+20:34) got ten of these and a list that called them ten causes.
  */
 const NO_BASE_URL_ERROR = /Cannot navigate to invalid URL/i;
+/** The browser's own `net::ERR_*`, as Playwright prints it for a document that never loaded. */
+const NETWORK_ERROR_TEXT = /\bnet::ERR_[A-Z0-9_]+\b/;
+/**
+ * Whether every cause this run grouped is a `page.goto` that ran out of time.
+ *
+ * @param causes - The run's grouped causes.
+ * @returns True when the run measured no page at all.
+ */
+function everyCauseIsNavigationTimeout(causes) {
+    return (causes.length > 0 &&
+        causes.every((cause) => cause.message !== null &&
+            (/\bpage\.goto\b/.test(cause.message) || /navigating to/.test(cause.message)) &&
+            /timeout|timed out/i.test(cause.message)));
+}
 /**
  * The one-line note for a run whose EVERY failure is {@link NO_BASE_URL_ERROR}: a configuration
  * failure, not a result about the app.
@@ -2390,8 +2598,8 @@ function noBaseUrlConfigNote(causes, run, excluded) {
  *   "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) {
-    const { causes, ignored, flaky } = groupFailures(log, excluded);
+export function failureCausesNote(log, excluded = [], run, pageErrors = []) {
+    const { causes, ignored, flaky } = groupFailures(log, excluded, pageErrors);
     const total = causes.reduce((n, c) => n + c.tests.length, 0);
     if (total < 2)
         return null;
@@ -2406,6 +2614,23 @@ export function failureCausesNote(log, excluded = [], run) {
     // cannot report them again.
     const locations = [...new Set(causes.flatMap((c) => c.tests.map((t) => t.where)).filter(Boolean))];
     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
+    // `net::ERR_CONTENT_DECODING_FAILED`. The cause list is the wrong shape here — there is one
+    // cause and it is the server — so the note leads with the browser's own line, not a fix round.
+    const networkError = NETWORK_ERROR_TEXT.exec(log)?.[0];
+    if (networkError !== undefined && everyCauseIsNavigationTimeout(causes)) {
+        return (`${total} failure${total === 1 ? '' : 's'} in this run, and every one is a \`page.goto\` ` +
+            `that never loaded while the browser reported \`${networkError}\` — the document request ` +
+            `itself failed, so none of these is the app’s code or a selector. Fix the server first` +
+            (networkError === 'net::ERR_CONTENT_DECODING_FAILED'
+                ? ': a body whose gzip `content-encoding` no longer matches its bytes does this, and a ' +
+                    '`vite preview` over a build must be started with ' +
+                    '`MOL_E2E_PREVIEW_PLUGIN=0 npx vite preview --port 4173 --strictPort`'
+                : ' (what the run hit, and why it refused the connection)') +
+            (rerun ? `. Then send exactly this: \`${rerun}\`` : '') +
+            (locations.length > 0 ? `. Failing tests: ${locations.join(', ')}.` : ''));
+    }
     const ignoredTitles = [...new Set(ignored.map((t) => t.title || t.where).filter(Boolean))];
     const flakyTitles = [...new Set(flaky.map((t) => t.where || t.title).filter(Boolean))];
     // A cause that never reached the app is not a cause the app's code can fix: the transport
@@ -2421,8 +2646,22 @@ export function failureCausesNote(log, excluded = [], run) {
             "if the failure repeats, read the app's own log (`read_logs`) — a connection error is never a " +
             'handler shape, a header or CORS.');
     }
-    const header = `${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`;
+    // A text that is the TAIL of a longer log says so in its first line (`…(N earlier characters
+    // omitted)`, the shape `background-tasks` writes when a log is capped): what it holds is not
+    // the run's list of failures, only the part that survived the cut. Saying "N failures in this
+    // run" over it reads as complete, and did: xr-molecule-flash-m123's collected 42 KB diagnosis
+    // log was clipped to its last 8 KB, and this note grouped 2 of the run's 14 failures under
+    // "fix every cause below" while the 11 that shared the run's one real cause were gone
+    // (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 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}\`` : '') +
@@ -2479,10 +2718,21 @@ function failureCauseLine(cause, index) {
     // twice; the rest are the values the normalised signature replaced with `<n>`.
     const body = cause.evidence.filter((line) => cause.message === null || !cause.message.includes(line));
     const shortened = body.map((line) => line.length > FAILURE_EVIDENCE_CHARS ? `${line.slice(0, FAILURE_EVIDENCE_CHARS - 1)}…` : line);
+    // The page's own words at the failure (xr-molecule-flash-m122 +23:39): the error line names the
+    // symptom, and these name what the app was saying while it happened. The parenthetical is said
+    // only for the shape the items themselves show — validation copy on a form — where "submitted
+    // before its values loaded" is the reading, and never for arbitrary page text.
+    const showed = cause.pageShowed?.length
+        ? `\n     the page showed: ${cause.pageShowed.map((t) => `\`${t}\``).join(', ')}` +
+            (cause.pageShowed.some((t) => /\b(?:blank|required|invalid|must be)\b/i.test(t))
+                ? ' (the action ran before the form’s values had loaded)'
+                : '')
+        : '';
     return (`  ${index + 1}. ${cause.kind === 'connection' ? 'CONNECTION error, not the app’s — ' : ''}${signature} — ` +
         `${cause.tests.length} test${cause.tests.length === 1 ? '' : 's'} ` +
         `in ${files} file${files === 1 ? '' : 's'}: ${tests.join(', ')}${more}` +
-        (shortened.length ? `\n     ${shortened.join(' · ')}` : ''));
+        (shortened.length ? `\n     ${shortened.join(' · ')}` : '') +
+        showed);
 }
 /**
  * The sentence for the causes a recap could not fit: exactly which `file:line` each one was
@@ -2538,11 +2788,11 @@ function omittedCausesRecap(omitted, run, excluded) {
  * is not a Playwright run this can narrow.
  *
  * The `locations` are the paths the run's own log printed, which are relative to the directory
- * that run started in, so a re-run has to resolve them there: the command names that directory
- * unless it already changes into one of its own, because the executor's next command starts
- * wherever it starts. The returned command is for AFTER the run ends — it is a second run against
- * the same app and database, and that is exactly what is refused while the run walks
- * ({@link suiteRunInTheWay}).
+ * that run started in, so the composer resolves them there ({@link scopedRerunCommand}): the
+ * command names that directory unless it already changes into one of its own, because the
+ * executor's next command starts wherever it starts. The returned command is for AFTER the run
+ * ends — it is a second run against the same app and database, and that is exactly what is
+ * refused while the run walks ({@link suiteRunInTheWay}).
  *
  * @param run - The run in flight: the command it was started with, as it was run, the directory
  *   that command ran in, and the config it loaded when the caller knows it.
@@ -2554,7 +2804,10 @@ function omittedCausesRecap(omitted, run, excluded) {
 export function rerunOfRunningSuite(run, locations, excluded = []) {
     if (locations.length === 0)
         return null;
-    const scoped = scopedRerunCommand(run.command, locations, excluded, run.config);
+    // The run's own directory is the base a relative failure location resolves against: the
+    // reporter prints it from where the runner started, and Playwright matches file arguments
+    // against absolute paths (xr-molecule-flash-m118 +16:34, m124 +18:38).
+    const scoped = scopedRerunCommand(run.command, locations, excluded, run.config, run.cwd);
     if (scoped === run.command)
         return null;
     if (!run.cwd || commandSegments(withoutHeredocs(run.command)).some((s) => s.program === 'cd'))
@@ -2592,8 +2845,10 @@ export function rerunOfRunningSuite(run, locations, excluded = []) {
  * @param found - What {@link repeatingFailure} found.
  * @param o - The run's facts: its `taskId`, its `log` path, `stop` — the shell command that
  *   stops it, printed only for an {@link earlyReturnCause} — `universal`, what
- *   {@link universalCause} found (absent means the run is not failing whole), and `run`, how the
- *   run was started ({@link rerunOfRunningSuite}) when the caller knows it.
+ *   {@link universalCause} found (absent means the run is not failing whole), `run`, how the
+ *   run was started ({@link rerunOfRunningSuite}) when the caller knows it, and
+ *   `editsInvalidateRun`, true when the run measures the sandbox's own app (a local run, where an
+ *   edit now changes what the suite is testing and its result stops counting).
  * @returns The note.
  */
 export function repeatingFailureNote(found, o) {
@@ -2656,8 +2911,11 @@ export function repeatingFailureNote(found, o) {
         const files = stop.files.map(shortFile);
         const shown = files.slice(0, 4).join(', ');
         const moreFiles = files.length > 4 ? `, … and ${files.length - 4} more` : '';
+        const span = files.length === 0
+            ? ''
+            : ` — across ${files.length} file${files.length === 1 ? '' : 's'} (${shown}${moreFiles})`;
         return (`Every test this run has walked so far has failed the same way — all ${found.count} of ` +
-            `them, ${signature} — across ${files.length} files (${shown}${moreFiles}), with nothing ` +
+            `them, ${signature}${span}, with nothing ` +
             `passing since the first:\n${rows}${more}\n` +
             `Every remaining test will fail the same way too, so walking the rest of this run only ` +
             `repeats this one cause. Stop it and fix that cause first: \`exec_command: ${o.stop}\`, ` +
@@ -2674,7 +2932,9 @@ export function repeatingFailureNote(found, o) {
     if (isCause)
         return (`${found.count} different tests in this run have already failed the same way — ${signature} — ` +
             `so one cause is repeating:\n${rows}${more}\n` +
-            `Start fixing it now, while the run keeps walking. Stop it only if every test it walks ` +
+            (o.editsInvalidateRun
+                ? `Work out the fix now: apply it when the run ends, not while it walks. Stop it only if every test it walks `
+                : `Start fixing it now, while the run keeps walking. Stop it only if every test it walks `) +
             `fails this same way (the app unreachable, a 5xx on every request, the same selector timing ` +
             `out on every test of every file so far).${reproduce} ${keepGoing}${thenRun}`);
     return (`${found.count} different tests in this run each failed after ~${found.seconds}s — the same ` +
@@ -2682,7 +2942,10 @@ export function repeatingFailureNote(found, o) {
         `config sets a timeout spends that timeout on every failure that waits for anything, so ` +
         `different missing elements land on the same number. Read these failures before fixing one ` +
         `of them:\n${rows}${more}\n` +
-        `Start on them now, while the run keeps walking.${reproduce} ${keepGoing}${thenRun}`);
+        (o.editsInvalidateRun
+            ? `Work out the fixes now: apply them when the run ends, not while it walks.`
+            : `Start on them now, while the run keeps walking.`) +
+        `${reproduce} ${keepGoing}${thenRun}`);
 }
 /**
  * Attempt a whitespace-tolerant replacement when an exact `old_string` match

package/package.json

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