@molecule/api-ai-tools 1.6.2 → 1.6.5

package/dist/tools.js

@@ -25,6 +25,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
@@ -63,13 +73,21 @@ const taskPidsCommand = (taskId) => `R=$(cat /tmp/${taskId}.pid 2>/dev/null); `
 /**
  * The command that stops a running background task, read from the sandbox's own pid files.
  *
+ * THE one builder for it, so every note that hands the executor a way to stop a run hands over the
+ * same pid-only form: a `pkill -f <something>` matches the shell running it (its argv IS the
+ * command), and `molecule-dev/api/src/ai/pattern-kill-guard.ts` holds exactly that — X1
+ * xr-molecule-flash-m87's stuck note suggested `kill $(cat /tmp/<id>.pid) 2>/dev/null; pkill -f
+ * <id>.sh`, which the platform's own guard then refused, and the same shape cost a refused call at
+ * +21:57. The pid tree is the whole of what the pattern was for: the detached shell and every
+ * process under it.
+ *
  * @param backend - The execution backend.
  * @param taskId - The task's `mol-bg-…` handle.
  * @returns The command to hand the executor — `kill <pids>` — falling back to the task's own pid
  *   file when the walk comes back empty (a sandbox without `pgrep`, or a pid file already gone,
  *   in which case the pid-file form is still the one the platform's guard names).
  */
