@molecule/api-ai-tools 1.6.6 → 1.8.1

package/README.md

@@ -3,15 +3,11 @@ 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-16T21:18:13.332Z
+Generated: 2026-10-17T02:50:55.123Z
 -->
 
 # @molecule/api-ai-tools
 
-> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
-> It is written to be read by coding agents as much as by people, and is generated from this
-> package's source — edit `src/index.ts` JSDoc, not this file.
-
 Shared AI agent tool set for molecule.dev — filesystem, search, and shell
 tools an LLM agent can call, with a swappable execution backend.
 
@@ -24,6 +20,10 @@ WHERE they act: `createLocalBackend(projectRoot)` (host filesystem) or
 container). `buildAgentPrompt(ctx)` composes a matching system prompt
 (identity, tool listing, project docs, discovered skills).
 
+> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
+> It is written to be read by coding agents as much as by people, and is generated from this
+> package's source — edit `src/index.ts` JSDoc, not this file.
+
 ## Quick Start
 
 ```typescript
@@ -81,6 +81,72 @@ interface CommandSegment {
 }
 ```
 
+#### `LocatedCommandSegment`
+
+One statement of a shell command, with where it sits and the variables it sets for itself.
+
+`commandSegments` answers WHAT runs; this answers where, and what the shell binds to it — the
+two things a caller that WRITES into a command needs. The platform composes a run from the
+executor's own command in more than one place, and a value written for the runner belongs in
+the runner's own statement: `APP_BASE=https://… cd app && npx playwright test` sets the variable
+for `cd` alone, so the Playwright config falls back to the local app while the command line
+still names the deployed host (xr-molecule-flash-m103 +28:08).
+
+```typescript
+interface LocatedCommandSegment {
+  /**
+   * What the statement runs, or null when it only sets variables (`BASE=http://…` on its own):
+   * that shape persists in the shell, so a caller following assignments across `;`/`&&` has to
+   * see it.
+   */
+  segment: CommandSegment | null
+  /** The statement's own leading `NAME=value` words, as written (`TEST_MODE=fullstack`). */
+  assignments: readonly string[]
+  /**
+   * The offset in the command of the statement's first word, or null for a segment inside a
+   * nested `sh -c '<command>'` string — its positions are offsets in THAT string, not in this
+   * command, so nothing may be spliced at them.
+   */
+  start: number | null
+  /**
+   * The offset in the command just before the word the statement runs — after its own leading
+   * `NAME=value` words and their whitespace. A `NAME=value` written here is in the environment of
+   * the program the statement runs (`… TEST_MODE=fullstack <here>npx playwright test`). Null
+   * inside a nested `sh -c` string, for the same reason as {@link start}.
+   */
+  assignmentOffset: number | null
+}
+```
+
+#### `SuiteSummary`
+
+What a runner's own closing summary reports, and whether it accounts for the whole run.
+
+A summary is not by itself proof that the run finished. Playwright prints one when its process
+is stopped too (SIGTERM/SIGINT), listing only the tests it reached — so a run killed at 36 of
+139 tests ends with the same `36 passed (2.5m)` line as a run that walked all 139. The only
+thing that separates them is the total the runner announced before it started
+(`Running 139 tests using 1 worker`), which {@link suiteSummary} reconciles the summary against.
+
+```typescript
+interface SuiteSummary {
+  /**
+   * The total the runner announced before its first test, or null when it announced none (Hurl
+   * announces nothing; Vitest's own summary line carries its total in parentheses).
+   */
+  announced: number | null
+  /**
+   * Every test the summary accounts for — the ones it passed, failed, marked flaky, timed out,
+   * interrupted, skipped or left "did not run". This is how far the walk got, which is what a
+   * stopped run's sentence says; a summary that accounts for fewer than {@link announced} was
+   * printed by a process that stopped early.
+   */
+  accounted: number
+  /** Whether the summary accounts for every test the runner announced. */
+  finished: boolean
+}
+```
+
 #### `CutRun`
 
 A run a budget stopped, as its result reports it.
@@ -96,9 +162,15 @@ interface CutRun {
    * the pipeline's filter (`… | tail`) rather than to the run — the case that read as success.
    */
   exitCode: number | null
-  /** How many files or tests the runner's own output shows finishing, or null when it shows none. */
+  /**
+   * How far the run got, as its own output counts it — the files that finished, or the tests its
+   * summary accounts for — or null when the output says nothing.
+   */
   ran: number | null
-  /** How many the run was walking, when the runner printed it (Playwright's `[n/K]`), or null. */
+  /**
+   * How many the run was walking: the total its runner announced (`Running 139 tests`), or
+   * Playwright's `[n/K]`, whichever the output carries; null when neither does.
+   */
   total: number | null
   /** The noun the runner counts in. */
   noun: 'files' | 'tests'
@@ -186,6 +258,51 @@ interface SuiteRunInFlight {
 }
 ```
 
