@molecule/api-ai-tools 1.6.6 → 1.8.1

package/dist/tools.js

@@ -6,7 +6,7 @@
  *
  * @module
  */
-import { commandCutRun, CUT_AT_BUDGET, cutRunSentence } from './cut-run.js';
+import { commandCutRun, CUT_AT_BUDGET, cutRunSentence, suiteRunExitCode } from './cut-run.js';
 import { addChangeSpan, changedSpan, countLines, renderEditExcerpt, renderSmallFile, } from './edit-excerpt.js';
 import { guardToolExecute, missingParamError, ToolInputError } from './input-normalizer.js';
 import { TOOL_SCHEMAS } from './schemas.js';
@@ -36,6 +36,14 @@ const outputFileByTask = new Map();
  * resolves the failing test's `file:line` against the wrong suite.
  */
 const runByTask = new Map();
+/**
+ * Why a finished suite run's result carries no exit code: the code a pipeline reports is its last
+ * stage's, and a stage after the runner (or a code of 0 beside a failure in the tally) is not the
+ * run's verdict. Said in the result so the missing field does not read as an omission.
+ */
+const FILTERED_EXIT_NOTE = 'No exit code is reported for this run: a stage after the test runner produced the pipeline’s ' +
+    'code (or the code says 0 beside a failure in the tally), so read the pass/fail tally in the ' +
+    'log instead.';
 /**
  * Task ids whose own-output file has already been looked for this process.
  * {@link outputFileByTask} is empty for every task after a restart — it is
@@ -52,8 +60,20 @@ const repeatingCauseLookMs = () => Number(process.env.MOL_AI_BG_CAUSE_LOOK_MS) |
  * Task ids a wait has already named a repeating cause for. The note is news once; a second wait
  * on the same run has nothing to add to it, and re-sending it would spend the executor's turns
  * telling it what it has already been told.
+ *
+ * Only a wait that ENDED EARLY on the finding lands here ({@link earlyReturnCause}); a lead does
+ * not, because the wait it was found in keeps looking — a run can go from a shared duration to a
+ * proven cause failing everything as the app goes down, and that is exactly the finding the wait
+ * must not sleep through.
  */
 const repeatingCauseNoted = new Set();
