@molecule/api-ai-tools 1.9.2 → 1.9.3

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-17T09:38:26.898Z
+Generated: 2026-10-17T20:38:26.582Z
 -->
 
 # @molecule/api-ai-tools
@@ -352,6 +352,12 @@ interface TraceRequest {
   sent?: string
   /** What came back for that 4xx, bounded the same way — the API's own error body. */
   got?: string
+  /**
+   * The browser's own resource type (`document`, `fetch`, `xhr`, `font`, `image`, `stylesheet`,
+   * `script`, …). `document` when the request was the page load itself; when it ended in a
+   * `net::ERR_*`, nothing rendered and no selector or app request was measured.
+   */
+  type?: string
 }
 ```
 
@@ -757,6 +763,28 @@ interface FailureCause {
    * (xr-molecule-flash-m110 +18:42 rewrote a CORS middleware for a 20 s connection timeout).
    */
   kind: RunFailureKind
+  /**
+   * What the page itself showed at the moment of the failure, when the caller read it from
+   * Playwright's `error-context.md` (the alert / error list). The failure's own error line names
+   * the symptom — `waitForURL` timed out — and never what the page was saying: xr-molecule-flash-
+   * m122 +23:39 grouped eight `waitForURL` timeouts under one line while the page snapshots named
+   * the cause (`email can't be blank`, `username can't be blank` — the settings form submitted
+   * before its values had loaded). Attached to the cause so the fix needs no `cat` of the file.
+   */
+  pageShowed?: string[]
+}
+```
+
+#### `CausePageErrors`
+
+One failing test's page errors, as read from its `error-context.md`.
+
+```typescript
+interface CausePageErrors {
+  /** The test's location as the log prints it (`settings.spec.ts:107`). */
+  where: string
+  /** The alert / error items the page showed at the moment it failed. */
+  items: readonly string[]
 }
 ```
 
@@ -905,6 +933,37 @@ function locatedCommandSegments(command: string): LocatedCommandSegment[]
 
 **Returns:** One entry per statement or pipeline stage, in order.
 
+#### `statementArgumentEnd(command, start, end)`
+
+Where an option of a statement's program belongs: one past the statement's last ARGUMENT.
+
+A flag written "at the end of the command" is not the runner's: a statement can end on a
+redirection (`… 2>&1`), and a statement can sit inside a group whose closer belongs to the
+shell, not to the words (`( … )`, `{ …; }`). Appending after that closer is a different shell
+word that the group has already closed — `… --config=x 2>&1) --reporter=list` is
+`sh: Syntax error: word unexpected`, which killed a backgrounded walk at once and pushed the
+model off the platform's runner shape (xr-molecule-flash-m129 +34:29). Write the option where
+the program's own arguments end and the rest of the statement still parses:
+`… --config=x --reporter=list 2>&1)`.
+
+The statement must be one {@link locatedCommandSegments} placed in THIS command: a statement
+inside a nested `sh -c '<command>'` string has no offsets here (its positions are positions in
+that string), so null is returned rather than a splice into the outer text.
+
+```typescript
+function statementArgumentEnd(
+  command: string,
+  start: number | null,
+  end: number | null,
+): number | null
+```
+
+- `command` — The shell command.
+- `start` — The statement's first character ({@link LocatedCommandSegment.start}).
+- `end` — One past the statement's last character ({@link LocatedCommandSegment.end}).
+
+**Returns:** The offset to write the option at, or null when the statement cannot be placed here.
+
 #### `commandTimeoutSeconds(command)`
 
 The bound a command puts on its own run: the largest `timeout <N>` any of its segments runs
@@ -1340,7 +1399,7 @@ function withSuiteConfig(command: string, config: string | null | undefined): st
 
 **Returns:** The command with the flag, or the command unchanged.
 
-#### `scopedRerunCommand(command, locations, excluded, config)`
+#### `scopedRerunCommand(command, locations, excluded, config, cwd)`
 
 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
@@ -1358,13 +1417,15 @@ function scopedRerunCommand(
   locations: readonly string[],
   excluded?: readonly string[],
   config?: string | null,
+  cwd?: string | null,
 ): 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.
