@molecule/api-ai-tools 1.5.18 → 1.5.20

package/dist/utilities.js

@@ -5,6 +5,7 @@
  * @module
  */
 import { posix } from 'path';
+import { commandRunsNoTests } from './no-test-run.js';
 /**
  * Shell-safe quoting using single quotes. Unlike JSON.stringify (double quotes),
  * single-quoted strings prevent command substitution ($(), backticks) and variable expansion.
@@ -307,12 +308,27 @@ const LINE_REPORTER_FLAG = /--reporter([= ])line\b/;
  *   `[n/N] <title>` with no ✓/✘ mark and no duration, so on X1 flash-m62 an
  *   8.3-minute walk of one suite could never trip the fail-fast note.
  *
- * Only the command's last step is touched, and only its reporter.
+ * A run being ITERATED on (capped, narrowed, or by file) gets `list,line` instead
+ * of `list` alone. `list` holds every failure's error for the summary at the end,
+ * so mid-run its log says only how long each failure took; `line` writes the body
+ * as the failure happens, and a look at a running suite (`wait_for_task`'s
+ * repeating-cause note, `suite-fail-fast.ts`) can then name the repeating cause by
+ * its error message. X1 flash-m76 walked 15 tests for 4.0 minutes, every one a
+ * `TimeoutError: page.waitForURL` from one missing `navigate('/')`.
+ *
+ * Only the command's last step is touched, and only its reporter, and only when that step runs
+ * something: `npx playwright test --list` takes two seconds and writes nothing per test, so
+ * neither reporter nor `--retries=0` is added to it ({@link isPlaywrightRunCommand}).
  *
  * @param command - The command as the executor sent it.
  * @returns The command to run and one sentence per change made (empty when none).
  */
 export function streamingBackgroundCommand(command) {
+    // A command that runs no test is not a run to keep a growing log for: nothing about it is
+    // rewritten (flash-m79's `--list` was read as a whole-suite run end to end, and got a ~4 KB
+    // refusal to send itself again with `--max-failures=15`).
+    if (commandRunsNoTests(command))
+        return { command, changes: [] };
     const changes = [];
     let out = command;
     const tail = TRAILING_TAIL.exec(out);
@@ -324,38 +340,143 @@ export function streamingBackgroundCommand(command) {
     // A Playwright run behind `| head -N` loses its tally, which prints last (X1
     // flash-m32 counted ✓/✘ marks by hand); the full log comes back anyway.
     const head = /\s*\|\s*head(?:\s+-n)?\s+-?\d+\s*$/.exec(out);
-    if (head && /\bplaywright\s+test\b/.test(out)) {
+    if (head && isPlaywrightRunCommand(out)) {
         out = out.slice(0, head.index);
         changes.push(`Dropped the trailing \`${head[0].trim()}\`: Playwright prints its pass/fail count last, and it would be cut.`);
     }
     const lastStep = out.split(/&&|\|\||;/).at(-1) ?? '';
-    const finalPlaywrightRun = /\bplaywright\s+test\b/.test(lastStep) &&
+    const finalPlaywrightRun = isPlaywrightRunCommand(lastStep) &&
         // `2>&1` only joins stderr to the log; any other pipe or redirect sends the output elsewhere.
         !/[|>]/.test(lastStep.replace(/\d?>&\d/g, ''));
+    // A diagnosis or a re-run (capped, last-failed, grepped, or named files) walks each failure
+    // 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
+    // keeps the suite's retries.
+    const iterating = /--max-failures\b|--last-failed\b|(?:^|\s)(?:-g|--grep)\b|\S+\.(?:spec|test)\.[cm]?[jt]sx?(?::\d+)?\b/.test(lastStep);
+    // `list` is the shape the platform reads a background suite back in (the fail-fast note and
+    // the Tests bar both parse its `  ✓/✘  <n> … (…)` lines), and it prints each failure's error
+    // only in the summary at the END. A run being iterated on is the one whose failures are read
+    // mid-run and stopped early, and for that the log has to carry the error as it happens —
+    // `line` writes exactly that, so an iterating run gets both reporters and a proof run, which
+    // nothing stops early, keeps `list` alone rather than doubling its log.
+    const wanted = iterating ? 'list,line' : 'list';
     if (finalPlaywrightRun && LINE_REPORTER_FLAG.test(lastStep)) {
         // Only the last step is rewritten, and `lastStep` is a suffix of `out`.
         out =
             out.slice(0, out.length - lastStep.length) +
-                lastStep.replace(LINE_REPORTER_FLAG, '--reporter$1list');
-        changes.push('Switched `--reporter=line` to `--reporter=list`: it also writes each test result as it ' +
-            'finishes, and it is the shape the platform reads back from a background run.');
+                lastStep.replace(LINE_REPORTER_FLAG, `--reporter$1${wanted}`);
+        changes.push(`Switched \`--reporter=line\` to \`--reporter=${wanted}\`: it also writes each test result as it ` +
+            'finishes, and it is the shape the platform reads back from a background run.' +
+            (iterating
+                ? ' `line` stays alongside it so each failure writes its error to the log as it happens — that is what a mid-run look reads.'
+                : ''));
+    }
+    else if (finalPlaywrightRun && iterating && /--reporter([= ])list\b/.test(lastStep)) {
+        // Only the last step's reporter, the same rule as above.
+        out =
+            out.slice(0, out.length - lastStep.length) +
+                lastStep.replace(/--reporter([= ])list\b/, '--reporter$1list,line');
+        changes.push('Added `line` to your `--reporter=list`: `list` writes each test result as it finishes but ' +
+            'holds every failure’s error for the summary at the end, and `line` writes it as the failure ' +
+            'happens — which is what names a cause that repeats while this run is still going.');
     }
     else if (finalPlaywrightRun && !/--reporter\b/.test(lastStep)) {
-        out = `${out.trimEnd()} --reporter=list`;
-        changes.push('Added `--reporter=list` so each test result is written to the log as it finishes ' +
-            '(the config reporter may print nothing until the end).');
+        out = `${out.trimEnd()} --reporter=${wanted}`;
+        changes.push(`Added \`--reporter=${wanted}\` so each test result is written to the log as it finishes ` +
+            '(the config reporter may print nothing until the end).' +
+            (iterating
+                ? ' `line` writes each failure’s error as it happens, which is what a mid-run look reads.'
+                : ''));
     }
-    // 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
-    // keeps the suite's retries.
-    const iterating = /--max-failures\b|--last-failed\b|(?:^|\s)(?:-g|--grep)\b|\S+\.(?:spec|test)\.[cm]?[jt]sx?(?::\d+)?\b/.test(lastStep);
     if (finalPlaywrightRun && iterating && !/--retries\b/.test(lastStep)) {
         out = `${out.trimEnd()} --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 };
 }
+/**
+ * How a shell command starts each runner whose whole-suite run saturates the
+ * sandbox it shares. The three are the runners this platform runs whole suites
+ * of from a sandbox; `suiteRunKind` (molecule-dev `api/src/ai/suite-proof.ts`)
+ * is the platform's fuller list of URL-testing runners, and the shapes here are
+ * its shapes.
+ */
+const SUITE_RUN_COMMANDS = [
+    // `playwright test`, not a bare `playwright` (`--version` is not a run).
+    /(?:^|[\s;&|(])(?:npx\s+(?:--no-install\s+)?)?(?:\S*\/)?playwright\s+test\b/,
+    // Vitest, however it is invoked (`vitest`, `npx vitest run`).
+    /(?:^|[\s;&|(])(?:npx\s+(?:--no-install\s+)?)?(?:\S*\/)?vitest\b/,
+    // `hurl --test …` or `hurl … x.hurl`.
+    /(?:^|[\s;&|(])(?:\S*\/)?hurl\s+[^|\n]*(?:--test|\.hurl)/,
+];
+/**
+ * Whether a command runs a whole test suite — a Playwright, Vitest or Hurl run
+ * — rather than a build, an install or a one-off script.
+ *
+ * A command that invokes a runner only to print is not one of these
+ * ({@link commandRunsNoTests}): `npx playwright test --list` prints the tests it would run and
+ * exits, and `npx playwright install`, `vitest list` and `hurl --help` start no test either.
+ *
+ * @param command - The shell command.
+ * @returns True when the command starts one of those runners.
+ */
+export function isSuiteRunCommand(command) {
+    return !commandRunsNoTests(command) && SUITE_RUN_COMMANDS.some((re) => re.test(command));
+}
+/**
+ * Whether a command starts a Playwright run — `playwright test` in a form that runs something.
+ *
+ * `npx playwright test --list` matched every `\bplaywright\s+test\b` test in the platform and was
+ * then treated as a run: held (flash-m79's config check), backgrounded for a run that outlasts
+ * the tool's ceiling, and rewritten with `--reporter`. A list takes two seconds, prints its lines
+ * and exits, so it is none of those; {@link commandRunsNoTests} is what decides.
+ *
+ * @param command - The shell command.
+ * @returns True when the command starts a Playwright run.
+ */
+export function isPlaywrightRunCommand(command) {
+    return /\bplaywright\s+test\b/.test(command) && !commandRunsNoTests(command);
+}
+/**
+ * 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.
+ *
+ * A whole-suite Playwright run saturates the one container the app's Vite
+ * server, its API process and every other command also live in: on X1 flash-m75
+ * the model backgrounded a 139-test run at +36:23 and the two-word shell
+ * command it sent next — tick its plan file — returned nothing for 2 min 40 s,
+ * measured on the chat payload and on the live-stream follower independently.
+ * The backgrounding note is right that the executor should go do other work;
+ * what it cannot promise is that the sandbox will let it.
+ *
+ * `nice -n 10` lowers the run's CPU share and `ionice -c3` its IO class. Both
+ * are PROBED in the sandbox by RUNNING them, not with `command -v`: a syscall a
+ * container's seccomp policy refuses leaves `-v` passing while the real run
+ * fails. Each is applied only if its probe passed, so a sandbox with neither,
+ * or with only one, runs the suite exactly as it did before. Playwright's own
+ * workers are children of this shell and inherit both (niceness and IO class
+ * are inherited across fork/exec).
+ *
+ * Only a command the caller has already detached reaches this: foreground
+ * commands are never touched.
+ *
+ * @param command - The command as the executor sent it; the suite detection reads this.
+ * @param launch - The shell line that would start it, with no prefix of its own.
+ * @returns The line to run, and one sentence for the tool note ('' when unchanged).
+ */
+export function suiteRunPriorityLaunch(command, launch) {
+    if (!isSuiteRunCommand(command))
+        return { launch, note: '' };
+    return {
+        // `$p` is deliberately unquoted: it expands to the prefix words, and to
+        // nothing at all when neither probe passed.
+        launch: "p=''; nice -n 10 true >/dev/null 2>&1 && p='nice -n 10'; " +
+            'ionice -c3 true >/dev/null 2>&1 && p="$p ionice -c3"; ' +
+            `$p ${launch}`,
+        note: 'Started at lower CPU and IO priority, so commands you run while it works stay ' +
+            'responsive (the suite itself may take a little longer).',
+    };
+}
 // ── Command blocking ──────────────────────────────────────────────────────────
 /**
  * Commands that dump environment variables — blocked to prevent secret leakage.
@@ -474,6 +595,64 @@ export function isValidGlob(pattern) {
     // `@` has no meaning to either.
     return /^[A-Za-z0-9@*?._/()[\]-]+$/.test(pattern);
 }
+/**
+ * The `find` predicate for a `find_files` pattern.
+ *
+ * `find -name` compares a pattern against a file's BASENAME, so a pattern
+ * containing a slash (`helpers/*`, `e2e/*.spec.ts`, `src` + `**` + `/App.tsx`)
+ * can never match and the tool answers `[]` (xr-molecule-flash-m77, on two
+ * calls in one run). Such a pattern is matched with `-path` instead: an fnmatch
+ * glob over the whole printed path, whose `*` crosses `/` — the rule
+ * `.gitignore` uses, and the reason a bare `helpers/*` means "a `helpers/`
+ * directory anywhere below the root". The pattern is anchored with a leading
+ * `*` then `/` ("any parent") so the search root — an absolute
+ * `/workspace/<app>` in a sandbox — need not be spelled out.
+ *
+ * A doubled-star directory segment keeps its usual meaning of ZERO or more
+ * directories; `-path` alone would demand at least one, so the pattern is also
+ * emitted with each such segment removed.
+ *
+ * @param pattern - A pattern already accepted by {@link isValidGlob}.
+ * @returns A `find` predicate: `-name '…'` for a bare name, else one or more
+ *   `-path '…'` alternatives, ORed inside parens when there is more than one.
+ */
+export function findPatternArgs(pattern) {
+    if (!pattern.includes('/'))
+        return `-name ${shellQuote(pattern)}`;
+    const paths = pathPatternVariants(pattern).map((p) => `-path ${shellQuote(`*/${p}`)}`);
+    return paths.length === 1 ? paths[0] : `\\( ${paths.join(' -o ')} \\)`;
+}
+/**
+ * The `-path` globs for a pattern that contains a slash, one per way each
+ * doubled-star directory segment can stand for zero directories.
+ *
+ * Dropping the segment is not a convenience: `*` already crosses `/` in a
+ * `-path` glob, so the KEPT form (`src` + `**` + `/App.tsx`) matches one or more
+ * intervening directories at any depth, and only the DROPPED form
+ * (`src/App.tsx`) matches the file sitting directly in `src/`. Both are what
+ * the glob means to a caller.
+ *
+ * @param pattern - The glob, e.g. `src` + `**` + `/App.tsx`.
+ * @returns The path globs, each without the leading "any parent" anchor (added
+ *   by {@link findPatternArgs}).
+ */
+function pathPatternVariants(pattern) {
+    const rooted = pattern.replace(/^(?:\.?\/)+/, '');
+    const out = new Set();
+    const pending = [{ text: rooted, from: 0 }];
+    while (pending.length > 0) {
+        const { text, from } = pending.pop();
+        const at = text.indexOf('**/', from);
+        if (at === -1) {
+            out.add(text);
+            continue;
+        }
+        pending.push({ text, from: at + '**/'.length }); // keep it: one or more dirs
+        // Drop it — the zero-directories case, which `-path` cannot express on its own.
+        pending.push({ text: text.slice(0, at) + text.slice(at + '**/'.length), from: at });
+    }
+    return [...out];
+}
 /**
  * Validate a file tool's `path` argument is a non-empty string. A weak model
  * sometimes omits it or passes a non-string, which would otherwise crash
@@ -592,6 +771,92 @@ export const MAX_READ_RETURN_CHARS = 80 * 1024;
  * file under it "fits in ONE call", and a smaller bound here broke that promise (X1 flash-m67).
  */
 export const SMALL_FILE_WHOLE_CHARS = MAX_READ_RETURN_CHARS;
+/**
+ * How large an HTML document must be before a whole-file read is replaced by its
+ * outLINE — much smaller than {@link MAX_READ_RETURN_CHARS}, because the cost of
+ * an HTML read is almost never worth it.
+ *
+ * An entry document is boilerplate the reader rarely needs in full: meta tags,
+ * stylesheet and preload links, a `<style>` block, and a handful of `<script>`
+ * tags. The parts an executor acts on — the body's structure, where a script is
+ * loaded — are all visible in an outline of one line per tag. X0 flash-m77 paid
+ * 63,735 chars for one such read: ~60 KB of it was the IDE's own preview bridges,
+ * and the read pushed the transcript past its context cap, so the e2e specs the
+ * executor had just read were trimmed to summaries and it read the whole suite
+ * again — twice (findings, +01:23 and +02:56). The scaffold now keeps those
+ * bridges in separate files, but a template's own head is still ~5-12 KB, and a
+ * static-site or SSR entry can be far more.
+ *
+ * The outline is not a truncation: the note beside it names the exact
+ * offset/limit that returns the whole document in one call.
+ */
+export const MAX_HTML_INLINE_CHARS = 16 * 1024;
+/** Most lines an HTML outline prints before it stops and says so. */
+export const MAX_HTML_OUTLINE_LINES = 200;
+/** Longest a single outline line may be before it is cut. */
+const MAX_HTML_OUTLINE_LINE_CHARS = 200;
+/** Whether `text` is an HTML document (a doctype or an `<html` root tag). */
+export function looksLikeHtml(text) {
+    return /^\s*(?:<!doctype\s+html|<html[\s>])/i.test(text);
+}
+/**
+ * An OUTLINE of an HTML document: its head's tags and the tags that open each
+ * body section, one per line, with line numbers.
+ *
+ * Line-based on purpose — a parser would be a dependency and an attack surface
+ * for a read that only has to be *navigable*. A line is shown when it starts with
+ * `<` after trimming, which is what keeps the inside of a `<style>` block, a
+ * `<script>` body or a prerendered text section out of the outline while keeping
+ * every tag the document is built from. Long lines (a minified tag, a data URI)
+ * are cut, and the whole outline is capped, so a pathological document cannot
+ * turn one read into another wall of text.
+ *
+ * @param text - The document's full text.
+ * @param label - What to call the document in the outline's header (its path).
+ * @returns The outline — or null when `text` is not an HTML document.
+ */
+export function htmlOutline(text, label = 'document') {
+    if (!looksLikeHtml(text))
+        return null;
+    // "0 KB" for anything under a kilobyte reads like a bug; say the real unit.
+    const size = (chars) => chars >= 1024 ? `${Math.round(chars / 1024)} KB` : `${chars} char${chars === 1 ? '' : 's'}`;
+    const lines = text.split('\n');
+    const out = [];
+    let skipped = 0;
+    let skippedChars = 0;
+    let truncated = false;
+    const flushSkipped = () => {
+        if (skipped === 0)
+            return;
+        out.push(`        … ${skipped} more line${skipped === 1 ? '' : 's'} (${size(skippedChars)}) …`);
+        skipped = 0;
+        skippedChars = 0;
+    };
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        const trimmed = line.trim();
+        if (trimmed !== '' && trimmed.startsWith('<')) {
+            if (out.length >= MAX_HTML_OUTLINE_LINES) {
+                truncated = true;
+                break;
+            }
+            flushSkipped();
+            const shown = trimmed.length > MAX_HTML_OUTLINE_LINE_CHARS
+                ? `${trimmed.slice(0, MAX_HTML_OUTLINE_LINE_CHARS)}… (${trimmed.length} chars on this line)`
+                : trimmed;
+            out.push(`${String(i + 1).padStart(6)}  ${shown}`);
+        }
+        else {
+            skipped++;
+            skippedChars += line.length + 1;
+        }
+    }
+    flushSkipped();
+    const header = `OUTLINE of ${label} — ${size(text.length)}, ${lines.length} lines. ` +
+        `Its tags and the tags that open each section, one line each; tag bodies (CSS, JS, text) are not shown.` +
+        (truncated ? ` (Outline capped at ${MAX_HTML_OUTLINE_LINES} lines.)` : '');
+    return `${header}\n\n${out.join('\n')}`;
+}
 /** Max search results. */
 export const MAX_SEARCH_RESULTS = 50;
 /** Max find results. */
@@ -713,6 +978,16 @@ function truncateMiddleBody(s, maxLength) {
         `\n\n... [middle truncated — ${omitted} chars omitted; the head AND the tail are shown, a failing command's error is usually near the end] ...\n\n` +
         s.slice(s.length - tailLen));
 }
+/**
+ * A Playwright failure block's header line:
+ * `  3) [chromium] › e2e/a.spec.ts:5:1 › home › shows the title ────────`.
+ *
+ * Two things vary and both are optional here. The `[<project>] › ` half is absent from a run
+ * whose config declares no projects, and the `line` reporter draws a rule after the title on
+ * the same line. Both forms name a title path, so a header is only a header when the line
+ * carries a `›` — a plain numbered list in a build log must not read as test failures.
+ */
+const FAILURE_BLOCK_HEADER = /^\s*\d+\)\s+(?:\[[^\]\n]*\]\s*›\s*)?(?=[^\n]*›)(.+?)\s*─*\s*$/;
 /**
  * The numbered failure blocks of a Playwright report (`  1) [chromium] › file:line › title`
  * up to the next block or the tally).
@@ -725,7 +1000,7 @@ export function failureBlocks(s) {
     const blocks = [];
     let current = null;
     for (const line of lines) {
-        if (/^\s*\d+\) \[[^\]\n]+\] › /.test(line)) {
+        if (FAILURE_BLOCK_HEADER.test(line)) {
             if (current)
                 blocks.push(current.join('\n').trimEnd());
             current = [line];
@@ -770,6 +1045,229 @@ export function runningOutputSliceCommand(log, own) {
     return (`{ ${read} | grep -aE ${shellQuote(RUNNING_FAILURE_LINE_RE)} | head -${RUNNING_FAILURE_LINES} | cut -c1-300; ` +
         `echo; ${read} | tail -c ${RUNNING_TAIL_BYTES}; }`);
 }
+/** Bytes of a running log a repeating-cause look reads back. */
+export const REPEATING_CAUSE_TAIL_BYTES = 40_000;
+/**
+ * The shell command whose stdout is enough of a running log to tell whether one cause is
+ * repeating: its tail, {@link REPEATING_CAUSE_TAIL_BYTES} of it.
+ *
+ * {@link runningOutputSliceCommand} is the wrong read for this: it keeps only the FIRST 40
+ * failure lines plus 1 000 bytes, so on a run whose failures print a body each — which is what
+ * a `line` reporter does, and the only form that names the cause as an error message rather than
+ * a duration — three bodies do not fit, and the repeat is invisible. This read is not shown to
+ * anyone; it is parsed.
+ *
+ * @param log - The task log path.
+ * @param own - A file the command redirects its own output to, if any.
+ * @returns The shell command, safe to hand to the execution backend as-is.
+ */
+export function runningCauseCommand(log, own) {
+    const read = `cat ${log}${own ? ` ${shellQuote(own)}` : ''} 2>/dev/null`;
+    return `${read} | tail -c ${REPEATING_CAUSE_TAIL_BYTES}`;
+}
+/** Failures that must share one signature before a running suite's repeating cause is named. */
+export const REPEATING_FAILURE_MIN = 3;
+/** ANSI SGR sequences — the `line` reporter writes cursor moves even into a file. */
+// eslint-disable-next-line no-control-regex -- an escape sequence IS a control character
+const ANSI_SGR = /\u001B\[[0-9;]*[A-Za-z]/g;
+/**
+ * A `list`-reporter result line: `  ✘    3 [chromium] › e2e/a.spec.ts:5:1 › A › does x (15.6s)`.
+ * The `[<project>]` half is optional (a config with no projects prints none), as is the title
+ * path's `›` tail. Durations are Playwright's own: `ms`, `s`, `m`.
+ */
+const LIST_RESULT_LINE = /^\s*([✓✘])\s+\d+\s+(?:\[[^\]\n]*\]\s*›\s*)?(.+?)\s+\((\d+(?:\.\d+)?)\s*(ms|s|m)\)\s*$/;
+/** A title path's location segment (`…/articles.spec.ts:32:3`). */
+const TITLE_LOCATION = /^(.*?:\d+)(?::\d+)?$/;
+/**
+ * Split a Playwright title path (`…/a.spec.ts:5:1 › Home › shows the title`) into the location
+ * and the test's own title, dropping the column (a re-run names `file:line`).
+ *
+ * @param titlePath - The title path the log writes.
+ * @returns The location ('' when the path names none) and the title.
+ */
+function splitTitlePath(titlePath) {
+    const parts = titlePath.split(' › ');
+    const location = TITLE_LOCATION.exec(parts[0]?.trim() ?? '')?.[1];
+    if (location)
+        return { where: location, title: parts.length > 1 ? (parts.at(-1) ?? '').trim() : '' };
+    return { where: '', title: parts.join(' › ').trim() };
+}
+/**
+ * The seconds a Playwright duration is worth, in Playwright's units.
+ *
+ * @param value - The digits the log printed.
+ * @param unit - `ms`, `s` or `m`.
+ * @returns Seconds.
+ */
+function durationSeconds(value, unit) {
+    const n = Number(value);
+    if (unit === 'ms')
+        return n / 1000;
+    return unit === 'm' ? n * 60 : n;
+}
+/**
+ * Every failed test a running log names, in the order it names them.
+ *
+ * @param log - The log so far (ANSI already stripped).
+ * @returns The failed tests.
+ */
+function failedTests(log) {
+    const out = [];
+    for (const line of log.split('\n')) {
+        const m = LIST_RESULT_LINE.exec(line);
+        if (!m || m[1] !== '✘')
+            continue;
+        const { where, title } = splitTitlePath(m[2]);
+        out.push({ where, title, seconds: durationSeconds(m[3], m[4]) });
+    }
+    return out;
+}
+/**
+ * The error a failure block reports: the first line of its body that names a thrown error
+ * (`TimeoutError: page.waitForURL: Timeout 10000ms exceeded.`), else its first real line.
+ *
+ * The body's first line is usually the runner's own sentence (`Test timeout of 15000ms exceeded
+ * while running "beforeEach" hook.`), which changes with the hook; the thrown error below it is
+ * what repeats verbatim, so it is preferred.
+ *
+ * @param block - One block from {@link failureBlocks}.
+ * @returns The error line, or null when the block has no body.
+ */
+function failureMessage(block) {
+    const body = block
+        .split('\n')
+        .slice(1)
+        .map((l) => l.replace(ANSI_SGR, '').trim())
+        // Progress lines the `list` reporter interleaves with the `line` reporter's blocks are not
+        // the block's own words, and a code frame or an `at …` line is where the error happened, not
+        // what it said.
+        .filter((l) => l &&
+        !LIST_RESULT_LINE.test(l) &&
+        !/^(?:at\s|\d+ \||>\s*\d+ \||\|)/.test(l) &&
+        !/^Error Context:/.test(l));
+    const thrown = body.find((l) => /^[A-Za-z_$][\w.$]*(?:Error|Exception)\b/.test(l));
+    return thrown ?? body[0] ?? null;
+}
+/**
+ * The largest group of items sharing a key.
+ *
+ * @param groups - Keyed groups, in the order they were built.
+ * @returns The largest group's key and members, or null when there are none.
+ */
+function largestGroup(groups) {
+    let best = null;
+    for (const [key, members] of groups) {
+        if (!best || members.length > best.members.length)
+            best = { key, members };
+    }
+    return best;
+}
+/**
+ * The cause repeating among a running suite's failures, or null.
+ *
+ * Playwright's `list` reporter prints one line per test as it finishes — its mark, its title
+ * path and how long it ran — and defers each failure's error to the summary at the end, so
+ * mid-run the only signature those lines carry is the duration. A `line` reporter prints the
+ * failure bodies as they happen, and there the repeated error message itself is the signature,
+ * which is stronger (it needs no assumption about how long a failure should take), so the
+ * message is looked for first.
+ *
+ * Either way the point is the same: a suite whose failures repeat one cause spends its whole
+ * runtime proving that one cause, and the executor watching it can be told so at the third
+ * failure instead of at the last. X1 flash-m76 walked 15 tests in 4.0 minutes where 15.6 s
+ * each was the test timeout and one missing `navigate('/')` was the cause of all of them.
+ *
+ * @param log - The log so far.
+ * @returns The repeating cause, or null when no signature has {@link REPEATING_FAILURE_MIN}
+ *   failures behind it.
+ */
+export function repeatingFailure(log) {
+    const text = log.replace(ANSI_SGR, '');
+    // The failure BODIES first: a message repeating verbatim names the cause itself.
+    const byMessage = new Map();
+    for (const block of failureBlocks(text)) {
+        const message = failureMessage(block);
+        if (message === null)
+            continue;
+        const m = FAILURE_BLOCK_HEADER.exec(block.split('\n')[0] ?? '');
+        const { where, title } = splitTitlePath(m?.[1] ?? '');
+        const group = byMessage.get(message);
+        if (group)
+            group.push({ where, title, seconds: null });
+        else
+            byMessage.set(message, [{ where, title, seconds: null }]);
+    }
+    const messageGroup = largestGroup(byMessage);
+    if (messageGroup && messageGroup.members.length >= REPEATING_FAILURE_MIN)
+        return {
+            count: messageGroup.members.length,
+            message: messageGroup.key,
+            seconds: null,
+            tests: messageGroup.members,
+        };
+    // Otherwise the durations: the largest set of failures that took the same time to within the
+    // band. A test that runs to its timeout prints slightly different durations on each attempt
+    // (15.6 s, 15.1 s, 15.0 s), so the band is 0.5 s or 5% of the duration, whichever is larger.
+    const tests = failedTests(text);
+    const withSeconds = tests.filter((t) => t.seconds !== null);
+    let best = [];
+    for (const t of withSeconds) {
+        const band = Math.max(0.5, t.seconds * 0.05);
+        const near = withSeconds.filter((x) => Math.abs(x.seconds - t.seconds) <= band);
+        if (near.length > best.length)
+            best = near;
+    }
+    if (best.length < REPEATING_FAILURE_MIN)
+        return null;
+    const mean = best.reduce((sum, t) => sum + t.seconds, 0) / best.length;
+    return { count: best.length, message: null, seconds: Math.round(mean * 10) / 10, tests: best };
+}
+/** How many of a repeating cause's failures the note lists before it says "and N more". */
+export const REPEATING_FAILURE_LISTED = 5;
+/**
+ * The shortest unambiguous tail of a logged path (`…/specs/e2e/articles.spec.ts:32` →
+ * `e2e/articles.spec.ts:32`).
+ *
+ * @param where - The location the log wrote.
+ * @returns The last two path segments.
+ */
+function shortWhere(where) {
+    const parts = where.split('/');
+    return parts.slice(-2).join('/');
+}
+/**
+ * The sentence that names a cause repeating among a running suite's failures, and the command
+ * that stops the run so the cause can be fixed first.
+ *
+ * Kept here, beside {@link repeatingFailure}, so the two stay in step: every word below is about
+ * what that function could actually see in the log.
+ *
+ * @param found - What {@link repeatingFailure} found.
+ * @param o - The run's facts: its `taskId`, its `log` path, and `stop` — the shell command that
+ *   stops it (the pids the platform's own pid file leads to).
+ * @returns The note.
+ */
+export function repeatingFailureNote(found, o) {
+    const listed = found.tests.slice(0, REPEATING_FAILURE_LISTED);
+    const rows = listed
+        .map((t) => `  ✘ ${[t.where && shortWhere(t.where), t.title].filter(Boolean).join(' › ')}` +
+        (t.seconds === null ? '' : ` (${t.seconds}s)`))
+        .join('\n');
+    const more = found.count > listed.length ? `\n  … and ${found.count - listed.length} more` : '';
+    const signature = found.message !== null
+        ? `every one with \`${found.message}\``
+        : `each after ~${found.seconds}s — the same duration to within half a second`;
+    const first = found.tests[0];
+    const reproduce = first?.where && !found.message
+        ? ` \`${first.where}\` alone reproduces the first one.`
+        : first?.where
+            ? ` Re-run \`${first.where}\` alone to see its error in full.`
+            : '';
+    return (`${found.count} of this run’s tests have already failed the same way — ${signature} — so one ` +
+        `cause is repeating and the rest of the run only repeats it:\n${rows}${more}\n` +
+        `Stop this run and fix that cause before the rest: \`exec_command: ${o.stop}\`. ` +
+        `It is still going (task ${o.taskId}, log ${o.log}) — do not wait for the rest of it.${reproduce}`);
+}
 /**
  * Attempt a whitespace-tolerant replacement when an exact `old_string` match
  * failed. Finds a contiguous run of lines in `content` whose per-line

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-ai-tools",
-  "version": "1.5.18",
+  "version": "1.5.20",
   "description": "Shared AI agent tools with backend abstraction for sandbox and local execution",
   "type": "module",
   "main": "dist/index.js",
@@ -31,7 +31,7 @@
     "@molecule/api-ai": "^1.0.1"
   },
   "devDependencies": {
-    "@molecule/api-ai": "1.3.1",
+    "@molecule/api-ai": "1.3.2",
     "@types/node": "26.1.2",
     "esbuild": "0.28.2",
     "typescript": "6.0.3",