@molecule/api-ai-tools 1.6.5 → 1.7.0

package/dist/tools.js

@@ -6,6 +6,7 @@
  *
  * @module
  */
+import { commandCutRun, CUT_AT_BUDGET, cutRunSentence } 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';
@@ -51,8 +52,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.
@@ -208,12 +221,44 @@ function runningNote(clauses) {
     const joined = clauses.join('; ');
     return `${joined[0].toUpperCase()}${joined.slice(1)}.`;
 }
-import { checkBlockedCommand, declaredBudgetSeconds, DEFAULT_SEARCH_EXCLUDED_DIRS, directoryReadHint, emptyCallError, failureCausesNote, findPatternArgs, fusedLine, htmlOutline, isEnvFilePath, isOutsideRoot, isPlaywrightRunCommand, isValidGlob, linesWithinSerialized, 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, 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, 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.
  */
 const OVER_CEILING_GRACE_MS = 45_000;
+/**
+ * The closing advice on an over-budget message for a command that is not a test
+ * suite: the work it was chaining is what to split.
+ */
+export const SPLIT_WORK_ADVICE = 'Run a smaller unit per command (one test file, one build step) instead of chaining ' +
+    'a build and a whole suite.';
+/**
+ * The closing advice on an over-budget message for a command that IS a suite run
+ * (Playwright, Vitest, a `hurl` run — {@link isSuiteRunCommand}): its files are not
+ * a bigger unit to break up.
+ *
+ * X1 flash-m36 asked for this half and the message kept saying "run a smaller unit"
+ * for two months. It is the wrong direction for a suite, and measurably: a run
+ * stopped here reports NO tally, so nothing in the result says which test or request
+ * hung — the run has to be sent again in the background (off this budget, its output
+ * written to a log that can be read mid-run) or, when a consumer knows the runner's
+ * per-request limit, with each request bounded. xr-molecule-flash-m93 (+06:22,
+ * 2026-10-16) lost 4.8 minutes to a Hurl run whose ONE unanswered request had hurl's
+ * 300 s default per request holding the file, ten seconds past this tool's budget.
+ */
+export const SUITE_OVER_BUDGET_ADVICE = 'A test suite is not a bigger unit to split: stopped here it reports no tally at all, so nothing ' +
+    'in this result says which test or request never finished — run it in the background ' +
+    '(`run_in_background`, then `wait_for_task`), which takes it off this budget and writes its output ' +
+    "to a log, and read that log (or the app's own log) for what it was waiting on.";
+/**
+ * How long a tree walk (`find_files`, `search_files`) may run before the backend's
+ * own deadline stops it. Both tools answer that deadline in their own words
+ * (see searchTimeoutError) rather than forwarding the sandbox SDK's `timeoutMs`
+ * sentence, which names an option the executor cannot set.
+ */
+const SEARCH_TIMEOUT_MS = 10_000;
 /**
  * The share of its budget a command must use before the "you asked for more than
  * this tool's ceiling" note is worth attaching. Below it the clamp changed nothing
@@ -290,6 +335,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.
  *
@@ -1048,6 +1127,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 = [];
@@ -1080,9 +1166,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
@@ -1104,9 +1193,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
@@ -1122,9 +1214,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
@@ -1142,9 +1237,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
@@ -1161,12 +1254,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 = [
@@ -1201,13 +1297,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
@@ -1239,10 +1333,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
@@ -1251,8 +1357,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
@@ -1262,20 +1374,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
@@ -1291,9 +1403,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
@@ -1320,6 +1435,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
@@ -1484,7 +1606,7 @@ export function buildTools(backend, config) {
                 // -H: a search scoped to one file printed `line:content` with no file, and every match
                 // came back `{file: "", line: 0}` (X1 flash-m62).
                 const grepArgs = `-rnH ${globArg} ${contextArg} ${grepExcludeArgs(path)} --max-count=${MAX_SEARCH_RESULTS} -- ${shellQuote(pattern)} ${shellQuote(path)}`;
-                const result = await backend.run(`{ grep -E ${grepArgs}; s=$?; if [ "$s" -eq 2 ]; then grep -F ${grepArgs}; fi; } 2>/dev/null || true`, { timeout: 10000 });
+                const result = await backend.run(`{ grep -E ${grepArgs}; s=$?; if [ "$s" -eq 2 ]; then grep -F ${grepArgs}; fi; } 2>/dev/null || true`, { timeout: SEARCH_TIMEOUT_MS });
                 // grep emits `<file>:<line>:<content>`, so redaction runs PER MATCH on the
                 // content alone: the file prefix would otherwise hide an env assignment from
                 // the line-anchored env pattern, and knowing each match's own path is what
@@ -1521,6 +1643,11 @@ export function buildTools(backend, config) {
                 return { pattern, path, matches };
             }
             catch (e) {
+                if (isCommandTimeout(e))
+                    return {
+                        error: searchTimeoutError('search_files', path, pattern, SEARCH_TIMEOUT_MS / 1000, `Give \`path\` the subdirectory you mean and narrow with \`include\` ` +
+                            `(e.g. "*.ts"), or use find_files with the directory in the pattern.`),
+                    };
                 return { error: `Search failed: ${e.message}` };
             }
         },
@@ -1542,21 +1669,54 @@ export function buildTools(backend, config) {
             const symlinkErr = await checkSymlink(path);
             if (symlinkErr)
                 return { error: symlinkErr };
+            // The directory the PATTERN itself names (`node_modules` +
+            // `@molecule/api-resource-user/dist/*.d.ts`) becomes the search root. Matched
+            // against the whole path with an implicit "any parent" anchor, the pattern
+            // made `find` visit every entry below `path` — the whole dependency tree,
+            // which hit the 10 s deadline with no result at all while the one directory
+            // the model meant answered a `list_files` instantly (xr-molecule-flash-m94).
+            // A bare first segment (`helpers/*`) is left alone on purpose: it means "any
+            // `helpers/` below the root" (xr-molecule-flash-m77, see literalDirPrefix).
+            const prefixDir = literalDirPrefix(pattern);
+            let findRoot = path;
+            let findArgs = findPatternArgs(pattern);
+            let missingPrefix;
             try {
+                if (prefixDir) {
+                    const candidate = `${path.replace(/\/+$/, '')}/${prefixDir}`;
+                    const probe = await backend.run(`test -d ${shellQuote(candidate)}`, {
+                        timeout: SEARCH_TIMEOUT_MS,
+                    });
+                    if (probe.exitCode === 0) {
+                        findRoot = candidate;
+                        // The remainder keeps the `-path` form: `*` crosses `/`, so a `.d.ts`
+                        // in `dist/utilities/` is still found (see findPathArgs).
+                        findArgs = findPathArgs(pattern.replace(/^(?:\.?\/)+/, '').slice(prefixDir.length + 1));
+                    }
+                    else {
+                        missingPrefix = `"${candidate}" does not exist; searched all of ${path}.`;
+                    }
+                }
                 // `findPatternArgs`, not `-name`: a pattern with a `/` in it
                 // (`helpers/*`, `e2e/*.spec.ts`) matched nothing at all, because `-name`
                 // compares it against the basename (xr-molecule-flash-m77).
-                const result = await backend.run(`find ${shellQuote(path)} ${findPruneArgs(path)} ${findPatternArgs(pattern)} -print 2>/dev/null | head -${MAX_FIND_RESULTS}`, { timeout: 10000 });
+                const result = await backend.run(`find ${shellQuote(findRoot)} ${findPruneArgs(findRoot)} ${findArgs} -print 2>/dev/null | head -${MAX_FIND_RESULTS}`, { timeout: SEARCH_TIMEOUT_MS });
                 const files = result.stdout.trim().split('\n').filter(Boolean);
                 // A slash changes what the pattern means — the whole path, not the file
                 // name — and an empty result does not say so, so the model reads it as
                 // "no such file" and goes looking elsewhere. Name the rule on the miss.
-                const note = files.length === 0 && pattern.includes('/')
+                const missNote = files.length === 0 && pattern.includes('/')
                     ? `"${pattern}" contains a "/", so it was matched against each file's PATH below ${path} (a leading "*/" is implicit), not against the file name — no path matched it. list_files shows the real entries.`
                     : undefined;
-                return { pattern, path, files, ...(note ? { note } : {}) };
+                const notes = [missingPrefix, missNote].filter((n) => Boolean(n));
+                return { pattern, path, files, ...(notes.length ? { note: notes.join(' ') } : {}) };
             }
             catch (e) {
+                if (isCommandTimeout(e))
+                    return {
+                        error: searchTimeoutError('find_files', findRoot === path ? path : `${findRoot} (under ${path})`, pattern, SEARCH_TIMEOUT_MS / 1000, `Give \`path\` the directory you mean (a package's own folder rather than all of ` +
+                            `${path}) or use list_files on it, and keep the pattern narrow.`),
+                    };
                 return { error: `Find failed: ${e.message}` };
             }
         },
