@molecule/api-ai-tools 1.10.10 → 1.11.1

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-20T14:43:37.900Z
+Generated: 2026-10-21T08:55:11.822Z
 -->
 
 # @molecule/api-ai-tools
@@ -105,6 +105,28 @@ interface CommandSegment {
 }
 ```
 
+#### `ExecutedCommand`
+
+One command a shell command actually executes, wherever the shell runs it.
+
+```typescript
+interface ExecutedCommand {
+  /**
+   * The word in command position, its directory removed (`/usr/bin/printenv` → `printenv`) — or
+   * the launcher itself when it runs alone and nothing follows it (`x | env` → `env`).
+   */
+  program: string
+  /**
+   * Its arguments, as written with quotes kept — the statement's own words AFTER the program,
+   * including an input redirect's path (`< /proc/self/environ`), so a reader of secret files sees
+   * the file it reads.
+   */
+  args: readonly string[]
+  /** The program and its arguments as one line, what a pattern anchored at the program matches. */
+  text: string
+}
+```
+
 #### `LocatedCommandSegment`
 
 One statement of a shell command, with where it sits and the variables it sets for itself.
@@ -705,6 +727,81 @@ interface TraceHiddenBox {
 }
 ```
 
+#### `TraceCountMatch`
+
+One element a failing locator count matched, read from the trace's own failure snapshot.
+
+A count assertion reports only `Expected: 3 / Received: 4`; the element that made it 4 is not
+in the error. Playwright's trace does hold it — either marked `__playwright_target__` in the
+failure snapshot (`expect(locator).toHaveCount(n)`), or recoverable by replaying the recorded
+selector against the snapshot's DOM in a browser (`locator.count()` then `expect(n).toBe(k)`) —
+so each match is named by what it is and where it sits, never by a guess.
+
+```typescript
+interface TraceCountMatch {
+  /** The element's tag, lowercased (`div`). */
+  tag: string
+  /** Its `class` attribute, bounded (`card-block`). */
+  classes?: string
+  /** Its own text, whitespace-collapsed and bounded. */
+  text?: string
+  /** Its ancestors, outermost first (`body > div.comment-form > div.card`), bounded. */
+  path?: string
+  /** True when a `<form>` is one of its ancestors — the m321 extra match's shape. */
+  inForm?: true
+}
+```
+
+#### `TraceCountMismatch`
+
+A failing assertion that compared a LOCATOR COUNT (`expect(await locator.count()).toBe(n)` or
+`expect(locator).toHaveCount(n)`), with the locator the trace recorded and, when the failure
+snapshot can supply them, the elements it matched.
+
+xr-molecule-flash-m321's `comments.spec.ts:86` sat on `Expected: 3 / Received: 4` for ~30
+minutes and three whole suite walks: the helper counted `.card:not(.comment-form) .card-block`,
+the app's comment form was a `.comment-form` wrapper around a plain `.card`, and the form's own
+`.card-block` made the fourth. The trace had the selector (its `Frame.queryCount` entry) and the
+four elements (its failure snapshot); the note printed neither. This reading prints both, and
+fails closed — a selector outside the browser's own CSS support, a missing browser, or a replay
+that disagrees with the recorded count names no elements rather than inventing them.
+
+```typescript
+interface TraceCountMismatch {
+  /** The locator as the trace or the assertion printed it (`locator('.card:not(…')`). */
+  locator: string
+  /** The selector inside that locator, when the trace recorded one. */
+  selector?: string
+  /** The number the assertion expected. */
+  expected: number
+  /** The number the page matched. */
+  received: number
+  /**
+   * Where the locator came from: the assertion's own message, or the `locator.count()` entry the
+   * trace recorded just before the failing assertion.
+   */
+  source: 'assertion' | 'locator-count'
+  /** The matched elements, bounded to {@link MAX_COUNT_MATCHES} in document order. */
+  matched?: TraceCountMatch[]
+  /** How many elements matched in total, before the display bound. */
+  matchedTotal?: number
+  /**
+   * How the elements were read: Playwright's own `__playwright_target__` marks in the failure
+   * snapshot, or the recorded selector replayed against that snapshot in a browser.
+   */
+  matchedFrom?: 'snapshot-targets' | 'selector-replay'
+  /**
+   * Why no elements are named, when they are not. `unsupported-selector` is a selector the
+   * browser's `querySelectorAll` rejects (a `getByRole`/`getByText` engine, `>>` chaining);
+   * `no-snapshot` is a trace with no readable DOM snapshot at the failure; `count-mismatch` is a
+   * replay that disagreed with the recorded count, so the snapshot is not evidence for this
+   * assertion; `browser-unavailable` is a project whose Playwright module or recorded engine
+   * executable could not be resolved, so the selector could not be replayed at all.
+   */
+  unreadable?: 'unsupported-selector' | 'no-snapshot' | 'count-mismatch' | 'browser-unavailable'
+}
+```
+
 #### `TraceArtifact`
 
 What one trace says: the test it belongs to, the requests it made, and its console lines.