+- `locations` — The failing `file:line`s to re-run, as the run's own log printed them. A location the reporter printed relative to the runner's own directory (`../../fixtures/…`, which no absolute path contains) is resolved here ({@link playwrightLocations}), so the command this returns is one Playwright can match.
 - `excluded` — The test titles the request carves out. They are inverted out (`--grep-invert`) so a re-run of the failing locations cannot report one of them again — xr-molecule-flash-m101 re-ran the whole 139-test suite and spent ~4 minutes to be told about a test the request had already said does not count.
 - `config` — The config the run loaded, when the caller knows it; added when the command does not name one.
+- `cwd` — The directory `exec_command` was given, when it was; the base a location is resolved against when the command does not `cd` anywhere.
 
 **Returns:** The scoped command, or the command unchanged when it runs no Playwright suite.
 
@@ -1615,6 +1676,51 @@ function parseTraceArtifacts(stdout: string): TraceArtifact[]
 
 **Returns:** One entry per trace it printed.
 
+#### `isStaticAssetRequest(request)`
+
+Whether a request is one of the page shell's, not the test's (`STATIC_ASSET_PATH`).
+
+The document itself is never incidental — a page that never loaded IS the failure — and a
+request whose type is the app's own API (`fetch`/`xhr`) is judged by its path alone.
+
+```typescript
+function isStaticAssetRequest(request: TraceRequest): boolean
+```
+
+- `request` — One request a trace recorded.
+
+**Returns:** True when the request is incidental to the step under test.
+
+#### `failedRequest(request)`
+
+Whether a trace recorded a request the server actually failed: a 4xx/5xx, or a network error.
+
+A 404 on a static asset is excepted: `/sw.js` and `/fonts/*` 404 on an app that never shipped
+them, and naming one as a failure sent m125 into writing the caching worker it had asked about.
+A 5xx on an asset, or a network error, still counts — the server did fail.
+
+```typescript
+function failedRequest(request: TraceRequest): boolean
+```
+
+- `request` — One request a trace recorded.
+
+**Returns:** True when the request failed in a way the note should name.
+
+#### `unansweredRequest(request)`
+
+Whether a trace recorded NO response and no reason for it — a request that was aborted or still
+in flight when the test ended. It is not evidence that the server failed (m112 +30:45), and one
+the page shell made is not evidence about the step at all (m125 +29:33).
+
+```typescript
+function unansweredRequest(request: TraceRequest): boolean
+```
+
+- `request` — One request a trace recorded.
+
+**Returns:** True when the request is still in flight and worth naming.
+
 #### `failureTraceNote(items, target, earlierFailures)`
 
 The note a failed suite run's result carries: what each failing test's page actually sent, and
@@ -1935,6 +2041,12 @@ are output-only ({@link isOutputOnlyFilter}): a `| tee` or `| xargs` keeps its p
 caller that reports the run's exit code must then treat it as unknown
 ({@link suiteRunPipedAfterRunner}).
 
+A statement after the run's own pipeline (`; echo done`, `&& echo ok`) does not protect the
+filters before it: the filter is thrown away and the trailing statement is kept, so the log the
+run writes still holds every failure (xr-molecule-flash-m121 — a `| tail -5; echo done` kept its
+tail, and a 95-second walk's log held only the tally while the platform's own hold had handed
+that command back).
+
 ```typescript
 function stripTrailingSuiteFilters(command: string): SuiteFilterStrip
 ```
@@ -2461,28 +2573,65 @@ function repeatingFailure(log: string): RepeatingFailure | null
 
 **Returns:** The repeating cause, or null when no signature has {@link REPEATING_FAILURE_MIN} distinct tests behind it.
 
-#### `universalCause(log, found)`
+#### `specFilesSelected(command)`
 
-Whether a repeating cause is failing the whole run — the one case where stopping it is the
-right call.
+How many test FILES a Playwright run's own command narrows it to, or null when it selects the
+whole suite (or its selection cannot be read).
 
