@molecule/api-ai-tools 1.8.2 → 1.9.1

package/dist/tools.js

@@ -10,6 +10,7 @@ import { commandCutRun, CUT_AT_BUDGET, cutRunSentence, suiteRunExitCode } from '
 import { addChangeSpan, changedSpan, countLines, renderEditExcerpt, renderSmallFile, } from './edit-excerpt.js';
 import { guardToolExecute, missingParamError, ToolInputError } from './input-normalizer.js';
 import { TOOL_SCHEMAS } from './schemas.js';
+import { leadingSleepPeek } from './sleep-peek.js';
 /**
  * Total waiting, per background task, after which wait_for_task reports it
  * stuck instead of waiting again. Env-tunable so a test can exercise it.
@@ -44,6 +45,36 @@ const runByTask = new Map();
 const FILTERED_EXIT_NOTE = 'No exit code is reported for this run: a stage after the test runner produced the pipeline’s ' +
     'code (or the code says 0 beside a failure in the tally), so read the pass/fail tally in the ' +
     'log instead.';
+/**
+ * What a finished run says when its suite sits inside a `sh -c '<command>'` string: the stages are
+ * positions in THAT string, so the platform cannot point at one in the command's own text. Said
+ * instead of {@link FILTERED_EXIT_NOTE} — that note names a stage after the runner, and this run
+ * cannot be read as having one; a command with nothing piped after the runner keeps its code.
+ */
+const UNPLACED_KEPT_NOTE = 'The suite sits inside a `sh -c` string, so its stages cannot be placed in the command’s own ' +
+    'text; nothing follows the runner there, so the exit code above is the run’s own — read the ' +
+    'pass/fail tally in the log for the verdict.';
+/** {@link UNPLACED_KEPT_NOTE} when between them a stage after the runner produced the code. */
+const UNPLACED_PIPED_NOTE = 'The suite sits inside a `sh -c` string, so its stages cannot be placed in the command’s own ' +
+    'text, and a stage after the runner may have produced the pipeline’s code: none is reported, ' +
+    'so read the pass/fail tally in the log instead.';
+/**
+ * The sentence a finished suite run's result carries about its exit code, or null when the code it
+ * reports is the run's own and needs no explanation.
+ *
+ * {@link FILTERED_EXIT_NOTE} names a stage after the runner, so it is said only when the parse
+ * found one; a run whose stages cannot be placed says THAT instead, and keeps the command's own
+ * code when nothing follows the runner.
+ *
+ * @param placement - Where the code came from ({@link suiteRunPipelinePlacement}).
+ * @param reported - The code the result reports, or null when it reports none.
+ * @returns The note, or null.
+ */
+function suiteExitCodeNote(placement, reported) {
+    if (placement.unplaced)
+        return reported === null ? UNPLACED_PIPED_NOTE : UNPLACED_KEPT_NOTE;
+    return reported === null ? FILTERED_EXIT_NOTE : null;
+}
 /**
  * Task ids whose own-output file has already been looked for this process.
  * {@link outputFileByTask} is empty for every task after a restart — it is
@@ -229,8 +260,106 @@ function runningNote(clauses) {
     const joined = clauses.join('; ');
     return `${joined[0].toUpperCase()}${joined.slice(1)}.`;
 }
+/**
+ * The background task a leading `sleep` was about to peek at, and its state now — or null when the
+ * command has no task of this process's to report, in which case the sleep runs as written (the
+ * tool's own budget bounds it, as before).
+ *
+ * X1 xr-molecule-flash-m105 (+08:49 → +10:53, 2026-10-17) hand-polled with `sleep N; tail …`
+ * three times. The state the executor wanted was always one the platform already held: two tasks
+ * had ended 0.1 s in (exit 127, and `Error: No tests found`) and the third was live at 72 of 139
+ * with failures the log already carried. So a command that opens with a long sleep is answered
+ * from the same reads `wait_for_task` makes — the exit file, and the failure-lines-plus-tail slice
+ * of the log — and the sleep is dropped.
+ *
+ * The command names WHAT it is peeking at (`/tmp/<id>.log`, or the file the task redirects its own
+ * output to), and that task is the answer whether it has ended or not: the two dead peeks are
+ * exactly this shape. With no name to follow, the newest LIVE task is the answer — the point of
+ * the rule is that a sleep never outlives a run it could have been waiting on — and with no live
+ * task there is nothing to report.
+ *
+ * @param backend - The execution backend the task runs on.
+ * @param command - The command whose leading sleep is being replaced.
+ * @param seconds - The seconds that leading sleep asked for.
+ * @param ceilingMs - The wait ceiling a `wait_for_task` would have, so the ETA it states is the
+ *   one an actual wait would act on.
+ * @returns One sentence naming the task's state and how to get its result, plus the log slice the
+ *   caller attaches as `outputSoFar`; null when no task answers this command.
+ */
+async function backgroundTaskState(backend, command, seconds, ceilingMs) {
+    const ids = [...runByTask.keys()];
+    if (!ids.length)
+        return null;
+    const exitCodeOf = async (id) => {
+        try {
+            const raw = await backend.readFile(`/tmp/${id}.exit`);
+            const code = Number.parseInt(raw.trim(), 10);
+            return Number.isFinite(code) ? code : 0;
+        }
+        catch (_error) {
+            // No exit file yet: the task is still running. Not an error.
+            return null;
+        }
+    };
+    const names = (id) => {
+        if (command.includes(`/tmp/${id}.log`))
+            return true;
+        const own = outputFileByTask.get(id);
+        return own !== undefined && command.includes(own);
+    };
+    const newestFirst = [...ids].reverse();
+    const namedId = newestFirst.find(names);
+    let target = namedId
+        ? { id: namedId, exitCode: await exitCodeOf(namedId) }
+        : null;
+    if (!target) {
+        // Bounded: a long session can leave many finished tasks behind, and each look costs a read.
+        for (const id of newestFirst.slice(0, 8)) {
+            const exitCode = await exitCodeOf(id);
+            if (exitCode === null) {
+                target = { id, exitCode };
+                break;
+            }
+        }
+    }
+    if (!target)
+        return null;
+    let slice = '';
+    try {
+        const r = await backend.run(runningOutputSliceCommand(`/tmp/${target.id}.log`, outputFileByTask.get(target.id)), { timeout: 5_000 });
+        slice = r.stdout ?? '';
+    }
+    catch (_error) {
+        // No slice: the note still says the task's state and how to get its result.
+    }
+    const secondsText = `Did not sleep ${Math.round(seconds)} s: background task \`${target.id}\``;
+    if (target.exitCode === null) {
+        const facts = waitProgressClauses({
+            taskId: target.id,
+            slice,
+            stillWriting: false,
+            bytes: null,
+            ceilingMs,
+            waitedMs: 0,
+        });
+        const failures = slice.trim() ? '; the failures already in its log are in outputSoFar' : '';
+        return {
+            note: `${secondsText} is live (${facts.join('; ')})${failures} — ` +
+                `\`wait_for_task ${target.id}\` returns its result the moment it ends.`,
+            slice,
+        };
+    }
+    const counter = logProgress(slice);
+    const progress = counter ? `, at ${counter.done} of ${counter.total} in its log` : '';
+    const failures = slice.trim() ? '; the failures in its log are in outputSoFar' : '';
+    return {
+        note: `${secondsText} had already ended (exit code ${target.exitCode})${progress}${failures} — ` +
+            `\`wait_for_task ${target.id}\` returns its result now.`,
+        slice,
+    };
+}
 import { diagnosisTraceCommand } from './trace-artifacts.js';