+#### `TraceRequest`
+
+One request a traced page made, as `*.network` records it.
+
+```typescript
+interface TraceRequest {
+  /** The HTTP method (`POST`). */
+  method: string
+  /** The request's path (`/api/articles/x/favorite`), or the whole URL when it is cross-origin. */
+  path: string
+  /** The response status, or 0 when the request never got a response. */
+  status: number
+}
+```
+
+#### `TraceArtifact`
+
+What one trace says: the test it belongs to, the requests it made, and its console errors.
+
+```typescript
+interface TraceArtifact {
+  /** The failure's spec file, relative to the run's directory, when the trace names one. */
+  spec: string | null
+  /** The line of the test's last traced step, 0 when the trace names no spec. */
+  line: number
+  /** The requests the page made, the interesting ones first ({@link traceArtifactsScript}). */
+  requests: TraceRequest[]
+  /** The console errors and page errors the page raised. */
+  console: string[]
+}
+```
+
+#### `DiagnosisTraceRewrite`
+
+A command with the trace flag this platform decided to add, and the sentence to report it in.
+
+```typescript
+interface DiagnosisTraceRewrite {
+  /** The command to run. */
+  command: string
+  /** One sentence naming the flag and why, or null when nothing was added. */
+  change: string | null
+}
+```
+
 #### `ExecutionBackend`
 
 Abstraction over the execution environment.
@@ -331,6 +448,20 @@ interface ToolBuildConfig {
    */
   outlineLargeHtml?: () => boolean
 
+  /**
+   * The test titles the person's request EXCLUDES by name (molecule-dev's `excludedTestTitles`),
+   * asked when a finished suite run's cause note is built. Their failures are not causes to fix:
+   * the note drops them, says so at the end, and inverts them out of the narrowed re-run it hands
+   * over — a result must never name a test beside "it does not count" (xr-molecule-flash-m101
+   * +12:00, where the executor spent a turn and an edit on the excluded test).
+   *
+   * A getter, not an array, because the request is read per turn while the tool set is built
+   * once. Unset means no test is excluded.
+   *
+   * @returns The quoted titles the request carves out.
+   */
+  excludedTestTitles?: () => readonly string[]
+
   /** Post-write hook (e.g. auto-format via Prettier/ESLint). Called after every write_file/edit_file. */
   onAfterWrite?: (path: string) => Promise<void>
 
@@ -409,6 +540,19 @@ interface PromptContext {
 }
 ```
 
+#### `SuiteFilterStrip`
+
+A command with the output filters after its suite runner removed.
+
+```typescript
+interface SuiteFilterStrip {
+  /** The command to run. */
+  command: string
+  /** The pipeline stages dropped, as written (`| grep … | tail -20`), or '' when none were. */
+  dropped: string
+}
+```
+
 #### `FailedTest`
 
 One failed test, as a running suite's log names it.
@@ -469,6 +613,12 @@ interface FailureCause {
   seconds: number | null
   /** The distinct tests it hit, in the order the log named them. */
   tests: FailedTest[]
+  /**
+   * The FIRST failure's two most useful body lines — the values that differ, or the locator from
+   * its `Call log` ({@link failureEvidence}) — so a fix round needs no re-read of the log. Empty
+   * for a duration group, whose blocks carried no bodies.
+   */
+  evidence: string[]
 }
 ```
 
@@ -487,7 +637,17 @@ type CommandRunState = 'ran' | typeof CUT_AT_BUDGET
 What stopped a run.
 
 ```typescript
-type CutBy = 'tool-budget' | 'command-timeout'
+type CutBy =
+  /** This tool's own budget (the backend's `timeout`, just past it). */
+  | 'tool-budget'
+  /** The `timeout <N>` the command itself carried. */
+  | 'command-timeout'
+  /**
+   * Something outside the run: the runner's summary does not account for the total it announced,
+   * and neither of the two bounds above had fired — the process was killed by something this
+   * platform does not own (the sandbox's own process supervisor, the box going away, a signal).
+   */
+  | 'process-stop'
 ```
 
 #### `DiscoveredSkill` _(deprecated)_
@@ -563,6 +723,20 @@ function commandSegments(command: string): CommandSegment[]
 
 **Returns:** One entry per statement or pipeline stage that runs something, in order.
 
+#### `locatedCommandSegments(command)`
+
+Every statement of a command, with its own assignments and where it sits — assignment-only
+statements included, because the variables those persist are exactly what a later statement of
+the same command reads.
+
+```typescript
+function locatedCommandSegments(command: string): LocatedCommandSegment[]
+```
+
+- `command` — The shell command.
+
+**Returns:** One entry per statement or pipeline stage, in order.
+
 #### `commandTimeoutSeconds(command)`
 
 The bound a command puts on its own run: the largest `timeout <N>` any of its segments runs
@@ -617,9 +791,29 @@ function commandRunState(result: unknown): CommandRunState
 
 **Returns:** The state the result records.
 
+#### `suiteSummary(text)`
+
+What the runner's closing summary accounts for, or null when it printed none.
+
+Three runners' summaries are read, each by its own wording: Playwright's per-status lines
+(reconciled against its `Running N tests` announcement), Vitest's single `Tests …` line (its own
+parenthesised total), and Hurl's `Executed files:` block (which it prints only at the end, and
+which announces no total — so it is a finish by construction).
+
+```typescript
+function suiteSummary(text: string): SuiteSummary | null
+```
+
+- `text` — The run's stdout and stderr, RAW (a truncated copy can lose the announcement).
+
+**Returns:** The summary, or null when the text carries none.
+
 #### `suiteTally(text)`
 
