@molecule/api-ai-tools 1.9.18 → 1.10.0

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-18T15:48:52.035Z
+Generated: 2026-10-18T22:07:04.913Z
 -->
 
 # @molecule/api-ai-tools
@@ -66,7 +66,9 @@ One statement or pipeline stage of a shell command: what it runs, and with what.
 interface CommandSegment {
   /**
    * The word in command position, its directory removed (`/usr/bin/hurl` → `hurl`): the program
-   * the shell would run once whatever wrappers stood in front of it are taken away.
+   * the shell would run once whatever wrappers stood in front of it are taken away. When a
+   * wrapper runs a tool's own CLI by file, this is the tool's name — `node
+   * <path>/node_modules/.bin/playwright test` is a `playwright` invocation, not a `node` one.
    */
   program: string
   /** The words after it, as written — quotes kept, so a quoted `"a|b"` is one word. */
@@ -284,9 +286,13 @@ A cutting stage that follows the runner, and the command with the whole pipe rem
 
 ```typescript
 interface RunnerOutputFilter {
-  /** The stage exactly as the runner's command wrote it — `tail -6`. */
+  /**
+   * The stage exactly as the runner's command wrote it — `tail -6`. When several cutting filters
+   * follow the runner, this is the whole trailing chain as written, pipes included:
+   * `grep -E "Failure|actual" | head -40`.
+   */
   stage: string
-  /** The pipe as a sentence names it — `| tail -6`. */
+  /** The pipe as a sentence names it — `| tail -6`, or the whole chain `| grep … | head -40`. */
   pipe: string
   /**
    * The command with the pipe and the stage removed — `hurl --variable uid=… --test /tmp/t.hurl
@@ -333,6 +339,17 @@ interface LeadingSleep {
 }
 ```
 
+#### `RunEnvSetting`
+
+One `NAME=value` the request requires of a suite run.
+
+```typescript
+interface RunEnvSetting {
+  name: string
+  value: string
+}
+```
+
 #### `SuiteRunInFlight`
 
 One suite run, as the rule that decides whether a second may start beside it reads it.
@@ -511,6 +528,17 @@ interface TraceAction {
   pageId?: string
   /** The frame the action ran in, from the same snapshot. */
   frameId?: string
+  /**
+   * The selector a `fill`/`type`/`selectOption` acted on (`textarea[name="bio"]`), from the
+   * trace's own params. Kept so the note can compare what the test typed with what the page
+   * submitted (m173: the field it typed into was sent empty).
+   */
+  selector?: string
+  /**
+   * The value a `fill`/`type`/`selectOption` typed or chose, from the trace's own params —
+   * absent when the action carried none (a `selectOption` by label only).
+   */
+  value?: string
 }
 ```
 
@@ -561,6 +589,33 @@ interface TraceMissingText {
 }
 ```
 
+#### `TraceReadContradiction`
+
+A write the trace recorded answering a boolean field, and a LATER GET of the same resource
+answering the opposite for that field.
+
+This is the pair that reads as a frontend race and is not one: xr-molecule-flash-m181's follow
+test sent `POST /api/profiles/:username/follow` and the API answered
+`{"profile":{…,"following":true}}`, then a `GET /api/profiles/:username` answered
+`{"profile":{…,"following":false}}` — the READ route never saw the viewer, so it hydrated
+`following` from nobody. The run rewrote the profile component twice, the API client once, and
+added optimistic state before anyone read the route's middleware; the write itself was fine.
+
+```typescript
+interface TraceReadContradiction {
+  /** The boolean field both answered (`following`, `favorited`). */
+  field: string
+  /** What the write's response said it is. */
+  writeValue: boolean
+  /** What the later read's response said it is. */
+  readValue: boolean
+  /** The write that answered it (`POST /api/profiles/x/follow`). */
+  write: TraceRequest
+  /** The later GET of the same resource (`GET /api/profiles/x`). */
+  read: TraceRequest
+}
+```
+
 #### `TraceArtifact`
 
 What one trace says: the test it belongs to, the requests it made, and its console lines.
@@ -641,6 +696,15 @@ interface TraceArtifact {
    * read before this field existed.
    */
   missingText?: TraceMissingText
+  /**
+   * A write's answer a later GET of the same resource contradicted — the read route does not see
+   * the viewer (xr-molecule-flash-m181's `following`). The note leads with it and sends the run at
+   * the route's middleware, not the page's state handling.
+   *
+   * Absent when no write and later read in the trace answered the same boolean field differently,
+   * and on traces read before this field existed.
+   */
+  readContradiction?: TraceReadContradiction
 }
 ```
 
@@ -897,6 +961,26 @@ interface ToolBuildConfig {
    */
   excludedTestTitles?: () => readonly string[]
 
+  /**
+   * The `NAME=value` settings the person's request REQUIRES of a suite run (molecule-dev's
+   * `requiredRunSettings` — its mode, say), asked when the cause note composes a narrowed re-run
+   * of a finished run's failures. A re-run composed from the executor's own command inherits what
+   * that command set — and nothing it left out, so a run that measured the suite in `spa` handed
+   * back a re-run that would measure `spa` again (xr-molecule-flash-m182 +12:06: the request names
+   * `TEST_MODE=fullstack`, the run and its re-run both omitted it).
+   *
+   * A getter, not an array: the request is read per turn while the tool set is built once, and
+   * what the suite's own files read is the consumer's reading. Unset answers "nothing required".
+   *
+   * @param command - The command the finished run was started with.
+   * @param cwd - The resolved working directory it ran in.
+   * @returns The settings to put on a re-run of that command.
+   */
+  requiredSuiteEnv?: (
+    command: string,
+    cwd: string,
+  ) => Promise<readonly { name: string; value: string }[] | null | undefined>
+
   /**
    * The supplied suite's own budget, when the Playwright config a command would load sets
    * different settings, asked BEFORE the run executes. The consumer knows where the suite and its
@@ -1699,10 +1783,13 @@ function commandRunsNoTests(command: string): boolean
 
 The output filter that follows the runner in `command`, or null when there is none.
 
-Only a stage of the runner's OWN pipeline counts (its separator is `|`), and only when it is the
-LAST stage of that pipeline: a `| grep … | wc -l` chain would leave a dangling pipe if the
-middle stage were cut out, so a chain is not answered here at all. A filter before the runner
-(`cat run.log | tail -20 && hurl …`) reads something else's output and is not this.
+Only stages of the runner's OWN pipeline count (their separator is `|`), and they are read as
+one trailing CHAIN: `| grep … | head -40` is two cuts, and removing only the first would leave
+the run piped into the second. Every stage after the runner must be a cutting filter and the
+chain must run to the pipeline's end — a pipeline that continues into `wc -l` is not answered
+here, because removing the cutting stages alone would still leave the failure hidden. A filter
+before the runner (`cat run.log | tail -20 && hurl …`) reads something else's output and is not
+this.
 
 ```typescript
 function outputFilterAfterRunner(
@@ -1881,13 +1968,17 @@ function withSuiteConfig(command: string, config: string | null | undefined): st
 
 **Returns:** The command with the flag, or the command unchanged.
 
-#### `scopedRerunCommand(command, locations, excluded, config, cwd)`
+#### `scopedRerunCommand(command, locations, excluded, config, cwd, env)`
 
 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).
 
+The re-run keeps the run's `> <file>` redirect only in the sense of keeping its OUTPUT there:
+the target is rewritten to a fresh sibling ({@link redirectToFreshFile}), so a re-run never
+overwrites the log the run itself is the evidence for (xr-molecule-flash-m173).
+
 `config` is the config the run was measured under ({@link withSuiteConfig}): the narrowed re-run
 carries it whenever the command itself does not, so a run that dropped `--config` cannot be
 handed back a command with the same defect (xr-molecule-flash-m113: every failing test was
@@ -1900,6 +1991,7 @@ function scopedRerunCommand(
   excluded?: readonly string[],
   config?: string | null,
   cwd?: string | null,
+  env?: readonly RunEnvSetting[],
 ): string
 ```
 
@@ -1908,9 +2000,32 @@ function scopedRerunCommand(
 - `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.
+- `env` — The settings the REQUEST requires of the suite and this run left out ({@link withRunEnv}): the re-run carries them, so a re-run of a run measured in the wrong mode is not measured in that mode again (xr-molecule-flash-m182 +12:06).
 
 **Returns:** The scoped command, or the command unchanged when it runs no Playwright suite.
 
+#### `withRunEnv(command, settings)`
+
+The command with the request's required settings put in front of its RUN statement — the ONE
+place every composed re-run gets them (xr-molecule-flash-m182).
+
+The settings are written at the statement's own assignment offset, never in front of the whole
+command: a shell binds an assignment there to the statement's program, while one in front of the
+whole command is the environment of its FIRST statement alone (`APP_BASE=… cd app && npx
+playwright test` sets the variable for `cd`; xr-molecule-flash-m103 +28:08). A name the command
+gives a different value is replaced, and one it already gives the required value is left as
+written. When the parse cannot place the statement (a run inside a nested `sh -c '…'`), the
+settings become `export`s, which no statement boundary can swallow.
+
+```typescript
+function withRunEnv(command: string, settings?: readonly RunEnvSetting[]): string
+```
+
+- `command` — The command to carry them.
+- `settings` — The `NAME`/`value` pairs the request requires.
+
+**Returns:** The command, or the command unchanged when it already carries every setting.
+
 #### `suiteRunInTheWay(candidate, inFlight)`
 
 The run in flight that makes a second run a hazard, or null when nothing is in the way.
@@ -2226,6 +2341,25 @@ function stalledDocumentSubresource(request: TraceRequest): boolean
 
 **Returns:** True when the request is a document subresource that never finished.
 
+#### `isCredentialExchangePath(path, authEndpoints)`
+
+Whether a request PATH asks the app to mint a credential — a login, a registration, a token
+endpoint — as opposed to a protected resource that presents one.
+
+This is the path half of {@link isCredentialExchange}, exported so a caller holding only a
+`METHOD path` reads the same classification: a Hurl failing entry says
+`POST /api/users/login` and nothing about the body, and the whole-suite note must not explain
+a wrong-password login that answered 200 as a cookie-jar effect (xr-molecule-flash-m176).
+
+```typescript
+function isCredentialExchangePath(path: string, authEndpoints?: readonly string[]): boolean
+```
+
+- `path` — The request path (`/api/users/login`); a query or fragment is ignored.
+- `authEndpoints` — The endpoints the app's auth config names (`/users/login`).
+
+**Returns:** True when the path names a credential exchange.
+
 #### `failureTraceNote(items, target, earlierFailures, apiPrefixes, report)`
 
 The note a failed suite run's result carries: what each failing test's page actually sent, and
@@ -3372,14 +3506,20 @@ reads as ten defects in the app.
 function failureCausesNote(
   log: string,
   excluded?: readonly string[],
-  run?: { command: string; cwd?: string; log?: string; config?: string | null },
+  run?: {
+    command: string
+    cwd?: string
+    log?: string
+    config?: string | null
+    env?: readonly RunEnvSetting[]
+  },
   pageErrors?: readonly CausePageErrors[],
 ): string | null
 ```
 
 - `log` — The finished run's output.
 - `excluded` — The test titles the request carves out, if the caller knows them.
-- `run` — How the run was started, when the caller knows it: the narrowed re-run is built from `command`/`cwd`/`config`, and `log` (the path the output was written to) is what the "left out" sentence greps when more causes exist than the result has room for.
+- `run` — How the run was started, when the caller knows it: the narrowed re-run is built from `command`/`cwd`/`config`/`env`, and `log` (the path the output was written to) is what the "left out" sentence greps when more causes exist than the result has room for.
 
 **Returns:** The note, or null.
 
@@ -3398,13 +3538,13 @@ refused while the run walks ({@link suiteRunInTheWay}).
 
 ```typescript
 function rerunOfRunningSuite(
-  run: { command: string; cwd?: string; config?: string | null },
+  run: { command: string; cwd?: string; config?: string | null; env?: readonly RunEnvSetting[] },
   locations: readonly string[],
   excluded?: readonly string[],
 ): string | null
 ```
 
-- `run` — The run in flight: the command it was started with, as it was run, the directory that command ran in, and the config it loaded when the caller knows it.
+- `run` — The run in flight: the command it was started with, as it was run, the directory that command ran in, the config it loaded when the caller knows it, and the settings the request required and the run left out (`env`) — the re-run carries them, so it never reproduces the configuration the run was measured under by mistake (m182).
 - `locations` — The failing `file:line`s to re-run, as the run's log printed them.
 - `excluded` — The test titles the request carves out: the re-run inverts them out (`--grep-invert`) so it cannot report them again.
 
@@ -3443,7 +3583,7 @@ function repeatingFailureNote(
     log: string
     stop: string
     universal?: UniversalCause | null
-    run?: { command: string; cwd?: string }
+    run?: { command: string; cwd?: string; env?: readonly RunEnvSetting[] }
     editsInvalidateRun?: boolean
   },
 ): string
@@ -4026,11 +4166,22 @@ const UNIVERSAL_CAUSE_FILES: 3
 #### `EMPTY_PAGE_CAUSE_TESTS`
 
 How many tests a run must have walked — with nothing passing since its first failure — before
-"the page renders nothing" can be its one cause. A handful of failures is a handful of bugs;
-a page that never painted fails every spec that reaches it, and m141's walk had 36 by +20:30.
-
-```typescript
-const EMPTY_PAGE_CAUSE_TESTS: 15
+"the page renders nothing" can be its one cause.
+
+THREE, and the number is the cost of the alternative. The old floor of 15 was chosen when the
+reading was only offered at a completed run; once it STOPS the walk, every test waited for is
+a test whose result is thrown away, and a blank page costs its per-test budget each time
+(m177: 18 tests, ~4.2 minutes, on a page whose thrown error was visible in the first
+`pageerror`). Three is the smallest count that is not one page's own bug: the cause additionally
+needs three DISTINCT spec files (`UNIVERSAL_CAUSE_FILES`, or the files a narrowed run selected),
+each spec waiting for its OWN first element, and no test passing after the first failure. A page
+that renders misses elements, but three unrelated specs in three files failing at three
+different first locators with nothing passing in between is the page, not three bugs. At the
+suite's own 5 s action timeout that verdict lands ~20 s into the walk, so the early stop costs
+about one test's worth of time instead of fifteen.
+
+```typescript
+const EMPTY_PAGE_CAUSE_TESTS: 3
 ```
 
 #### `CONNECTION_CAUSE_TESTS`

package/dist/command-position.d.ts

@@ -36,7 +36,9 @@
 export interface CommandSegment {
     /**
      * The word in command position, its directory removed (`/usr/bin/hurl` → `hurl`): the program
-     * the shell would run once whatever wrappers stood in front of it are taken away.
+     * the shell would run once whatever wrappers stood in front of it are taken away. When a
+     * wrapper runs a tool's own CLI by file, this is the tool's name — `node
+     * <path>/node_modules/.bin/playwright test` is a `playwright` invocation, not a `node` one.
      */
     program: string;
     /** The words after it, as written — quotes kept, so a quoted `"a|b"` is one word. */

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;AAqND;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM3D;AAmjBD;;;;;;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;IACjB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;;;;OAKG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;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;AAwFD;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOpE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,GAC1C;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAoD7C;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;;;;;OAKG;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;AA8RD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM3D;AAwkBD;;;;;;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;IACjB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;;;;OAKG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;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;AA2FD;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOpE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,GAC1C;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAoD7C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAK/E"}

package/dist/command-position.js

@@ -68,6 +68,75 @@ const LAUNCHERS = new Set([
 ]);
 /** The shells whose `-c '<command>'` argument is a command of its own. */
 const SHELLS = new Set(['ash', 'bash', 'dash', 'ksh', 'sh', 'zsh']);
+/**
+ * Node, which is a wrapper only when the script it runs IS a tool's own CLI — never in general:
+ * `node script.mjs` RUNS that script, so the parser's answer for it stays `node`.
+ *
+ * The Playwright runner is spelled this way whenever a project reaches it by file instead of by
+ * the `.bin` shim: xr-molecule-flash-m179 (+17:51) ran
+ * `node /workspace/node_modules/.bin/playwright test` after `npx playwright test` in every
+ * earlier call, and no reader recognised it — the run got no `--trace`, no suite-budget pin and
+ * no proof credit, and the platform spent the rest of the turn re-walking a suite it had already
+ * walked green.
+ */
+const NODE = new Set(['node']);
+/**
+ * The Playwright CLI, as the path operand of a `node` invocation: the package's `.bin` shim, or
+ * the `cli.js` a package installs (`playwright/cli.js`, `@playwright/test/cli.js`).
+ */
+const PLAYWRIGHT_CLI = /(?:^|\/)node_modules\/(?:\.bin\/playwright|(?:playwright|@playwright\/test)\/cli\.(?:js|mjs|cjs))$/;
+/**
+ * The runner a `node` script operand IS, or null when the operand is any other script.
+ *
+ * @param word - The script operand, as written.
+ * @returns The runner's name (`playwright`), or null.
+ */
+function nodeScriptRunner(word) {
+    return PLAYWRIGHT_CLI.test(unquoted(word)) ? 'playwright' : null;
+}
+/**
+ * Node's own value-taking options: the ones that consume the word after them, so the script
+ * operand is not mistaken for a value (`node -r tsx/cli.js …`). Node also accepts `--flag=value`.
+ */
+const NODE_VALUE_FLAGS = new Set([
+    '-e',
+    '--eval',
+    '-p',
+    '--print',
+    '-r',
+    '--require',
+    '--import',
+    '--loader',
+    '--experimental-loader',
+    '--input-type',
+    '--conditions',
+    '--title',
+]);
+/**
+ * The word a `node` invocation runs as its script: the first operand after node's own options,
+ * with `--` ending the options. Null when node runs no file (`node --test`, `node -e '<code>'`).
+ *
+ * A wrong guess here is harmless: the operand is then checked against {@link PLAYWRIGHT_CLI}, so
+ * an ordinary script (`node probe.mjs`) is never read as a runner.
+ *
+ * @param words - The segment's words.
+ * @param from - The index just after `node`.
+ * @returns The script operand's index, or null.
+ */
+function nodeScriptIndex(words, from) {
+    let at = from;
+    for (let guard = 0; guard < MAX_WRAPPERS && at < words.length; guard++) {
+        const word = words[at] ?? '';
+        if (!word.startsWith('-'))
+            return at;
+        const flag = unquoted(word);
+        // `--` ends node's options; the script is the next word.
+        if (flag === '--')
+            return at + 1 < words.length ? at + 1 : null;
+        at += flag.includes('=') || !NODE_VALUE_FLAGS.has(flag) ? 1 : 2;
+    }
+    return null;
+}
 /** Package runners that run the program named after them (`npx playwright test`). */
 const PACKAGE_RUNNERS = new Set(['bunx', 'npx', 'pnpx']);
 /** Package managers whose sub-command runs a package's binary (`bun x`, `pnpm dlx`, `npm exec`). */
@@ -345,6 +414,8 @@ function nestedCommand(words, from) {
  * @returns The index of the word in command position (one past the end when the segment runs
  *   nothing), the command string of a `sh -c '<command>'` this segment turns out to be, and the
  *   seconds its own `timeout` wrapper allows that command (`timeout 280 hurl …` → 280) or null.
+ *   `program` names what runs when that is not the word itself's name — `node <path>/playwright`
+ *   is a `playwright` invocation, not a `node` one ({@link nodeScriptRunner}).
  */
 function commandStart(words) {
     let at = 0;
@@ -364,14 +435,14 @@ function commandStart(words) {
         if (SHELLS.has(name)) {
             const nested = nestedCommand(words, at + 1);
             if (nested !== null)
-                return { at, nested, timeoutSeconds };
+                return { at, nested, timeoutSeconds, program: null };
             at += 1 + flagWords(words, at + 1, name);
             continue;
         }
         if (PACKAGE_RUNNERS.has(name)) {
             const runner = packageRunnerOptions(words, at + 1, name);
             if (runner.nested !== null)
-                return { at, nested: runner.nested, timeoutSeconds };
+                return { at, nested: runner.nested, timeoutSeconds, program: null };
             at += 1 + runner.count;
             continue;
         }
@@ -380,19 +451,35 @@ function commandStart(words) {
             const subcommand = unquoted(words[at + 1] ?? '');
             const runner = packageRunnerOptions(words, at + 2, `${name} ${subcommand}`);
             if (runner.nested !== null)
-                return { at, nested: runner.nested, timeoutSeconds };
+                return { at, nested: runner.nested, timeoutSeconds, program: null };
             at += 2 + runner.count;
             continue;
         }
+        if (name === 'yarn' && unquoted(words[at + 1] ?? '') === 'playwright') {
+            // Yarn classic runs the binary named after it (`yarn playwright test`); Yarn 2+ spells the
+            // same thing `yarn exec`/`yarn dlx` ({@link PACKAGE_RUNNER_SUBCOMMANDS}). Only the runner's
+            // own name is read through it — `yarn test` is the project's own script, not a binary.
+            at += 1;
+            continue;
+        }
+        if (NODE.has(name)) {
+            // `node <path>/playwright test` is a Playwright invocation; `node probe.mjs` runs the
+            // project's own script and stays a `node` statement (`program: null`).
+            const script = nodeScriptIndex(words, at + 1);
+            const runner = script === null ? null : nodeScriptRunner(words[script] ?? '');
+            return runner === null
+                ? { at, nested: null, timeoutSeconds, program: null }
+                : { at: script ?? at, nested: null, timeoutSeconds, program: runner };
+        }
         if (!LAUNCHERS.has(name))
-            return { at, nested: null, timeoutSeconds };
+            return { at, nested: null, timeoutSeconds, program: null };
         at += 1 + flagWords(words, at + 1, name);
         if (name === 'timeout' && DURATION.test(words[at] ?? '')) {
             timeoutSeconds = durationSeconds(words[at] ?? '');
             at += 1;
         }
     }
-    return { at, nested: null, timeoutSeconds };
+    return { at, nested: null, timeoutSeconds, program: null };
 }
 /**
  * A command with every heredoc BODY blanked to spaces, so its length and every offset in it are
@@ -993,7 +1080,9 @@ function locatedSegmentsOf(command, depth) {
             assignmentOffset: part.start + leading.end,
             programOffset: words[start.at] === undefined ? null : part.start + (wordOffset(part.text, start.at) ?? 0),
         };
-        const program = words[start.at] === undefined ? '' : programName(words[start.at] ?? '');
+        // The runner the word RUNS names, when that is not the word's own name (`node <path>/playwright`
+        // is a `playwright` invocation, xr-molecule-flash-m179).
+        const program = words[start.at] === undefined ? '' : (start.program ?? programName(words[start.at] ?? ''));
         const args = words.slice(start.at + 1);
         const redirectTarget = redirectTargetOf(part.text, part.depths, program, args);
         if (start.nested !== null) {

package/dist/output-filter.d.ts

@@ -19,9 +19,13 @@
 import { type CommandSegment } from './command-position.js';
 /** A cutting stage that follows the runner, and the command with the whole pipe removed. */
 export interface RunnerOutputFilter {
-    /** The stage exactly as the runner's command wrote it — `tail -6`. */
+    /**
+     * The stage exactly as the runner's command wrote it — `tail -6`. When several cutting filters
+     * follow the runner, this is the whole trailing chain as written, pipes included:
+     * `grep -E "Failure|actual" | head -40`.
+     */
     stage: string;
-    /** The pipe as a sentence names it — `| tail -6`. */
+    /** The pipe as a sentence names it — `| tail -6`, or the whole chain `| grep … | head -40`. */
     pipe: string;
     /**
      * The command with the pipe and the stage removed — `hurl --variable uid=… --test /tmp/t.hurl
@@ -33,10 +37,13 @@ export interface RunnerOutputFilter {
 /**
  * The output filter that follows the runner in `command`, or null when there is none.
  *
- * Only a stage of the runner's OWN pipeline counts (its separator is `|`), and only when it is the
- * LAST stage of that pipeline: a `| grep … | wc -l` chain would leave a dangling pipe if the
- * middle stage were cut out, so a chain is not answered here at all. A filter before the runner
- * (`cat run.log | tail -20 && hurl …`) reads something else's output and is not this.
+ * Only stages of the runner's OWN pipeline count (their separator is `|`), and they are read as
+ * one trailing CHAIN: `| grep … | head -40` is two cuts, and removing only the first would leave
+ * the run piped into the second. Every stage after the runner must be a cutting filter and the
+ * chain must run to the pipeline's end — a pipeline that continues into `wc -l` is not answered
+ * here, because removing the cutting stages alone would still leave the failure hidden. A filter
+ * before the runner (`cat run.log | tail -20 && hurl …`) reads something else's output and is not
+ * this.
  *
  * @param command - The command as the executor sent it.
  * @param runs - Whether a segment is the runner this run is about (the caller knows its own kind:

package/dist/output-filter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"output-filter.d.ts","sourceRoot":"","sources":["../src/output-filter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,KAAK,cAAc,EAA0B,MAAM,uBAAuB,CAAA;AASnF,4FAA4F;AAC5F,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAA;IACb,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,EAC1C,UAAU,SAAI,GACb,kBAAkB,GAAG,IAAI,CAsB3B"}
+{"version":3,"file":"output-filter.d.ts","sourceRoot":"","sources":["../src/output-filter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,KAAK,cAAc,EAGpB,MAAM,uBAAuB,CAAA;AAS9B,4FAA4F;AAC5F,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,+FAA+F;IAC/F,IAAI,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,EAC1C,UAAU,SAAI,GACb,kBAAkB,GAAG,IAAI,CAmC3B"}

package/dist/output-filter.js

@@ -16,7 +16,7 @@
  *
  * @module
  */
-import { locatedCommandSegments } from './command-position.js';
+import { locatedCommandSegments, } from './command-position.js';
 /**
  * The programs whose job is to re-shape what an earlier stage printed and that can DROP lines —
  * the reader's own cut, never part of the run. `tee`, `sort` and `wc` are output plumbing too, but
@@ -26,10 +26,13 @@ const CUTTING_FILTERS = new Set(['awk', 'cut', 'grep', 'head', 'sed', 'tail']);
 /**
  * The output filter that follows the runner in `command`, or null when there is none.
  *
- * Only a stage of the runner's OWN pipeline counts (its separator is `|`), and only when it is the
- * LAST stage of that pipeline: a `| grep … | wc -l` chain would leave a dangling pipe if the
- * middle stage were cut out, so a chain is not answered here at all. A filter before the runner
- * (`cat run.log | tail -20 && hurl …`) reads something else's output and is not this.
+ * Only stages of the runner's OWN pipeline count (their separator is `|`), and they are read as
+ * one trailing CHAIN: `| grep … | head -40` is two cuts, and removing only the first would leave
+ * the run piped into the second. Every stage after the runner must be a cutting filter and the
+ * chain must run to the pipeline's end — a pipeline that continues into `wc -l` is not answered
+ * here, because removing the cutting stages alone would still leave the failure hidden. A filter
+ * before the runner (`cat run.log | tail -20 && hurl …`) reads something else's output and is not
+ * this.
  *
  * @param command - The command as the executor sent it.
  * @param runs - Whether a segment is the runner this run is about (the caller knows its own kind:
@@ -51,23 +54,39 @@ export function outputFilterAfterRunner(command, runs, occurrence = 1) {
             runners.push(index);
     });
     const runnerAt = runners[occurrence - 1];
-    if (runnerAt === undefined || runnerAt + 1 >= entries.length)
+    if (runnerAt === undefined)
         return null;
     const runner = entries[runnerAt];
-    const filter = entries[runnerAt + 1];
-    // The stage must be fed by the runner's own pipe, and nothing may be piped out of the filter:
-    // those are the two positions where cutting it out leaves a command that still runs the run.
-    if (!runner || !filter || filter.separator.trim() !== '|')
+    if (!runner || runner.end === null)
         return null;
-    if (!filter.segment || !CUTTING_FILTERS.has(filter.segment.program))
+    // The chain is every stage fed by the runner's own pipe, until the pipeline ends. Each one has
+    // to be a cutting filter: a stage that does not drop lines ends the chain, and the chain then
+    // stops before the pipeline's end — which is not answerable (`| grep … | wc -l` would still
+    // hide the assertion in a count).
+    const chain = [];
+    for (let index = runnerAt + 1; index < entries.length; index++) {
+        const entry = entries[index];
+        if (!entry || entry.separator.trim() !== '|')
+            break;
+        if (!entry.segment || !CUTTING_FILTERS.has(entry.segment.program))
+            break;
+        chain.push(entry);
+        if (entry.terminator.trim() !== '|')
+            break;
+    }
+    const first = chain[0];
+    const last = chain[chain.length - 1];
+    if (!first || !last)
         return null;
-    if (filter.terminator.trim() === '|')
+    // A pipeline that continues past the chain means a non-cutting stage sits after it.
+    if (last.terminator.trim() === '|')
         return null;
-    if (runner.end === null || filter.start === null || filter.end === null)
+    if (first.start === null || last.end === null)
         return null;
+    const stage = command.slice(first.start, last.end);
     return {
-        stage: command.slice(filter.start, filter.end),
-        pipe: `| ${command.slice(filter.start, filter.end)}`,
-        command: `${command.slice(0, runner.end)}${command.slice(filter.end)}`,
+        stage,
+        pipe: `| ${stage}`,
+        command: `${command.slice(0, runner.end)}${command.slice(last.end)}`,
     };
 }