@molecule/api-ai-tools 1.6.4 → 1.6.6

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';
@@ -25,6 +26,16 @@ const waitedByTask = new Map();
 const logBytesByTask = new Map();
 /** The file a background command writes its own output to, when it redirects it. */
 const outputFileByTask = new Map();
+/**
+ * How each background task was started: the command as it was actually run (after
+ * {@link streamingBackgroundCommand} rewrote it) and the directory it ran in.
+ *
+ * A mid-run note has to hand over the re-run of a test that just failed, and a re-run is composed
+ * from the command that is still walking ({@link rerunOfRunningSuite}) — a whole-suite re-run is
+ * what the executor must not be handed for now, and a re-run narrowed for the wrong directory
+ * resolves the failing test's `file:line` against the wrong suite.
+ */
+const runByTask = new Map();
 /**
  * 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
@@ -198,12 +209,43 @@ 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 { 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';
 /**
  * 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
@@ -234,6 +276,52 @@ export function moleculeDistReadNote(path) {
             ? ' The declarations above are generated from it.'
             : ' 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.
+ *
+ * `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
+ * shared (the pre-installed superset) breaks every other run through it. X0
+ * xr-molecule-flash-m91 (+04:43) called `write_file` on
+ * `node_modules/@molecule/api-resource-comment/dist/numbers.d.ts` while reading
+ * the package's declarations and clobbered its runtime module a call later
+ * (`module.exports = {}` over the ESM handler its own code imports) — the write
+ * answered `ok: true`, and 18 s went to noticing, `npm pack`-ing the package and
+ * putting the file back. Reading these files stays allowed (that is how the
+ * declarations above are read at all).
+ *
+ * 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
+ * sandbox. `npm pack` + a `tar` extraction over the package directory is what
+ * m91 used, and what both guards leave alone.
+ *
+ * @param path - An absolute path a tool is about to write.
+ * @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)
+        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 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. ' +
+        'Reading these files is fine.';
+    const restore = name && dir
+        ? ` If you have already overwritten one there, restore the package before anything else: ` +
+            `\`npm pack ${name}@<version>\` (the version is in ${dir}/package.json), then ` +
+            `\`tar -xzf <the tarball npm pack printed> --strip-components=1 -C ${dir}\` — never a hand-edit.`
+        : '';
+    return `Not written: ${path} is inside ${what} (node_modules). ${change}${restore}`;
+}
 /**
  * Build a complete set of AI agent tools bound to an execution backend.
  *
@@ -336,6 +424,22 @@ export function buildTools(backend, config) {
         }
         return pathGuards ? resolvePath(path, root) : path;
     }
+    /**
+     * Resolve the path a WRITING tool was given, refusing a target inside an
+     * installed package ({@link installedPackageWriteRefusal}). Reads are not sent
+     * through this: reading `node_modules` is how a package's declarations are
+     * read at all, and only the write is unrecoverable.
+     *
+     * @param path - Relative or absolute path requested by the tool input.
+     * @returns The normalized path, when writing it is allowed.
+     */
+    function resolveWrite(path) {
+        const resolved = resolve(path);
+        const refusal = installedPackageWriteRefusal(resolved);
+        if (refusal)
+            throw new ToolInputError(refusal);
+        return resolved;
+    }
     /** Paths read with a window in this tool set, to tell paging from one targeted read. */
     const windowedReads = new Set();
     /** The text each path was last handed back WHOLE as, so that correction fires once per version. */