-Whether text carries a runner's closing summary ({@link SUITE_TALLY}).
+Whether text carries a runner's closing summary.
+
+A summary is NOT a finish on its own — a stopped Playwright run prints one too. Use
+{@link suiteSummary} and its `finished` for that.
 
 ```typescript
 function suiteTally(text: string): boolean
@@ -629,13 +823,39 @@ function suiteTally(text: string): boolean
 
 **Returns:** True when the runner's own end-of-run summary is there.
 
-#### `commandCutRun(command, result, elapsedMs, budgetSeconds)`
+#### `suiteRunExitCode(exitCode, output, piped)`
+
+The exit code a finished suite run may report.
+
+The code in a background result is the code of the command's LAST pipeline stage. When a stage
+after the suite runner still consumes its output (`| tee run.log`, or a filter the platform could
+not prove output-only), that stage produced the code, not the run — and `… | grep … | tail -20`
+exited 0 for a run with a failure in it (xr-molecule-flash-m101 +25:54). No code is reported
+then: the log's own tally decides.
+
+The same reading covers a code of 0 beside a tally that names a failure: whatever ended the
+pipeline, a run whose log counts a failure did not pass.
+
+```typescript
+function suiteRunExitCode(exitCode: number | null, output: string, piped: boolean): number | null
+```
+
+- `exitCode` — The code the pipeline reported (null when it has none).
+- `output` — The run's full log.
+- `piped` — Whether a pipeline stage after the suite runner still consumes its output.
+
+**Returns:** The code the run may report, or null when the code is the filter's or contradicts the tally.
+
+#### `commandCutRun(command, result, elapsedMs, budgetSeconds, rawOutput)`
 
 The run a command's result records as stopped by a budget, or null when the result is a run that
 ended (or says nothing about a run).
 
 Evidence, in order — never a guess:
 
+- the runner's own summary, when it printed one: it is a finish only if it accounts for the total
+  the runner announced. A summary that accounts for fewer is a walk a process stopped early, and
+  falls through to the branches below with its own counts ({@link suiteSummary}).
 - `timeout`'s own 124 (the code the backend's wrapper returns whenever the TOOL's budget fired,
   whatever the pipeline ended with) — and, when the clock says the command's own smaller bound
   ran out first and less than the budget, that bound instead.
@@ -644,6 +864,8 @@ Evidence, in order — never a guess:
   killed at its own bound. Its exit code, when the pipeline handed one back, is the filter's.
 - the run used this tool's whole budget behind a filter that withheld its output, and printed no
   closing summary: the budget stopped it, and no code in the result is the run's.
+- a summary that does not account for its announced total, with neither bound fired: something
+  outside this platform stopped the process ({@link CutBy} `process-stop`).
 
 ```typescript
 function commandCutRun(
@@ -651,6 +873,7 @@ function commandCutRun(
   result: unknown,
   elapsedMs: number,
   budgetSeconds?: number,
+  rawOutput?: string,
 ): CutRun | null
 ```
 
@@ -658,6 +881,7 @@ function commandCutRun(
 - `result` — Its result.
 - `elapsedMs` — How long the command ran, in ms.
 - `budgetSeconds` — This tool's foreground budget, in seconds (0 when it has none).
+- `rawOutput` — The run's output BEFORE truncation, when the caller has it: the announcement a summary is reconciled against is the first line a long run prints, which is exactly what a size cap drops. Detection reads this; the sentence's last line still comes from `result`.
 
 **Returns:** The stopped run, or null.
 
@@ -681,12 +905,14 @@ function cutRunFacts(result: unknown): CutRun | null
 
 #### `cutRunSentence(run)`
 
-The first line of a stopped run's result: how long it was allowed, what stopped it, how far it
-got, and the last thing it printed.
+The first line of a stopped run's result: how far it got, what stopped it, the last thing it
+printed, and what the reader must do next.
 
 Written to be quotable by the model in one sentence and to leave no room for "nearly passing":
 the counts come from the runner's own output ({@link runProgress}), and a `total` the caller
-read elsewhere (the suite's own file count) fills in the "M of K" it can then state.
+read elsewhere (the suite's own file count) fills in the "of N" it can then state. The sentence
+says how many tests the stop left unrun — a number a reader cannot round up to "the suite
+passed" — and hands over the one move that survives a long run: run it in the background.
 
 ```typescript
 function cutRunSentence(run: CutRun): string
@@ -835,7 +1061,7 @@ function suiteCommandTarget(command: string): string
 
 **Returns:** The target key.
 
-#### `scopedRerunCommand(command, locations)`
+#### `scopedRerunCommand(command, locations, excluded)`
 
 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
@@ -843,11 +1069,16 @@ suite, `--last-failed` dropped (it re-runs the tests that never ran too, X1 flas
 `--retries=0` set (a re-run of a known failure does not need to pay for retries).
 
 ```typescript
-function scopedRerunCommand(command: string, locations: readonly string[]): string
+function scopedRerunCommand(
+  command: string,
+  locations: readonly string[],
+  excluded?: readonly string[],
+): string
 ```
 
 - `command` — The whole-suite run's command.
 - `locations` — The failing `file:line`s to re-run, as the run's own log printed them — or, for a run that started outside the suite, the absolute form Playwright matches each file argument against.
+- `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.
 
 **Returns:** The scoped command, or the command unchanged when it runs no Playwright suite.
 
@@ -1025,6 +1256,107 @@ function buildTools(backend: ExecutionBackend, config?: ToolBuildConfig): AITool
 
 **Returns:** Array of AITool objects ready to pass to an AI provider
 
+#### `traceArtifactsScript()`
+
+The Node program the sandbox runs to read a failed run's traces: `node <script> <dir>` prints one
+`TRACE <json>` line per `trace.zip` under `<dir>` (newest first, {@link MAX_TRACE_ARTIFACTS} of
+them), each with the test it belongs to, the requests its page made and its console errors.
+
+It is a standalone program, not an import, for the reason `@molecule/api-code-sandbox` runs it:
+Playwright's own zip reader is not reachable from a project's `node_modules`, and a dependency
+on `unzip` would make the read fail on every sandbox that has none. The zip is read with the
+central directory and `zlib.inflateRawSync` — about forty lines, and the only thing that has to
+be true of a `trace.zip` is that it IS one.
+
+A request is kept over a static asset when it failed (`status >= 400`) or never answered
+(`status === 0`), and over anything else when it is the page talking to the app
+(`fetch`/`xhr`/`document`): a failing test's trace holds the whole page load, and the answer is
+always at the end of it.
+
+```typescript
+function traceArtifactsScript(): string
+```
+
+**Returns:** The program's source, to write to a file and run.
+
+#### `parseTraceArtifacts(stdout)`
+
+The traces {@link traceArtifactsScript} printed, parsed.
+
+A line that is not a complete `TRACE <json>` (a truncated read, a program that died mid-write) is
+dropped: a partial trace is not evidence about the test it came from.
+
+```typescript
+function parseTraceArtifacts(stdout: string): TraceArtifact[]
+```
+
+- `stdout` — The program's output.
+
+**Returns:** One entry per trace it printed.
+
+#### `failureTraceNote(items, target)`
+
+The note a failed suite run's result carries: what each failing test's page actually sent, and
+what came back.
+
+This is the answer to the question a swallowed error hides — a click that changed nothing is
+usually a request that failed — so the note leads with the failing requests and says what to do
+with them: read the handler the route reaches, not the selector. It is BOUNDED to
+{@link MAX_TRACE_NOTE_TESTS} tests with {@link MAX_TRACE_NOTE_REQUESTS} requests each, because it
+rides in a result the model pays for.
+
+```typescript
+function failureTraceNote(items: readonly TraceArtifact[], target: string): string | null
+```
+
+- `items` — The traces {@link parseTraceArtifacts} read.
+- `target` — Where the run went — the deployed host, as the note names it.
+
+**Returns:** The note, or null when no trace held a request or a console error.
+
+#### `suiteRecordsTraces(configText)`
+
+Whether a Playwright config records traces for the tests that fail.
+
+Only `on` and `retain-on-failure` keep a `trace.zip` for a failure whatever the retries do: the
+two retry modes need a retry to happen at all, and a diagnosis run is given `--retries=0`
+(`streamingBackgroundCommand`), so on X1 xr-molecule-flash-m100 the run's own
+`trace: 'on-first-retry'` recorded nothing — which is what left the failing tests' network log
+unreadable. A config that sets no `trace:` at all records nothing either (Playwright's default
+is off); so does one that cannot be read.
+
+```typescript
+function suiteRecordsTraces(configText: string): boolean
+```
+
+- `configText` — The config's source, or '' when none could be read.
+
+**Returns:** True when the config records traces for failures.
+
+#### `diagnosisTraceCommand(args)`
+
+The command a DIAGNOSIS run needs to leave a readable trace behind, when the suite's config
+would record none.
+
+The failing tests' requests are only readable if the run wrote them down (see the module doc),
+and the config is where the decision about that lives — the platform does not edit the suite's
+config, so it passes the flag instead, and only where it can do no harm: on a run narrowed to a
+part of the suite or capped ({@link isDiagnosisRun}), never on the whole-suite proof run, and
+never over a `--trace` the executor wrote itself. A capped walk is exactly the run whose
+failures someone is about to work on; the proof run is graded as it is.
+
+```typescript
+function diagnosisTraceCommand(args: {
+  command: string
+  cwd: string
+  readFile: (path: string) => Promise<string>
+}): Promise<DiagnosisTraceRewrite>
+```
+
+- `args` — The command, the directory it starts in, and the backend's file read.
+
+**Returns:** The command to run and the sentence to report, or the command unchanged.
+
 #### `shellQuote(s)`
 
 Shell-safe quoting using single quotes. Unlike JSON.stringify (double quotes),
@@ -1185,19 +1517,19 @@ killed (X1 run flash-m15 lost 20 of its 60 minutes this way, 2026-10-15):
 
 - a trailing `| tail -N`, which holds everything back until the command ends.
   It is dropped: `wait_for_task` already returns the end of the log.
+- any output-only filter piped after a SUITE runner (`| grep … | tail -20`), which hides the
+  failing test's own error and leaves the pipeline's exit status — the filter's — as the run's.
+  Every such stage is dropped ({@link stripTrailingSuiteFilters}); `wait_for_task` already
+  returns the end of the full log, and a run whose tally shows a failure must never report 0
+  (xr-molecule-flash-m101 +25:54).
 - `playwright test` with no `--reporter`, which runs the config's reporter —
   often `html`, which prints nothing per test. `--reporter=list` is added
-  when the playwright run is the command's last step and nothing is piped or
-  redirected from it: it writes each result as it finishes, and it is the
-  shape the platform reads a background suite back in.
+  when the playwright run is the command's last step, piped or not: it writes each result as
+  it finishes, and it is the shape the platform reads a background suite back in.
 
 The run ends up with exactly ONE reporter that prints each failure — `list`. A run that names
 any other printing reporter has it REPLACED, never joined: two of them write every test result
 into the log twice, which on X1 flash-m83 (2026-10-16) made a `--reporter=list,line` run (its
-`line` added by this function one run earlier) report two distinct failures as "4 of this run's
-tests have already failed the same way", and the executor stopped a 139-test walk at test 21
-with a single cause in hand. `line` alone is no use either: it writes `[n/N] <title>` with no
-✓/✘ mark and no duration, so on X1 flash-m62 an 8.3-minute walk of one suite could never trip
 
 _(description truncated — read the full text in `node_modules/@molecule/api-ai-tools/dist/utilities.d.ts`.)_
 
@@ -1247,6 +1579,47 @@ function isPlaywrightRunCommand(command: string): boolean
 
 **Returns:** True when the command starts a Playwright run.
 
+#### `stripTrailingSuiteFilters(command)`
+
+Drop the output-only filters piped after the command's suite runner.
+
+A filter after the runner is not "the end of the log" the executor asked for: it hides the
+failing test's own error (it usually matches none of `✘|passed|failed`), and the pipeline's exit
+status becomes the FILTER's, so `… 2>&1 | grep -E "✘|passed|failed|skipped" | tail -20` came back
+`exitCode: 0` for a run with a failure in it (xr-molecule-flash-m101 +25:54). The tool returns
+the end of the full log anyway, so the filter only costs diagnosability.
+
+Only a contiguous suffix of the stages after the runner is cut, and only stages the parse proves
+are output-only ({@link isOutputOnlyFilter}): a `| tee` or `| xargs` keeps its place, and a
+caller that reports the run's exit code must then treat it as unknown
+({@link suiteRunPipedAfterRunner}).
+
+```typescript
+function stripTrailingSuiteFilters(command: string): SuiteFilterStrip
+```
+
+- `command` — The shell command.
+
+**Returns:** The rewritten command and the stages dropped.
+
+#### `suiteRunPipedAfterRunner(command)`
+
+Whether the command's last step runs a suite whose output still passes through a stage after
+the runner — one {@link stripTrailingSuiteFilters} could not prove is output-only (`| tee log`,
+`| xargs …`). The pipeline's exit status is that stage's, not the run's.
+
+A command whose stages cannot be placed in the text (irregular whitespace inside the run) is
+reported as piped too: whether a pipe follows the runner is then UNKNOWN, and an unknown exit
+code that gets trusted is a failing run read as a pass — the failure this rule exists to stop.
+
+```typescript
+function suiteRunPipedAfterRunner(command: string): boolean
+```
+
+- `command` — The shell command, after the streaming rewrite when one was applied.
+
+**Returns:** True when a pipe this tool must not drop still follows the suite runner, or when the command runs a suite the parse cannot place.
+
 #### `suiteRunPriorityLaunch(command, launch)`
 
 Start a background suite run at lower CPU and IO priority, so the sandbox it
@@ -1661,10 +2034,12 @@ function failureBlocks(s: string): string[]
 The shell command whose stdout is the interesting part of a log that is still being written:
 the failure lines so far (capped at {@link RUNNING_FAILURE_LINES}), then the end of the log.
 
-A Playwright `list` run prints one line per test as it finishes and its error blocks only at
-the end, so the LAST bytes of a running log are its least informative part — in X1 flash-m61
-the last 3 000 bytes of a 139-test walk were the skip list, and all 61 failures were above
-them, which cost the run the grep it had to make anyway.
+A Playwright `list` run prints one line per test as it finishes, so the LAST bytes of a running
+log are its least informative part — in X1 flash-m61 the last 3 000 bytes of a 139-test walk
+were the skip list, and all 61 failures were above them, which cost the run the grep it had to
+make anyway. A background run also carries each failure's own error as it fails
+({@link PLAYWRIGHT_FAILURES_INLINE_ENV}), and {@link RUNNING_FAILURE_LINE_RE} already matches
+those blocks' headers and their `Error:` lines, so this slice shows the causes too.
 
 ```typescript
 function runningOutputSliceCommand(log: string, own?: string): string
@@ -1700,9 +2075,11 @@ function runningCauseCommand(log: string, own?: string): string
 The cause repeating among a running suite's failures, or null.
 
 Playwright's `list` reporter prints one line per test as it finishes — its mark, its title
-path and how long it ran — and defers each failure's error to the summary at the end, so
-mid-run the only signature those lines carry is the duration. Where the log carries the
-failure bodies (a `line` reporter's output, or a finished run's summary) the signature is the
+path and how long it ran — and, on a run the platform started in the background, each failure's
+own error with it ({@link PLAYWRIGHT_FAILURES_INLINE_ENV}); a `list` run with no error bodies in
+its log (an older Playwright, a log the bodies have been cut from) carries only the duration as
+a signature. Where the log carries the failure bodies (either inline, or in a finished run's
+summary) the signature is the
 error itself — {@link failureMessage}: the error class plus the locator or the values that
 differ — which is stronger (it needs no assumption about how long a failure should take), so
 the message is looked for first and the duration is then left with the tests whose bodies the
@@ -1715,8 +2092,8 @@ each was the test timeout and one missing `navigate('/')` was the cause of all o
 
 The quorum is of DISTINCT tests — {@link REPEATING_FAILURE_MIN} of them — because a log that
 prints each failure twice (a second reporter, a retry) had X1 flash-m83 told that four of its
-tests had failed the same way when two had, so the executor stopped a 139-test walk at test 21
-with one cause in hand (2026-10-16).
+
+_(description truncated — read the full text in `node_modules/@molecule/api-ai-tools/dist/utilities.d.ts`.)_
 
 ```typescript
 function repeatingFailure(log: string): RepeatingFailure | null
@@ -1751,7 +2128,69 @@ function universalCause(log: string, found: RepeatingFailure): UniversalCause |
 
 **Returns:** The cause's count and files, or null when the run is not failing whole.
 
-#### `failuresByCause(log)`
+#### `earlyReturnCause(found, universal)`
+
+The ONE finding that ends a wait early, and the only one a note may hand a stop command over
+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
+  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.
+- **A PROVEN cause** is an error repeated VERBATIM. A shared DURATION is a LEAD, never a cause:
+  a suite whose config sets a timeout spends that timeout on every failure that waits for
+  anything, so three unrelated tests timing out together look exactly like one broken run
+  (`~7 s` is a property of the CONFIG, not of the cause — {@link normalizedSignature}). X1
+  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`.)_
+
+```typescript
+function earlyReturnCause(
+  found: RepeatingFailure,
+  universal: UniversalCause | null | undefined,
+): UniversalCause | null
+```
+
+- `found` — What {@link repeatingFailure} found mid-run.
+- `universal` — What {@link universalCause} found for it, if anything.
+
+**Returns:** The cause to stop the run over, or null — in which case nothing may be stopped, the wait keeps going, and the finding rides the run's result as a note.
+
+#### `matchingExcludedTitles(heading, excluded)`
+
+The titles a request excludes that a test's heading names — the ONE matcher for "is this
+failure one the request does not count?".
+
+The request quotes a test's own title (`… except "should require login to post comment"`,
+extracted by molecule-dev's `excludedTestTitles`) while a run's heading carries more of it
+(`comments.spec.ts › Comments › should require login to post comment`), so containment is the
+comparison. Whitespace is normalised and case is ignored: a brief may wrap the title across a
+line (`xr-molecule-flash-m44`), and the reporter's own casing never has to match the brief's.
+
+Two readers used to answer this separately — the causes note (which therefore asked the
+executor to fix a test the same result said not to) and molecule-dev's exclusion notes — and
+xr-molecule-flash-m101 paid for the gap (+12:00: a turn and an edit spent on the excluded
+test).
+
+```typescript
+function matchingExcludedTitles(heading: string, excluded: readonly string[]): string[]
+```
+
+- `heading` — The text to match against: a test's title, its whole `file › describe › title` path, or (for a note that only has the run's output) the run's text.
+- `excluded` — The titles the request carves out, if the caller knows them.
+
+**Returns:** The excluded titles this heading names, in the request's order.
+
+#### `failuresByCause(log, excluded)`
 
 Every failure a run names, grouped by the cause behind it — one group per cause, with the
 tests it hit.
