test(e2e): event-based waits PR-4 — wait-timeout ratchet + flake harness

[intendednull]

Summary

PR-4 — final installment of the event-based-waits initiative (#454, #495, #496). No test migration; pure enforcement infrastructure:

1. Wait-timeout ratchet. scripts/check-wait-timeout-count.sh reads e2e/.wait-timeout-baseline (locked at the current count of 53) and fails CI if any PR introduces a new page.waitForTimeout in e2e/*.ts. Below-baseline counts pass with a hint to update the baseline file in the same PR. The script also enforces the spec's 2026-09-30 sunset cutoff — after that date, any spec still carrying an eslint-disable.*no-restricted-syntax header fails the gate, forcing the file-by-file migration tracked at e2e: migrate remaining specs to event-based waits #458 to complete.
2. Flake harness. just test-e2e-flake N=5 runs the Playwright suite N times in sequence and aggregates pass/fail per run. Default 5, override via N=10 etc. Not wired into check-all (heavy + non-deterministic per spec); opt-in for investigating intermittent failures.
3. README docs for both, in e2e/README.md.

The ratchet wires into just check-all after check-no-test-hooks-in-prod.sh so any regression fails the PR gate.

Spec: docs/specs/2026-04-27-event-based-waits-design.md §"Implementation phasing PR 4" + §"CI gate" + §"Sunset". Plan: docs/plans/2026-04-30-event-based-waits-pr4-ratchet-flake-harness.md. Tracking: #458.

Baseline correction during implementation

The plan stated 54 based on a grep -roh "waitForTimeout" e2e/ (no filter), which counted a documentation reference in e2e/README.md. The script correctly filters to *.ts files only. The committed baseline is 53 — this is the right number.

Self-review caught two blocking bugs (committed in eeed70f)

1. Script silent-aborts at sunset success. current=$(grep ... | wc -l) under set -euo pipefail would silently exit when grep found zero matches (which is the success state the migration is driving toward). When migration completes and zero waitForTimeout calls remain, grep returns 1 → pipefail propagates → set -e kills with no output → CI thinks the ratchet failed. Fix: brace-group the grep with || true so the exit code is absorbed before the pipe, giving current=0 correctly. Naive grep ... || true | wc -l won't work due to || having lower precedence than |.

2. @just setup-e2e invalid inside shebang recipe. test-e2e-flake uses #!/usr/bin/env bash, which makes the body one bash script. The @ prefix is a just line-attribute that only works in plain (non-shebang) recipes — under bash it's interpreted as a literal command name. The recipe would fail on first invocation with @just: command not found. Fix: replace with WILLOW_FEATURES="{{FEATURES}}" ./scripts/setup-e2e.sh mirroring the working pattern in the existing test-e2e-full recipe.

Both fixes verified locally:

• Zero-match self-test now reports current=0 instead of silently exiting 1.
• The flake recipe's setup line now matches the same shape as test-e2e-full.

Test plan

• ./scripts/check-wait-timeout-count.sh exits 0 with current=53 baseline=53 / ratchet ok
• Regression self-test (baseline=52, current=53): script exits non-zero with the "regressed" error block
• Below-baseline self-test (baseline=54, current=53): script exits 0 with the "note: ... below baseline" hint
• Zero-match self-test (using a pattern that doesn't exist): current=0 reported correctly (this exercises the post-sunset success path)
• git diff confirms the two fix-commit edits land where intended
• CI: just check-all FEATURES=test-hooks runs the full gate plus the new ratchet step. The flake recipe is not in check-all per spec — opt-in only.

What this completes

The four-PR initiative (spec) ships its full skeleton:

PR	Delivered
#454	test-hooks cargo feature: window.__willow pull API + __willowEvent push stream
#495	JS Peer wrapper, helpers split, pilot conversion of multi-peer-sync.spec.ts
#496	data-state lifecycle on 5 animated components, page.clock helper
#this	wait-timeout ratchet + flake harness + sunset enforcement

Remaining work is per-spec migration (5 specs still carry eslint-disable headers — cross-browser-sync, multi-peer-mobile, mobile-actions, permissions, mobile), tracked file-by-file via #458. The ratchet ensures each migration only ever decreases the count.

Out of scope (deferred)

• Migration of any of the 5 remaining specs.
• Adding the flake harness to check-all (explicitly opt-in per spec — heavy + non-deterministic).
• A separate ratchet for { timeout: 30_000 } overrides — the ESLint rule blocks new waitForTimeout calls already; the 30s overrides are a different convention. Defer until a regression case justifies it.

https://claude.ai/code/session_01AKogx2HEvgHw41aPHyp1Va

---

Generated by Claude Code