Add opt-in retry for caller-declared transient failures

[bigtiger]

Why

Users reported Perchfall flagging failures caused by "small timing errors" — a navigation that timed out by a hair, a connection reset, a server returning 5xx mid-restart. Runs were single-shot, so a one-off blip became a failed report (report.ok? == false) or a raised ScriptError — a false alarm.

What

Opt-in retry where the caller declares which conditions are retryable. Off by default — retries: 0 preserves today's single-shot behaviour exactly.

# Up to 2 extra attempts on load/script/5xx failures (the defaults)
Perchfall.run(url: "https://example.com", retries: 2)

Options

Option	Default	Notes
retries:	0	Additional attempts (N retries = N+1 attempts). Capped at 10.
retry_on:	[:load_error, :script_error, :server_error]	Array of named conditions or a predicate proc.
retry_backoff_ms:	250	Exponential backoff (250/500/1000…); 0 disables. Slot released while waiting.

Retryable conditions

Symbol	Matches	Default
:load_error	page failed to load (status: "error")	✅
:script_error	Errors::ScriptError (process failed)	✅
:server_error	HTTP 5xx	✅
:client_error	HTTP 4xx	off
:network_error	sub-resource net::ERR_*	off

JavaScript/console (assertion) errors are never retryable — they're real defects, not timing blips, and aren't in the valid set.

Key safety property

The symbol form is conservative: a run is retried only when every reason it failed is a declared condition. A transient 5xx that also carries a console error is not retried — the assertion failure would never clear, so it would just fail again after burning the backoff budget. ConcurrencyLimitError, InvocationError, ParseError, and ArgumentError are never auto-retried.

Implementation

• New pure Perchfall::RetryPolicy module classifies an outcome's failure reasons and decides retryability — testable with plain Report objects and exceptions, no browser/process needed.
• Client gains the options, an injected sleeper: (for fast deterministic tests), and a run_with_retries loop. Backoff sleeps outside the concurrency slot; each :query_bust retry uses a fresh _pf= timestamp.
• run! benefits automatically — raises PageLoadError only after retries are exhausted.

Docs / metadata

Version → 0.5.0, CHANGELOG, new ADR 0021, README, docs/configuration.md, docs/error-handling.md.

Non-goals

• No attempt count added to Report (keeps the value object + JSON schema untouched) — easy follow-up if a "passed after N retries" signal is wanted.

Testing

All 288 unit specs green (306 with RUN_JS_SPECS=true); no browser or Node required. New coverage: reason classification, all-reasons-opted-in rule, proc form, ScriptError retry, never-retry of non-transient exceptions, exponential backoff timing, and validation.