-The test is: the cause accounts for every failure the log names, it has hit
-{@link UNIVERSAL_CAUSE_FILES} spec files or more, and nothing has passed since its first
-failure. An app that is not up, a 5xx on every request, or a selector that is missing on every
-page all look like that, and every remaining test will fail the same way — so the run's
-remaining minutes measure nothing. Anything less is NOT this: a cause that stops at one file,
-or that leaves other tests passing, or that shares the run with failures of another shape,
-leaves the run with something to say, and the run is the only thing that will say it. X1
-flash-m83 (2026-10-16) stopped eight local runs at their first repeating cause over 14.5
-minutes and never finished one; three of its deploys each fixed a single cause that a finished
-run would have listed alongside the others.
+{@link universalCause}'s file threshold is written for a whole-suite run, which a narrowed run
+can never reach. xr-molecule-flash-m119 (+42:08) re-ran ONE spec file against a hand-started
+`vite preview` the browser could not reach, and every test in it failed `page.goto: Timeout` —
+but one file is below {@link UNIVERSAL_CAUSE_FILES}, so the wait sat out its entire 280 s
+budget on a run that had already measured all it could.
+
+The command is read through {@link commandSegments}, so a `playwright test` named as an
+argument is not a run. A {@link PLAYWRIGHT_VALUE_FLAGS} flag written without `=` takes the next
+word as its value, so a `--config app/e2e-suite.config.ts` is never counted as a spec file; a
+directory or a bare substring filter names files the command does not list, which answers null
+(the whole-suite threshold) rather than a count of the wrong files.
 
 ```typescript
-function universalCause(log: string, found: RepeatingFailure): UniversalCause | null
+function specFilesSelected(command: string): number | null
+```
+
+- `command` — The run's command.
+
+**Returns:** The number of distinct test files it names, or null when it names none (the whole suite) or the selection cannot be told.
+
+#### `universalCause(log, found, command)`
+
+Whether a repeating cause is failing the whole run — the one case where stopping it is the
+right call.
+
+The test is: the cause accounts for every failure the log names, it has hit the spec-file
+threshold, and nothing has passed since its first failure. The threshold is
+{@link UNIVERSAL_CAUSE_FILES} for a whole-suite run but the number of files the command
+SELECTED for a narrowed one ({@link specFilesSelected}): a one-file run can never span three,
+and xr-molecule-flash-m119 (+42:08) waited out its whole budget on exactly that shape. An app
+that is not up, a 5xx on every request, or a selector that is missing on every page all look
+like that, and every remaining test will fail the same way — so the run's remaining minutes
+measure nothing. A CONNECTION-class cause ({@link CONNECTION_CAUSE}) needs no file span at all:
+three tests that could not reach the app, with nothing passing since, is the app-unreachable
+case however few files the run walks.
+
+Anything less is NOT this: a cause that stops at one file of a multi-file run, or that leaves
+other tests passing, or that shares the run with failures of another shape, leaves the run with
+something to say, and the run is the only thing that will say it. X1 flash-m83 (2026-10-16)
+stopped eight local runs at their first repeating cause over 14.5 minutes and never finished
+one; three of its deploys each fixed a single cause that a finished run would have listed
+alongside the others.
+
+```typescript
+function universalCause(
+  log: string,
+  found: RepeatingFailure,
+  command?: string | null,
+): UniversalCause | null
 ```
 
 - `log` — The log so far.
 - `found` — The repeating cause {@link repeatingFailure} found in it.
+- `command` — How the run was started, when the caller knows it: its spec-file selection scales the file threshold ({@link specFilesSelected}).
 
 **Returns:** The cause's count and files, or null when the run is not failing whole.
 
@@ -2493,8 +2642,10 @@ for: a PROVEN cause that is failing the whole run.
 
 Both halves are load-bearing, each of them learned from a run that lost minutes to the other.
 