@@ -1761,21 +2200,28 @@ after another with no statement of which of them share a cause, so a run of 19 f
 bodies to read; X1 flash-m83 (2026-10-16) spent three deploys (6.7 minutes) each fixing a
 single cause, two of them found by runs stopped before they walked the rest.
 
-The signature is the cause itself where the log carries the failures' bodies (a finished run,
-or a `line` reporter) — {@link failureMessage}: the error class plus the locator or the values
-that differ — and how long they took where it does not (a still-running `list` log, which is
-why a duration group is labelled as a duration and not as a proven cause). A test the log
-printed twice, or failed twice, is one test.
+The signature is the cause itself where the log carries the failures' bodies (a finished run, a
+background `list` run — whose failures print as they fail — or a `line` reporter) —
+{@link failureMessage}: the error class plus the locator or the values that differ — and how long
+they took where it does not, which is why a duration group is labelled as a duration and not as a
+proven cause. A test the log printed twice, or failed twice, is one test.
+
+A test the request EXCLUDES by name is not a cause to fix: its failure does not count for
+this request ({@link matchingExcludedTitles}), so it is dropped here rather than handed to the
+executor as work — a result that names it beside "it does not count" is the contradiction
+xr-molecule-flash-m101 filed (+12:00: the model spent a turn and an edit on the excluded test,
+on a page that was passing).
 
 ```typescript
-function failuresByCause(log: string): FailureCause[]
+function failuresByCause(log: string, excluded?: readonly string[]): FailureCause[]
 ```
 
 - `log` — The log of a finished or running run.