+/**
+ * Task ids whose mid-run finding has already ridden a result as a note ({@link
+ * repeatingFailureNote} without an {@link earlyReturnCause}). Same rule as
+ * {@link repeatingCauseNoted} — news once, and the executor still has the ✘ rows in its context —
+ * but kept apart from it, because a task in this set keeps being looked at.
+ */
+const midRunLeadNoted = new Set();
 /**
  * The shell command that stops a background task by pid: the pid the platform wrote when it
  * detached the run, plus every process under it.
@@ -209,7 +229,8 @@ function runningNote(clauses) {
     const joined = clauses.join('; ');
     return `${joined[0].toUpperCase()}${joined.slice(1)}.`;
 }
-import { checkBlockedCommand, declaredBudgetSeconds, DEFAULT_SEARCH_EXCLUDED_DIRS, directoryReadHint, emptyCallError, failureCausesNote, findPathArgs, findPatternArgs, fusedLine, htmlOutline, isCommandTimeout, isEnvFilePath, isOutsideRoot, isPlaywrightRunCommand, isSuiteRunCommand, isValidGlob, linesWithinSerialized, literalDirPrefix, MAX_BATCH_READ_FILES, MAX_FIND_RESULTS, MAX_HTML_INLINE_CHARS, MAX_OUTPUT_SIZE, MAX_READ_CALL_CHARS, MAX_READ_RETURN_CHARS, MAX_READ_SIZE, MAX_SEARCH_CONTEXT_LINES, MAX_SEARCH_RESULTS, MAX_WRITE_SIZE, outputIsWithheldUntilExit, outputRedirectTarget, parseCheckCommand, parseCheckProblem, pathArgError, printsOnlySource, READ_RESULT_ENVELOPE_CHARS, redactSecrets, redactSecretsInCode, repeatingFailure, repeatingFailureNote, resolvePath, RUNNING_FAILURE_LINES, runningCauseCommand, runningOutputSliceCommand, searchTimeoutError, serializedChars, shellQuote, sliceLines, SMALL_FILE_WHOLE_CHARS, streamingBackgroundCommand, stripControlChars, suiteRunPriorityLaunch, truncateMiddle, universalCause, whitespaceTolerantReplace, } from './utilities.js';
+import { diagnosisTraceCommand } from './trace-artifacts.js';
+import { checkBlockedCommand, declaredBudgetSeconds, DEFAULT_SEARCH_EXCLUDED_DIRS, directoryReadHint, earlyReturnCause, emptyCallError, failureCausesNote, findPathArgs, findPatternArgs, fusedLine, htmlOutline, isCommandTimeout, isEnvFilePath, isOutsideRoot, isPlaywrightRunCommand, isSuiteRunCommand, isValidGlob, linesWithinSerialized, literalDirPrefix, MAX_BATCH_READ_FILES, MAX_FIND_RESULTS, MAX_HTML_INLINE_CHARS, MAX_OUTPUT_SIZE, MAX_READ_CALL_CHARS, MAX_READ_RETURN_CHARS, MAX_READ_SIZE, MAX_SEARCH_CONTEXT_LINES, MAX_SEARCH_RESULTS, MAX_WRITE_SIZE, outputIsWithheldUntilExit, outputRedirectTarget, parseCheckCommand, parseCheckProblem, pathArgError, printsOnlySource, READ_RESULT_ENVELOPE_CHARS, redactSecrets, redactSecretsInCode, repeatingFailure, repeatingFailureNote, resolvePath, RUNNING_FAILURE_LINES, runningCauseCommand, runningOutputSliceCommand, searchTimeoutError, serializedChars, shellQuote, sliceLines, SMALL_FILE_WHOLE_CHARS, streamingBackgroundCommand, stripControlChars, suiteRunPipedAfterRunner, suiteRunPriorityLaunch, truncateMiddle, universalCause, whitespaceTolerantReplace, } from './utilities.js';
 /**
  * How long exec_command waits for a command it backgrounded only because the
  * command asked for more than the tool's ceiling, before handing back a task id.
@@ -322,6 +343,40 @@ export function installedPackageWriteRefusal(path) {
         : '';
     return `Not written: ${path} is inside ${what} (node_modules). ${change}${restore}`;
 }
+/** How many failing replacements one refusal names before it stops listing. */
+const MAX_REPORTED_REPLACEMENT_FAILURES = 5;
+/**
+ * The one refusal a batch `edit_file` gets, naming EVERY replacement that did not
+ * match — each with the same detail a lone failure gets (which replacement, the
+ * head of its old_string, where it diverges from the file).
+ *
+ * A batch is applied all-or-nothing, so one bad `old_string` means none of the
+ * others were applied either: they are not "the rest, which worked", they are
+ * unchecked work the model will otherwise re-send as-is. Naming one per round trip
+ * cost flash-m98 two full re-sends of a six-replacement batch — the second bad
+ * hunk was not reported until the first was fixed, 7 s later.
+ *
+ * @param path - The file the batch targets (nothing was written to it).
+ * @param total - How many replacements the batch carried.
+ * @param failures - Every failing replacement, in batch order.
+ * @returns The error message.
+ */
+function batchFailureError(path, total, failures) {
+    // A single replacement keeps the message it has always had: "Replacement 1 of 1"
+    // is noise, and the failure of a lone edit is not a batch problem.
+    if (total === 1 && failures.length === 1)
+        return failures[0].message;
+    const shown = failures.slice(0, MAX_REPORTED_REPLACEMENT_FAILURES);
+    const omitted = failures.length - shown.length;
+    const blocks = shown.map((f) => `Replacement ${f.index} of ${total} failed` +
+        (f.start ? ` (its old_string starts "${f.start}")` : '') +
+        `:\n${f.message}`);
+    return (`edit_file (${path}): nothing was written — ${failures.length} of the ${total} replacements do not match the file, and the batch is all-or-nothing, so re-send it with every one of these fixed.\n\n` +
+        blocks.join('\n\n') +
+        (omitted > 0
+            ? `\n\n(${omitted} more replacement${omitted === 1 ? '' : 's'} also failed and are not shown.)`
+            : ''));
+}
 /**
  * Build a complete set of AI agent tools bound to an execution backend.
  *
@@ -330,7 +385,7 @@ export function installedPackageWriteRefusal(path) {
  * @returns Array of AITool objects ready to pass to an AI provider
  */
 export function buildTools(backend, config) {
-    const { include, exclude, pathGuards = true, symlinkGuards = false, redactSecrets: doRedact = true, blockDangerousCommands = false, blockCommand, execTimeoutMs = 120_000, commandBudgetMs, overCeilingGraceMs = OVER_CEILING_GRACE_MS, searchExcludedDirs, outlineLargeHtml, onAfterWrite, onFileDiff, onFileChange, } = config ?? {};
+    const { include, exclude, pathGuards = true, symlinkGuards = false, redactSecrets: doRedact = true, blockDangerousCommands = false, blockCommand, execTimeoutMs = 120_000, commandBudgetMs, overCeilingGraceMs = OVER_CEILING_GRACE_MS, searchExcludedDirs, outlineLargeHtml, excludedTestTitles, onAfterWrite, onFileDiff, onFileChange, } = config ?? {};
     const root = backend.projectRoot;
     // A host-filesystem backend with escape guards off is the combination the
     // audit flagged: `pathGuards` off lets `..` paths out of the workspace,
@@ -1080,6 +1135,13 @@ export function buildTools(backend, config) {
                 // Replacements refused for changing the line break at old_string's boundary and
                 // nothing else — reported by position, never applied (see below).
                 const skipped = [];
+                // Every replacement this batch refuses, collected rather than returned on the
+                // first: a batch is atomic, so the other bad hunks are just as unreported, and
+                // one-per-round-trip cost flash-m98 two full re-sends of a six-replacement
+                // batch (the second bad hunk was not named until the first was fixed).
+                const failures = [];
+                /** How a failure names the replacement it is about: the head of its old_string. */
+                const startOf = (text) => text.split('\n')[0].trim().slice(0, 80);
                 // Where each applied replacement landed, in the coordinates of the
                 // latest content — rendered into the result so the model sees the edit.
                 let spans = [];
@@ -1112,9 +1174,12 @@ export function buildTools(backend, config) {
                     // method access) or silently inserts the literal "undefined" (a missing
                     // new_string). Fail fast with an actionable message instead.
                     if (typeof oldString !== 'string' || oldString === '' || typeof newString !== 'string') {
-                        return {
-                            error: `edit_file: each replacement needs a non-empty string old_string and a string new_string (got old_string: ${oldString === '' ? 'empty' : typeof oldString}, new_string: ${typeof newString}). To delete text, pass new_string: "".`,
-                        };
+                        failures.push({
+                            index: index + 1,
+                            start: typeof oldString === 'string' ? startOf(oldString) : '',
+                            message: `each replacement needs a non-empty string old_string and a string new_string (got old_string: ${oldString === '' ? 'empty' : typeof oldString}, new_string: ${typeof newString}). To delete text, pass new_string: "".`,
+                        });
+                        continue;
                     }
                     const count = content.split(oldString).length - 1;
                     // The edit is ALREADY in the file: old_string is gone and a distinctive
@@ -1136,9 +1201,12 @@ export function buildTools(backend, config) {
                         // match failed and hand back the file's actual content so it fixes in
                         // one retry instead of many.
                         if (oldString.includes('\\n')) {
-                            return {
-                                error: `old_string not found in ${path} (hint: old_string contains literal "\\n" — use actual newlines in JSON strings, not escaped \\n)`,
-                            };
+                            failures.push({
+                                index: index + 1,
+                                start: startOf(oldString),
+                                message: `old_string not found in ${path} (hint: old_string contains literal "\\n" — use actual newlines in JSON strings, not escaped \\n)`,
+                            });
+                            continue;
                         }
                         // Whitespace-only mismatch: the text is there but indentation/spacing
                         // differs (tabs vs spaces, trailing whitespace). If a UNIQUE line-run
@@ -1154,9 +1222,12 @@ export function buildTools(backend, config) {
                         const normalize = (s) => s.replace(/\s+/g, ' ').trim();
                         const normOld = normalize(oldString);
                         if (normOld && normalize(content).includes(normOld)) {
-                            return {
-                                error: `old_string not found in ${path} — a match exists but whitespace/indentation differs and is not unique enough to apply automatically. Re-read the file and copy the exact text (tabs vs spaces, trailing spaces, blank lines must match), or include more surrounding context.`,
-                            };
+                            failures.push({
+                                index: index + 1,
+                                start: startOf(oldString),
+                                message: `old_string not found in ${path} — a match exists but whitespace/indentation differs and is not unique enough to apply automatically. Re-read the file and copy the exact text (tabs vs spaces, trailing spaces, blank lines must match), or include more surrounding context.`,
+                            });
+                            continue;
                         }
                         // Anchor probe: locate the target region by the most DISTINCTIVE line
                         // of old_string (longest non-trivial line first, requiring a UNIQUE
@@ -1174,9 +1245,7 @@ export function buildTools(backend, config) {
                                 .slice(start, idx + 8)
                                 .map((l, i) => `${start + i + 1}: ${l}`)
                                 .join('\n');
-                            return {
-                                error: `old_string not found in ${path}. The file's ACTUAL content near your target (copy the exact text from here):\n${snippet}`,
-                            };
+                            return `old_string not found in ${path}. The file's ACTUAL content near your target (copy the exact text from here):\n${snippet}`;
                         };
                         // An import block the model rebuilt in its own order: the linter's
                         // import sort owns that order, so name it and show the real block. X1
@@ -1193,12 +1262,15 @@ export function buildTools(backend, config) {
                                     .slice(start, at + 1)
                                     .map((l, i) => `${start + i + 1}: ${l}`)
                                     .join('\n');
-                                return {
-                                    error: `old_string not found in ${path}: it is an import block, and the linter's import ` +
+                                failures.push({
+                                    index: index + 1,
+                                    start: startOf(oldString),
+                                    message: `old_string not found in ${path}: it is an import block, and the linter's import ` +
                                         `sort decides its order, so do not rebuild it. The file's import from ` +
                                         `'${imported}' reads:\n${block}\nEdit one line of it, or add your import as a ` +
                                         'new line and let the linter sort it.',
-                                };
+                                });
+                                continue;
                             }
                         }
                         const distinctiveLines = [
@@ -1233,13 +1305,11 @@ export function buildTools(backend, config) {
                                 .slice(start, base + k + 6)
                                 .map((l, i) => `${start + i + 1}: ${l}`)
                                 .join('\n');
-                            return {
-                                error: `old_string not found in ${path} — it matches the file through line ${base + k}, ` +
-                                    `then diverges at your line ${k + 1} of ${oldLines.length}${howFar}.\n` +
-                                    `Your old_string line ${k + 1}: ${whitespaceOnly ? visible(expected) : expected}\n` +
-                                    `The file's line ${base + k + 1}: ${whitespaceOnly ? visible(actual) : actual}\n` +
-                                    `The file's ACTUAL content near your target (copy the exact text from here):\n${snippet}`,
-                            };
+                            return (`old_string not found in ${path} — it matches the file through line ${base + k}, ` +
+                                `then diverges at your line ${k + 1} of ${oldLines.length}${howFar}.\n` +
+                                `Your old_string line ${k + 1}: ${whitespaceOnly ? visible(expected) : expected}\n` +
+                                `The file's line ${base + k + 1}: ${whitespaceOnly ? visible(actual) : actual}\n` +
+                                `The file's ACTUAL content near your target (copy the exact text from here):\n${snippet}`);
                         };
                         // The longest run of old_string lines that IS in the file decides which
                         // alignment to report, so a later distinctive line can beat an earlier
@@ -1271,10 +1341,22 @@ export function buildTools(backend, config) {
                             if (k > 0 && k < oldLines.length && (best === null || k > best.k))
                                 best = { base, k };
                         }
-                        if (best)
-                            return showDivergence(best.base, best.k);
-                        if (firstUniqueHit !== null)
-                            return showSnippet(firstUniqueHit);
+                        if (best) {
+                            failures.push({
+                                index: index + 1,
+                                start: startOf(oldString),
+                                message: showDivergence(best.base, best.k),
+                            });
+                            continue;
+                        }
+                        if (firstUniqueHit !== null) {
+                            failures.push({
+                                index: index + 1,
+                                start: startOf(oldString),
+                                message: showSnippet(firstUniqueHit),
+                            });
+                            continue;
+                        }
                         // Fallback: the first non-blank line, even if not unique (better than a
                         // bare "re-read" when the model just needs to see nearby real content).
                         const firstLine = oldString
@@ -1283,8 +1365,14 @@ export function buildTools(backend, config) {
                             ?.trim();
                         if (firstLine) {
                             const idx = fileLines.findIndex((l) => l.includes(firstLine));
-                            if (idx >= 0)
-                                return showSnippet(idx);
+                            if (idx >= 0) {
+                                failures.push({
+                                    index: index + 1,
+                                    start: startOf(oldString),
+                                    message: showSnippet(idx),
+                                });
+                                continue;
+                            }
                         }
                         // Nothing anchored. Say WHICH of the two situations this is — they
                         // call for different next moves, and the old message implied the
@@ -1294,20 +1382,20 @@ export function buildTools(backend, config) {
                         // "re-read and copy the exact text", which is wrong advice when the
                         // text is not in the file at all.
                         const anchorsPresent = distinctiveLines.some((anchor) => fileLines.some((l) => l.includes(anchor)));
-                        if (!anchorsPresent) {
-                            return {
-                                error: `old_string not found in ${path} — and NONE of its lines appear anywhere in ` +
+                        failures.push({
+                            index: index + 1,
+                            start: startOf(oldString),
+                            message: !anchorsPresent
+                                ? `old_string not found in ${path} — and NONE of its lines appear anywhere in ` +
                                     `that file, so this is not a whitespace problem. Either the edit was already ` +
                                     `applied, or this is the wrong file. read_file it and look before trying ` +
-                                    `again; do not retry the same old_string.`,
-                            };
-                        }
-                        return {
-                            error: `old_string not found in ${path}. Parts of it ARE in the file but no single ` +
-                                `line is distinctive enough to locate the target. read_file the region you ` +
-                                `mean and copy old_string verbatim from what it returns — including ` +
-                                `indentation — or include more surrounding context to make it unique.`,
-                        };
+                                    `again; do not retry the same old_string.`
+                                : `old_string not found in ${path}. Parts of it ARE in the file but no single ` +
+                                    `line is distinctive enough to locate the target. read_file the region you ` +
+                                    `mean and copy old_string verbatim from what it returns — including ` +
+                                    `indentation — or include more surrounding context to make it unique.`,
+                        });
+                        continue;
                     }
                     if (count > 1 && (replaceAll === true || replaceAllCamel === true)) {
                         // Every occurrence, by split/join — never String.replace, whose
@@ -1323,9 +1411,12 @@ export function buildTools(backend, config) {
                         const lines = [];
                         for (let at = content.indexOf(oldString); at >= 0 && lines.length < 10; at = content.indexOf(oldString, at + 1))
                             lines.push(content.slice(0, at).split('\n').length);
-                        return {
-                            error: `old_string found ${count} times in ${path} (starting at lines ${lines.join(', ')}${count > lines.length ? ', …' : ''}) — must be unique. Include more surrounding context from the one you mean, or set replace_all: true on this replacement to change every occurrence.`,
-                        };
+                        failures.push({
+                            index: index + 1,
+                            start: startOf(oldString),
+                            message: `old_string found ${count} times in ${path} (starting at lines ${lines.join(', ')}${count > lines.length ? ', …' : ''}) — must be unique. Include more surrounding context from the one you mean, or set replace_all: true on this replacement to change every occurrence.`,
+                        });
+                        continue;
                     }
                     // Splice by index rather than `content.replace(oldString, newString)`:
                     // String.replace treats `$&`, `$$`, `` $` ``, `$'` in the REPLACEMENT as
@@ -1352,6 +1443,13 @@ export function buildTools(backend, config) {
                     spans = addChangeSpan(spans, content, spliced);
                     content = spliced;
                 }
+                // Every replacement was checked before this: a batch that refuses ANY of them
+                // writes nothing, so the ones that DID match are just as unreported as the ones
+                // that did not — and naming them one per round trip cost flash-m98 two full
+                // re-sends of a six-replacement batch. Nothing is written here: the file on disk
+                // is the original, and the model fixes all of them in one retry.
+                if (failures.length)
+                    return { error: batchFailureError(path, replacements.length, failures) };
                 // One line per refused replacement: what it would have done, and the two ways to
                 // say it on purpose. The rest of the batch is applied — the second half of the pair
                 // above (`comments.ts`'s third replacement, `articles.ts`'s own text edit) anchors
@@ -1687,7 +1785,7 @@ export function buildTools(backend, config) {
             }
         },
         async exec_command(input) {
-            const command = input.command;
+            const rawCommand = input.command;
             const cwd = input.cwd ? resolve(input.cwd, 'cwd') : root;
             // A model that sent the command under another name (`cmd`, `script`, …)
             // has already been normalized by guardToolExecute; reaching here with
@@ -1697,21 +1795,32 @@ export function buildTools(backend, config) {
             // undefined (reading 'match')" — the executor read that as a broken shell,
             // stopped verifying, and ended the turn claiming all checks passed while
             // seven acceptance checks failed (X0 rehearsal 83, 2026-09-16).
-            if (typeof command !== 'string' || command.trim() === '') {
+            if (typeof rawCommand !== 'string' || rawCommand.trim() === '') {
                 return { error: missingParamError(TOOL_SCHEMAS.exec_command, input, ['command']) };
             }
             if (blockDangerousCommands) {
-                const blocked = checkBlockedCommand(command);
+                const blocked = checkBlockedCommand(rawCommand);
                 if (blocked)
                     return { error: blocked };
             }
             // Consumer-specific guard (see ToolBuildConfig.blockCommand) — an environment can
             // veto commands the generic dangerous-command check can't know about.
             if (blockCommand) {
-                const blocked = blockCommand(command, cwd);
+                const blocked = blockCommand(rawCommand, cwd);
                 if (blocked)
                     return { error: blocked };
             }
+            // A diagnosis run of a suite whose config records no trace gets one recorded anyway
+            // (`diagnosisTraceCommand`, trace-artifacts.ts): the failing tests' own network log is what
+            // tells a swallowed request error from a selector, and X1 xr-molecule-flash-m100 spent the
+            // last minutes of its run hand-writing Chromium probes for what the trace it never wrote
+            // down would have said. The whole rule is that function's; the proof run is never touched.
+            const traced = await diagnosisTraceCommand({
+                command: rawCommand,
+                cwd,
+                readFile: (path) => backend.readFile(path),
+            });
+            const command = traced.command;
             // Detached: start it, hand back a handle, let the turn continue. A
             // command that outlives the tool's ceiling is otherwise simply lost —
             // measured across six agent runs, ten of them were killed at the
@@ -1759,6 +1868,10 @@ export function buildTools(backend, config) {
                     // Keep the log growing while it runs (see streamingBackgroundCommand):
                     // an empty log is what wait_for_task reads as stuck.
                     const streaming = streamingBackgroundCommand(command);
+                    // …and the trace flag this tool added (above), which the streaming rewrite never saw:
+                    // its changes are what this branch reports the run's own settings in.
+                    if (traced.change)
+                        streaming.changes.unshift(traced.change);
                     // A whole-suite run starves the sandbox it shares with the app and with
                     // every command the executor sends next, so it starts at lower CPU and
                     // IO priority (see suiteRunPriorityLaunch). Foreground runs are never
@@ -1774,6 +1887,9 @@ export function buildTools(backend, config) {
                         outputFileByTask.set(id, ownFile);
                     runByTask.set(id, { command: streaming.command, cwd });
                     await backend.writeFile(script, `${streaming.command}\n`);
+                    // The clock the grace return below reports a stopped run against: the command is
+                    // started here, and how long it ran is what a stop at its own bound is read from.
+                    const launchedAt = Date.now();
                     await backend.run(`nohup sh -c ${shellQuote(prioritized.launch)} ` +
                         `> /dev/null 2>&1 & echo $! > /tmp/${id}.pid`, { cwd, timeout: 15_000 });
                     // A command backgrounded only for the budget it ASKED for often ends in
@@ -1803,12 +1919,43 @@ export function buildTools(backend, config) {
                                     // Finished without writing anything: an empty output is still a result.
                                     output = '';
                                 }
+                                const stdout = sanitizeOutput(truncateMiddle(output, MAX_OUTPUT_SIZE));
+                                // A grace return is a foreground-shaped result, so it carries the same stop: this
+                                // command was started because its output is withheld until it ends (a Playwright
+                                // run behind a pipe), and a run that printed a tally accounting for fewer tests
+                                // than it announced was stopped — not "Finished … with exit code 0" (the pipeline's
+                                // 0 is the filter's). No tool budget applies to a detached run, so the command's
+                                // own `timeout` is the only bound here.
+                                const cut = commandCutRun(command, { exitCode: code, stdout, stderr: '' }, Date.now() - launchedAt, 0, output);
+                                if (cut) {
+                                    return {
+                                        stdout,
+                                        stderr: '',
+                                        status: CUT_AT_BUDGET,
+                                        exitCode: cut.exitCode,
+                                        cutRun: cut,
+                                        ...(output.length > MAX_OUTPUT_SIZE
+                                            ? { truncated: true, fullOutput: log }
+                                            : {}),
+                                        error: `${cutRunSentence(cut)} ` +
+                                            (isSuiteRunCommand(command) ? SUITE_OVER_BUDGET_ADVICE : SPLIT_WORK_ADVICE),
+                                    };
+                                }
+                                // The exit file holds the PIPELINE's code: when a stage this rewrite could not
+                                // prove is output-only still follows the suite runner (`| tee run.log`), that code
+                                // is the filter's — report none and let the log's tally decide (m101 +25:54).
+                                const piped = suiteRunPipedAfterRunner(streaming.command);
+                                const reported = suiteRunExitCode(code, output, piped);
+                                const notes = [
+                                    ...streaming.changes,
+                                    ...(reported === null ? [FILTERED_EXIT_NOTE] : []),
+                                ];
                                 return {
-                                    stdout: sanitizeOutput(truncateMiddle(output, MAX_OUTPUT_SIZE)),
+                                    stdout,
                                     stderr: '',
-                                    exitCode: code,
+                                    exitCode: reported,
                                     ...(output.length > MAX_OUTPUT_SIZE ? { truncated: true, fullOutput: log } : {}),
-                                    ...(streaming.changes.length ? { note: streaming.changes.join(' ') } : {}),
+                                    ...(notes.length ? { note: notes.join(' ') } : {}),
                                 };
                             }
                             await new Promise((r) => setTimeout(r, 1_500));
@@ -1900,7 +2047,12 @@ export function buildTools(backend, config) {
                 // output and the clock in one place (cut-run.ts) so every reader of a run's verdict reads
                 // the same state (X1 xr-molecule-flash-m93: `timeout 280 hurl … | tail -60` came back
                 // `exitCode: 0` after 284 s and four of thirteen files, and the executor re-sent it).
-                const cut = commandCutRun(command, { exitCode: result.exitCode, stdout, stderr }, elapsedMs, budgetSeconds);
+                const cut = commandCutRun(command, { exitCode: result.exitCode, stdout, stderr }, elapsedMs, budgetSeconds, 
+                // Detection reads the RAW output: `truncateMiddle` keeps the head and the tail, and the
+                // runner's announcement (`Running 139 tests using 1 worker`) is the first line a long run
+                // prints — the one a size cap drops first. Only the counts and the tally come from here;
+                // what the result quotes is still the sanitized, truncated text.
+                `${result.stdout}\n${result.stderr}`);
                 if (cut) {
                     const cutLead = cutRunSentence(cut);
                     return {
@@ -1926,7 +2078,9 @@ export function buildTools(backend, config) {
                     stdout,
                     stderr,
                     exitCode: result.exitCode,
-                    ...(ceilingNote ? { note: ceilingNote } : {}),
+                    ...(ceilingNote || traced.change
+                        ? { note: [ceilingNote, traced.change].filter(Boolean).join(' ') }
+                        : {}),
                 };
             }
             catch (e) {
@@ -2092,9 +2246,19 @@ export function buildTools(backend, config) {
             // and then fixed it in 51 s. The task is NOT stopped — the executor is handed the cause and
             // decides, and the note tells it to let the run finish because the run's other causes only
             // surface in it (X1 flash-m83 stopped eight runs at their first repeating cause and never
-            // finished one). Only a cause that is failing the WHOLE run — every failure sharing it,
-            // across `UNIVERSAL_CAUSE_FILES` files or more, with nothing passing since the first —
-            // comes with a stop command.
+            // finished one).
+            //
+            // WHAT ENDS THIS WAIT is the whole of the executor's next move, so only ONE finding does:
+            // `earlyReturnCause` — a PROVEN cause (an error repeating verbatim, never a shared duration)
+            // that is failing the WHOLE run (every failure the log names, across `UNIVERSAL_CAUSE_FILES`
+            // files or more, with nothing passing since the first). Anything else is a LEAD: the wait
+            // keeps going to the caller's own timeout, and the finding is attached to the result of this
+            // wait as a note. X1 xr-molecule-flash-m99 (2026-10-16) was cut short twice by a status that
+            // returned early on three tests sharing the suite's own `timeout: 15_000` — a signature the
+            // note it printed called "a lead, not a cause" — and read the early return as "stop waiting,
+            // edit now", voiding a run that was still walking both times (the second wait, 224 s of a
+            // 280 s budget, ended with nothing at all).
+            let midRunNote = null;
             let lastCauseLookAt = startedAt - repeatingCauseLookMs();
             let exitCode = await readExit();
             while (exitCode === null && Date.now() - startedAt < budgetMs) {
@@ -2123,29 +2287,46 @@ export function buildTools(backend, config) {
                 const found = repeatingFailure(causeLog);
                 if (!found)
                     continue;
-                // Only a cause that is failing the whole run gets a stop command — and only then is the
-                // pid walk paid for.
-                const universal = universalCause(causeLog, found);
+                // The ONE predicate behind this decision and `repeatingFailureNote`'s wording, so the two
+                // cannot come to different verdicts.
+                const stopCause = earlyReturnCause(found, universalCause(causeLog, found));
                 // How this run was started, so the note can hand over the re-run to send once it ends
                 // instead of one for now — the platform refuses a second run against the same app and
                 // database while this one walks (xr-molecule-flash-m89: the +19:59 note named a re-run
                 // and its overlap hold refused that exact run 23 s later).
                 const started = runByTask.get(taskId);
-                repeatingCauseNoted.add(taskId);
-                const earlyMs = Date.now() - startedAt;
-                waitedByTask.set(taskId, waitedBefore + earlyMs);
-                return {
-                    taskId,
-                    status: 'repeating_failure',
-                    waitedMs: earlyMs,
-                    note: repeatingFailureNote(found, {
+                if (stopCause) {
+                    // …and only now is the pid walk paid for.
+                    repeatingCauseNoted.add(taskId);
+                    const earlyMs = Date.now() - startedAt;
+                    waitedByTask.set(taskId, waitedBefore + earlyMs);
+                    return {
+                        taskId,
+                        status: 'repeating_failure',
+                        waitedMs: earlyMs,
+                        note: repeatingFailureNote(found, {
+                            taskId,
+                            log,
+                            stop: await taskStopCommand(backend, taskId),
+                            universal: stopCause,
+                            ...(started ? { run: started } : {}),
+                        }),
+                    };
+                }
+                // A lead: this wait goes on, and the finding rides its result as a note — the executor has
+                // to keep waiting for the run's own result, so it must not be told one in the status. The
+                // look keeps running for the same reason: an app that goes down mid-run turns a shared
+                // duration into a proven whole-run cause, and that one is worth returning early for.
+                if (!midRunLeadNoted.has(taskId)) {
+                    midRunLeadNoted.add(taskId);
+                    midRunNote = repeatingFailureNote(found, {
                         taskId,
                         log,
-                        stop: universal ? await taskStopCommand(backend, taskId) : '',
-                        universal,
+                        stop: '',
+                        universal: null,
                         ...(started ? { run: started } : {}),
-                    }),
-                };
+                    });
+                }
             }
             const waitedMs = Date.now() - startedAt;
             waitedByTask.set(taskId, waitedBefore + waitedMs);
@@ -2188,6 +2369,13 @@ export function buildTools(backend, config) {
                     waitedMs: waitedBefore + waitedMs,
                 }));
                 const sliceField = soFar.trim() ? { outputSoFar: sanitizeOutput(soFar) } : {};
+                // What this wait found mid-run, when it was not a reason to end early: it rides the result
+                // the wait is about to hand back, because that result is where the executor decides what to
+                // do next and a lead it never saw is a lead it cannot weigh. Not on the `stuck` answer
+                // below — that verdict is about the command having stopped PRINTING and carries its own
+                // instruction — and not on a finished run's result, where `failureCausesNote` reads the
+                // whole log instead of the 40 KB tail a mid-run look is given.
+                const midRun = midRunNote ? ` ${midRunNote}` : '';
                 if (stillWriting && waitedBefore + waitedMs >= stuckAfterMs()) {
                     waitedByTask.set(taskId, 0);
                     return {
@@ -2196,7 +2384,7 @@ export function buildTools(backend, config) {
                         waitedMs,
                         ...sliceField,
                         note: `${progress} Call wait_for_task again to keep waiting; peek with exec_command: ` +
-                            `tail ${log}.`,
+                            `tail ${log}.${midRun}`,
                     };
                 }
                 if (waitedBefore + waitedMs >= stuckAfterMs()) {
@@ -2223,9 +2411,11 @@ export function buildTools(backend, config) {
                         (soFar.trim()
                             ? `outputSoFar is the failure lines so far (up to ${RUNNING_FAILURE_LINES}) and then the end of ` +
                                 `the log, not the whole run — \`grep -n '✘' ${log} | head -40\` lists every failure, ` +
-                                `\`grep -n -A 20 '<test name>' ${log}\` reads one failure's error. `
+                                `\`grep -n -A 20 '<test name>' ${log}\` reads one failure's error: this run writes ` +
+                                `each failure's own report into the log as that test fails, right under its ✘ line, ` +
+                                `not only in the summary at the end. `
                             : `Nothing has been printed yet — \`grep -n '✘' ${log} | head -40\` lists failures as they appear. `) +
-                        `Meanwhile do work that leaves the code under test alone (read the failures so far, plan the fixes): editing app/src or api/src now changes the code the run is testing, and its result no longer counts.`,
+                        `Meanwhile do work that leaves the code under test alone (read the failures so far, plan the fixes): editing app/src or api/src now changes the code the run is testing, and its result no longer counts.${midRun}`,
                 };
             }
             let output;
@@ -2257,16 +2447,27 @@ export function buildTools(backend, config) {
             // flash-m83 (2026-10-16) spent three deploys (6.7 minutes) each fixing a single cause, and
             // the second and third were found by runs stopped before they walked the rest. Null for
             // anything that is not a run with failures in it.
-            const causes = failureCausesNote(output);
+            // How this run was started, so the note can hand over the narrowed re-run of exactly its
+            // failing tests instead of leaving the executor to re-run the whole suite (xr-molecule-
+            // flash-m101 +12:13: 139 tests, ~4 minutes, to check two fixes).
+            const run = runByTask.get(taskId);
+            // The tests the request excludes are not causes to fix, and the re-run below inverts them
+            // out — a result must never ask the executor to fix a test it also says does not count.
+            // The log's own path rides along so a recap that leaves causes out can hand over the ONE
+            // grep that prints their bodies: the stdout above is cut in the middle, so the log is where
+            // they still are whole.
+            const causes = failureCausesNote(output, excludedTestTitles?.() ?? [], run ? { ...run, log: ownFile ?? log } : undefined);
             // A backgrounded run is under no tool budget, and the exit file hands back the PIPELINE's
             // code — so a suite killed at a `timeout 280` the command carried behind a `| tail` reports
             // 0 here too. The run's start is in its own id ({@link taskStartedAt}), so the bound it used
             // is readable without new state: say stopped, and never hand the pipeline's 0 back as the
             // run's (X1 xr-molecule-flash-m93 re-sent that run three times).
-            const run = runByTask.get(taskId);
             const startedAtMs = taskStartedAt(taskId);
             const cut = run && startedAtMs !== null
-                ? commandCutRun(run.command, { exitCode, stdout: output, stderr: '' }, Date.now() - startedAtMs, 0)
+                ? commandCutRun(run.command, { exitCode, stdout: output, stderr: '' }, Date.now() - startedAtMs, 0, 
+                // Same reason as the foreground path: the log is raw here, and the returned stdout
+                // below is the truncated copy — detection must not read that copy.
+                output)
                 : null;
             if (cut) {
                 return {
@@ -2281,12 +2482,19 @@ export function buildTools(backend, config) {
                 };
             }
             // Same shaping as a foreground exec result, so the executor reads both
-            // the same way.
+            // the same way. The exit file holds the PIPELINE's code: when a stage this rewrite could not
+            // prove is output-only still follows the suite runner (`| tee run.log`), that code is the
+            // filter's — report none and let the log's tally decide (m101 +25:54).
+            const piped = run ? suiteRunPipedAfterRunner(run.command) : false;
+            const reported = suiteRunExitCode(exitCode, output, piped);
+            const noCodeNote = reported === null ? FILTERED_EXIT_NOTE : null;
             return {
                 taskId,
-                exitCode,
+                exitCode: reported,
                 waitedMs,
-                ...(causes ? { note: causes } : {}),
+                ...(causes || noCodeNote
+                    ? { note: [causes, noCodeNote].filter((n) => Boolean(n)).join(' ') }
+                    : {}),
                 stdout: sanitizeOutput(truncateMiddle(output, MAX_OUTPUT_SIZE)),
                 ...(output.length > MAX_OUTPUT_SIZE ? { truncated: true, fullOutput: log } : {}),
             };