@molecule/api-ai-tools 1.6.6 → 1.8.1

package/dist/utilities.js

@@ -327,6 +327,20 @@ function lastReporterFlag(step) {
  * carries every result twice.
  */
 const PRINTING_REPORTERS = new Set(['list', 'line', 'dot', 'basic', 'spec']);
+/**
+ * Playwright's switch for printing each failure's own error as that test fails, instead of only in
+ * the summary at the end: `list` reads it in its constructor (`ListReporterOptions.printFailuresInline`,
+ * `playwright/lib/reporters/list.js` — 1.63, the version the toolchain pins), and when it prints
+ * 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:
+ * 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.
+ */
+export const PLAYWRIGHT_FAILURES_INLINE_ENV = 'PLAYWRIGHT_LIST_PRINT_FAILURES_INLINE';
 /**
  * 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
@@ -335,11 +349,15 @@ const PRINTING_REPORTERS = new Set(['list', 'line', 'dot', 'basic', 'spec']);
  *
  * - a trailing `| tail -N`, which holds everything back until the command ends.
  *   It is dropped: `wait_for_task` already returns the end of the log.
+ * - any output-only filter piped after a SUITE runner (`| grep … | tail -20`), which hides the
+ *   failing test's own error and leaves the pipeline's exit status — the filter's — as the run's.
+ *   Every such stage is dropped ({@link stripTrailingSuiteFilters}); `wait_for_task` already
+ *   returns the end of the full log, and a run whose tally shows a failure must never report 0
+ *   (xr-molecule-flash-m101 +25:54).
  * - `playwright test` with no `--reporter`, which runs the config's reporter —
  *   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.
+ *   when the playwright run is the command's last step, piped or not: it writes each result as
+ *   it finishes, and it is the 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
@@ -352,6 +370,11 @@ const PRINTING_REPORTERS = new Set(['list', 'line', 'dot', 'basic', 'spec']);
  * `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).
+ *
  * 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}).
@@ -367,6 +390,24 @@ export function streamingBackgroundCommand(command) {
         return { command, changes: [] };
     const changes = [];
     let out = command;
+    // A filter after the suite runner is not output the platform can read: it hides the failing
+    // test's own error, and its exit status replaces the run's with the filter's — m101's
+    // `… | grep -E "✘|passed|failed|skipped" | tail -20` reported `exitCode: 0` for a run with a
+    // failure in it. Every stage the parse proves is output-only is dropped; the end of the FULL
+    // log comes back anyway.
+    const filtered = stripTrailingSuiteFilters(out);
+    if (filtered.dropped) {
+        out = filtered.command;
+        // A lone trailing `| tail -N` keeps its own sentence: the reason it goes is that it holds all
+        // output back until the command ends, not that a filter cannot be read back.
+        const tailOnly = TRAILING_TAIL.exec(filtered.dropped);
+        changes.push(tailOnly && tailOnly[0].trim() === filtered.dropped
+            ? `Dropped the trailing \`${filtered.dropped}\`: it holds all output back until the command ends, ` +
+                'and wait_for_task returns the end of the log anyway.'
+            : `Dropped \`${filtered.dropped}\` from after the test runner: a filtered log cannot be ` +
+                'diagnosed — the failing test’s own error is not in it — and wait_for_task returns the ' +
+                'end of the full log anyway.');
+    }
     const tail = TRAILING_TAIL.exec(out);
     if (tail) {
         out = out.slice(0, tail.index);
@@ -381,9 +422,25 @@ export function streamingBackgroundCommand(command) {
         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 = 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, ''));
+    // 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
+    // +25:54); what the runner writes into its log does not depend on what reads the pipe. A
+    // REDIRECT still sends the output somewhere this tool cannot read it (`> out.txt`); `2>&1` only
+    // joins stderr to it.
+    const finalPlaywrightRun = isPlaywrightRunCommand(lastStep) && !/>/.test(lastStep.replace(/\d?>&\d/g, ''));
+    /**
+     * Add a word to the suite runner's own arguments. 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.
+     */
+    const addToRun = (flag) => {
+        const pipeline = lastSuitePipeline(out);
+        const runner = pipeline ? pipeline.located[pipeline.at] : undefined;
+        out = runner
+            ? `${out.slice(0, runner.end)} ${flag}${out.slice(runner.end)}`
+            : `${out.trimEnd()} ${flag}`;
+    };
     // A diagnosis or a re-run (capped, last-failed, grepped, or named files) walks each failure
     // once: the suite's own `retries` doubled every failure of X1 flash-m71's first whole run,
     // which had dropped the `--retries=0` it used one command earlier. The uncapped proof run
@@ -437,12 +494,26 @@ export function streamingBackgroundCommand(command) {
         }
     }
     else if (finalPlaywrightRun) {
-        out = `${out.trimEnd()} --reporter=list`;
+        addToRun('--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).');
     }