@@ -1617,7 +1777,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
@@ -1627,21 +1787,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
@@ -1689,6 +1860,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
@@ -1825,25 +2000,40 @@ export function buildTools(backend, config) {
                     : sanitizeOutput;
                 const stdout = grade(truncateMiddle(result.stdout, MAX_OUTPUT_SIZE));
                 const stderr = sanitizeOutput(truncateMiddle(result.stderr, MAX_OUTPUT_SIZE));
-                if (budgetSeconds && result.exitCode === 124) {
+                // A run a budget stopped is NOT a run that ended: it reports `status: 'cut_at_budget'`,
+                // never a 0 the pipeline produced, and names how far it got. Read from the command, the
+                // 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);
+                if (cut) {
+                    const cutLead = cutRunSentence(cut);
                     return {
                         stdout,
                         stderr,
-                        exitCode: result.exitCode,
-                        error: `The command was stopped after ${budgetSeconds}s, this tool's limit; the output above is ` +
-                            'everything it printed until then' +
-                            (/\|\s*(tail|head)\b/.test(command)
-                                ? ' — and a pipe through tail/head holds everything back until the command ends, so it printed nothing: run it without the pipe (use a line reporter and let the output stream)'
+                        status: CUT_AT_BUDGET,
+                        exitCode: cut.exitCode,
+                        // The facts, so a reader that can also see the suite itself (its own `.hurl` file
+                        // count) says the same sentence with the total the output alone cannot give.
+                        cutRun: cut,
+                        error: `${cutLead} ` +
+                            // The tool's own budget stopping a run that printed nothing: keep the sentence that
+                            // says why the output is empty, since nothing else in the result can say it.
+                            (cut.stoppedBy === 'tool-budget'
+                                ? `The output above is everything it printed until then${/\|\s*(tail|head)\b/.test(command)
+                                    ? ' — and a pipe through tail/head holds everything back until the command ends, so it printed nothing: run it without the pipe (use a line reporter and let the output stream)'
+                                    : ''}. `
                                 : '') +
-                            '. Run a smaller unit per command (one test file, one build step) instead of chaining ' +
-                            'a build and a whole suite.',
+                            (isSuiteRunCommand(command) ? SUITE_OVER_BUDGET_ADVICE : SPLIT_WORK_ADVICE),
                     };
                 }
                 return {
                     stdout,
                     stderr,
                     exitCode: result.exitCode,
-                    ...(ceilingNote ? { note: ceilingNote } : {}),
+                    ...(ceilingNote || traced.change
+                        ? { note: [ceilingNote, traced.change].filter(Boolean).join(' ') }
+                        : {}),
                 };
             }
             catch (e) {
@@ -2009,9 +2199,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) {
@@ -2040,29 +2240,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);
@@ -2105,6 +2322,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 {
@@ -2113,7 +2337,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()) {
@@ -2140,9 +2364,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;
@@ -2175,6 +2401,28 @@ export function buildTools(backend, config) {
             // 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);
+            // 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)
+                : null;
+            if (cut) {
+                return {
+                    taskId,
+                    status: CUT_AT_BUDGET,
+                    exitCode: cut.exitCode,
+                    waitedMs,
+                    cutRun: cut,
+                    note: [cutRunSentence(cut), causes].filter((n) => Boolean(n)).join(' '),
+                    stdout: sanitizeOutput(truncateMiddle(output, MAX_OUTPUT_SIZE)),
+                    ...(output.length > MAX_OUTPUT_SIZE ? { truncated: true, fullOutput: log } : {}),
+                };
+            }
             // Same shaping as a foreground exec result, so the executor reads both
             // the same way.
             return {