@@ -801,6 +898,13 @@ interface TraceArtifact {
    * leaving the run to probe computed styles (xr-molecule-flash-m197).
    */
   hiddenBox?: TraceHiddenBox
+  /**
+   * A failing assertion that compared a locator count, with the locator the trace recorded and the
+   * elements its failure snapshot matched ({@link TraceCountMismatch}). The row prints them, so a
+   * count that is off by one names the extra element instead of leaving the run to probe for it
+   * (xr-molecule-flash-m321's 30-minute `Expected: 3 / Received: 4`).
+   */
+  countMismatch?: TraceCountMismatch
   /**
    * The method+path groups this test's page sent {@link TRACE_NOTE_LOOP_REPEATS} times or more,
    * most-repeated first — a render loop the note leads with (xr-molecule-flash-m215: 2,106
@@ -1588,6 +1692,32 @@ function commandSegments(command: string): CommandSegment[]
 
 **Returns:** One entry per statement or pipeline stage that runs something, in order.
 
+#### `executedCommands(command)`
+
+Every command a shell command actually executes, at any depth — the statements themselves, the
+body of a `sh -c '<command>'`, and the body of every command substitution (`$(…)`, backticks).
+
+This is the reading a policy that asks "does this command run X" needs, and it is deliberately
+not a text match. The command-position parser already knows what runs and what is only quoted
+data ({@link commandSegments}), so a pattern never reads a `|` inside a quoted grep alternation
+as a pipeline: `grep -E "USER CALLS|ENV|BUTTON" app.log` prints log lines, and the `ENV` in
+its pattern started nothing (X0 xr-molecule-flash-m331 blocked exactly that call as an
+environment dump). What the shell DOES run stays visible through the same walk: a bare
+launcher (`ls | env`), a shell string (`bash -c 'env'`), a substitution
+(`echo "$(printenv)"`) and a nested one (`sh -c 'x; env'`) are all commands here.
+
+`commandSegments` answers what a pipeline stage runs for a caller matching a runner; this
+answers with the launcher left standing when it runs alone, since that is what the shell
+executes then.
+
+```typescript
+function executedCommands(command: string): ExecutedCommand[]
+```
+
+- `command` — The shell command.
+
+**Returns:** Each command the shell executes, in the order the shell reaches them.
+
 #### `locatedCommandSegments(command)`
 
 Every statement of a command, with its own assignments and where it sits — assignment-only
@@ -2671,6 +2801,37 @@ function hiddenBoxNote(items: readonly TraceArtifact[]): string | null
 
 **Returns:** The sentence, or null when no failure carries a hidden-box reading.
 
+#### `countMismatchSentence(mismatch)`
+
+The row's sentence for a failing count assertion: the locator, both numbers, and the elements
+the failure snapshot held.
+
+xr-molecule-flash-m321's `comments.spec.ts:86` printed only `Expected: 3 / Received: 4`. The
+helper counted `.card:not(.comment-form) .card-block`, and the app's comment form was a
+`.comment-form` wrapper around a plain `.card`, so the form's own `.card-block` was the fourth
+match. The trace held the selector and the four elements; the note held neither.
+
+```typescript
+function countMismatchSentence(mismatch: TraceCountMismatch): string
+```
+
+- `mismatch` — The trace's count reading ({@link TraceCountMismatch}).
+
+**Returns:** The sentence.
+
+#### `countMismatchNote(items)`
+
+The sentence a count assertion earns when every traced failure is one — the next read before
+the API or the request is changed.
+
+```typescript
+function countMismatchNote(items: readonly TraceArtifact[]): string | null
+```
+
+- `items` — The traces {@link parseTraceArtifacts} read.
+
+**Returns:** The sentence, or null when not every traced failure is a count mismatch.
+
 #### `failureTraceNote(items, target, earlierFailures, apiPrefixes, report)`
 
 The note a failed suite run's result carries: what each failing test's page actually sent, and
@@ -3210,6 +3371,15 @@ function suiteRunPriorityLaunch(command: string, launch: string): { launch: stri
 
 Check if a command is blocked for security reasons. Returns error message or null if allowed.
 
+The first check reads the commands the shell actually RUNS — the statements, a `sh -c`
+string's body, and every command substitution ({@link executedCommands}) — so a `|` inside a
+quoted grep alternation is data, not a pipeline: `grep -E "USER CALLS|ENV|BUTTON|passed|failed"
+app.log` prints log lines, and the `ENV` in its pattern started nothing (X0
+xr-molecule-flash-m331 blocked exactly that call as an environment dump, twice). What the
+shell DOES run stays visible through the same walk: `ls | env`, `bash -c 'env'`,
+`echo "$(printenv)"` and a nested `sh -c 'x; env'` are all commands, and so is `env` itself
+when nothing follows it.
+
 ```typescript
 function checkBlockedCommand(command: string): string | null
 ```

package/dist/command-position.d.ts

@@ -74,6 +74,43 @@ export declare function endsInBackground(command: string): boolean;
  * @returns One entry per statement or pipeline stage that runs something, in order.
  */
 export declare function commandSegments(command: string): CommandSegment[];
+/** One command a shell command actually executes, wherever the shell runs it. */
+export interface ExecutedCommand {
+    /**
+     * The word in command position, its directory removed (`/usr/bin/printenv` → `printenv`) — or
+     * the launcher itself when it runs alone and nothing follows it (`x | env` → `env`).
+     */
+    program: string;
+    /**
+     * Its arguments, as written with quotes kept — the statement's own words AFTER the program,
+     * including an input redirect's path (`< /proc/self/environ`), so a reader of secret files sees
+     * the file it reads.
+     */
+    args: readonly string[];
+    /** The program and its arguments as one line, what a pattern anchored at the program matches. */
+    text: string;
+}
+/**
+ * Every command a shell command actually executes, at any depth — the statements themselves, the
+ * body of a `sh -c '<command>'`, and the body of every command substitution (`$(…)`, backticks).
+ *
+ * This is the reading a policy that asks "does this command run X" needs, and it is deliberately
+ * not a text match. The command-position parser already knows what runs and what is only quoted
+ * data ({@link commandSegments}), so a pattern never reads a `|` inside a quoted grep alternation
+ * as a pipeline: `grep -E "USER CALLS|ENV|BUTTON" app.log` prints log lines, and the `ENV` in
+ * its pattern started nothing (X0 xr-molecule-flash-m331 blocked exactly that call as an
+ * environment dump). What the shell DOES run stays visible through the same walk: a bare
+ * launcher (`ls | env`), a shell string (`bash -c 'env'`), a substitution
+ * (`echo "$(printenv)"`) and a nested one (`sh -c 'x; env'`) are all commands here.
+ *
+ * `commandSegments` answers what a pipeline stage runs for a caller matching a runner; this
+ * answers with the launcher left standing when it runs alone, since that is what the shell
+ * executes then.
+ *
+ * @param command - The shell command.
+ * @returns Each command the shell executes, in the order the shell reaches them.
+ */
+export declare function executedCommands(command: string): ExecutedCommand[];
 /**
  * One statement of a shell command, with where it sits and the variables it sets for itself.
  *

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;;;;;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;AAgSD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM3D;AAikBD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEzD;AA8GD;;;;;;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;AA4GD;;;;;;;;;;;;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;AAgSD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM3D;AAynBD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEzD;AA8GD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAIjE;AAED,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IACvB,iGAAiG;IACjG,IAAI,EAAE,MAAM,CAAA;CACb;AAmFD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,EAAE,CAGnE;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;AA4GD;;;;;;;;;;;;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

@@ -694,14 +694,23 @@ function blankHeredocBodies(command) {
  * `molecule-dev/api/src/ai/supplied-tree-guard.ts` — so a script that does not classify records
  * no runner, and every run of it reads as nothing).
  *
+ * The walk also RECORDS the command substitutions it enters (`$(…)` and backticks), because the
+ * shell runs those too: a reader that only saw the outer statements could not tell that
+ * `echo "$(printenv)"` prints the environment ({@link executedCommands}).
+ *
  * @param command - The shell command.
  * @returns Each statement's text, the offset its first character sits at, and the separator that
  *   ended it (`|`, `&&`, `;`, a newline, … — '' after the last one), in order, with empty ones
- *   dropped.
+ *   dropped — and the bodies of the command substitutions this level enters, as offsets.
  */
-function splitSegments(command) {
+function splitCommand(command) {
     const source = blankHeredocBodies(command);
     const parts = [];
+    const substitutions = [];
+    /** Where each open `$(` body starts; -1 for a bare `(` opened inside one. */
+    const subOpens = [];
+    /** Where each open backtick body starts. */
+    const tickOpens = [];
     let buffer = '';
     /** The offset in the command of the current buffer's first character. */
     let bufferStart = 0;
@@ -739,6 +748,32 @@ function splitSegments(command) {
                 stack.pop();
             continue;
         }
+        // Backticks open a command substitution wherever one runs — outside quotes, inside double
+        // quotes, and inside another substitution or a parameter expansion — but never inside single
+        // quotes (handled above). Its body is a command of its own: nothing in it splits THIS command,
+        // and a `'` or `"` in it is the nested command's, not this one's.
+        if (top !== 'tick' && char === '`') {
+            stack.push('tick');
+            tickOpens.push(i + 1);
+            put(char, -1);
+            continue;
+        }
+        if (top === 'tick') {
+            if (char === '\\' && next !== undefined) {
+                // An escaped character is literal: `\`` does not close the substitution.
+                put(char + next, -1);
+                i += 1;
+                continue;
+            }
+            if (char === '`') {
+                stack.pop();
+                const opened = tickOpens.pop();
+                if (opened !== undefined)
+                    substitutions.push({ start: opened, end: i });
+            }
+            put(char, -1);
+            continue;
+        }
         // Comments are shell syntax only in a command context, including an unquoted `$(`.
         // Blank their bytes so quotes/operators cannot affect this walk, while every later
         // position and depth index stays aligned with the original command. Keep the newline.
@@ -753,6 +788,7 @@ function splitSegments(command) {
         // inside single quotes (handled above). The `(` is consumed here so the depth is counted once.
         if (char === '$' && next === '(') {
             stack.push('sub');
+            subOpens.push(i + 2);
             put('$(', -1);
             i += 1;
             continue;
@@ -802,10 +838,16 @@ function splitSegments(command) {
         // Inside a substitution or a subshell of one: its own parentheses nest, its `|`/`;`/`&&`
         // belong to the nested command, and its newlines are that command's too.
         if (top === 'sub') {
-            if (char === '(')
+            if (char === '(') {
                 stack.push('sub');
-            else if (char === ')')
+                subOpens.push(-1);
+            }
+            else if (char === ')') {
                 stack.pop();
+                const opened = subOpens.pop();
+                if (opened !== undefined && opened >= 0)
+                    substitutions.push({ start: opened, end: i });
+            }
             put(char, -1);
             continue;
         }
@@ -861,7 +903,16 @@ function splitSegments(command) {
         });
         lastAfter = part.after;
     }
-    return out;
+    return { parts: out, substitutions };
+}
+/**
+ * A command's statements and pipeline stages — {@link splitCommand}'s parts on their own.
+ *
+ * @param command - The shell command.
+ * @returns Each statement, in order, with empty ones dropped.
+ */
+function splitSegments(command) {
+    return splitCommand(command).parts;
 }
 /**
  * Whether the outer shell's final statement starts a background job.
@@ -983,6 +1034,114 @@ function leadingAssignments(text) {
 export function commandSegments(command) {
     return locatedSegmentsOf(command, 0).flatMap((located) => located.segment === null ? [] : [located.segment]);
 }
+/**
+ * A statement's words with its redirections taken out, so the walk that finds the program does
+ * not read a redirect's target as the program: `env > out.txt` RUNS `env`, and `cat > f` runs
+ * `cat` with no file argument. Each word kept carries its index in `words`, because a caller
+ * reading the statement's ARGUMENTS wants it as written — an input redirect's path is one.
+ *
+ * @param words - One statement's words, quotes kept.
+ * @returns The words that are not redirections, and each one's index in `words`.
+ */
+function withoutRedirects(words) {
+    const kept = [];
+    const index = [];
+    for (let i = 0; i < words.length; i += 1) {
+        const word = words[i] ?? '';
+        // An operator written on its own owns the word after it (`> out.txt`, `< /proc/self/environ`).
+        if (REDIRECT_OPERATOR.test(word)) {
+            i += 1;
+            continue;
+        }
+        // An operator with its target attached (`2>&1`, `>out.txt`, `&>log`) is one word.
+        if (REDIRECT_WORD.test(word))
+            continue;
+        kept.push(word);
+        index.push(i);
+    }
+    return { words: kept, index };
+}
+/**
+ * The index of the last launcher a statement names (`x | env`, `sudo nice`), or null when it
+ * names none.
+ *
+ * A statement that only NAMES a launcher runs that launcher: `x | env` pipes x's output into
+ * `env`, which prints the environment, and the walk that reports what a command runs has to say
+ * so ({@link executedCommands}).
+ *
+ * @param words - The statement's words, redirections already taken out.
+ * @returns The launcher's index, or null.
+ */
+function lastLauncherIndex(words) {
+    for (let i = words.length - 1; i >= 0; i -= 1) {
+        if (LAUNCHERS.has(programName(words[i] ?? '')))
+            return i;
+    }
+    return null;
+}
+/**
+ * {@link executedCommands}'s recursion: a statement's own `sh -c '<command>'`, and every command
+ * substitution it carries, is a command of its own.
+ *
+ * @param command - The shell command, or one nested command string.
+ * @param depth - How many nested command strings this one already sits inside.
+ * @returns Each command the shell executes, in order.
+ */
+function executedCommandsOf(command, depth) {
+    if (typeof command !== 'string' || depth > MAX_NESTING)
+        return [];
+    const out = [];
+    const { parts, substitutions } = splitCommand(command);
+    for (const part of parts) {
+        const words = segmentWords(part.text);
+        const placed = withoutRedirects(words);
+        const start = commandStart(placed.words);
+        // A shell's `-c '<command>'` is the command: what the shell itself does is run it.
+        if (start.nested !== null) {
+            out.push(...executedCommandsOf(start.nested, depth + 1));
+            continue;
+        }
+        const at = placed.words[start.at] === undefined ? lastLauncherIndex(placed.words) : start.at;
+        if (at === null)
+            continue;
+        const program = start.program ?? programName(placed.words[at] ?? '');
+        if (!program)
+            continue;
+        // Arguments from the statement as written, from the word after the program: `cat < /proc/…`
+        // reads that file, and a reader of secret files has to see it.
+        const args = words.slice((placed.index[at] ?? 0) + 1);
+        out.push({ program, args, text: [program, ...args].join(' ') });
+    }
+    for (const substitution of substitutions) {
+        out.push(...executedCommandsOf(command.slice(substitution.start, substitution.end), depth + 1));
+    }
+    return out;
+}
+/**
+ * Every command a shell command actually executes, at any depth — the statements themselves, the
+ * body of a `sh -c '<command>'`, and the body of every command substitution (`$(…)`, backticks).
+ *
+ * This is the reading a policy that asks "does this command run X" needs, and it is deliberately
+ * not a text match. The command-position parser already knows what runs and what is only quoted
+ * data ({@link commandSegments}), so a pattern never reads a `|` inside a quoted grep alternation
+ * as a pipeline: `grep -E "USER CALLS|ENV|BUTTON" app.log` prints log lines, and the `ENV` in
+ * its pattern started nothing (X0 xr-molecule-flash-m331 blocked exactly that call as an
+ * environment dump). What the shell DOES run stays visible through the same walk: a bare
+ * launcher (`ls | env`), a shell string (`bash -c 'env'`), a substitution
+ * (`echo "$(printenv)"`) and a nested one (`sh -c 'x; env'`) are all commands here.
+ *
+ * `commandSegments` answers what a pipeline stage runs for a caller matching a runner; this
+ * answers with the launcher left standing when it runs alone, since that is what the shell
+ * executes then.
+ *
+ * @param command - The shell command.
+ * @returns Each command the shell executes, in the order the shell reaches them.
+ */
+export function executedCommands(command) {
+    if (typeof command !== 'string' || !command.trim())
+        return [];
+    return executedCommandsOf(command, 0);
+}
 /**
  * Where a statement's word sits in its own raw text, as {@link segmentWords} counts the words.
  *

package/dist/cut-run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cut-run.d.ts","sourceRoot":"","sources":["../src/cut-run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAMH;;;GAGG;AACH,eAAO,MAAM,aAAa,kBAAkB,CAAA;AAE5C,kFAAkF;AAClF,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,OAAO,aAAa,CAAA;AAE1D;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,eAAe,CAGhE;AAiBD;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB,wEAAwE;IACxE,QAAQ,EAAE,OAAO,CAAA;CAClB;AAkDD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CA4B9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhD;AAKD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,GACb,MAAM,GAAG,IAAI,CAIf;AAED,0BAA0B;AAC1B,MAAM,MAAM,KAAK;AACf,sEAAsE;AACpE,aAAa;AACf,oDAAoD;GAClD,iBAAiB;AACnB;;;;GAIG;GACD,cAAc,CAAA;AAElB,wDAAwD;AACxD,MAAM,WAAW,MAAM;IACrB,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAA;IACf,kFAAkF;IAClF,SAAS,EAAE,KAAK,CAAA;IAChB;;;;;;OAMG;IACH,UAAU,EAAE,OAAO,CAAA;IACnB;;;OAGG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB;;;OAGG;IACH,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB;;;OAGG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,qCAAqC;IACrC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAA;IACvB,yEAAyE;IACzE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAC7B;AAsDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,OAAO,EACf,SAAS,EAAE,MAAM,EACjB,aAAa,SAAI,EACjB,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,GAAG,IAAI,CA4Ff;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAmB1D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAyClD"}
+{"version":3,"file":"cut-run.d.ts","sourceRoot":"","sources":["../src/cut-run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAMH;;;GAGG;AACH,eAAO,MAAM,aAAa,kBAAkB,CAAA;AAE5C,kFAAkF;AAClF,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,OAAO,aAAa,CAAA;AAE1D;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,eAAe,CAGhE;AAiBD;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB,wEAAwE;IACxE,QAAQ,EAAE,OAAO,CAAA;CAClB;AAkDD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CA4B9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhD;AAKD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,GACb,MAAM,GAAG,IAAI,CAIf;AAED,0BAA0B;AAC1B,MAAM,MAAM,KAAK;AACf,sEAAsE;AACpE,aAAa;AACf,oDAAoD;GAClD,iBAAiB;AACnB;;;;GAIG;GACD,cAAc,CAAA;AAElB,wDAAwD;AACxD,MAAM,WAAW,MAAM;IACrB,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAA;IACf,kFAAkF;IAClF,SAAS,EAAE,KAAK,CAAA;IAChB;;;;;;OAMG;IACH,UAAU,EAAE,OAAO,CAAA;IACnB;;;OAGG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB;;;OAGG;IACH,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB;;;OAGG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,qCAAqC;IACrC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAA;IACvB,yEAAyE;IACzE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAC7B;AAsDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,OAAO,EACf,SAAS,EAAE,MAAM,EACjB,aAAa,SAAI,EACjB,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,GAAG,IAAI,CAgGf;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAmB1D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAyClD"}

package/dist/cut-run.js

@@ -345,12 +345,16 @@ export function commandCutRun(command, result, elapsedMs, budgetSeconds = 0, raw
             inlineScript,
         };
     }
-    // The runner printed a summary that does not account for the total it announced, and neither
-    // bound above fired: the process was stopped from outside the run. A run that used the whole
-    // budget is the backend's deadline (which sits just past it); anything else is a stop this tool
-    // does not own. Either way the summary counts are all that ran, and a pipeline's 0 is not the
-    // run's code — the run never reached its own verdict.
-    if (summary !== null && summary.announced !== null) {
+    // A runner's summary that does not account for the total it announced, in a command that
+    // actually RUNS that runner, and neither bound above fired: the process was stopped from
+    // outside the run. The command must run the runner — a reader of a LIVE run's log prints the
+    // same announcement and partial tally as text it copies, and reporting that as a stopped run
+    // told the executor a suite it had only grepped had been killed (X0 xr-molecule-flash-m345,
+    // +50:00: `grep -B2 -A12 … /tmp/mol-bg-….log | head -40` came back `stoppedBy: process-stop`
+    // after 1 s). A run that used the whole budget is the backend's deadline (which sits just past
+    // it); anything else is a stop this tool does not own. Either way the summary counts are all
+    // that ran, and a pipeline's 0 is not the run's code — the run never reached its own verdict.
+    if (suite && summary !== null && summary.announced !== null) {
         const usedBudget = budgetSeconds > 0 && elapsedMs >= atBoundMs(budgetSeconds);
         return {
             seconds: usedBudget ? budgetSeconds : Math.max(1, Math.round(elapsedMs / 1000)),

package/dist/trace-artifacts.d.ts

@@ -18,11 +18,14 @@
  * 401`. So the platform reads it (bounded, per test) and puts it in the run's result
  * ({@link failureTraceNote}), instead of leaving the executor to build its own browser to find out.
  *
- * Everything here is text in, text out: the sandbox runs {@link traceArtifactsScript} (Node, no
- * dependencies — Playwright's zip reader is not importable from a project) and prints one
- * `TRACE <json>` line per trace; the platform parses those lines ({@link parseTraceArtifacts}) and
- * writes the note ({@link failureTraceNote}). Both halves are covered by a test that runs the
- * script against a `trace.zip` produced by a real Playwright run, in the sandbox's own shape.
+ * Everything here is text in, text out: the sandbox runs {@link traceArtifactsScript} (plain Node —
+ * the zip is read without a dependency) and prints one `TRACE <json>` line per trace; the platform
+ * parses those lines ({@link parseTraceArtifacts}) and writes the note ({@link failureTraceNote}).
+ * The one exception is the selector replay behind a `locator.count()` reading: it resolves the
+ * project's own installed Playwright, replays the recorded selector against the recorded snapshot
+ * in that browser's DOM, and reports `browser-unavailable` (naming no elements) when it cannot.
+ * Both halves are covered by a test that runs the script against a `trace.zip` produced by a real
+ * Playwright run, in the sandbox's own shape.
  *
  * @module
  */
@@ -263,6 +266,73 @@ export interface TraceHiddenBox {
     /** True when the element has no text and no element children at all. */
     empty?: true;
 }
+/**
+ * One element a failing locator count matched, read from the trace's own failure snapshot.
+ *
+ * A count assertion reports only `Expected: 3 / Received: 4`; the element that made it 4 is not
+ * in the error. Playwright's trace does hold it — either marked `__playwright_target__` in the
+ * failure snapshot (`expect(locator).toHaveCount(n)`), or recoverable by replaying the recorded
+ * selector against the snapshot's DOM in a browser (`locator.count()` then `expect(n).toBe(k)`) —
+ * so each match is named by what it is and where it sits, never by a guess.
+ */
+export interface TraceCountMatch {
+    /** The element's tag, lowercased (`div`). */
+    tag: string;
+    /** Its `class` attribute, bounded (`card-block`). */
+    classes?: string;
+    /** Its own text, whitespace-collapsed and bounded. */
+    text?: string;
+    /** Its ancestors, outermost first (`body > div.comment-form > div.card`), bounded. */
+    path?: string;
+    /** True when a `<form>` is one of its ancestors — the m321 extra match's shape. */
+    inForm?: true;
+}
+/**
+ * A failing assertion that compared a LOCATOR COUNT (`expect(await locator.count()).toBe(n)` or
+ * `expect(locator).toHaveCount(n)`), with the locator the trace recorded and, when the failure
+ * snapshot can supply them, the elements it matched.
+ *
+ * xr-molecule-flash-m321's `comments.spec.ts:86` sat on `Expected: 3 / Received: 4` for ~30
+ * minutes and three whole suite walks: the helper counted `.card:not(.comment-form) .card-block`,
+ * the app's comment form was a `.comment-form` wrapper around a plain `.card`, and the form's own
+ * `.card-block` made the fourth. The trace had the selector (its `Frame.queryCount` entry) and the
+ * four elements (its failure snapshot); the note printed neither. This reading prints both, and
+ * fails closed — a selector outside the browser's own CSS support, a missing browser, or a replay
+ * that disagrees with the recorded count names no elements rather than inventing them.
+ */
+export interface TraceCountMismatch {
+    /** The locator as the trace or the assertion printed it (`locator('.card:not(…')`). */
+    locator: string;
+    /** The selector inside that locator, when the trace recorded one. */
+    selector?: string;
+    /** The number the assertion expected. */
+    expected: number;
+    /** The number the page matched. */
+    received: number;
+    /**
+     * Where the locator came from: the assertion's own message, or the `locator.count()` entry the
+     * trace recorded just before the failing assertion.
+     */
+    source: 'assertion' | 'locator-count';
+    /** The matched elements, bounded to {@link MAX_COUNT_MATCHES} in document order. */
+    matched?: TraceCountMatch[];
+    /** How many elements matched in total, before the display bound. */
+    matchedTotal?: number;
+    /**
+     * How the elements were read: Playwright's own `__playwright_target__` marks in the failure
+     * snapshot, or the recorded selector replayed against that snapshot in a browser.
+     */
+    matchedFrom?: 'snapshot-targets' | 'selector-replay';
+    /**
+     * Why no elements are named, when they are not. `unsupported-selector` is a selector the
+     * browser's `querySelectorAll` rejects (a `getByRole`/`getByText` engine, `>>` chaining);
+     * `no-snapshot` is a trace with no readable DOM snapshot at the failure; `count-mismatch` is a
+     * replay that disagreed with the recorded count, so the snapshot is not evidence for this
+     * assertion; `browser-unavailable` is a project whose Playwright module or recorded engine
+     * executable could not be resolved, so the selector could not be replayed at all.
+     */
+    unreadable?: 'unsupported-selector' | 'no-snapshot' | 'count-mismatch' | 'browser-unavailable';
+}
 /**
  * One method+path a test's page sent many times — the trace of a render loop.
  *
@@ -376,6 +446,13 @@ export interface TraceArtifact {
      * leaving the run to probe computed styles (xr-molecule-flash-m197).
      */
     hiddenBox?: TraceHiddenBox;
+    /**
+     * A failing assertion that compared a locator count, with the locator the trace recorded and the
+     * elements its failure snapshot matched ({@link TraceCountMismatch}). The row prints them, so a
+     * count that is off by one names the extra element instead of leaving the run to probe for it
+     * (xr-molecule-flash-m321's 30-minute `Expected: 3 / Received: 4`).
+     */
+    countMismatch?: TraceCountMismatch;
     /**
      * The method+path groups this test's page sent {@link TRACE_NOTE_LOOP_REPEATS} times or more,
      * most-repeated first — a render loop the note leads with (xr-molecule-flash-m215: 2,106
@@ -601,6 +678,27 @@ export declare function isCredentialExchangePath(path: string, authEndpoints?: r
  * @returns The sentence, or null when no failure carries a hidden-box reading.
  */
 export declare function hiddenBoxNote(items: readonly TraceArtifact[]): string | null;
+/**
+ * The row's sentence for a failing count assertion: the locator, both numbers, and the elements
+ * the failure snapshot held.
+ *
+ * xr-molecule-flash-m321's `comments.spec.ts:86` printed only `Expected: 3 / Received: 4`. The
+ * helper counted `.card:not(.comment-form) .card-block`, and the app's comment form was a
+ * `.comment-form` wrapper around a plain `.card`, so the form's own `.card-block` was the fourth
+ * match. The trace held the selector and the four elements; the note held neither.
+ *
+ * @param mismatch - The trace's count reading ({@link TraceCountMismatch}).
+ * @returns The sentence.
+ */
+export declare function countMismatchSentence(mismatch: TraceCountMismatch): string;
+/**
+ * The sentence a count assertion earns when every traced failure is one — the next read before
+ * the API or the request is changed.
+ *
+ * @param items - The traces {@link parseTraceArtifacts} read.
+ * @returns The sentence, or null when not every traced failure is a count mismatch.
+ */
+export declare function countMismatchNote(items: readonly TraceArtifact[]): string | null;
 /**
  * The note a failed suite run's result carries: what each failing test's page actually sent, and
  * what came back.