@molecule/api-ai-tools 1.6.6 → 1.7.0

package/dist/tools.js

@@ -52,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.
@@ -209,7 +221,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, 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 +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.
  *
@@ -1080,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 = [];
@@ -1112,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
@@ -1136,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
@@ -1154,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
@@ -1174,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
@@ -1193,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 = [
@@ -1233,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
@@ -1271,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
@@ -1283,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
@@ -1294,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
@@ -1323,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
@@ -1352,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
@@ -1687,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
@@ -1697,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
@@ -1759,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
@@ -1926,7 +2031,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 +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) {
@@ -2123,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);
@@ -2188,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 {
@@ -2196,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()) {
@@ -2223,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;

package/dist/trace-artifacts.d.ts

@@ -0,0 +1,147 @@
+/**
+ * What a failed Playwright run's own trace files say about the requests its page made — read
+ * headlessly, in the sandbox, from the `trace.zip` files the run left behind.
+ *
+ * X1 xr-molecule-flash-m100 (+51:19 → +53:00, 2026-10-16) ended with three failures against the
+ * deployed URL — `social.spec.ts:22` and `:153` waited for a "Unfollow" button that never appeared
+ * after the click, and `url-navigation.spec.ts:234` was bounced to `/login` mid-test — and nothing
+ * in the run's result said why. The app's own `toggleFollow` swallowed the error of its request
+ * with a bare `catch` and a comment, so the page showed nothing; the ONE artifact
+ * that held the answer, the failing tests' own traces, was never read. The executor spent the
+ * last minutes of the run writing throwaway Chromium probes against localhost — where the same
+ * tests passed — and finished chasing an artifact of its own probe
+ * (`waitForURL('/')` resolved against a `baseURL` its script did not have).
+ *
+ * A trace is not a debugging aid that has to be enabled by hand: Playwright writes the request
+ * log and the console into `test-results/<test>/trace.zip` whenever a run retains traces, and the
+ * evidence a swallowed failure hides is exactly one line of it — `POST /api/articles/x/favorite →
+ * 401`. So the platform reads it (bounded, per test) and puts it in the run's result
+ * ({@link failureTraceNote}), instead of leaving the executor to build its own browser to find out.
+ *
+ * Everything here is text in, text out: the sandbox runs {@link traceArtifactsScript} (Node, no
+ * dependencies — Playwright's zip reader is not importable from a project) and prints one
+ * `TRACE <json>` line per trace; the platform parses those lines ({@link parseTraceArtifacts}) and
+ * writes the note ({@link failureTraceNote}). Both halves are covered by a test that runs the
+ * script against a `trace.zip` produced by a real Playwright run, in the sandbox's own shape.
+ *
+ * @module
+ */
+/** One request a traced page made, as `*.network` records it. */
+export interface TraceRequest {
+    /** The HTTP method (`POST`). */
+    method: string;
+    /** The request's path (`/api/articles/x/favorite`), or the whole URL when it is cross-origin. */
+    path: string;
+    /** The response status, or 0 when the request never got a response. */
+    status: number;
+}
+/** What one trace says: the test it belongs to, the requests it made, and its console errors. */
+export interface TraceArtifact {
+    /** The failure's spec file, relative to the run's directory, when the trace names one. */
+    spec: string | null;
+    /** The line of the test's last traced step, 0 when the trace names no spec. */
+    line: number;
+    /** The requests the page made, the interesting ones first ({@link traceArtifactsScript}). */
+    requests: TraceRequest[];
+    /** The console errors and page errors the page raised. */
+    console: string[];
+}
+/** How many traces one read reports, newest first. */
+export declare const MAX_TRACE_ARTIFACTS = 12;
+/** How many requests one test's trace contributes. */
+export declare const MAX_TRACED_REQUESTS = 6;
+/** How many console errors one test's trace contributes. */
+export declare const MAX_TRACED_CONSOLE = 4;
+/** How many tests the note in a run's result names. */
+export declare const MAX_TRACE_NOTE_TESTS = 5;
+/** How many requests the note names per test. */
+export declare const MAX_TRACE_NOTE_REQUESTS = 4;
+/** How long a URL the note prints, before the middle is cut. */
+export declare const TRACE_NOTE_URL_CHARS = 96;
+/**
+ * The Node program the sandbox runs to read a failed run's traces: `node <script> <dir>` prints one
+ * `TRACE <json>` line per `trace.zip` under `<dir>` (newest first, {@link MAX_TRACE_ARTIFACTS} of
+ * them), each with the test it belongs to, the requests its page made and its console errors.
+ *
+ * It is a standalone program, not an import, for the reason `@molecule/api-code-sandbox` runs it:
+ * Playwright's own zip reader is not reachable from a project's `node_modules`, and a dependency
+ * on `unzip` would make the read fail on every sandbox that has none. The zip is read with the
+ * central directory and `zlib.inflateRawSync` — about forty lines, and the only thing that has to
+ * be true of a `trace.zip` is that it IS one.
+ *
+ * A request is kept over a static asset when it failed (`status >= 400`) or never answered
+ * (`status === 0`), and over anything else when it is the page talking to the app
+ * (`fetch`/`xhr`/`document`): a failing test's trace holds the whole page load, and the answer is
+ * always at the end of it.
+ *
+ * @returns The program's source, to write to a file and run.
+ */
+export declare const traceArtifactsScript: () => string;
+/**
+ * The traces {@link traceArtifactsScript} printed, parsed.
+ *
+ * A line that is not a complete `TRACE <json>` (a truncated read, a program that died mid-write) is
+ * dropped: a partial trace is not evidence about the test it came from.
+ *
+ * @param stdout - The program's output.
+ * @returns One entry per trace it printed.
+ */
+export declare function parseTraceArtifacts(stdout: string): TraceArtifact[];
+/**
+ * The note a failed suite run's result carries: what each failing test's page actually sent, and
+ * what came back.
+ *
+ * This is the answer to the question a swallowed error hides — a click that changed nothing is
+ * usually a request that failed — so the note leads with the failing requests and says what to do
+ * with them: read the handler the route reaches, not the selector. It is BOUNDED to
+ * {@link MAX_TRACE_NOTE_TESTS} tests with {@link MAX_TRACE_NOTE_REQUESTS} requests each, because it
+ * rides in a result the model pays for.
+ *
+ * @param items - The traces {@link parseTraceArtifacts} read.
+ * @param target - Where the run went — the deployed host, as the note names it.
+ * @returns The note, or null when no trace held a request or a console error.
+ */
+export declare function failureTraceNote(items: readonly TraceArtifact[], target: string): string | null;
+/**
+ * Whether a Playwright config records traces for the tests that fail.
+ *
+ * Only `on` and `retain-on-failure` keep a `trace.zip` for a failure whatever the retries do: the
+ * two retry modes need a retry to happen at all, and a diagnosis run is given `--retries=0`
+ * (`streamingBackgroundCommand`), so on X1 xr-molecule-flash-m100 the run's own
+ * `trace: 'on-first-retry'` recorded nothing — which is what left the failing tests' network log
+ * unreadable. A config that sets no `trace:` at all records nothing either (Playwright's default
+ * is off); so does one that cannot be read.
+ *
+ * @param configText - The config's source, or '' when none could be read.
+ * @returns True when the config records traces for failures.
+ */
+export declare function suiteRecordsTraces(configText: string): boolean;
+/** The `--trace` flag this platform adds, and the only value it adds it with. */
+export declare const DIAGNOSIS_TRACE_FLAG = "--trace=retain-on-failure";
+/** A command with the trace flag this platform decided to add, and the sentence to report it in. */
+export interface DiagnosisTraceRewrite {
+    /** The command to run. */
+    command: string;
+    /** One sentence naming the flag and why, or null when nothing was added. */
+    change: string | null;
+}
+/**
+ * The command a DIAGNOSIS run needs to leave a readable trace behind, when the suite's config
+ * would record none.
+ *
+ * The failing tests' requests are only readable if the run wrote them down (see the module doc),
+ * and the config is where the decision about that lives — the platform does not edit the suite's
+ * config, so it passes the flag instead, and only where it can do no harm: on a run narrowed to a
+ * part of the suite or capped ({@link isDiagnosisRun}), never on the whole-suite proof run, and
+ * never over a `--trace` the executor wrote itself. A capped walk is exactly the run whose
+ * failures someone is about to work on; the proof run is graded as it is.
+ *
+ * @param args - The command, the directory it starts in, and the backend's file read.
+ * @returns The command to run and the sentence to report, or the command unchanged.
+ */
+export declare function diagnosisTraceCommand(args: {
+    command: string;
+    cwd: string;
+    readFile: (path: string) => Promise<string>;
+}): Promise<DiagnosisTraceRewrite>;
+//# sourceMappingURL=trace-artifacts.d.ts.map

package/dist/trace-artifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-artifacts.d.ts","sourceRoot":"","sources":["../src/trace-artifacts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAKH,iEAAiE;AACjE,MAAM,WAAW,YAAY;IAC3B,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAA;IACd,iGAAiG;IACjG,IAAI,EAAE,MAAM,CAAA;IACZ,uEAAuE;IACvE,MAAM,EAAE,MAAM,CAAA;CACf;AAED,iGAAiG;AACjG,MAAM,WAAW,aAAa;IAC5B,0FAA0F;IAC1F,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAA;IACZ,6FAA6F;IAC7F,QAAQ,EAAE,YAAY,EAAE,CAAA;IACxB,0DAA0D;IAC1D,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB;AAED,sDAAsD;AACtD,eAAO,MAAM,mBAAmB,KAAK,CAAA;AAErC,sDAAsD;AACtD,eAAO,MAAM,mBAAmB,IAAI,CAAA;AAEpC,4DAA4D;AAC5D,eAAO,MAAM,kBAAkB,IAAI,CAAA;AAEnC,uDAAuD;AACvD,eAAO,MAAM,oBAAoB,IAAI,CAAA;AAErC,iDAAiD;AACjD,eAAO,MAAM,uBAAuB,IAAI,CAAA;AAExC,gEAAgE;AAChE,eAAO,MAAM,oBAAoB,KAAK,CAAA;AAEtC;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,oBAAoB,QAAO,MA+LvC,CAAA;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,EAAE,CAyBnE;AAiBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA4B/F;AAaD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAG9D;AAED,iFAAiF;AACjF,eAAO,MAAM,oBAAoB,8BAA8B,CAAA;AAuE/D,oGAAoG;AACpG,MAAM,WAAW,qBAAqB;IACpC,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAA;IACf,4EAA4E;IAC5E,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CACtB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE;IAChD,OAAO,EAAE,MAAM,CAAA;IACf,GAAG,EAAE,MAAM,CAAA;IACX,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;CAC5C,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAgBjC"}