@molecule/api-ai-tools 1.6.2 → 1.6.5

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-10-16T15:37:48.365Z
+Generated: 2026-10-16T19:48:43.608Z
 -->
 
 # @molecule/api-ai-tools
@@ -132,6 +132,29 @@ interface ToolSchema {
 }
 ```
 
+#### `SuiteRunInFlight`
+
+One suite run, as the rule that decides whether a second may start beside it reads it.
+
+Both callers describe the runs in flight the same way and ask the same question of them; what
+differs is only which runs each one knows about — the hold reads its ledger of background runs,
+the note reads the one run it is waiting on.
+
+```typescript
+interface SuiteRunInFlight {
+  /** Whether the run invokes a suite at all: a `vitest`/`jest` run is not one, and cannot be. */
+  runsSuite: boolean
+  /** The app and database the run measures, as {@link suiteCommandTarget} keys it. */
+  target: string
+  /**
+   * Whether the command being judged STOPS this run before starting its own — a kill comes first,
+   * so a run the command itself stops is not in the way (xr-molecule-flash-m87's
+   * `kill 19408 … ; npx playwright test …`).
+   */
+  stoppedByCommand?: boolean
+}
+```
+
 #### `ExecutionBackend`
 
 Abstraction over the execution environment.
@@ -606,6 +629,108 @@ function commandRunsNoTests(command: string): boolean
 
 **Returns:** True when the command invokes a runner only to print.
 
+#### `withoutHeredocs(command)`
+
+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.
+
+```typescript
+function withoutHeredocs(command: string): string
+```
+
+- `command` — The shell command.
+
+**Returns:** The command without its heredoc bodies.
+
+#### `suiteCommandTarget(command)`
+
+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).
+
+```typescript
+function suiteCommandTarget(command: string): string
+```
+
+- `command` — The suite command.
+
+**Returns:** The target key.
+
+#### `scopedRerunCommand(command, locations)`
+
+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).
+
+```typescript
+function scopedRerunCommand(command: string, locations: readonly string[]): string
+```
+
+- `command` — The whole-suite run's command.
+- `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.
+
+#### `suiteRunInTheWay(candidate, inFlight)`
+
+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.
+
+```typescript
+function suiteRunInTheWay(candidate: { target: string }, inFlight: readonly T[]): T | null
+```
+
+- `candidate` — The run about to start, by the app and database it would measure ({@link suiteCommandTarget}).
+- `inFlight` — The suite runs already going, in the order the caller found them.
+
+**Returns:** The first run in the way, or null.
+
+#### `isDiagnosisRun(command)`
+
+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
+
+_(description truncated — read the full text in `node_modules/@molecule/api-ai-tools/dist/suite-overlap.d.ts`.)_
+
+```typescript
+function isDiagnosisRun(command: string): boolean
+```
+
+- `command` — The command as the executor sent it.
+
+**Returns:** True when the run is a diagnosis or a re-run, not the whole suite.
+
 #### `discoverSkills(backend)`
 
 Discover skills from a project directory.
@@ -644,6 +769,27 @@ function buildAgentPrompt(ctx: PromptContext): string
 
 **Returns:** Fully assembled system prompt text for the coding agent.
 
+#### `taskStopCommand(backend, taskId)`
+
+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.
+
+```typescript
+function taskStopCommand(backend: ExecutionBackend, taskId: string): Promise<string>
+```
+
+- `backend` — The execution backend.
+- `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).
+
 #### `moleculeDistReadNote(path)`
 
 The steer attached to a SUCCESSFUL read of a package's built output. The ENOENT
@@ -662,6 +808,36 @@ function moleculeDistReadNote(path: string): string | null
 
 **Returns:** The note, or null when the path is not inside a package's `dist`.
 
+#### `installedPackageWriteRefusal(path)`
+
+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.
+
+```typescript
+function installedPackageWriteRefusal(path: string): string | null
+```
+
+- `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.
+
 #### `buildTools(backend, config)`
 
 Build a complete set of AI agent tools bound to an execution backend.
@@ -1343,6 +1519,31 @@ function failureCausesNote(log: string): string | null
 
 **Returns:** The note, or null.
 
