devharness 0.8.0

package/docs/replay.md

@@ -0,0 +1,1411 @@
+# Command Replay
+
+Record and replay command sequences for testing, automation, and debugging workflows.
+
+> **Tip:** Use the `replay-agent` (`.claude/agents/replay-agent.md`) to build sequences through investigation - it records your tool calls automatically.
+>
+> For a condensed, agent-facing version of this material see
+> `skills/cdp-tools/references/sequences.md`. This document is the fuller
+> reference with worked examples.
+
+## Actions
+
+Every capability below is the one `replay` tool, dispatched on `action`:
+
+| Group | Actions |
+|---|---|
+| History | `history`, `repeat`, `runFromLog` |
+| Authoring | `create`, `recordInteraction`, `insert`, `addConditional`, `declare` |
+| Managing | `list`, `get`, `delete`, `export`, `load`, `listSaved`, `deleteSaved` |
+| Running | `run`, `runAll`, `step`, `finish`, `status`, `cancel` |
+
+There is no `stopInteraction` and no `save` action - see
+[Recording Interactions](#recording-interactions) and
+[Saving and Loading](#saving-and-loading).
+
+## Recording Interactions
+
+The easiest way to create a sequence is to record your interactions directly in
+the browser.
+
+```javascript
+// Launch Chrome with a meaningful name
+launchChrome({ reference: "my-signup-test" })
+
+// Start recording - THIS CALL BLOCKS until you finish in the browser
+replay({ action: 'recordInteraction', connectionReason: 'my-signup-test' })
+```
+
+**`recordInteraction` blocks until the person finishes in the browser overlay.**
+There is no separate stop call. The tool call returns only once you click ✓
+(complete) or ✕ (cancel) in the overlay, and its response *is* the created
+sequence summary. Because it waits on a human, don't call it unattended.
+
+If no connection exists for `connectionReason`, Chrome is auto-launched - but
+only if you also pass `startUrl` (or an `issueId` whose issue carries one). If a
+connection already exists and you pass `startUrl`, the page navigates there
+first.
+
+### The Recording Overlay
+
+A visual overlay appears showing:
+- Recording status (`REC` / `PAUSED`)
+- Event count and duration
+- Coordinates and element info
+- Buttons: 💬 Comment | ⏸ Pause | ↺ Reset | ✓ Complete | ✕ Cancel
+
+Pass `showOverlay: false` to suppress it.
+
+### Add Comments
+
+During recording, add comments to document expected behavior:
+- Click the 💬 button in the overlay
+- Or press **Ctrl/Cmd+Shift+C** (plain comment), **Ctrl/Cmd+Shift+B** (bug),
+  **Ctrl/Cmd+Shift+F** (feature)
+
+Comments are attached to the previous action and appear in exported tests.
+
+**Bug and feature comments create issues.** Each `bug`/`feature` comment becomes
+an entry in the issue tracker with its own copy of the sequence saved as
+`<type>-<id>-repro`. When a recording contains any such comment, no plain
+in-memory sequence is created - the issue sequences are the output.
+
+### Naming
+
+The sequence is named, in order of preference:
+1. the `name` you passed,
+2. `<issueType>-<issueId>-repro` when you passed `issueId`,
+3. the `connectionReason`.
+
+If a sequence with that name already exists you get a conflict response. Re-run
+with a different `name`, or with `overwrite: true`.
+
+### Recording Options
+
+The conversion from raw input events to sequence commands is tunable. All four
+flags default to today's behaviour, so omitting them changes nothing:
+
+| Option | Default | Effect |
+|---|---|---|
+| `simplifyEvents` | `true` | Collapse noisy raw events (mousemove runs, key repeats) before conversion. `false` keeps them all. |
+| `includeHovers` | `false` | Emit `input({ action: 'mousemove' })` steps for hovers. Needs `simplifyEvents: false` to keep more than the settled positions. |
+| `preferCoordinates` | `false` | Emit `x,y` clicks even where a selector was captured. Use for canvas/3D/drag-heavy UIs. |
+| `preferSelectors` | `false` | Emit selector clicks wherever a selector exists - *including* canvas elements, which otherwise fall back to coordinates. |
+
+If both `preferCoordinates` and `preferSelectors` are `true`, **`preferSelectors`
+wins** - the more portable of the two is chosen.
+
+```javascript
+replay({
+  action: 'recordInteraction',
+  connectionReason: 'canvas-bug',
+  preferCoordinates: true,   // a WebGL canvas has no useful selectors
+  includeHovers: true,       // the bug is a hover artefact
+  simplifyEvents: false
+})
+```
+
+`recordInteraction` also accepts `outputFormat`, which appends a dump to the
+usual recording summary:
+
+- `events` - the raw captured input events as JSON (this is the only place they
+  are ever available; they are not stored with the sequence)
+- `commands` - the converted command list as JSON
+- `review` - a human-readable walkthrough of the captured events: one numbered
+  entry per interaction with its coordinates, the element and selector found for
+  it, plus navigations, pastes and the comments the person left while recording
+- `playwright` / `puppeteer` - generated test code for the fresh recording
+
+Use `outputFormat: 'events'` when a recording produced surprising commands and
+you need to see what the recorder actually captured; `review` is the same
+information in a form you can read, and is the better choice when you want to
+decide whether a step should use a selector or coordinates.
+
+### Recording Against an Issue
+
+```javascript
+replay({ action: 'recordInteraction', connectionReason: 'bug-7', issueId: 7 })
+```
+
+The issue's `type`, `title` and `startUrl` are used automatically, a fullscreen
+issue overlay is shown, and the finished sequence is saved into the issues
+folder and linked to issue #7.
+
+## Exporting Tests
+
+Export sequences as Playwright or Puppeteer tests:
+
+```javascript
+// Export as Playwright test
+replay({ action: 'export', name: 'my-signup-test', format: 'playwright' })
+// Creates: tests/e2e/my-signup-test.spec.ts
+// Also saves: .cdp-tools/sequences/my-signup-test.json
+
+// Export as Puppeteer test
+replay({ action: 'export', name: 'my-signup-test', format: 'puppeteer' })
+// Creates: tests/puppeteer/my-signup-test.test.js
+
+// Export sequence JSON only (default format)
+replay({ action: 'export', name: 'my-signup-test', format: 'sequence' })
+// Creates: .cdp-tools/sequences/my-signup-test.json
+```
+
+`export` always writes the sequence JSON first, whatever the format. If a target
+file already exists you get a conflict response; re-run with `overwrite: true`.
+
+Only `navigate` and `input` steps are translated into Playwright/Puppeteer code
+- debugging steps (`breakpoint`, `inspect`, `request`, ...) have no equivalent
+and are dropped from the generated test.
+
+### Configure Export Paths
+
+In `.cdp-tools/config.json`:
+
+```json
+{
+  "replay": {
+    "playwrightExportPath": "./tests/e2e",
+    "puppeteerExportPath": "./tests/puppeteer"
+  }
+}
+```
+
+### Preview Before Export
+
+```javascript
+// Preview as Playwright code
+replay({ action: 'get', name: 'my-signup-test', outputFormat: 'playwright' })
+
+// Preview as Puppeteer code
+replay({ action: 'get', name: 'my-signup-test', outputFormat: 'puppeteer' })
+
+// The raw command list as JSON (what actually gets executed)
+replay({ action: 'get', name: 'my-signup-test', outputFormat: 'commands' })
+```
+
+`outputFormat` on `get` accepts `commands`, `playwright` and `puppeteer`.
+`events` and `review` are not valid here and each returns an error explaining
+why: a stored sequence holds converted *commands*, never the raw input events,
+and both of those formats render events. The raw events exist only during a
+recording - see [Recording Options](#recording-options) for
+`outputFormat: 'events'` and `outputFormat: 'review'` on `recordInteraction`.
+
+## Visual Replay Cursor
+
+When replaying sequences, a visual cursor shows where clicks happen:
+
+- **Animated cursor** moves to the click position before clicking
+- **Green ripple** on the click
+- **Key press toast** shows keyboard input
+
+The cursor is only driven for *coordinate* clicks (`input({ action: 'click', x,
+y })`) and for `input({ action: 'press' })`. Selector-based clicks execute
+without a cursor effect.
+
+Configure in `.cdp-tools/config.json`:
+
+```json
+{
+  "replay": {
+    "showCursor": true
+  }
+}
+```
+
+## Creating Sequences from History
+
+### From Command History
+
+```javascript
+// View command history
+replay({ action: 'history', limit: 20 })
+
+// Create sequence from history indices
+replay({
+  action: 'create',
+  name: 'login-flow',
+  indices: [1, 2, 3, 4, 5]
+})
+```
+
+Every tool response footer shows its own history index, so you usually don't
+need to call `history` first.
+
+### With Metadata
+
+Add description, expected outcome and a start URL for better documentation:
+
+```javascript
+replay({
+  action: 'create',
+  name: 'login-flow',
+  description: 'Logs into the application with test credentials',
+  expectedOutcome: 'User should be redirected to dashboard with welcome message',
+  startUrl: 'http://localhost:3000/login',
+  indices: [1, 2, 3, 4, 5]
+})
+```
+
+These fields are saved to disk and displayed when listing sequences.
+
+### Re-running History Directly
+
+```javascript
+// Execute commands straight from history without making a sequence
+replay({ action: 'repeat', indices: [12, 13] })
+
+// Execute lines from .cdp-tools/history.log (1-indexed, line 1 = most recent)
+replay({ action: 'runFromLog', lines: [3, 4, 5] })
+```
+
+Both stop at the first failing command. Both infer `connectionReason` from a
+`launchChrome`/`connectDebugger` command in the selection if you don't pass one,
+and error out if the commands need a connection and none can be determined.
+
+## Tool-Name Validation
+
+`create` and `load` reject a sequence whose steps name a tool that doesn't
+exist, **before anything runs**:
+
+```
+Error: Sequence "login-flow" references 1 unknown tool name
+The "load" action was rejected before any step ran, so no browser state was changed.
+
+- Step 4: `navigatee` is not a known tool - did you mean `navigate`?
+
+**Fix:** correct the `tool` field on the listed step(s).
+```
+
+Notes:
+- Only the tool *name* is checked. Params are deliberately not validated against
+  the tools' schemas, because a param may legitimately hold a `{{var:...}}` or
+  `{{timestamp}}` token at rest that only resolves to its real type at run time.
+- `conditional` is exempt - it is a virtual step tool the executor handles
+  itself and it is never a registered tool (see [Conditional Steps](#conditional-steps)).
+- A rejected `create` does not clobber an existing same-named sequence; a
+  rejected `load` is dropped from memory so it can't be run by id.
+
+## Managing Sequences
+
+```javascript
+// List all in-memory sequences
+replay({ action: 'list' })
+
+// View sequence details (by sequenceId or name)
+replay({ action: 'get', sequenceId: 'seq-1234567890' })
+replay({ action: 'get', name: 'login-flow' })  // memory first, then disk (fuzzy name match)
+
+// Delete a sequence from memory
+replay({ action: 'delete', sequenceId: 'seq-1234567890' })
+```
+
+## Saving and Loading
+
+```javascript
+// Export sequence to disk (working directory)
+replay({ action: 'export', sequenceId: 'seq-1234567890', format: 'sequence' })
+// Saves to: .cdp-tools/sequences/<name>.json
+
+// Export to global location (accessible from any directory)
+replay({ action: 'export', sequenceId: 'seq-1234567890', format: 'sequence', global: true })
+// Saves to: ~/.cdp-tools/sequences/<name>.json
+
+// List saved sequences on disk (add showAll: true to include completed issues)
+replay({ action: 'listSaved' })
+
+// Load sequence from disk
+replay({ action: 'load', filename: 'login-flow.json' })
+
+// Load into history (for editing)
+replay({ action: 'load', filename: 'login-flow.json', intoHistory: true })
+
+// Delete saved file
+replay({ action: 'deleteSaved', filename: 'login-flow.json' })
+```
+
+`run` and `get` load by `name` from disk on their own, so `load` is only needed
+when you want the sequence in memory (or in history) first.
+
+### Editing a sequence mid-session
+
+Edit the file and run it - the edit is what runs. The sequences directories are
+watched the way a managed dev server watches its own sources, so an edited file
+is re-read into memory shortly after you save it, and a run re-checks the file's
+timestamp on the way past rather than waiting for the watcher. Both are needed:
+the watcher keeps memory honest while you work, and the check at run time closes
+the gap between saving a file and immediately running it.
+
+In-memory copies used to shadow disk for the rest of the session - you edited a
+sequence, ran it by name, and silently got the previous version, while `runAll`
+reloaded the tree first and ran the new one. The same sequence behaved
+differently depending on how it was invoked.
+
+A file that is missing or mid-write leaves the loaded copy in place: a watcher
+fires as readily during a write as after one, and dropping a good sequence
+because it was caught half-saved is worse than the staleness this replaces. A
+sequence built from history and never saved is untouched by any of this - there
+is no file to reload it from.
+
+## Running Sequences
+
+### Basic Run
+
+```javascript
+replay({
+  action: 'run',
+  sequenceId: 'seq-1234567890',
+  connectionReason: 'test-session'
+})
+```
+
+Or by name, which also finds it on disk:
+
+```javascript
+replay({ action: 'run', name: 'login-flow', connectionReason: 'test-session' })
+```
+
+### Background by Default (breaking change in 0.7)
+
+**`run` no longer blocks.** It validates the request (sequence exists, tool
+names known, `startFrom` in range, variables supplied), registers a run, and
+returns immediately with a run id:
+
+```javascript
+replay({ action: 'run', name: 'login-flow' })
+// -> Run started in the background ... Run id: `run-3-mdkq1x2`
+
+replay({ action: 'status', runId: 'run-3-mdkq1x2' })   // progress while running,
+                                                       // the full result once settled
+replay({ action: 'cancel', runId: 'run-3-mdkq1x2' })   // stop it
+```
+
+While a run executes, `status` with its `runId` reports the current step and
+tool; once the run settles it returns exactly what the old blocking `run`
+would have returned (step results, debug state, `killChromeOnFinish` outcome).
+Post-run cleanup - cursor/overlay removal, debug state, `killChromeOnFinish` -
+happens in the background before the run's status turns terminal, exactly once.
+
+Run states: `running` → (`cancelling` →) one of `completed`, `failed`,
+`cancelled`, or `paused` (stepTo / breakpoint / click-validation - drive it
+with `step`/`finish` as before).
+
+Lifetime and limits:
+
+- Several runs can execute concurrently, including two runs of the same
+  sequence - the run id is what tells them apart.
+- Settled runs and their results are kept **in memory for 30 minutes** (at
+  most 50 records). After that, or after a server restart (including the
+  supervisor's hot-restart on rebuild, which also kills any in-flight run),
+  `status`/`cancel` with that id return `REPLAY_RUN_NOT_FOUND`.
+- `cancel` with a `runId` aborts the run's controller. The run's signal is
+  forwarded to every step's tool handler; cancellation also reaches nested
+  sequences (`conditional` flows, nested `replay run` steps) - they share the
+  parent run's signal. Status shows `cancelling` until the run actually stops.
+  What a cancel does to the step that is currently in flight depends on the
+  tool, and the three levels are genuinely different (see the table below).
+
+**Which tools honour cancellation** (canonical list - `#110`):
+
+| Tool | On cancel | What that means |
+| --- | --- | --- |
+| `wait` (all forms: `selector`, `selectorGone`, `expression`, `ms`) | **cancelled** | Polling/sleep stops mid-step. Nothing was in flight to abandon. |
+| `request` (`destination: 'node'`) | **cancelled** | The external signal is composed into the fetch's controller, so the **socket is closed** - the server sees the request aborted. Its own `timeoutMs` is still reported as a timeout, separately. |
+| `navigate` (`goto`, `reload`, `back`, `forward`) | **stops waiting** | Deliberate owner decision: `Page.stopLoading` is *not* called, because a half-loaded page that later steps act on is worse than a loaded one. The page finishes loading in the background; the step stops waiting for it. |
+| `inspect` (`evaluateExpression`) | **stops waiting** | CDP cannot recall a `Runtime.evaluate`; the expression keeps running in the target. Other `inspect` actions read captured state and only get the entry checkpoint. |
+| `content` (`parse`) | **stops waiting** | The plugin's `waitFor` predicate (default up to 8s) is abandoned. Extraction itself is one `page.evaluate`. |
+| `input` (every action) | **checkpoint only** | Input events cannot be recalled: once `Input.dispatchMouseEvent` is on the wire, Chrome **will** process it. Cancellation prevents events that had *not* gone out yet - checkpoints sit after connection/selector resolution, immediately before each dispatch, and between events in multi-dispatch paths (Tab loops, drag stepping, clear-and-retype, pinch). A cancelled drag still releases the mouse button. **Nothing already dispatched is undone.** |
+| `breakpoint({ action: 'await' })` | **checkpoint + fails the step** | Cancelling the wait removes a breakpoint the step created and fails the step. (Before #110 it reported `success: true` - a cancelled step recorded as passed.) |
+| `request` (`destination: 'browser'`) | **checkpoint only** | The `fetch` runs inside the page and is unreachable from the server; it runs to its own timeout. |
+| `screenshot`, `content` (other actions), `inspect` (other actions) | **checkpoint only** | Enough not to *start* a capture/read after the cancel; the capture itself is a single call with nothing to cancel. |
+| `dom`, `network`, everything else | **next step boundary** | No real wait or loop to interrupt (`network` reads an in-memory buffer). The in-flight call finishes and the run stops before the next step. |
+
+  Two caveats that apply to every row: work already dispatched to the browser
+  may still take effect, and a "stops waiting" step leaves work running in the
+  target that no one is watching any more.
+- A nested run started by a sequence step (a `conditional` flow, or a
+  `replay run` step - which is forced to `wait: true`) is part of its parent
+  run, never a separate top-level run.
+
+**Migration:** pass `wait: true` to keep the pre-0.7 blocking behaviour:
+
+```javascript
+replay({ action: 'run', name: 'login-flow', wait: true })  // blocks, returns full result
+```
+
+### Auto-Launch Chrome
+
+If the sequence starts with `launchChrome`, no `connectionReason` is needed -
+the launch step's `reference` becomes the run's connection.
+
+```javascript
+replay({ action: 'run', sequenceId: 'seq-my-flow' })
+```
+
+Otherwise, if the sequence needs a browser and no connection is active, Chrome
+is launched as a **fresh instance** using `connectionReason` (or a reference
+derived from the sequence name when you didn't pass one).
+
+### Retargeting a Run
+
+```javascript
+// Point a staging-recorded sequence at local
+replay({ action: 'run', name: 'checkout', baseUrl: 'http://localhost:3000' })
+
+// Enter through a freshly minted link, once
+replay({ action: 'run', name: 'magic-link-login', startUrl: 'https://app.example.com/m/abc123' })
+```
+
+- **`baseUrl`** rewrites the origin of *every absolute* `http(s)` URL in the
+  sequence - the stored `startUrl` and any string param in any step (a
+  `navigate goto` url, a `request` url, ...) - keeping path, query and hash.
+  Relative URLs are untouched. The stored sequence is never mutated.
+- **`startUrl`** replaces the sequence's start URL wholesale for this run,
+  applied after any rebasing.
+- Neither is preserved across a mid-run pause and `step`/`finish` resume, which
+  re-reads the stored sequence.
+
+### Timeout Configuration
+
+```javascript
+replay({
+  action: 'run',
+  sequenceId: 'seq-slow-flow',
+  connectionReason: 'test-session',
+  stepTimeout: 60000,    // per step (default: 30000)
+  totalTimeout: 600000   // whole run (default: 300000)
+})
+```
+
+Each step's tool call is bounded by `min(stepTimeout, remaining totalTimeout)`.
+A step that exceeds its bound fails the run at that step, like any other step
+failure - the error names the step, the tool, and the limit that fired. The
+run stops immediately; the timed-out tool call is not interrupted and may
+still complete in the background (its side effects can still land).
+
+Exceptions:
+
+- `wait` steps are exempt from `stepTimeout` - a wait carries its own
+  `timeoutMs` bound (default 15000) and fails itself on expiry. It is still
+  capped by the remaining `totalTimeout`.
+- Breakpoint pauses are unaffected: a step that hits a breakpoint returns
+  immediately with pause info, so an intentional pause never trips the
+  step timeout.
+
+### Start From a Specific Step
+
+```javascript
+replay({
+  action: 'run',
+  name: 'login-flow',
+  connectionReason: 'test-session',
+  startFrom: 5  // Skip steps 1-4, start at step 5 (1-indexed)
+})
+```
+
+`startFrom` beyond the sequence length is rejected.
+
+### Pause, Step, Finish
+
+```javascript
+replay({ action: 'run', name: 'login-flow', stepTo: 3 })  // run steps 1-3, then pause
+replay({ action: 'status' })                              // where am I?
+replay({ action: 'step', stepCount: 2 })                  // run the next 2 steps
+replay({ action: 'finish' })                              // run the rest
+replay({ action: 'cancel' })                              // drop the paused session
+```
+
+A bare `cancel` prefers the paused session; with background runs in flight,
+address the one you mean with `runId` (a bare `cancel` also works when exactly
+one run is executing and nothing is paused). `status` without `runId` shows
+the paused session plus all recent runs.
+
+While paused you can run tools by hand and then splice them into the sequence:
+
+```javascript
+replay({ action: 'history' })                    // required before inserting by index
+replay({ action: 'insert' })                     // show what's insertable
+replay({ action: 'insert', insertIndices: [42, 43], insertAfterStep: 3 })
+```
+
+By default `insert` creates a new sequence named `<name>-modified` (override
+with `newName`); pass `overwrite: true` to edit the sequence in place.
+
+### Closing Chrome Afterwards
+
+```javascript
+replay({ action: 'run', name: 'smoke-test', connectionReason: 'ci-run',
+         killChromeOnFinish: true })
+```
+
+`killChromeOnFinish` kills the browsers the run **owns**: its own (run-level)
+connection, plus every browser a `launchChrome` step actually created. It runs
+only after the run finishes - it is skipped on pause, breakpoint,
+click-validation failure or abort.
+
+Ownership is read from the launch itself, not guessed from the sequence: a
+`launchChrome` step against a reference that already exists hands back someone
+else's browser (`CHROME_CONNECTION_REUSED`), and those are left running - that
+is the long-lived instance you started by hand, and killing it would take state
+you cannot get back.
+
+For the same reason the kill is **skipped entirely when another live connection
+shares the port** — a `launchChrome` step normally opens a tab in the existing
+instance rather than a new process, so killing by port would take those
+browsers down too. The run says so instead: *"Chrome left running (port 9224
+also serves duo-member-two, killChromeOnFinish)"*. Disconnect or close the other
+connections first if you want the instance gone.
+
+### Preview Sequence
+
+```javascript
+replay({ action: 'get', name: 'login-flow' })
+// Shows: commands, substitutable variables, metadata, and run instructions
+```
+
+## Variables: Two Unrelated Mechanisms
+
+`replay` has two features that both get called "variables". They share nothing
+but the word.
+
+| | `variables` on `run` | `saveAs` + `{{var:...}}` |
+|---|---|---|
+| What it does | Replaces **recorded typed text** before the run | Captures a **value produced mid-run** for later steps |
+| Set where | A parameter of `replay({ action: 'run' })` | A param on an individual sequence step |
+| Read where | Only by `input({ action: 'type' })` steps | Any step param, via `{{var:name}}` |
+| Naming | Auto-generated `var_<i>_<selector>` keys | Names you choose |
+
+### 1. `variables` - substituting recorded typed text
+
+Every recorded `input({ action: 'type' })` step gets an auto-generated key of
+the form `var_<0-based step index>_<selector, non-alphanumerics replaced by _>`
+(or `var_<i>_text` when the step has no selector).
+
+```javascript
+// Original recording had: input({ action: 'type', selector: '#email', text: 'original@email.com' })
+replay({
+  action: 'run',
+  sequenceId: 'seq-login-flow',
+  connectionReason: 'test-session',
+  variables: {
+    'var_2_#email': 'new@email.com',
+    'var_3_#password': 'newpassword'
+  }
+})
+```
+
+**If the sequence contains any typed text and you omit `variables` entirely,
+`run` does not execute** - it returns a prompt listing the substitutable keys
+and their recorded values. Pass `variables: {}` to accept the recorded values
+as-is, or supply the keys you want to change.
+
+### 2. `saveAs` and `{{var:name.path}}` - capturing values mid-run
+
+A step can capture its own result into the run's variable store with `saveAs`.
+Later steps read it back with `{{var:name}}` / `{{var:name.path}}` in any
+param.
+
+Supported on exactly two tools today:
+
+| Step | What gets stored |
+|---|---|
+| `request` | the **whole response object** - address into it: `{{var:login.body.token}}` |
+| `inspect({ action: 'evaluateExpression' })` | the **evaluated value itself** - use it directly: `{{var:pairingUrl}}` |
+
+```json
+{ "tool": "request", "params": {
+    "url": "https://api.example.com/login", "method": "POST", "saveAs": "login" } }
+
+{ "tool": "inspect", "params": {
+    "action": "evaluateExpression",
+    "expression": "document.querySelector('#pair').href",
+    "saveAs": "pairingUrl" } }
+
+{ "tool": "navigate", "params": { "action": "goto", "url": "{{var:pairingUrl}}" } }
+
+{ "tool": "assert", "params": {
+    "left": "{{var:login.body.token}}", "operator": "exists" } }
+```
+
+Behaviour worth knowing:
+
+- A `saveAs` that cannot be honoured (unsupported tool, or a call that produced
+  nothing capturable) **fails the step**. It is never a silent no-op, because the
+  failure would otherwise surface far away as a confusing "no variable named ..."
+  message.
+- Async expressions work: a Promise returned by `evaluateExpression` is awaited
+  by default, so an async IIFE (IndexedDB read, `crypto.subtle`, `fetch`)
+  captures its **settled value**, not the Promise object. A rejection fails the
+  step with the expression's own error.
+- JSON-serializable results are captured **by value** (exact - a string `"42"`
+  stays a string). Values that only render as a description (`[HTMLDivElement]`,
+  `Array(3)`) come back as strings - capture a specific field, not a whole DOM
+  object.
+- The store is shared by reference across the whole run, including nested
+  `conditional` sequences and steps running on other connections, and it
+  survives a mid-run pause into `step`/`finish`.
+
+### Interpolation Tokens
+
+`{{var:...}}` and `{{timestamp}}` are resolved in a step's params immediately
+before it executes.
+
+- `{{timestamp}}` - milliseconds, computed **once per run** and reused by every
+  step (including later `step`/`finish` calls), so all steps agree on it.
+- `{{timestamp+3600000}}` / `{{timestamp-1000}}` - the same run timestamp with a
+  millisecond offset, for expiry-style fields.
+- `{{var:a.b.c}}` - dot-separated path. For a key containing a literal dot, use
+  bracket notation for that segment: `{{var:a.b['exec.t1.s2'].c}}`.
+- **Whole-string tokens keep their type.** `"right": "{{var:r.body.count}}"`
+  resolves to the number `3`; `"name": "kit{{timestamp}}"` resolves to the
+  string `"kit1699999999999"`.
+- An unresolvable token fails the step with a message telling you which
+  `saveAs` to add.
+
+## Per-Step Connections (Multi-Device Sequences)
+
+Any step may carry its own `connectionReason`. Steps that don't get the
+run-level connection injected (for the tools that accept one).
+
+```json
+{ "tool": "input",    "params": { "action": "click", "selector": "#pair",
+                                  "connectionReason": "device-a" } }
+{ "tool": "inspect",  "params": { "action": "evaluateExpression",
+                                  "expression": "document.querySelector('#code').textContent",
+                                  "saveAs": "code", "connectionReason": "device-a" } }
+{ "tool": "navigate", "params": { "action": "goto", "url": "{{var:code}}",
+                                  "connectionReason": "device-b" } }
+```
+
+A per-step connection is honoured for **everything wrapped around the step**,
+not just for dispatching it: pre/post-click state capture, click validation,
+navigation validation, typed-text validation, breakpoint/pause detection,
+failure diagnostics, and the wait for the *next* step's element (which follows
+the next step's connection). That is what makes "device A scans, device B
+confirms" work in a single run.
+
+Details:
+
+- Connection injection applies to `navigate`, `content`, `input`, `console`,
+  `network`, `dom`, `screenshot`, `storage`, `inspect`, `execution`,
+  `breakpoint`, `getSourceCode`, `detectModals`, `dismissModal`.
+- `request` is handled separately: it only receives a connection when the step
+  sets `destination: 'browser'`, so Node-targeted sequences never drag a Chrome
+  launch in.
+- Only the browser-only tools (the first group above) make a sequence
+  "need a connection" and trigger Chrome auto-launch. A Node-only debugging
+  sequence won't spuriously launch Chrome.
+### Recording a multi-connection sequence
+
+Recording **preserves** `connectionReason` (it used to be stripped, which meant
+a recorded two-browser sequence silently replayed in one). Pass it explicitly on
+**every** call while you drive the browsers, including the one that is already
+active, then `create` decides what to do with it:
+
+| Recording | `create` result |
+|---|---|
+| All steps on one connection | Hoisted off the steps, so the sequence stays portable and `run({ connectionReason })` still retargets it |
+| Genuinely spans connections | Kept per step |
+| **Mixed** — some steps named, others driven implicitly | Kept as-is, with a warning |
+
+The mixed case can't be resolved automatically: nothing knows which browser the
+bare steps belonged to, so hoisting could pin them to the wrong one. `create`
+says so in its output; re-record naming every step rather than shipping it.
+
+"Bare" means any step that would have the run-level connection injected — which
+includes the tools whose `connectionReason` is *optional* (`inspect`,
+`execution`, `storage`, `network`, `breakpoint`, `request`, `getSourceCode`),
+not just the browser-only ones. Those are the ones people actually leave off.
+`wait({ ms })` is a plain sleep and doesn't count; every other `wait` form does.
+
+A sequence can be both multi-connection **and** mixed, and that combination is
+the dangerous one: the bare steps land in a different browser depending on the
+run-level `connectionReason`, and the run reports success either way. `create`
+warns about both.
+
+### Inserting into an existing sequence
+
+`insert` splices history commands (which now carry their connection) into a
+sequence whose own steps had theirs hoisted off. To compare like with like it
+first re-stamps the hoisted connection — recorded on the sequence as
+`recordedConnection` — onto its bare steps, then re-normalizes the merged array:
+
+| Inserted steps came from | Result |
+|---|---|
+| The same browser as the sequence | Hoisted again — still portable |
+| A different browser | Every step made explicit, so the sequence is a real multi-connection one and the run-time existence check applies |
+
+Without that re-stamp the merge always looked "mixed" (one named reference plus
+the sequence's own bare steps), the hoist was skipped, and an ordinary
+same-browser insert silently left the sequence half-pinned to this session — so
+a later `run({ connectionReason })` split it across two browsers and passed.
+
+### Rebinding references at run time
+
+Recorded references are per-session, so a sequence recorded elsewhere needs its
+names mapped onto this session's:
+
+```javascript
+replay({
+  action: 'run',
+  sequenceId: 'duo-stock-propagation',
+  connections: { 'duo-member-two': 'my-second-browser' },
+})
+```
+
+Recorded name on the left, a reference from this session on the right. Both
+sides are sanitized, so spaced forms work. A key matching nothing in the
+sequence is rejected before anything runs, listing the references the sequence
+actually uses — a typo fails loudly instead of being ignored. "The sequence"
+includes any sequence reached through a `conditional` step, since a setup
+sequence normally lives behind one; when such a sub-sequence can't be resolved
+in memory the key is accepted rather than guessed at.
+
+A step naming a connection other than the run's is checked against the live
+session before it runs, whether or not the sequence spans several connections,
+so a missing browser fails as *"step 3 needs connection duo-member-two, which
+does not exist in this session"* instead of a generic "not connected to browser"
+from inside the tool.
+
+Mapping also renames the `reference` on `launchChrome` / `connectDebugger`
+steps; otherwise a mapped sequence would launch the recorded name and then drive
+a different one. Where a mapping renames a launch, it wins over the run-level
+`connectionReason`, which would otherwise rename it straight back.
+
+**Two recorded references cannot be mapped onto one browser.** That would run
+the whole multi-browser sequence in a single browser and report success — the
+original bug, re-entered through the API that exists to prevent it — so it is
+rejected before anything runs.
+
+The run-level connection is mapped too when it was *derived* from the sequence
+(e.g. from a `launchChrome` step) rather than passed explicitly; otherwise it
+would point at a reference that doesn't exist here and the `startUrl` navigation
+and cursor injection would silently no-op.
+
+`issues({ action: 'workOn' | 'resolve' })` accepts `connections` as well, so a
+multi-browser repro sequence attached to an issue can be replayed in a fresh
+session.
+
+### Declaring the browsers a sequence needs
+
+A multi-browser sequence can say which browsers it needs, instead of expecting
+whoever runs it to have launched them first. Set it with `declare`:
+
+```javascript
+replay({
+  action: 'declare',
+  name: 'duo-stock-propagation',
+  requiredConnections: [
+    { reference: 'duo-member-two', profile: 'device-a', role: 'the member who draws stock' }
+  ],
+  requiredSockets: ['/api/sync/socket'],
+})
+```
+
+Each list **replaces** its field and `[]` clears it — a declaration is a whole
+statement about the run, and merging would make "drop the second browser"
+unexpressible. Passing only one list leaves the other alone. The sequence is
+written back to the file it came from; a memory-only sequence waits for
+`export`. Declarations that cannot mean what they say (two references on one
+profile, a reference declared twice, a profile name that is not a safe
+directory segment, an empty socket pattern that would match every socket) are
+refused here rather than on the next run.
+
+It lands on the sequence next to `commands`:
+
+```json
+{
+  "name": "duo-stock-propagation",
+  "startUrl": "http://localhost:5173/",
+  "requiredConnections": [
+    { "reference": "duo-member-two", "role": "the member who draws stock",
+      "url": "http://localhost:5173/login" }
+  ],
+  "commands": [ ... ]
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `reference` | The reference the steps use |
+| `profile` | Named persistent Chrome profile to come up on (see below) |
+| `url` | Opened on launch (defaults to the sequence's `startUrl`) |
+| `forceNewInstance` | A separate browser process rather than a tab, default **true** — two identities sharing one browser share its storage, which defeats the point. Defaults to **false** when `profile` is set |
+| `role` | Why this browser exists, for the run summary |
+
+The run brings each one up before the first step. A reference already bound to
+a live browser is reused, so a browser you launched by hand is not duplicated,
+and a `connections` mapping wins over the declaration — the declaration
+supplies a default, it does not override where the caller points the steps. A
+browser that cannot be launched fails the run before any step executes, naming
+the reference and its role.
+
+The run **closes what it launched**, on every terminal outcome: completed,
+failed, and cancelled. A pause is the exception — those browsers are the state
+you stopped to inspect — but whatever ends the pause (`cancel`, `finish`, or
+stepping off the end) closes them then. Browsers that were already up are left
+alone, and a browser sharing its port with another live connection is left
+running too. The run says which it closed:
+
+```
+**Browsers closed** (declared and launched): duo-member-two
+```
+
+#### Declaring the device, not just the browser
+
+`profile` names a persistent Chrome profile (the same ones
+`launchChrome({ profile })` creates, under `~/.cdp-tools/profiles`):
+
+```json
+"requiredConnections": [
+  { "reference": "device-a", "profile": "device-a", "role": "the enrolled device" }
+]
+```
+
+The profile is the durable half. Its cookies, localStorage and IndexedDB —
+including non-extractable CryptoKeys — survive between runs, so a device
+enrolled once stays enrolled, while the reference is only a name for this
+session. Declaring the pair is what lets a saved multi-device sequence be re-run
+tomorrow without rewiring which reference means which device.
+
+Steps still address browsers by `connectionReason`. There is no per-step
+`profile`: a step names a browser, the declaration decides what that browser
+is.
+
+Two consequences worth knowing:
+
+- **A profile implies reuse.** Only one live Chrome may hold a profile, so
+  `forceNewInstance` defaults to `false` here — a Chrome already running that
+  profile *is* the browser the declaration wants, whatever reference it is
+  bound to. Set `forceNewInstance: true` explicitly if you really want a spawn
+  attempt.
+- **A profile-bearing reference cannot be rebound.** Elsewhere a `connections`
+  mapping wins over a declaration, because a declaration is only a default. A
+  profile is an identity claim: pointing `device-a` at another browser would run
+  device-a's steps somewhere that is not device-a and report success. The run is
+  refused instead. Two declarations naming the same profile are refused for the
+  same reason — they would be one browser wearing two names.
+
+Teardown kills the browser, never the profile: the directory is persistent, so
+the next run finds the device exactly as this one left it.
+
+### Saying what kind of sequence it is
+
+`tags` are free-form labels the suite runner selects on:
+
+```javascript
+replay({ action: 'declare', name: 'spine-09-retire-asset', tags: ['ui'] })
+replay({ action: 'declare', name: 'story-b1-pool',        tags: ['contract', 'slow'] })
+
+replay({ action: 'runAll', tags: ['ui'] })              // only those
+replay({ action: 'runAll', folder: 'spine', tags: ['ui'] })  // composes with folder
+```
+
+Several tags mean **any of**. Tags are lowercased, trimmed and de-duplicated on
+the way in — a tag is matched, not displayed, and `tags: ['UI']` skipping a
+sequence tagged `ui` would quietly run less than you asked for. Spaces are
+refused for the same reason: `slow ui` is ambiguous in a filter, `slow-ui`
+isn't.
+
+Every `runAll` reports the split, filtered or not:
+
+```
+runAll folder "tagcheck": 3 passed, 0 failed (1 contract, 1 ui, 1 untagged)
+```
+
+That line is the point of the feature. A suite of 43 sequences reporting "36
+passed" reads as interface coverage, and 14 of those may never issue an `input`
+step — `navigate` → `request` → `assert`, with the browser present only to hold
+the auth cookie. Good contract tests, but no UI regression can fail one of
+them. The split makes the balance visible on every run instead of on an audit.
+
+Folders can't carry this: they're already spoken for by scenario shape
+(`spine/`, `story/`, `_helpers/`), and a sequence has one folder but can
+legitimately be both `contract` and `slow`.
+
+### Declaring the sockets a sequence depends on
+
+`requiredSockets` is the same idea for transports: a list of URL substrings
+naming the WebSockets the sequence's assertions ride on. Set by the same
+action:
+
+```javascript
+replay({ action: 'declare', name: 'duo-stock-propagation',
+         requiredSockets: ['/api/sync/socket'] })
+```
+
+A sequence that declares them is checked whether or not the caller asks for it
+(`requireSockets: true` is only needed for a sequence that declares none). For
+each entry the run fails when a matching socket closed or hit frame errors
+while it executed, or when none is open at the end — including one that never
+opened at all, which no "is it up now" final assertion can catch. Closes the
+run did not cause are not blamed on it: a socket torn down with its target by a
+navigation, or hung up by the page itself, is normal.
+
+Match on the app's own path rather than the origin, so the declaration survives
+`baseUrl` retargeting. Dev-server sockets (Vite HMR and friends) simply go
+undeclared and are ignored.
+
+### repeat / runFromLog
+
+History retains the connection each command was recorded with, so both replay
+each command against its own connection by default. An explicit
+`connectionReason`:
+
+- **retargets** a batch that used a single connection (what the parameter has
+  always meant), and
+- is **refused** for a batch spanning several connections, since no single value
+  is honest there.
+
+It is deliberately not silently ignored — for a while it was, which broke a
+documented parameter with no signal at all.
+
+### Exported test code
+
+`outputFormat: 'playwright' | 'puppeteer'` gives each recorded connection its own
+page (`page`, `pageDuoMemberTwo`, …), with a header naming the browsers. A
+single-connection sequence generates exactly what it always did. Emitting every
+step against one `page` would relocate the same silent collapse into the
+exported test.
+
+The generators only know `navigate` and `input` steps. Anything else —
+`conditional`, `launchChrome`, `inspect`, `storage`, `wait`, `breakpoint` —
+becomes a `// [not generated]` comment naming the step, and a sequence where
+*nothing* could be generated exports a test that **throws** rather than an empty
+one that passes. A setup sequence made of a conditional and a launch has no
+Playwright equivalent at all; run it with `replay({ action: 'run' })` instead of
+exporting it.
+
+### Two deliberate non-behaviours
+
+- **A run-level `connectionReason` does not override a step's own.** The step
+  wins.
+- **A per-step reference that doesn't exist fails the step.** It never falls
+  back to the run-level connection.
+
+The second is the whole point. Falling back is what let a two-browser sequence
+replay in one browser and report success — the "member" steps ran in the owner's
+browser, the owner saw their own optimistic update, and a cross-user propagation
+assertion went green having never involved a second user.
+
+## Conditional Steps
+
+`conditional` is a virtual step tool: it is handled inside the executor, never
+appears in the tool list, and is exempt from tool-name validation.
+
+Not being a real tool, it is never recorded, so `create` and `insert` — which
+both build steps out of recorded history — cannot produce one. `addConditional`
+is its authoring action:
+
+```javascript
+replay({ action: 'addConditional',
+         name: 'checkout-flow',              // or sequenceId
+         condition: '{{selector:.cookie-banner}}',
+         thenSequence: 'dismiss-cookie-banner',
+         insertAfterStep: 2,                 // omit to append; 0 puts it first
+         comment: 'EU builds only' })        // optional
+```
+
+which stores the step as:
+
+```json
+{ "tool": "conditional", "params": {
+    "if": "{{selector:.cookie-banner}}",
+    "then": "dismiss-cookie-banner" } }
+```
+
+Rejected before the sequence is touched: a condition that doesn't parse, an
+unknown type, an uncompilable or over-long `url:matches` regex, a malformed
+`indexedDB` path, a `thenSequence` naming no known sequence or naming this one
+(which would recurse to `maxConditionalDepth`), an out-of-range
+`insertAfterStep`. Values holding a `{{var:...}}` token are skipped — they are
+substituted at run time.
+
+A sequence already saved on disk is rewritten in place; otherwise it waits for
+`export`. The response says which.
+
+`then` is the name of another sequence, loaded and run inline when the condition
+holds, and it shares the parent run's captured variables. A `launchChrome` step
+inside it is skipped when that reference is already connected, and run when it
+isn't - so a setup sequence spanning two browsers can create the second one.
+
+Which browser the sub-sequence's *bare* steps run in follows from that:
+
+| The nested `launchChrome` | Bare steps run in |
+|---|---|
+| **ran** (that browser didn't exist) | the browser it just launched |
+| **skipped** (already connected), or absent | the calling run's connection |
+
+That split is what makes both shapes work. A setup sequence is a launch plus
+bare steps (`create` hoists the connection off them), so its steps have to
+follow the browser it created - otherwise the run opens a browser, does the work
+in the *caller's* browser, and still reports success. A nested login sequence
+whose browser already exists keeps running in whatever browser called it. Steps
+that name their own `connectionReason` are unaffected either way.
+
+> **Two connections are not two devices.** A plain `launchChrome` reuses the
+> running instance and opens a *tab* in it, so both references share one profile
+> - one set of cookies, one localStorage, one IndexedDB. A duo test built that
+> way has a single device identity wearing two names, and a "does it propagate
+> to the other user" check passes without a second device ever existing. Give
+> the second browser its own `profile` (and `forceNewInstance: true`) when the
+> point of the test is that the two sides are genuinely separate:
+>
+> ```javascript
+> launchChrome({ reference: 'duo-member-two', profile: 'member', forceNewInstance: true })
+> ```
+>
+> `listConnections` shows the giveaway: same `port` means same instance and
+> therefore shared storage.
+
+Supported conditions:
+
+| Condition | True when |
+|---|---|
+| `{{selector:CSS}}` / `{{!selector:CSS}}` | element exists / doesn't |
+| `{{url:contains:STRING}}` | current URL contains the string |
+| `{{url:matches:REGEX}}` | current URL matches the regex |
+| `{{url:EXACT}}` | current URL equals the value |
+| `{{cookie:NAME}}` / `{{!cookie:NAME}}` | cookie exists / doesn't |
+| `{{localStorage:KEY}}` / `{{!localStorage:KEY}}` | key exists / doesn't |
+| `{{indexedDB:DB/STORE/KEY}}` / `{{!indexedDB:...}}` | that record exists / doesn't |
+| `{{indexedDB:DB/STORE}}` | the object store holds at least one record |
+
+An element that isn't on the page counts as *absent*, not an error, so
+`{{!selector:...}}` skips correctly. A malformed selector or a disconnected
+browser still fails the run. The page is probed once with no retry (precede an
+async marker with a `wait` step), and a hidden element counts as present.
+
+Every condition reads the tool's structured result, never its printed text, so
+stored *data* cannot answer a question about *structure*: a localStorage value
+of `"null"` (or one containing "not found") is present, an empty string is
+present, a cookie name matches exactly rather than as a suffix, and a URL
+containing a comma compares in full.
+
+A database or store that doesn't exist yet counts as *absent*, not as an
+evaluation error - that is the state a wiped profile is in, and the state a
+healing setup sequence exists to fix. A value that cannot be represented in
+JSON (a non-extractable `CryptoKey`, a `Blob`) still counts as present.
+Presence comes from the storage tool's structured result, not its printed text,
+so a record whose *value* happens to read "No record found for this key." is
+still present. A condition is written as text, so an all-digits key is probed as
+a string and then, if that misses, as a number - IndexedDB keys `42` and `"42"`
+are different keys.
+
+A condition is interpolated like any other step parameter, so a captured
+variable can drive it — `{{indexedDB:identity/keys/{{var:deviceId}}}}` after an
+earlier `inspect({ saveAs: 'deviceId' })`.
+
+A condition that is legitimately *not met* skips the nested sequence and the
+step counts as a success. A condition that cannot be *evaluated* (bad format,
+unknown type, invalid or over-long regex, tool error) fails the run.
+
+Nesting is capped by `replay.maxConditionalDepth` (default 10) and regexes by
+`replay.maxRegexLength` (default 500); both are `.cdp-tools/config.json`
+settings. Oscillating chains (A→B→A) are allowed up to the depth limit.
+
+## forEach Steps
+
+`forEach` is the second virtual step tool: handled inside the executor, never a
+registered tool, exempt from tool-name validation via `VIRTUAL_STEP_TOOLS`.
+
+```json
+{ "tool": "forEach", "params": {
+    "in": "{{var:shares}}",
+    "as": "share",
+    "do": "revoke-one-share",
+    "where": "item.name !== 'Employees'",
+    "maxItems": 50 } }
+```
+
+It exists because conditions are single-subject. `{{selector:X}}` answers "does
+X exist"; there is no condition that answers "what is there", so a sequence could
+provision a missing fixture but never remove an unexpected one. That asymmetry is
+what made shared-fixture suites drift.
+
+`in` resolves in one of two ways. `{{var:name}}` is a whole-string interpolation
+token, so **the run's normal param interpolation resolves it before the step is
+dispatched** and — because whole-string tokens preserve type — what the step
+receives is the captured array itself, not a string. `resolveForEachItems`
+therefore accepts an array directly; its string branches only matter for direct
+calls and for `{{selectorAll:CSS}}`, which is not a var token and arrives
+unresolved. `{{selectorAll:CSS}}` evaluates in the page and yields one plain
+descriptor per element (`index`, `text`, `id`, `className`, `href`, `value`) —
+DOM nodes cannot cross the CDP boundary.
+
+`where` is evaluated as JavaScript in the page with `item` and `index` in scope,
+**not** in the `{{...}}` condition grammar. A filter reads fields off an
+arbitrary object, which that grammar cannot express, and adding a second
+mini-language beside it would leave two half-expressive syntaxes. A `where` that
+throws fails the run rather than excluding the item, matching how an
+unevaluatable condition behaves.
+
+Per-iteration the item is written to the shared variable store under `as` (and
+its position under `<as>Index`). The store is shared by reference with nested
+runs, so bindings are replaced rather than scoped, and a body's own `saveAs`
+captures persist across iterations.
+
+Budget is the parent's *remaining* total, decremented per iteration, so a loop
+cannot extend the run's total the way a fresh copy would. Depth shares
+`maxConditionalDepth`: a loop body that loops is the same runaway risk as a
+conditional chain. `maxItems` (default 100) is a backstop, and hitting it is
+logged rather than silently truncating.
+
+An empty source is a success with `iterations: 0`, rendered as "N item(s) found,
+none ran" — a converge loop with nothing to do must not look like a broken
+selector.
+
+## Teardown Steps
+
+`CommandSequence.teardown` is an optional second command array, run by
+`runTeardown` after the main loop in `executeSteps` reaches a terminal state.
+
+Terminal means: all steps ran, a step failed, the run was aborted, or the total
+timeout expired. It explicitly does **not** include the pause paths — `stepTo`
+(detected as `targetEnd < commands.length` with nothing failed), an unexpected
+breakpoint, or a click-validation failure, which return early and never reach the
+teardown call. A paused run is not finished, and tearing down would destroy the
+state the user paused to inspect.
+
+Three deliberate departures from how nested sequences are otherwise run:
+
+| Property | Why |
+|---|---|
+| Own `teardownTimeout` (default 60s), not `totalTimeout` | The commonest reason a run needs cleanup is that it timed out. Drawing on the exhausted parent budget would skip teardown in exactly that case. |
+| The run's `AbortSignal` is not forwarded | `replay cancel` must stop the work, not the cleanup. A cancelled run is precisely one that has left something behind. |
+| Shares `ctx.variableStore` | Teardown revokes what setup minted, and the capturing step may have run long before the failure. |
+
+The synthetic sequence passed to the nested `executeSteps` call sets
+`teardown: undefined`; without it the teardown run reaches the same code and runs
+the teardown again, unboundedly.
+
+Results land on `ExecutionResult.teardownResults` / `teardownFailed` and are
+rendered in their own section — never merged into `results` or the
+successful/failed counts. A broken cleanup must not turn a passing run red, nor
+make a failing one look like it failed somewhere it did not.
+
+Teardown is best-effort by construction: a killed cdp-tools process takes any
+pending teardown with it. It reduces accumulation; it cannot guarantee a clean
+world, so assertions that depend on absence remain order-dependent regardless.
+
+## Debug-Aware Replay
+
+Replay handles debugging sequences specially.
+
+### Fresh callFrameId Replacement
+
+When replaying `inspect({ action: 'getVariables' })` with a recorded
+`callFrameId`, replay fetches the current call stack on that step's connection
+and swaps in a fresh ID.
+
+### Auto-Resume
+
+If the debugger is already paused when a run starts (or when checking an
+existing connection), replay resumes it first, so a leftover pause from a
+previous run can't stall the sequence.
+
+### Expected vs Unexpected Breakpoints
+
+Replay tracks breakpoints that the sequence itself sets (`breakpoint({ action:
+'set' })`), including ±1 line to absorb CDP's 0-based/1-based resolution. After
+each step it checks whether execution is paused:
+
+- paused at a breakpoint this sequence set → **keep going**;
+- paused anywhere else → **stop and report the breakpoint hit**, with the pause
+  location and the connection to inspect it on.
+
+### Debug State Output
+
+After a run that completed with no failures, if breakpoints are active or
+execution is paused, replay appends the current debug state:
+
+```
+## Debug State
+
+⏸️ **Execution paused** at http://localhost:3101/client.js:6
+
+**Next steps:**
+- Inspect call stack: `inspect({ action: 'getCallStack', connectionReason: '...' })`
+- Get variables: `inspect({ action: 'getVariables', connectionReason: '...', callFrameId: '<from call stack>' })`
+- Resume execution: `execution({ action: 'resume', connectionReason: '...' })`
+- Step over: `execution({ action: 'stepOver', connectionReason: '...' })`
+
+🔴 **1 active breakpoint**
+- List breakpoints: `breakpoint({ action: 'list', connectionReason: '...' })`
+```
+
+## Step Robustness
+
+Beyond click validation, each step gets some automatic help:
+
+- **Retries:** `input` `click` / `type` / `hover` retry up to 5 times, 500ms
+  apart, when the failure looks like "element not found" - enough for a
+  component that hasn't mounted yet.
+- **Element pre-wait:** after a `navigate` step or a click, if the next step is
+  an `input` with a selector, replay waits for that selector (5 tries, 500ms
+  apart) on the *next step's* connection.
+- **Navigation validation:** after every `navigate` step, replay checks the page
+  didn't land on `about:blank`, a `chrome-error://` page, an `ERR_*`, or a
+  "site can't be reached" title.
+- **Port check:** before navigating to a `localhost` URL (including the
+  sequence's `startUrl`), the port is checked and the run fails fast with a
+  clear message rather than loading an error page.
+- **Typed-text validation:** after `input({ action: 'type', selector })`, the
+  field's value (or `innerText` for contenteditable) is compared against what
+  was typed - exact match, or "ends with" when `append: true`.
+- **Recorded delays:** delays captured during interaction recording are replayed
+  (capped by `replay.maxDelayMs`, default 1000ms).
+
+These are best-effort niceties with short, fixed budgets. When a step
+genuinely depends on async work settling - a page load after `location.href`,
+a spinner clearing, an async probe writing a global - add an explicit `wait`
+step instead of relying on them.
+
+## Explicit Waits (`wait` steps)
+
+`wait` is a first-class sequence step for "the previous step kicked off async
+work". Exactly one of four mutually exclusive forms:
+
+```javascript
+{ tool: 'wait', params: { selector: 'button:has-text("Join")' } }  // element appears
+{ tool: 'wait', params: { selectorGone: '.spinner' } }             // element disappears
+{ tool: 'wait', params: { expression: 'window.__probe !== "PENDING"' } }
+{ tool: 'wait', params: { ms: 500 } }                              // fixed sleep, last resort
+```
+
+- The condition forms are polled **from the MCP side** as a synchronous check
+  (default `pollIntervalMs` 100, `timeoutMs` 15000). Because nothing waits
+  inside the page, a wait survives a navigation that happens mid-wait (each
+  poll simply runs in whatever document exists at that moment) and never
+  depends on in-page timers or promises resolving.
+- `expression` must be synchronous - don't `await` in it. Kick async work off
+  in a prior step, have it write a global, and wait on the global.
+- On timeout the step returns an error (`WAIT_TIMEOUT`, including the last
+  evaluation error if the predicate was throwing), which stops the sequence
+  like any other failed step. A `wait` never hangs a run.
+- The run-level `connectionReason` is injected like any other step, and a
+  per-step `connectionReason` is honoured (multi-device sequences).
+- `wait({ ms })` needs no browser at all and never triggers a Chrome
+  auto-launch; `wait({ expression })` also works against a Node.js target.
+
+## Click Validation
+
+Click steps validate their effects. When validation fails, the sequence pauses
+for inspection rather than failing outright.
+
+### What Gets Validated
+
+- **Console errors**: new errors after the click (default: enabled, fail mode `error`)
+- **Navigation**: if the click caused navigation, that it succeeded (default: enabled)
+- **DOM mutations**: whether the click changed anything (default: disabled)
+- **Network requests**: failed POST requests (default: disabled)
+
+New console warnings and logs are recorded as information only.
+
+### Pause on Failure
+
+When validation fails the sequence pauses **on the failed step** - the active
+sequence's cursor is rewound so the next `step` re-runs it. You can:
+
+- inspect the error state with `console`, `network`, `dom`, `screenshot`, ...
+- retry the failed step: `replay({ action: 'step', stepCount: 1 })`
+- run the rest: `replay({ action: 'finish' })`
+- abandon it: `replay({ action: 'cancel' })`
+
+There is no "skip this step" action - `step` always re-runs the step it is
+parked on.
+
+### Configuration
+
+Configure in `.cdp-tools/config.json` (values shown are the defaults):
+
+```json
+{
+  "clickValidation": {
+    "enabled": true,
+    "validateNavigation": true,
+    "requireDomChanges": false,
+    "domChangesFailMode": "warn",
+    "failOnConsoleErrors": true,
+    "consoleErrorsFailMode": "error",
+    "validateNetworkPayload": false,
+    "networkFailMode": "warn",
+    "postClickDelayMs": 100
+  }
+}
+```
+
+**Fail modes:**
+- `error`: pauses the sequence for inspection
+- `warn`: logs a warning and continues
+
+## Use Cases
+
+### Regression Testing
+
+```javascript
+// Record interactions directly - this call blocks until you click ✓ in the browser
+launchChrome({ reference: "checkout-test" })
+replay({ action: 'recordInteraction', connectionReason: 'checkout-test' })
+
+// Export as Playwright test
+replay({ action: 'export', name: 'checkout-test', format: 'playwright' })
+
+// Run anytime to verify
+replay({ action: 'run', name: 'checkout-test', connectionReason: 'test-run' })
+```
+
+### Debugging Workflows
+
+```javascript
+// Create a debug sequence from what you just did
+replay({
+  action: 'create',
+  name: 'debug-auth-bug',
+  description: 'Sets breakpoint on auth handler and triggers login',
+  expectedOutcome: 'Debugger pauses at auth.js:42 showing user object',
+  indices: [0, 1, 2, 3, 4, 5]
+})
+
+// Run to debug - debug state is shown automatically after the run
+replay({ action: 'run', name: 'debug-auth-bug' })
+```
+
+### Verifying the Same Flow on Two Deployments
+
+```javascript
+replay({ action: 'run', name: 'checkout', baseUrl: 'http://localhost:3000' })
+replay({ action: 'run', name: 'checkout', baseUrl: 'https://staging.example.com' })
+```
+
+### Cross-Device Handoff
+
+Hand-author steps with per-step `connectionReason` and capture the handoff value
+with `saveAs` - see [Per-Step Connections](#per-step-connections-multi-device-sequences).
+
+### Automation
+
+```javascript
+replay({
+  action: 'create',
+  name: 'daily-smoke-test',
+  description: 'Navigates key pages and checks for console errors',
+  expectedOutcome: 'All pages load without errors',
+  indices: [0, 1, 2, 3, 4, 5, 6, 7]
+})
+
+replay({ action: 'run', name: 'daily-smoke-test', killChromeOnFinish: true })
+```
+
+## Notes
+
+- **Recording:** only tool calls are recorded, not responses.
+- **Replay:** steps execute sequentially, and the run stops at the first failing
+  step.
+- **Persistence:** in-memory sequences are cleared on restart; use
+  `export`/`load` for disk persistence. `run` and `get` load from disk by name
+  automatically.
+- **Connection stripping:** `connectionReason` is removed from commands as they
+  are recorded into history, for portability.
+- **Validation timing:** tool *names* are validated at `create`/`load` time;
+  `run` does not re-validate, so a sequence edited on disk by hand is best
+  round-tripped through `load` before running.