-- **Failing the WHOLE run** is {@link universalCause}: every failure the log names, across
-  {@link UNIVERSAL_CAUSE_FILES} spec files or more, with nothing passing since the first — the
+- **Failing the WHOLE run** is {@link universalCause}: every failure the log names, across the
+  spec-file threshold — {@link UNIVERSAL_CAUSE_FILES}, or the files a narrowed run's own
+  command selects, or {@link CONNECTION_CAUSE_TESTS} tests of an app that never answered — with
+  nothing passing since the first. That is the
   dont-stop-runs rule. X1 flash-m83 (2026-10-16) stopped eight local runs at their first
   repeating cause in 14.5 minutes and never finished one, and a run that still has other causes
   left to name is the only thing that will name them.
@@ -2505,9 +2656,6 @@ Both halves are load-bearing, each of them learned from a run that lost minutes
   xr-molecule-flash-m99 (2026-10-16) was told `status: 'repeating_failure'` twice on that
   shape — three `url-navigation.spec.ts` tests at ~16.2 s, one `timeout: 15_000` plus teardown
   — read the early return as "stop waiting, edit now", and voided a run that was still walking;
-  the second cost a 224 s wait that ended with no result at all.
-
-Neither half alone is enough, and {@link repeatingFailure} finding a signature is not either:
 
 _(description truncated — read the full text in `node_modules/@molecule/api-ai-tools/dist/utilities.d.ts`.)_
 
@@ -2605,6 +2753,7 @@ function failureCausesNote(
   log: string,
   excluded?: readonly string[],
   run?: { command: string; cwd?: string; log?: string; config?: string | null },
+  pageErrors?: readonly CausePageErrors[],
 ): string | null
 ```
 
@@ -2621,11 +2770,11 @@ invocation, in the same directory, narrowed to those tests — or null when the
 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}).
+that run started in, so the composer resolves them there ({@link scopedRerunCommand}): 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(
@@ -2675,12 +2824,13 @@ function repeatingFailureNote(
     stop: string
     universal?: UniversalCause | null
     run?: { command: string; cwd?: string }
+    editsInvalidateRun?: boolean
   },
 ): 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 an {@link earlyReturnCause} — `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.
+- `o` — The run's facts: its `taskId`, its `log` path, `stop` — the shell command that stops it, printed only for an {@link earlyReturnCause} — `universal`, what {@link universalCause} found (absent means the run is not failing whole), `run`, how the run was started ({@link rerunOfRunningSuite}) when the caller knows it, and `editsInvalidateRun`, true when the run measures the sandbox's own app (a local run, where an edit now changes what the suite is testing and its result stops counting).
 
 **Returns:** The note.
 