-import { checkBlockedCommand, declaredBudgetSeconds, DEFAULT_SEARCH_EXCLUDED_DIRS, directoryReadHint, earlyReturnCause, emptyCallError, failureCausesNote, findPathArgs, findPatternArgs, fusedLine, htmlOutline, isCommandTimeout, isEnvFilePath, isOutsideRoot, isPlaywrightRunCommand, isSuiteRunCommand, isValidGlob, linesWithinSerialized, literalDirPrefix, MAX_BATCH_READ_FILES, MAX_FIND_RESULTS, MAX_HTML_INLINE_CHARS, MAX_OUTPUT_SIZE, MAX_READ_CALL_CHARS, MAX_READ_RETURN_CHARS, MAX_READ_SIZE, MAX_SEARCH_CONTEXT_LINES, MAX_SEARCH_RESULTS, MAX_WRITE_SIZE, outputIsWithheldUntilExit, outputRedirectTarget, parseCheckCommand, parseCheckProblem, pathArgError, printsOnlySource, READ_RESULT_ENVELOPE_CHARS, redactSecrets, redactSecretsInCode, repeatingFailure, repeatingFailureNote, resolvePath, RUNNING_FAILURE_LINES, runningCauseCommand, runningOutputSliceCommand, searchTimeoutError, serializedChars, shellQuote, sliceLines, SMALL_FILE_WHOLE_CHARS, streamingBackgroundCommand, stripControlChars, suiteRunPipedAfterRunner, suiteRunPriorityLaunch, truncateMiddle, universalCause, whitespaceTolerantReplace, } from './utilities.js';
+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, suiteRunPipelinePlacement, 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.
@@ -298,8 +427,51 @@ export function moleculeDistReadNote(path) {
             : ' For one signature, read the matching .d.ts file.'));
 }
 /**
- * The refusal for a write whose target is inside an installed package, or null
- * when the path is not under a `node_modules` directory.
+ * The `node_modules` entry a path goes through, and the package name after it
+ * (`null` when the path IS the entry).
+ *
+ * @param path - An absolute path.
+ * @returns The entry and the name, or null when no `node_modules` component is in the path.
+ */
+function nodeModulesParts(path) {
+    // A path may sit in a NESTED node_modules (`app/node_modules/...`) as well as the
+    // hoisted root one: both can be installed trees.
+    const at = /(?:^|\/)node_modules(?:\/|$)/.exec(path);
+    if (!at)
+        return null;
+    const head = path.slice(0, at.index);
+    const entry = `${head}${head === '' || head.endsWith('/') ? '' : '/'}node_modules`;
+    const named = /node_modules\/((?:@[^/]+\/)?[^/]+)(?:\/|$)/.exec(path.slice(at.index));
+    return { entry, name: named?.[1] ?? null };
+}
+/**
+ * Build an {@link InstalledPackageProbe} from a shell runner (a backend's
+ * `run`, or a sandbox's `exec`): one command reports whether the entry is a
+ * link and whether a `package.json` resolves under it.
+ *
+ * @param run - Runs a command where the path lives.
+ * @returns The probe.
+ */
+export function shellInstalledPackageProbe(run) {
+    return async (path) => {
+        const parts = nodeModulesParts(path);
+        if (!parts)
+            return { symlink: false, installed: false };
+        const { entry, name } = parts;
+        // A bare `@scope` is not a package, but removing it takes every package under
+        // it: treat the scope directory like the entry itself and look beneath it.
+        const scopeOnly = name !== null && /^@[^/]+$/.test(name);
+        const install = name !== null && !scopeOnly
+            ? `if [ -e ${shellQuote(`${entry}/${name}/package.json`)} ]; then echo installed; fi`
+            : `if find ${shellQuote(name === null ? entry : `${entry}/${name}`)} -maxdepth 3 -name package.json -print -quit 2>/dev/null | grep -q .; then echo installed; fi`;
+        const out = String((await run(`if [ -L ${shellQuote(entry)} ]; then echo symlink; fi; ${install}`))?.stdout ??
+            '');
+        return { symlink: out.includes('symlink'), installed: out.includes('installed') };
+    };
+}
+/**
+ * The refusal for a write whose target is inside an INSTALLED package, or null
+ * when the path is not under `node_modules` or nothing is installed there.
  *
  * `node_modules` is not the project's code: nothing written there survives the
  * next install, no deploy carries it, and a sandbox whose dependency tree is
@@ -312,6 +484,19 @@ export function moleculeDistReadNote(path) {
  * putting the file back. Reading these files stays allowed (that is how the
  * declarations above are read at all).
  *
+ * What is protected is the INSTALL, not the spelling: the decision comes from
+ * {@link InstalledPackageFacts}, never from the path alone (m106 above). Three
+ * things are the run's own to remove or replace —
+ *
+ * - a `node_modules` that is a SYMLINK: `rm`/`unlink` removes the link, never the
+ *   tree it points at, so a link the run made cannot clobber anything;
+ * - anything under the run's own `.mol-scratch/` directory;
+ * - a `node_modules` with no `package.json` under it (nothing was ever installed).
+ *
+ * A path INSIDE the link is still decided by what resolves there: a link into a
+ * real tree is refused, because removing or writing through it reaches the
+ * install.
+ *
  * The restore route is named because the model that has ALREADY clobbered a file
  * (this refusal is too late for it) is the one who needs it, and because the
  * obvious repair — `npm install <pkg>` — is itself refused in the pre-installed
@@ -319,19 +504,34 @@ export function moleculeDistReadNote(path) {
  * m91 used, and what both guards leave alone.
  *
  * @param path - An absolute path a tool is about to write.
+ * @param probe - Looks at the filesystem where the path lives.
  * @returns The one-line refusal naming the package, or null when nothing is installed there.
  */
