@molecule/api-ai-tools 1.9.2 → 1.9.4

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/command-position.d.ts

@@ -124,6 +124,28 @@ export interface LocatedCommandSegment {
  * @returns One entry per statement or pipeline stage, in order.
  */
 export declare function locatedCommandSegments(command: string): LocatedCommandSegment[];
+/**
+ * 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.
+ *
+ * @param command - The shell command.
+ * @param start - The statement's first character ({@link LocatedCommandSegment.start}).
+ * @param 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.
+ */
+export declare function statementArgumentEnd(command: string, start: number | null, end: number | null): number | null;
 /**
  * The bound a command puts on its own run: the largest `timeout <N>` any of its segments runs
  * under (`timeout 280 hurl --test …` → 280), or null when it carries none.

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;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;IACZ;;;OAGG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AA2MD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM3D;AA+cD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAIjE;AAmCD;;;;;;;;;GASG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,OAAO,EAAE,cAAc,GAAG,IAAI,CAAA;IAC9B,0FAA0F;IAC1F,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B;;;;OAIG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB;;;;;OAKG;IACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B;;;OAGG;IACH,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB;;;;OAIG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB,EAAE,CAE/E;AA4ED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOpE;AAED;;;;;;;;;;;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;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;IACZ;;;OAGG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AAqND;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM3D;AA+cD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAIjE;AAmCD;;;;;;;;;GASG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,OAAO,EAAE,cAAc,GAAG,IAAI,CAAA;IAC9B,0FAA0F;IAC1F,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B;;;;OAIG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB;;;;;OAKG;IACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B;;;OAGG;IACH,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB;;;;OAIG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB,EAAE,CAE/E;AAmDD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,GAAG,EAAE,MAAM,GAAG,IAAI,GACjB,MAAM,GAAG,IAAI,CAyDf;AA4ED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOpE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAK/E"}

package/dist/command-position.js

@@ -36,6 +36,14 @@
 const WORD = /"(?:\\.|[^"\\])*"|'[^']*'|\S+/g;
 /** Shell words that stand alone: grouping, never an argument. */
 const GROUPING = new Set(['(', ')', '{', '}']);
+/**
+ * A redirection written as ONE word, its target attached: `2>&1`, `>out.log`, `&>/dev/null`,
+ * `<<'EOF'`. Matched against a word of the statement, so a redirect's target written as its own
+ * word is {@link REDIRECT_OPERATOR}'s case instead.
+ */
+const REDIRECT_WORD = /^(?:\d*|&)(?:<<<|<<-?|>>?\|?|<>|>&|<&)(?:&?\d+|-|[^\s;&|()<>]*)?$/;
+/** A redirection operator on its own, whose target is the word after it (`> out.log`). */
+const REDIRECT_OPERATOR = /^(?:\d*|&)(?:<<<|<<-?|>>?\|?|<>|>&|<&)$/;
 /** How deep a `sh -c '<command>'` is opened before the parser leaves it alone. */
 const MAX_NESTING = 3;
 /** How many wrapper words one segment may carry before the parser gives up on it. */
@@ -744,6 +752,142 @@ function wordOffset(text, index) {
 export function locatedCommandSegments(command) {
     return locatedSegmentsOf(command, 0);
 }
+/**
+ * How many `$( … )` and `${ … }` expansions a piece of shell text has open at its end.
+ *
+ * Quotes are honoured (a `'$('` expands nothing, and `"$("` opens one), and a backslash escapes
+ * the next character. Only `$(`/`${` are counted: a bare `(` or `{` opens a group whose closer is
+ * the statement's own punctuation and may be stepped over, while an expansion opened inside the
+ * statement is an argument in progress, and its closer must not be crossed.
+ *
+ * @param text - The statement's text, up to (not including) the position being asked about.
+ * @returns The open parentheses and braces.
+ */
+function substitutionDepth(text) {
+    let parens = 0;
+    let braces = 0;
+    let quote = null;
+    for (let i = 0; i < text.length; i++) {
+        const char = text[i] ?? '';
+        if (quote === "'") {
+            if (char === "'")
+                quote = null;
+            continue;
+        }
+        if (char === '\\') {
+            i += 1;
+            continue;
+        }
+        if (char === "'" && quote === null) {
+            quote = "'";
+            continue;
+        }
+        if (char === '"') {
+            quote = quote === '"' ? null : '"';
+            continue;
+        }
+        if (char === '$' && text[i + 1] === '(') {
+            parens += 1;
+            i += 1;
+            continue;
+        }
+        if (char === '$' && text[i + 1] === '{') {
+            braces += 1;
+            i += 1;
+            continue;
+        }
+        if (char === ')' && parens > 0)
+            parens -= 1;
+        else if (char === '}' && braces > 0)
+            braces -= 1;
+    }
+    return { parens, braces };
+}
+/**
+ * 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.
+ *
+ * @param command - The shell command.
+ * @param start - The statement's first character ({@link LocatedCommandSegment.start}).
+ * @param 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.
+ */
+export function statementArgumentEnd(command, start, end) {
+    if (start === null || end === null)
+        return null;
+    if (!Number.isInteger(start) || !Number.isInteger(end))
+        return null;
+    if (start < 0 || end > command.length || end < start)
+        return null;
+    let at = end;
+    // Group closers are the shell's words, not the program's: `… 2>&1)` and `… ; }` end the
+    // statement with punctuation no option can follow. A `)` that closes a `$(` opened INSIDE the
+    // statement is not one of those — it is the last character of an argument
+    // (`… $(cat e2e/args.txt)`), and crossing it would write the option inside the substitution.
+    for (;;) {
+        let cursor = at;
+        while (cursor > start && /\s/.test(command[cursor - 1] ?? ''))
+            cursor -= 1;
+        const closer = command[cursor - 1];
+        if (closer !== ')' && closer !== '}') {
+            at = cursor;
+            break;
+        }
+        const open = substitutionDepth(command.slice(start, cursor - 1));
+        if ((closer === ')' && open.parens > 0) || (closer === '}' && open.braces > 0)) {
+            at = cursor;
+            break;
+        }
+        at = cursor - 1;
+    }
+    const words = [...command.slice(start, at).matchAll(new RegExp(WORD.source, 'g'))].map((m) => ({
+        text: m[0],
+        index: start + (m.index ?? 0),
+    }));
+    // A trailing redirection belongs to the statement but is not an argument of its program. An
+    // option written after it would still parse, but the option belongs with the program's own
+    // words (`… --flag 2>&1`, not `… 2>&1 --flag`), so every redirect suffix is stepped over.
+    while (words.length > 0) {
+        const last = words[words.length - 1];
+        if (last === undefined)
+            break;
+        if (GROUPING.has(last.text) || REDIRECT_WORD.test(last.text)) {
+            at = last.index;
+            words.pop();
+            continue;
+        }
+        const operator = words[words.length - 2];
+        if (operator !== undefined && REDIRECT_OPERATOR.test(operator.text)) {
+            at = operator.index;
+            words.pop();
+            words.pop();
+            // `2 > out.log` spells the same redirect as `2>out.log`: the descriptor is the word before
+            // the operator, and an option written between them would turn it into an argument.
+            const descriptor = words[words.length - 1];
+            if (descriptor !== undefined && /^\d+$/.test(descriptor.text)) {
+                at = descriptor.index;
+                words.pop();
+            }
+            continue;
+        }
+        break;
+    }
+    while (at > start && /\s/.test(command[at - 1] ?? ''))
+        at -= 1;
+    return at;
+}
 /**
  * {@link locatedCommandSegments}'s recursion, so a `sh -c '<command>'` is opened as far as
  * {@link MAX_NESTING} allows. A nested statement's offsets are cleared: they are positions in

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"}