@@ -3213,6 +3363,15 @@ property of the run rather than of a page.
 const UNIVERSAL_CAUSE_FILES: 3
 ```
 
+#### `CONNECTION_CAUSE_TESTS`
+
+How many tests a connection-class cause must cover before the run is stopped even when they
+are all in one file — see {@link universalCause}.
+
+```typescript
+const CONNECTION_CAUSE_TESTS: 3
+```
+
 #### `PARSE_CHECKABLE`
 
 Files a parse check can vouch for cheaply right after a write.

package/dist/suite-overlap.d.ts

@@ -89,18 +89,21 @@ export declare function withSuiteConfig(command: string, config: string | null |
  * `Cannot navigate to invalid URL` because the re-run loaded no base URL).
  *
  * @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.
+ * @param locations - The failing `file:line`s to re-run, as the run's own log printed them. A
+ *   location the reporter printed relative to the runner's own directory (`../../fixtures/…`,
+ *   which no absolute path contains) is resolved here ({@link playwrightLocations}), so the
+ *   command this returns is one Playwright can match.
  * @param excluded - The test titles the request carves out. They are inverted out
  *   (`--grep-invert`) so a re-run of the failing locations cannot report one of them again —
  *   xr-molecule-flash-m101 re-ran the whole 139-test suite and spent ~4 minutes to be told about
  *   a test the request had already said does not count.
  * @param config - The config the run loaded, when the caller knows it; added when the command
  *   does not name one.
+ * @param cwd - The directory `exec_command` was given, when it was; the base a location is
+ *   resolved against when the command does not `cd` anywhere.
  * @returns The scoped command, or the command unchanged when it runs no Playwright suite.
  */
-export declare function scopedRerunCommand(command: string, locations: readonly string[], excluded?: readonly string[], config?: string | null): string;
+export declare function scopedRerunCommand(command: string, locations: readonly string[], excluded?: readonly string[], config?: string | null, cwd?: string | null): string;
 /**
  * One suite run, as the rule that decides whether a second may start beside it reads it.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"suite-overlap.d.ts","sourceRoot":"","sources":["../src/suite-overlap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAMH;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAoB1D;AAKD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAc1F;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,QAAQ,GAAE,SAAS,MAAM,EAAO,EAChC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GACrB,MAAM,CA8BR;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"}
+{"version":3,"file":"suite-overlap.d.ts","sourceRoot":"","sources":["../src/suite-overlap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAQH;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAoB1D;AAKD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAc1F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,QAAQ,GAAE,SAAS,MAAM,EAAO,EAChC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,EACtB,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,GAClB,MAAM,CAqCR;AA8ID;;;;;;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"}

package/dist/suite-overlap.js

@@ -28,7 +28,8 @@
  *
  * @module
  */
-import { commandSegments } from './command-position.js';
+import { posix } from 'node:path';
+import { commandSegments, locatedCommandSegments } from './command-position.js';
 import { commandRunsNoTests } from './no-test-run.js';
 import { shellQuote } from './utilities.js';
 /**
@@ -131,18 +132,21 @@ export function withSuiteConfig(command, config) {
  * `Cannot navigate to invalid URL` because the re-run loaded no base URL).
  *
  * @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.
+ * @param locations - The failing `file:line`s to re-run, as the run's own log printed them. A
+ *   location the reporter printed relative to the runner's own directory (`../../fixtures/…`,
+ *   which no absolute path contains) is resolved here ({@link playwrightLocations}), so the
+ *   command this returns is one Playwright can match.
  * @param excluded - The test titles the request carves out. They are inverted out
  *   (`--grep-invert`) so a re-run of the failing locations cannot report one of them again —
  *   xr-molecule-flash-m101 re-ran the whole 139-test suite and spent ~4 minutes to be told about
  *   a test the request had already said does not count.
  * @param config - The config the run loaded, when the caller knows it; added when the command
  *   does not name one.
+ * @param cwd - The directory `exec_command` was given, when it was; the base a location is
+ *   resolved against when the command does not `cd` anywhere.
  * @returns The scoped command, or the command unchanged when it runs no Playwright suite.
  */
-export function scopedRerunCommand(command, locations, excluded = [], config) {
+export function scopedRerunCommand(command, locations, excluded = [], config, cwd) {
     const at = command.search(/\bplaywright\s+test\b/);
     if (at === -1)
         return command;
@@ -165,12 +169,155 @@ export function scopedRerunCommand(command, locations, excluded = [], config) {
     // The run's own config: the command's `--config` when it has one, else the config the caller
     // recorded for the run. A re-run without it measures nothing (m113).
     const carry = config && !namesSuiteConfig(statement) ? ` --config ${shellQuote(config)}` : '';
-    const scoped = statement
+    // Playwright matches each positional argument as a regex against the ABSOLUTE path of every test
+    // file it collects (`playwright test --help`: "Each argument is treated as a regular expression.
+    // Matching is performed against the absolute file paths."), while the reporter prints a failure
+    // relative to the runner's own directory. A `../../fixtures/…` location therefore matches
+    // nothing — "No tests found" — so every location is rendered in a form Playwright can match
+    // ({@link playwrightLocations}).
+    const narrowed = playwrightLocations(locations, command, cwd);
+    const scoped = dropSupersededSpecFiles(statement, narrowed)
         .replace(/\s*--last-failed\b/g, '')
         .replace(/\s*--retries(?:[= ]\d+)?/g, '')
-        .replace(/^(playwright\s+test)\b/, `$1 ${locations.join(' ')} --retries=0${carry}${invert}`);
+        .replace(/^(playwright\s+test)\b/, `$1 ${narrowed.join(' ')} --retries=0${carry}${invert}`);
     return `${head}${scoped}${tail}`;
 }
+/** A directory a `cd` can name literally: no `~`, no variable, no glob. */
+const LITERAL_DIR = /^[A-Za-z0-9_./+-]+$/;
+/** A word without its shell quotes. */
+const unquoted = (word) => word.replace(/^['"]|['"]$/g, '');
+/**
+ * The absolute directory the Playwright statement in a command runs in, or null when the command
+ * does not say.
+ *
+ * The reporter prints a failing test's file relative to the process directory the runner started
+ * in (`../fixtures/…` from a run whose suite lives outside its own tree), so the directory has to
+ * come from the command itself: `exec_command`'s `cwd` when it was given, then each `cd` before
+ * the runner. Only a literal `cd` is followed — a target holding a variable, a glob or `~`
+ * resolves nowhere useful, and a guessed absolute path is worse than the relative one the
+ * reporter printed.
+ *
+ * @param command - The shell command.
+ * @param cwd - The `cwd` the tool was given, when it was.
+ * @returns The absolute directory, or null.
+ */
+function suiteRunDirectory(command, cwd) {
+    let dir = typeof cwd === 'string' && cwd.startsWith('/') ? posix.normalize(cwd) : null;
+    for (const { segment } of locatedCommandSegments(command)) {
+        if (segment === null)
+            continue;
+        if (segment.program === 'cd') {
+            const target = unquoted(segment.args[0] ?? '').replace(/\/+$/, '');
+            if (!target || target.startsWith('-') || target.startsWith('~') || !LITERAL_DIR.test(target))
+                return null;
+            // A shell `cd /abs` DISCARDS the directory before it; only a relative target resolves
+            // against the one the run started in.
+            if (target.startsWith('/'))
+                dir = posix.normalize(target);
+            else if (dir === null)
+                return null;
+            else
+                dir = posix.normalize(posix.join(dir, target));
+            continue;
+        }
+        if (segment.program === 'playwright' && segment.args[0] === 'test')
+            break;
+    }
+    return dir;
+}
+/** A failure location's path and its `:line[:column]` suffix, split the way Playwright does. */
+const LOCATION_LINE = /^(.*?)(:\d+(?::\d+)?)$/;
+/**
+ * Each location in a form Playwright matches, so a re-run composed from a run's own report can
+ * actually run.
+ *
+ * Playwright compiles every positional file argument into a regex and tests it against the
+ * absolute path of each collected test file (`playwright test --help`; `createFiltersFromArguments`
+ * → `forceRegExp` → `createFileMatcher`, verified against Playwright 1.63 with `--list`: the
+ * reporter's `../../fixtures/…/articles.spec.ts:3` lists 0 tests, the absolute path lists 1). A
+ * location the reporter printed relative to the runner's directory is resolved against it; where
+ * that directory cannot be known, only the leading `./`/`../` segments are dropped, which leaves a
+ * suffix the absolute path still contains (`fixtures/…/articles.spec.ts:3` matches).
+ *
+ * A location without a leading dot is left alone: it is either absolute or already a suffix of the
+ * absolute path, and rewriting it against a mis-guessed base could only break it
+ * (xr-molecule-flash-m118 +16:34 "No tests found"; m124 +18:38 the platform's own "Re-run just
+ * these" command).
+ *
+ * @param locations - The failing `file:line`s as the run's log printed them.
+ * @param command - The run's command, for its own `cd`s.
+ * @param cwd - The `cwd` the tool was given, when it was.
+ * @returns The locations, matchable by Playwright.
+ */
+function playwrightLocations(locations, command, cwd) {
+    const base = suiteRunDirectory(command, cwd);
+    return locations.map((location) => {
+        const [, file = '', suffix = ''] = LOCATION_LINE.exec(location) ?? [];
+        if (!file.startsWith('./') && !file.startsWith('../'))
+            return location;
+        const resolved = base === null ? file.replace(/^(?:\.{1,2}\/)+/, '') : posix.resolve(base, file);
+        return `${resolved}${suffix}`;
+    });
+}
+/** A spec-file argument Playwright accepts as its positional filter — never a flag. */
+const SPEC_FILE_ARGUMENT = /^(?!-)[^\s]*\.(?:spec|test)\.[cm]?[jt]sx?(?::\d+(?::\d+)?)?$/;
+/**
+ * A `file:line` location's own file part: Playwright prints failures as
+ * `url-navigation.spec.ts:13:7`, and the file is the argument that supersedes.
+ *
+ * @param location - A location (`file.spec.ts:13`, `file.spec.ts:13:7`) or a spec-file argument.
+ * @returns The path without its line numbers.
+ */
+function locationFile(location) {
+    return location.replace(/:\d+(?::\d+)?$/, '');
+}
+/**
+ * Whether two spellings name the same spec file: equal, or one the absolute (or longer) form of
+ * the other. The command and the reporter routinely spell the same file differently — the model
+ * names `url-navigation.spec.ts`, the summary prints `specs/e2e/url-navigation.spec.ts:13`, and a
+ * hold hands back `/workspace/fixtures/realworld/specs/e2e/url-navigation.spec.ts:13`.
+ *
+ * @param argument - The spec-file argument as the command wrote it.
+ * @param location - The failing location.
+ * @returns True when the location is inside that file.
+ */
+function sameSpecFile(argument, location) {
+    const a = locationFile(argument)
+        .replace(/^['"]|['"]$/g, '')
+        .replace(/^\.\//, '');
+    const l = locationFile(location)
+        .replace(/^['"]|['"]$/g, '')
+        .replace(/^\.\//, '');
+    return a === l || a.endsWith(`/${l}`) || l.endsWith(`/${a}`);
+}
+/**
+ * The statement with every spec-file argument its OWN failure locations already name taken out.
+ *
+ * A `file:line` inside a named file supersedes the whole file, so keeping both runs the file plus
+ * the locations — the whole suite again, with the failures duplicated inside it. xr-molecule-flash-m118
+ * (+45:24) composed just that: the model's `npx playwright test … url-navigation.spec.ts` was
+ * narrowed to the 14 `file:line`s AND the bare file, "~297s" for a file and fourteen duplicates.
+ *
+ * @param statement - The Playwright statement, starting at its own `playwright test`.
+ * @param locations - The failing `file:line`s the re-run names.
+ * @returns The statement without those superseded file arguments.
+ */
+function dropSupersededSpecFiles(statement, locations) {
+    if (locations.length === 0)
+        return statement;
+    const runner = /^(playwright\s+test)\b/.exec(statement);
+    if (runner === null)
+        return statement;
+    const head = runner[1];
+    const kept = statement
+        .slice(head.length)
+        .replace(/(^|\s+)([^\s]+)(?=\s|$)/g, (whole, _space, token) => {
+        if (!SPEC_FILE_ARGUMENT.test(token))
+            return whole;
+        return locations.every((location) => sameSpecFile(token, location)) ? '' : whole;
+    });
+    return `${head}${kept}`;
+}
 /**
  * The run in flight that makes a second run a hazard, or null when nothing is in the way.
  *

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;AAiJ9C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAahG;AAiOD,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAmEnE;;;GAGG;AACH,eAAO,MAAM,iBAAiB,QAEA,CAAA;AAE9B;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,wBAAwB,QAI6C,CAAA;AAmBlF;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUhE;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,qBAAqB;IACpC,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,8FAA8F;IAC9F,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAC5B;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAA;AAoBpF;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,CAAC,GACxE,qBAAqB,CAkBvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAsB,4BAA4B,CAChD,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,qBAAqB,GAC5B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiCxB;AAgDD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CAy3ExF"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAiJ9C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAahG;AAkOD,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAmEnE;;;GAGG;AACH,eAAO,MAAM,iBAAiB,QAEA,CAAA;AAE9B;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,wBAAwB,QAI6C,CAAA;AAmBlF;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUhE;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,qBAAqB;IACpC,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,8FAA8F;IAC9F,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAC5B;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAA;AAoBpF;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,CAAC,GACxE,qBAAqB,CAkBvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAsB,4BAA4B,CAChD,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,qBAAqB,GAC5B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiCxB;AA8ED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CAk6ExF"}