@molecule/api-ai-tools 1.6.5 → 1.7.0

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-16T19:48:43.608Z
+Generated: 2026-10-17T00:30:38.264Z
 -->
 
 # @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
@@ -73,6 +73,37 @@ interface CommandSegment {
   args: readonly string[]
   /** The program and its arguments as one line — what a runner pattern is matched against. */
   text: string
+  /**
+   * The seconds the segment's own `timeout` wrapper allows the command it runs
+   * (`timeout 280 hurl --test …` → 280), or null when it carries none.
+   */
+  timeoutSeconds: number | null
+}
+```
+
+#### `CutRun`
+
+A run a budget stopped, as its result reports it.
+
+```typescript
+interface CutRun {
+  /** The bound the run was allowed, in seconds. */
+  seconds: number
+  /** Whether this tool's budget stopped it or the `timeout` the command carried. */
+  stoppedBy: CutBy
+  /**
+   * The exit code the run's own process reported, or null when the code in the result belongs to
+   * 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. */
+  ran: number | null
+  /** How many the run was walking, when the runner printed it (Playwright's `[n/K]`), or null. */
+  total: number | null
+  /** The noun the runner counts in. */
+  noun: 'files' | 'tests'
+  /** The last thing the run printed — the line a reader looks at first. */
+  doing: string | null
 }
 ```
 
@@ -155,6 +186,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.
@@ -443,6 +519,22 @@ interface FailureCause {
 
 ### Types
 
+#### `CommandRunState`
+
+What a command's result records: a run that ended, or one a budget stopped.
+
+```typescript
+type CommandRunState = 'ran' | typeof CUT_AT_BUDGET
+```
+
+#### `CutBy`
+
+What stopped a run.
+
+```typescript
+type CutBy = 'tool-budget' | 'command-timeout'
+```
+
 #### `DiscoveredSkill` _(deprecated)_
 
 Re-export SkillEntry as DiscoveredSkill for backwards compatibility.
@@ -491,6 +583,18 @@ function createSandboxBackend(sandbox: SandboxLike, projectRoot?: string): Execu
 
 **Returns:** A backend that proxies all filesystem calls into the sandbox.
 
+#### `durationSeconds(word)`
+
+The seconds a duration word stands for.
+
+```typescript
+function durationSeconds(word: string): number | null
+```
+
+- `word` — A duration (`280`, `20s`, `1m`).
+
+**Returns:** The seconds, or null when the word is not a duration.
+
 #### `commandSegments(command)`
 
 The segments of a command, each with its program and arguments — the answer every classifier
@@ -504,6 +608,25 @@ function commandSegments(command: string): CommandSegment[]
 
 **Returns:** One entry per statement or pipeline stage that runs something, in order.
 
+#### `commandTimeoutSeconds(command)`
+
+The bound a command puts on its own run: the largest `timeout <N>` any of its segments runs
+under (`timeout 280 hurl --test …` → 280), or null when it carries none.
+
+This is the bound `man timeout` enforces by KILLING the command — so a run that used it did not
+finish, whatever the pipeline's own exit status says. It is read here, from the same parse every
+other command reader uses, rather than matched as text: `timeout` in an argument
+(`grep -n 'timeout 280' notes.md`) bounds nothing, and `-k 5` is the grace before the kill, not
+the bound ({@link WRAPPER_VALUE_FLAGS}).
+
+```typescript
+function commandTimeoutSeconds(command: string): number | null
+```
+
+- `command` — The shell command.
+
+**Returns:** The seconds the command allows itself, or null.
+
 #### `runsInCommandPosition(command, pattern)`
 
 Whether any segment of the command runs a program whose command-position text matches
@@ -522,6 +645,102 @@ function runsInCommandPosition(command: string, pattern: RegExp): boolean
 
 **Returns:** True when a segment in command position matches.
 
+#### `commandRunState(result)`
+
+The state a command's result records — THE reader every verdict about a run goes through.
+
+A result that carries no state is a run that ended: the state is written where the run is
+stopped ({@link commandCutRun}), so a result without it was never stopped by a budget this
+platform set or can see. Results produced before this state existed read the same way, which is
+what keeps a past turn's tally readable.
+
+```typescript
+function commandRunState(result: unknown): CommandRunState
+```
+
+- `result` — The exec_command / wait_for_task result.
+
+**Returns:** The state the result records.
+
+#### `suiteTally(text)`
+
+Whether text carries a runner's closing summary ({@link SUITE_TALLY}).
+
+```typescript
+function suiteTally(text: string): boolean
+```
+
+- `text` — The run's stdout and stderr.
+
+**Returns:** True when the runner's own end-of-run summary is there.
+
+#### `commandCutRun(command, result, elapsedMs, budgetSeconds)`
+
+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:
+
+- `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.
+- the command carried its own `timeout <N>`, N is inside this tool's budget (a larger one never
+  fires — the tool's does), the run used N, and no runner printed a closing summary: the run was
+  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.
+
+```typescript
+function commandCutRun(
+  command: string,
+  result: unknown,
+  elapsedMs: number,
+  budgetSeconds?: number,
+): CutRun | null
+```
+
+- `command` — The command the executor sent.
+- `result` — Its result.
+- `elapsedMs` — How long the command ran, in ms.
+- `budgetSeconds` — This tool's foreground budget, in seconds (0 when it has none).
+
+**Returns:** The stopped run, or null.
+
+#### `cutRunFacts(result)`
+
+The facts a result records about the run a budget stopped it in — what a reader needs to say
+how far the run got WITHOUT re-reading its log or re-deriving the counts.
+
+The numbers are read from the runner's own output where it printed them (Hurl's per-file lines,
+Playwright's `[n/K]`), so a caller that can also see the suite itself — the file count of the
+`*.hurl` directory the run walked — fills in the `total` this could not know, and both then say
+the same sentence ({@link cutRunSentence}).
+
+```typescript
+function cutRunFacts(result: unknown): CutRun | null
+```
+
+- `result` — The exec_command / wait_for_task result.
+
+**Returns:** The facts the result carries, or null when it records no stopped run.
+
+#### `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.
+
+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.
+
+```typescript
+function cutRunSentence(run: CutRun): string
+```
+
+- `run` — The stopped run.
+
+**Returns:** The sentence.
+
 #### `normalizeToolInput(schema, raw)`
 
 Move known aliases onto the declared parameter names and report what is still
