@molecule/api-ai-tools 1.8.2 → 1.9.1

package/dist/utilities.js

@@ -5,9 +5,10 @@
  * @module
  */
 import { posix } from 'path';
-import { commandSegments } from './command-position.js';
+import { commandSegments, locatedCommandSegments } from './command-position.js';
+import { classifyRunFailure } from './failure-kind.js';
 import { commandRunsNoTests } from './no-test-run.js';
-import { isDiagnosisRun, scopedRerunCommand, suiteCommandTarget, suiteRunInTheWay, withoutHeredocs, } from './suite-overlap.js';
+import { isDiagnosisRun, scopedRerunCommand, suiteCommandTarget, suiteRunInTheWay, withoutHeredocs, withSuiteConfig, } from './suite-overlap.js';
 /**
  * Shell-safe quoting using single quotes. Unlike JSON.stringify (double quotes),
  * single-quoted strings prevent command substitution ($(), backticks) and variable expansion.
@@ -430,16 +431,23 @@ export function streamingBackgroundCommand(command) {
     // 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.
+     * Add a word to the suite runner's own arguments; false when the runner could not be placed.
+     *
+     * A pipe this rewrite could not drop still follows the runner (`| tee run.log`), so appending at
+     * the end of the whole command would make the word an operand of the filter — m102's dangling
+     * `--trace` flag, in the same shape. A suite inside a nested `sh -c '<command>'` string has no
+     * offsets in this command (they are positions in THAT string), so the command is left exactly as
+     * written and the caller reports no rewrite: appending at the end would hand the flag to the
+     * shell, outside the quotes.
      */
     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}`;
+        if (runner && runner.end === null)
+            return false;
+        const at = runner?.end ?? out.trimEnd().length;
+        out = `${out.slice(0, at)} ${flag}${out.slice(at)}`;
+        return true;
     };
     // 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,
@@ -493,8 +501,7 @@ export function streamingBackgroundCommand(command) {
                     'write every result into the log twice (X1 flash-m83).');
         }
     }
-    else if (finalPlaywrightRun) {
-        addToRun('--reporter=list');
+    else if (finalPlaywrightRun && 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).');
     }
@@ -513,8 +520,8 @@ export function streamingBackgroundCommand(command) {
             'and you need not wait for it to end to start on them.');
     }
     if (finalPlaywrightRun && diagnosis && !/--retries\b/.test(lastStep)) {
-        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.');
+        if (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 };
 }
@@ -604,32 +611,34 @@ const OUTPUT_ONLY_FILTERS = new Set([
 /** 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.
+ * The shell parse's segments with their offsets in the command.
  *
- * {@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.
+ * {@link commandSegments} answers which program each stage runs; this answers where it is. The
+ * offsets come from the parse's own token positions ({@link locatedCommandSegments}), never from
+ * searching the command for the re-joined text: the words are joined back with single spaces for
+ * matching, so `command.indexOf(segment.text)` comes up empty on irregular spacing, on a grouping
+ * brace, or on anything a heredoc body shifts — and the caller then cut at a guess or refused to
+ * cut at all (xr-molecule-flash-m105 +08:12, where a heredoc body turned a finished run into
+ * "piped" for the rest of the session).
+ *
+ * A statement inside a nested `sh -c '<command>'` string is listed with null offsets: its
+ * positions are positions in THAT string, so nothing may be spliced at them — but its separator
+ * is known, which is all a pipeline question needs.
  *
  * @param command - The shell command.
- * @returns The located segments, in order, or null.
+ * @returns The located segments, in order.
  */
 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;
+    for (const located of locatedCommandSegments(command)) {
+        if (located.segment === null)
+            continue;
         out.push({
-            segment,
-            start: at,
-            end: at + segment.text.length,
-            between: previousEnd === null ? '' : command.slice(previousEnd, at),
+            segment: located.segment,
+            start: located.start,
+            end: located.end,
+            between: located.separator,
         });
-        cursor = at + segment.text.length;
-        previousEnd = cursor;
     }
     return out;
 }
@@ -673,8 +682,6 @@ 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;
@@ -724,33 +731,59 @@ export function stripTrailingSuiteFilters(command) {
     const stage = located[first];
     if (!previous || !stage)
         return { command, dropped: '' };
+    // A stage inside a nested `sh -c` string has no offsets in this command: nothing can be cut.
+    if (previous.end === null || stage.start === null)
+        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() };
 }
+/**
+ * Where the suite runner's exit code comes from: the runner itself, or a stage piped after it.
+ *
+ * {@link suiteRunPipedAfterRunner}'s one question, with the honest third answer kept apart. The
+ * code a finished run reports is its LAST pipeline stage's, so a stage after the runner makes the
+ * code the stage's — but only when such a stage EXISTS. The platform used to report "piped" for
+ * any run whose statements it could not place in the text, which one heredoc body was enough to
+ * cause: on X1 xr-molecule-flash-m105 (+08:12) a config written in the same `exec_command` made
+ * the run come back with no exit code at all, and the note under it claimed a stage after the
+ * runner that was not there. The parse now places every statement (`locatedCommandSegments`), so
+ * "unplaced" is the rare, named case rather than a guess dressed as an answer.
+ *
+ * @param command - The shell command, after the streaming rewrite when one was applied.
+ * @returns Whether a stage follows the runner, and whether the run could be placed at all.
+ */
+export function suiteRunPipelinePlacement(command) {
+    const located = locatedSegments(command);
+    const pipeline = lastSuitePipeline(command);
+    if (pipeline !== null) {
+        const stages = pipeline.located.slice(pipeline.at);
+        // Every stage of the pipeline has to sit somewhere in THIS command to be read as a pipeline
+        // of it: a suite inside a `sh -c '<command>'` string has no offsets here.
+        const unplaced = stages.some((stage) => stage.start === null);
+        return { piped: pipeline.located.length > pipeline.at + 1, unplaced };
+    }
+    if (commandRunsNoTests(command))
+        return { piped: false, unplaced: false };
+    const runner = located.find((stage) => SUITE_RUN_COMMANDS.some((re) => re.test(stage.segment.text)));
+    // No suite at all, or a suite that is not the command's last step (a `; echo done` follows it):
+    // either way no stage after the RUNNER produces this command's code.
+    if (!runner)
+        return { piped: false, unplaced: false };
+    return { piped: false, unplaced: runner.start === null };
+}
 /**
  * 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.
+ * @returns True when a pipe this tool must not drop still follows the suite runner.
  */
 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)));
+    return suiteRunPipelinePlacement(command).piped;
 }
 /**
  * Start a background suite run at lower CPU and IO priority, so the sandbox it
@@ -1753,6 +1786,32 @@ function normalizedSignature(s) {
         .replace(/\b\d{5,}\b/g, '<n>')
         .replace(/\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi, '<id>'));
 }
+/**
+ * The per-test budget a failure block's own message names, in ms, or null. Only the runner's
+ * budget kill (`Test timeout of 15000ms exceeded`) is read: a locator wait's own
+ * `Timeout 5000ms exceeded` is the config's action timeout, not the budget a test body has to fit
+ * its repeated work into.
+ *
+ * @param block - One failure block, as {@link failureBlocks} splits them.
+ * @returns The budget in ms, or null.
+ */
+function failureBudgetMs(block) {
+    const m = /\bTest timeout of (\d+)ms exceeded\b/.exec(block.replace(ANSI_SGR, ''));
+    return m ? Number(m[1]) : null;
+}
+/**
+ * The cause signature with the budget it normalized away put back: `Test timeout of <n> exceeded`
+ * becomes `Test timeout of 15000ms exceeded`. Every other `<n>` stays — those are the values that
+ * differ between tests of one cause, while the budget is the one that does not, and it is what
+ * turns "a timeout" into "15 creates in 15 s" (xr-molecule-flash-m110 +20:44).
+ *
+ * @param message - The normalized signature.
+ * @param budgetMs - The budget the cause's first block printed.
+ * @returns The signature to print.
+ */
+function signatureWithBudget(message, budgetMs) {
+    return message.replace(/Test timeout of <n> exceeded/, `Test timeout of ${budgetMs}ms exceeded`);
+}
 /**
  * What separates one cause from another in a `playwright test` log: the error CLASS plus the
  * normalized message — the error line, the thing it waited for or asserted on, and the values
@@ -2124,17 +2183,63 @@ 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.
+ * A finished run's own count of tests that failed their first attempt and passed on the retry:
+ * Playwright's `  1 flaky`, printed in its closing tally.
+ */
+const FLAKY_TALLY_LINE = /^\s*[1-9]\d*\s+flaky\b/;
+/**
+ * The tests a finished run's tally declares FLAKY (`  1 flaky` followed by their headings), keyed
+ * the way a failure block is.
+ *
+ * Playwright prints a numbered failure block for the FIRST attempt of a test that then passes on
+ * its retry, and also declares the test under `N flaky` — so a reader that only looks at the
+ * blocks counts a flake as a cause to fix. xr-molecule-flash-m105's proof run against the deployed
+ * URL reported ten `waitForURL` timing flakes as "causes" of a red run (+24:54), and the executor
+ * spent its next minutes re-running them one by one until three passed untouched. The
+ * declaration under the count is the runner's own answer, and its heading carries the same words
+ * as the failure block's ({@link splitTitlePath} reads both the same way).
+ *
+ * @param text - The run's output, ANSI already stripped.
+ * @returns Each flaky test, first seen first.
+ */
+function flakyTestsDeclared(text) {
+    const tests = [];
+    let underFlakyCount = false;
+    for (const line of text.split('\n')) {
+        if (FLAKY_TALLY_LINE.test(line)) {
+            underFlakyCount = true;
+            continue;
+        }
+        if (!underFlakyCount)
+            continue;
+        // The declaration lines are the reporter's own headings (`    [chromium] › a.spec.ts:5:1 › …`);
+        // the first line that is not one ends them (the next tally line, or the end of the report).
+        const heading = /^\s+\[[^\]\n]+\]\s*›\s*(.+)$/.exec(line)?.[1];
+        if (heading === undefined) {
+            underFlakyCount = false;
+            continue;
+        }
+        const { where, title } = splitTitlePath(heading.replace(/[\s─]+$/, ''));
+        tests.push({ where, title, seconds: null });
+    }
+    return distinctTests(tests);
+}
+/**
+ * The causes a run's log names, the failures the request excludes, and the failures the runner
+ * itself counted as flaky 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.
+ * @returns The causes to fix, the distinct tests dropped as excluded, and the distinct tests the
+ *   runner counted as flaky (a retried pass is not a cause to fix).
  */
 function groupFailures(log, excluded) {
     const text = log.replace(ANSI_SGR, '');
+    const flakyTests = flakyTestsDeclared(text);
+    const flaky = new Set(flakyTests.map(testKey));
     const byMessage = new Map();
     const named = [];
     for (const block of failureBlocks(text)) {
@@ -2144,6 +2249,10 @@ function groupFailures(log, excluded) {
         const m = FAILURE_BLOCK_HEADER.exec(block.split('\n')[0] ?? '');
         const { where, title } = splitTitlePath(m?.[1] ?? '');
         const test = { where, title, seconds: null };
+        // The runner declared this test flaky: the block above is its first attempt, which it
+        // passed on the retry, so it is neither a cause nor a failure to re-run.
+        if (flaky.has(testKey(test)))
+            continue;
         named.push(test);
         if (matchingExcludedTitles(title, excluded).length > 0)
             continue;
@@ -2151,18 +2260,31 @@ function groupFailures(log, excluded) {
         if (group)
             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.
+        // says the same thing, and the first is the one the note's own line refers to. Its LAYER
+        // rides along too: a cause that never reached the app is not an app-code fix
+        // (`failure-kind.ts`).
         else
             byMessage.set(message, {
                 tests: [test],
                 evidence: failureEvidence(failureBody(block), message),
+                budgetMs: failureBudgetMs(block),
+                kind: classifyRunFailure(block)?.kind ?? 'assertion',
             });
     }
     const causes = [];
     for (const [message, group] of byMessage) {
         const tests = distinctTests(group.tests);
         if (tests.length > 0)
-            causes.push({ message, seconds: null, tests, evidence: group.evidence });
+            causes.push({
+                message,
+                seconds: null,
+                tests,
+                evidence: group.evidence,
+                // A duration group carries no block, so nothing says the transport failed: a cause with
+                // no layer of its own is read as an assertion (unknown is never `connection`).
+                kind: group.kind,
+                ...(group.budgetMs === null ? {} : { budgetMs: group.budgetMs }),
+            });
     }
     // 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
@@ -2173,6 +2295,9 @@ function groupFailures(log, excluded) {
     const claimed = new Set(causes.flatMap((c) => c.tests.map(testKey)));
     const unclaimed = distinctTests(listed).filter((t) => t.seconds !== null &&
         !claimed.has(testKey(t)) &&
+        // A flaky test's `✘` row is its first attempt; its `✓` retry follows it in the same log,
+        // and the runner's tally already said the test passed.
+        !flaky.has(testKey(t)) &&
         matchingExcludedTitles(t.title, excluded).length === 0);
     const byDuration = [];
     for (const t of unclaimed) {
@@ -2184,9 +2309,59 @@ function groupFailures(log, excluded) {
             byDuration.push({ seconds: t.seconds, tests: [t] });
     }
     for (const g of byDuration)
-        causes.push({ message: null, seconds: g.seconds, tests: g.tests, evidence: [] });
+        causes.push({
+            message: null,
+            seconds: g.seconds,
+            tests: g.tests,
+            evidence: [],
+            kind: 'assertion',
+        });
     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 };
+    return {
+        causes: causes.sort((a, b) => b.tests.length - a.tests.length),
+        ignored,
+        flaky: flakyTests,
+    };
+}
+/**
+ * The error every test of a Playwright run reports when the run loaded no base URL: `page.goto('/')`
+ * has nothing to resolve against, so the browser refuses the navigation before any page loads.
+ * xr-molecule-flash-m113 (+20:34) got ten of these and a list that called them ten causes.
+ */
+const NO_BASE_URL_ERROR = /Cannot navigate to invalid URL/i;
+/**
+ * The one-line note for a run whose EVERY failure is {@link NO_BASE_URL_ERROR}: a configuration
+ * failure, not a result about the app.
+ *
+ * A list of causes is the wrong shape here — there is one cause, and it is not in the app: the
+ * command loaded no base URL. The line names the config the run should have loaded (the caller
+ * passes the one the platform recorded for this suite) and hands over the exact narrowed command
+ * with it, so the next run measures the app instead of spending another six minutes on the same
+ * configuration mistake (xr-molecule-flash-m113 ran four such runs, 07:06:17 → 07:12:03).
+ *
+ * @param causes - The run's failures, all carrying the same error.
+ * @param run - How the run was started, when the caller knows it.
+ * @param excluded - The test titles the request carves out (inverted out of the re-run).
+ * @returns The one-line sentence.
+ */
+function noBaseUrlConfigNote(causes, run, excluded) {
+    const total = causes.reduce((n, c) => n + c.tests.length, 0);
+    const locations = [...new Set(causes.flatMap((c) => c.tests.map((t) => t.where)).filter(Boolean))];
+    const config = run?.config ?? null;
+    // The command is only worth handing over WITH the config: the same command without it is the
+    // run that just failed this way. Where the caller does not know the config, the line says what
+    // to find instead of repeating the mistake.
+    const rerun = run && config ? rerunOfRunningSuite(run, locations, excluded) : null;
+    const command = rerun ?? (run && config ? withSuiteConfig(run.command, config) : null);
+    return (`Every one of these ${total} failures is the same configuration failure, not a result about ` +
+        `the app: the run loaded no base URL, so every \`page.goto\` was refused with ` +
+        `\`Cannot navigate to invalid URL\` before a page opened. Nothing here is a defect to fix. ` +
+        (config
+            ? `\`${config}\` is the config that sets \`use.baseURL\`, and the run before this one loaded ` +
+                `it; this command left it out. `
+            : 'The app’s own Playwright config (the one that sets `use.baseURL`) has to be passed ' +
+                'with `--config`; this command names none. ') +
+        (command ? `Send exactly this: \`${command}\`` : ''));
 }
 /**
  * The one-line-per-cause summary of a finished run's failures, or null when the run named fewer
@@ -2197,22 +2372,33 @@ function groupFailures(log, excluded) {
  * 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.
+ * end, so a result never asks to fix a test it also says to ignore. A test the runner itself
+ * declared `flaky` (it failed once and passed on its config retry) is not a cause either: it is
+ * named apart from them, once, as what the tally called it ({@link flakyTestsDeclared}). 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.
+ *
+ * A run whose failures are ALL {@link NO_BASE_URL_ERROR} is not a set of causes at all: it is one
+ * configuration failure, said in one line ({@link noBaseUrlConfigNote}) rather than a list that
+ * reads as ten defects in the app.
  *
  * @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.
+ *   from `command`/`cwd`/`config`, 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, excluded = [], run) {
-    const { causes, ignored } = groupFailures(log, excluded);
+    const { causes, ignored, flaky } = groupFailures(log, excluded);
     const total = causes.reduce((n, c) => n + c.tests.length, 0);
     if (total < 2)
         return null;
+    // One cause that is not in the app: every failure is the browser refusing a navigation with no
+    // base URL. The list shape is what m113 read as ten causes, so it is never printed for this.
+    if (causes.every((c) => c.message !== null && NO_BASE_URL_ERROR.test(c.message)))
+        return noBaseUrlConfigNote(causes, run, excluded);
     // 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
@@ -2221,10 +2407,36 @@ export function failureCausesNote(log, excluded = [], run) {
     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 flakyTitles = [...new Set(flaky.map((t) => t.where || t.title).filter(Boolean))];
+    // A cause that never reached the app is not a cause the app's code can fix: the transport
+    // failed, so the one action is a re-run (xr-molecule-flash-m110 +18:42 — a 20 s connection
+    // timeout was read as an assertion and answered with a CORS middleware). Every cause being one
+    // is its own sentence: nothing the app produced was measured, so there is no fix round at all.
+    const connections = causes.filter((cause) => cause.kind === 'connection');
+    if (causes.length > 0 && connections.length === causes.length) {
+        const at = [...new Set(connections.flatMap((c) => c.tests.map((t) => t.where)).filter(Boolean))];
+        return (`${total} failure${total === 1 ? '' : 's'} in this run, and every one is a CONNECTION error — ` +
+            `the requests never reached the app, so nothing here is an app-code cause${at.length ? `: ${at.join(', ')}` : ''}. ` +
+            `Send the same file${at.length === 1 ? '' : 's'} once more as ${at.length === 1 ? 'it is' : 'they are'}; ` +
+            "if the failure repeats, read the app's own log (`read_logs`) — a connection error is never a " +
+            'handler shape, a header or CORS.');
+    }
     const header = `${total} failure${total === 1 ? '' : 's'} in this run, grouped by cause — fix every cause ` +
-        `below before the next deploy:\n`;
+        `below${connections.length > 0 ? ' the app’s code can produce, and re-send the connection error once as it is' : ' before the next deploy'}:\n`;
+    // The flaky sentence sits before the ignored one: the ignored sentence is the LAST thing the
+    // note says, and callers assert on that ending.
     const tail = (rerun ? ` Re-run just these once they are fixed: \`${rerun}\`` : '') +
-        (ignoredTitles.length ? ` Ignored (excluded by the request): ${ignoredTitles.join(', ')}.` : '');
+        (flakyTitles.length
+            ? ' Flaky (failed once, passed on the config retry — the runner counts these as flaky, not ' +
+                `as failures): ${flakyTitles.join(', ')}.`
+            : '') +
+        (ignoredTitles.length
+            ? ` Ignored (excluded by the request): ${ignoredTitles.join(', ')}.`
+            : '') +
+        (connections.length > 0
+            ? ` The connection error is not app code: send that file once more as it is, and if it repeats, ` +
+                "read the app's own log (`read_logs`) — it never reached the app."
+            : '');
     // 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
@@ -2260,14 +2472,15 @@ 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}\``
+        ? `\`${cause.budgetMs === undefined ? cause.message : signatureWithBudget(cause.message, cause.budgetMs)}\``
         : `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'} ` +
+    return (`  ${index + 1}. ${cause.kind === 'connection' ? 'CONNECTION error, not the app’s — ' : ''}${signature} — ` +
+        `${cause.tests.length} test${cause.tests.length === 1 ? '' : 's'} ` +
         `in ${files} file${files === 1 ? '' : 's'}: ${tests.join(', ')}${more}` +
         (shortened.length ? `\n     ${shortened.join(' · ')}` : ''));
 }
@@ -2331,8 +2544,8 @@ function omittedCausesRecap(omitted, run, excluded) {
  * the same app and database, and that is exactly what is refused while the run walks
  * ({@link suiteRunInTheWay}).
  *
- * @param run - The run in flight: the command it was started with, as it was run, and the
- *   directory that command ran in.
+ * @param run - The run in flight: the command it was started with, as it was run, the directory
+ *   that command ran in, and the config it loaded when the caller knows it.
  * @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.
@@ -2341,7 +2554,7 @@ function omittedCausesRecap(omitted, run, excluded) {
 export function rerunOfRunningSuite(run, locations, excluded = []) {
     if (locations.length === 0)
         return null;
-    const scoped = scopedRerunCommand(run.command, locations, excluded);
+    const scoped = scopedRerunCommand(run.command, locations, excluded, run.config);
     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.8.2",
+  "version": "1.9.1",
   "description": "Shared AI agent tools with backend abstraction for sandbox and local execution",
   "type": "module",
   "main": "dist/index.js",