@molecule/api-ai-tools 1.8.2 → 1.9.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-17T02:50:55.123Z
+Generated: 2026-10-17T07:58:25.504Z
 -->
 
 # @molecule/api-ai-tools
@@ -115,6 +115,24 @@ interface LocatedCommandSegment {
    * inside a nested `sh -c` string, for the same reason as {@link start}.
    */
   assignmentOffset: number | null
+  /**
+   * The offset in the command one past the statement's last word — where an option of this
+   * statement's program belongs, before whatever closes it. Null inside a nested `sh -c` string.
+   */
+  end: number | null
+  /**
+   * The offset in the command of the word in command position — the program, once every wrapper
+   * in front of it is taken away (`npx --prefix /app <here>playwright test`). Null inside a
+   * nested `sh -c` string, and for a statement that only sets variables.
+   */
+  programOffset: number | null
+  /**
+   * The separator the shell split at immediately before this statement — `|`, `||`, `&&`, `;`,
+   * a newline or `&` — or '' when it is the first statement of the command. It is the parse's own
+   * answer, so it is known even where the offsets are not, and a caller deciding whether two
+   * statements are one pipeline (`|`, never `;`) asks it instead of reading the text between them.
+   */
+  separator: string
 }
 ```
 
@@ -179,6 +197,23 @@ interface CutRun {
 }
 ```
 
+#### `RunFailureClass`
+
+One failure a runner printed, classified by the layer that failed.
+
+```typescript
+interface RunFailureClass {
+  /** The layer that failed. */
+  kind: RunFailureKind
+  /** For a `connection` failure, what the transport did. */
+  connection?: ConnectionFailureKind
+  /** How long the request waited before the transport gave up, in seconds, when printed. */
+  seconds?: number
+  /** The `file:line` the runner printed for the failure, when it printed one. */
+  at?: string
+}
+```
+
 #### `NormalizableSchema`
 
 The JSON-Schema-ish shape every tool in this package declares.
@@ -235,6 +270,19 @@ interface ToolSchema {
 }
 ```
 
+#### `LeadingSleep`
+
+The leading `sleep` a command opens with, and the command that follows it.
+
+```typescript
+interface LeadingSleep {
+  /** How many seconds the statement would have slept (GNU sleep sums its operands). */
+  seconds: number
+  /** What follows the leading statement, trimmed — '' when the sleep was the whole command. */
+  rest: string
+}
+```
+
 #### `SuiteRunInFlight`
 
 One suite run, as the rule that decides whether a second may start beside it reads it.
@@ -258,6 +306,20 @@ interface SuiteRunInFlight {
 }
 ```
 
+#### `InstalledPackageFacts`
+
+What the filesystem says about a write target under `node_modules` — the half
+of the decision a path's spelling cannot make.
+
+```typescript
+interface InstalledPackageFacts {
+  /** Whether the `node_modules` entry the path goes through is a symbolic link. */
+  readonly symlink: boolean
+  /** Whether a package is really installed there: a `package.json` resolves under the entry. */
+  readonly installed: boolean
+}
+```
+
 #### `TraceRequest`
 
 One request a traced page made, as `*.network` records it.
@@ -268,8 +330,43 @@ interface TraceRequest {
   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. */
+  /**
+   * The response status as the trace recorded it. Playwright writes `-1` when a request was never
+   * answered (its HAR entry starts at `-1` and only a response event overwrites it); `0` is the
+   * same absence when the snapshot carried no response at all. Neither is a server failure.
+   */
   status: number
+  /**
+   * Playwright's own error text for a request that failed WITHOUT a response
+   * (`net::ERR_CONNECTION_REFUSED`) — a real failure. A request that got no response and recorded
+   * no text was aborted or still in flight when the test ended (the page closed under it), so it
+   * says nothing about the server (xr-molecule-flash-m112 +30:45).
+   */
+  failure?: string
+  /**
+   * What the page SENT, for a 4xx answered by the app's own API — bounded (see
+   * {@link MAX_TRACED_BODY_CHARS}). A body wrapped as `{"data":{…}}` is visible here in one line:
+   * app-http's verbs take the body as their second argument, so a helper that passes
+   * `{ data: body }` there ships the wrapper (xr-molecule-flash-m111 +11:36).
+   */
+  sent?: string
+  /** What came back for that 4xx, bounded the same way — the API's own error body. */
+  got?: string
+}
+```
+
+#### `TraceAction`
+
+One action the traced page performed, with the trace's own timing for it.
+
+```typescript
+interface TraceAction {
+  /** The Playwright API the entry names: `Frame.goto`, `Locator.fill`, `Locator.click`. */
+  api: string
+  /** When the action started, on the trace's own monotonic clock (ms). */
+  start: number
+  /** When it finished, or null when the run ended before it did. */
+  end: number | null
 }
 ```
 
@@ -287,6 +384,12 @@ interface TraceArtifact {
   requests: TraceRequest[]
   /** The console errors and page errors the page raised. */
   console: string[]
+  /**
+   * The page's own actions in the order the trace recorded them, bounded — what a test that ran
+   * out of a per-test budget spends its time on. A test that repeats one action prints it once per
+   * repeat, so the gap between two starts is one repeat's measured cost.
+   */
+  actions: TraceAction[]
 }
 ```
 