@@ -851,6 +1070,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),
@@ -1199,6 +1519,105 @@ function findPatternArgs(pattern: string): string
 
 **Returns:** A `find` predicate: `-name '…'` for a bare name, else one or more `-path '…'` alternatives, ORed inside parens when there is more than one.
 
+#### `findPathArgs(pattern)`
+
+The `-path` alternatives of {@link findPatternArgs}, for a pattern whose
+directory the caller has already rooted the search at.
+
+`find_files` narrows the search root itself when the pattern spells its own
+directory out (see {@link literalDirPrefix}) — `node_modules` plus
+`@molecule/api-resource-user/dist/*.d.ts` searched that one directory. The
+remainder (`*.d.ts`) must then keep the `-path` form rather than collapsing to
+`-name`: `*` crosses `/` in an fnmatch glob, so the `-path` form still finds a
+declaration file in a `dist/utilities/` subdirectory, which `-name '*.d.ts'`
+would drop (a silent partial answer, which is worse than the timeout it
+replaced).
+
+```typescript
+function findPathArgs(pattern: string): string
+```
+
+- `pattern` — The pattern's remainder, with a `/` in it or not.
+
+**Returns:** One or more `-path '…'` alternatives, ORed inside parens when there is more than one.
+
+#### `literalDirPrefix(pattern)`
+
+The directory a GLOB pattern spells out, when it spells one out: everything
+before the pattern's first glob character, trimmed back to the last `/`.
+
+A pattern is matched against the whole path with a leading "any parent"
+anchor ({@link findPatternArgs}), so `find` visits every entry below the
+search root. Handed `/workspace/node_modules` and
+`@molecule/api-resource-user/dist/*.d.ts` — a directory named outright —
+`find` walked the sandbox's entire dependency tree and hit the tool's 10 s
+deadline without printing a result (xr-molecule-flash-m94: the one directory
+the model meant answered a `list_files` in 0 s). The literal prefix is that
+directory, and rooting the search at it is what keeps the call instant.
+
+A BARE first segment (`helpers/*`, `bonds/*`, `e2e/*.spec.ts`) is NOT one:
+`helpers/*` means "a `helpers/` directory anywhere below the root", which the
+tool documents and a live run relied on (xr-molecule-flash-m77 — a path
+pattern is not anchored to one depth). Rooting those at
+`<root>/helpers` would answer with a SUBSET, silently: the nested
+`api/src/helpers/` matches would disappear, and a missing file reads as
+"no such file". So a prefix is returned only when it names a path of two or
+more segments (`@molecule/api-resource-user/dist`), which is the shape that
+is a directory rather than a directory name.
+
+```typescript
+function literalDirPrefix(pattern: string): string | null
+```
+
+- `pattern` — A pattern already accepted by {@link isValidGlob}.
+
+**Returns:** The literal directory prefix, without a trailing slash, or null when the pattern has no glob character, no `/`, or only a bare name before one.
+
+#### `isCommandTimeout(error)`
+
+Whether a backend error is the sandbox's own command deadline.
+
+The E2B SDK answers a timed-out `exec` with its generic text —
+`[deadline_exceeded] the operation timed out: … It can be modified by passing
+'timeoutMs' when making the request. Use '0' to disable the timeout.` — which
+names an option the executor cannot set and says nothing about the search
+that died. Handing that sentence to the model is what xr-molecule-flash-m94
+read after `find_files` spent 10 s walking `node_modules`; the tool answers
+the deadline in its own words instead (see {@link searchTimeoutError}).
+
+```typescript
+function isCommandTimeout(error: unknown): boolean
+```
+
+- `error` — The error the backend threw.
+
+**Returns:** True when the error reads as a timeout or a deadline.
+
+#### `searchTimeoutError(tool, searched, pattern, seconds, hint)`
+
+The answer a search tool gives when the backend's deadline fires: what was
+searched, for what, how long the tool allowed, and the two ways to get an
+answer — a narrower `path`, or a listing. Never the vendor's `timeoutMs`
+sentence (see {@link isCommandTimeout}).
+
+```typescript
+function searchTimeoutError(
+  tool: string,
+  searched: string,
+  pattern: string,
+  seconds: number,
+  hint: string,
+): string
+```
+
+- `tool` — The tool that timed out (`find_files`, `search_files`).
+- `searched` — The directory the search actually covered.
+- `pattern` — The pattern it was searching for.
+- `seconds` — The tool's own limit, in seconds.
+- `hint` — What to do differently — the narrower target or the listing tool.
+
+**Returns:** The message's text.
+
 #### `pathArgError(path, tool)`
 
 Validate a file tool's `path` argument is a non-empty string. A weak model