+- `excluded` — The test titles the request carves out, if the caller knows them.
 
 **Returns:** The causes, the one with the most tests first.
 
-#### `failureCausesNote(log)`
+#### `failureCausesNote(log, excluded, run)`
 
 The one-line-per-cause summary of a finished run's failures, or null when the run named fewer
 than two of them.
@@ -1784,15 +2230,26 @@ This is what makes a run worth finishing: every cause the run found, in the resu
 executor reads, so one round of fixes covers all of them rather than the one cause a run
 stopped early happened to reach.
 
+A test the request excludes is not one of the causes — it is dropped and named once, at the
+end, so a result never asks to fix a test it also says to ignore. Where the caller knows how
+the run was started, the note also hands over the narrowed re-run of exactly those tests
+({@link rerunOfRunningSuite}) instead of leaving the executor to re-run the whole suite.
+
 ```typescript
-function failureCausesNote(log: string): string | null
+function failureCausesNote(
+  log: string,
+  excluded?: readonly string[],
+  run?: { command: string; cwd?: string; log?: string },
+): 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`, 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.
 
-#### `rerunOfRunningSuite(run, locations)`
+#### `rerunOfRunningSuite(run, locations, excluded)`
 
 The command that re-runs the tests at `locations` the way the run IN FLIGHT ran them: the same
 invocation, in the same directory, narrowed to those tests — or null when the running command