@@ -887,7 +991,7 @@ export function buildTools(backend, config) {
             const argErr = pathArgError(input.path, 'write_file');
             if (argErr)
                 return { error: argErr };
-            const path = resolve(input.path);
+            const path = resolveWrite(input.path);
             const content = input.content;
             if (content.length > MAX_WRITE_SIZE)
                 return {
@@ -936,7 +1040,7 @@ export function buildTools(backend, config) {
             const argErr = pathArgError(input.path, 'edit_file');
             if (argErr)
                 return { error: argErr };
-            const path = resolve(input.path);
+            const path = 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
@@ -973,13 +1077,35 @@ export function buildTools(backend, config) {
                 }
                 const oldContent = content;
                 let alreadyApplied = 0;
+                // Replacements refused for changing the line break at old_string's boundary and
+                // nothing else — reported by position, never applied (see below).
+                const skipped = [];
                 // Where each applied replacement landed, in the coordinates of the
                 // latest content — rendered into the result so the model sees the edit.
                 let spans = [];
-                for (const { old_string: oldString, new_string: newString, replace_all: replaceAll, 
+                // A replacement whose ONLY effect is the line break at old_string's boundary:
+                // `new_string` is `old_string` minus its trailing newline (applying it runs the
+                // line after it onto the last line) or `old_string` plus one (applying it moves
+                // the rest of that line down). A weaker model sends the first as an "anchor" — it
+                // repeats a line it means to keep, minus its `\n` — and the join is silent when
+                // it still parses: flash-m28 merged two lines three times in one run, flash-m89
+                // twice in two consecutive calls (comments.ts, then articles.ts), flash-m55,
+                // m62 and m89 all paid a repair round trip for it. A real edit changes some other
+                // character, so this costs nothing.
+                const boundaryOnly = (oldText, newText) => {
+                    const oldBody = oldText.replace(/\r?\n$/, '');
+                    // `newText !== ''` keeps a deletion out of this: `old_string: "\n"` → `""` is a
+                    // real request to remove a blank line, and the notes below already cover it.
+                    if (newText !== '' && oldBody !== oldText && newText === oldBody)
+                        return 'removed';
+                    if (!oldText.endsWith('\n') && newText === `${oldText}\n`)
+                        return 'added';
+                    return null;
+                };
+                for (const [index, { old_string: oldString, new_string: newString, replace_all: replaceAll, 
                 // Models sometimes send the camelCase spelling inside an item, where
                 // the input normalizer (top-level keys only) does not reach.
-                replaceAll: replaceAllCamel, } of replacements) {
+                replaceAll: replaceAllCamel, },] of replacements.entries()) {
                     // Validate each replacement is well-formed BEFORE touching content. A
                     // weak model sometimes emits a batch element missing a field or with a
                     // non-string value; left unchecked that either crashes (`undefined`
@@ -1081,15 +1207,74 @@ export function buildTools(backend, config) {
                                 .map((l) => l.trim())
                                 .filter((l) => l.length >= 8)),
                         ].sort((a, b) => b.length - a.length);
+                        const oldLines = oldString.split('\n');
+                        // Whitespace is the one difference the model cannot see in its own
+                        // text, so make it visible when that is the whole difference.
+                        const visible = (l) => l.replace(/ /g, '·').replace(/\t/g, '⇥');
+                        // Report where old_string and the file STOP agreeing, not where the
+                        // match starts. A snippet centred on the anchor is the part the model
+                        // already has right, so it re-sends the same old_string and fails the
+                        // same way (X0 m89: two failed edits, a whole-file re-read and a
+                        // rewrite, 9 s, for a divergence 35 lines below the anchor).
+                        const showDivergence = (base, k) => {
+                            const expected = oldLines[k];
+                            const actual = fileLines[base + k] ?? '(end of file)';
+                            const whitespaceOnly = expected.replace(/\s/g, '') === actual.replace(/\s/g, '');
+                            let col = 0;
+                            while (col < expected.length && col < actual.length && expected[col] === actual[col])
+                                col++;
+                            const howFar = whitespaceOnly
+                                ? ' (whitespace only — · is a space, ⇥ a tab)'
+                                : col > 0
+                                    ? ` (first character difference at column ${col + 1})`
+                                    : '';
+                            const start = Math.max(0, base + k - 2);
+                            const snippet = fileLines
+                                .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}`,
+                            };
+                        };
+                        // 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
+                        // one. k === 0 means nothing beyond the anchor itself lines up; only
+                        // then fall back to the old anchor snippet.
+                        let best = null;
+                        let firstUniqueHit = null;
                         for (const anchor of distinctiveLines) {
                             const hits = fileLines.reduce((acc, l, i) => {
                                 if (l.includes(anchor))
                                     acc.push(i);
                                 return acc;
                             }, []);
-                            if (hits.length === 1)
-                                return showSnippet(hits[0]);
+                            if (hits.length !== 1)
+                                continue;
+                            if (firstUniqueHit === null)
+                                firstUniqueHit = hits[0];
+                            const base = hits[0] - oldLines.findIndex((l) => l.trim() === anchor);
+                            if (base < 0)
+                                continue;
+                            // Exact comparison: a line that differs only in trailing whitespace
+                            // is itself a reason the exact match failed, and it is invisible in
+                            // the model's own text — report it as the divergence (the message
+                            // renders it with · for space).
+                            let k = 0;
+                            while (k < oldLines.length && fileLines[base + k] === oldLines[k]) {
+                                k++;
+                            }
+                            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);
                         // 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
@@ -1149,10 +1334,36 @@ export function buildTools(backend, config) {
                     // a self-inflicted syntax error written with ok:true that the executor
                     // then can't locate. count === 1 here, so indexOf is the unique site.
                     const at = content.indexOf(oldString);
+                    // Refuse a replacement whose only effect is the line break at the boundary,
+                    // INSTEAD of applying it (flash-m89 +08:32 left `function pageLimit(req): number
+                    // {  const raw = …` on one line and +07:25 left a comment handler unparseable,
+                    // twice in two calls, and the API was down between the pair). The file's own
+                    // next character is the evidence that decides it: text on the same line means
+                    // the break is moving across lines (a join, or a split), which the shape of the
+                    // replacement says the model did not ask for. At a line boundary — a blank line
+                    // after it, or the end of the file — nothing crosses lines and the edit stands.
+                    const boundary = boundaryOnly(oldString, newString);
+                    const after = content[at + oldString.length];
+                    if (boundary !== null && after !== undefined && after !== '\n') {
+                        skipped.push({ position: index + 1, shape: boundary });
+                        continue;
+                    }
                     const spliced = content.slice(0, at) + newString + content.slice(at + oldString.length);
                     spans = addChangeSpan(spans, content, spliced);
                     content = spliced;
                 }
+                // 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
+                // on text a joined file no longer has, so applying the join takes the batch down
+                // with it.
+                const skippedNote = skipped.length === 0
+                    ? null
+                    : skipped
+                        .map(({ position, shape }) => shape === 'removed'
+                        ? `replacement ${position} was skipped, nothing was changed for it: its new_string is its old_string minus the trailing newline, so the only thing it changes is the line break between that text and the line after it — applying it would run the two lines together. To join two lines on purpose, include the next line in old_string.`
+                        : `replacement ${position} was skipped, nothing was changed for it: its new_string is its old_string plus a trailing newline, so the only thing it changes is the line break after that text — applying it would move the rest of that line down. To split a line on purpose, include the text that follows it in old_string.`)
+                        .join('\n');
                 const alreadyNote = alreadyApplied > 0
                     ? `${alreadyApplied} of these edits ${alreadyApplied === 1 ? 'was' : 'were'} already in the file (its new_string is there and its old_string is not) — nothing to do for ${alreadyApplied === 1 ? 'it' : 'them'}.`
                     : null;
@@ -1164,7 +1375,16 @@ export function buildTools(backend, config) {
                         (identical > 0
                             ? `Nothing changed: ${identical === 1 ? 'the replacement’s new_string is' : `${identical} replacements’ new_string are`} identical to old_string, so the file is exactly as it was. Write the text you want in new_string.`
                             : 'Nothing changed: the file is exactly as it was.');
-                    return { path, ok: true, replacementsApplied: 0, alreadyApplied, note };
+                    // A refused boundary-newline replacement is why nothing changed: "the file is
+                    // exactly as it was" would read as "your edit landed".
+                    return {
+                        path,
+                        ok: true,
+                        replacementsApplied: 0,
+                        alreadyApplied,
+                        note: skippedNote ?? note,
+                        ...(skippedNote ? { skippedNote } : {}),
+                    };
                 }
                 if (onFileDiff)
                     onFileDiff({ path, oldContent, newContent: content });
@@ -1190,10 +1410,13 @@ export function buildTools(backend, config) {
                 const excerpt = renderEditExcerpt(finalContent, spans);
                 // A replacement whose old text ended in a newline and whose new text does not
                 // joins the line after it onto its last line. Applied as written, but said:
-                // flash-m28 saw two lines merged only one round trip later.
+                // flash-m28 saw two lines merged only one round trip later. The refused ones
+                // above were never applied, so what the file holds is not their work.
+                const refused = new Set(skipped.map((s) => s.position));
                 const dropped = replacements
                     .map((r, i) => ({ ...r, position: i + 1 }))
-                    .filter((r) => typeof r.old_string === 'string' &&
+                    .filter((r) => !refused.has(r.position) &&
+                    typeof r.old_string === 'string' &&
                     typeof r.new_string === 'string' &&
                     r.old_string.endsWith('\n') &&
                     r.new_string !== '' &&
@@ -1232,7 +1455,7 @@ export function buildTools(backend, config) {
                 return {
                     path,
                     ok: true,
-                    replacementsApplied: replacements.length - alreadyApplied,
+                    replacementsApplied: replacements.length - alreadyApplied - skipped.length,
                     ...(fusedNote
                         ? { syntaxError: fusedNote }
                         : {
@@ -1251,6 +1474,7 @@ export function buildTools(backend, config) {
                                 : {}),
                             ...syntax,
                         }),
+                    ...(skippedNote ? { skippedNote } : {}),
                     ...(alreadyApplied > 0 ? { alreadyApplied, note: alreadyNote } : {}),
                     totalLines: countLines(finalContent),
                     ...(excerpt ? { excerpt: sanitizeFileContent(excerpt, path) } : {}),
@@ -1292,7 +1516,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
@@ -1329,6 +1553,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}` };
             }
         },
@@ -1350,26 +1579,59 @@ 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}` };
             }
         },
         async create_directory(input) {
-            const path = resolve(input.path);
+            const path = resolveWrite(input.path);
             const parentPath = path.substring(0, path.lastIndexOf('/')) || root;
             const symlinkErr = await checkSymlink(parentPath);
             if (symlinkErr)
@@ -1385,8 +1647,10 @@ export function buildTools(backend, config) {
             }
         },
         async rename_file(input) {
-            const oldPath = resolve(input.old_path);
-            const newPath = resolve(input.new_path);
+            // 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 oldSymlinkErr = await checkSymlink(oldPath);
             if (oldSymlinkErr)
                 return { error: oldSymlinkErr };
@@ -1408,7 +1672,7 @@ export function buildTools(backend, config) {
             }
         },
         async delete_file(input) {
-            const path = resolve(input.path);
+            const path = resolveWrite(input.path);
             const symlinkErr = await checkSymlink(path);
             if (symlinkErr)
                 return { error: symlinkErr };
@@ -1508,6 +1772,7 @@ export function buildTools(backend, config) {
                         : null;
                     if (ownFile)
                         outputFileByTask.set(id, ownFile);
+                    runByTask.set(id, { command: streaming.command, cwd });
                     await backend.writeFile(script, `${streaming.command}\n`);
                     await backend.run(`nohup sh -c ${shellQuote(prioritized.launch)} ` +
                         `> /dev/null 2>&1 & echo $! > /tmp/${id}.pid`, { cwd, timeout: 15_000 });
@@ -1630,18 +1895,31 @@ 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 {
@@ -1848,6 +2126,11 @@ export function buildTools(backend, config) {
                 // 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);
+                // 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);
@@ -1860,6 +2143,7 @@ export function buildTools(backend, config) {
                         log,
                         stop: universal ? await taskStopCommand(backend, taskId) : '',
                         universal,
+                        ...(started ? { run: started } : {}),
                     }),
                 };
             }
@@ -1974,6 +2258,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 {