@@ -1388,10 +1807,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
@@ -1427,9 +1848,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
@@ -1442,8 +1865,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
@@ -1478,6 +1901,43 @@ function universalCause(log: string, found: RepeatingFailure): UniversalCause |
 
 **Returns:** The cause's count and files, or null when the run is not failing whole.
 
+#### `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.
+
 #### `failuresByCause(log)`
 
 Every failure a run names, grouped by the cause behind it — one group per cause, with the
@@ -1488,11 +1948,11 @@ 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.
 
 ```typescript
 function failuresByCause(log: string): FailureCause[]
@@ -1553,18 +2013,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`.)_
 
@@ -1582,7 +2043,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.
 
@@ -1664,6 +2125,15 @@ function fusedLine(content: string, newString: string): { line: number; text: st
 
 ### Constants
 
+#### `CUT_AT_BUDGET`
+
+The state a result carries when a budget stopped its command: a run that did not finish is not a
+run that passed, and no reader may treat it as one.
+
+```typescript
+const CUT_AT_BUDGET: 'cut_at_budget'
+```
+
 #### `TOOL_SCHEMAS`
 
 Canonical tool schemas shared by the agent runtime and documentation.
@@ -1672,6 +2142,108 @@ Canonical tool schemas shared by the agent runtime and documentation.
 const TOOL_SCHEMAS: Record<string, ToolSchema>
 ```
 
+#### `SPLIT_WORK_ADVICE`
+
+The closing advice on an over-budget message for a command that is not a test
+suite: the work it was chaining is what to split.
+
+```typescript
+const SPLIT_WORK_ADVICE: string
+```
+
+#### `SUITE_OVER_BUDGET_ADVICE`
+
+The closing advice on an over-budget message for a command that IS a suite run
+(Playwright, Vitest, a `hurl` run — {@link isSuiteRunCommand}): its files are not
+a bigger unit to break up.
+
+X1 flash-m36 asked for this half and the message kept saying "run a smaller unit"
+for two months. It is the wrong direction for a suite, and measurably: a run
+stopped here reports NO tally, so nothing in the result says which test or request
+hung — the run has to be sent again in the background (off this budget, its output
+written to a log that can be read mid-run) or, when a consumer knows the runner's
+per-request limit, with each request bounded. xr-molecule-flash-m93 (+06:22,
+2026-10-16) lost 4.8 minutes to a Hurl run whose ONE unanswered request had hurl's
+300 s default per request holding the file, ten seconds past this tool's budget.
+
+```typescript
+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).