+#### `rerunOfRunningSuite(run, locations)`
+
+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}).
+
+```typescript
+function rerunOfRunningSuite(
+  run: { command: string; cwd?: string },
+  locations: readonly string[],
+): string | null
+```
+
+- `run` — The run in flight: the command it was started with, as it was run, and the directory that command ran in.
+- `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.
+
 #### `repeatingFailureNote(found, o)`
 
 The sentence that names a cause repeating among a running suite's failures, mid-run.
@@ -1358,15 +1559,30 @@ cause was certain at the third, 47 s in, and the note answers exactly that; X1 f
 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
+
+_(description truncated — read the full text in `node_modules/@molecule/api-ai-tools/dist/utilities.d.ts`.)_
+
 ```typescript
 function repeatingFailureNote(
   found: RepeatingFailure,
-  o: { taskId: string; log: string; stop: string; universal?: UniversalCause | null },
+  o: {
+    taskId: string
+    log: string
+    stop: string
+    universal?: UniversalCause | null
+    run?: { command: string; cwd?: string }
+  },
 ): string
 ```
 
 - `found` — What {@link repeatingFailure} found.
-- `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).
+- `o` — The run's facts: its `taskId`, its `log` path, `stop` — the shell command that 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.
 
@@ -1779,6 +1995,18 @@ Peer dependencies:
   `newlineNote` hint beside an unrelated-looking parse error, which an executor
   repairs by rewriting the fused line's text and fuses the next one. The
   `newlineNote` alone is still returned when the file parses.
+- **A replacement that only changes a line break at its boundary is refused,
+  not applied.** When `new_string` is `old_string` with its trailing newline
+  added or removed and nothing else, the edit can only move text across lines —
+  joining the next line onto the replaced text, or pushing the rest of the line
+  down — which is what a weak model does by accident when it repeats a line it
+  means to keep (flash-m28, m55, m62, m89, five times in the m89 run alone). The
+  replacement is skipped, the rest of the batch is applied, and the result
+  carries `skippedNote`: one line naming the replacement, what applying it would
+  have done, and how to say it on purpose (include the next line in `old_string`).
+  The file's own next character decides: text on the same line is a join or a
+  split and is refused; a blank line after it, or the end of the file, means no
+  text crosses lines and the edit is applied as written.
 - **A parameter under another name is not a broken tool.** Every tool's input
   is normalized first (`cmd` → `command`, `file` → `path`, camelCase ⇄
   snake_case), and a handler that throws returns an error naming the missing

package/dist/command-position.d.ts

@@ -22,7 +22,7 @@
  * (`head -30 run-api-tests-hurl.sh`, `grep -n playwright e2e/README.md`,
  * `git show HEAD:run-api-tests.sh`), and a runner named in a heredoc body — a file a command
  * WRITES is the caller's business, so a command with a heredoc goes through the caller's own
