@molecule/api-ai-tools 1.6.4 → 1.6.5

package/dist/suite-overlap.js

@@ -0,0 +1,208 @@
+/**
+ * The ONE rule that decides whether a suite run may start while another is already walking, and
+ * the command readings both sides of it need.
+ *
+ * Two sites ask "may a second run start now?" about the same pair of runs — the mid-run note that
+ * tells the executor what to do next while the suite it is waiting on is still going
+ * ({@link ./utilities.js} `repeatingFailureNote`), and the hold that refuses the run when it
+ * arrives (molecule-dev's `suite-overlap-hold.ts`) — and until xr-molecule-flash-m89 they answered
+ * it separately. That run's +19:59 `wait_for_task` handed over a repeating cause with "the test
+ * alone reproduces the first one … start on them now, while the run keeps walking"; 23 s later the
+ * executor sent exactly that re-run, and the overlap hold refused it — "A playwright suite is
+ * already running against this app and database … Wait for it." Two orders, one run, and the round
+ * trip between them was the whole cost.
+ *
+ * So the rule lives here ({@link suiteRunInTheWay}) and both of them call it: a run may start only
+ * when nothing in flight is already measuring the same app and database. What "the same app and
+ * database" MEANS lives here too ({@link suiteCommandTarget}) — the note and the hold have to key
+ * a command the same way before they can agree on whether two of them collide, and the re-run a
+ * note hands over is built from the same reading of the running command
+ * ({@link scopedRerunCommand}).
+ *
+ * The same treatment for the other pair that answered one question twice: whether a run walks the
+ * WHOLE suite or a part of it. The rewriter that decides whether a background Playwright run gets
+ * `--retries=0` ({@link ./utilities.js} `streamingBackgroundCommand`) and the platform's own notes
+ * (molecule-dev's `suite-cli-override.ts`) asked it separately — a regex there, a predicate here —
+ * until xr-molecule-flash-m89 showed the two answers were never the same question
+ * ({@link isDiagnosisRun}).
+ *
+ * @module
+ */
+import { commandSegments } from './command-position.js';
+import { commandRunsNoTests } from './no-test-run.js';
+/**
+ * A command with its heredoc bodies removed: the runs, kills and hosts it names in a file it
+ * WRITES are not what the command itself does.
+ *
+ * The header is kept (`cat > run.sh <<'EOF' …EOF` leaves `cat > run.sh`), which is what the
+ * readers here want: everything before the body is still readable as the command's own words.
+ *
+ * @param command - The shell command.
+ * @returns The command without its heredoc bodies.
+ */
+export function withoutHeredocs(command) {
+    return command.replace(/<<-?\s*(['"]?)(\w+)\1[\s\S]*?\n\s*\2\b/g, ' ');
+}
+/**
+ * The server a suite command points at, as a comparable key: the host it names (`HOST=`,
+ * `BASE_URL=`, `PLAYWRIGHT_BASE_URL=`, `--variable host=`, or a bare URL), or `local` for a run
+ * that names none — a suite run in the sandbox goes to the sandbox's own app unless the command
+ * says otherwise. Every localhost spelling collapses to `local` (one sandbox, one app, one
+ * database).
+ *
+ * @param command - The suite command.
+ * @returns The target key.
+ */
+export function suiteCommandTarget(command) {
+    const text = withoutHeredocs(command);
+    const named = /(?:\b(?:HOST|BASE_URL|PLAYWRIGHT_BASE_URL|E2E_BASE_URL)|--variable\s+host)\s*=\s*['"]?([^\s'"|;&]+)/i.exec(text)?.[1] ?? /https?:\/\/[^\s'"|;&]+/i.exec(text)?.[0];
+    if (!named)
+        return 'local';
+    const value = named.trim();
+    let host;
+    try {
+        const url = new URL(/^[a-z][a-z0-9+.-]*:\/\//i.test(value) ? value : `http://${value}`);
+        host = url.hostname.toLowerCase();
+        if (!/^(?:localhost|127\.0\.0\.1|0\.0\.0\.0|::1|\[::1\])$/.test(host))
+            return url.port ? `${host}:${url.port}` : host;
+    }
+    catch (_error) {
+        // Not a URL at all (a shell variable the command does not expand): compare
+        // the token itself, so the same spelling still reads as the same target.
+        return value.toLowerCase();
+    }
+    return 'local';
+}
+/**
+ * The whole-suite command made scoped to the tests it should re-run instead: the same
+ * invocation — same directory, same settings — with the named `file:line`s in place of the whole
+ * suite, `--last-failed` dropped (it re-runs the tests that never ran too, X1 flash-m60) and
+ * `--retries=0` set (a re-run of a known failure does not need to pay for retries).
+ *
+ * @param command - The whole-suite run's command.
+ * @param locations - The failing `file:line`s to re-run, as the run's own log printed them — or,
+ *   for a run that started outside the suite, the absolute form Playwright matches each file
+ *   argument against.
+ * @returns The scoped command, or the command unchanged when it runs no Playwright suite.
+ */
+export function scopedRerunCommand(command, locations) {
+    const at = command.search(/\bplaywright\s+test\b/);
+    if (at === -1)
+        return command;
+    const head = command.slice(0, at);
+    const rest = command.slice(at);
+    // Only the first statement runs the suite; the rest (`| tail -50`, `&& echo done`)
+    // is left exactly as it was.
+    const end = rest.search(/&&|\|\||;|\|/);
+    const statement = end === -1 ? rest : rest.slice(0, end);
+    const tail = end === -1 ? '' : rest.slice(end);
+    const scoped = statement
+        .replace(/\s*--last-failed\b/g, '')
+        .replace(/\s*--retries(?:[= ]\d+)?/g, '')
+        .replace(/^(playwright\s+test)\b/, `$1 ${locations.join(' ')} --retries=0`);
+    return `${head}${scoped}${tail}`;
+}
+/**
+ * The run in flight that makes a second run a hazard, or null when nothing is in the way.
+ *
+ * This is the ONE rule the mid-run note and the suite-overlap hold both answer with: a suite run
+ * may start only when this returns null, because two suites against one app and database share its
+ * rows — the failures one causes the other cannot be told from real ones. A run that invokes no
+ * suite is never in the way, and neither is one the candidate command stops first.
+ *
+ * @param candidate - The run about to start, by the app and database it would measure
+ *   ({@link suiteCommandTarget}).
+ * @param inFlight - The suite runs already going, in the order the caller found them.
+ * @returns The first run in the way, or null.
+ */
+export function suiteRunInTheWay(candidate, inFlight) {
+    return (inFlight.find((run) => run.runsSuite && run.target === candidate.target && !run.stoppedByCommand) ?? null);
+}
+/**
+ * The Playwright invocation of a command, as its own command-position text (`playwright test …`),
+ * or null when the command starts no Playwright run.
+ *
+ * The runner's own word has to END where the sub-command starts (`(?=\s|$)`, not a `\b`): a
+ * segment can be a fragment beginning at a `playwright test` printed INSIDE a string
+ * (`echo "then npx playwright test" && npx playwright test`), and a match that ends against the
+ * closing quote is that echo. A version-pinned `playwright@1.44.0 test` is the same run.
+ */
+const PLAYWRIGHT_RUN = /^(?:@playwright\/test|playwright)(?:@\S+)?\s+test(?=\s|$)/;
+/**
+ * What narrows a Playwright run to a part of the suite: a named file or line, a title filter, or
+ * the tests the run before it printed (`--last-failed`, `--only-changed`).
+ */
+const NARROWED_RUN = /\.(?:spec|test)\.[cm]?[jt]sx?\b|\.[cm]?[jt]sx?:\d+|(?:^|\s)(?:-g|--grep(?:-invert)?|--last-failed|--only-changed)\b/;
+/**
+ * The Playwright invocation's text when the command starts one, or null.
+ *
+ * @param command - The command as the executor sent it.
+ * @returns The invocation's command-position text, or null.
+ */
+function playwrightRun(command) {
+    return (commandSegments(withoutHeredocs(command)).find((segment) => PLAYWRIGHT_RUN.test(segment.text))
+        ?.text ?? null);
+}
+/**
+ * Whether a `--max-failures` BOUNDS the walk: the flag is given a count above zero.
+ *
+ * Playwright's own spelling of "no cap" is zero — `maxFailures: 0` "disables the feature" — and
+ * that is the flag the platform's `testRunNote` asks for on the uncapped whole-suite run ("run the
+ * whole suite once with `--max-failures=0`"), which is why this is not a plain flag test.
+ *
+ * @param command - The command as the executor sent it.
+ * @returns True when a failure cap would stop the walk.
+ */
+function boundsFailures(command) {
+    const flag = /(?:^|[\s;&|(])--max-failures(?![-\w])/.exec(command);
+    if (!flag)
+        return false;
+    const value = /(?:^|[\s;&|(])--max-failures(?:=|\s+)(['"]?)(\d[\d_]*)/.exec(command)?.[2];
+    // A `--max-failures` with no count at all is not the uncapped spelling of anything: it is read
+    // as a cap, the way Playwright's own default reading of the flag is a count of failures.
+    if (value === undefined)
+        return true;
+    return Number(value.replace(/_/g, '')) !== 0;
+}
+/**
+ * Whether a command walks a PART of a suite instead of all of it: a cap that stops it at a failure
+ * count, the failures the last run printed (`--last-failed`, `--only-changed`), a title filter, or
+ * named files/lines.
+ *
+ * THE one reading of that question, in one place. Two sites act on the answer and must never
+ * disagree:
+ *
+ * - the command rewriter that adds `--retries=0` to a background Playwright run
+ *   ({@link ./utilities.js} `streamingBackgroundCommand`) — a diagnosis walks each failure once,
+ *   while the run the suite is judged by keeps the suite's own retries; and
+ * - the platform's own notes (molecule-dev's `suite-cli-override.ts`), which must not tell the
+ *   executor to drop the `--retries=0` the platform itself has just added — the contradiction X1
+ *   flash-m74 and m75 filed, and m76 filed a third time.
+ *
+ * Until xr-molecule-flash-m89 they were a regex and a predicate that only LOOKED alike, and the
+ * gap was exactly the run the platform had asked for: its `testRunNote` says "run the whole suite
+ * once with `--max-failures=0`", and the rewriter read that cap flag as a capped diagnosis and
+ * stripped the suite's retries from the uncapped proof run that follows a deploy — the one run the
+ * graded run is compared against (+25:03, +31:39, +36:40 and +49:57, the last two against the
+ * deployed URL, where a network blip is likeliest and the retries it dropped are the ones that
+ * absorb it).
+ *
+ * `--max-failures=0` is Playwright's own "no cap" ({@link boundsFailures}), so it is not a
+ * diagnosis. A command that starts no Playwright run is not one either (false): the question is
+ * about a run already read as a Playwright suite.
+ *
+ * @param command - The command as the executor sent it.
+ * @returns True when the run is a diagnosis or a re-run, not the whole suite.
+ */
+export function isDiagnosisRun(command) {
+    if (boundsFailures(command))
+        return true;
+    const run = playwrightRun(command);
+    if (run === null)
+        return false;
+    // A run that only collects and prints (`playwright test --list`, `--version`) walks no part of
+    // the suite either, and is not the whole-suite run the retries belong on.
+    if (commandRunsNoTests(run))
+        return true;
+    return NARROWED_RUN.test(run);
+}

package/dist/tools.d.ts

@@ -39,6 +39,31 @@ import type { ExecutionBackend, ToolBuildConfig } from './types.js';
  * @returns The note, or null when the path is not inside a package's `dist`.
  */
 export declare function moleculeDistReadNote(path: string): string | null;
+/**
+ * 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 declare function installedPackageWriteRefusal(path: string): string | null;
 /**
  * Build a complete set of AI agent tools bound to an execution backend.
  *

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAsE9C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAahG;AAwHD,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAoEnE;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUhE;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CA65DxF"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAiF9C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAahG;AAwHD,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAoEnE;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUhE;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAsBxE;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CAgjExF"}

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
@@ -234,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.
  *
@@ -336,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. */
@@ -887,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 {
@@ -936,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
@@ -973,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`
@@ -1081,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
@@ -1149,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;
@@ -1164,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 });
@@ -1190,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 !== '' &&
@@ -1232,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 }
                         : {
@@ -1251,6 +1442,7 @@ export function buildTools(backend, config) {
                                 : {}),
                             ...syntax,
                         }),
+                    ...(skippedNote ? { skippedNote } : {}),
                     ...(alreadyApplied > 0 ? { alreadyApplied, note: alreadyNote } : {}),
                     totalLines: countLines(finalContent),
                     ...(excerpt ? { excerpt: sanitizeFileContent(excerpt, path) } : {}),
@@ -1369,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)
@@ -1385,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 };
@@ -1408,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 };
@@ -1508,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 });
@@ -1848,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);
@@ -1860,6 +2060,7 @@ export function buildTools(backend, config) {
                         log,
                         stop: universal ? await taskStopCommand(backend, taskId) : '',
                         universal,
+                        ...(started ? { run: started } : {}),
                     }),
                 };
             }