+    // 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.
+    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.');
+    }
     if (finalPlaywrightRun && diagnosis && !/--retries\b/.test(lastStep)) {
-        out = `${out.trimEnd()} --retries=0`;
+        addToRun('--retries=0');
         changes.push('Added `--retries=0`: a diagnosis or re-run walks each failure once; keep the suite’s retries for the proof run.');
     }
     return { command: out, changes };
@@ -502,6 +573,185 @@ export function isPlaywrightRunCommand(command) {
         return false;
     return commandSegments(command).some((segment) => /^playwright\s+test\b/.test(segment.text));
 }
+/**
+ * The programs a pipeline may end with when all they do is read what the runner printed and print
+ * it again — the filters a background suite may lose without changing what it ran.
+ *
+ * Everything else stays: `tee` writes a file, `xargs` runs a command, and an unknown program may
+ * do either. Dropping a filter is only sound where the parse can PROVE it is output-only.
+ */
+const OUTPUT_ONLY_FILTERS = new Set([
+    'awk',
+    'cat',
+    'column',
+    'cut',
+    'egrep',
+    'fgrep',
+    'fmt',
+    'fold',
+    'grep',
+    'head',
+    'jq',
+    'nl',
+    'rg',
+    'sed',
+    'sort',
+    'tail',
+    'tr',
+    'uniq',
+    'wc',
+]);
+/** A word that sends output to a file (`> f`, `>> f`, `2> f`); `2>&1` only joins stderr, so it is not one. */
+const OUTPUT_REDIRECT = /^(?:\d*|&)>>?(?!&)/;
+/**
+ * The shell parse's segments with their offsets in the command, or null when one cannot be placed.
+ *
+ * {@link commandSegments} answers which program each stage runs, but re-joins the words with single
+ * spaces — so a segment written with irregular whitespace, or a program spelled with a directory,
+ * has no offset a caller can cut at. Null is the honest answer there: every caller then leaves the
+ * command exactly as written rather than cutting into a guess.
+ *
+ * @param command - The shell command.
+ * @returns The located segments, in order, or null.
+ */
+function locatedSegments(command) {
+    const out = [];
+    let cursor = 0;
+    let previousEnd = null;
+    for (const segment of commandSegments(command)) {
+        const at = command.indexOf(segment.text, cursor);
+        if (at < 0)
+            return null;
+        out.push({
+            segment,
+            start: at,
+            end: at + segment.text.length,
+            between: previousEnd === null ? '' : command.slice(previousEnd, at),
+        });
+        cursor = at + segment.text.length;
+        previousEnd = cursor;
+    }
+    return out;
+}
+/**
+ * Whether a pipeline stage only reads the output it is handed and prints it again.
+ *
+ * `sed`/`awk` are listed for the filters they usually are (`sed -n '1,20p'`, `awk '{print $1}'`),
+ * but a program that can WRITE is not output-only: `-i` edits a file in place, and a program that
+ * names `>`, `w <file>` or `system(` writes a file or runs a command. Those keep their pipe.
+ *
+ * @param segment - One pipeline stage of the shell parse.
+ * @returns True when dropping the stage can only change what is printed.
+ */
+function isOutputOnlyFilter(segment) {
+    if (!OUTPUT_ONLY_FILTERS.has(segment.program))
+        return false;
+    if (segment.args.some((arg) => OUTPUT_REDIRECT.test(arg)))
+        return false;
+    if (segment.program === 'sed' &&
+        segment.args.some((arg) => /^(?:--in-place\b|-[A-Za-z]*i)/.test(arg)))
+        return false;
+    if (segment.program === 'awk' || segment.program === 'sed') {
+        const program = segment.args.map((arg) => arg.replace(/^['"]|['"]$/g, '')).join(' ');
+        if (/\bsystem\s*\(|>|\bw\s+\S/.test(program))
+            return false;
+    }
+    return true;
+}
+/**
+ * The command's last step, when that step runs a suite: the suite's own segment and every stage
+ * piped after it. Null when no suite runs, or when the suite is not the last step — a `;` or `&&`
+ * after it starts another statement, whose output and status are then what the command describes.
+ *
+ * A stage belongs to the same statement as its predecessor only when the two are joined by a
+ * single `|` ({@link LocatedSegment.between}); `||` is a different separator and is not one.
+ *
+ * @param command - The shell command.
+ * @returns The located segments and the last suite stage's index among them, or null.
+ */
+function lastSuitePipeline(command) {
+    if (commandRunsNoTests(command))
+        return null;
+    const located = locatedSegments(command);
+    if (located === null)
+        return null;
+    let at = -1;
+    for (let i = 0; i < located.length; i += 1) {
+        const segment = located[i]?.segment;
+        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 };
+}
+/**
+ * Drop the output-only filters piped after the command's suite runner.
+ *
+ * A filter after the runner is not "the end of the log" the executor asked for: it hides the
+ * failing test's own error (it usually matches none of `✘|passed|failed`), and the pipeline's exit
+ * status becomes the FILTER's, so `… 2>&1 | grep -E "✘|passed|failed|skipped" | tail -20` came back
+ * `exitCode: 0` for a run with a failure in it (xr-molecule-flash-m101 +25:54). The tool returns
+ * the end of the full log anyway, so the filter only costs diagnosability.
+ *
+ * Only a contiguous suffix of the stages after the runner is cut, and only stages the parse proves
+ * are output-only ({@link isOutputOnlyFilter}): a `| tee` or `| xargs` keeps its place, and a
+ * caller that reports the run's exit code must then treat it as unknown
+ * ({@link suiteRunPipedAfterRunner}).
+ *
+ * @param command - The shell command.
+ * @returns The rewritten command and the stages dropped.
+ */
+export function stripTrailingSuiteFilters(command) {
+    const pipeline = lastSuitePipeline(command);
+    if (pipeline === null)
+        return { command, dropped: '' };
+    const { located, at } = pipeline;
+    let first = located.length;
+    for (let i = located.length - 1; i > at; i -= 1) {
+        const stage = located[i];
+        if (!stage || !isOutputOnlyFilter(stage.segment))
+            break;
+        first = i;
+    }
+    if (first === located.length)
+        return { command, dropped: '' };
+    const previous = located[first - 1];
+    const stage = located[first];
+    if (!previous || !stage)
+        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() };
+}
+/**
+ * Whether the command's last step runs a suite whose output still passes through a stage after
+ * the runner — one {@link stripTrailingSuiteFilters} could not prove is output-only (`| tee log`,
+ * `| xargs …`). The pipeline's exit status is that stage's, not the run's.
+ *
+ * A command whose stages cannot be placed in the text (irregular whitespace inside the run) is
+ * reported as piped too: whether a pipe follows the runner is then UNKNOWN, and an unknown exit
+ * code that gets trusted is a failing run read as a pass — the failure this rule exists to stop.
+ *
+ * @param command - The shell command, after the streaming rewrite when one was applied.
+ * @returns True when a pipe this tool must not drop still follows the suite runner, or when the
+ *   command runs a suite the parse cannot place.
+ */
+export function suiteRunPipedAfterRunner(command) {
+    const pipeline = lastSuitePipeline(command);
+    if (pipeline !== null)
+        return pipeline.located.length > pipeline.at + 1;
+    // No placed pipeline: either there is no suite at all, or its stages cannot be located.
+    if (commandRunsNoTests(command) || locatedSegments(command) !== null)
+        return false;
+    return commandSegments(command).some((segment) => SUITE_RUN_COMMANDS.some((re) => re.test(segment.text)));
+}
 /**
  * Start a background suite run at lower CPU and IO priority, so the sandbox it
  * shares with everything else stays responsive to what the executor does next.
@@ -1280,10 +1530,12 @@ export const RUNNING_FAILURE_LINE_RE = '^[[:space:]]*(✘|✗|×|✖|✕|[0-9]+\
  * The shell command whose stdout is the interesting part of a log that is still being written:
  * the failure lines so far (capped at {@link RUNNING_FAILURE_LINES}), then the end of the log.
  *
- * A Playwright `list` run prints one line per test as it finishes and its error blocks only at
- * the end, so the LAST bytes of a running log are its least informative part — in X1 flash-m61
- * the last 3 000 bytes of a 139-test walk were the skip list, and all 61 failures were above
- * them, which cost the run the grep it had to make anyway.
+ * A Playwright `list` run prints one line per test as it finishes, so the LAST bytes of a running
+ * log are its least informative part — in X1 flash-m61 the last 3 000 bytes of a 139-test walk
+ * were the skip list, and all 61 failures were above them, which cost the run the grep it had to
+ * make anyway. A background run also carries each failure's own error as it fails
+ * ({@link PLAYWRIGHT_FAILURES_INLINE_ENV}), and {@link RUNNING_FAILURE_LINE_RE} already matches
+ * those blocks' headers and their `Error:` lines, so this slice shows the causes too.
  *
  * @param log - The task log path.
  * @param own - A file the command redirects its own output to, if any.
@@ -1439,6 +1691,44 @@ function failureDetail(body) {
     ];
     return parts.filter((p) => p !== undefined).join(' · ');
 }
+/** The longest one body line a cause's recap carries before it is shortened. */
+const FAILURE_EVIDENCE_CHARS = 200;
+/**
+ * The two body lines worth carrying beside a cause's signature: the values that differ
+ * (`Expected:` / `Received:`), or — where the failure asserts no pair — the locator from the
+ * `Call log` and the error line that follows it.
+ *
+ * The signature is normalised ({@link normalizedSignature}): `Expected: 100000` becomes
+ * `Expected: <n>`, and a signature built from a `waiting for` line never carries the assertion
+ * values at all. Those values are what a fix round needs, and the run's stdout they came from is
+ * cut in the MIDDLE by the tool-result cap, so a listed cause that does not carry them sends the
+ * executor back to the log — xr-molecule-flash-m102 (+12:43) made four `grep -A` round trips
+ * (~25 s) for the bodies of causes the note had already listed.
+ *
+ * @param body - The block's lines, from {@link failureBody}.
+ * @param message - The cause's signature: a line it already carries is not repeated.
+ * @returns Up to two lines, most useful first (empty when the body names none).
+ */
+function failureEvidence(body, message) {
+    const carried = (line) => message !== null && message.includes(line);
+    const expected = body.find((l) => /^Expected\b/.test(l));
+    const received = body.find((l) => /^Received\b/.test(l));
+    if (expected !== undefined && received !== undefined)
+        return [expected, received];
+    const picked = [];
+    const waiting = body.find((l) => /^-?\s*waiting for (?:locator\(|navigation|element|selector)/.test(l));
+    if (waiting !== undefined)
+        picked.push(waiting.replace(/^-\s*/, ''));
+    const locator = body.find((l) => /^Locator:\s/.test(l));
+    if (locator !== undefined)
+        picked.push(locator);
+    // The first body line IS the error the signature already names; a later `Error:` line is the
+    // detail that explains it (a strict-mode violation, the two elements it resolved to).
+    const detail = body.slice(1).find((l) => /^Error:\s/.test(l));
+    if (detail !== undefined)
+        picked.push(detail);
+    return picked.filter((line) => !carried(line)).slice(0, 2);
+}
 /**
  * A cause signature with the values that differ between two tests of ONE cause replaced by `<n>`:
  * a duration, a generated id or timestamp, a host's port.
@@ -1529,9 +1819,11 @@ function distinctTests(tests) {
  * 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. Where the log carries the
- * failure bodies (a `line` reporter's output, or a finished run's summary) the signature is the
+ * path and how long it ran — and, on a run the platform started in the background, each failure's
+ * own error with it ({@link PLAYWRIGHT_FAILURES_INLINE_ENV}); a `list` run with no error bodies in
+ * its log (an older Playwright, a log the bodies have been cut from) carries only the duration as
+ * a signature. Where the log carries the failure bodies (either inline, or in a finished run's
+ * summary) the signature is the
  * error itself — {@link failureMessage}: the error class plus the locator or the values that
  * differ — which is stronger (it needs no assumption about how long a failure should take), so
  * the message is looked for first and the duration is then left with the tests whose bodies the
@@ -1607,8 +1899,31 @@ 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;
+/**
+ * The platform's cap on one tool result's text: `MAX_TOOL_OUTPUT_CHARS` in molecule-dev's
+ * `api/src/ai/chat-handler.ts`, which cuts a longer string field's MIDDLE. A finished run's
+ * stdout is cut to it, so the cause list must not depend on reading the log back — and must
+ * itself fit inside it, or the cut lands in the list.
+ */
+export const TOOL_RESULT_CHARS = 8000;
+/**
+ * The characters a finished run's cause list may use of {@link TOOL_RESULT_CHARS}. The recap
+ * measured by xr-molecule-flash-m102 (+12:43) was `12 failures, 8 causes`: one cause line is
+ * ~200 chars and ~80 more with its two body lines, so 8 causes is ~2.3 k against the 8 k cap —
+ * the old 5-cause cap withheld 3 causes that the same result had room for.
+ *
+ * The rest of the cap is left to the header, the narrowed re-run command and the exclusion
+ * line, which ride the same note.
+ */
+export const FAILURE_CAUSES_CHARS = TOOL_RESULT_CHARS - 2600;
+/**
+ * How many causes a finished run's summary lists at most. The character budget above is the
+ * bound that must hold (it is what keeps the note on the surviving side of the tool-result
+ * cut); this is the bound past which a list stops being read at all.
+ */
+export const FAILURE_CAUSES_LISTED = 12;
+/** The room the "and N more causes" sentence gets inside {@link FAILURE_CAUSES_CHARS}. */
+const FAILURE_CAUSES_OMITTED_CHARS = 800;
 /** How many of one cause's tests that summary names before it says "and N more". */
 export const FAILURE_CAUSE_TESTS_LISTED = 6;
 /**
@@ -1714,6 +2029,72 @@ export function universalCause(log, found) {
         return null;
     return { count: found.count, files };
 }
+/**
+ * The ONE finding that ends a wait early, and the only one a note may hand a stop command over
+ * for: a PROVEN cause that is failing the whole run.
+ *
+ * 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
+ *   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.
+ * - **A PROVEN cause** is an error repeated VERBATIM. A shared DURATION is a LEAD, never a cause:
+ *   a suite whose config sets a timeout spends that timeout on every failure that waits for
+ *   anything, so three unrelated tests timing out together look exactly like one broken run
+ *   (`~7 s` is a property of the CONFIG, not of the cause — {@link normalizedSignature}). X1
+ *   xr-molecule-flash-m99 (2026-10-16) was told `status: 'repeating_failure'` twice on that
+ *   shape — three `url-navigation.spec.ts` tests at ~16.2 s, one `timeout: 15_000` plus teardown
+ *   — read the early return as "stop waiting, edit now", and voided a run that was still walking;
+ *   the second cost a 224 s wait that ended with no result at all.
+ *
+ * Neither half alone is enough, and {@link repeatingFailure} finding a signature is not either:
+ * that answers "is a cause repeating among this run's failures", which is worth telling the
+ * executor mid-run as a NOTE while the wait goes on. This answers the narrower question the wait
+ * needs — is the run over as a measuring instrument — and it is THE one predicate behind both
+ * that decision and the note's wording, so the two cannot come to different verdicts.
+ *
+ * @param found - What {@link repeatingFailure} found mid-run.
+ * @param universal - What {@link universalCause} found for it, if anything.
+ * @returns The cause to stop the run over, or null — in which case nothing may be stopped, the
+ *   wait keeps going, and the finding rides the run's result as a note.
+ */
+export function earlyReturnCause(found, universal) {
+    if (found.message === null)
+        return null;
+    return universal ?? null;
+}
+/**
+ * The titles a request excludes that a test's heading names — the ONE matcher for "is this
+ * failure one the request does not count?".
+ *
+ * The request quotes a test's own title (`… except "should require login to post comment"`,
+ * extracted by molecule-dev's `excludedTestTitles`) while a run's heading carries more of it
+ * (`comments.spec.ts › Comments › should require login to post comment`), so containment is the
+ * comparison. Whitespace is normalised and case is ignored: a brief may wrap the title across a
+ * line (`xr-molecule-flash-m44`), and the reporter's own casing never has to match the brief's.
+ *
+ * Two readers used to answer this separately — the causes note (which therefore asked the
+ * executor to fix a test the same result said not to) and molecule-dev's exclusion notes — and
+ * xr-molecule-flash-m101 paid for the gap (+12:00: a turn and an edit spent on the excluded
+ * test).
+ *
+ * @param heading - The text to match against: a test's title, its whole `file › describe › title`
+ *   path, or (for a note that only has the run's output) the run's text.
+ * @param excluded - The titles the request carves out, if the caller knows them.
+ * @returns The excluded titles this heading names, in the request's order.
+ */
+export function matchingExcludedTitles(heading, excluded) {
+    const normalise = (s) => s.replace(/\s+/g, ' ').trim().toLowerCase();
+    const haystack = normalise(heading);
+    if (!haystack)
+        return [];
+    return excluded.filter((title) => {
+        const needle = normalise(title);
+        return needle.length > 0 && haystack.includes(needle);
+    });
+}
 /**
  * Every failure a run names, grouped by the cause behind it — one group per cause, with the
  * tests it hit.
@@ -1723,41 +2104,76 @@ export function universalCause(log, found) {
  * 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 cause itself where the log carries the failures' bodies (a finished run,
- * or a `line` reporter) — {@link failureMessage}: the error class plus the locator or the values
- * that differ — and how long they took where it does not (a still-running `list` log, which is
- * why a duration group is labelled as a duration and not as a proven cause). A test the log
- * printed twice, or failed twice, is one test.
+ * The signature is the cause itself where the log carries the failures' bodies (a finished run, a
+ * background `list` run — whose failures print as they fail — or a `line` reporter) —
+ * {@link failureMessage}: the error class plus the locator or the values that differ — and how long
+ * they took where it does not, which is why a duration group is labelled as a duration and not as a
+ * proven cause. A test the log printed twice, or failed twice, is one test.
+ *
+ * A test the request EXCLUDES by name is not a cause to fix: its failure does not count for
+ * this request ({@link matchingExcludedTitles}), so it is dropped here rather than handed to the
+ * executor as work — a result that names it beside "it does not count" is the contradiction
+ * xr-molecule-flash-m101 filed (+12:00: the model spent a turn and an edit on the excluded test,
+ * on a page that was passing).
  *
  * @param log - The log of a finished or running run.
+ * @param excluded - The test titles the request carves out, if the caller knows them.
  * @returns The causes, the one with the most tests first.
  */
-export function failuresByCause(log) {
+export function failuresByCause(log, excluded = []) {
+    return groupFailures(log, excluded).causes;
+}
+/**
+ * The causes a run's log names, and the failures the request excludes out of them.
+ *
+ * One grouping pass, because a note that lists the causes must know what it left out to say so
+ * ({@link failureCausesNote}).
+ *
+ * @param log - The log of a finished or running run.
+ * @param excluded - The test titles the request carves out.
+ * @returns The causes to fix, and the distinct tests dropped as excluded.
+ */
+function groupFailures(log, excluded) {
     const text = log.replace(ANSI_SGR, '');
     const byMessage = new Map();
+    const named = [];
     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 test = { where, title, seconds: null };
+        named.push(test);
+        if (matchingExcludedTitles(title, excluded).length > 0)
+            continue;
         const group = byMessage.get(message);
         if (group)
-            group.push({ where, title, seconds: null });
+            group.tests.push(test);
+        // The FIRST block with this signature carries the evidence: a later block of the same cause
+        // says the same thing, and the first is the one the note's own line refers to.
         else
-            byMessage.set(message, [{ where, title, seconds: null }]);
+            byMessage.set(message, {
+                tests: [test],
+                evidence: failureEvidence(failureBody(block), message),
+            });
     }
     const causes = [];
-    for (const [message, members] of byMessage) {
-        const tests = distinctTests(members);
+    for (const [message, group] of byMessage) {
+        const tests = distinctTests(group.tests);
         if (tests.length > 0)
-            causes.push({ message, seconds: null, tests });
+            causes.push({ message, seconds: null, tests, evidence: group.evidence });
     }
-    // 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
+    // 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
+    // first test and takes the ones that
     // then ran the same length, the same band {@link repeatingFailure} uses.
+    const listed = failedTests(text);
+    named.push(...listed);
     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 unclaimed = distinctTests(listed).filter((t) => t.seconds !== null &&
+        !claimed.has(testKey(t)) &&
+        matchingExcludedTitles(t.title, excluded).length === 0);
     const byDuration = [];
     for (const t of unclaimed) {
         const band = Math.max(0.5, t.seconds * 0.05);
@@ -1768,8 +2184,9 @@ export function failuresByCause(log) {
             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);
+        causes.push({ message: null, seconds: g.seconds, tests: g.tests, evidence: [] });
+    const ignored = distinctTests(named).filter((t) => matchingExcludedTitles(t.title, excluded).length > 0);
+    return { causes: causes.sort((a, b) => b.tests.length - a.tests.length), ignored };
 }
 /**
  * The one-line-per-cause summary of a finished run's failures, or null when the run named fewer
@@ -1779,32 +2196,128 @@ export function failuresByCause(log) {
  * executor reads, so one round of fixes covers all of them rather than the one cause a run
  * stopped early happened to reach.
  *
+ * A test the request excludes is not one of the causes — it is dropped and named once, at the
+ * end, so a result never asks to fix a test it also says to ignore. Where the caller knows how
+ * the run was started, the note also hands over the narrowed re-run of exactly those tests
+ * ({@link rerunOfRunningSuite}) instead of leaving the executor to re-run the whole suite.
+ *
  * @param log - The finished run's output.
+ * @param excluded - The test titles the request carves out, if the caller knows them.
+ * @param run - How the run was started, when the caller knows it: the narrowed re-run is built
+ *   from `command`/`cwd`, and `log` (the path the output was written to) is what the "left out"
+ *   sentence greps when more causes exist than the result has room for.
  * @returns The note, or null.
  */
-export function failureCausesNote(log) {
-    const causes = failuresByCause(log);
+export function failureCausesNote(log, excluded = [], run) {
+    const { causes, ignored } = groupFailures(log, excluded);
     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) => {
-        // The path the log itself wrote, never a shortened one: it is relative to the command's own
-        // cwd, so it is the form the executor can paste back (X1 flash-m82 read a shortened
-        // `e2e/auth.spec.ts:19` as the suite's own stale starter spec, rewrote its Playwright config
-        // over it and deleted the app's tests — 4 minutes of a 60-minute run on a working config).
-        const tests = c.tests.slice(0, FAILURE_CAUSE_TESTS_LISTED).map((t) => 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 (a shared duration, not a proven cause)`;
-        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 narrowed run, so the next fix round costs two tests instead of the whole suite
+    // (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))];
+    const rerun = run ? rerunOfRunningSuite(run, locations, excluded) : null;
+    const ignoredTitles = [...new Set(ignored.map((t) => t.title || t.where).filter(Boolean))];
+    const header = `${total} failure${total === 1 ? '' : 's'} in this run, grouped by cause — fix every cause ` +
+        `below before the next deploy:\n`;
+    const tail = (rerun ? ` Re-run just these once they are fixed: \`${rerun}\`` : '') +
+        (ignoredTitles.length ? ` Ignored (excluded by the request): ${ignoredTitles.join(', ')}.` : '');
+    // This list is the part of the result that SURVIVES the platform's tool-output cut: the stdout
+    // above it is cut in the MIDDLE at {@link TOOL_RESULT_CHARS}, which is why the recap must fit
+    // whole ({@link FAILURE_CAUSES_CHARS}) instead of being capped at a line count that left 3 of
+    // xr-molecule-flash-m102's 8 causes out of a result that had room for them (+12:43).
+    const room = Math.min(FAILURE_CAUSES_CHARS, TOOL_RESULT_CHARS - header.length - tail.length - FAILURE_CAUSES_OMITTED_CHARS);
+    const lines = [];
+    let used = 0;
+    for (const cause of causes) {
+        if (lines.length >= FAILURE_CAUSES_LISTED)
+            break;
+        const line = failureCauseLine(cause, lines.length);
+        if (lines.length > 0 && used + line.length + 1 > room)
+            break;
+        lines.push(line);
+        used += line.length + 1;
+    }
+    return `${header}${lines.join('\n')}${omittedCausesRecap(causes.slice(lines.length), run, excluded)}${tail}`;
+}
+/**
+ * One cause's line in a finished run's recap: its signature, the tests it hit, and the first
+ * failure's two most useful body lines underneath.
+ *
+ * The path is the one the log itself wrote, never a shortened one: it is relative to the
+ * command's own cwd, so it is the form the executor can paste back (X1 flash-m82 read a shortened
+ * `e2e/auth.spec.ts:19` as the suite's own stale starter spec, rewrote its Playwright config over
+ * it and deleted the app's tests — 4 minutes of a 60-minute run on a working config).
+ *
+ * @param cause - The cause to write.
+ * @param index - Its position in the recap (0-based; printed 1-based).
+ * @returns The line, with its body line when it has one.
+ */
+function failureCauseLine(cause, index) {
+    const tests = cause.tests.slice(0, FAILURE_CAUSE_TESTS_LISTED).map((t) => t.where || t.title);
+    const more = cause.tests.length > tests.length ? `, … and ${cause.tests.length - tests.length} more` : '';
+    const signature = cause.message !== null
+        ? `\`${cause.message}\``
+        : `each after ~${cause.seconds}s (a shared duration, not a proven cause)`;
+    const files = new Set(cause.tests.map((t) => specFile(t.where)).filter(Boolean)).size;
+    // A line the signature already carries (a timeout's `waiting for` locator, say) is not printed
+    // 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);
+    return (`  ${index + 1}. ${signature} — ${cause.tests.length} test${cause.tests.length === 1 ? '' : 's'} ` +
+        `in ${files} file${files === 1 ? '' : 's'}: ${tests.join(', ')}${more}` +
+        (shortened.length ? `\n     ${shortened.join(' · ')}` : ''));
+}
+/**
+ * The sentence for the causes a recap could not fit: exactly which `file:line` each one was
+ * found at, and the ONE command that prints their bodies.
+ *
+ * Without it the old note said "… and 3 more causes" and left the executor to find them in a
+ * stdout whose middle the tool-result cut had already removed — xr-molecule-flash-m102 (+12:43)
+ * spent four `grep -A` round trips (~25 s) naming three causes the platform had withheld, and a
+ * weaker turn reads the listed ones and skips the rest.
+ *
+ * @param omitted - The causes past the recap's budget.
+ * @param run - How the run was started, and where its log is, when the caller knows.
+ * @param excluded - The test titles the request carves out (the fallback re-run inverts them out).
+ * @returns The sentence, or '' when nothing was omitted.
+ */
+function omittedCausesRecap(omitted, run, excluded) {
+    if (omitted.length === 0)
+        return '';
+    const all = omitted
+        .map((c) => c.tests[0]?.where || c.tests[0]?.title)
+        .filter((l) => Boolean(l));
+    // The one command: a grep of the run's own log when the caller knows its path (the bodies are
+    // still there, whole), else a narrowed re-run of exactly these tests, which prints them.
+    const print = (named) => {
+        if (run?.log && named.length > 0)
+            return (` Print them: \`grep -n -A 40 ` +
+                `${named.map((l) => `-e ${shellQuote(l)}`).join(' ')} ${shellQuote(run.log)}\`.`);
+        const rerun = run ? rerunOfRunningSuite(run, named, excluded) : null;
+        if (rerun)
+            return ` Print them by re-running just these: \`${rerun}\`.`;
+        if (named.length === 0)
+            return '';
+        return ` Print one with \`grep -n -A 40 -e ${shellQuote(named[0])} <the run's log>\`.`;
+    };
+    let keep = all.length;
+    for (;;) {
+        const named = all.slice(0, keep);
+        const dropped = all.length - keep;
+        const sentence = `\n  … and ${omitted.length} more cause${omitted.length === 1 ? '' : 's'}` +
+            (named.length
+                ? `: ${named.join(', ')}${dropped > 0 ? ` (+${dropped} more, also in the log)` : ''}`
+                : '') +
+            ` — their bodies are past the part of this result the cut keeps.` +
+            print(named);
+        if (sentence.length <= FAILURE_CAUSES_OMITTED_CHARS || keep <= 1)
+            return sentence;
+        keep = Math.max(1, Math.floor(keep / 2));
+    }
 }
 /**
  * The command that re-runs the tests at `locations` the way the run IN FLIGHT ran them: the same
@@ -1821,12 +2334,14 @@ export function failureCausesNote(log) {
  * @param run - The run in flight: the command it was started with, as it was run, and the
  *   directory that command ran in.
  * @param locations - The failing `file:line`s to re-run, as the run's log printed them.
+ * @param excluded - The test titles the request carves out: the re-run inverts them out
+ *   (`--grep-invert`) so it cannot report them again.
  * @returns The re-run command, or null when there is no suite to narrow.
  */
-export function rerunOfRunningSuite(run, locations) {
+export function rerunOfRunningSuite(run, locations, excluded = []) {
     if (locations.length === 0)
         return null;
-    const scoped = scopedRerunCommand(run.command, locations);
+    const scoped = scopedRerunCommand(run.command, locations, excluded);
     if (scoped === run.command)
         return null;
     if (!run.cwd || commandSegments(withoutHeredocs(run.command)).some((s) => s.program === 'cd'))
@@ -1841,11 +2356,15 @@ export function rerunOfRunningSuite(run, locations) {
  * 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.
+ * and it hands a stop command over only when {@link earlyReturnCause} says so — the SAME
+ * predicate the wait uses to decide whether to return early, so a finding the wait keeps waiting
+ * on is a finding this note never asks to stop for. 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. X1 xr-molecule-flash-m99 (2026-10-16) is the third shape: a shared duration is
+ * not a cause at all, so a lead reaches the executor as a note on a result it is still waiting
+ * for — never as a verdict with a stop command in it.
  *
  * The run is STILL WALKING while this note is written — both callers produce it mid-run — so a
  * re-run of one of its tests is a second run against the same app and database, and the platform
@@ -1859,7 +2378,7 @@ export function rerunOfRunningSuite(run, locations) {
  *
  * @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 a {@link UniversalCause} — `universal`, what
+ *   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.
  * @returns The note.
@@ -1917,8 +2436,11 @@ export function repeatingFailureNote(found, o) {
     // directory the run started in. Without that record it says the timing and nothing more.
     const thenRun = aRunIsInTheWay && rerun ? `\nSend this once the run ends:\n  ${rerun}` : '';
     const where = `task ${o.taskId}, log ${o.log}`;
-    if (o.universal) {
-        const files = o.universal.files.map(shortFile);
+    // The ONE predicate behind this wording and the wait's own early return (`earlyReturnCause`), so
+    // a finding the wait keeps waiting on can never be handed a stop command here.
+    const stop = earlyReturnCause(found, o.universal);
+    if (stop) {
+        const files = stop.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 ` +
@@ -1928,15 +2450,20 @@ export function repeatingFailureNote(found, o) {
             `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}`);
     }
+    // Everything else is a note on a run the wait is still waiting for, and both its shapes end the
+    // same way: the run finishes, because it is the only thing that names the causes this finding is
+    // not. What it does NOT carry is the "Stop it if every test fails this way" clause — that one
+    // belongs to a PROVEN cause the run is still walking (the sentence below), never to a lead:
+    // xr-molecule-flash-m99's executor read it on a shared duration and voided the run.
     const keepGoing = `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}).`;
+        `them. It is still going (${where}).`;
     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.${reproduce} ${keepGoing}${thenRun}`);
+            `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 ` +
         `duration to within half a second. A shared duration is a lead, not a cause: a suite whose ` +
         `config sets a timeout spends that timeout on every failure that waits for anything, so ` +