e2e 0.16.0 → 0.17.0

package/dist/run/worker/entry.js

@@ -17,7 +17,7 @@ import { StreamRedactor } from '../../internal/redact.js';
 import { processSecrets, registerStaticSecrets, staticSecretLedger } from '../secrecy.js';
 import { SessionStore } from '../sessions.js';
 import { TargetWorker } from './session.js';
-import { isAbandonedStepRejection } from '../steps.js';
+import { isAbandonedRejection } from '../../internal/abandoned.js';
 /**
  * Outbound messages in flight. `process.send` is asynchronous and a
  * `process.exit` right behind it can drop the message, so exiting waits for
@@ -152,6 +152,7 @@ async function bootstrap(message, debug, aiTrace) {
         sessionStore: SessionStore.forWorker(message.runId, message.sessionsRoot, Buffer.from(message.sessionKeyBase64, 'base64')),
         runId: message.runId,
         artifactsRoot: message.artifactsRoot,
+        rerunDir: message.rerunDir,
         headed: message.headed,
         workerSlot: message.workerSlot,
         env: process.env,
@@ -169,13 +170,13 @@ function main() {
     process.on('SIGINT', () => undefined);
     process.on('SIGTERM', () => undefined);
     process.on('uncaughtException', (cause) => fatal(cause));
-    // A step the body did not await rejects on a promise nobody holds once it
-    // is cancelled; the attempt has already recorded it as STEP_NOT_AWAITED.
+    // A step or poll the test did not await rejects on a promise nobody holds
+    // once it is cancelled; the attempt has already recorded it as STEP_NOT_AWAITED.
     // Any other rejection nobody caught is charged to the attempt in flight,
     // or recorded against the last test that finished; only before any test
     // has finished is it the worker's.
     process.on('unhandledRejection', (cause) => {
-        if (isAbandonedStepRejection(cause))
+        if (isAbandonedRejection(cause))
             return;
         if (worker?.strayRejection(cause) !== true)
             fatal(cause);

package/dist/run/worker/protocol.d.ts

@@ -56,6 +56,8 @@ export interface WorkerBootstrap {
     readonly workerSlot: number;
     readonly runId: string;
     readonly artifactsRoot: string;
+    /** See `TargetExecutorOptions.rerunDir`. */
+    readonly rerunDir: string | undefined;
     readonly headed: boolean;
     readonly sessionsRoot: string;
     /** Per-run AES key; transferred only over this channel, never disk or env. */

package/dist/run/worker/session.d.ts