-export function installedPackageWriteRefusal(path) {
-    // A path may sit in a NESTED node_modules (`app/node_modules/...`) as well as the
-    // hoisted root one: both are installed packages.
-    const at = /(?:^|\/)node_modules(?:\/|$)/.exec(path);
-    if (!at)
+export async function installedPackageWriteRefusal(path, probe) {
+    const parts = nodeModulesParts(path);
+    if (!parts)
         return null;
-    const named = /(?:^|\/)node_modules\/((?:@[^/]+\/)?[^/]+)(?:\/|$)/.exec(path);
-    const name = named?.[1] ?? null;
-    const scoped = at[0].startsWith('/') ? path.slice(0, at.index) : '';
-    const dir = name ? `${scoped}/node_modules/${name}` : null;
-    const what = name ? `the installed package ${name}` : 'an installed package';
+    const { entry, name } = parts;
+    // The run's own scratch directory is the run's to clean: the platform tells it
+    // to put throwaway work there (system prompt, "Throwaway probes go in
+    // `.mol-scratch/`"), so nothing in it is the pre-installed tree.
+    if (/(?:^|\/)\.mol-scratch(?:\/|$)/.test(path))
+        return null;
+    // No probe, or a probe that could not answer: keep the old, conservative
+    // reading (everything under node_modules is an install).
+    const facts = probe ? await probe(path).catch(() => null) : null;
+    const symlink = facts?.symlink ?? false;
+    const installed = facts?.installed ?? true;
+    // The entry itself — the link (or a tree with nothing in it) the run may take
+    // away. Removing a symlink deletes the LINK only; its target is untouched.
+    if (name === null && (symlink || !installed))
+        return null;
+    // A path under the entry: `installed` resolved through any link, so it is true
+    // exactly when a write here would land in a real installation.
+    if (name !== null && !installed)
+        return null;
+    const dir = name ? `${entry}/${name}` : null;
+    const what = name ? `the installed package ${name}` : 'an installed node_modules tree';
     const change = 'Installed packages are read-only: the next install replaces that file and a deploy never ' +
         'carries it. Change its behaviour from your app instead (its options, your own handler, a ' +
         'bond), and where the package itself is wrong, report it rather than patching it here. ' +
@@ -488,9 +688,11 @@ export function buildTools(backend, config) {
      * @param path - Relative or absolute path requested by the tool input.
      * @returns The normalized path, when writing it is allowed.
      */
-    function resolveWrite(path) {
+    async function resolveWrite(path) {
         const resolved = resolve(path);
-        const refusal = installedPackageWriteRefusal(resolved);
+        // The guard decides from what is installed where the path lives, so the
+        // backend is asked (one command, only for a path that names node_modules).
+        const refusal = await installedPackageWriteRefusal(resolved, shellInstalledPackageProbe((command) => backend.run(command, { timeout: 8000 })));
         if (refusal)
             throw new ToolInputError(refusal);
         return resolved;
@@ -1046,7 +1248,7 @@ export function buildTools(backend, config) {
             const argErr = pathArgError(input.path, 'write_file');
             if (argErr)
                 return { error: argErr };
-            const path = resolveWrite(input.path);
+            const path = await resolveWrite(input.path);
             const content = input.content;
             if (content.length > MAX_WRITE_SIZE)
                 return {
@@ -1095,7 +1297,7 @@ export function buildTools(backend, config) {
             const argErr = pathArgError(input.path, 'edit_file');
             if (argErr)
                 return { error: argErr };
-            const path = resolveWrite(input.path);
+            const path = await resolveWrite(input.path);
             // Support both formats: { replacements: [...] } (batch) and { old_string, new_string } (single, backwards-compatible)
             let replacements = input.replacements;
             // Accept the single format when BOTH are strings — `typeof` (not truthy) so
@@ -1729,7 +1931,7 @@ export function buildTools(backend, config) {
             }
         },
         async create_directory(input) {
-            const path = resolveWrite(input.path);
+            const path = await resolveWrite(input.path);
             const parentPath = path.substring(0, path.lastIndexOf('/')) || root;
             const symlinkErr = await checkSymlink(parentPath);
             if (symlinkErr)
@@ -1747,8 +1949,8 @@ export function buildTools(backend, config) {
         async rename_file(input) {
             // Both ends: moving a package's file OUT is as much a change to the installed
             // package as moving one in.
-            const oldPath = resolveWrite(input.old_path);
-            const newPath = resolveWrite(input.new_path);
+            const oldPath = await resolveWrite(input.old_path);
+            const newPath = await resolveWrite(input.new_path);
             const oldSymlinkErr = await checkSymlink(oldPath);
             if (oldSymlinkErr)
                 return { error: oldSymlinkErr };
@@ -1770,7 +1972,7 @@ export function buildTools(backend, config) {
             }
         },
         async delete_file(input) {
-            const path = resolveWrite(input.path);
+            const path = await resolveWrite(input.path);
             const symlinkErr = await checkSymlink(path);
             if (symlinkErr)
                 return { error: symlinkErr };
@@ -1820,7 +2022,28 @@ export function buildTools(backend, config) {
                 cwd,
                 readFile: (path) => backend.readFile(path),
             });
-            const command = traced.command;
+            let command = traced.command;
+            // A leading `sleep N; <read of a background task's log>` is a hand-rolled poll, and the
+            // platform knows the task's state better than the log's tail does (see
+            // {@link backgroundTaskState}): X1 xr-molecule-flash-m105 slept 225 s this way, two of the
+            // three on tasks that had already ended. The sleep is dropped and the rest of the command
+            // runs at once; with no background task behind it, the sleep is left exactly as sent — the
+            // tool's own budget is the existing bound.
+            const sleepPeek = leadingSleepPeek(command);
+            const peekedTask = sleepPeek
+                ? await backgroundTaskState(backend, command, sleepPeek.seconds, Math.max(5_000, (commandBudgetMs ?? 290_000) - 10_000))
+                : null;
+            const sleepNote = peekedTask?.note ?? null;
+            if (sleepPeek && peekedTask) {
+                command = sleepPeek.rest;
+                if (!command) {
+                    return {
+                        status: 'task_state',
+                        note: peekedTask.note,
+                        ...(peekedTask.slice.trim() ? { outputSoFar: sanitizeOutput(peekedTask.slice) } : {}),
+                    };
+                }
+            }
             // 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
@@ -1937,18 +2160,22 @@ export function buildTools(backend, config) {
                                         ...(output.length > MAX_OUTPUT_SIZE
                                             ? { truncated: true, fullOutput: log }
                                             : {}),
-                                        error: `${cutRunSentence(cut)} ` +
+                                        error: (sleepNote ? `${sleepNote} ` : '') +
+                                            `${cutRunSentence(cut)} ` +
                                             (isSuiteRunCommand(command) ? SUITE_OVER_BUDGET_ADVICE : SPLIT_WORK_ADVICE),
                                     };
                                 }
                                 // The exit file holds the PIPELINE's code: when a stage this rewrite could not
                                 // prove is output-only still follows the suite runner (`| tee run.log`), that code
-                                // is the filter's — report none and let the log's tally decide (m101 +25:54).
-                                const piped = suiteRunPipedAfterRunner(streaming.command);
-                                const reported = suiteRunExitCode(code, output, piped);
+                                // is the filter's — report none and let the log's tally decide (m101 +25:54). The
+                                // note says this only when the parse found such a stage (m105 +08:12).
+                                const placement = suiteRunPipelinePlacement(streaming.command);
+                                const reported = suiteRunExitCode(code, output, placement.piped);
+                                const exitNote = suiteExitCodeNote(placement, reported);
                                 const notes = [
+                                    ...(sleepNote ? [sleepNote] : []),
                                     ...streaming.changes,
-                                    ...(reported === null ? [FILTERED_EXIT_NOTE] : []),
+                                    ...(exitNote === null ? [] : [exitNote]),
                                 ];
                                 return {
                                     stdout,
@@ -1965,22 +2192,25 @@ export function buildTools(backend, config) {
                         taskId: id,
                         log,
                         exitFile,
-                        note: (overCeiling
-                            ? declaredSeconds > ceilingSeconds
-                                ? `This command asks for ${declaredSeconds}s, more than this tool's ${ceilingSeconds}s, and its ` +
-                                    'output only appears when it ends — so it was started in the background instead. '
-                                : `A Playwright run can take longer than this tool's ${ceilingSeconds}s, and behind a pipe its ` +
-                                    'output only appears when it ends — so it was started in the background instead. '
-                            : '') +
+                        ...(peekedTask?.slice.trim() ? { outputSoFar: sanitizeOutput(peekedTask.slice) } : {}),
+                        note: (sleepNote ? `${sleepNote} ` : '') +
+                            (overCeiling
+                                ? declaredSeconds > ceilingSeconds
+                                    ? `This command asks for ${declaredSeconds}s, more than this tool's ${ceilingSeconds}s, and its ` +
+                                        'output only appears when it ends — so it was started in the background instead. '
+                                    : `A Playwright run can take longer than this tool's ${ceilingSeconds}s, and behind a pipe its ` +
+                                        'output only appears when it ends — so it was started in the background instead. '
+                                : '') +
                             `Started in the background. Its output is written to ${log} and comes back as the ` +
-                            `stdout of wait_for_task when the command finishes (read_file cannot reach /tmp — ` +
-                            `to peek mid-run, exec_command: tail ${log}). If you have other work, do it and ` +
-                            `check back. If you need this result before you can continue, call wait_for_task ` +
-                            `with this taskId — never sleep and read the log by hand.` +
+                            `stdout of wait_for_task when the command finishes (read_file cannot reach /tmp). If ` +
+                            `you have other work, do it and check back. If you need this result before you can ` +
+                            `continue, call wait_for_task with this taskId: it returns the moment the command ` +
+                            `ends, returns early when a failure cause repeats, and reports progress and the ` +
+                            `failures so far — never sleep and read the log by hand.` +
                             (streaming.changes.length ? ` ${streaming.changes.join(' ')}` : '') +
                             (prioritized.note ? ` ${prioritized.note}` : '') +
                             (ownFile
-                                ? ` This command writes its own output to ${ownFile}, so the task log stays empty: peek with exec_command: tail ${ownFile}.`
+                                ? ` This command writes its own output to ${ownFile}, so the task log stays empty: wait_for_task reads that file when the command ends and reports its progress while it runs — never sleep and tail it by hand.`
                                 : ''),
                     };
                 }
@@ -2063,7 +2293,8 @@ export function buildTools(backend, config) {
                         // 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} ` +
+                        error: (sleepNote ? `${sleepNote} ` : '') +
+                            `${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'
@@ -2078,8 +2309,11 @@ export function buildTools(backend, config) {
                     stdout,
                     stderr,
                     exitCode: result.exitCode,
-                    ...(ceilingNote || traced.change
-                        ? { note: [ceilingNote, traced.change].filter(Boolean).join(' ') }
+                    ...(peekedTask?.slice.trim() ? { outputSoFar: sanitizeOutput(peekedTask.slice) } : {}),
+                    ...(sleepNote || ceilingNote || traced.change
+                        ? {
+                            note: [sleepNote, ceilingNote, traced.change].filter(Boolean).join(' '),
+                        }
                         : {}),
                 };
             }
@@ -2383,8 +2617,8 @@ export function buildTools(backend, config) {
                         status: 'running',
                         waitedMs,
                         ...sliceField,
-                        note: `${progress} Call wait_for_task again to keep waiting; peek with exec_command: ` +
-                            `tail ${log}.${midRun}`,
+                        note: `${progress} Call wait_for_task again to keep waiting — it returns the moment the ` +
+                            `command ends and reports the failures as they appear.${midRun}`,
                     };
                 }
                 if (waitedBefore + waitedMs >= stuckAfterMs()) {
@@ -2484,10 +2718,13 @@ export function buildTools(backend, config) {
             // Same shaping as a foreground exec result, so the executor reads both
             // the same way. The exit file holds the PIPELINE's code: when a stage this rewrite could not
             // prove is output-only still follows the suite runner (`| tee run.log`), that code is the
-            // filter's — report none and let the log's tally decide (m101 +25:54).
-            const piped = run ? suiteRunPipedAfterRunner(run.command) : false;
-            const reported = suiteRunExitCode(exitCode, output, piped);
-            const noCodeNote = reported === null ? FILTERED_EXIT_NOTE : null;
+            // filter's — report none and let the log's tally decide (m101 +25:54). The note says this
+            // only when the parse found such a stage (m105 +08:12).
+            const placement = run
+                ? suiteRunPipelinePlacement(run.command)
+                : { piped: false, unplaced: false };
+            const reported = suiteRunExitCode(exitCode, output, placement.piped);
+            const noCodeNote = suiteExitCodeNote(placement, reported);
             return {
                 taskId,
                 exitCode: reported,

package/dist/trace-artifacts.d.ts

@@ -32,8 +32,37 @@ export interface TraceRequest {
     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. */
+    /**
+     * The response status as the trace recorded it. Playwright writes `-1` when a request was never
+     * answered (its HAR entry starts at `-1` and only a response event overwrites it); `0` is the
+     * same absence when the snapshot carried no response at all. Neither is a server failure.
+     */
     status: number;
+    /**
+     * Playwright's own error text for a request that failed WITHOUT a response
+     * (`net::ERR_CONNECTION_REFUSED`) — a real failure. A request that got no response and recorded
+     * no text was aborted or still in flight when the test ended (the page closed under it), so it
+     * says nothing about the server (xr-molecule-flash-m112 +30:45).
+     */
+    failure?: string;
+    /**
+     * What the page SENT, for a 4xx answered by the app's own API — bounded (see
+     * {@link MAX_TRACED_BODY_CHARS}). A body wrapped as `{"data":{…}}` is visible here in one line:
+     * app-http's verbs take the body as their second argument, so a helper that passes
+     * `{ data: body }` there ships the wrapper (xr-molecule-flash-m111 +11:36).
+     */
+    sent?: string;
+    /** What came back for that 4xx, bounded the same way — the API's own error body. */
+    got?: string;
+}
+/** One action the traced page performed, with the trace's own timing for it. */
+export interface TraceAction {
+    /** The Playwright API the entry names: `Frame.goto`, `Locator.fill`, `Locator.click`. */
+    api: string;
+    /** When the action started, on the trace's own monotonic clock (ms). */
+    start: number;
+    /** When it finished, or null when the run ended before it did. */
+    end: number | null;
 }
 /** What one trace says: the test it belongs to, the requests it made, and its console errors. */
 export interface TraceArtifact {
@@ -45,6 +74,12 @@ export interface TraceArtifact {
     requests: TraceRequest[];
     /** The console errors and page errors the page raised. */
     console: string[];
+    /**
+     * The page's own actions in the order the trace recorded them, bounded — what a test that ran
+     * out of a per-test budget spends its time on. A test that repeats one action prints it once per
+     * repeat, so the gap between two starts is one repeat's measured cost.
+     */
+    actions: TraceAction[];
 }
 /** How many traces one read reports, newest first. */
 export declare const MAX_TRACE_ARTIFACTS = 12;
@@ -52,12 +87,20 @@ export declare const MAX_TRACE_ARTIFACTS = 12;
 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 of the page's own actions one test's trace contributes, the LAST ones. */
+export declare const MAX_TRACED_ACTIONS = 40;
+/** How much of a 4xx request's sent body (or its response body) the trace read keeps. */
+export declare const MAX_TRACED_BODY_CHARS = 300;
 /** 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;
+/** How much of the sent body the note prints — enough to see a `{"data":…}` wrapper. */
+export declare const TRACE_NOTE_SENT_CHARS = 160;
+/** How much of the response body the note prints — the API's first error line. */
+export declare const TRACE_NOTE_GOT_CHARS = 120;
 /**
  * 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
@@ -69,10 +112,17 @@ export declare const TRACE_NOTE_URL_CHARS = 96;
  * 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.
+ * A request is kept over a static asset when it failed — a `status >= 400`, or no response at all
+ * together with Playwright's own error text (`-1` plus `_failureText`, a refused connection) — 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. A request with no response and NO error text was aborted
+ * or still in flight when the test ended; it is kept too, but as what it is, not as a failure.
+ *
+ * A request answered 4xx by the app's OWN API also keeps what the page SENT and the first of what
+ * came back: Playwright stores either inline (`text`) or in a resource entry (`_file`), and both
+ * are read. That is where a wrapped body shows: xr-molecule-flash-m111's helper passed
+ * `{ data: body }` as app-http's second argument, so every POST/PUT was `{"data":{…}}` and the API
+ * validated `{}`. Status alone said only "422".
  *
  * @returns The program's source, to write to a file and run.
  */
@@ -97,11 +147,31 @@ export declare function parseTraceArtifacts(stdout: string): TraceArtifact[];
  * {@link MAX_TRACE_NOTE_TESTS} tests with {@link MAX_TRACE_NOTE_REQUESTS} requests each, because it
  * rides in a result the model pays for.
  *
+ * The three kinds are kept apart, because they mean different things. A FAILED request (4xx/5xx, or
+ * a network error with Playwright's own text) is a cause. A request with NO RESPONSE RECORDED —
+ * Playwright's `-1`, no error text — was still in flight when the test ended (the page closed under
+ * it); listing it as a failure sent a run hunting an API that never answered anything wrong
+ * (xr-molecule-flash-m112 +30:45). The rest are the page's last answered requests.
+ *
+ * A 4xx request carries what the page SENT beside its status, so a wrapped body is visible in one
+ * line rather than inferred from the status; when one of those bodies is an object whose only key
+ * is `data`, the note names the call shape that produces it (xr-molecule-flash-m111 +11:36).
+ *
+ * WHICH rows it spends is evidence, not artifact order (xr-molecule-flash-m112 +53:46): a row
+ * needs a recorded response, a real failure or a console error ({@link traceRowEvidence}), rows are
+ * deduplicated by the test's location, and they are ordered real failure → repeated from an
+ * earlier walk → the rest ({@link traceRowTier}). Without that the note spent all five rows on four
+ * traces of one `afterEach` line whose every request was `-1`, and left the favorite cause — the
+ * one failure that repeated in every walk — in its "… and N more".
+ *
  * @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.
+ * @param earlierFailures - The failing `file:line`s earlier walks of this suite left, so a repeat
+ *   is ranked above a one-off. Empty when the caller knows of no earlier walk.
+ * @returns The note, or null when no trace held a recorded response, a real failure or a console
+ *   error.
  */
-export declare function failureTraceNote(items: readonly TraceArtifact[], target: string): string | null;
+export declare function failureTraceNote(items: readonly TraceArtifact[], target: string, earlierFailures?: readonly string[]): string | null;
 /**
  * Whether a Playwright config records traces for the tests that fail.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"trace-artifacts.d.ts","sourceRoot":"","sources":["../src/trace-artifacts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAMH,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;AAuG/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,CAyBjC"}
+{"version":3,"file":"trace-artifacts.d.ts","sourceRoot":"","sources":["../src/trace-artifacts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAMH,iEAAiE;AACjE,MAAM,WAAW,YAAY;IAC3B,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAA;IACd,iGAAiG;IACjG,IAAI,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAA;IACd;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,oFAAoF;IACpF,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AAED,gFAAgF;AAChF,MAAM,WAAW,WAAW;IAC1B,yFAAyF;IACzF,GAAG,EAAE,MAAM,CAAA;IACX,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAA;IACb,kEAAkE;IAClE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;CACnB;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;IACjB;;;;OAIG;IACH,OAAO,EAAE,WAAW,EAAE,CAAA;CACvB;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,sFAAsF;AACtF,eAAO,MAAM,kBAAkB,KAAK,CAAA;AAEpC,yFAAyF;AACzF,eAAO,MAAM,qBAAqB,MAAM,CAAA;AAExC,uDAAuD;AACvD,eAAO,MAAM,oBAAoB,IAAI,CAAA;AAErC,iDAAiD;AACjD,eAAO,MAAM,uBAAuB,IAAI,CAAA;AAExC,gEAAgE;AAChE,eAAO,MAAM,oBAAoB,KAAK,CAAA;AAEtC,wFAAwF;AACxF,eAAO,MAAM,qBAAqB,MAAM,CAAA;AAExC,kFAAkF;AAClF,eAAO,MAAM,oBAAoB,MAAM,CAAA;AAKvC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,oBAAoB,QAAO,MAiQvC,CAAA;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,EAAE,CAqCnE;AAwJD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,SAAS,aAAa,EAAE,EAC/B,MAAM,EAAE,MAAM,EACd,eAAe,GAAE,SAAS,MAAM,EAAO,GACtC,MAAM,GAAG,IAAI,CAmFf;AAaD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAG9D;AAED,iFAAiF;AACjF,eAAO,MAAM,oBAAoB,8BAA8B,CAAA;AA2G/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,CAyBjC"}