@@ -553,6 +656,27 @@ interface SuiteFilterStrip {
 }
 ```
 
+#### `SuiteRunPipelinePlacement`
+
+Whether a finished run's exit code belongs to a stage after the suite runner.
+
+```typescript
+interface SuiteRunPipelinePlacement {
+  /**
+   * True when a pipe this tool must not drop still follows the suite runner: the code in the
+   * result is that stage's, not the run's.
+   */
+  piped: boolean
+  /**
+   * True when the suite (or a stage of its pipeline) sits inside a nested `sh -c '<command>'`
+   * string, so the parse cannot place it in the command's own text. The caller then says so
+   * plainly instead of implying a stage it can point at — and keeps the command's own code when
+   * no pipe follows the runner, because on that command the pipeline's last stage IS the run.
+   */
+  unplaced: boolean
+}
+```
+
 #### `FailedTest`
 
 One failed test, as a running suite's log names it.
@@ -619,6 +743,20 @@ interface FailureCause {
    * for a duration group, whose blocks carried no bodies.
    */
   evidence: string[]
+  /**
+   * The suite's own per-test budget in ms, when the cause is the test-budget kill
+   * (`Test timeout of 15000ms exceeded`). The signature normalizes the number away
+   * ({@link normalizedSignature}) so equal causes group, and that number is the one fact that
+   * predicts a test spending its budget on a repeated action (xr-molecule-flash-m110 +20:44).
+   */
+  budgetMs?: number
+  /**
+   * The layer the failure came from ({@link classifyRunFailure}). A `connection` cause never
+   * reached the app, so it is NOT a cause the app's code can fix: the note says to re-run it
+   * once and read the app's log on a repeat, instead of sending a fix at a handler
+   * (xr-molecule-flash-m110 +18:42 rewrote a CORS middleware for a 20 s connection timeout).
+   */
+  kind: RunFailureKind
 }
 ```
 
@@ -650,6 +788,23 @@ type CutBy =
   | 'process-stop'
 ```
 
+#### `RunFailureKind`
+
+The layer a failure came from: the transport (no answer at all), the response's status, or an
+assertion over a response that arrived.
+
+```typescript
+type RunFailureKind = 'connection' | 'status' | 'assertion'
+```
+
+#### `ConnectionFailureKind`
+
+What the transport did when a request never got an answer.
+
+```typescript
+type ConnectionFailureKind = 'timeout' | 'refused' | 'reset' | 'dns' | 'tls' | 'empty'
+```
+
 #### `DiscoveredSkill` _(deprecated)_
 
 Re-export SkillEntry as DiscoveredSkill for backwards compatibility.
@@ -658,6 +813,19 @@ Re-export SkillEntry as DiscoveredSkill for backwards compatibility.
 type DiscoveredSkill = SkillEntry
 ```
 
+#### `InstalledPackageProbe`
+
+Looks at the filesystem for {@link InstalledPackageFacts}.
+
+The guard cannot `stat` the path itself: the tools act through a backend (a
+sandbox over the network for the fleet), so the caller — which holds that
+backend — supplies the look. {@link shellInstalledPackageProbe} builds one
+from any shell runner.
+
+```typescript
+type InstalledPackageProbe = (path: string) => Promise<InstalledPackageFacts>
+```
+
 ### Classes
 
 #### `ToolInputError`