-async function taskStopCommand(backend, taskId) {
+export async function taskStopCommand(backend, taskId) {
     const fallback = `kill $(cat /tmp/${taskId}.pid)`;
     try {
         const r = await backend.run(taskPidsCommand(taskId), { timeout: 10_000 });
@@ -122,7 +140,8 @@ function logProgress(log) {
 /**
  * What a wait knows about the command BESIDES "it has not exited": how long it
  * has been running, whether its output is still growing, how far its own log
- * says it has got, and how much longer that implies.
+ * says it has got, and how much longer that implies — one fact per clause, built
+ * here so the note carrying them cannot state one of them twice.
  *
  * X1 flash-m62 (2026-10-16) spent three 290 s waits on one 8.3-minute suite and
  * every answer read only "Still running after 280s": the run could not tell a
@@ -131,35 +150,63 @@ function logProgress(log) {
  * waiting. The elapsed time comes from the task id, the progress from the log
  * this wait already read, and the time left is the rate so far, said as such.
  *
+ * X1 flash-m87 §+47:20 (2026-10-16): that suite's answer read "Still running
+ * after 342s of waiting, and its output is still growing (71839 bytes) — slow,
+ * not stuck." and then this sentence, which opens with the same growth clause
+ * and gives the same elapsed time in its other format — one answer, two facts,
+ * each said twice. The clauses ARE the facts, and {@link runningNote} is the
+ * only place they become a sentence, so a lead the caller writes itself cannot
+ * repeat one (the way `deployOwedNote` returns one sentence rather than a join).
+ *
  * @param o - The wait's facts: `taskId`, the `slice` of the log it read,
  *   `stillWriting` (the log grew during this wait), `bytes` (the log's size, null
- *   when unreadable), and `ceilingMs` (this call's ceiling, for "one more wait").
- * @returns A sentence to append to a running note, or '' when nothing is known.
+ *   when unreadable), `ceilingMs` (this call's ceiling, for "one more wait"), and
+ *   `waitedMs` (this call's own wait, the elapsed figure when the id carries no
+ *   start stamp).
+ * @returns The clauses in reading order. The first states the elapsed time, so a
+ *   sentence built from them always says something.
  */
-function waitProgressNote(o) {
+function waitProgressClauses(o) {
     const startedAt = taskStartedAt(o.taskId);
-    const elapsedMs = startedAt === null ? null : Math.max(0, Date.now() - startedAt);
-    const parts = [];
-    if (elapsedMs !== null)
-        parts.push(`it has been running ${durationText(elapsedMs)}`);
+    const sinceStart = startedAt === null ? null : Math.max(0, Date.now() - startedAt);
+    // A task id this process minted always carries its start stamp; a synthetic one
+    // does not, and the time this call spent waiting is then the floor for how long
+    // the command has been running — it ran throughout that wait.
+    const clauses = [
+        sinceStart === null
+            ? `it has been running at least ${durationText(o.waitedMs)}`
+            : `it has been running ${durationText(sinceStart)}`,
+    ];
     if (o.stillWriting)
-        parts.push(`its output is still growing (${o.bytes} bytes) — slow, not stuck`);
+        clauses.push(`its output is still growing (${o.bytes} bytes) — slow, not stuck`);
     else if (o.bytes !== null)
-        parts.push(`its log has not grown during this wait (${o.bytes} bytes)`);
+        clauses.push(`its log has not grown during this wait (${o.bytes} bytes)`);
     const counter = logProgress(o.slice);
     if (counter) {
-        parts.push(`its log is at ${counter.done} of ${counter.total}`);
-        if (elapsedMs !== null && counter.done > 0 && counter.done < counter.total) {
-            const leftMs = Math.round((elapsedMs * (counter.total - counter.done)) / counter.done);
-            parts.push(leftMs <= o.ceilingMs
+        clauses.push(`its log is at ${counter.done} of ${counter.total}`);
+        // The rate is the task's own elapsed time, never this call's wait: with no
+        // start stamp, "34 tests in the 290 s I just waited" would be reported as the
+        // speed of a suite that has been walking for ten minutes.
+        if (sinceStart !== null && counter.done > 0 && counter.done < counter.total) {
+            const leftMs = Math.round((sinceStart * (counter.total - counter.done)) / counter.done);
+            clauses.push(leftMs <= o.ceilingMs
                 ? `about ${durationText(leftMs)} left at that rate — one more wait covers it`
                 : `about ${durationText(leftMs)} left at that rate (${Math.ceil(leftMs / o.ceilingMs)} more waits)`);
         }
     }
-    if (!parts.length)
+    return clauses;
+}
+/**
+ * One sentence from clauses: joined by "; ", capitalised and punctuated once.
+ *
+ * @param clauses - The facts to state, each in its own clause.
+ * @returns The sentence, or '' when there is nothing to say.
+ */
+function runningNote(clauses) {
+    if (!clauses.length)
         return '';
-    const sentence = parts.join('; ');
-    return ` ${sentence[0].toUpperCase()}${sentence.slice(1)}.`;
+    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';
 /**
@@ -197,6 +244,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.
  *
@@ -299,6 +392,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. */
@@ -850,7 +959,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 {
@@ -899,7 +1008,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
@@ -936,13 +1045,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`
@@ -1044,15 +1175,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
@@ -1112,10 +1302,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;
@@ -1127,7 +1343,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 });
@@ -1153,10 +1378,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 !== '' &&
@@ -1195,7 +1423,7 @@ export function buildTools(backend, config) {
                 return {
                     path,
                     ok: true,
-                    replacementsApplied: replacements.length - alreadyApplied,
+                    replacementsApplied: replacements.length - alreadyApplied - skipped.length,
                     ...(fusedNote
                         ? { syntaxError: fusedNote }
                         : {
@@ -1214,6 +1442,7 @@ export function buildTools(backend, config) {
                                 : {}),
                             ...syntax,
                         }),
+                    ...(skippedNote ? { skippedNote } : {}),
                     ...(alreadyApplied > 0 ? { alreadyApplied, note: alreadyNote } : {}),
                     totalLines: countLines(finalContent),
                     ...(excerpt ? { excerpt: sanitizeFileContent(excerpt, path) } : {}),
@@ -1332,7 +1561,7 @@ export function buildTools(backend, config) {
             }
         },
         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)
@@ -1348,8 +1577,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 };
@@ -1371,7 +1602,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 };
@@ -1471,6 +1702,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 });
@@ -1739,8 +1971,8 @@ export function buildTools(backend, config) {
                     status: 'stuck',
                     waitedMs: waitedBefore,
                     note: `You have already waited ${Math.round(waitedBefore / 1000)}s on this command and it ` +
-                        `has not exited — it is stuck, not slow. Kill it (exec_command: kill $(cat /tmp/${taskId}.pid) ` +
-                        `2>/dev/null; pkill -f ${taskId}.sh) and move on; do not wait on it again.`,
+                        `has not exited — it is stuck, not slow. Kill it (\`exec_command: ` +
+                        `${await taskStopCommand(backend, taskId)}\`) and move on; do not wait on it again.`,
                 };
             }
             // The id names files under /tmp; only an id this tool minted may be used
@@ -1811,6 +2043,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);
@@ -1823,6 +2060,7 @@ export function buildTools(backend, config) {
                         log,
                         stop: universal ? await taskStopCommand(backend, taskId) : '',
                         universal,
+                        ...(started ? { run: started } : {}),
                     }),
                 };
             }
@@ -1853,13 +2091,19 @@ export function buildTools(backend, config) {
                     // No slice: the notes still say how to peek, and the task id still
                     // carries how long the command has been running.
                 }
-                const progress = waitProgressNote({
+                // ONE sentence of facts, each said once, then what to do next: the lead
+                // this branch used to write ("Still running after 342s of waiting, and its
+                // output is still growing (71839 bytes) — slow, not stuck") restated the
+                // elapsed time and the growth clause these clauses already hold — the same
+                // sentence, twice (X1 flash-m87 §+47:20).
+                const progress = runningNote(waitProgressClauses({
                     taskId,
                     slice: soFar,
                     stillWriting,
                     bytes: grownTo,
                     ceilingMs: ceiling,
-                });
+                    waitedMs: waitedBefore + waitedMs,
+                }));
                 const sliceField = soFar.trim() ? { outputSoFar: sanitizeOutput(soFar) } : {};
                 if (stillWriting && waitedBefore + waitedMs >= stuckAfterMs()) {
                     waitedByTask.set(taskId, 0);
@@ -1868,9 +2112,8 @@ export function buildTools(backend, config) {
                         status: 'running',
                         waitedMs,
                         ...sliceField,
-                        note: `Still running after ${Math.round((waitedBefore + waitedMs) / 1000)}s of waiting, and its ` +
-                            `output is still growing (${grownTo} bytes) — slow, not stuck.${progress} Call wait_for_task ` +
-                            `again to keep waiting; peek with exec_command: tail ${log}.`,
+                        note: `${progress} Call wait_for_task again to keep waiting; peek with exec_command: ` +
+                            `tail ${log}.`,
                     };
                 }
                 if (waitedBefore + waitedMs >= stuckAfterMs()) {
@@ -1880,8 +2123,8 @@ export function buildTools(backend, config) {
                         waitedMs: waitedBefore + waitedMs,
                         note: `${Math.round((waitedBefore + waitedMs) / 1000)}s of waiting and it has not exited — it is ` +
                             `stuck, not slow. See what it printed with exec_command (tail /tmp/${taskId}.log — ` +
-                            `read_file cannot reach /tmp), kill it (exec_command: ` +
-                            `kill $(cat /tmp/${taskId}.pid) 2>/dev/null; pkill -f ${taskId}.sh) and move on; do not wait on it again.`,
+                            `read_file cannot reach /tmp), kill it (\`exec_command: ` +
+                            `${await taskStopCommand(backend, taskId)}\`) and move on; do not wait on it again.`,
                     };
                 }
                 return {
@@ -1889,7 +2132,10 @@ export function buildTools(backend, config) {
                     status: 'running',
                     waitedMs,
                     ...sliceField,
-                    note: `Still running after ${Math.round(waitedMs / 1000)}s.${progress} Call wait_for_task again to ` +
+                    // No "Still running after Ns" lead here either: the clauses already say
+                    // how long it has been running, and the lead said it a second time in
+                    // the other format (X1 flash-m87 §+47:20).
+                    note: `${progress} Call wait_for_task again to ` +
                         `keep waiting — its result carries the log output. ` +
                         (soFar.trim()
                             ? `outputSoFar is the failure lines so far (up to ${RUNNING_FAILURE_LINES}) and then the end of ` +

package/dist/utilities.d.ts

@@ -691,6 +691,27 @@ export declare function failuresByCause(log: string): FailureCause[];
  * @returns The note, or null.
  */
 export declare function failureCausesNote(log: string): string | null;
+/**
+ * The command that re-runs the tests at `locations` the way the run IN FLIGHT ran them: the same
+ * invocation, in the same directory, narrowed to those tests — or null when the running command
+ * is not a Playwright run this can narrow.
+ *
+ * The `locations` are the paths the run's own log printed, which are relative to the directory
+ * that run started in, so a re-run has to resolve them there: the command names that directory
+ * unless it already changes into one of its own, because the executor's next command starts
+ * wherever it starts. The returned command is for AFTER the run ends — it is a second run against
+ * the same app and database, and that is exactly what is refused while the run walks
+ * ({@link suiteRunInTheWay}).
+ *
+ * @param run - The run in flight: the command it was started with, as it was run, and the
+ *   directory that command ran in.
+ * @param locations - The failing `file:line`s to re-run, as the run's log printed them.
+ * @returns The re-run command, or null when there is no suite to narrow.
+ */
+export declare function rerunOfRunningSuite(run: {
+    command: string;
+    cwd?: string;
+}, locations: readonly string[]): string | null;
 /**
  * The sentence that names a cause repeating among a running suite's failures, mid-run.
  *
@@ -705,10 +726,21 @@ export declare function failureCausesNote(log: string): string | null;
  * stopped eight runs at their first repeating cause in 14.5 minutes and never finished one, so
  * the note must not say to stop when the run still has other causes to name.
  *
+ * The run is STILL WALKING while this note is written — both callers produce it mid-run — so a
+ * re-run of one of its tests is a second run against the same app and database, and the platform
+ * refuses that ({@link suiteRunInTheWay}, the same rule its overlap hold answers with):
+ * xr-molecule-flash-m89 (2026-10-16) read *"Start on them now, while the run keeps walking.
+ * `null-fields.spec.ts:53` alone reproduces the first one."* and sent exactly that re-run 23 s
+ * later, where the hold answered *"A playwright suite is already running against this app and
+ * database … Wait for it."* The note therefore hands over the read-and-fix to do NOW and the
+ * re-run for after the run ends — the exact command where the caller knows how the run was
+ * started ({@link rerunOfRunningSuite}), the timing alone where it does not.
+ *
  * @param found - What {@link repeatingFailure} found.
  * @param o - The run's facts: its `taskId`, its `log` path, `stop` — the shell command that
- *   stops it, printed only for a {@link UniversalCause} — and `universal`, what
- *   {@link universalCause} found (absent means the run is not failing whole).
+ *   stops it, printed only for a {@link UniversalCause} — `universal`, what
+ *   {@link universalCause} found (absent means the run is not failing whole), and `run`, how the
+ *   run was started ({@link rerunOfRunningSuite}) when the caller knows it.
  * @returns The note.
  */
 export declare function repeatingFailureNote(found: RepeatingFailure, o: {
@@ -716,6 +748,10 @@ export declare function repeatingFailureNote(found: RepeatingFailure, o: {
     log: string;
     stop: string;
     universal?: UniversalCause | null;
+    run?: {
+        command: string;
+        cwd?: string;
+    };
 }): string;
 /**
  * Attempt a whitespace-tolerant replacement when an exact `old_string` match