@@ -1809,11 +2266,13 @@ the same app and database, and that is exactly what is refused while the run wal
 function rerunOfRunningSuite(
   run: { command: string; cwd?: string },
   locations: readonly string[],
+  excluded?: readonly string[],
 ): string | null
 ```
 
 - `run` — The run in flight: the command it was started with, as it was run, and the directory that command ran in.
 - `locations` — The failing `file:line`s to re-run, as the run's log printed them.
+- `excluded` — The test titles the request carves out: the re-run inverts them out (`--grep-invert`) so it cannot report them again.
 
 **Returns:** The re-run command, or null when there is no suite to narrow.
 
@@ -1826,18 +2285,19 @@ what that function could actually see in the log — including the count, which
 tests, so the note never names one or two tests as a cause.
 
 The note names the cause early so the executor can START FIXING while the run keeps walking,
-and it asks for the run to be stopped only when {@link universalCause} says the cause is
-failing the whole run. X1 flash-m76 (2026-10-16) spent 4.0 minutes walking 15 tests whose one
-cause was certain at the third, 47 s in, and the note answers exactly that; X1 flash-m83 then
-stopped eight runs at their first repeating cause in 14.5 minutes and never finished one, so
-the note must not say to stop when the run still has other causes to name.
+and it hands a stop command over only when {@link earlyReturnCause} says so — the SAME
+predicate the wait uses to decide whether to return early, so a finding the wait keeps waiting
+on is a finding this note never asks to stop for. X1 flash-m76 (2026-10-16) spent 4.0 minutes
+walking 15 tests whose one cause was certain at the third, 47 s in, and the note answers
+exactly that; X1 flash-m83 then stopped eight runs at their first repeating cause in 14.5
+minutes and never finished one, so the note must not say to stop when the run still has other
+causes to name. X1 xr-molecule-flash-m99 (2026-10-16) is the third shape: a shared duration is
+not a cause at all, so a lead reaches the executor as a note on a result it is still waiting
+for — never as a verdict with a stop command in it.
 
 The run is STILL WALKING while this note is written — both callers produce it mid-run — so a
 re-run of one of its tests is a second run against the same app and database, and the platform
 refuses that ({@link suiteRunInTheWay}, the same rule its overlap hold answers with):
-xr-molecule-flash-m89 (2026-10-16) read _"Start on them now, while the run keeps walking.
-`null-fields.spec.ts:53` alone reproduces the first one."_ and sent exactly that re-run 23 s
-later, where the hold answered *"A playwright suite is already running against this app and
 
 _(description truncated — read the full text in `node_modules/@molecule/api-ai-tools/dist/utilities.d.ts`.)_
 
@@ -1855,7 +2315,7 @@ function repeatingFailureNote(
 ```
 
 - `found` — What {@link repeatingFailure} found.