@@ -922,6 +1090,36 @@ function cutRunSentence(run: CutRun): string
 
 **Returns:** The sentence.
 
+#### `classifyRunFailure(text)`
+
+Classify ONE failure's text — a Hurl `error:` block, or a Playwright failure message/body.
+
+The transport is read first: a block that carries a connection error AND an assertion is a
+request whose assertion never ran, so it is a connection failure. Only a block that carries no
+failure signature at all answers null — unknown is never a connection failure, because a
+misread transport hides a real app failure behind "just re-run it".
+
+```typescript
+function classifyRunFailure(text: string): RunFailureClass | null
+```
+
+- `text` — One failure's text, as the runner printed it.
+
+**Returns:** The classification, or null when the text carries no failure this reads.
+
+#### `allConnectionFailures(failures)`
+
+Whether every one of the classified failures is a connection failure — the only shape in which
+no response the app produced was measured.
+
+```typescript
+function allConnectionFailures(failures: readonly (RunFailureClass | null)[]): boolean
+```
+
+- `failures` — The run's classifications, in printed order.
+
+**Returns:** True when there is at least one and none of them is the app's.
+
 #### `normalizeToolInput(schema, raw)`
 
 Move known aliases onto the declared parameter names and report what is still
@@ -1029,6 +1227,26 @@ function commandRunsNoTests(command: string): boolean
 
 **Returns:** True when the command invokes a runner only to print.
 
+#### `leadingSleepPeek(command)`
+
+The leading `sleep` of a command, when the first statement is one and it asks for at least
+{@link MIN_PEEK_SLEEP_SECONDS}.
+
+The statement is read by {@link locatedCommandSegments} — the same parse every other command
+classifier uses — so only a `sleep` in command position of the FIRST statement counts. The end
+of that statement is then found by walking forward from its own start: the statement is
+`sleep <duration>`, whose words carry no quotes and open no substitution, so the first unquoted
+`;`, newline or `&` ends it. A `|` is refused: dropping the left side of a pipeline would hand
+the right side its stdin instead, and a `||` fallback would run on a success that never did.
+
+```typescript
+function leadingSleepPeek(command: string): LeadingSleep | null
+```
+
+- `command` — The shell command the executor sent.
+
+**Returns:** The seconds and the remaining command, or null when the command does not open with a long `sleep`.
+
 #### `withoutHeredocs(command)`
 
 A command with its heredoc bodies removed: the runs, kills and hosts it names in a file it
@@ -1061,24 +1279,68 @@ function suiteCommandTarget(command: string): string
 
 **Returns:** The target key.
 