- * stripper first (`withoutHeredocs` in molecule-dev's suite checks).
+ * stripper first (`withoutHeredocs`, in `./suite-overlap.js`).
  *
  * @module
  */

package/dist/command-position.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-position.d.ts","sourceRoot":"","sources":["../src/command-position.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;IACf,qFAAqF;IACrF,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IACvB,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAA;CACb;AAqRD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAEjE;AA+BD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAK/E"}
+{"version":3,"file":"command-position.d.ts","sourceRoot":"","sources":["../src/command-position.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;IACf,qFAAqF;IACrF,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IACvB,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAA;CACb;AA8TD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAEjE;AA+BD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAK/E"}

package/dist/command-position.js

@@ -22,7 +22,7 @@
  * (`head -30 run-api-tests-hurl.sh`, `grep -n playwright e2e/README.md`,
  * `git show HEAD:run-api-tests.sh`), and a runner named in a heredoc body — a file a command
  * WRITES is the caller's business, so a command with a heredoc goes through the caller's own
- * stripper first (`withoutHeredocs` in molecule-dev's suite checks).
+ * stripper first (`withoutHeredocs`, in `./suite-overlap.js`).
  *
  * @module
  */
@@ -206,50 +206,84 @@ function commandStart(words) {
  * A single `&` separates only when it backgrounds a command: the one in a redirect (`2>&1`,
  * `&>log`) is part of the word it sits in.
  *
+ * The nestings are a STACK, not a (quote, depth) pair, because they interleave: a command
+ * substitution opened inside a double quote can itself hold double quotes, and each of those can
+ * hold another substitution. `DIR="$(cd "$(dirname "$0")" && pwd)"` is exactly that shape — it
+ * opens `"`, `$(`, `"`, `$(`, `"` in order — and every runner script of the RealWorld kind has it.
+ * A flat walk read that first inner `"` as the CLOSE of the outer one, so the `)` that ends the
+ * outer substitution landed inside a quote that was never opened, the depth was left standing at
+ * 1, and every newline in the rest of the script was swallowed: the script's own `hurl --test`
+ * never reached command position, and X1 xr-molecule-flash-m89 saw seven passing Hurl runs the
+ * platform could not see (the runner is read from the tree's own script TEXT —
+ * `molecule-dev/api/src/ai/supplied-tree-guard.ts` — so a script that does not classify records
+ * no runner, and every run of it reads as nothing).
+ *
  * @param command - The shell command.
  * @returns Each segment's text, in order, with empty ones dropped.
  */
 function splitSegments(command) {
     const parts = [];
     let buffer = '';
-    let quote = null;
-    let substitutions = 0;
+    /** The nestings this position sits inside, outermost first. */
+    const stack = [];
     for (let i = 0; i < command.length; i++) {
         const char = command[i] ?? '';
-        if (quote !== null) {
+        const next = command[i + 1];
+        const top = stack[stack.length - 1];
+        // A single-quoted string expands nothing at all: no escape, no substitution, and no quote
+        // but its own ends it.
+        if (top === 'single') {
             buffer += char;
-            if (char === '\\' && quote === '"' && i + 1 < command.length) {
-                buffer += command[i + 1] ?? '';
-                i += 1;
-            }
-            else if (char === quote)
-                quote = null;
+            if (char === "'")
+                stack.pop();
             continue;
         }
-        if (char === '"' || char === "'") {
-            quote = char;
+        // A command substitution, wherever a shell opens one — inside double quotes too, and never
+        // inside single quotes (handled above). The `(` is consumed here so the depth is counted once.
+        if (char === '$' && next === '(') {
+            stack.push('sub');
+            buffer += '$(';
+            i += 1;
+            continue;
+        }
+        // Inside double quotes: a `"` closes them, a backslash escapes the next character (so
+        // `"\$("` opens nothing), and everything else is literal — a `'`, a `|`, a newline included.
+        if (top === 'double') {
+            if (char === '"')
+                stack.pop();
+            else if (char === '\\' && next !== undefined) {
+                buffer += char + next;
+                i += 1;
+                continue;
+            }
             buffer += char;
             continue;
         }
-        if (char === '\\' && i + 1 < command.length) {
-            buffer += char + (command[i + 1] ?? '');
-            i += 1;
+        if (char === '"') {
+            stack.push('double');
+            buffer += char;
             continue;
         }
-        if (char === '$' && command[i + 1] === '(') {
-            substitutions += 1;
+        if (char === "'") {
+            stack.push('single');
             buffer += char;
             continue;
         }
-        if (substitutions > 0) {
+        // Inside a substitution or a subshell of one: its own parentheses nest, its `|`/`;`/`&&`
+        // belong to the nested command, and its newlines are that command's too.
+        if (top === 'sub') {
             if (char === '(')
-                substitutions += 1;
+                stack.push('sub');
             else if (char === ')')
-                substitutions -= 1;
+                stack.pop();
             buffer += char;
             continue;
         }
-        const next = command[i + 1];
+        if (char === '\\' && next !== undefined) {
+            buffer += char + next;
+            i += 1;
+            continue;
+        }
         if ((char === '&' && next === '&') || (char === '|' && next === '|')) {
             parts.push(buffer);
             buffer = '';

package/dist/index.d.ts

@@ -51,6 +51,18 @@
  *   `newlineNote` hint beside an unrelated-looking parse error, which an executor
  *   repairs by rewriting the fused line's text and fuses the next one. The
  *   `newlineNote` alone is still returned when the file parses.
+ * - **A replacement that only changes a line break at its boundary is refused,
+ *   not applied.** When `new_string` is `old_string` with its trailing newline
+ *   added or removed and nothing else, the edit can only move text across lines —
+ *   joining the next line onto the replaced text, or pushing the rest of the line
+ *   down — which is what a weak model does by accident when it repeats a line it
+ *   means to keep (flash-m28, m55, m62, m89, five times in the m89 run alone). The
+ *   replacement is skipped, the rest of the batch is applied, and the result
+ *   carries `skippedNote`: one line naming the replacement, what applying it would
+ *   have done, and how to say it on purpose (include the next line in `old_string`).
+ *   The file's own next character decides: text on the same line is a join or a
+ *   split and is refused; a blank line after it, or the end of the file, means no
+ *   text crosses lines and the edit is applied as written.
  * - **A parameter under another name is not a broken tool.** Every tool's input
  *   is normalized first (`cmd` → `command`, `file` → `path`, camelCase ⇄
  *   snake_case), and a handler that throws returns an error naming the missing
@@ -124,6 +136,7 @@ export * from './command-position.js';
 export * from './input-normalizer.js';
 export * from './no-test-run.js';
 export * from './schemas.js';
+export * from './suite-overlap.js';
 export * from './system-prompt.js';
 export * from './tools.js';
 export * from './types.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsHG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,uBAAuB,CAAA;AACrC,cAAc,kBAAkB,CAAA;AAChC,cAAc,cAAc,CAAA;AAC5B,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkIG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,uBAAuB,CAAA;AACrC,cAAc,kBAAkB,CAAA;AAChC,cAAc,cAAc,CAAA;AAC5B,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}

package/dist/index.js

@@ -51,6 +51,18 @@
  *   `newlineNote` hint beside an unrelated-looking parse error, which an executor
  *   repairs by rewriting the fused line's text and fuses the next one. The
  *   `newlineNote` alone is still returned when the file parses.
+ * - **A replacement that only changes a line break at its boundary is refused,
+ *   not applied.** When `new_string` is `old_string` with its trailing newline
+ *   added or removed and nothing else, the edit can only move text across lines —
+ *   joining the next line onto the replaced text, or pushing the rest of the line
+ *   down — which is what a weak model does by accident when it repeats a line it
+ *   means to keep (flash-m28, m55, m62, m89, five times in the m89 run alone). The
+ *   replacement is skipped, the rest of the batch is applied, and the result
+ *   carries `skippedNote`: one line naming the replacement, what applying it would
+ *   have done, and how to say it on purpose (include the next line in `old_string`).
+ *   The file's own next character decides: text on the same line is a join or a
+ *   split and is refused; a blank line after it, or the end of the file, means no
+ *   text crosses lines and the edit is applied as written.
  * - **A parameter under another name is not a broken tool.** Every tool's input
  *   is normalized first (`cmd` → `command`, `file` → `path`, camelCase ⇄
  *   snake_case), and a handler that throws returns an error naming the missing
@@ -124,6 +136,7 @@ export * from './command-position.js';
 export * from './input-normalizer.js';
 export * from './no-test-run.js';
 export * from './schemas.js';
+export * from './suite-overlap.js';
 export * from './system-prompt.js';
 export * from './tools.js';
 export * from './types.js';

package/dist/suite-overlap.d.ts

@@ -0,0 +1,132 @@
+/**
+ * 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
+ */
+/**
+ * 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 declare function withoutHeredocs(command: string): string;
+/**
+ * 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 declare function suiteCommandTarget(command: string): string;
+/**
+ * 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 declare function scopedRerunCommand(command: string, locations: readonly string[]): string;
+/**
+ * One suite run, as the rule that decides whether a second may start beside it reads it.
+ *
+ * Both callers describe the runs in flight the same way and ask the same question of them; what
+ * differs is only which runs each one knows about — the hold reads its ledger of background runs,
+ * the note reads the one run it is waiting on.
+ */
+export interface SuiteRunInFlight {
+    /** Whether the run invokes a suite at all: a `vitest`/`jest` run is not one, and cannot be. */
+    runsSuite: boolean;
+    /** The app and database the run measures, as {@link suiteCommandTarget} keys it. */
+    target: string;
+    /**
+     * Whether the command being judged STOPS this run before starting its own — a kill comes first,
+     * so a run the command itself stops is not in the way (xr-molecule-flash-m87's
+     * `kill 19408 … ; npx playwright test …`).
+     */
+    stoppedByCommand?: boolean;
+}
+/**
+ * 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 declare function suiteRunInTheWay<T extends SuiteRunInFlight>(candidate: {
+    target: string;
+}, inFlight: readonly T[]): T | null;
+/**
+ * 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 declare function isDiagnosisRun(command: string): boolean;
+//# sourceMappingURL=suite-overlap.d.ts.map

package/dist/suite-overlap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suite-overlap.d.ts","sourceRoot":"","sources":["../src/suite-overlap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAKH;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAoB1D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAexF;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+FAA+F;IAC/F,SAAS,EAAE,OAAO,CAAA;IAClB,oFAAoF;IACpF,MAAM,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAC3B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,gBAAgB,EACzD,SAAS,EAAE;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,EAC7B,QAAQ,EAAE,SAAS,CAAC,EAAE,GACrB,CAAC,GAAG,IAAI,CAMV;AAqDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAQvD"}