@molecule/api-ai-tools 1.7.0 → 1.8.2

package/dist/utilities.js

@@ -349,11 +349,15 @@ export const PLAYWRIGHT_FAILURES_INLINE_ENV = 'PLAYWRIGHT_LIST_PRINT_FAILURES_IN
  *
  * - 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
@@ -386,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);
@@ -400,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
@@ -456,7 +494,7 @@ 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).');
     }
@@ -475,7 +513,7 @@ export function streamingBackgroundCommand(command) {
             '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 };
@@ -535,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.
@@ -1474,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.
@@ -1644,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;
 /**
@@ -1787,6 +2065,36 @@ export function earlyReturnCause(found, universal) {
         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.
@@ -1802,36 +2110,70 @@ export function earlyReturnCause(found, universal) {
  * 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 — 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);
@@ -1842,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
@@ -1853,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
@@ -1895,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'))

package/package.json

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