-#### `scopedRerunCommand(command, locations, excluded)`
+#### `namesSuiteConfig(command)`
+
+Whether a Playwright statement names its own config — the reading {@link withSuiteConfig} and
+{@link scopedRerunCommand} share, so neither adds a second `--config` to a command that has one.
+
+```typescript
+function namesSuiteConfig(command: string): boolean
+```
+
+- `command` — A command, or the Playwright statement inside it.
+
+**Returns:** True when the statement loads a config of its own.
+
+#### `withSuiteConfig(command, config)`
+
+The command with a `--config` added to the Playwright invocation it starts — or unchanged when
+it already names one, or starts no Playwright run.
+
+The flag rides the same statement the runner does: a `cd`, an env prefix and a `timeout` before
+it are left exactly as they were, and so is everything chained after the run (`| tail -50`).
+
+xr-molecule-flash-m113 (+19:09): the model's fix-round re-run dropped the
+`--config playwright.conduit.config.ts` both earlier runs had carried, so Playwright started with
+NO base URL and all 10 failures were `page.goto: Cannot navigate to invalid URL` — a failure list
+that says nothing about the app. The platform composes commands back to the executor too (the
+narrowed re-run of a finished run's failures), and a command it hands back has to carry the
+config the run was measured under, never the shape that caused that finding.
+
+```typescript
+function withSuiteConfig(command: string, config: string | null | undefined): string
+```
+
+- `command` — The command as the executor sent it.
+- `config` — The config the run loads, when the caller knows it.
+
+**Returns:** The command with the flag, or the command unchanged.
+
+#### `scopedRerunCommand(command, locations, excluded, config)`
 
 The whole-suite command made scoped to the tests it should re-run instead: the same
 invocation — same directory, same settings — with the named `file:line`s in place of the whole
 suite, `--last-failed` dropped (it re-runs the tests that never ran too, X1 flash-m60) and
 `--retries=0` set (a re-run of a known failure does not need to pay for retries).
 
+`config` is the config the run was measured under ({@link withSuiteConfig}): the narrowed re-run
+carries it whenever the command itself does not, so a run that dropped `--config` cannot be
+handed back a command with the same defect (xr-molecule-flash-m113: every failing test was
+`Cannot navigate to invalid URL` because the re-run loaded no base URL).
+
 ```typescript
 function scopedRerunCommand(
   command: string,
   locations: readonly string[],
   excluded?: readonly string[],
+  config?: string | null,
 ): string
 ```
 
 - `command` — The whole-suite run's command.
 - `locations` — The failing `file:line`s to re-run, as the run's own log printed them — or, for a run that started outside the suite, the absolute form Playwright matches each file argument against.
 - `excluded` — The test titles the request carves out. They are inverted out (`--grep-invert`) so a re-run of the failing locations cannot report one of them again — xr-molecule-flash-m101 re-ran the whole 139-test suite and spent ~4 minutes to be told about a test the request had already said does not count.
+- `config` — The config the run loaded, when the caller knows it; added when the command does not name one.
 
 **Returns:** The scoped command, or the command unchanged when it runs no Playwright suite.
 
@@ -1213,10 +1475,26 @@ function moleculeDistReadNote(path: string): string | null
 
 **Returns:** The note, or null when the path is not inside a package's `dist`.
 
-#### `installedPackageWriteRefusal(path)`
+#### `shellInstalledPackageProbe(run)`
+
+Build an {@link InstalledPackageProbe} from a shell runner (a backend's
+`run`, or a sandbox's `exec`): one command reports whether the entry is a
+link and whether a `package.json` resolves under it.
+
+```typescript
+function shellInstalledPackageProbe(
+  run: (command: string) => Promise<{ stdout?: string } | null | undefined>,
+): InstalledPackageProbe
+```
+
+- `run` — Runs a command where the path lives.
+
+**Returns:** The probe.
 
-The refusal for a write whose target is inside an installed package, or null
-when the path is not under a `node_modules` directory.
+#### `installedPackageWriteRefusal(path, probe)`
+
+The refusal for a write whose target is inside an INSTALLED package, or null
+when the path is not under `node_modules` or nothing is installed there.
 
 `node_modules` is not the project's code: nothing written there survives the
 next install, no deploy carries it, and a sandbox whose dependency tree is
@@ -1229,17 +1507,29 @@ answered `ok: true`, and 18 s went to noticing, `npm pack`-ing the package and
 putting the file back. Reading these files stays allowed (that is how the
 declarations above are read at all).
 
-The restore route is named because the model that has ALREADY clobbered a file
-(this refusal is too late for it) is the one who needs it, and because the
-obvious repair — `npm install <pkg>` — is itself refused in the pre-installed
-sandbox. `npm pack` + a `tar` extraction over the package directory is what
-m91 used, and what both guards leave alone.
+What is protected is the INSTALL, not the spelling: the decision comes from
+{@link InstalledPackageFacts}, never from the path alone (m106 above). Three
+things are the run's own to remove or replace —
+
+- a `node_modules` that is a SYMLINK: `rm`/`unlink` removes the link, never the
+  tree it points at, so a link the run made cannot clobber anything;
+- anything under the run's own `.mol-scratch/` directory;
+- a `node_modules` with no `package.json` under it (nothing was ever installed).
+
+A path INSIDE the link is still decided by what resolves there: a link into a
+real tree is refused, because removing or writing through it reaches the
+
+_(description truncated — read the full text in `node_modules/@molecule/api-ai-tools/dist/tools.d.ts`.)_
 
 ```typescript
-function installedPackageWriteRefusal(path: string): string | null
+function installedPackageWriteRefusal(
+  path: string,
+  probe?: InstalledPackageProbe,
+): Promise<string | null>
 ```
 
 - `path` — An absolute path a tool is about to write.
+- `probe` — Looks at the filesystem where the path lives.
 
 **Returns:** The one-line refusal naming the package, or null when nothing is installed there.
 
@@ -1268,10 +1558,17 @@ on `unzip` would make the read fail on every sandbox that has none. The zip is r
 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.
+A request is kept over a static asset when it failed — a `status >= 400`, or no response at all
+together with Playwright's own error text (`-1` plus `_failureText`, a refused connection) — 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. A request with no response and NO error text was aborted
+or still in flight when the test ended; it is kept too, but as what it is, not as a failure.
+
+A request answered 4xx by the app's OWN API also keeps what the page SENT and the first of what
+came back: Playwright stores either inline (`text`) or in a resource entry (`_file`), and both
+are read. That is where a wrapped body shows: xr-molecule-flash-m111's helper passed
+
+_(description truncated — read the full text in `node_modules/@molecule/api-ai-tools/dist/trace-artifacts.d.ts`.)_
 
 ```typescript
 function traceArtifactsScript(): string
@@ -1294,7 +1591,7 @@ function parseTraceArtifacts(stdout: string): TraceArtifact[]
 
 **Returns:** One entry per trace it printed.
 
-#### `failureTraceNote(items, target)`
+#### `failureTraceNote(items, target, earlierFailures)`
 
 The note a failed suite run's result carries: what each failing test's page actually sent, and
 what came back.
@@ -1305,14 +1602,34 @@ with them: read the handler the route reaches, not the selector. It is BOUNDED t
 {@link MAX_TRACE_NOTE_TESTS} tests with {@link MAX_TRACE_NOTE_REQUESTS} requests each, because it
 rides in a result the model pays for.
 
+The three kinds are kept apart, because they mean different things. A FAILED request (4xx/5xx, or
+a network error with Playwright's own text) is a cause. A request with NO RESPONSE RECORDED —
+Playwright's `-1`, no error text — was still in flight when the test ended (the page closed under
+it); listing it as a failure sent a run hunting an API that never answered anything wrong
+(xr-molecule-flash-m112 +30:45). The rest are the page's last answered requests.
+
+A 4xx request carries what the page SENT beside its status, so a wrapped body is visible in one
+line rather than inferred from the status; when one of those bodies is an object whose only key
+is `data`, the note names the call shape that produces it (xr-molecule-flash-m111 +11:36).
+
+WHICH rows it spends is evidence, not artifact order (xr-molecule-flash-m112 +53:46): a row
+needs a recorded response, a real failure or a console error ({@link traceRowEvidence}), rows are
+
+_(description truncated — read the full text in `node_modules/@molecule/api-ai-tools/dist/trace-artifacts.d.ts`.)_
+
 ```typescript
-function failureTraceNote(items: readonly TraceArtifact[], target: string): string | null
+function failureTraceNote(
+  items: readonly TraceArtifact[],
+  target: string,
+  earlierFailures?: readonly string[],
+): string | null
 ```
 
 - `items` — The traces {@link parseTraceArtifacts} read.
 - `target` — Where the run went — the deployed host, as the note names it.
+- `earlierFailures` — The failing `file:line`s earlier walks of this suite left, so a repeat is ranked above a one-off. Empty when the caller knows of no earlier walk.
 
-**Returns:** The note, or null when no trace held a request or a console error.
+**Returns:** The note, or null when no trace held a recorded response, a real failure or a console error.
 
 #### `suiteRecordsTraces(configText)`
 
@@ -1602,23 +1919,40 @@ function stripTrailingSuiteFilters(command: string): SuiteFilterStrip
 
 **Returns:** The rewritten command and the stages dropped.
 
+#### `suiteRunPipelinePlacement(command)`
+
+Where the suite runner's exit code comes from: the runner itself, or a stage piped after it.
+
+{@link suiteRunPipedAfterRunner}'s one question, with the honest third answer kept apart. The
+code a finished run reports is its LAST pipeline stage's, so a stage after the runner makes the
+code the stage's — but only when such a stage EXISTS. The platform used to report "piped" for
+any run whose statements it could not place in the text, which one heredoc body was enough to
+cause: on X1 xr-molecule-flash-m105 (+08:12) a config written in the same `exec_command` made
+the run come back with no exit code at all, and the note under it claimed a stage after the
+runner that was not there. The parse now places every statement (`locatedCommandSegments`), so
+"unplaced" is the rare, named case rather than a guess dressed as an answer.
+
+```typescript
+function suiteRunPipelinePlacement(command: string): SuiteRunPipelinePlacement
+```
+
+- `command` — The shell command, after the streaming rewrite when one was applied.
+
+**Returns:** Whether a stage follows the runner, and whether the run could be placed at all.
+
 #### `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.
+**Returns:** True when a pipe this tool must not drop still follows the suite runner.
 
 #### `suiteRunPriorityLaunch(command, launch)`
 
@@ -2231,21 +2565,28 @@ executor reads, so one round of fixes covers all of them rather than the one cau
 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.
+end, so a result never asks to fix a test it also says to ignore. A test the runner itself
+declared `flaky` (it failed once and passed on its config retry) is not a cause either: it is
+named apart from them, once, as what the tally called it ({@link flakyTestsDeclared}). 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.
+
+A run whose failures are ALL {@link NO_BASE_URL_ERROR} is not a set of causes at all: it is one
+configuration failure, said in one line ({@link noBaseUrlConfigNote}) rather than a list that
+reads as ten defects in the app.
 
 ```typescript
 function failureCausesNote(
   log: string,
   excluded?: readonly string[],
-  run?: { command: string; cwd?: string; log?: string },
+  run?: { command: string; cwd?: string; log?: string; config?: string | null },
 ): 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.
+- `run` — How the run was started, when the caller knows it: the narrowed re-run is built from `command`/`cwd`/`config`, and `log` (the path the output was written to) is what the "left out" sentence greps when more causes exist than the result has room for.
 
 **Returns:** The note, or null.
 
@@ -2264,13 +2605,13 @@ the same app and database, and that is exactly what is refused while the run wal
 
 ```typescript
 function rerunOfRunningSuite(
-  run: { command: string; cwd?: string },
+  run: { command: string; cwd?: string; config?: string | null },
   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.
+- `run` — The run in flight: the command it was started with, as it was run, the directory that command ran in, and the config it loaded when the caller knows it.
 - `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.
 
@@ -2414,6 +2755,15 @@ Canonical tool schemas shared by the agent runtime and documentation.
 const TOOL_SCHEMAS: Record<string, ToolSchema>
 ```
 
+#### `MIN_PEEK_SLEEP_SECONDS`
+
+The shortest leading sleep the platform drops: below it the wall clock it costs is noise, and a
+short settle (`sleep 2; curl …`) is a legitimate thing to run.
+
+```typescript
+const MIN_PEEK_SLEEP_SECONDS: 5
+```
+
 #### `SPLIT_WORK_ADVICE`
 
 The closing advice on an over-budget message for a command that is not a test
@@ -2466,6 +2816,22 @@ How many console errors one test's trace contributes.
 const MAX_TRACED_CONSOLE: 4
 ```
 
+#### `MAX_TRACED_ACTIONS`
+
+How many of the page's own actions one test's trace contributes, the LAST ones.
+
+```typescript
+const MAX_TRACED_ACTIONS: 40
+```
+
+#### `MAX_TRACED_BODY_CHARS`
+
+How much of a 4xx request's sent body (or its response body) the trace read keeps.
+
+```typescript
+const MAX_TRACED_BODY_CHARS: 300
+```
+
 #### `MAX_TRACE_NOTE_TESTS`
 
 How many tests the note in a run's result names.
@@ -2490,6 +2856,22 @@ How long a URL the note prints, before the middle is cut.
 const TRACE_NOTE_URL_CHARS: 96
 ```
 
+#### `TRACE_NOTE_SENT_CHARS`
+
+How much of the sent body the note prints — enough to see a `{"data":…}` wrapper.
+
+```typescript
+const TRACE_NOTE_SENT_CHARS: 160
+```
+
+#### `TRACE_NOTE_GOT_CHARS`
+
+How much of the response body the note prints — the API's first error line.
+
+```typescript
+const TRACE_NOTE_GOT_CHARS: 120
+```
+
 #### `DIAGNOSIS_TRACE_FLAG`
 
 The `--trace` flag this platform adds, and the only value it adds it with.