@molecule/api-ai-tools 1.5.19 → 1.6.0

package/dist/utilities.js

@@ -5,6 +5,8 @@
  * @module
  */
 import { posix } from 'path';
+import { commandSegments } from './command-position.js';
+import { commandRunsNoTests } from './no-test-run.js';
 /**
  * Shell-safe quoting using single quotes. Unlike JSON.stringify (double quotes),
  * single-quoted strings prevent command substitution ($(), backticks) and variable expansion.
@@ -287,8 +289,43 @@ export function outputRedirectTarget(command) {
 }
 /** A trailing `| tail -N` / `| tail -n N` (stderr redirects before it stay). */
 const TRAILING_TAIL = /\s*\|\s*tail(?:\s+-n)?\s+[-+]?\d+\s*$/;
-/** `--reporter=line` / `--reporter line`, the one reporter the platform cannot read back. */
-const LINE_REPORTER_FLAG = /--reporter([= ])line\b/;
+/** `--reporter line` / `--reporter=line` / `--reporter="list,line"`, with its value. */
+const REPORTER_FLAG = /--reporter(=|\s+)(?:"([^"]*)"|'([^']*)'|(\S+))/g;
+/**
+ * The reporters a step's LAST `--reporter` names (`--reporter=list,line` → `['list', 'line']`).
+ *
+ * Playwright takes the last `--reporter`, so an earlier one is not what runs.
+ *
+ * @param step - The command's last step.
+ * @returns The flag's span and its reporters, or null when the step names none.
+ */
+function lastReporterFlag(step) {
+    REPORTER_FLAG.lastIndex = 0;
+    let last = null;
+    for (let m = REPORTER_FLAG.exec(step); m !== null; m = REPORTER_FLAG.exec(step))
+        last = m;
+    if (!last)
+        return null;
+    const value = last[2] ?? last[3] ?? last[4] ?? '';
+    return {
+        start: last.index,
+        end: last.index + last[0].length,
+        separator: last[1] ?? '=',
+        values: value
+            .split(',')
+            .map((v) => v.trim())
+            .filter(Boolean),
+    };
+}
+/**
+ * The reporters that print one line (or one mark) per test into the log, `list` among them.
+ *
+ * `list` is the only one of these the platform can read back — `suite-fail-fast.ts`'s fail-fast
+ * note and the Tests bar both parse its `  ✓/✘  <n> … (…)` lines — so it is the one a background
+ * run is put on. The rest are here because they print each failure TOO: a log with two of them
+ * carries every result twice.
+ */
+const PRINTING_REPORTERS = new Set(['list', 'line', 'dot', 'basic', 'spec']);
 /**
  * Rewrite a command about to run in the background so its log grows while it
  * runs. Two shapes left the log empty until exit, and an empty log is what
@@ -301,26 +338,32 @@ const LINE_REPORTER_FLAG = /--reporter([= ])line\b/;
  *   often `html`, which prints nothing per test. `--reporter=list` is added
  *   when the playwright run is the command's last step and nothing is piped or
  *   redirected from it: it writes each result as it finishes, and it is the
- *   shape the platform reads a background suite back in (`suite-fail-fast.ts`'s
- *   fail-fast note and the Tests bar both parse `list` lines). A run that names
- *   `--reporter=line` is switched to `list` for the same reason — `line` writes
- *   `[n/N] <title>` with no ✓/✘ mark and no duration, so on X1 flash-m62 an
- *   8.3-minute walk of one suite could never trip the fail-fast note.
- *
- * A run being ITERATED on (capped, narrowed, or by file) gets `list,line` instead
- * of `list` alone. `list` holds every failure's error for the summary at the end,
- * so mid-run its log says only how long each failure took; `line` writes the body
- * as the failure happens, and a look at a running suite (`wait_for_task`'s
- * repeating-cause note, `suite-fail-fast.ts`) can then name the repeating cause by
- * its error message. X1 flash-m76 walked 15 tests for 4.0 minutes, every one a
- * `TimeoutError: page.waitForURL` from one missing `navigate('/')`.
- *
- * Only the command's last step is touched, and only its reporter.
+ *   shape the platform reads a background suite back in.
+ *
+ * The run ends up with exactly ONE reporter that prints each failure — `list`. A run that names
+ * any other printing reporter has it REPLACED, never joined: two of them write every test result
+ * into the log twice, which on X1 flash-m83 (2026-10-16) made a `--reporter=list,line` run (its
+ * `line` added by this function one run earlier) report two distinct failures as "4 of this run's
+ * tests have already failed the same way", and the executor stopped a 139-test walk at test 21
+ * with a single cause in hand. `line` alone is no use either: it writes `[n/N] <title>` with no
+ * ✓/✘ mark and no duration, so on X1 flash-m62 an 8.3-minute walk of one suite could never trip
+ * the fail-fast note. A reporter set that writes a machine format to a file (`json`, `html`,
+ * `junit`) is the
+ * executor's own and is left exactly as it is — so is any reporter this build does not know.
+ *
+ * Only the command's last step 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
+ * neither reporter nor `--retries=0` is added to it ({@link isPlaywrightRunCommand}).
  *
  * @param command - The command as the executor sent it.
  * @returns The command to run and one sentence per change made (empty when none).
  */
 export function streamingBackgroundCommand(command) {
+    // A command that runs no test is not a run to keep a growing log for: nothing about it is
+    // rewritten (flash-m79's `--list` was read as a whole-suite run end to end, and got a ~4 KB
+    // refusal to send itself again with `--max-failures=15`).
+    if (commandRunsNoTests(command))
+        return { command, changes: [] };
     const changes = [];
     let out = command;
     const tail = TRAILING_TAIL.exec(out);
@@ -332,12 +375,12 @@ export function streamingBackgroundCommand(command) {
     // A Playwright run behind `| head -N` loses its tally, which prints last (X1
     // flash-m32 counted ✓/✘ marks by hand); the full log comes back anyway.
     const head = /\s*\|\s*head(?:\s+-n)?\s+-?\d+\s*$/.exec(out);
-    if (head && /\bplaywright\s+test\b/.test(out)) {
+    if (head && isPlaywrightRunCommand(out)) {
         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) ?? '';
-    const finalPlaywrightRun = /\bplaywright\s+test\b/.test(lastStep) &&
+    const finalPlaywrightRun = isPlaywrightRunCommand(lastStep) &&
         // `2>&1` only joins stderr to the log; any other pipe or redirect sends the output elsewhere.
         !/[|>]/.test(lastStep.replace(/\d?>&\d/g, ''));
     // A diagnosis or a re-run (capped, last-failed, grepped, or named files) walks each failure
@@ -345,40 +388,54 @@ export function streamingBackgroundCommand(command) {
     // which had dropped the `--retries=0` it used one command earlier. The uncapped proof run
     // keeps the suite's retries.
     const iterating = /--max-failures\b|--last-failed\b|(?:^|\s)(?:-g|--grep)\b|\S+\.(?:spec|test)\.[cm]?[jt]sx?(?::\d+)?\b/.test(lastStep);
-    // `list` is the shape the platform reads a background suite back in (the fail-fast note and
-    // the Tests bar both parse its `  ✓/✘  <n> … (…)` lines), and it prints each failure's error
-    // only in the summary at the END. A run being iterated on is the one whose failures are read
-    // mid-run and stopped early, and for that the log has to carry the error as it happens —
-    // `line` writes exactly that, so an iterating run gets both reporters and a proof run, which
-    // nothing stops early, keeps `list` alone rather than doubling its log.
-    const wanted = iterating ? 'list,line' : 'list';
-    if (finalPlaywrightRun && LINE_REPORTER_FLAG.test(lastStep)) {
-        // Only the last step is rewritten, and `lastStep` is a suffix of `out`.
-        out =
-            out.slice(0, out.length - lastStep.length) +
-                lastStep.replace(LINE_REPORTER_FLAG, `--reporter$1${wanted}`);
-        changes.push(`Switched \`--reporter=line\` to \`--reporter=${wanted}\`: it also writes each test result as it ` +
-            'finishes, and it is the shape the platform reads back from a background run.' +
-            (iterating
-                ? ' `line` stays alongside it so each failure writes its error to the log as it happens — that is what a mid-run look reads.'
-                : ''));
-    }
-    else if (finalPlaywrightRun && iterating && /--reporter([= ])list\b/.test(lastStep)) {
-        // Only the last step's reporter, the same rule as above.
-        out =
-            out.slice(0, out.length - lastStep.length) +
-                lastStep.replace(/--reporter([= ])list\b/, '--reporter$1list,line');
-        changes.push('Added `line` to your `--reporter=list`: `list` writes each test result as it finishes but ' +
-            'holds every failure’s error for the summary at the end, and `line` writes it as the failure ' +
-            'happens — which is what names a cause that repeats while this run is still going.');
+    // The last step's reporters: one printer, and it is `list`. Every branch below only ever moves
+    // the command TO that shape — a reporter set is never left with two printers in it.
+    const reporters = finalPlaywrightRun ? lastReporterFlag(lastStep) : null;
+    if (reporters) {
+        const printing = reporters.values.filter((v) => PRINTING_REPORTERS.has(v));
+        // Already exactly `list`: the shape, and nothing printing beside it. Left verbatim — the
+        // executor's own spelling of the command is not rewritten for nothing.
+        if (printing.length > 0 && !(printing.length === 1 && printing[0] === 'list')) {
+            // The printing reporters become ONE `list`, in the place of the first of them; every other
+            // reporter (a `json`/`html`/`junit` file the executor asked for, or one this build does not
+            // know) is left where it was.
+            let placed = false;
+            const kept = reporters.values
+                .map((v) => {
+                if (!PRINTING_REPORTERS.has(v))
+                    return v;
+                if (placed)
+                    return null;
+                placed = true;
+                return 'list';
+            })
+                .filter((v) => v !== null);
+            // Only the last step is rewritten, and `lastStep` is a suffix of `out`.
+            out =
+                out.slice(0, out.length - lastStep.length) +
+                    lastStep.slice(0, reporters.start) +
+                    `--reporter${reporters.separator}${kept.join(',')}` +
+                    lastStep.slice(reporters.end);
+            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`).
+            printing.includes('list')
+                ? `Dropped \`${printing
+                    .filter((v) => v !== 'list')
+                    .join(',')}\` from your \`--reporter=${reporters.values.join(',')}\`: ` +
+                    'two reporters that both print each failure write every test result into the log ' +
+                    'twice — the whole log doubled for nothing (X1 flash-m83) — so this run keeps ' +
+                    '`list` alone.'
+                : `Switched the test reporters to \`--reporter${reporters.separator}${kept.join(',')}\`: ` +
+                    '`list` writes each test result as it finishes and is the shape the platform reads ' +
+                    'back from a background run, and it is the only printing reporter — two of them ' +
+                    'write every result into the log twice (X1 flash-m83).');
+        }
     }
-    else if (finalPlaywrightRun && !/--reporter\b/.test(lastStep)) {
-        out = `${out.trimEnd()} --reporter=${wanted}`;
-        changes.push(`Added \`--reporter=${wanted}\` so each test result is written to the log as it finishes ` +
-            '(the config reporter may print nothing until the end).' +
-            (iterating
-                ? ' `line` writes each failure’s error as it happens, which is what a mid-run look reads.'
-                : ''));
+    else if (finalPlaywrightRun) {
+        out = `${out.trimEnd()} --reporter=list`;
+        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).');
     }
     if (finalPlaywrightRun && iterating && !/--retries\b/.test(lastStep)) {
         out = `${out.trimEnd()} --retries=0`;
@@ -392,24 +449,54 @@ export function streamingBackgroundCommand(command) {
  * of from a sandbox; `suiteRunKind` (molecule-dev `api/src/ai/suite-proof.ts`)
  * is the platform's fuller list of URL-testing runners, and the shapes here are
  * its shapes.
+ *
+ * Each is matched at the START of a pipeline segment's command-position text
+ * (`commandSegments`), so a runner named as an argument is not an invocation:
+ * `grep -n playwright e2e/README.md` reads a file and starts nothing.
  */
 const SUITE_RUN_COMMANDS = [
     // `playwright test`, not a bare `playwright` (`--version` is not a run).
-    /(?:^|[\s;&|(])(?:npx\s+(?:--no-install\s+)?)?(?:\S*\/)?playwright\s+test\b/,
+    /^playwright\s+test\b/,
     // Vitest, however it is invoked (`vitest`, `npx vitest run`).
-    /(?:^|[\s;&|(])(?:npx\s+(?:--no-install\s+)?)?(?:\S*\/)?vitest\b/,
+    /^vitest\b/,
     // `hurl --test …` or `hurl … x.hurl`.
-    /(?:^|[\s;&|(])(?:\S*\/)?hurl\s+[^|\n]*(?:--test|\.hurl)/,
+    /^hurl\s+[^|\n]*(?:--test|\.hurl)/,
 ];
 /**
  * Whether a command runs a whole test suite — a Playwright, Vitest or Hurl run
  * — rather than a build, an install or a one-off script.
  *
+ * A command that invokes a runner only to print is not one of these
+ * ({@link commandRunsNoTests}): `npx playwright test --list` prints the tests it would run and
+ * exits, and `npx playwright install`, `vitest list` and `hurl --help` start no test either.
+ *
  * @param command - The shell command.
  * @returns True when the command starts one of those runners.
  */
 export function isSuiteRunCommand(command) {
-    return SUITE_RUN_COMMANDS.some((re) => re.test(command));
+    if (commandRunsNoTests(command))
+        return false;
+    return commandSegments(command).some((segment) => SUITE_RUN_COMMANDS.some((re) => re.test(segment.text)));
+}
+/**
+ * Whether a command starts a Playwright run — a `playwright test` in command position, in a form
+ * that runs something.
+ *
+ * `npx playwright test --list` matched every `\bplaywright\s+test\b` test in the platform and was
+ * then treated as a run: held (flash-m79's config check), backgrounded for a run that outlasts
+ * the tool's ceiling, and rewritten with `--reporter`. A list takes two seconds, prints its lines
+ * and exits, so it is none of those; {@link commandRunsNoTests} is what decides.
+ *
+ * A `playwright test` named as an argument is not a run either (`head -30 run-tests.sh`,
+ * `grep -n "playwright test" e2e/README.md`): the command that runs is the reader.
+ *
+ * @param command - The shell command.
+ * @returns True when the command starts a Playwright run.
+ */
+export function isPlaywrightRunCommand(command) {
+    if (commandRunsNoTests(command))
+        return false;
+    return commandSegments(command).some((segment) => /^playwright\s+test\b/.test(segment.text));
 }
 /**
  * Start a background suite run at lower CPU and IO priority, so the sandbox it
@@ -714,31 +801,96 @@ export function sliceLines(content, window) {
         truncated: offset > 1 || offset - 1 + picked.length < totalLines,
     };
 }
-/** Max search results. */
+/**
+ * A file's text as the request counts it: the length of its JSON string.
+ *
+ * JSON escaping (`\n` → `\\n`, `"` → `\"`) costs characters, and the request
+ * side counts the SERIALIZED tool result. A window of 59,000 characters of
+ * source — 1,200 lines — arrives as ~60,200 characters of JSON, over the
+ * ceiling it was sized for, so a window is measured with this rather than by
+ * its raw text length.
+ *
+ * @param text - The text.
+ * @returns Its serialized length, without the surrounding quotes.
+ */
+export function serializedChars(text) {
+    return JSON.stringify(text).length - 2;
+}
+/**
+ * How many leading lines of a file fit inside a budget of SERIALIZED chars,
+ * the way `read_file` sizes a window (see {@link serializedChars}).
+ *
+ * @param content - The file's full text.
+ * @param chars - The budget in serialized chars.
+ * @returns The line count, at least one.
+ */
+export function linesWithinSerialized(content, chars) {
+    let used = 0;
+    let lines = 0;
+    for (const line of content.split('\n')) {
+        // +2: the newline between two lines escapes to `\n`. The last line of a
+        // window has no trailing newline, so this counts 2 chars it does not use —
+        // a window that errs small is the safe direction here.
+        used += serializedChars(line) + 2;
+        if (used > chars && lines > 0)
+            break;
+        lines++;
+    }
+    return Math.max(1, lines);
+}
 /**
  * Most files one batched `read_file` call returns. The cap exists so a survey
- * of a large tree cannot swallow the turn's context in one result; the tool
- * reports where it stopped so the model continues from there.
+ * of a large tree cannot swallow the turn's context in one result; every path
+ * past it is named in the result's `note` and listed with its own `error`, so
+ * the model continues from there.
  */
 export const MAX_BATCH_READ_FILES = 25;
 /**
- * Total content bytes one batched `read_file` call returns, across all files.
- * The per-file {@link MAX_READ_SIZE} still applies to each one.
+ * The most one `read_file` RESULT may carry, in chars of its JSON — every file
+ * the call returns, the envelope and the note included. That is how the request
+ * side counts a tool result, so it is how this tool counts one too
+ * ({@link serializedChars}).
+ *
+ * One tool result is ONE block in the request, and the request side caps a
+ * block: molecule-dev cuts any block over `MAX_TAIL_BLOCK_CHARS` (60,000) in
+ * place, keeping ~30 KB of each end. A batched read that crossed it lost its
+ * MIDDLE — the cut lands between two `"content"` values, so whole files fell
+ * out and the note in their place said only "N characters cut here" — while
+ * this tool's own note had promised each of those files that it "fits in one
+ * call, so it is not paged": X0 flash-m81 (2026-10-16) read ten e2e specs in
+ * one call (121,467 chars), lost the middle six, and bought them again in six
+ * further calls (52,908 chars).
+ *
+ * So the CALL gets the ceiling the request gives it. Whole files are returned
+ * up to it; the paths that did not fit are named in `note` and listed in
+ * `files` with their own `error`, the shape every other entry has. No file is
+ * ever cut, and no read result reaches the request-side cut. A test in
+ * molecule-dev's `context-fit` asserts the two ceilings still agree.
+ */
+export const MAX_READ_CALL_CHARS = 60_000;
+/**
+ * Room inside one read result for what is not file content: the `path`, the
+ * offset/line fields, and the note.
+ *
+ * A batch sizes each file against what the call has left
+ * ({@link MAX_READ_CALL_CHARS} less this), so the entry that does not fit is
+ * caught here rather than by the request-side cut.
  */
-export const MAX_BATCH_READ_BYTES = 200 * 1024;
+export const READ_RESULT_ENVELOPE_CHARS = 1_000;
 /**
  * The most one read_file call returns for ONE file when no window was asked
- * for, in chars. Larger files come back as their first window with a note
- * saying how to read the rest.
+ * for, in serialized chars: larger files come back as their first window, with
+ * a note saying how to read the rest.
  *
  * MAX_READ_SIZE (5 MB) is a bound on what the tool will open, not on what it
  * should hand a model: a single batched read that returned a 1.2 MB README
  * put the next three provider calls at 366k tokens (~330k of them fresh)
- * against a 120k-token context cap (X0 run x5, call 26). ~80 KB is ~20–25k
- * tokens — a fifth of that cap, and more than any one file read usually
- * needs.
+ * against a 120k-token context cap (X0 run x5, call 26). This is the call's
+ * own ceiling ({@link MAX_READ_CALL_CHARS}) less the room its envelope takes,
+ * so one read result — one file or twenty-five — fits inside what the request
+ * side carries without being cut.
  */
-export const MAX_READ_RETURN_CHARS = 80 * 1024;
+export const MAX_READ_RETURN_CHARS = MAX_READ_CALL_CHARS - READ_RESULT_ENVELOPE_CHARS;
 /**
  * A file this small is returned whole on a second window of it (paging it costs a call each).
  * The same bound as {@link MAX_READ_RETURN_CHARS}: the windowed-read note promises that a
@@ -792,6 +944,8 @@ export function looksLikeHtml(text) {
 export function htmlOutline(text, label = 'document') {
     if (!looksLikeHtml(text))
         return null;
+    // "0 KB" for anything under a kilobyte reads like a bug; say the real unit.
+    const size = (chars) => chars >= 1024 ? `${Math.round(chars / 1024)} KB` : `${chars} char${chars === 1 ? '' : 's'}`;
     const lines = text.split('\n');
     const out = [];
     let skipped = 0;
@@ -800,7 +954,7 @@ export function htmlOutline(text, label = 'document') {
     const flushSkipped = () => {
         if (skipped === 0)
             return;
-        out.push(`        … ${skipped} more line${skipped === 1 ? '' : 's'} (${Math.round(skippedChars / 1024)} KB) …`);
+        out.push(`        … ${skipped} more line${skipped === 1 ? '' : 's'} (${size(skippedChars)}) …`);
         skipped = 0;
         skippedChars = 0;
     };
@@ -824,9 +978,7 @@ export function htmlOutline(text, label = 'document') {
         }
     }
     flushSkipped();
-    // "0 KB" for anything under a kilobyte reads like a bug; say the real unit.
-    const size = text.length >= 1024 ? `${Math.round(text.length / 1024)} KB` : `${text.length} chars`;
-    const header = `OUTLINE of ${label} — ${size}, ${lines.length} lines. ` +
+    const header = `OUTLINE of ${label} — ${size(text.length)}, ${lines.length} lines. ` +
         `Its tags and the tags that open each section, one line each; tag bodies (CSS, JS, text) are not shown.` +
         (truncated ? ` (Outline capped at ${MAX_HTML_OUTLINE_LINES} lines.)` : '');
     return `${header}\n\n${out.join('\n')}`;
@@ -1039,7 +1191,10 @@ export function runningCauseCommand(log, own) {
     const read = `cat ${log}${own ? ` ${shellQuote(own)}` : ''} 2>/dev/null`;
     return `${read} | tail -c ${REPEATING_CAUSE_TAIL_BYTES}`;
 }
-/** Failures that must share one signature before a running suite's repeating cause is named. */
+/**
+ * DISTINCT tests that must share one signature before a running suite's repeating cause is named.
+ * A test the log prints twice, or a test that failed twice, is still one test.
+ */
 export const REPEATING_FAILURE_MIN = 3;
 /** ANSI SGR sequences — the `line` reporter writes cursor moves even into a file. */
 // eslint-disable-next-line no-control-regex -- an escape sequence IS a control character
@@ -1136,28 +1291,63 @@ function largestGroup(groups) {
     }
     return best;
 }
+/**
+ * One test's identity in a log: where it sits and what it is called.
+ *
+ * A test printed twice by two reporters, or failed twice by a retry, is the same test — the
+ * identity is what it is called and where it lives, never which line of the log it came from.
+ *
+ * @param t - A failed test.
+ * @returns The key two prints of one test share.
+ */
+function testKey(t) {
+    return `${t.where}|${t.title}`;
+}
+/**
+ * The same tests with each one kept once, in first-seen order.
+ *
+ * @param tests - Failed tests, as the log printed them (possibly more than once each).
+ * @returns The distinct tests.
+ */
+function distinctTests(tests) {
+    const seen = new Set();
+    return tests.filter((t) => {
+        const key = testKey(t);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
 /**
  * The cause repeating among a running suite's failures, or null.
  *
  * Playwright's `list` reporter prints one line per test as it finishes — its mark, its title
  * path and how long it ran — and defers each failure's error to the summary at the end, so
- * mid-run the only signature those lines carry is the duration. A `line` reporter prints the
- * failure bodies as they happen, and there the repeated error message itself is the signature,
- * which is stronger (it needs no assumption about how long a failure should take), so the
- * message is looked for first.
+ * mid-run the only signature those lines carry is the duration. Where the log carries the
+ * failure bodies (a `line` reporter's output, or a finished run's summary) the repeated error
+ * message itself is the signature, which is stronger (it needs no assumption about how long a
+ * failure should take), so the message is looked for first.
  *
  * Either way the point is the same: a suite whose failures repeat one cause spends its whole
  * runtime proving that one cause, and the executor watching it can be told so at the third
  * failure instead of at the last. X1 flash-m76 walked 15 tests in 4.0 minutes where 15.6 s
  * each was the test timeout and one missing `navigate('/')` was the cause of all of them.
  *
+ * The quorum is of DISTINCT tests — {@link REPEATING_FAILURE_MIN} of them — because a log that
+ * prints each failure twice (a second reporter, a retry) had X1 flash-m83 told that four of its
+ * tests had failed the same way when two had, so the executor stopped a 139-test walk at test 21
+ * with one cause in hand (2026-10-16).
+ *
  * @param log - The log so far.
  * @returns The repeating cause, or null when no signature has {@link REPEATING_FAILURE_MIN}
- *   failures behind it.
+ *   distinct tests behind it.
  */
 export function repeatingFailure(log) {
     const text = log.replace(ANSI_SGR, '');
-    // The failure BODIES first: a message repeating verbatim names the cause itself.
+    // The failure BODIES first: a message repeating verbatim names the cause itself. Grouped by
+    // DISTINCT test, so the largest group is the cause the most tests share — not the one whose
+    // failures happen to have been printed the most times.
     const byMessage = new Map();
     for (const block of failureBlocks(text)) {
         const message = failureMessage(block);
@@ -1171,7 +1361,10 @@ export function repeatingFailure(log) {
         else
             byMessage.set(message, [{ where, title, seconds: null }]);
     }
-    const messageGroup = largestGroup(byMessage);
+    const distinctByMessage = new Map();
+    for (const [message, members] of byMessage)
+        distinctByMessage.set(message, distinctTests(members));
+    const messageGroup = largestGroup(distinctByMessage);
     if (messageGroup && messageGroup.members.length >= REPEATING_FAILURE_MIN)
         return {
             count: messageGroup.members.length,
@@ -1182,7 +1375,7 @@ export function repeatingFailure(log) {
     // Otherwise the durations: the largest set of failures that took the same time to within the
     // band. A test that runs to its timeout prints slightly different durations on each attempt
     // (15.6 s, 15.1 s, 15.0 s), so the band is 0.5 s or 5% of the duration, whichever is larger.
-    const tests = failedTests(text);
+    const tests = distinctTests(failedTests(text));
     const withSeconds = tests.filter((t) => t.seconds !== null);
     let best = [];
     for (const t of withSeconds) {
@@ -1198,27 +1391,222 @@ export function repeatingFailure(log) {
 }
 /** How many of a repeating cause's failures the note lists before it says "and N more". */
 export const REPEATING_FAILURE_LISTED = 5;
+/** How many causes a finished run's summary lists before it says "and N more". */
+export const FAILURE_CAUSES_LISTED = 5;
+/** How many of one cause's tests that summary names before it says "and N more". */
+export const FAILURE_CAUSE_TESTS_LISTED = 6;
 /**
  * The shortest unambiguous tail of a logged path (`…/specs/e2e/articles.spec.ts:32` →
  * `e2e/articles.spec.ts:32`).
  *
  * @param where - The location the log wrote.
- * @returns The last two path segments.
+ * @returns The last two path segments, with the line number.
  */
 function shortWhere(where) {
     const parts = where.split('/');
     return parts.slice(-2).join('/');
 }
 /**
- * The sentence that names a cause repeating among a running suite's failures, and the command
- * that stops the run so the cause can be fixed first.
+ * The shortest unambiguous tail of a logged path's FILE (`…/specs/e2e/articles.spec.ts` →
+ * `e2e/articles.spec.ts`).
+ *
+ * @param file - A path as {@link specFile} returns it.
+ * @returns The last two path segments.
+ */
+function shortFile(file) {
+    return file.split('/').slice(-2).join('/');
+}
+/**
+ * The spec file a logged location names (`…/e2e/articles.spec.ts:32` → `…/e2e/articles.spec.ts`).
+ *
+ * @param where - A location from {@link FailedTest.where}.
+ * @returns The path without its line number.
+ */
+function specFile(where) {
+    return where.replace(/:\d+$/, '');
+}
+/**
+ * The mark of every test result a log names, in the order it printed them (`✘` failed, `✓`
+ * passed).
+ *
+ * A `line`-only log writes none: `[n/N] <title>` carries no mark. An empty list therefore means
+ * the log cannot say whether anything passed, not that nothing did.
+ *
+ * @param text - The log (ANSI already stripped).
+ * @returns The marks.
+ */
+function resultMarks(text) {
+    const out = [];
+    for (const line of text.split('\n')) {
+        const m = LIST_RESULT_LINE.exec(line);
+        if (m)
+            out.push(m[1]);
+    }
+    return out;
+}
+/**
+ * Every test the log's numbered failure blocks name, in the order it names them.
+ *
+ * @param text - The log (ANSI already stripped).
+ * @returns The failed tests, with the location and title their header carries.
+ */
+function failureBlockTests(text) {
+    return failureBlocks(text).map((block) => {
+        const m = FAILURE_BLOCK_HEADER.exec(block.split('\n')[0] ?? '');
+        const { where, title } = splitTitlePath(m?.[1] ?? '');
+        return { where, title, seconds: null };
+    });
+}
+/**
+ * Distinct spec FILES a repeating cause must span — with every failure sharing it and nothing
+ * passing since — before a run is called broken for the whole suite.
+ *
+ * One file's failures can be that file's own setup, so a cause confined to one file is never
+ * this. Across {@link UNIVERSAL_CAUSE_FILES} files, on the other hand, whatever it is is a
+ * property of the run rather than of a page.
+ */
+export const UNIVERSAL_CAUSE_FILES = 3;
+/**
+ * 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.
+ *
+ * @param log - The log so far.
+ * @param found - The repeating cause {@link repeatingFailure} found in it.
+ * @returns The cause's count and files, or null when the run is not failing whole.
+ */
+export function universalCause(log, found) {
+    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)
+        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.
+    const named = Math.max(distinctTests(failedTests(text)).length, distinctTests(failureBlockTests(text)).length);
+    if (found.count < named)
+        return null;
+    // And nothing may have passed since its first failure. A pass after it means the app answered
+    // a request, so a test that still fails the same way fails for a reason this run has not seen.
+    const marks = resultMarks(text);
+    const firstFailure = marks.indexOf('✘');
+    if (firstFailure === -1 || marks.slice(firstFailure).includes('✓'))
+        return null;
+    return { count: found.count, files };
+}
+/**
+ * Every failure a run names, grouped by the cause behind it — one group per cause, with the
+ * tests it hit.
+ *
+ * The point is that ONE run yields EVERY cause. A Playwright report prints its failures one
+ * after another with no statement of which of them share a cause, so a run of 19 failures is 19
+ * bodies to read; X1 flash-m83 (2026-10-16) spent three deploys (6.7 minutes) each fixing a
+ * single cause, two of them found by runs stopped before they walked the rest.
+ *
+ * The signature is the failures' own error line where the log carries their bodies (a finished
+ * run, or a `line` reporter), and how long they took where it does not (a still-running `list`
+ * log). A test the log printed twice, or failed twice, is one test.
+ *
+ * @param log - The log of a finished or running run.
+ * @returns The causes, the one with the most tests first.
+ */
+export function failuresByCause(log) {
+    const text = log.replace(ANSI_SGR, '');
+    const byMessage = new Map();
+    for (const block of failureBlocks(text)) {
+        const message = failureMessage(block);
+        if (message === null)
+            continue;
+        const m = FAILURE_BLOCK_HEADER.exec(block.split('\n')[0] ?? '');
+        const { where, title } = splitTitlePath(m?.[1] ?? '');
+        const group = byMessage.get(message);
+        if (group)
+            group.push({ where, title, seconds: null });
+        else
+            byMessage.set(message, [{ where, title, seconds: null }]);
+    }
+    const causes = [];
+    for (const [message, members] of byMessage) {
+        const tests = distinctTests(members);
+        if (tests.length > 0)
+            causes.push({ message, seconds: null, tests });
+    }
+    // The failures with no body of their own — every failure of a still-running `list` log — are
+    // grouped by how long they took: a band is opened by its first test and takes the ones that
+    // then ran the same length, the same band {@link repeatingFailure} uses.
+    const claimed = new Set(causes.flatMap((c) => c.tests.map(testKey)));
+    const unclaimed = distinctTests(failedTests(text)).filter((t) => t.seconds !== null && !claimed.has(testKey(t)));
+    const byDuration = [];
+    for (const t of unclaimed) {
+        const band = Math.max(0.5, t.seconds * 0.05);
+        const open = byDuration.find((g) => Math.abs(g.seconds - t.seconds) <= Math.max(band, g.seconds * 0.05));
+        if (open)
+            open.tests.push(t);
+        else
+            byDuration.push({ seconds: t.seconds, tests: [t] });
+    }
+    for (const g of byDuration)
+        causes.push({ message: null, seconds: g.seconds, tests: g.tests });
+    return causes.sort((a, b) => b.tests.length - a.tests.length);
+}
+/**
+ * The one-line-per-cause summary of a finished run's failures, or null when the run named fewer
+ * than two of them.
+ *
+ * This is what makes a run worth finishing: every cause the run found, in the result the
+ * executor reads, so one round of fixes covers all of them rather than the one cause a run
+ * stopped early happened to reach.
+ *
+ * @param log - The finished run's output.
+ * @returns The note, or null.
+ */
+export function failureCausesNote(log) {
+    const causes = failuresByCause(log);
+    const total = causes.reduce((n, c) => n + c.tests.length, 0);
+    if (total < 2)
+        return null;
+    const listed = causes.slice(0, FAILURE_CAUSES_LISTED);
+    const lines = listed.map((c, i) => {
+        const tests = c.tests
+            .slice(0, FAILURE_CAUSE_TESTS_LISTED)
+            .map((t) => shortWhere(t.where) || t.title);
+        const more = c.tests.length > tests.length ? `, … and ${c.tests.length - tests.length} more` : '';
+        const signature = c.message !== null ? `\`${c.message}\`` : `each after ~${c.seconds}s`;
+        const files = new Set(c.tests.map((t) => specFile(t.where)).filter(Boolean)).size;
+        return (`  ${i + 1}. ${signature} — ${c.tests.length} test${c.tests.length === 1 ? '' : 's'} ` +
+            `in ${files} file${files === 1 ? '' : 's'}: ${tests.join(', ')}${more}`);
+    });
+    const moreCauses = causes.length > listed.length ? `\n  … and ${causes.length - listed.length} more causes` : '';
+    return (`${total} failure${total === 1 ? '' : 's'} in this run, grouped by cause — fix every cause ` +
+        `below before the next deploy:\n${lines.join('\n')}${moreCauses}`);
+}
+/**
+ * The sentence that names a cause repeating among a running suite's failures, mid-run.
  *
  * Kept here, beside {@link repeatingFailure}, so the two stay in step: every word below is about
- * what that function could actually see in the log.
+ * what that function could actually see in the log — including the count, which is of DISTINCT
+ * tests, so the note never names one or two tests as a cause.
+ *
+ * The note names the cause early so the executor can START FIXING while the run keeps walking,
+ * and it asks for the run to be stopped only when {@link universalCause} says the cause is
+ * failing the whole run. X1 flash-m76 (2026-10-16) spent 4.0 minutes walking 15 tests whose one
+ * cause was certain at the third, 47 s in, and the note answers exactly that; X1 flash-m83 then
+ * stopped eight runs at their first repeating cause in 14.5 minutes and never finished one, so
+ * the note must not say to stop when the run still has other causes to name.
  *
  * @param found - What {@link repeatingFailure} found.
- * @param o - The run's facts: its `taskId`, its `log` path, and `stop` — the shell command that
- *   stops it (the pids the platform's own pid file leads to).
+ * @param o - The run's facts: its `taskId`, its `log` path, `stop` — the shell command that
+ *   stops it, printed only for a {@link UniversalCause} — and `universal`, what
+ *   {@link universalCause} found (absent means the run is not failing whole).
  * @returns The note.
  */
 export function repeatingFailureNote(found, o) {
@@ -1237,10 +1625,26 @@ export function repeatingFailureNote(found, o) {
         : first?.where
             ? ` Re-run \`${first.where}\` alone to see its error in full.`
             : '';
-    return (`${found.count} of this run’s tests have already failed the same way — ${signature} — so one ` +
-        `cause is repeating and the rest of the run only repeats it:\n${rows}${more}\n` +
-        `Stop this run and fix that cause before the rest: \`exec_command: ${o.stop}\`. ` +
-        `It is still going (task ${o.taskId}, log ${o.log}) — do not wait for the rest of it.${reproduce}`);
+    const where = `task ${o.taskId}, log ${o.log}`;
+    if (o.universal) {
+        const files = o.universal.files.map(shortFile);
+        const shown = files.slice(0, 4).join(', ');
+        const moreFiles = files.length > 4 ? `, … and ${files.length - 4} more` : '';
+        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 ` +
+            `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}\`, ` +
+            `then run the whole suite again. It is still going (${where}).${reproduce}`);
+    }
+    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.${reproduce} ` +
+        `Let the rest of the run finish — it is the only thing that will name the causes that are NOT ` +
+        `this one, and a run stopped at its first repeating cause costs a second whole run to find ` +
+        `them. 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). ` +
+        `It is still going (${where}).`);
 }
 /**
  * Attempt a whitespace-tolerant replacement when an exact `old_string` match