@@ -35,6 +35,8 @@ export interface TargetWorkerDeps {
     readonly sessionStore: SessionStore;
     readonly runId: string;
     readonly artifactsRoot: string;
+    /** See `TargetExecutorOptions.rerunDir`. */
+    readonly rerunDir: string | undefined;
     readonly headed: boolean;
     /** See `TargetExecutorOptions.workerSlot`. */
     readonly workerSlot: number;

package/dist/run/worker/session.js

@@ -46,6 +46,7 @@ export class TargetWorker {
                 target: deps.target,
                 runId: deps.runId,
                 artifactsRoot: deps.artifactsRoot,
+                rerunDir: deps.rerunDir,
                 sessionStore: deps.sessionStore,
                 headed: deps.headed,
                 workerSlot: deps.workerSlot,

package/dist/telemetry/events.js

@@ -205,6 +205,7 @@ export function runCompletedEvent(report, context) {
             tests_executed: run.summary.executed,
             tests_passed: run.summary.passed,
             tests_failed: run.summary.failed,
+            tests_interrupted: run.summary.interrupted,
             tests_flaky: run.summary.flaky,
             tests_skipped: run.summary.skipped,
             attempts_total: attempts.reduce((total, count) => total + count, 0),

package/dist/types.d.ts

@@ -198,7 +198,7 @@ export interface TextMatchOptions {
 /**
  * Role query options. A role query never matches a node hidden from the
  * accessibility tree, on every engine; `visible` (inherited) is the one knob
- * that narrows the other query kinds the same way.
+ * that narrows the other query kinds, to the nodes `toBeVisible()` accepts.
  */
 export interface RoleOptions extends TextMatchOptions {
     /** Accessible name filter. */
@@ -377,9 +377,13 @@ export interface Locator extends Screen {
     all(): Promise<Locator[]>;
     /** Reads the normalized text of every current match, without auto-waiting; empty when nothing matches. */
     allTextContents(): Promise<string[]>;
-    /** Waits for the requested locator state. */
+    /**
+     * Waits for the requested locator state, `visible` by default: `attached`
+     * for one match, visible or not; `detached` for none; `hidden` for none or
+     * a hidden one.
+     */
     waitFor(options?: {
-        state?: 'visible' | 'hidden';
+        state?: 'attached' | 'detached' | 'visible' | 'hidden';
         timeout?: number;
     }): Promise<void>;
     /** Adds deterministic locator filters. */
@@ -1250,6 +1254,8 @@ export interface E2EConfig {
     cleanupTimeout?: number;
     /** Retries per test, 0 through 10; default 1 in CI, else 0. */
     retries?: number;
+    /** Fail the run when a test skips itself after a soft failure or an earlier failed attempt; default false. */
+    failOnSkippedFailure?: boolean;
     /** Parallel workers, 1 through 1024; default 1 in CI, else half the cores. An engine may cap it lower. */
     workers?: number;
     /** `{ store }` hands every artifact to a host store as it is produced. */

package/docs/agents.mdx

@@ -109,9 +109,12 @@ agent if the problem affects several tests:
 5. Compare models or `providerOptions` by running the same tests with
    `--agent <name>`.
 
-Named agents can use the [replay cache](/cache). Custom tools and executors
-have their own replay constraints, described under [project tools](/tools)
-and [custom executors](/executors#replay-cache).
+Named agents can use the [replay cache](/cache). Each agent records its
+own entries, keyed by its name and its context, so a test that runs as
+`buyer` and as `admin` never replays one persona's steps for the other, and
+changing `agentContext` records again. Custom tools and executors have their
+own replay constraints, described under [project tools](/tools) and
+[custom executors](/executors#replay-cache).
 
 ## Pick an agent per run
 

package/docs/assertions.mdx

@@ -0,0 +1,94 @@
+---
+title: Assertions
+description: Check the screen with agent.assert, wait for a condition, and extract data.
+---
+
+An assertion checks what is on screen. The agent has three judgment calls:
+`assert` checks the screen now, `waitFor` waits until a condition holds, and
+`extract` reads structured data. When you know the exact value, use an
+`expect` [locator assertion](#locator-assertions) instead, with no model call.
+
+```ts
+await agent.assert('the dashboard shows a trial badge');
+```
+
+## `agent.assert`
+
+`assert` checks a statement against the current screen. A false statement
+fails with `ASSERTION_FAILED`. If the screen does not provide enough evidence,
+it fails with `ASSERTION_INCONCLUSIVE`.
+
+The judging model sees the statement and the current screen. It does not see
+earlier steps or the acting agent's summaries.
+
+## `agent.waitFor`
+
+`assert` checks the screen now. Use `waitFor` when the condition may become true
+later. It polls the screen and only calls the model when the observation changes.
+
+```ts
+await agent.waitFor('the export finishes and a download link appears', {
+  interval: 500,
+  timeout: 120_000,
+});
+```
+
+## `agent.extract`
+
+`extract` reads structured data from the screen. Provide a
+[Standard Schema](https://standardschema.dev) validator, such as Zod, to define
+the result.
+
+```ts
+import { expect } from 'e2e';
+import { z } from 'zod';
+
+const data = await agent.extract('every todo title and how many remain', {
+  schema: z.object({ titles: z.array(z.string()), remaining: z.number().int() }),
+});
+expect(data.titles).toContain('Buy milk');
+```
+
+<Tip>
+For model-generated descriptions, check the relevant meaning rather than the
+entire sentence. Use a [locator assertion](/locators) when the exact text matters.
+</Tip>
+
+## Judging pixels
+
+By default, judgments read a redacted text snapshot of the screen. Add
+`vision: true` for visual checks, such as charts or layout. Use
+`vision: 'only'` to judge the screenshot alone.
+
+```ts
+await agent.assert('the chart trends upward', { vision: true });
+await agent.assert('the search form is not covered by a banner', { vision: 'only' });
+```
+
+Images add input tokens. Screenshots are withheld for the rest of an attempt
+after a secret is filled. The [agent reference](/reference/agent#vision)
+lists the modes and restrictions.
+
+## Locator assertions
+
+`expect` on a locator checks an exact value and calls no model. It retries
+until the check passes or the assertion timeout runs out.
+
+```ts
+await expect(screen.getByRole('status')).toHaveText('2 remaining');
+await expect(screen.getByRole('heading', 'Dashboard')).toBeVisible();
+```
+
+[Locators](/locators) covers queries and actions. The
+[expect reference](/reference/expect#locator-matchers) lists every matcher.
+
+## Next
+
+<CardGroup cols={2}>
+  <Card title="Locators" icon="crosshairs" href="/locators">
+    Exact actions and checks with `screen` and `expect`.
+  </Card>
+  <Card title="How agent steps work" icon="list-check" href="/agent-steps">
+    Verdicts, exit codes, and what the model sees.
+  </Card>
+</CardGroup>

package/docs/authentication.mdx

@@ -211,7 +211,9 @@ export default {
 ```
 
 `E2E_SECRET_<NAME>` overrides an entry per run, with the same uppercasing rule
-as credentials, so a CI job can supply the value without touching the config:
+as credentials, so a CI job can supply the value without touching the config.
+Two entries that map to one variable, like `stripe-key` and `stripe_key`, fail
+the config load with `INVALID_CONFIG`, as two such credentials do:
 
 <CodeGroup>
 ```bash npm

package/docs/browser.mdx

@@ -39,7 +39,9 @@ await app.open('/checkout');
 await expect(screen.getByText('$42.00')).toBeVisible();
 ```
 
-Each handler must call exactly one of `fulfill`, `continue`, or `abort`. An
+Each handler must call exactly one of `fulfill`, `continue`, `fallback`, or
+`abort`. The newest route runs first; `continue` sends the request straight to
+the network, while `fallback` passes it to the route registered before. An
 `expect` that fails inside the handler fails the test, at the next step or at
 the end of the test when nothing follows. To inspect a real response, start
 waiting before the action that sends it:
@@ -114,14 +116,33 @@ const flag = await browser.evaluate((name: string) => window.localStorage.getIte
 Use `evaluate` for state that `screen` cannot read. Prefer locators and
 assertions for visible UI so tests depend less on the DOM structure.
 
+## Run a script before the page
+
+An init script runs in every document before the page's own scripts: mock a
+browser API, seed `Math.random`, or set a flag the app reads at boot. For every
+test:
+
+```ts
+web({ initScripts: [{ path: 'tests/init.js' }] })
+```
+
+For one test, before the page opens:
+
+```ts
+await browser.addInitScript((value) => { Math.random = () => value; }, 0.5);
+await app.open('/raffle');
+```
+
+See [init scripts](/reference/web#init-scripts).
+
 ## Cookies
 
 ```ts
 await browser.setCookies([{ url: 'http://localhost:3000', name: 'tz', value: 'UTC' }]);
 ```
 
-A cookie URL that does not parse, or uses `file:`, `data:`, or
-`javascript:`, is `POLICY_DENIED`; a domain cookie is checked as the origin
+A cookie URL that does not parse, or uses a scheme other than `http:` or
+`https:` (`about:blank` included), is `POLICY_DENIED`; a domain cookie is checked as the origin
 it would be sent to. If any entry is refused, no cookies are set. To resize
 the page, see [Testing viewports](/viewports).
 
@@ -144,8 +165,23 @@ export default {
 } satisfies E2EConfig;
 ```
 
-`npx playwright install webkit --with-deps` provisions the extra browser in
-CI. `connect` attaches to a remote Chromium over CDP instead of launching
+In CI, provision the extra browser with the [install command](/reference/web#installing-browsers):
+
+<CodeGroup>
+```bash npm
+npx @e2e-dev/web install webkit --with-deps
+```
+
+```bash pnpm
+pnpm exec e2e-web install webkit --with-deps
+```
+
+```bash bun
+bunx @e2e-dev/web install webkit --with-deps
+```
+</CodeGroup>
+
+`connect` attaches to a remote Chromium over CDP instead of launching
 one; a [browser provider](#hosted-browsers) does the same and also leases
 and releases the browser. [Testing viewports](/viewports) covers sizes.
 
@@ -237,7 +273,7 @@ The attempt runs in the browser's persistent default context, on the
 browser's own first tab, so the remote must contain only that context, and
 the limits of
 [`connect.reconnectEndpoint`](/reference/web#recovering-a-cdp-transport)
-apply: no `headers`, `basicAuth`, or `userAgent` (each is `INVALID_CONFIG`), no
+apply: no `headers`, `basicAuth`, `userAgent`, `locale`, or `timezoneId` (each is `INVALID_CONFIG`), no
 `app.clearState()` (`UNSUPPORTED_CAPABILITY` naming the scope), and no session
 state capture or restore, so a run whose tests consume a
 [session](/authentication) on the target fails with `COLLECTION_ERROR`

package/docs/cache.mdx

@@ -45,27 +45,60 @@ bunx e2e run --no-cache
 
 ## How a replay works
 
-1. Check the starting screen: the same route, whatever the record id, the
-   query, or the fragment. Retries always run live.
+1. Check the starting screen: the same route, whatever the record id or the
+   fragment. Retries always run live.
 2. Find each recorded control and repeat its action. The runner matches
    controls by their role, name, test id, and surrounding context. It waits
    for missing controls and stops if a match is ambiguous. A control with no
-   name is found by its place among the unnamed controls of its kind.
-3. Check the final path and controls that appeared during the original step.
-   Text that changes with the data, a count, a date, an id, is not used.
+   name is found by its place among the unnamed controls of its kind inside
+   the same named row, list item, or group; with no such container to tell
+   it from its twins, the agent takes the step.
+3. Check the final route and what the original step changed: the controls
+   that appeared, with their checked, selected, expanded, or pressed state,
+   and the ones that went away. At least one of those changes must happen
+   during the replay, counted from the first screen the replay saw on the
+   route it ended on, so an outcome already on screen before the actions
+   that should produce it proves nothing; a step whose last action moved to
+   another route has that move as its evidence. An alert the replay raised
+   that the recording never saw stops it too. Text that reads differently on
+   every run, a date, a time, a duration, an id, is not used, except in an
+   alert, where it is read as a placeholder.
 4. Finish without a model call, or let the agent continue with a record of
    what ran and why replay stopped.
 
+A route is the origin, the path, and the query. Ids, tokens, timestamps,
+and cache busters in either the path or the query are read as an id
+placeholder, so `/orders/42?t=1727780000` and `/orders/7?t=1727780999` are
+one route. Every other query value is part of it: `?mode=safe` and
+`?mode=unsafe`, or `/companies` and `/companies?tab=notes`, are different
+screens, and so is a tracking parameter that was not there when the step
+was recorded. Two routes that differ in one word, `/products/summer-sneaker`
+and `/products/winter-boot`, are different screens too, even when they look
+alike. A location on the app's own origin is compared by its path, so a
+recording follows the app to a preview deployment that shares its
+`app.identity`; a page on any other origin is another route.
+
+A count that names what it counts, `3 records imported` or `Showing 1 to 9
+of 9 results`, is part of the effect when the step made it appear on the
+screen it acted on, and must read the same on replay. A count that was
+already on screen and only moved, `41 items` to `42 items`, or one on a
+screen the step navigated to, is not used, since leftover data from earlier
+runs moves it again. A bare number such as a badge is never used.
+
 Typed values replay as recorded, even when an earlier run left the same
 value on screen. Secret fills resolve the current value by name and run
 through authorization again.
 
 ## What must match
 
-A cache entry belongs to a specific test, target, instruction, and set of
-params. Renaming the test or target, changing the instruction or an ordinary
-param, or upgrading the engine's major or minor version causes a miss.
-Changing the model does not.
+A cache entry belongs to a specific test, target, instruction, set of
+params, and agent. Renaming the test or target, changing the instruction or
+an ordinary param, running with another configured agent, changing the
+agent's `context` or the test's `agentContext`, or upgrading the engine's
+major or minor version causes a miss. A test that runs once per agent
+(`agent: ['buyer', 'admin']`) records once per agent. Changing the model
+does not. The agent context enters the key as a hash of its redacted text,
+so a secret in it contributes only its name.
 
 A timestamp or a fresh email address would cause a miss on every run. Wrap
 values like these in `unique()` so the runner substitutes the current value
@@ -96,7 +129,9 @@ identity. On devices, replay uses the
 
 In `read-write` mode, the runner saves a recording at the end of the
 attempt when a later verification step passed. A step that took no action
-records nothing.
+records nothing, and neither does one that changed nothing the replay could
+check: no control appeared, went away, or changed state, and the route
+stayed the same.
 
 | Counts as verification | Does not count |
 | --- | --- |
@@ -145,14 +180,14 @@ such as an `afterEach` assertion.
 | `retry` | Retries never replay. | Nothing. |
 | `invalid-entry` | The file is unreadable, over 1 MiB, or from another schema version. | `npx e2e cache clear`. |
 | `truncated` | The recording hit a limit, see [below](#limits-and-gaps). | Split the step, or pass the secret as a `Secret`. |
-| `wrong-context` | The app was on another screen than when the step was recorded: a different route, not a different record, query, or fragment. | Open the same screen before the step. |
-| `target-not-found` | A recorded control did not appear within 15 seconds. | The UI changed. The next passing run re-records. |
+| `wrong-context` | The app was on another screen than when the step was recorded: a different origin, path, or query, not a different record id or fragment. | Open the same screen before the step. |
+| `target-not-found` | A recorded control did not appear within 15 seconds, or it has no name and no named container to tell it from its twins. | The UI changed: the next passing run re-records. For an unnamed control, give it a label or put it in a named row or group. |
 | `target-ambiguous` | The number of matching controls changed. | Give repeated controls distinct names or use unique test data. |
 | `gap` | An action cannot be replayed, see [below](#limits-and-gaps). | The agent continues this part live. Put stable values in `params`. |
 | `action-failed` | The app rejected a replayed action. | Check the app. |
 | `action-uncertain` | A replayed action failed with an unknown commit state. The agent is told to check before acting again. | Check the app. |
 | `viewport-changed` | A bare-point tap or hover was recorded on a viewport of another size. | Keep the viewport fixed. |
-| `end-mismatch` | Every action ran, but the recorded path or a control that should have appeared did not come back. | Leftover data from an earlier run, a banner that comes and goes, or a regression. |
+| `end-mismatch` | Every action ran, but the recorded route, a control that should have appeared or gone away, or a recorded state did not come back; the outcome was already on screen before the replay; or the replay raised an alert the recording never saw. | Leftover data from an earlier run, a banner that comes and goes, or a regression. |
 
 A stop before any action ran is a miss. After replay starts, it is a
 hand-off. Unique test data and cleanup in `afterEach` help avoid stale
@@ -176,8 +211,9 @@ the instruction or `params`, or ones the agent composed itself, replay.
 
 Each entry is a JSON file under `.e2e/cache/`, named by a hash of its key.
 It contains actions, target descriptions, typed text, a step summary, and
-checks for the final state. Those checks include the path and up to eight
-controls that appeared during the step.
+checks for the final state. Those checks include the route, up to eight
+controls that appeared during the step, alerts and status messages first,
+and up to eight that went away.
 
 Entries contain no prompts, conversations, screenshots, observed trees, or
 secret values. A secret fill stores only the secret's name. Other typed
@@ -220,12 +256,16 @@ Local runs leave a committed directory clean unless something changed. A
 replayed step never rewrites its entry, and a live re-recording with the same
 actions, paths, and anchors is not written: the summary, the measured end
 wait, and the rule that flagged a typed run-time value differ between two
-live runs of the same flow and do not count. A file changes when:
+live runs of the same flow and do not count. Upgrading `e2e` to a version
+that changes how entries are matched re-keys every entry, so the first run
+after it records them again. A file changes when:
 
 - a step records for the first time,
 - the agent finishes a step after a hand-off, re-recording what it saw,
 - a step fails after replaying, or ends in an `end-mismatch` the agent had
   to repair, which deletes the entry,
+- a step with an entry passes without leaving anything to record, which
+  deletes the entry,
 - no verification step confirmed the entry by the end of the attempt, which
   deletes it.
 
@@ -257,8 +297,14 @@ CI=1 bunx e2e run --strict-cache
 The reasons that fail are the ones that mean the app or the entry changed:
 `invalid-entry`, `wrong-context`, `target-not-found`, `target-ambiguous`,
 `viewport-changed`, `action-failed`, `action-uncertain`, and `end-mismatch`.
-A step with no recording (`no-entry`), a retry, a `gap`, and a `truncated`
-recording still run live. `REPLAY_STALE` exits 2 and is not retried, since a
+A `no-entry` miss fails too when the cache directory holds a recording of the
+same step under another key, from before an `e2e` or engine upgrade or a
+change to the project id, the app's identity, or the agent's context. The
+message names that file; delete it once nothing replays it. A custom
+`cache.store` is not checked this way. Entries recorded before this check
+existed are covered once a `read-write` run replays or re-records them. A
+step never recorded (a new or edited instruction or params), a retry, a
+`gap`, and a `truncated` recording still run live. `REPLAY_STALE` exits 2 and is not retried, since a
 retry never replays and would pass live. The entry stays where it is, even
 in `read-write` mode, so every strict run fails on it until it is re-recorded:
 run the test in `read-write` mode without the flag, and with `cache.strict`

package/docs/ci.mdx

@@ -35,7 +35,7 @@ jobs:
       - run: pnpm install --frozen-lockfile
 
       - name: Install browsers
-        run: npx playwright install chromium --with-deps
+        run: pnpm exec e2e-web install chromium --with-deps
 
       - name: Run e2e
         run: npx e2e run --reporter list,junit
@@ -66,7 +66,9 @@ jobs:
 ```
 
 The workflow pins actions to commit SHAs and installs dependencies from the
-lockfile. `npx e2e` runs the installed version.
+lockfile. `npx e2e` runs the installed version. The
+[install command](/reference/web#installing-browsers) downloads the browsers
+for the Playwright version the engine pins, with their system libraries.
 
 Artifacts upload on every run that is not cancelled, so a test that failed
 and then passed on retry still has its evidence.
@@ -139,10 +141,12 @@ implemented yet.
 
 `--last-failed` runs only the tests the previous run did not pass, read from
 `report.json` in the [`output`](/reference/config#output) directory (`.e2e`
-by default). The rerun empties `artifacts/` there when it starts, so
-upload the first run's artifacts before rerunning in the same job if you want
-both. The [CLI reference](/reference/cli#flags) lists what counts as not
-passed. Locally it is the loop after a red run:
+by default). The rerun keeps the artifacts the first run's report names and
+writes its own under `artifacts/rerun-1/`, so one upload after both steps
+holds the evidence of each. A test another filter keeps out of the rerun
+stays owed: the next `--last-failed` runs it. The
+[CLI reference](/reference/cli#flags) lists what counts as not passed.
+Locally it is the loop after a red run:
 
 <CodeGroup>
 ```bash npm
@@ -193,7 +197,7 @@ flaky, so you can identify flows that need investigation.
 `--max-failures <n>` stops the run once that many tests have failed, so a
 broken deploy does not spend a model call on every remaining agent step. The
 tests not started are skipped with cause `failure-limit`, the ones running
-end as `interrupted`, and the job exits 1.
+end as `interrupted`, counted apart from the failures, and the job exits 1.
 
 ## Exit codes
 

package/docs/debugging.mdx

@@ -91,7 +91,9 @@ failed result:
 
 Artifacts land under `.e2e/artifacts/` (`<output>/artifacts/` when the
 [`output`](/reference/config#output) is moved), one directory per attempt.
-Each run empties it first, so it holds the latest run's evidence:
+Each run empties it first, so it holds the latest run's evidence. A
+`--last-failed` rerun instead empties it down to the files the report it
+reruns names, and writes its own under `rerun-<n>/`:
 
 - **Screenshots.** Failed attempts capture one whenever the engine can and
   pixels are allowed. The built-in `agent.assert` also captures one after
@@ -99,8 +101,9 @@ Each run empties it first, so it holds the latest run's evidence:
   be withheld. Use `app.screenshot('label')` to capture one explicitly.
 - **Playwright traces** on the attempts the [`trace`](/reference/config#trace)
   mode records: every attempt locally, the first retry in CI. Open one with
-  `npx playwright show-trace <file>`; `--trace off` skips the cost for one
-  run, `--trace` records every attempt of a CI run.
+  `npx playwright-core@1.63.0 show-trace <file>` (`pnpm dlx` under pnpm);
+  `--trace off` skips the cost for one run, `--trace` records every attempt
+  of a CI run.
 - **Downloads** saved through `browser.waitForDownload`, recorded with kind
   `download`. They are the app's bytes: `redaction: "incomplete"` unless a
   secret reached the session (filled, or held by the engine for basic auth)

package/docs/executors.mdx

@@ -215,8 +215,10 @@ default, follows the configured cache mode. A recorded step replays without
 calling `runStep`. A replay that stops partway calls `runStep` with
 `ctx.replayedPrefix`: continue from the current screen and do not redo the
 replayed actions. What a step does through `ctx.actions` is recorded; a
-mutating tool call leaves a gap the executor fills on replay. Entries are not
-keyed by executor, so an entry one agent recorded replays for another.
+mutating tool call leaves a gap the executor fills on replay. Entries are
+keyed by the configured agent and its context, so an entry one agent
+recorded never replays for another; the executor itself is not part of the
+key, so changing an agent's executor keeps its entries.
 
 `'off'` never replays or records the executor's steps, so every step reaches
 `runStep`. Use it for a brain whose own history or memory is the source of

package/docs/github.mdx

@@ -63,7 +63,10 @@ Upload artifacts even when a retry passes. Each failure's evidence links open
 the run's Artifacts section; inside the download, every test has a directory
 named after it and the agent that ran it
 (`web/tests_billing.e2e.ts__upgrades/default/attempt-0/`), so keep
-`path: .e2e/artifacts` and the download lines up with the report. A project
+`path: .e2e/artifacts` and the download lines up with the report. A
+`--last-failed` rerun keeps the first run's directories and puts its own
+under `rerun-1/`, so a flaky test's failed attempt still links to its own
+files. A project
 below the checkout root, such as `packages/e2e-tests`, gets source links under
 that path. The checkout root is the nearest directory holding `.git` inside
 `GITHUB_WORKSPACE`, so `actions/checkout` with a `path` input works too.
@@ -143,9 +146,14 @@ passes:
 
 The comment covers the whole suite, not only the tests the rerun ran again.
 A test that failed and then passed shows as flaky, a test that failed twice
-stays failed, and the rest keep their first-pass results. The comment
-matches the job's status: it stays red when another filter kept a failed
-test out of the rerun.
+stays failed, one that was interrupted and then passed shows as passed, and
+the rest keep their first-pass results. The comment stays red while the
+rerun left out something it owed: a failed test, one `--max-failures` stopped
+before it ran, or a failed `beforeAll` or `afterAll` whose tests another
+filter kept out of the rerun. It shows ⏹️ when the rerun left out a test the
+first pass never finished. The rerun's own exit code counts only what it ran.
+A failed attempt's evidence links to the first run's files, which the rerun
+keeps.
 
 ## Matrix jobs