-- `o` — The run's facts: its `taskId`, its `log` path, `stop` — the shell command that stops it, printed only for a {@link UniversalCause} — `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), and `run`, how the run was started ({@link rerunOfRunningSuite}) when the caller knows it.
 
 **Returns:** The note.
 
@@ -1982,6 +2442,80 @@ per-request limit, with each request bounded. xr-molecule-flash-m93 (+06:22,
 const SUITE_OVER_BUDGET_ADVICE: string
 ```
 
+#### `MAX_TRACE_ARTIFACTS`
+
+How many traces one read reports, newest first.
+
+```typescript
+const MAX_TRACE_ARTIFACTS: 12
+```
+
+#### `MAX_TRACED_REQUESTS`
+
+How many requests one test's trace contributes.
+
+```typescript
+const MAX_TRACED_REQUESTS: 6
+```
+
+#### `MAX_TRACED_CONSOLE`
+
+How many console errors one test's trace contributes.
+
+```typescript
+const MAX_TRACED_CONSOLE: 4
+```
+
+#### `MAX_TRACE_NOTE_TESTS`
+
+How many tests the note in a run's result names.
+
+```typescript
+const MAX_TRACE_NOTE_TESTS: 5
+```
+
+#### `MAX_TRACE_NOTE_REQUESTS`
+
+How many requests the note names per test.
+
+```typescript
+const MAX_TRACE_NOTE_REQUESTS: 4
+```
+
+#### `TRACE_NOTE_URL_CHARS`
+
+How long a URL the note prints, before the middle is cut.
+
+```typescript
+const TRACE_NOTE_URL_CHARS: 96
+```
+
+#### `DIAGNOSIS_TRACE_FLAG`
+
+The `--trace` flag this platform adds, and the only value it adds it with.
+
+```typescript
+const DIAGNOSIS_TRACE_FLAG: '--trace=retain-on-failure'
+```
+
+#### `PLAYWRIGHT_FAILURES_INLINE_ENV`
+
+Playwright's switch for printing each failure's own error as that test fails, instead of only in
+the summary at the end: `list` reads it in its constructor (`ListReporterOptions.printFailuresInline`,
+`playwright/lib/reporters/list.js` — 1.63, the version the toolchain pins), and when it prints
+inline the end-of-run repeat is suppressed with it (`epilogue(!printFailuresInline)`), so one
+reporter still prints each failure exactly once.
+
+A background suite is put on `list` (see {@link streamingBackgroundCommand}) and this with it, so
+the log names its causes WHILE it walks. Without it the log's only failure lines are `✘` rows:
+X1 xr-molecule-flash-m99 (+19:27 → +21:00, 2026-10-16) was told to `grep -n -A 20 '<test name>'`
+the log, got nothing back through four greps, inferred causes from the spec prose instead, and
+edited `app/src` while the run was still walking — which voids the run.
+
+```typescript
+const PLAYWRIGHT_FAILURES_INLINE_ENV: 'PLAYWRIGHT_LIST_PRINT_FAILURES_INLINE'
+```
+
 #### `MAX_READ_SIZE`
 
 Max file size for read_file (5MB).
@@ -2217,12 +2751,39 @@ How many of a repeating cause's failures the note lists before it says "and N mo
 const REPEATING_FAILURE_LISTED: 5
 ```
 
+#### `TOOL_RESULT_CHARS`
+
+The platform's cap on one tool result's text: `MAX_TOOL_OUTPUT_CHARS` in molecule-dev's
+`api/src/ai/chat-handler.ts`, which cuts a longer string field's MIDDLE. A finished run's
+stdout is cut to it, so the cause list must not depend on reading the log back — and must
+itself fit inside it, or the cut lands in the list.
+
+```typescript
+const TOOL_RESULT_CHARS: 8000
+```
+
+#### `FAILURE_CAUSES_CHARS`
+
+The characters a finished run's cause list may use of {@link TOOL_RESULT_CHARS}. The recap
+measured by xr-molecule-flash-m102 (+12:43) was `12 failures, 8 causes`: one cause line is
+~200 chars and ~80 more with its two body lines, so 8 causes is ~2.3 k against the 8 k cap —
+the old 5-cause cap withheld 3 causes that the same result had room for.
+
+The rest of the cap is left to the header, the narrowed re-run command and the exclusion
+line, which ride the same note.
+
+```typescript
+const FAILURE_CAUSES_CHARS: number
+```
+
 #### `FAILURE_CAUSES_LISTED`
 
-How many causes a finished run's summary lists before it says "and N more".
+How many causes a finished run's summary lists at most. The character budget above is the
+bound that must hold (it is what keeps the note on the surviving side of the tool-result
+cut); this is the bound past which a list stops being read at all.
 
 ```typescript
-const FAILURE_CAUSES_LISTED: 5
+const FAILURE_CAUSES_LISTED: 12
 ```
 
 #### `FAILURE_CAUSE_TESTS_LISTED`