@broberg/lens-daemon 0.0.0-stage → 0.1.5

package/src/flow.ts

@@ -0,0 +1,2953 @@
+// F082 — Lens E2E flow executor.
+//
+// A "flow" is a manuscript: an ordered list of steps a repo commits, executed
+// by the daemon in ONE fresh authed Playwright page (state persists across
+// steps — that's what makes it End-to-End: log in, navigate, fill, submit,
+// assert the result). Every element is anchored on `data-testid` — never a CSS
+// guess — the same strict contract as the capture catalogue.
+//
+// Reuses the F074 foundation: withPage() for the authed context, authPrepare()
+// for the credential pre-step, takeShot() for per-step screenshots. A step that
+// throws stops the flow and pins a screenshot of the failure, so "create user"
+// failing at the submit button is obvious with the exact before-shot.
+
+import nodePath from 'node:path';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import type { Locator, Page } from 'playwright';
+import {
+  resolveTarget,
+  isEditableElement,
+  evalAssertBody,
+  noVerdictMessage,
+  type AssertOutcome,
+  type Target,
+} from '@broberg/lens-engine';
+import { withPage, type LensEngine } from './browser.ts';
+import { authPrepare, type AuthConfig, type AuthEnv } from './auth/index.ts';
+import { takeShot, settleForShot } from './capture.ts';
+import { runCritic, topFindingMessage, type CriticMode, type CriticReport } from './critic.ts';
+import { waitForBuild, observeBuild } from './build-marker.ts';
+import { fillAndVerify } from './fill.ts';
+import { fillSecret } from './secret-fill.ts';
+import { storagePayload, type StorageSeed } from './seed-storage.ts';
+import { passwordInUrl, type FilledPassword, type PasswordInUrlFinding } from './password-in-url.ts';
+import {
+  EDIT_EVENTS,
+  waitForListening,
+  waitForListeningOn,
+  readinessOfElement,
+  notListeningMessage,
+  type ReadinessResult,
+  type NotListeningFinding,
+} from './readiness.ts';
+
+/** F255.1 — how a click activates a button. See `clickAndActivate`. */
+export type ActivateMode = 'auto' | 'click' | 'enter';
+
+/** F009.121 — where a `fill` reads a SECRET from instead of carrying it inline:
+ *  a gitignored file (absolute, or relative to the run's local_path) or a daemon
+ *  env var. The value is read at run time and never echoed. */
+export type ValueFrom = { path: string } | { env: string };
+
+export type FlowStep =
+  // F074.51 — `timeout` was absent here while every other verb carried it, so a
+  // goto's 30s was unoverridable. Found by the typecheck of this card's own
+  // tests: normalising `timeout_ms` onto a step nobody reads would have shipped a
+  // NEW instance of the exact lie this card closes.
+  | { type: 'goto'; path: string; label?: string; timeout?: number }
+  // F074.23 — single-anchor locating steps accept EITHER a `testid` (string,
+  // resolved as [data-testid="…"], unchanged) OR a self-healing `target`
+  // (LocateSpec: testid|css|role|label|placeholder|text|vision), resolved
+  // through the ONE resolver in @broberg/lens-engine (shared with cloud runFlow
+  // so the self-heal priority can't drift). `target` is what lets the daemon
+  // drive testid-less sites (App Store Connect) same-IP. Exactly one is required.
+  // F255.1 — `activate` picks how a BUTTON is fired. 'auto' (default) clicks, and only
+  // if the click produced nothing observable falls back to focus+Enter; 'click' forces
+  // the old mouse-only behaviour; 'enter' skips straight to focus+Enter.
+  // F255.4 — `at` clicks a POINT inside the element ("50%,28%" or "40,120" px)
+  // instead of its centre, for canvas/3D surfaces where the centre hits nothing.
+  | { type: 'click'; testid?: string; target?: Target; label?: string; timeout?: number; activate?: ActivateMode; at?: string }
+  | { type: 'fill'; testid?: string; target?: Target; value?: string; valueFrom?: ValueFrom; label?: string; timeout?: number }
+  | { type: 'select'; testid?: string; target?: Target; value: string; label?: string; timeout?: number }
+  | { type: 'check'; testid?: string; target?: Target; label?: string; timeout?: number }
+  | { type: 'uncheck'; testid?: string; target?: Target; label?: string; timeout?: number }
+  | { type: 'waitFor'; testid?: string; target?: Target; label?: string; timeout?: number }
+  | { type: 'expectText'; testid?: string; target?: Target; text: string; match?: 'contains' | 'equals' | 'not-equals'; label?: string; timeout?: number }
+  | { type: 'expectVisible'; testid?: string; target?: Target; label?: string; timeout?: number }
+  // F236 — prove an element is editable RIGHT NOW (contenteditable nearest-ancestor
+  // wins + inherited counts, OR an enabled non-readonly input/textarea/select). The
+  // live-DOM complement to coverage(); @broberg/lens-engine 0.4.0's isEditableElement
+  // is the ONE shared "editable" definition (serialized into the page via evaluate).
+  | { type: 'expectEditable'; testid?: string; target?: Target; label?: string; timeout?: number }
+  | { type: 'expectAbsent'; testid: string; label?: string; timeout?: number }
+  // F074.59 — assert MOTION by observing it. Reading `animationName` off computed
+  // style proves a RULE EXISTS; it says nothing about whether the animation plays,
+  // and it reads identically in a browser that has stopped every animation. These
+  // two verbs measure the thing itself, and they are a matched pair on purpose:
+  // expectAnimating alone would pass on any element in a browser that animates
+  // everything, and expectStill alone would pass in one that animates nothing.
+  | { type: 'expectAnimating'; testid?: string; target?: Target; property?: string; label?: string; timeout?: number }
+  | { type: 'expectStill'; testid?: string; target?: Target; property?: string; label?: string; timeout?: number }
+  // F213.8 — gate on the page actually LISTENING, not merely painted. The
+  // browser owns form controls itself, so a write before the app's scripts
+  // attach lands in the DOM, reads back green, and is silently lost.
+  | { type: 'waitForReady'; testid?: string; target?: Target; events?: string[]; label?: string; timeout?: number }
+  // F213.9 — the POSITIVE form of "the overlay is gone". A negative assertion can
+  // always be green too early; this one cannot, because the target must EXIST and be
+  // what the browser would actually hit at its own centre.
+  | { type: 'expectTopmost'; testid?: string; target?: Target; label?: string; timeout?: number }
+  // F082.x (lens-gap 019eeec7) — frame-aware, CSS-selector steps for cross-origin
+  // surfaces a top-frame testid can't reach (e.g. Stripe's PCI card iframes).
+  // `frame` is one iframe selector or an outer→inner chain; absent = top frame.
+  | { type: 'fillSelector'; selector: string; value: string; frame?: string | string[]; label?: string; timeout?: number }
+  | { type: 'clickSelector'; selector: string; frame?: string | string[]; label?: string; timeout?: number; at?: string }
+  // F255.7 — block until the app serves the build under test. `sha` waits for THAT build;
+  // without it, for any build other than the one live when the step started.
+  | { type: 'waitForBuild'; sha?: string; label?: string; timeout?: number }
+  // Wait until the page URL contains this substring — the redirect-back assertion
+  // so a manuscript knows it left the 3rd party and is back on our origin.
+  | { type: 'waitForUrl'; url: string; label?: string; timeout?: number }
+  // F082.x (lens-gap) — DOM inspector: dump a frame's iframes/inputs/clickables
+  // (names, ids, roles, iframe titles, testids, text) so an author can discover
+  // the exact anchors on a 3rd-party page (Stripe's accordion + PCI iframes)
+  // WITHOUT raw Playwright. CSP-safe — a real fn injected by Playwright, never
+  // page-level eval (Stripe's strict CSP blocks new Function/eval).
+  // F389.2 — `html: true` returns the element's (or, without a testid, the page
+  // body's) full outerHTML instead of the anchor dump, so a built screen can be
+  // compared with its approved mockup (cardmem_check_mockup_fidelity).
+  | { type: 'inspect'; frame?: string | string[]; html?: boolean; testid?: string; label?: string; timeout?: number }
+  | { type: 'assert'; js: string; label?: string; timeout?: number }
+  | { type: 'screenshot'; label?: string }
+  // F213.2 — interaction verbs that make write-flows drivable end-to-end
+  // (paired with the F213.1 write-capable mint so the submit actually persists).
+  // clear: empty a field. press: a keyboard key on a testid (focused) or global
+  // (no testid) — Enter-to-submit, arrow-nav, autocomplete triggering. drag: a
+  // real HTML5 drag-and-drop from one testid to another (Playwright dragTo),
+  // for DnD features a synthetic-event assert can't cleanly drive (lens-gap 019f2438).
+  | { type: 'clear'; testid?: string; target?: Target; label?: string; timeout?: number }
+  | { type: 'press'; key: string; testid?: string; label?: string; timeout?: number }
+  | { type: 'drag'; testid: string; toTestid: string; label?: string; timeout?: number }
+  // F213.6 — uploadFile: set a fixture file on an input[type=file] (Playwright
+  // setInputFiles), INCLUDING a hidden input behind a custom "add photo" button.
+  // `path` is a repo-relative fixture path (sandboxed to local_path) or a data:
+  // URI; an array = a multi-file upload. Drives real add-photo/attach steps a DSL
+  // could not before (fd-sundhed skadefoto-flow, lens-gap 019f581a).
+  | { type: 'uploadFile'; testid: string; path: string | string[]; label?: string; timeout?: number }
+  // F213.3 — composite + control-flow verbs for FMC-level manuscripts.
+  // autocomplete: type into a field, wait for the suggestion list to render, then
+  //   pick a suggestion by visible text (pickText) or index (pickIndex) — a real
+  //   lookup→select, not a bare fill. `option` is the suggestion-item testid.
+  // capture: read an element's text (or an input's value, from:'value') into a
+  //   named var so a LATER step reuses it via {{name}} — passing data forward.
+  // conditional: run a child block only when `testid` is present (present:true →
+  //   'if') or absent (present:false → 'unless'), so a manuscript branches on page
+  //   state (a cookie banner, an optional step) without failing the whole run.
+  | { type: 'autocomplete'; testid: string; value: string; option: string; pickText?: string; pickIndex?: number; label?: string; timeout?: number }
+  | { type: 'capture'; testid: string; as: string; from?: 'text' | 'value'; label?: string; timeout?: number }
+  | { type: 'conditional'; testid: string; present: boolean; steps: FlowStep[]; label?: string; timeout?: number }
+  | { type: 'loop'; data: Array<Record<string, unknown>>; steps: FlowStep[]; label?: string; parallel?: number };
+
+export interface Flow {
+  name: string;
+  base_url: string;
+  /** Daemon-side auth pre-step (storageState / statePath / cookieJwt / mintEndpoint). */
+  auth?: AuthConfig;
+  /** Flags a flow that creates/changes data (create user, submit form). Surfaced
+   *  so a mutating flow against prod is an explicit, visible choice. */
+  mutates?: boolean;
+  /** F255.7 — gate the WHOLE flow on the deployed build being live: a sha to wait for, or
+   *  true to wait for any change from the build serving when the run starts. The common
+   *  case is "deploy, then verify everything", so it belongs on the flow, not per step. */
+  wait_for_build?: string | boolean;
+  /** F213.10 — how long, after the last verdict, to keep watching for the page
+   *  ejecting us. Default {@link DEFAULT_EJECT_GRACE_MS}; 0 opts out. Raise it
+   *  for an app whose auth check is slow (fd-sundhed's bounced at ~3.6s). */
+  eject_grace_ms?: number;
+  steps: FlowStep[];
+}
+
+/**
+ * MEASURED, not chosen. Against a fixture that bounces 800ms after load:
+ *
+ *     grace 1000  →  F.FF.F   caught 4 of 6
+ *     grace 1500  →  FFFFFF   caught 6 of 6
+ *     grace 3000  →  FFFFFF   caught 6 of 6
+ *
+ * The window is measured from when the goto RESOLVES, which is already later
+ * than the moment the page's own check started, so a window merely larger than
+ * the bounce is not enough — the margin gets eaten by that offset plus run
+ * variance. 1000ms left ~200ms of margin and lost a third of the time.
+ *
+ * A guard that catches two thirds is worse than no guard, because it teaches a
+ * reader that green means safe. 2000ms buys margin over the 1500 that was merely
+ * sufficient here, and it is still bounded.
+ *
+ * THIS IS NOT A UNIVERSAL NUMBER. fd-sundhed's app bounced at ~3.6s behind a
+ * splash screen; that one needs `eject_grace_ms: 5000` and no default would have
+ * caught it. What this default covers is the ORDINARY case — a token check that
+ * resolves as soon as the page has booted.
+ */
+export const DEFAULT_EJECT_GRACE_MS = 2000;
+
+/** F074.48 — one failed HTTP response, as the app sent it. */
+export interface FailedResponse {
+  method: string;
+  url: string;
+  status: number;
+  /** The body, capped and redacted. A stated marker when it could not be read —
+   *  "we did not look" and "there was nothing" must never look the same. */
+  body: string;
+}
+
+/** Cap per failing step. A flow against a chatty app must not turn its report
+ *  into a network log; the first few failures are what explain the step. */
+const MAX_FAILED_RESPONSES_PER_STEP = 5;
+/** Cap per body. Long enough for an error message, short enough that nobody
+ *  stores a page of HTML per step. */
+const MAX_BODY_CHARS = 600;
+
+/**
+ * F074.48 — strip obvious credential shapes from a captured error body.
+ *
+ * DEFENCE IN DEPTH, NOT A GUARANTEE, and the distinction is this week's lesson:
+ * a pattern list is a DENYLIST, so it will miss the shape nobody thought of. The
+ * real protection here is narrowness — only FAILED responses are read, capped at
+ * 600 chars, and flow results stay on the machine that ran the flow.
+ *
+ * There is no shared @broberg/* redactor to reuse: @broberg/apikey 0.1.0 exports
+ * generateKey/hashKey/verifyKey/makeKeyPreview and no redactor (checked, not
+ * assumed). Filed as a reuse gap; if one lands, this is deleted for it.
+ */
+export function redactBody(text: string): string {
+  return text
+    .replace(/\b(sk|pk|rk)-[A-Za-z0-9_-]{16,}/g, '$1-[REDACTED]')
+    .replace(/\b(pa|pi|piw|uk|trail|lens)_[A-Za-z0-9_-]{12,}/g, '$1_[REDACTED]')
+    .replace(/\bgh[pousr]_[A-Za-z0-9]{16,}/g, 'gh?_[REDACTED]')
+    .replace(/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g, '[REDACTED-JWT]')
+    .replace(/\b([Bb]earer\s+)[A-Za-z0-9._-]{16,}/g, '$1[REDACTED]')
+    .replace(/("(?:password|secret|token|api[_-]?key)"\s*:\s*")[^"]{4,}/gi, '$1[REDACTED]');
+}
+
+export interface FlowStepResult {
+  index: number;
+  type: string;
+  label: string;
+  status: 'pass' | 'fail' | 'skip';
+  testid: string | null;
+  detail: string | null;
+  /** PNG bytes for screenshot steps + the failing step (pinned for debugging). */
+  screenshot: Buffer | null;
+  /** F213.11 — milliseconds between the most recent navigation and the moment THIS
+   *  step started. NOT the step's own duration; the name says `after_navigation`
+   *  precisely because "elapsed" would be read as duration by the next person.
+   *
+   *  It exists because a write into a page that has not begun listening reads back
+   *  green and is silently lost (F213.8). sanne lost three runs' data that way and
+   *  spent them suspecting her own instrument. A step showing `fill @ 180ms` next to
+   *  a lost write answers that immediately.
+   *
+   *  Present on PASSING steps too, deliberately: a number that only appears on
+   *  failures cannot be used to investigate a run that passed for the wrong reason,
+   *  which is the entire premise of F213.8.
+   *
+   *  OPTIONAL on purpose. A SKIPPED step never started, so it has no such moment —
+   *  and stamping it with a number would say it ran. Absent means "did not run".
+   *  The engine-mapped cloud results (mapEngineFlowResult) also omit it: they report
+   *  per-step duration, not a navigation offset, and inventing one from a duration
+   *  would be a fabricated measurement — the exact class this field exists to expose.
+   *
+   *  F213.13 — AND IT IS ABSENT ON A `goto`. The clock only restarts once the goto
+   *  has finished, so a goto's own reading is measured from the PREVIOUS navigation
+   *  (for the first goto, from the start of the flow — i.e. browser launch). It is
+   *  a start, like every other reading, but against a different origin, so putting
+   *  it in the same column invites a subtraction that silently spans two clocks.
+   *  sanne hit this within an hour of the field going live (#21315): she read the
+   *  goto's number as the step's END and could not tell the two kinds apart. The
+   *  cure is to remove the trap, not to document it — the next person subtracts the
+   *  two numbers whatever a comment says. Absent here means "this step IS the
+   *  navigation", and every remaining reading shares one origin. */
+  ms_after_navigation?: number;
+  /** F213.13 — how long THIS step took, once it started. The companion to the
+   *  field above, and the pair is what makes a report answerable.
+   *
+   *  A step with waiting built into it (a click that retries actionability, a
+   *  waitFor) reports a start and then hides everything that follows: sanne could
+   *  say her `fill` was stamped 1119ms later when a click preceded it, but not when
+   *  the click itself actually landed inside its own step — so "a click waits long
+   *  enough" and "a click happens to wait long enough HERE" stayed undecidable.
+   *  start + duration closes that.
+   *
+   *  OPTIONAL for the same reason as above: a SKIPPED step has no duration. */
+  ms_step_duration?: number;
+  /** F126.7 — the FULL composition report for a screenshot step, on pass and on
+   *  fail. Previously the findings ended as a string carrying the count and the
+   *  first message; the rest were discarded, so a caller fixed the one issue it
+   *  was shown, re-ran, went green, and the unreported findings were silently
+   *  recorded as resolved. Same reason `network` exists two fields up: a report
+   *  that says less than the run measured, without saying so. */
+  critic?: CriticReport | null;
+  /** F074.48 — the FAILED HTTP responses that arrived while this step ran, with
+   *  the body the app actually sent. Present only on a FAILING step: on a passing
+   *  one it would be noise, and noise in a report is how people stop reading it.
+   *
+   *  pitch-vault (#20462/#20464) drove a write-flow with a read-only capture
+   *  principal. Our guard refused it correctly with
+   *  `403 {"error":"Lens capture sessions are read-only"}` — a fully
+   *  self-explaining answer — and the report showed only
+   *  "expected [data-testid=pitch-save] to be absent, but it is visible".
+   *  Fifteen minutes fault-finding an app that was working as designed.
+   *
+   *  The wire had the answer both times. The instrument dropped it. */
+  network?: FailedResponse[];
+  /** F074.29 — WHY this step failed, when the answer is "the probe was broken"
+   *  rather than "the app was wrong". Absent on an ordinary assertion failure.
+   *
+   *  Deliberately a SEPARATE field instead of a new `status` value: every
+   *  consumer that asks `status === 'fail'` (including this file's own
+   *  `anyFail`) must keep counting a broken probe as a failure. A new status
+   *  would have silently downgraded exactly the runs that deserve attention —
+   *  the same class of bug this whole story is about.
+   *
+   *  fd-sundhed's argument for surfacing it at all (#18586): "a throw is not a
+   *  slow truth, it is a broken instrument. Otherwise people learn to read
+   *  'threw' as 'not hydrated yet' and wait for something that never comes." */
+  fault?: 'instrument';
+}
+
+/** A failure caused by the PROBE, not by the app under test: an assert body that
+ *  cannot compile, or one that throws every time it runs. Carried as a distinct
+ *  error type so the recorder can label it without string-matching messages. */
+export class InstrumentError extends Error {
+  readonly fault = 'instrument' as const;
+  constructor(message: string) {
+    super(message);
+    this.name = 'InstrumentError';
+  }
+}
+
+export interface FlowResult {
+  name: string;
+  status: 'pass' | 'fail' | 'error';
+  steps: FlowStepResult[];
+  failed_at: number | null;
+  reason: string | null;
+  duration_ms: number;
+  /** F255.5 — the whole run as a .webm, present only when record:true was asked for.
+   *  Screenshots show states; this shows the MOTION between them. */
+  video?: Buffer | null;
+  /** F074.30 — the build sha this run was looking at, stamped at capture time.
+   *  NULL when the target exposes no marker. Never re-read later: asking after
+   *  the fact returns TODAY's build for an OLD recording. */
+  build?: string | null;
+  /** F074.36 — the URL the run ended on. NULL means not measured. Lets a reader
+   *  answer "which page was that verdict actually about?" after the fact. */
+  final_url?: string | null;
+  /** F074.99 — a password this run typed came back in the final URL. Null when
+   *  it did not, which is every ordinary run. Names the field and the parameter,
+   *  never the value. */
+  password_in_url?: PasswordInUrlFinding | null;
+  /** F074.99 part 1 — an edit verb wrote to a field on a page where nothing was
+   *  listening, or (state 'uninstrumented') the check could not run at all. Null
+   *  means no finding on a run that DID look; absent means a result from before
+   *  the check existed. Never fails the run — see the field's own type. */
+  not_listening?: NotListeningFinding | null;
+  /** F074.36 — set when a goto landed somewhere other than the path asked for,
+   *  e.g. an auth wall. Present on passing runs too (a silently rerouted green
+   *  run is precisely the case worth re-checking); only a FAILING run has it
+   *  prepended to `reason`. */
+  redirected?: string | null;
+  /** F074.36 — set when the applied credential cannot reach the target host at
+   *  all (cookies scoped elsewhere, or none). The SPA-proof half of the check:
+   *  an unauthenticated single-page app renders its login screen at the URL you
+   *  asked for, so the routing looks perfect and only the credential tells the
+   *  truth. Does NOT cover a well-scoped credential the server has expired. */
+  auth_reach?: string | null;
+  /** F213.10 — set when the page LOADED where we asked and then moved away on its
+   *  own, i.e. the run formed verdicts about a surface it was thrown off. Fails
+   *  the run: unlike a redirect, there is no reading of this that is benign. */
+  ejected?: string | null;
+  /** F074.59 — which motion state this run executed under.
+   *
+   *  THREE VALUES, NOT TWO. 'reduce' | 'no-preference' say what the browser was
+   *  told; ABSENT means an older run that predates the field, i.e. NOT RECORDED —
+   *  which is a different fact from "it ran under reduce" and must not be readable
+   *  as it. A green run that cannot say whether motion was on is uninterpretable,
+   *  and that ambiguity is exactly what left F144.23's animation criterion neither
+   *  provable nor disprovable. */
+  reduced_motion?: 'reduce' | 'no-preference';
+}
+
+export const STEP_TYPES = new Set([
+  'goto', 'click', 'fill', 'select', 'check', 'uncheck', 'waitFor',
+  'expectText', 'expectVisible', 'expectEditable', 'expectAbsent', 'expectTopmost', 'assert', 'screenshot', 'loop',
+  // F074.59 — motion assertions
+  'expectAnimating', 'expectStill',
+  'fillSelector', 'clickSelector', 'waitForUrl', 'inspect',
+  // F213.2 — interaction verbs
+  'clear', 'press', 'drag',
+  // F213.6 — file upload
+  'uploadFile',
+  // F213.3 — composite + control-flow verbs
+  'autocomplete', 'capture', 'conditional',
+  // F255.7 — gate on the deployed build actually serving
+  'waitForBuild',
+  // F213.8 — readiness gate (the page is listening, not just painted)
+  'waitForReady',
+]);
+
+/** Validate + normalise an untrusted flow (HTTP/MCP boundary). Throws on the
+ *  first structural problem — the daemon avoids a zod dep, so this is hand-rolled
+ *  in the same style as the other daemon request validators. */
+export function parseFlow(input: unknown): Flow {
+  const f = input as Partial<Flow>;
+  if (!f || typeof f !== 'object') throw new Error('flow must be an object');
+  if (typeof f.name !== 'string' || !f.name.trim()) throw new Error('flow.name is required');
+  if (typeof f.base_url !== 'string' || !/^https?:\/\//.test(f.base_url)) {
+    throw new Error('flow.base_url must be an http(s) URL');
+  }
+  if (!Array.isArray(f.steps) || f.steps.length === 0) throw new Error('flow.steps[] is required');
+  // F255.7 — a sha string or the boolean shorthand. Anything else is a typo that would
+  // otherwise silently disable the gate, which is the failure mode the gate exists for.
+  if (f.wait_for_build !== undefined && typeof f.wait_for_build !== 'string' && typeof f.wait_for_build !== 'boolean') {
+    throw new Error('flow.wait_for_build must be a commit sha (string) or true');
+  }
+  // F213.10 — same reasoning as wait_for_build, and it matters more here: a typo
+  // ("eject_grace" for "eject_grace_ms", a string "1000") would fall back to the
+  // default silently. That is survivable. But a NEGATIVE or NaN value would
+  // disable the guard while the author believes they raised it, and a guard
+  // believed-on-but-off is worse than one honestly off.
+  if (f.eject_grace_ms !== undefined && (typeof f.eject_grace_ms !== 'number' || !Number.isFinite(f.eject_grace_ms) || f.eject_grace_ms < 0)) {
+    throw new Error('flow.eject_grace_ms must be a non-negative number of milliseconds');
+  }
+  validateAndNormalizeSteps(f.steps);
+  return {
+    name: f.name.trim(),
+    base_url: f.base_url,
+    auth: f.auth,
+    mutates: f.mutates === true,
+    ...(f.wait_for_build !== undefined ? { wait_for_build: f.wait_for_build } : {}),
+    ...(f.eject_grace_ms !== undefined ? { eject_grace_ms: f.eject_grace_ms } : {}),
+    steps: f.steps as FlowStep[],
+  };
+}
+
+// F074.23 — light structural check for a self-healing `target` at the HTTP/MCP
+// boundary (the daemon stays zod-free in this validator; the engine's
+// resolveTarget does the real resolution at run time). A bare string is the
+// selector layer; an object must carry ≥1 locator layer and only known keys.
+const TARGET_KEYS = ['testid', 'css', 'role', 'name', 'label', 'placeholder', 'text', 'vision', 'nth', 'exact'];
+const TARGET_LAYERS = ['testid', 'css', 'role', 'label', 'placeholder', 'text', 'vision'];
+function isValidTarget(t: unknown): boolean {
+  if (typeof t === 'string') return t.length > 0;
+  if (!t || typeof t !== 'object' || Array.isArray(t)) return false;
+  const keys = Object.keys(t);
+  return keys.length > 0 && keys.every((k) => TARGET_KEYS.includes(k)) && TARGET_LAYERS.some((k) => k in (t as object));
+}
+
+/** F009.119 — the fields each step type uses, beyond the shared ones. Mirrors the
+ *  FlowStep union above; flow-step-fields.test.ts reads the union from source and
+ *  fails if the two drift. An unknown field is REFUSED: `inspect` with a guessed
+ *  `selector` used to run a whole-page dump in silence (cardmem, flow b62ffca3). */
+const SHARED_STEP_FIELDS = ['type', 'label', 'timeout', 'timeout_ms'];
+const TARGETED = ['testid', 'target'];
+export const STEP_FIELDS: Record<string, string[]> = {
+  goto: ['path'],
+  click: [...TARGETED, 'activate', 'at'],
+  fill: [...TARGETED, 'value', 'valueFrom'],
+  select: [...TARGETED, 'value'],
+  check: TARGETED,
+  uncheck: TARGETED,
+  waitFor: TARGETED,
+  expectText: [...TARGETED, 'text', 'match'],
+  expectVisible: TARGETED,
+  expectEditable: TARGETED,
+  expectAbsent: ['testid'],
+  expectAnimating: [...TARGETED, 'property'],
+  expectStill: [...TARGETED, 'property'],
+  waitForReady: [...TARGETED, 'events'],
+  expectTopmost: TARGETED,
+  fillSelector: ['selector', 'value', 'frame'],
+  clickSelector: ['selector', 'frame', 'at'],
+  waitForBuild: ['sha'],
+  waitForUrl: ['url'],
+  inspect: ['frame', 'html', 'testid'],
+  assert: ['js'],
+  screenshot: [],
+  clear: TARGETED,
+  press: ['key', 'testid'],
+  drag: ['testid', 'toTestid'],
+  uploadFile: ['testid', 'path'],
+  autocomplete: ['testid', 'value', 'option', 'pickText', 'pickIndex'],
+  capture: ['testid', 'as', 'from'],
+  conditional: ['testid', 'present', 'steps'],
+  loop: ['data', 'steps', 'parallel'],
+};
+
+function validateAndNormalizeSteps(steps: unknown[], depth = 0): void {
+  if (depth > 3) throw new Error('flow loops nested too deep (max 3)');
+  for (const [index, raw] of steps.entries()) {
+    const s = raw as FlowStep & Record<string, unknown>;
+    if (!s || typeof s !== 'object' || !STEP_TYPES.has(s.type)) {
+      // F074.50 — name the ones that DO exist. The list is rendered from
+      // STEP_TYPES itself, never a copy: a verb added tomorrow appears here
+      // without anyone editing this string. Two sessions lost time on one day to
+      // this message naming only the guess — pitch-vault hand-rolled synthetic
+      // KeyboardEvents while `press` already existed, and storeform concluded
+      // their OWN product could not branch while `conditional` already existed.
+      throw new Error(
+        `invalid step type: ${JSON.stringify((s as { type?: unknown })?.type)} — known: ${[...STEP_TYPES].join(', ')}`,
+      );
+    }
+    // F074.51 — accept `timeout_ms`, the name the rest of this wire teaches
+    // (session_id, state_path, base_url, and service.ts's own timeout_ms on the
+    // capture body). Until this line it was silently dropped and the caller got
+    // the default back inside a message confidently naming a number they never
+    // chose — storeform read that as "Play Console is slow" for two days.
+    //
+    // Normalising HERE rather than inside stepTimeout() is the load-bearing
+    // choice: THREE places read step.timeout directly (stepTimeout, the
+    // waitForBuild step, and the inspect probe), so a fix in the shared reader
+    // alone would leave two verbs still lying. One boundary, every verb, and
+    // nested loop/conditional steps too via the recursion below.
+    const alias = (s as { timeout_ms?: unknown }).timeout_ms;
+    if (typeof alias === 'number' && Number.isFinite(alias) && alias >= 0) s.timeout = alias;
+    if (s.type === 'goto' && typeof (s as { path?: unknown }).path !== 'string') {
+      throw new Error('goto step requires a string path');
+    }
+    if (s.type === 'loop') {
+      if (!Array.isArray((s as { data?: unknown }).data)) throw new Error('loop step requires data[]');
+      if (!Array.isArray((s as { steps?: unknown }).steps)) throw new Error('loop step requires steps[]');
+      validateAndNormalizeSteps((s as { steps: unknown[] }).steps, depth + 1);
+    }
+    // F213.3 — control-flow + composite verbs.
+    if (s.type === 'conditional') {
+      if (typeof (s as { present?: unknown }).present !== 'boolean') throw new Error('conditional step requires a boolean present');
+      if (!Array.isArray((s as { steps?: unknown }).steps)) throw new Error('conditional step requires steps[]');
+      validateAndNormalizeSteps((s as { steps: unknown[] }).steps, depth + 1);
+    }
+    if (s.type === 'autocomplete') {
+      if (typeof (s as { value?: unknown }).value !== 'string') throw new Error('autocomplete step requires a string value');
+      if (typeof (s as { option?: unknown }).option !== 'string') throw new Error('autocomplete step requires a string option testid');
+      const pt = (s as { pickText?: unknown }).pickText;
+      const pi = (s as { pickIndex?: unknown }).pickIndex;
+      if (typeof pt !== 'string' && typeof pi !== 'number') {
+        throw new Error('autocomplete step requires pickText (string) or pickIndex (number)');
+      }
+    }
+    if (s.type === 'capture' && typeof (s as { as?: unknown }).as !== 'string') {
+      throw new Error('capture step requires a string "as" name');
+    }
+    // F009.121 — a fill carries its value inline OR names where to read a secret
+    // from; never both (which one would win is a guess), never neither.
+    if (s.type === 'fill') {
+      const hasValue = typeof (s as { value?: unknown }).value === 'string';
+      const vf = (s as { valueFrom?: unknown }).valueFrom;
+      if (hasValue && vf !== undefined) throw new Error('fill step takes value OR valueFrom, not both');
+      if (!hasValue && vf === undefined) throw new Error('fill step requires a string value or valueFrom {path} | {env}');
+      if (vf !== undefined) {
+        const keys = vf && typeof vf === 'object' && !Array.isArray(vf) ? Object.keys(vf) : [];
+        const k = keys[0];
+        if (keys.length !== 1 || (k !== 'path' && k !== 'env') || typeof (vf as Record<string, unknown>)[k] !== 'string' || !(vf as Record<string, string>)[k]) {
+          throw new Error('fill valueFrom must be exactly one of {path: "<file>"} or {env: "<NAME>"}');
+        }
+      }
+    }
+    // F074.23 — single-anchor steps accept a string testid OR a self-healing
+    // `target` (LocateSpec); the rest still require a string testid.
+    const targetable = ['click', 'fill', 'select', 'check', 'uncheck', 'waitFor', 'expectText', 'expectVisible', 'expectEditable', 'expectTopmost', 'clear', 'waitForReady', 'expectAnimating', 'expectStill'];
+    // `expectAbsent` IS NOT MISSING FROM `targetable` BY OVERSIGHT — do not "fix"
+    // the asymmetry by moving it up. Measured 2026-08-18 with components: a
+    // LocateSpec resolves through the engine's resolveTarget, and their F071.4
+    // makes that resolver WAIT (a race over all layers against the caller's
+    // timeout) instead of taking an instant `count()` snapshot. Every positive
+    // verb wants that. `expectAbsent` is the one verb that must NOT have it:
+    // "prove this is gone" would then always cost the full timeout, and worse,
+    // the verb's meaning changes — it would be asserting on whatever the patient
+    // race eventually resolved, not on the element it was asked about.
+    // Staying testid-only keeps it on `page.locator(sel(testid))`, which is a
+    // plain locator this verb times itself (see the settle window below).
+    const testidOnly = ['expectAbsent', 'drag', 'autocomplete', 'capture', 'conditional', 'uploadFile'];
+    if (testidOnly.includes(s.type) && typeof (s as { testid?: unknown }).testid !== 'string') {
+      throw new Error(`${s.type} step requires a string testid`);
+    }
+    if (targetable.includes(s.type)) {
+      const hasTestid = typeof (s as { testid?: unknown }).testid === 'string';
+      const hasTarget = isValidTarget((s as { target?: unknown }).target);
+      if (!hasTestid && !hasTarget) {
+        throw new Error(`${s.type} step requires a string testid or a target (testid/css/role/label/placeholder/text)`);
+      }
+    }
+    // F255.1 — a typo'd activation mode must fail loudly, not silently fall back to 'auto'.
+    if (s.type === 'click') {
+      const a = (s as { activate?: unknown }).activate;
+      if (a !== undefined && a !== 'auto' && a !== 'click' && a !== 'enter') {
+        throw new Error("click step activate must be 'auto', 'click' or 'enter'");
+      }
+    }
+    // F255.4 — validate the `at` offset AT PARSE TIME, so a typo is a flow-authoring
+    // error rather than a mid-run surprise on step 12.
+    if (s.type === 'click' || s.type === 'clickSelector') {
+      const at = (s as { at?: unknown }).at;
+      if (at !== undefined) {
+        if (typeof at !== 'string') throw new Error(`${s.type} step "at" must be a string`);
+        parseAtOffset(at);
+      }
+    }
+    // F213.2 — drag needs a target testid; press needs a key (its testid is optional).
+    if (s.type === 'drag' && typeof (s as { toTestid?: unknown }).toTestid !== 'string') {
+      throw new Error('drag step requires a string toTestid');
+    }
+    if (s.type === 'press' && typeof (s as { key?: unknown }).key !== 'string') {
+      throw new Error('press step requires a string key');
+    }
+    // F213.6 — uploadFile needs a string path or a non-empty string[] of paths.
+    if (s.type === 'uploadFile') {
+      const p = (s as { path?: unknown }).path;
+      const ok = typeof p === 'string' ? p.length > 0 : Array.isArray(p) && p.length > 0 && p.every((x) => typeof x === 'string' && x.length > 0);
+      if (!ok) throw new Error('uploadFile step requires a non-empty string path or string[] path');
+    }
+    if ((s.type === 'fillSelector' || s.type === 'clickSelector') && typeof (s as { selector?: unknown }).selector !== 'string') {
+      throw new Error(`${s.type} step requires a string selector`);
+    }
+    if (s.type === 'fillSelector' && typeof (s as { value?: unknown }).value !== 'string') {
+      throw new Error('fillSelector step requires a string value');
+    }
+    if (s.type === 'waitForUrl' && typeof (s as { url?: unknown }).url !== 'string') {
+      throw new Error('waitForUrl step requires a string url');
+    }
+    const frameRef = (s as { frame?: unknown }).frame;
+    if (
+      frameRef !== undefined &&
+      typeof frameRef !== 'string' &&
+      !(Array.isArray(frameRef) && frameRef.every((x) => typeof x === 'string'))
+    ) {
+      throw new Error(`${s.type} step frame must be a string or string[]`);
+    }
+    // Checked LAST, so a step missing its required field keeps the message that
+    // names that field — the more useful one when both are wrong.
+    const allowed = [...SHARED_STEP_FIELDS, ...(STEP_FIELDS[s.type] ?? [])];
+    const unknown = Object.keys(s).filter((k) => !allowed.includes(k));
+    if (unknown.length > 0) {
+      throw new Error(
+        `step ${index} (${s.type}${depth > 0 ? `, nested depth ${depth}` : ''}): unknown field ${unknown.map((k) => JSON.stringify(k)).join(', ')} — ${s.type} accepts: ${allowed.filter((k) => k !== 'type').join(', ')}`,
+      );
+    }
+  }
+}
+
+/** Collect every data-testid a flow references — the flow-gate cross-checks
+ *  these against the repo's inventory (a missing anchor is a hard block). */
+export function flowTestIds(flow: Flow): string[] {
+  const ids = new Set<string>();
+  const walk = (steps: FlowStep[]) => {
+    for (const s of steps) {
+      if ('testid' in s && s.testid) ids.add(s.testid);
+      if (s.type === 'drag' && s.toTestid) ids.add(s.toTestid); // F213.2 — drag target anchor
+      if (s.type === 'autocomplete' && s.option) ids.add(s.option); // F213.3 — suggestion-list anchor
+      if (s.type === 'loop' || s.type === 'conditional') walk(s.steps); // F213.3 — conditional block
+    }
+  };
+  walk(flow.steps);
+  return [...ids];
+}
+
+// ── F082.5 — markdown manuscript → compiled flow ────────────────────────────
+//
+// A human-readable manuscript (fmc-automation style) compiles to the Flow JSON
+// the executor runs. Header lines set name/base/auth/mutates; each `- <verb>`
+// line is a step. testids are written in [brackets]. Grammar:
+//
+//   # flow: create-user
+//   base: https://staging.example.com
+//   mutates: true
+//
+//   - goto /signup
+//   - fill [email] = alice@example.com
+//   - select [role] = admin
+//   - check [agree]
+//   - click [submit]
+//   - waitFor [toast]
+//   - expectVisible [success]
+//   - expectText [success] ~ Account created
+//   - expectAbsent [error]
+//   - assert: return document.title.length > 0
+//   - screenshot after-submit
+//
+// Frame-aware CSS-selector steps (lens-gap 019eeec7) reach a cross-origin iframe
+// a [testid] can't (Stripe PCI fields). `@frame <a> >> <b>` nests outer→inner;
+// fillSelector's value delimiter is " = " (spaced) so it survives `[name="x"]`:
+//
+//   - fillSelector input[name="cardnumber"] = 4242 4242 4242 4242 @frame iframe[name^="__privateStripeFrame"]
+//   - clickSelector .SubmitButton @frame iframe[name^="__privateStripeFrame"]
+//   - waitForUrl /shop/receipt/
+//
+// Loops are indentation-based:
+//
+//   - loop parallel 4:
+//       data: [{"n":"Alice","r":"admin"},{"n":"Bob","r":"user"}]
+//       - goto /signup
+//       - fill [name] = {{n}}
+//       - select [role] = {{r}}
+//       - click [submit]
+//
+// `data:` is a JSON array; nested `- ` lines are the loop body; `{{field}}`
+// substitutes per row. `parallel N` runs iterations concurrently.
+//
+// F213.3 — composite + control-flow verbs (FMC-level manuscripts):
+//
+//   - autocomplete [city] = Cop -> [city-option] "Copenhagen"   (pick by text)
+//   - autocomplete [city] = Cop -> [city-option] #0             (pick by index)
+//   - capture [order-id] as orderId                             (element text → var)
+//   - capture [ref-field] as ref value                          (input .value → var)
+//   - fill [confirm-ref] = {{orderId}}                          (reuse a captured var)
+//
+//   - if [cookie-banner]:        # run the block only when the anchor is present
+//       - click [cookie-accept]
+//   - unless [logged-in]:        # run the block only when the anchor is absent
+//       - goto /login
+//
+// An `if`/`unless` block whose condition isn't met is SKIPPED (its child steps
+// report `skip`), so a manuscript branches on page state without failing the run.
+interface IndentLine {
+  indent: number;
+  text: string;
+}
+
+export function compileManuscript(md: string): Flow {
+  const headers: Record<string, string> = {};
+  const lines: IndentLine[] = md
+    .split('\n')
+    .map((l) => ({ indent: (l.match(/^\s*/)?.[0].length ?? 0), text: l.trim() }))
+    .filter((l) => l.text && !l.text.startsWith('//'));
+
+  let i = 0;
+  for (; i < lines.length; i++) {
+    const { text } = lines[i]!;
+    if (text.startsWith('-')) break;
+    if (text.startsWith('#')) {
+      const m = text.match(/^#\s*flow:\s*(.+)$/i);
+      if (m) headers.name = m[1]!.trim();
+      continue;
+    }
+    const h = text.match(/^(\w+)\s*:\s*(.+)$/);
+    if (h) headers[h[1]!.toLowerCase()] = h[2]!.trim();
+  }
+
+  // F074.34 — a `#` line AFTER the preamble is a comment, not a header and not a
+  // terminator. It used to end the step block: parseStepBlock breaks on any line
+  // that does not start with `-`, so a comment between two steps silently
+  // TRUNCATED the manuscript — the surviving prefix ran and the run reported
+  // PASS. fd-sundhed lost two asserts and a screenshot that way and got a green
+  // run for work that never executed (#18606). Comments appear in the most
+  // carefully written manuscripts, because that is where people explain WHY.
+  const stepLines = lines.filter((l, idx) => !(idx >= i && l.text.startsWith('#')));
+  const stepStart = stepLines.findIndex((l, idx) => idx >= 0 && l.text.startsWith('-'));
+  const [steps, consumedTo] = parseStepBlock(
+    stepLines,
+    stepStart < 0 ? stepLines.length : stepStart,
+    stepStart < 0 ? 0 : stepLines[stepStart]!.indent,
+  );
+
+  // F074.34 — and the general guard, which matters more than the comment fix:
+  // ANY line the parser did not consume now fails LOUDLY. Silent truncation is
+  // the one behaviour a verification tool must never have, because the result
+  // is a green run for steps that were never executed. This catches every
+  // future unrecognised syntax, not just `#`.
+  if (consumedTo < stepLines.length) {
+    const bad = stepLines[consumedTo]!;
+    throw new Error(
+      `manuscript line ${consumedTo + 1} was not understood and would have been silently dropped ` +
+        `(every step after it too): "${bad.text.slice(0, 80)}". Steps must start with "- ".`,
+    );
+  }
+
+  if (!headers.name) throw new Error('manuscript needs a "# flow: <name>" header');
+  if (!headers.base) throw new Error('manuscript needs a "base: <url>" header');
+  const flow: Flow = {
+    name: headers.name,
+    base_url: headers.base,
+    steps,
+    ...(headers.mutates === 'true' ? { mutates: true } : {}),
+  };
+  return parseFlow(flow); // reuse the structural validator
+}
+
+// Parse `- ` step lines at >= minIndent into FlowSteps, recursing into loop
+// blocks. Returns the steps + the index of the first line NOT consumed.
+function parseStepBlock(lines: IndentLine[], start: number, minIndent: number): [FlowStep[], number] {
+  const steps: FlowStep[] = [];
+  let i = start;
+  while (i < lines.length) {
+    const line = lines[i]!;
+    if (line.indent < minIndent || !line.text.startsWith('-')) break;
+    const body = line.text.replace(/^-\s*/, '');
+    // F213.3 — `if [anchor]:` / `unless [anchor]:` block; nested `- ` lines are
+    // the conditional body (same indentation grammar as loop).
+    const condM = body.match(/^(if|unless)\s+\[([^\]]+)\]\s*:?\s*$/i);
+    if (condM) {
+      const present = condM[1]!.toLowerCase() === 'if';
+      const testid = condM[2]!.trim();
+      const [childSteps, nextJ] = parseStepBlock(lines, i + 1, line.indent + 1);
+      steps.push({ type: 'conditional', testid, present, steps: childSteps });
+      i = nextJ;
+      continue;
+    }
+    const loopM = body.match(/^loop(?:\s+parallel\s+(\d+))?\s*:?\s*$/i);
+    if (loopM) {
+      const parallel = loopM[1] ? Number(loopM[1]) : undefined;
+      let j = i + 1;
+      let data: Array<Record<string, unknown>> = [];
+      // child non-`-` lines (data:) before the nested steps
+      while (j < lines.length && lines[j]!.indent > line.indent && !lines[j]!.text.startsWith('-')) {
+        const d = lines[j]!.text.match(/^data\s*:\s*(.+)$/i);
+        if (d) {
+          try {
+            data = JSON.parse(d[1]!);
+          } catch (err) {
+            throw new Error(`loop data is not valid JSON: ${err instanceof Error ? err.message : err}`);
+          }
+        }
+        j++;
+      }
+      const [childSteps, nextJ] = parseStepBlock(lines, j, line.indent + 1);
+      steps.push({ type: 'loop', data, steps: childSteps, ...(parallel ? { parallel } : {}) });
+      i = nextJ;
+      continue;
+    }
+    steps.push(parseManuscriptStep(body));
+    i++;
+  }
+  return [steps, i];
+}
+
+// F082.5 STRETCH — autonomous discovery: propose a candidate smoke-flow from a
+// project's route map (manifest surface paths) + their root [data-testid]
+// anchors, with no hand-written manuscript. A starting draft the author refines
+// (visit each route, assert its anchor is visible, screenshot). `surfaces` are
+// {path, testid} pairs the caller extracts from the manifest/inventory.
+export function proposeFlow(
+  name: string,
+  baseUrl: string,
+  surfaces: Array<{ path: string; testid: string }>,
+): Flow {
+  const steps: FlowStep[] = [];
+  for (const s of surfaces) {
+    steps.push({ type: 'goto', path: s.path });
+    steps.push({ type: 'expectVisible', testid: s.testid });
+    steps.push({ type: 'screenshot', label: s.testid });
+  }
+  if (steps.length === 0) throw new Error('no surfaces with a [data-testid] anchor to propose a flow from');
+  return { name, base_url: baseUrl, steps };
+}
+
+// Split a manuscript step's optional " @frame <a> >> <b>" suffix off. Returns
+// [mainPart, frameChain|null]; frames nest outer→inner, '>>'-separated.
+function splitFrame(s: string): [string, string[] | null] {
+  const at = s.search(/\s@frame\s/i);
+  if (at < 0) return [s, null];
+  const chain = s
+    .slice(at)
+    .replace(/^\s@frame\s/i, '')
+    .split('>>')
+    .map((x) => x.trim())
+    .filter(Boolean);
+  return [s.slice(0, at), chain.length ? chain : null];
+}
+
+/**
+ * F074.55 — the verbs the PROSE parser accepts, in the casing an author writes.
+ *
+ * Three repos have now reported a Lens verb as "missing" when it was present:
+ * pitch-vault hand-rolled synthetic KeyboardEvents rather than use `press`,
+ * storeform found the vocabulary by failing through four wrong guesses, and
+ * fd-sundhed reported `press` as absent. In every case the ability existed and
+ * there was no route to it — the tool description listed 9 of these by hand and
+ * the rejection message named none.
+ *
+ * An ability that exists and cannot be found costs the same as one that is
+ * missing, and it is worse on a board: nobody files a card about something they
+ * believe does not exist.
+ *
+ * This list is the ONE source. The rejection message and the MCP tool
+ * descriptions both read it, and a test fails if it disagrees with what the
+ * switch below actually accepts — in either direction.
+ */
+export const MANUSCRIPT_VERBS = [
+  'goto', 'click', 'fill', 'select', 'check', 'uncheck', 'clear',
+  'press', 'drag', 'upload', 'autocomplete',
+  'waitFor', 'waitForUrl', 'waitForBuild',
+  'expectText', 'expectVisible', 'expectEditable', 'expectAbsent', 'expectTopmost',
+  'fillSelector', 'clickSelector',
+  'inspect', 'assert', 'screenshot', 'capture',
+] as const;
+
+function parseManuscriptStep(s: string): FlowStep {
+  const testid = () => {
+    const m = s.match(/\[([^\]]+)\]/);
+    if (!m) throw new Error(`step "${s}" needs a [testid]`);
+    return m[1]!.trim();
+  };
+  const verb = s.split(/\s|\[|:/)[0]!.toLowerCase();
+  switch (verb) {
+    case 'goto':
+      return { type: 'goto', path: s.replace(/^goto\s+/i, '').trim() };
+    // F255.1 — `click [testid] via enter` / `via click` overrides the default 'auto'
+    // activation (click, then focus+Enter only if nothing observable happened).
+    // F255.4 — `click [testid] @ 50%,28%` clicks that point inside the element.
+    case 'click': {
+      const via = s.match(/\bvia\s+(auto|click|enter)\b/i);
+      const at = s.match(/@\s*(-?[\d.]+%?\s*[, ]\s*-?[\d.]+%?)\s*$/);
+      const step: FlowStep = { type: 'click', testid: testid() };
+      if (via) step.activate = via[1]!.toLowerCase() as ActivateMode;
+      if (at) step.at = at[1]!.trim();
+      return step;
+    }
+    case 'check': return { type: 'check', testid: testid() };
+    case 'uncheck': return { type: 'uncheck', testid: testid() };
+    case 'waitfor': return { type: 'waitFor', testid: testid() };
+    case 'expectvisible': return { type: 'expectVisible', testid: testid() };
+    case 'expecteditable': return { type: 'expectEditable', testid: testid() };
+    case 'expectabsent': return { type: 'expectAbsent', testid: testid() };
+    case 'expecttopmost': return { type: 'expectTopmost', testid: testid() };
+    case 'fill': {
+      // F009.121 — "fill [pw] from file <path>" / "from env <NAME>": the secret
+      // is read at run time, so the manuscript (and its label) never holds it.
+      const from = s.match(/\]\s+from\s+(file|env)\s+(\S.*)$/i);
+      if (from) {
+        const src = from[2]!.trim();
+        return { type: 'fill', testid: testid(), valueFrom: from[1]!.toLowerCase() === 'file' ? { path: src } : { env: src } };
+      }
+      const v = s.split('=').slice(1).join('=').trim();
+      return { type: 'fill', testid: testid(), value: v };
+    }
+    case 'select': {
+      const v = s.split('=').slice(1).join('=').trim();
+      return { type: 'select', testid: testid(), value: v };
+    }
+    case 'clear': return { type: 'clear', testid: testid() };
+    case 'press': {
+      // "press Enter" (global) or "press Enter [testid]" (on a focused element).
+      const hasTestid = /\[[^\]]+\]/.test(s);
+      const key = s.replace(/^press\s+/i, '').replace(/\s*\[[^\]]+\]\s*$/, '').trim();
+      if (!key) throw new Error(`press step "${s}" needs a key (e.g. "press Enter")`);
+      return { type: 'press', key, ...(hasTestid ? { testid: testid() } : {}) };
+    }
+    case 'drag': {
+      // "drag [source] -> [target]" (any two [testid]s in order).
+      const ids = [...s.matchAll(/\[([^\]]+)\]/g)].map((m) => m[1]!.trim());
+      if (ids.length < 2) throw new Error(`drag step "${s}" needs [source] and [target] testids`);
+      return { type: 'drag', testid: ids[0]!, toTestid: ids[1]! };
+    }
+    case 'upload': {
+      // "upload [input-testid] = <fixture>" — a repo-relative fixture path
+      // (test/fixtures/lens/…), a comma-separated list for a multi-file upload,
+      // or a single data: URI. F213.6.
+      const id = testid();
+      const rhs = s.split('=').slice(1).join('=').trim();
+      if (!rhs) throw new Error(`upload step "${s}" needs "= <fixture path>"`);
+      const parts = rhs.startsWith('data:') ? [rhs] : rhs.split(',').map((x) => x.trim()).filter(Boolean);
+      return { type: 'uploadFile', testid: id, path: parts.length === 1 ? parts[0]! : parts };
+    }
+    case 'autocomplete': {
+      // "autocomplete [input] = <typed value> -> [option] "<text>"" (pick by text)
+      // or "... -> [option] #<index>" (pick by nth suggestion).
+      const ids = [...s.matchAll(/\[([^\]]+)\]/g)].map((m) => m[1]!.trim());
+      if (ids.length < 2) throw new Error(`autocomplete step "${s}" needs [input] and [option] testids`);
+      const valM = s.match(/=\s*(.+?)\s*->/);
+      if (!valM) throw new Error(`autocomplete step "${s}" needs "= <value> -> [option]"`);
+      const tail = s.slice(s.lastIndexOf(']') + 1).trim();
+      const idxM = tail.match(/^#(\d+)/);
+      const textM = tail.match(/^"([^"]*)"/) ?? tail.match(/^'([^']*)'/);
+      const baseStep = { type: 'autocomplete' as const, testid: ids[0]!, option: ids[1]!, value: valM[1]!.trim() };
+      if (idxM) return { ...baseStep, pickIndex: Number(idxM[1]) };
+      if (textM) return { ...baseStep, pickText: textM[1]! };
+      throw new Error(`autocomplete step "${s}" needs a pick after [option]: "text" or #index`);
+    }
+    case 'capture': {
+      // "capture [testid] as <name>" (element text) or "... as <name> value" (input value).
+      const m = s.match(/^capture\s+\[([^\]]+)\]\s+as\s+(\w+)(\s+value)?\s*$/i);
+      if (!m) throw new Error(`capture step "${s}" needs "capture [testid] as <name> [value]"`);
+      return { type: 'capture', testid: m[1]!.trim(), as: m[2]!, ...(m[3] ? { from: 'value' as const } : {}) };
+    }
+    case 'expecttext': {
+      // F074.56 — the operator is REQUIRED, and the expected text may not be empty.
+      //
+      // This was `s.split('~').slice(1).join('~').trim()`, so a line WITHOUT a
+      // tilde produced text:"" and asserted "contains the empty string" — true of
+      // every element that exists. Reported by moovyy (#21738) and reproduced:
+      // `expectText [board-root] = <text nowhere on the page>` ran GREEN
+      // (e93303e6-9ab8-4fc5-8ebb-82e1431c6c87, label `⊇ ""`) while the same
+      // assertion with `~` failed correctly (25ad7063). The runner was sound; the
+      // parser dropped the expected text.
+      //
+      // Three spellings reached that no-op — an unrecognised operator, no operator
+      // at all, and a bare `~` — so all three are refused HERE, at compile time.
+      // A runtime warning on a run that still reports PASS is the defect in a hat.
+      const afterId = s.replace(/^expectText\s*/i, '').replace(/\[[^\]]*\]/, '').trim();
+      const m = /^(==|!=|~)([\s\S]*)$/.exec(afterId);
+      if (!m) {
+        throw new Error(
+          `expectText step "${s}" needs an operator: "~" (contains), "==" (equals exactly) or "!=" (differs). ` +
+            `Without one the expected text is dropped and the step passes on any element.`,
+        );
+      }
+      const text = m[2]!.trim();
+      if (!text) {
+        throw new Error(
+          `expectText step "${s}" has no expected text — that asserts the empty string, which passes on every element.`,
+        );
+      }
+      const match = m[1] === '~' ? 'contains' : m[1] === '==' ? 'equals' : 'not-equals';
+      return { type: 'expectText', testid: testid(), text, match };
+    }
+    case 'waitforurl':
+      return { type: 'waitForUrl', url: s.replace(/^waitForUrl\s+/i, '').trim() };
+    case 'fillselector': {
+      // Value delimiter is " = " (spaced) so it survives a CSS attribute
+      // selector like input[name="cardnumber"] that itself contains '='.
+      const [main, frame] = splitFrame(s);
+      const afterVerb = main.replace(/^fillSelector\s+/i, '');
+      const eq = afterVerb.indexOf(' = ');
+      if (eq < 0) throw new Error(`fillSelector step "${s}" needs " = <value>"`);
+      return {
+        type: 'fillSelector',
+        selector: afterVerb.slice(0, eq).trim(),
+        value: afterVerb.slice(eq + 3).trim(),
+        ...(frame ? { frame } : {}),
+      };
+    }
+    case 'clickselector': {
+      const [main, frame] = splitFrame(s);
+      return {
+        type: 'clickSelector',
+        selector: main.replace(/^clickSelector\s+/i, '').trim(),
+        ...(frame ? { frame } : {}),
+      };
+    }
+    case 'inspect': {
+      const [, frame] = splitFrame(s);
+      return { type: 'inspect', ...(frame ? { frame } : {}) };
+    }
+    case 'assert':
+      return { type: 'assert', js: s.replace(/^assert\s*:?\s*/i, '').trim() };
+    case 'screenshot':
+      return { type: 'screenshot', label: s.replace(/^screenshot\s*/i, '').trim() || undefined };
+    // F255.7 — `waitForBuild <sha>` or bare `waitForBuild` (any change from the live build).
+    case 'waitforbuild': {
+      const sha = s.replace(/^waitforbuild\s*/i, '').trim();
+      return { type: 'waitForBuild', ...(sha ? { sha } : {}) };
+    }
+    default:
+      // Naming the alternatives is the whole fix: the FLOW path has answered
+      // "known: …" since the earlier round of this class, and the prose path —
+      // the one we tell repos to start with — never got the same sentence.
+      throw new Error(
+        `unknown manuscript verb: "${verb}" in "${s}" — known: ${MANUSCRIPT_VERBS.join(', ')}`,
+      );
+  }
+}
+
+// The number of leaf steps a step-list expands to (a loop contributes
+// data.length × its body length). Used to pre-allocate a contiguous index block
+// per loop iteration, so the per-step report stays deterministically ordered
+// even when iterations run concurrently (F082.4 parallel workers).
+function flattenCount(steps: FlowStep[]): number {
+  let n = 0;
+  for (const s of steps) {
+    if (s.type === 'loop') n += s.data.length * flattenCount(s.steps);
+    else if (s.type === 'conditional') n += flattenCount(s.steps); // F213.3 — body counts once (run OR skipped, indices stay aligned)
+    else n += 1;
+  }
+  return n;
+}
+
+// Bounded-concurrency pool: run `tasks` with at most `limit` in flight.
+async function runPool(tasks: Array<() => Promise<void>>, limit: number): Promise<void> {
+  let cursor = 0;
+  const workers = Array.from({ length: Math.min(limit, tasks.length) }, async () => {
+    for (;;) {
+      const i = cursor++;
+      if (i >= tasks.length) return;
+      await tasks[i]!();
+    }
+  });
+  await Promise.all(workers);
+}
+
+function subst(str: string, vars: Record<string, unknown>): string {
+  return str.replace(/\{\{(\w+)\}\}/g, (_, k) => (k in vars ? String(vars[k]) : `{{${k}}}`));
+}
+
+const sel = (testid: string) => `[data-testid="${testid}"]`;
+const stepTimeout = (s: { timeout?: number }) => s.timeout ?? 8000;
+
+// F082.x (lens-gap 019eeec7) — resolve a CSS-selector locator that may live
+// inside a cross-origin frame chain. `frame` is one iframe selector or an
+// outer→inner chain; absent = the top frame. Playwright drives a real browser,
+// so it CAN type into a 3rd-party PCI iframe (Stripe card fields) that page-
+// context JS can't touch — that's the whole reason this primitive exists.
+function resolveLocator(page: Page, selector: string, frame?: string | string[]) {
+  const chain = frame == null ? [] : Array.isArray(frame) ? frame : [frame];
+  if (chain.length === 0) return page.locator(selector);
+  let fl = page.frameLocator(chain[0]!);
+  for (let i = 1; i < chain.length; i++) fl = fl.frameLocator(chain[i]!);
+  return fl.locator(selector);
+}
+
+// F074.23 — resolve a single-anchor step's Locator. A self-healing LocateSpec
+// `target` goes through the engine's ONE resolver (shared with cloud runFlow so
+// the self-heal priority can't drift); otherwise the classic [data-testid] path,
+// byte-identical to before. Returns the matched layer (resolved_via) for the
+// step report's audit trail (null on the testid path).
+// F071.4 (@broberg/lens-engine 0.8.0) — the resolver now WAITS, so it SPENDS the
+// caller's budget, and the verb after it must wait on what is LEFT.
+//
+// This is the whole point of the breaking signature, and getting it wrong here
+// would reproduce F074.51 inside its own fix: pass 2 burns `timeout_ms` racing
+// the layers, then a verb that also waits `timeout_ms` makes a caller who asked
+// for 5s wait 10 and be told 5. `remaining_ms` never reaches 0 — Playwright reads
+// `timeout: 0` as "wait forever", so the engine floors it at 1.
+//
+// The classic testid path costs nothing to resolve, so it hands the FULL budget
+// on: that path never waited, and must not start paying for a race it does not run.
+async function locate(
+  page: Page,
+  step: { type: string; testid?: string; target?: Target; timeout?: number },
+): Promise<{ loc: Locator; via: string | null; remaining: number }> {
+  const budget = stepTimeout(step);
+  if (step.target !== undefined) {
+    const r = await resolveTarget(page, step.target, { action: step.type, timeoutMs: budget });
+    return { loc: r.locator, via: r.resolved_via, remaining: r.remaining_ms };
+  }
+  return { loc: page.locator(sel(step.testid!)).first(), via: null, remaining: budget };
+}
+
+// A compact human label for a target (for step descriptions + failure messages).
+function targetSummary(t: Target): string {
+  if (typeof t === 'string') return t;
+  const layer = TARGET_LAYERS.find((k) => k in (t as Record<string, unknown>));
+  const val = layer ? (t as Record<string, unknown>)[layer] : '';
+  const name = (t as { name?: string }).name;
+  return `${layer ?? '?'}=${val}${name ? ` "${name}"` : ''}`;
+}
+
+/** How a step addressed its target, for a report. */
+function anchorOf(step: { testid?: string; target?: Target }): string {
+  if (step.testid) return `[data-testid="${step.testid}"]`;
+  return step.target ? targetSummary(step.target) : 'the field';
+}
+
+/** F074.99 — how long an edit verb waits for the page to start listening.
+ *
+ *  FAR shorter than the step timeout, and that is the whole posture. MEASURED
+ *  against fd-sundhed's A/B rig (same server, same port, two hostnames): a
+ *  hydrated page answers after 204/177/162ms, a dead one takes 8.3s to give its
+ *  verdict. A static form with five fills must not pay 40s to learn something
+ *  true about all five, so the wait gets its own budget and the write proceeds
+ *  either way. */
+const READINESS_BUDGET_MS = 1_000;
+
+/**
+ * F074.99 part 1 — ask the F213.8 probe whether anything is listening BEFORE an
+ * edit verb writes, and record the answer without acting on it.
+ *
+ * WHY THIS IS NOT A STEP THE AUTHOR TYPES. `waitForReady` has existed for a month
+ * and is correct; fd-sundhed had it written into their own memory and still got 12
+ * of 12 green steps over two empty fields. A check that depends on someone
+ * remembering it at the right moment is the person, not the check.
+ *
+ * WHY IT DOES NOT FAIL THE RUN. A plain HTML form, a server-rendered page and a
+ * static site all legitimately never listen. Reddening them would be a correction
+ * for some and a regression for others on the same day, and a gate that reddens
+ * working flows gets switched off rather than fixed. Escalating stays available as
+ * its own announced decision.
+ *
+ * THE WAIT IS NOT A COST IT ADDS. `fill` already waits for VISIBILITY, and the
+ * ~180ms measured above is how long hydration runs AFTER the element is visible —
+ * so today the write lands inside that window. This removes a race; it does not
+ * buy one.
+ */
+async function consultReadiness(
+  page: Page,
+  loc: Locator,
+  step: { testid?: string; target?: Target },
+  readySink?: NotListeningFinding[],
+): Promise<void> {
+  if (!readySink) return;
+  const url = safeUrl(page) ?? '';
+  // Once a page has answered, the other edit verbs on it skip the probe. One
+  // finding is what a reader acts on, and five identical ones would each cost the
+  // budget to say the same thing.
+  if (readySink.some((f) => f.url === url)) return;
+  const events = [...EDIT_EVENTS];
+  const anchor = anchorOf(step);
+  const r = await waitForListeningOn(
+    // Asked through the LOCATOR the verb is about to write to, not by re-querying
+    // a selector: a selector that matches several elements would probe one element
+    // and write to another, and the two answers would be about different things.
+    () =>
+      loc
+        .evaluate(readinessOfElement, events, { timeout: READINESS_BUDGET_MS })
+        .then((v) => v as ReadinessResult)
+        .catch(() => null),
+    anchor,
+    events,
+    READINESS_BUDGET_MS,
+  );
+  if (r.ok) return;
+  // 'no-element' is a selector problem, not a hydration one, and the verb's own
+  // wait reports it properly a moment later. Never answered at all → we have no
+  // verdict to report, and whatever stopped the probe will stop the write too, so
+  // the step fails loudly on its own rather than silently here.
+  if (!r.answered || (r.state !== 'not-listening' && r.state !== 'uninstrumented')) return;
+  readySink.push({
+    anchor,
+    url,
+    state: r.state,
+    waited_ms: r.waitedMs,
+    message: notListeningMessage(r.state, anchor, r.waitedMs, events),
+  });
+}
+
+function describe(step: FlowStep): string {
+  switch (step.type) {
+    case 'goto': return `goto ${step.path}`;
+    case 'assert': return `assert ${step.js.slice(0, 40)}`;
+    case 'screenshot': return step.label ?? 'screenshot';
+    case 'expectText': {
+      const sym = step.match === 'equals' ? '≡' : step.match === 'not-equals' ? '≢' : '⊇';
+      return `expectText ${step.testid ?? targetSummary(step.target!)} ${sym} "${step.text}"`;
+    }
+    case 'fillSelector': return `fillSelector ${step.selector}`;
+    case 'clickSelector': return `clickSelector ${step.selector}${step.at ? ` @ ${step.at}` : ''}`;
+    case 'waitForUrl': return `waitForUrl ${step.url}`;
+    case 'inspect': return step.html ? `inspect html${step.testid ? ` [${step.testid}]` : ''}` : step.frame ? 'inspect @frame' : 'inspect';
+    case 'drag': return `drag ${step.testid} → ${step.toTestid}`;
+    case 'uploadFile': return `upload ${Array.isArray(step.path) ? `${step.path.length} files` : (step.path.startsWith('data:') ? 'data:…' : step.path)} → ${step.testid}`;
+    case 'press': return `press ${step.key}${step.testid ? ` @${step.testid}` : ''}`;
+    case 'autocomplete': return `autocomplete ${step.testid} → ${step.pickText !== undefined ? `"${step.pickText}"` : `#${step.pickIndex}`}`;
+    case 'capture': return `capture ${step.testid} → {{${step.as}}}`;
+    case 'conditional': return `${step.present ? 'if' : 'unless'} [${step.testid}]`;
+    case 'loop': return 'loop';
+    case 'waitForBuild': return `waitForBuild${step.sha ? ` ${step.sha.slice(0, 8)}` : ' (changed)'}`;
+    // F255.4 — show the offset in the step label so a positioned click is
+    // recognisable in the report (a plain "click canvas" hides where it aimed).
+    case 'click':
+      return `click ${step.testid ?? targetSummary(step.target!)}${step.at ? ` @ ${step.at}` : ''}`;
+    default: {
+      const s2 = step as { testid?: string; target?: Target };
+      const anchor = s2.testid ?? (s2.target !== undefined ? targetSummary(s2.target) : '');
+      return `${step.type} ${anchor}`.trim();
+    }
+  }
+}
+
+function testidOf(step: FlowStep): string | null {
+  return 'testid' in step && step.testid ? step.testid : null;
+}
+
+/** F255.4 — parse an `at` offset: "50%,28%" (fraction of the element box) or "40,120"
+ *  (css pixels from its top-left). Mixed units are allowed ("50%,20"). Throws on garbage
+ *  so a typo fails the step instead of silently clicking the centre — a canvas click that
+ *  lands in the wrong place looks like "the app ignored me", the hardest bug to read. */
+/**
+ * F074.56 — the expectText comparison, as a pure decision.
+ *
+ * Lives here rather than inline in runFlow because the runtime path needs a
+ * browser and CI has none: a comparison nothing executes is the same defect this
+ * card is about, one file along.
+ *
+ * `equals` trims — the DOM adds surrounding whitespace, the author did not — and
+ * normalises nothing else. `not-equals` additionally REFUSES an empty actual:
+ * different-because-there-is-nothing is not proof of anything, and letting it
+ * pass would rebuild this card's own defect one level down.
+ */
+export function textMatches(
+  mode: 'contains' | 'equals' | 'not-equals',
+  actual: string,
+  want: string,
+): boolean {
+  const got = actual.trim();
+  if (mode === 'contains') return actual.includes(want);
+  if (mode === 'equals') return got === want;
+  return got !== '' && got !== want;
+}
+
+export function parseAtOffset(at: string): { x: number; y: number; xPct: boolean; yPct: boolean } {
+  const m = at.trim().match(/^(-?[\d.]+)(%?)\s*[, ]\s*(-?[\d.]+)(%?)$/);
+  if (!m) throw new Error(`click "at" must look like "50%,28%" or "40,120" — got "${at}"`);
+  const x = Number(m[1]);
+  const y = Number(m[3]);
+  if (!Number.isFinite(x) || !Number.isFinite(y)) throw new Error(`click "at" has a non-numeric coordinate: "${at}"`);
+  return { x, y, xPct: m[2] === '%', yPct: m[4] === '%' };
+}
+
+/** Turn an `at` offset into Playwright's element-relative click position (css px). */
+export async function positionFor(loc: Locator, at: string): Promise<{ x: number; y: number }> {
+  const o = parseAtOffset(at);
+  if (!o.xPct && !o.yPct) return { x: o.x, y: o.y };
+  const box = await loc.boundingBox();
+  if (!box) throw new Error('cannot resolve a percentage click position: the element has no box');
+  return {
+    x: o.xPct ? (box.width * o.x) / 100 : o.x,
+    y: o.yPct ? (box.height * o.y) / 100 : o.y,
+  };
+}
+
+/** F255.1 — is this target a button-like control? Only those get the Enter fallback:
+ *  radios, labels and links register fine with a native click. Must be a real function,
+ *  not a source string: Playwright evaluates a string as an EXPRESSION, so the arrow
+ *  source came back as an unserialisable function and the guard silently read false —
+ *  which is why the fallback never fired on the fixture that reproduces the bug. */
+function isButtonLike(el: Element): boolean {
+  const t = el.tagName.toLowerCase();
+  if (t === 'button') return true;
+  if (t === 'input') return ['submit', 'button', 'reset'].includes((el as HTMLInputElement).type);
+  return el.getAttribute('role') === 'button';
+}
+
+/** How long to watch for an effect before deciding the click was a silent no-op. Polled,
+ *  so a click that works costs only the first tick — not the whole window. */
+/** F213.9 — how long a page must have been up before "the element is not there" is
+ *  allowed to mean "it is gone" rather than "it has not mounted yet". Charged only
+ *  for the time the page has NOT already been up, so a late expectAbsent is free. */
+const ABSENCE_SETTLE_MS = 1200;
+const ACTIVATION_PROBE_MS = 700;
+const ACTIVATION_TICK_MS = 50;
+
+/** F255.1 — fire a button and make sure the activation actually TOOK.
+ *
+ *  Angular/MDC forms (Google Play Console and friends) do not run their save handler on a
+ *  synthetic mouse click: the click "succeeds", nothing persists, and a later Next stays
+ *  disabled because the form still holds unsaved changes. That is a silent false pass —
+ *  the worst failure mode a verification tool has, because the run goes green on a lie.
+ *  StoreForm proved the cure by hand (focus the button, press Enter); this makes it the
+ *  engine's job so no other repo has to rediscover it.
+ *
+ *  The fallback only fires when NOTHING observable happened: no DOM mutation, no network
+ *  request, no navigation, within ACTIVATION_PROBE_MS. That guard is what makes it safe to
+ *  have on by default — a Send/Pay button that DID work always trips at least one of those
+ *  three signals, so it can never be double-fired. `activate:'click'` opts out entirely.
+ *  Returns true when the Enter fallback was used (so a caller could surface it). */
+export async function clickAndActivate(
+  page: Page,
+  loc: Locator,
+  mode: ActivateMode,
+  timeout: number,
+): Promise<boolean> {
+  if (mode === 'enter') {
+    await loc.waitFor({ state: 'visible', timeout });
+    await loc.evaluate((el) => (el as HTMLElement).focus());
+    await page.keyboard.press('Enter');
+    return true;
+  }
+  if (mode === 'click') {
+    await loc.click({ timeout });
+    return false;
+  }
+
+  const buttonLike = await loc.evaluate(isButtonLike).catch(() => false);
+  if (!buttonLike) {
+    await loc.click({ timeout });
+    return false;
+  }
+
+  // Count only requests a BUTTON would plausibly cause. Counting every request made
+  // the guard useless: a page's favicon fetch alone was enough to look like "the click
+  // worked", so the fallback never fired on the very fixture that reproduces the bug.
+  let requests = 0;
+  const onRequest = (req: { resourceType: () => string }) => {
+    const t = req.resourceType();
+    if (t === 'xhr' || t === 'fetch' || t === 'document') requests += 1;
+  };
+  page.on('request', onRequest);
+  const urlBefore = page.url();
+  await page
+    .evaluate(() => {
+      const w = window as unknown as { __lensMut?: number; __lensMo?: MutationObserver };
+      w.__lensMut = 0;
+      w.__lensMo?.disconnect();
+      const mo = new MutationObserver((records) => {
+        w.__lensMut = (w.__lensMut ?? 0) + records.length;
+      });
+      // F255.9 — a MutationObserver does not cross shadow boundaries, so a click
+      // whose only effect is inside a web component read as a silent no-op and got
+      // a second activation (a switch toggled back). Observe every OPEN shadow root.
+      const opts = { subtree: true, childList: true, attributes: true, characterData: true };
+      const observe = (root: Document | ShadowRoot) => {
+        mo.observe(root instanceof Document ? root.documentElement : root, opts);
+        root.querySelectorAll('*').forEach((el) => {
+          if (el.shadowRoot) observe(el.shadowRoot);
+        });
+      };
+      observe(document);
+      w.__lensMo = mo;
+    })
+    .catch(() => {});
+
+  // F255.9 — focus moving is an effect too: a handler that hands focus elsewhere
+  // did something, and an Enter sent after it lands on the NEW element.
+  const focusBefore = await page.evaluateHandle(() => {
+    let a: Element | null = document.activeElement;
+    while (a?.shadowRoot?.activeElement) a = a.shadowRoot.activeElement;
+    return a;
+  });
+
+  let target: Awaited<ReturnType<Locator['elementHandle']>> | null = null;
+  try {
+    // F009.118 — take the handle BEFORE the click. Taken after, a button the click
+    // removed never resolves, and elementHandle() waited out Playwright's 30 s default
+    // before the catch turned it into null — every dialog-close click took 30 s.
+    target = await loc.elementHandle({ timeout }).catch(() => null);
+    await loc.click({ timeout });
+    const deadline = Date.now() + ACTIVATION_PROBE_MS;
+    for (;;) {
+      const mutations = await page
+        .evaluate(() => (window as unknown as { __lensMut?: number }).__lensMut ?? 0)
+        .catch(() => 1); // page navigated away → that IS an effect
+      if (mutations > 0 || requests > 0 || page.url() !== urlBefore) return false;
+      const focusMoved = await page
+        .evaluate(
+          ([before, clicked]) => {
+            let a: Element | null = document.activeElement;
+            while (a?.shadowRoot?.activeElement) a = a.shadowRoot.activeElement;
+            // The click itself focusing its own button is not an effect.
+            return a !== before && a !== clicked;
+          },
+          [focusBefore, target] as const,
+        )
+        .catch(() => false);
+      if (focusMoved) return false;
+      if (Date.now() >= deadline) break;
+      await page.waitForTimeout(ACTIVATION_TICK_MS);
+    }
+    // Nothing moved: DOM untouched, no request, same URL. This is the Angular/MDC
+    // silent no-op — activate the button for real.
+    await loc.evaluate((el) => (el as HTMLElement).focus());
+    await page.keyboard.press('Enter');
+    return true;
+  } finally {
+    page.off('request', onRequest);
+    await focusBefore.dispose().catch(() => {});
+    await target?.dispose().catch(() => {});
+    await page
+      .evaluate(() => {
+        const w = window as unknown as { __lensMo?: MutationObserver };
+        w.__lensMo?.disconnect();
+        w.__lensMo = undefined;
+      })
+      .catch(() => {});
+  }
+}
+
+/** Execute one step against the live page. Returns a screenshot Buffer only for
+ *  `screenshot` steps; throws on any failure (the caller pins a shot + stops). */
+/**
+ * F074.36 — did we end up somewhere we did not ask for?
+ *
+ * Returns a human sentence when the landed page differs from the requested one,
+ * else null. Deliberately compares ORIGIN + PATHNAME only: a query string or
+ * hash changing is routine (tracking params, SPA state) and says nothing, while
+ * a path change is the thing that makes a verdict be about the wrong page.
+ * Trailing slashes are normalised — `/board` and `/board/` are the same page.
+ *
+ * There is no vocabulary of login-page words here on purpose. "Does this look
+ * like a sign-in screen" is a guess about the world and would only ever find the
+ * shapes we already thought of; "you asked for X and got Y" is a measurement and
+ * works on an app we have never seen.
+ */
+function comparePaths(a: string, b: string): { from: string; to: string } | null {
+  let x: URL;
+  let y: URL;
+  try {
+    x = new URL(a);
+    y = new URL(b);
+  } catch {
+    return null; // not comparable — say nothing rather than guess
+  }
+  // `new URL` ACCEPTS about:blank, data:, blob: and chrome-error://. Their origin
+  // is the string "null" and the path is not a path, so comparing them yields
+  // gibberish — the first version of this reported "loaded nullblank, then moved
+  // to /login", which is a fabricated finding dressed as a measurement. Caught by
+  // the test below, and it is not hypothetical: about:blank is exactly what a page
+  // reads before its first navigation.
+  if (!/^https?:$/.test(x.protocol) || !/^https?:$/.test(y.protocol)) return null;
+  const norm = (u: URL) => `${u.origin}${u.pathname.replace(/\/+$/, '') || '/'}`;
+  const from = norm(x);
+  const to = norm(y);
+  return from === to ? null : { from, to };
+}
+
+export function redirectOf(requested: string, landed: string): string | null {
+  const d = comparePaths(requested, landed);
+  return d && `redirected: asked for ${d.from}, landed on ${d.to}`;
+}
+
+/**
+ * F213.10 — the page LOADED where we asked, then moved somewhere else on its own.
+ *
+ * A DIFFERENT FACT FROM `redirectOf`, and the two need different fixes, which is
+ * why they get different words. "Asked for X, landed on Y" is the server or the
+ * router refusing at the door — you look at the route. "Loaded X, then moved to
+ * Y" is the shape of every client-gated SPA auth failure: the shell is served to
+ * anyone, the client checks a token a beat later, and routes to /login. There the
+ * page is innocent and the IDENTITY was wrong, so a reader who is sent to debug
+ * the route wastes the afternoon.
+ *
+ * fd-sundhed (#21299) sharpened the precondition by measuring their own app and
+ * finding they were IMMUNE: their access check withholds the content, so an
+ * unauthorised run has nothing to photograph and simply times out. The vulnerable
+ * shape is specifically "the surface RENDERS, we assert, and we are THEN ejected"
+ * — a late redirect alone is not enough.
+ */
+export function ejectionOf(loaded: string, current: string): string | null {
+  const d = comparePaths(loaded, current);
+  return d && `ejected: loaded ${d.from}, then moved to ${d.to} without being asked — the verdicts above were measured on a page the run was thrown off (usually the wrong identity, not a broken page)`;
+}
+
+/**
+ * Steps that move the page ON PURPOSE. A URL change while one of these runs is
+ * the flow doing its job, never an ejection.
+ *
+ * THIS SET IS THE WHOLE CHECK. Without it the guard fires on every flow that
+ * clicks a link — which is every real flow — and a guard that cries on the
+ * common case is one people switch off, taking the rare true positive with it.
+ * When in doubt a verb belongs HERE: a missed ejection is a silent green, but a
+ * false ejection is a red on working software, and the second is what destroys
+ * trust in the instrument.
+ */
+const NAVIGATES_BY_DESIGN = new Set([
+  'goto', 'click', 'clickSelector', 'press', 'drag', 'autocomplete', 'uploadFile',
+  'waitForUrl', 'waitForBuild',
+  // Every one of these can route on a change handler: a search box that submits,
+  // a <select> that filters by URL, a checkbox that writes a query param.
+  'fill', 'fillSelector', 'clear', 'select', 'check', 'uncheck',
+]);
+
+/** `page.url()` throws once the page is closed. A URL we cannot read is "not
+ *  measured", never a difference — inventing one would manufacture an ejection
+ *  out of teardown. */
+function safeUrl(page: Page): string | null {
+  try {
+    return page.url();
+  } catch {
+    return null;
+  }
+}
+
+/** The line the set above draws, stated once: an ACTION may move the page, a
+ *  VERDICT may not. What is left over — the expect family, assert, screenshot,
+ *  waitFor — is exactly what forms an opinion about what is on screen, and an
+ *  opinion formed on a page we were then thrown off is the thing being removed. */
+const formsAVerdict = (type: string) => !NAVIGATES_BY_DESIGN.has(type);
+
+/**
+ * What does a URL change after a verdict step MEAN? Extracted as a pure function
+ * because the answer is a RULE, not a timing coincidence — and the first version
+ * of this got it wrong in the dangerous direction.
+ *
+ * MEASURED DEFECT (found reviewing my own diff, then reproduced): a click whose
+ * navigation commits LATER than the click step returns. `page.url()` read right
+ * after the click still shows the OLD page, so it became the baseline, and the
+ * next verdict step — now on the new page — was reported as an ejection.
+ *
+ *     navigation 400ms after the click    0/5 false ejections
+ *     navigation 1800ms after the click   5/5 FALSE EJECTIONS
+ *
+ * The 400ms case passed only because the click's own actionability wait happened
+ * to cover it. That is luck, not a guard, and it is exactly the accidental
+ * protection F213.8 warned against relying on.
+ *
+ * So a deferred navigation gets ONE free pass: if the flow performed a navigating
+ * action and the page has since moved, that is the action landing, and we
+ * re-baseline instead of accusing. `goto` is excluded from `navActionPending` by
+ * the caller — Playwright already waited for it, so its URL is settled and a
+ * later change really is someone else's doing.
+ *
+ * THE COST OF THIS, STATED: an auth bounce triggered BY a click is indistinguish-
+ * able from that click's own navigation, so the first change after an action is
+ * never reported. We keep the shape that matters — goto → assert, which is what a
+ * wrong identity looks like — and we never redden working software. A false
+ * ejection would get the whole guard switched off, taking the true positives with
+ * it; that trade is deliberate, not an oversight.
+ */
+export function classifyUrlChange(o: { loaded: string; current: string; navActionPending: boolean }):
+  { kind: 'none' } | { kind: 'flow-navigation'; rebaseTo: string } | { kind: 'ejection'; message: string } {
+  const message = ejectionOf(o.loaded, o.current);
+  if (!message) return { kind: 'none' };
+  if (o.navActionPending) return { kind: 'flow-navigation', rebaseTo: o.current };
+  return { kind: 'ejection', message };
+}
+
+/** Per-step carrier for the composition report. Explicit rather than a module
+ *  variable: two flows running at once would otherwise report each other's
+ *  findings, which is a worse failure than reporting none. */
+type CriticSink = { critic: CriticReport | null };
+
+/** F074.59 — the properties sampled to detect motion when a step does not name one.
+ *  Deliberately a SHORT list of things that actually move on screen: a wide sweep of
+ *  computed style picks up values that differ for reasons unrelated to animation
+ *  (a resize, a font settling) and turns a motion assertion into a flake. */
+const MOTION_PROPS = [
+  'opacity', 'transform', 'box-shadow', 'background-color', 'color',
+  'filter', 'width', 'height', 'left', 'top',
+] as const;
+
+export interface MotionSample {
+  /** Names of the animations/transitions the Web Animations API reports as
+   *  RUNNING on the element or its subtree, at the first instant. */
+  running: string[];
+  /** Properties whose computed value DIFFERED between the two instants. */
+  changed: string[];
+  /** What the BROWSER reports for prefers-reduced-motion — read from the page, not
+   *  from what we meant to ask for. That distinction is the whole point: if the
+   *  option plumbing breaks, this still tells the truth about the run, so the
+   *  failure message can name the real cause instead of restating the intent. */
+  reducedMotion: 'reduce' | 'no-preference';
+  /** How far apart the two samples were, in ms. Reported so a null result can be
+   *  read as "nothing moved in 200ms" rather than an unqualified "nothing moved". */
+  gapMs: number;
+}
+
+/** F074.59 — sample an element twice and report what moved.
+ *
+ *  TWO INDEPENDENT SIGNALS, because each one alone lies in a different direction:
+ *  getAnimations() sees a declared animation that is running but may be animating a
+ *  property with no visible effect; a computed-value diff sees real change but cannot
+ *  tell an animation from a one-off layout shift. Requiring BOTH for "animating" and
+ *  NEITHER for "still" is what makes the pair discriminating. */
+async function sampleMotion(
+  loc: Locator,
+  property: string | undefined,
+  gapMs: number,
+): Promise<MotionSample> {
+  const props = property ? [property] : [...MOTION_PROPS];
+  return (await loc.evaluate(
+    (el: Element, args: { props: string[]; gapMs: number }) =>
+      new Promise((resolve) => {
+        const read = (): Record<string, string> => {
+          const cs = getComputedStyle(el);
+          const out: Record<string, string> = {};
+          for (const k of args.props) out[k] = cs.getPropertyValue(k);
+          return out;
+        };
+        const running = (): string[] => {
+          const anyEl = el as Element & { getAnimations?: (o?: { subtree?: boolean }) => unknown[] };
+          if (typeof anyEl.getAnimations !== 'function') return [];
+          return anyEl
+            .getAnimations({ subtree: true })
+            .filter((a) => (a as { playState?: string }).playState === 'running')
+            .map((a) => {
+              const x = a as { animationName?: string; transitionProperty?: string };
+              return x.animationName ?? x.transitionProperty ?? 'animation';
+            });
+        };
+        const before = read();
+        const runningBefore = running();
+        const reduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches
+          ? 'reduce'
+          : 'no-preference';
+        setTimeout(() => {
+          const after = read();
+          resolve({
+            running: runningBefore,
+            changed: args.props.filter((k) => before[k] !== after[k]),
+            reducedMotion: reduced,
+            gapMs: args.gapMs,
+          });
+        }, args.gapMs);
+      }),
+    { props, gapMs },
+  )) as MotionSample;
+}
+
+/** F074.59 — the sampling window. Long enough that a slow keyframe (the 2.4s
+ *  breathing dot) changes a value inside it, short enough not to tax a flow. */
+const MOTION_SAMPLE_MS = 250;
+
+
+async function execStep(page: Page, step: FlowStep, base: string, vars: Record<string, unknown>, critic: CriticMode, localPath?: string, sink?: CriticSink, pwSink?: FilledPassword[], readySink?: NotListeningFinding[]): Promise<Buffer | null | { __inspect: string } | { __via: string; __build?: string; __redirect?: string }> {
+  switch (step.type) {
+    case 'goto': {
+      const p = subst(step.path, vars);
+      const url = /^https?:\/\//.test(p) ? p : `${base}${p.startsWith('/') ? p : `/${p}`}`;
+      // F098.6 — 'domcontentloaded' (not 'load'): a flow's explicit waitFor/
+      // expectVisible steps gate content; 'load' hangs on live-data/canvas SPAs.
+      // F074.51 — honour an explicit per-step timeout, but keep 30s as goto's own
+      // default rather than falling back to stepTimeout()'s 8s: a navigation is
+      // not an element wait, and silently cutting every flow's first hop from 30s
+      // to 8s would be a regression dressed as a fix.
+      await page.goto(url, { waitUntil: 'domcontentloaded', timeout: step.timeout ?? 30_000 });
+      // F074.36 — a goto that lands somewhere else used to report a bare PASS.
+      // It is the single most useful fact about a failing run (you asked for
+      // /board, an auth wall sent you to /), and it was thrown away. Reported as
+      // a step detail always; the run only LEADS with it when it also failed, so
+      // a legitimate redirect can never turn a green run red.
+      const landed = redirectOf(url, page.url());
+      return landed ? { __via: '', __redirect: landed } : null;
+    }
+    case 'click': {
+      const { loc, via, remaining } = await locate(page, step);
+      if (step.at) {
+        // F255.4 — a positioned click is aimed at a spot inside a canvas/3D surface,
+        // which is never a button, so it goes straight to a trusted Playwright click
+        // at that offset (no activation probe).
+        await loc.click({ timeout: remaining, position: await positionFor(loc, step.at) });
+      } else {
+        await clickAndActivate(page, loc, step.activate ?? 'auto', remaining);
+      }
+      return via ? { __via: via } : null;
+    }
+    case 'fill': {
+      const { loc, via, remaining } = await locate(page, step);
+      await consultReadiness(page, loc, step, readySink);
+      // F213.7 — fill proves its own write; a silent no-op or a prepended value
+      // used to pass as success, which is the half of the fleet save-rule this
+      // instrument could not perform.
+      if (step.valueFrom) {
+        await fillSecret(loc, step.valueFrom, localPath, remaining, pwSink, anchorOf(step));
+        return via ? { __via: via } : null;
+      }
+      const filledValue = subst(step.value ?? '', vars);
+      await fillAndVerify(loc, filledValue, remaining);
+      // F074.99 — remember a PASSWORD so the end of the run can notice it coming
+      // back in the URL. Read from the element rather than guessed from the name:
+      // a field called "password" may be a text input and a password field may be
+      // called anything, and only the element knows which it is. Failure to read
+      // it is not a failure of the fill — a report is not worth a red run.
+      if (filledValue.length > 0) {
+        const isPassword = await loc
+          .evaluate((el) => (el as HTMLInputElement).type === 'password')
+          .catch(() => false);
+        if (isPassword) pwSink?.push({ anchor: anchorOf(step), value: filledValue });
+      }
+      return via ? { __via: via } : null;
+    }
+    case 'select': {
+      const { loc, via, remaining } = await locate(page, step);
+      await consultReadiness(page, loc, step, readySink);
+      await loc.selectOption(subst(step.value, vars), { timeout: remaining });
+      return via ? { __via: via } : null;
+    }
+    case 'check': {
+      const { loc, via, remaining } = await locate(page, step);
+      await consultReadiness(page, loc, step, readySink);
+      await loc.check({ timeout: remaining });
+      return via ? { __via: via } : null;
+    }
+    case 'uncheck': {
+      const { loc, via, remaining } = await locate(page, step);
+      await consultReadiness(page, loc, step, readySink);
+      await loc.uncheck({ timeout: remaining });
+      return via ? { __via: via } : null;
+    }
+    case 'waitFor':
+    case 'expectVisible': {
+      const { loc, via, remaining } = await locate(page, step);
+      await loc.waitFor({ state: 'visible', timeout: remaining });
+      return via ? { __via: via } : null;
+    }
+    case 'expectEditable': {
+      // F236 — visible first (like expectText), then POLL the shared editability
+      // predicate until the step timeout. isEditableElement is pure + self-contained
+      // so it serializes into the page via loc.evaluate — ONE "editable" definition,
+      // identical to the engine's expectEditable flow-step. A present-but-not-editable
+      // target (e.g. click-to-edit that never armed the field) throws a named error.
+      const { loc, via, remaining } = await locate(page, step);
+      const anchor = step.testid ? `[data-testid="${step.testid}"]` : targetSummary(step.target!);
+      const timeout = remaining;
+      try {
+        await loc.waitFor({ state: 'visible', timeout });
+      } catch {
+        throw new Error(`${anchor} never became visible within ${timeout}ms`);
+      }
+      const deadline = Date.now() + timeout;
+      for (;;) {
+        const editable = await loc.evaluate(isEditableElement).catch(() => false);
+        if (editable) return via ? { __via: via } : null;
+        if (Date.now() >= deadline) {
+          throw new Error(`expected ${anchor} to be editable within ${timeout}ms, but it is present-but-not-editable`);
+        }
+        await page.waitForTimeout(150);
+      }
+    }
+    // F074.59 — the motion pair.
+    //
+    // WHY THESE EXIST: the fleet's house rules make a loading indicator mandatory on
+    // anything clickable that takes >100ms, and until now not one of them could be
+    // proven to move. Worse, the Lens browser has been reporting
+    // prefers-reduced-motion:reduce since F098.8 — set BY US — so any check that read
+    // an animation off computed style was reading a rule in a browser that had
+    // stopped playing it. A spinner that silently froze looked exactly like a pass.
+    //
+    // Both verbs report the browser's OWN prefers-reduced-motion in their failure
+    // message, read from the page rather than from the option we passed. If the
+    // plumbing that carries `reduced_motion` ever breaks, the message says
+    // "the run executed under reduce" instead of a mystery — an instrument that
+    // names why it could not see, rather than reporting that there was nothing there.
+    case 'expectAnimating':
+    case 'expectStill': {
+      const wantMotion = step.type === 'expectAnimating';
+      const { loc, via, remaining } = await locate(page, step);
+      const anchorName = step.testid ? `[data-testid="${step.testid}"]` : targetSummary(step.target!);
+      try {
+        await loc.waitFor({ state: 'visible', timeout: remaining });
+      } catch {
+        throw new Error(`${anchorName} never became visible within ${remaining}ms`);
+      }
+      const deadline = Date.now() + remaining;
+      let last: MotionSample | null = null;
+      for (;;) {
+        const m = await sampleMotion(loc, step.property, MOTION_SAMPLE_MS);
+        last = m;
+        const moving = m.running.length > 0 && m.changed.length > 0;
+        if (wantMotion && moving) {
+          return { __via: `${via ? `${via}; ` : ''}animating under ${m.reducedMotion}: ${m.running.join(', ')} changed ${m.changed.join(', ')}` };
+        }
+        // STILLNESS IS NOT PROVEN BY ONE LOOK, and it is not proven by the first
+        // look either — an animation with a delay starts later. So expectStill
+        // keeps sampling for the WHOLE window and fails the moment it sees motion;
+        // only an element that stayed still the entire time passes.
+        if (!wantMotion && moving) {
+          throw new Error(
+            `expected ${anchorName} to be STILL, but it is animating under prefers-reduced-motion: ${m.reducedMotion}` +
+              ` — running: ${m.running.join(', ') || 'none'}; changed: ${m.changed.join(', ') || 'none'}`,
+          );
+        }
+        if (Date.now() >= deadline) break;
+      }
+      if (!wantMotion) return via ? { __via: `${via}; still under ${last?.reducedMotion ?? 'unknown'}` } : { __via: `still under ${last?.reducedMotion ?? 'unknown'}` };
+      // The failure that matters: say WHICH signal was missing and, above all,
+      // whether this browser was even allowed to animate.
+      const m = last!;
+      const why =
+        m.reducedMotion === 'reduce'
+          ? ` THE RUN EXECUTED UNDER prefers-reduced-motion: reduce, which is the Lens default (F098.8) — pass reduced_motion:'no-preference' to see motion at all.`
+          : ` The run executed under prefers-reduced-motion: no-preference, so the browser WAS allowed to animate — this is a real stillness.`;
+      throw new Error(
+        `expected ${anchorName} to be ANIMATING within ${remaining}ms, but in ${m.gapMs}ms samples` +
+          ` the Web Animations API reported running: [${m.running.join(', ')}] and these computed properties changed: [${m.changed.join(', ')}].` +
+          why,
+      );
+    }
+    // F213.8 — the readiness gate. Not a sleep: it asks whether anything is
+    // registered for the events an edit dispatches, anywhere on this element's
+    // propagation path. sanne's workaround was `assert performance.now() > 3000`,
+    // which is green on a fast machine and red in CI — the failure mode replaced.
+    case 'waitForReady': {
+      const cssFor = (): string => {
+        if (step.testid) return sel(step.testid);
+        const t = step.target;
+        if (typeof t === 'string') return t;
+        if (t && typeof t === 'object') {
+          if (typeof (t as { css?: string }).css === 'string') return (t as { css: string }).css;
+          if (typeof (t as { testid?: string }).testid === 'string') return sel((t as { testid: string }).testid);
+        }
+        // A role/label/text LocateSpec has no CSS form, and silently probing
+        // something else would answer a different question than the one asked.
+        throw new Error('waitForReady needs a testid or a css/testid target — a role/label/text target has no selector form to probe');
+      };
+      const events = step.events?.length ? step.events : [...EDIT_EVENTS];
+      const r = await waitForListening(page, cssFor(), events, stepTimeout(step));
+      if (!r.ok) throw new Error(r.error);
+      return { __via: `listening via ${r.via} after ${r.waitedMs}ms` };
+    }
+    case 'expectAbsent': {
+      // F213.9 — "not mounted YET" and "correctly gone" used to be the same green.
+      // This was a one-shot count, so it passed the instant a component had not
+      // hydrated. fd-sundhed measured their splash guard green at 654ms and 1731ms
+      // on a splash that arrived at 2967ms and covered the screen until 5287ms.
+      //
+      // The irony was in this same file: expectText already POLLS precisely because
+      // a one-shot read races hydration. That insight had only ever been applied to
+      // the POSITIVE verbs, where the race fails RED. Here the identical race fails
+      // GREEN, which is the direction nobody investigates.
+      //
+      // THE SETTLE WINDOW COSTS NOTHING ON A PAGE THAT HAS ALREADY BEEN UP. The
+      // element has had `performance.now()` milliseconds to appear already, so we
+      // only wait for the REMAINDER — an expectAbsent late in a flow is free, and
+      // only one placed immediately after a goto pays. Without that, every flow gets
+      // slower, and a verb that taxes you is one authors stop using.
+      // THE REACH OF THIS VERB (F213.8's rule — state the limit beside the check):
+      // a green expectAbsent proves the element was not visible during the settle
+      // window. It does NOT prove it will never appear — a component that mounts
+      // AFTER the window still passes. If you need "it is gone and stays gone", use
+      // expectTopmost on the thing you actually want, which cannot be green early.
+      const settle = step.timeout ?? ABSENCE_SETTLE_MS;
+      const upFor = await page.evaluate(() => performance.now()).catch(() => settle);
+      const remaining = Math.max(0, settle - upFor);
+      const loc = page.locator(sel(step.testid));
+      if (remaining > 0) {
+        try {
+          await loc.first().waitFor({ state: 'visible', timeout: remaining });
+        } catch {
+          // never appeared within the window → genuinely absent
+        }
+      }
+      const count = await loc.count();
+      if (count > 0 && (await loc.first().isVisible())) {
+        // Name WHICH of the two it is: a caller needs to know whether it never went
+        // away or arrived late, because those have different fixes.
+        const late = upFor < settle ? ' (it appeared while we waited for the page to settle)' : '';
+        throw new Error(`expected [data-testid="${step.testid}"] to be absent, but it is visible${late}`);
+      }
+      return null;
+    }
+    case 'expectTopmost': {
+      // F213.9 — fd-sundhed's cure, and it generalises: ask whether the WANTED thing
+      // is there and on top, not whether the unwanted thing is gone.
+      //
+      //   target not in the DOM yet      → RED
+      //   an overlay covers it           → RED
+      //   it exists and is the top hit   → GREEN
+      //
+      // A negative assertion can always be green too early. This one cannot, because
+      // the target must EXIST and be what the browser would actually hit. Their first
+      // attempt was "the centre of the screen is not the splash" — 18 of 18 green
+      // while the screenshot still showed the splash. A negative assertion phrased
+      // more cleverly is still a negative assertion.
+      const { loc, via, remaining } = await locate(page, step);
+      await loc.waitFor({ state: 'visible', timeout: remaining });
+      const hit = await loc.evaluate((el) => {
+        const r = el.getBoundingClientRect();
+        const top = document.elementFromPoint(r.left + r.width / 2, r.top + r.height / 2);
+        if (!top) return { ok: false, what: '(nothing — the centre is off-screen)' };
+        if (top === el || el.contains(top)) return { ok: true, what: '' };
+        const d = top as HTMLElement;
+        const id = d.getAttribute('data-testid');
+        return { ok: false, what: id ? `[data-testid="${id}"]` : `<${d.tagName.toLowerCase()}>` };
+      });
+      if (!hit.ok) {
+        const anchor = step.testid ? `[data-testid="${step.testid}"]` : targetSummary(step.target!);
+        throw new Error(`expected ${anchor} to be the topmost element at its own centre, but the browser would hit ${hit.what}`);
+      }
+      return via ? { __via: via } : null;
+    }
+    case 'expectText': {
+      // upmetrics #2 — POLL the substring until the step timeout, not "wait for
+      // element then read once". An SPA route mounts its shell synchronously
+      // (e.g. "Overview") then hydrates data ("sdk 0.1.4") via async fetch a
+      // beat later; a one-shot read races the hydration and false-fails.
+      const { loc, via, remaining } = await locate(page, step);
+      const anchor = step.testid ? `[data-testid="${step.testid}"]` : targetSummary(step.target!);
+      const want = subst(step.text, vars);
+      const timeout = remaining;
+      const deadline = Date.now() + timeout;
+      let last = '';
+      try {
+        await loc.waitFor({ state: 'visible', timeout });
+      } catch {
+        throw new Error(`${anchor} never became visible within ${timeout}ms`);
+      }
+      // F074.56 — `equals` is the operator Christian's 2026-08-16 rule needs: a
+      // saved value proven by STRICT equality, because `contains` fails in the
+      // GREEN direction. Surrounding whitespace is trimmed (the DOM adds it, the
+      // author did not); nothing else is normalised.
+      const mode = step.match ?? 'contains';
+      const verb = mode === 'equals' ? 'to equal' : mode === 'not-equals' ? 'to differ from' : 'to contain';
+      for (;;) {
+        last = (await loc.textContent().catch(() => null)) ?? '';
+        // A `!=` that passes because the element is EMPTY would be this card's own
+        // defect one level down — different-because-there-is-nothing is not proof.
+        const hit = textMatches(mode, last, want);
+        if (hit) return via ? { __via: via } : null;
+        if (Date.now() >= deadline) {
+          const why = mode === 'not-equals' && last.trim() === ''
+            ? ` — the element is EMPTY, which is not proof that it differs`
+            : '';
+          throw new Error(`expected ${anchor} ${verb} "${want}" within ${timeout}ms, last "${last.trim().slice(0, 160)}"${why}`);
+        }
+        await page.waitForTimeout(150);
+      }
+    }
+    case 'assert': {
+      // upmetrics #2 — POLL the predicate until the step timeout so an assert
+      // over hydrating data (or a redirecting page) settles instead of racing.
+      const body = subst(step.js, vars);
+      const timeout = stepTimeout(step);
+      const deadline = Date.now() + timeout;
+      // F074.29: remember the last thrown error so the timeout message can say
+      // the code exploded rather than claiming the predicate was false.
+      let lastThrow = '';
+      let lastDetail: string | undefined;
+      for (;;) {
+        const next = nextAssertState(await page.evaluate(evalAssertBody, body));
+        if (next.action === 'pass') return null;
+        // Both of these are the PROBE being broken, not the app being wrong:
+        // a body that cannot compile, and a body that threw on every attempt
+        // until the deadline. They stay failures; they just say whose fault.
+        if (next.action === 'fail_now') {
+          throw new InstrumentError(`${next.reason}: ${body.slice(0, 80)}`);
+        }
+        lastThrow = next.lastThrow;
+        lastDetail = next.lastDetail;
+
+        if (Date.now() >= deadline) {
+          const msg = assertTimeoutMessage(timeout, body, lastThrow, lastDetail);
+          throw lastThrow ? new InstrumentError(msg) : new Error(msg);
+        }
+        await page.waitForTimeout(150);
+      }
+    }
+    case 'screenshot': {
+      // F255.3 — settle FIRST. Flow screenshots used to grab the frame the instant the
+      // step ran, so a shot right after a click caught the page mid-transition: on the
+      // F249 mockups list a just-ticked checkbox (transition: background 0.12s) came out
+      // still white while every DOM assert said checked. That reads as "the feature is
+      // broken" when it is the camera that was early. Same settle as lens_capture.
+      await settleForShot(page);
+      const shot = (await takeShot(page, 'viewport', null, 8000)).screenshot;
+      // F126.4 — run the composition critic on this captured frame. A
+      // high-severity finding fails the step (the caller pins the shot + stops),
+      // so a visibly-broken screen breaks the E2E flow too.
+      if (critic !== 'off') {
+        const report = await runCritic(page, shot, critic);
+        // F126.7 — carry the WHOLE report out, on pass and on fail alike.
+        //
+        // It used to end here as a string: the count plus the FIRST message, with
+        // the other findings discarded. xrt81 (#21050) measured what that costs.
+        // A session is told about one issue, fixes it, re-runs, goes green — and
+        // the findings it was never shown are now silently recorded as resolved.
+        // The gate then reports success on a surface with unfixed high-severity
+        // problems, and reports it MORE confidently than before, because there is
+        // a passing run behind it. Every other member of this family produced a
+        // confusing or permissive answer; this one laundered a loss into a pass.
+        //
+        // And on a PASSING step the report vanished entirely, so a screen with
+        // four medium findings and zero high ones reported nothing at all.
+        // `high > 0` decides the STATUS; it must not decide what gets reported.
+        if (sink) sink.critic = report;
+        if (report.high > 0) {
+          const top = topFindingMessage(report);
+          throw new Error(`composition: ${report.high} high-severity issue(s)${top ? ` — ${top}` : ''}`);
+        }
+      }
+      return shot;
+    }
+    case 'fillSelector':
+      await resolveLocator(page, step.selector, step.frame)
+        .first()
+        .fill(subst(step.value, vars), { timeout: stepTimeout(step) });
+      return null;
+    case 'waitForBuild': {
+      // F255.7 — polled from HERE, not through the page: a service worker will happily
+      // serve a cached build and a page-side fetch would report the new marker on a page
+      // still running the old code (fd-sundhed's PWA, 2026-07-30).
+      const r = await waitForBuild(base, {
+        expected: step.sha ?? null,
+        ...(step.timeout ? { timeoutMs: step.timeout } : {}),
+      });
+      // F074.30 — hand the sha BACK, don't just render it into a label. This is
+      // the authoritative capture-time build: what the app was serving AFTER the
+      // wait, which is exactly what the run then looked at. Uses the same
+      // out-of-band channel as __via/__inspect (execStep has no run scope).
+      return {
+        __via: `build ${r.build.slice(0, 8)} live after ${r.polls} polls (${r.mode})`,
+        __build: r.build,
+      };
+    }
+    case 'clickSelector': {
+      const loc = resolveLocator(page, step.selector, step.frame).first();
+      await loc.click({
+        timeout: stepTimeout(step),
+        ...(step.at ? { position: await positionFor(loc, step.at) } : {}),
+      });
+      return null;
+    }
+    // F213.2 — interaction verbs.
+    case 'clear': {
+      const { loc, via, remaining } = await locate(page, step);
+      await consultReadiness(page, loc, step, readySink);
+      await loc.clear({ timeout: remaining });
+      return via ? { __via: via } : null;
+    }
+    case 'press':
+      // A key on a focused testid, or globally (no testid) — Enter-to-submit,
+      // arrow-nav, autocomplete triggering.
+      if (step.testid) {
+        await page.locator(sel(step.testid)).first().press(step.key, { timeout: stepTimeout(step) });
+      } else {
+        await page.keyboard.press(step.key);
+      }
+      return null;
+    case 'drag':
+      // A real HTML5 drag-and-drop (dragstart→dragover→drop) via Playwright's
+      // dragTo — drives the app's actual DnD handlers, unlike synthetic events.
+      await page
+        .locator(sel(step.testid))
+        .first()
+        .dragTo(page.locator(sel(step.toTestid)).first(), { timeout: stepTimeout(step) });
+      return null;
+    case 'uploadFile': {
+      // F213.6 — set the fixture(s) on the target input[type=file] (works on a
+      // HIDDEN input behind a custom button). setInputFiles takes either a list of
+      // absolute paths OR a list of FilePayloads; a step is one kind, not mixed.
+      const paths = Array.isArray(step.path) ? step.path : [step.path];
+      const isData = (p: string) => p.startsWith('data:');
+      if (paths.some(isData) && !paths.every(isData)) {
+        throw new Error('uploadFile: a step must be all data: URIs OR all fixture paths, not a mix');
+      }
+      const files = paths.every(isData) ? paths.map(dataUriToPayload) : paths.map((p) => resolveFixturePath(localPath, p));
+      await page.locator(sel(step.testid)).first().setInputFiles(files, { timeout: stepTimeout(step) });
+      return null;
+    }
+    case 'waitForUrl': {
+      const want = subst(step.url, vars);
+      await page.waitForURL((u) => u.toString().includes(want), { timeout: stepTimeout(step) });
+      return null;
+    }
+    case 'inspect': {
+      if (step.html) {
+        const target = step.testid ? page.locator(sel(step.testid)).first() : resolveLocator(page, 'body', step.frame).first();
+        await target.waitFor({ state: 'attached', timeout: stepTimeout(step) });
+        return { __inspect: await target.evaluate((el) => (el as Element).outerHTML, undefined, { timeout: stepTimeout(step) }) };
+      }
+      // CSP-safe DOM dump: a real fn (Playwright-injected, NOT page eval) run in
+      // the top frame or — with `frame` — inside a cross-origin iframe, so the
+      // author discovers the exact anchors without raw Playwright.
+      const dump = await resolveLocator(page, 'html', step.frame)
+        .first()
+        .evaluate((el) => {
+          const doc = (el as Element).ownerDocument ?? document;
+          const txt = (e: Element) => (e.textContent ?? '').trim().slice(0, 40);
+          const pick = (e: Element) => ({
+            tag: e.tagName.toLowerCase(),
+            type: e.getAttribute('type') ?? undefined,
+            name: e.getAttribute('name') ?? undefined,
+            id: e.id || undefined,
+            role: e.getAttribute('role') ?? undefined,
+            testid: e.getAttribute('data-testid') ?? undefined,
+            title: e.getAttribute('title') ?? undefined,
+            placeholder: e.getAttribute('placeholder') ?? undefined,
+            ariaLabel: e.getAttribute('aria-label') ?? undefined,
+            text: txt(e) || undefined,
+            // Surface a stable structural handle for NAME-LESS icon buttons (the
+            // whole class Set-of-Marks/role/text can't anchor): the class list +
+            // a trimmed outerHTML carrying any class/data-*/aria-* an author can
+            // turn into a deterministic CSS locator.
+            cls: e.getAttribute('class') || undefined,
+            html: (e as HTMLElement).outerHTML?.slice(0, 400) || undefined,
+          });
+          const iframes = Array.from(doc.querySelectorAll('iframe')).map((f) => ({
+            title: (f as HTMLIFrameElement).title || undefined,
+            name: (f as HTMLIFrameElement).name || undefined,
+            id: f.id || undefined,
+            src: ((f as HTMLIFrameElement).getAttribute('src') ?? '').slice(0, 70) || undefined,
+          }));
+          const inputs = Array.from(doc.querySelectorAll('input,select,textarea')).map(pick);
+          const clickables = Array.from(
+            doc.querySelectorAll('button,[role=button],[role=radio],[role=tab],label,[data-testid]'),
+          )
+            .slice(0, 60)
+            .map(pick);
+          // F009.119 — name the full-HTML option where the truncation is seen: two
+          // sessions in two days worked around the 400-char cut without knowing
+          // `html:true` existed.
+          const hint = "each element's html is cut at 400 chars; for one element's FULL outerHTML use {type:'inspect', html:true, testid}";
+          return JSON.stringify({ hint, iframes, inputs, clickables });
+        }, undefined, { timeout: stepTimeout(step) });
+      return { __inspect: String(dump) };
+    }
+    // F213.3 — composite autocomplete: type, wait for the suggestion list, pick.
+    case 'autocomplete': {
+      // fill() dispatches an `input` event (what most autocompletes listen to) so
+      // the suggestion list opens; then wait for ≥1 option and click the pick.
+      await page.locator(sel(step.testid)).first().fill(subst(step.value, vars), { timeout: stepTimeout(step) });
+      const options = page.locator(sel(step.option));
+      await options.first().waitFor({ state: 'visible', timeout: stepTimeout(step) });
+      if (step.pickText !== undefined) {
+        await options.filter({ hasText: subst(step.pickText, vars) }).first().click({ timeout: stepTimeout(step) });
+      } else {
+        await options.nth(step.pickIndex ?? 0).click({ timeout: stepTimeout(step) });
+      }
+      return null;
+    }
+    // F213.3 — capture an element's text (or an input's value) into a named var,
+    // reused by a later step via {{name}}. Mutates the shared `vars` in place.
+    case 'capture': {
+      const loc = page.locator(sel(step.testid)).first();
+      await loc.waitFor({ state: 'attached', timeout: stepTimeout(step) });
+      vars[step.as] =
+        step.from === 'value'
+          ? await loc.inputValue({ timeout: stepTimeout(step) })
+          : ((await loc.textContent({ timeout: stepTimeout(step) })) ?? '').trim();
+      return null;
+    }
+    case 'conditional':
+      throw new Error('conditional steps are handled by runSeq, never execStep');
+    case 'loop':
+      throw new Error('loop steps are flattened before execution');
+  }
+}
+
+export interface RunFlowOptions {
+  /** F082.4 — resume: skip leaf steps before this index (re-run a bulk data
+   *  flow from where it left off). Default 0 (run from the start). */
+  from?: number;
+  /** F092.9 — viewport for the flow's page(s). Default 1280x800 (desktop). Set
+   *  e.g. 390x844 to drive + screenshot mobile-only UI. */
+  viewport?: { width: number; height: number };
+  /** F098.9 — engine to drive the flow (chromium default; webkit/firefox for
+   *  cross-engine bugs, e.g. a WebKit-only mobile-drawer collapse). */
+  engine?: LensEngine;
+  /** F074.57 — BCP-47 locale + IANA timezone for the browser context. A flow on
+   *  a bilingual site is the reason this is per-CALL and not only per-project:
+   *  the same surface needs one run per language. Unset passes nothing. */
+  locale?: string;
+  timezone?: string;
+  /** F074.59 — what this run reports for `prefers-reduced-motion`. Default
+   *  'reduce' (what every run did before the option existed); 'no-preference'
+   *  is what lets `expectAnimating` see an animation at all. */
+  reducedMotion?: 'reduce' | 'no-preference';
+  /** F126.4 — composition critic to run on each `screenshot` step. 'off'
+   *  (default) | 'dom' | 'vision' | 'both'. A high-severity finding fails that
+   *  step (and thus the flow). */
+  critic?: CriticMode;
+  /** F213.6 — repo root for resolving an uploadFile step's fixture path. The
+   *  path is sandboxed to this dir (no `../` escape). Absent → only data: URIs. */
+  localPath?: string;
+  /** F255.5 — record the whole driven run to a .webm, returned as FlowResult.video.
+   *  Off by default: recording costs disk + a little time on every run, and most flows
+   *  only need the per-step stills. */
+  record?: boolean;
+  /** F074.97 — localStorage/sessionStorage written BEFORE the flow's first
+   *  navigation, scoped to the flow's OWN base_url origin. The bug that prompted
+   *  this needs a flow as often as a single shot, and a capability present on one
+   *  entry point and absent on another is the shape F074.23/.24 exist to remove.
+   *  The origin guard matters more here: a flow may redirect to a payment
+   *  provider, and a seed must never follow it there. */
+  storage?: StorageSeed;
+}
+
+// F213.6 — resolve an uploadFile fixture to what Playwright's setInputFiles wants.
+// A `data:` URI → a FilePayload (mime + bytes carried inline). A plain path → the
+// absolute path, SANDBOXED to the repo root so a manuscript can't read /etc/passwd;
+// Playwright reads the file + infers its mime itself. Mixing the two kinds in one
+// step is rejected (keeps the setInputFiles arg homogeneous).
+type FilePayload = { name: string; mimeType: string; buffer: Buffer };
+export function dataUriToPayload(p: string): FilePayload {
+  const m = /^data:([^;,]*)(;base64)?,([\s\S]*)$/.exec(p);
+  if (!m) throw new Error('uploadFile: invalid data: URI fixture');
+  const mimeType = m[1] || 'application/octet-stream';
+  const buffer = m[2] ? Buffer.from(m[3]!, 'base64') : Buffer.from(decodeURIComponent(m[3]!));
+  const ext = (mimeType.split('/')[1] || 'bin').split('+')[0];
+  return { name: `fixture.${ext}`, mimeType, buffer };
+}
+export function resolveFixturePath(localPath: string | undefined, p: string): string {
+  if (!localPath) throw new Error('uploadFile: a fixture path needs local_path — pass it to lens_run_flow / lens_run_manuscript (data: URIs work without it)');
+  const root = nodePath.resolve(localPath);
+  const abs = nodePath.resolve(root, p);
+  if (abs !== root && !abs.startsWith(root + nodePath.sep)) throw new Error(`uploadFile: fixture path escapes the repo root: ${p}`);
+  return abs;
+}
+
+/** Run a flow end-to-end. Top-level steps run sequentially in one authed page;
+ *  a failure there aborts the flow (prerequisite). A `loop` runs its iterations
+ *  either sequentially on the same page or — with `parallel: N` — concurrently,
+ *  each iteration in its own fresh authed page (F082.4 parallel workers). A
+ *  failing step inside an iteration fails + skips the rest of THAT iteration but
+ *  never aborts the others (per-item report). Pins a screenshot on every
+ *  failure. Each leaf gets a deterministic pre-allocated index. */
+export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {}): Promise<FlowResult> {
+  const startedAt = Date.now();
+  const results: FlowStepResult[] = [];
+  const base = flow.base_url.replace(/\/$/, '');
+  const from = Math.max(0, opts.from ?? 0);
+  const prepare = authPrepare(flow.auth, env);
+  // F074.97 — computed ONCE from the flow's own base_url, so every page this run
+  // opens (including each parallel loop iteration) seeds the same origin and
+  // nothing else. A bad seed throws here, before a browser is launched.
+  const seedStorage = storagePayload(opts.storage, base);
+  // F074.99 — passwords this run typed, so the report can say if one comes back
+  // in the URL. Run-level (a parallel loop iteration fills on its own page and
+  // the finding is about the RUN), and it never leaves the process: the finding
+  // names the field and the parameter, never the value.
+  const filledPasswords: FilledPassword[] = [];
+  // F074.99 part 1 — pages where an edit verb wrote while nothing was listening.
+  // Run-level for the same reason: the finding is about the RUN, and the first
+  // one is what a reader acts on.
+  const notListening: NotListeningFinding[] = [];
+  let firstFailedAt: number | null = null;
+  let reason: string | null = null;
+  let aborted = false;
+  /** F074.36 — the first "asked for X, landed on Y", if any. */
+  let firstRedirect: string | null = null;
+  /** F074.36 — where the run actually ended. null = not measured. */
+  let finalUrl: string | null = null;
+  /**
+   * F074.36 — set while the browser is on a page we did not ask for, CLEARED by
+   * the next goto that lands where it asked.
+   *
+   * This is what makes `fault:'instrument'` safe to apply. Tagging every failure
+   * in a run that was redirected at any point would mislabel a genuine app bug
+   * as a broken probe — which is worse than the silence it replaces, because it
+   * gives a reader permission to dismiss a real finding. A failure only stops
+   * being evidence about the app while we are still standing on the wrong page.
+   */
+  let onWrongPage: string | null = null;
+  /** F074.36 — set when the applied credential cannot reach the target host.
+   *  `certain` separates the unambiguous mismatch (we hold cookies, none for
+   *  this host) from the ambiguous one (no cookies at all — legitimate for a
+   *  localStorage-authenticated app). Only the CERTAIN case may tag a failure
+   *  `fault:'instrument'`; tagging the ambiguous one would label every genuine
+   *  bug in such an app as a broken probe, which is worse than the silence this
+   *  card removes because it gives a reader permission to dismiss a real
+   *  finding. Both are still reported. */
+  let authReach: string | null = null;
+  let authReachCertain = false;
+  /** F213.10 — where the most recent navigation LANDED. Null until the first one. */
+  let urlAtLoad: string | null = null;
+  /** F213.10 — the first "we were thrown off the page we were judging", if any. */
+  let firstEjection: string | null = null;
+  /** F213.10 — the flow performed a navigating action whose navigation may not
+   *  have committed yet, so the next URL change belongs to us, not to the app. */
+  let navActionPending = false;
+  /** F213.10 — did this run ever form a verdict about a page? A flow that only
+   *  drives and never asserts has no verdict to void, so it never pays the grace. */
+  let formedAVerdict = false;
+
+  /**
+   * F074.48 — every failed HTTP response the run has seen, in arrival order.
+   *
+   * Collected for the WHOLE run and sliced per step, rather than armed and
+   * disarmed around each step: a refusal often lands a tick after the click that
+   * caused it, and a listener that stops at the step boundary would miss exactly
+   * the response that explains the failure.
+   */
+  const failedResponses: FailedResponse[] = [];
+
+  /** Attach the collector to a page. Called for every page a flow drives — the
+   *  main one AND each parallel loop iteration, which get their own context. */
+  const collectFailures = (page: Page) => {
+    page.on('response', (res) => {
+      if (res.ok()) return;
+      const entry: FailedResponse = {
+        method: res.request().method(),
+        url: res.url(),
+        status: res.status(),
+        body: '',
+      };
+      failedResponses.push(entry);
+      // Read the body OUT OF BAND. A body can be unreadable (already consumed, a
+      // redirect, binary) and reading must never be able to fail the run — the
+      // whole point of this card is a report that says more, not a runner that
+      // breaks more.
+      res
+        .text()
+        .then((t) => {
+          entry.body = redactBody(t.trim()).slice(0, MAX_BODY_CHARS);
+        })
+        .catch(() => {
+          // Stated, not silent: "we could not read it" and "it was empty" are
+          // different facts, and collapsing them is the defect this card fixes.
+          entry.body = '[body not readable]';
+        });
+    });
+  };
+
+  const noteFail = (i: number, msg: string) => {
+    if (firstFailedAt === null) {
+      firstFailedAt = i;
+      reason = msg;
+    }
+  };
+  // F213.11 — reset on EVERY navigation, not just the first. A flow that gotos twice
+  // would otherwise report page two's steps as tens of seconds late, and a field that
+  // reads as noise is a field nobody checks.
+  let lastNavAt = Date.now();
+  const record = (r: FlowStepResult) => {
+    results.push(r);
+  };
+  const skipFill = (steps: FlowStep[], startIndex: number, vars: Record<string, unknown>, detail: string) => {
+    let idx = startIndex;
+    for (const s of steps) {
+      if (s.type === 'loop') {
+        s.data.forEach((row, k) => {
+          skipFill(s.steps, idx, { ...vars, ...row, __index: k }, detail);
+          idx += flattenCount(s.steps);
+        });
+      } else if (s.type === 'conditional') {
+        // F213.3 — a conditional's children occupy a contiguous index block; skip
+        // them all so the report stays aligned whether the branch ran or not.
+        skipFill(s.steps, idx, vars, detail);
+        idx += flattenCount(s.steps);
+      } else {
+        record({ index: idx, type: s.type, label: s.label ?? describe(s), status: 'skip', testid: testidOf(s), detail, screenshot: null });
+        idx += 1;
+      }
+    }
+  };
+
+  // Run a step-list on `page` starting at `startIndex`. Returns whether a
+  // non-loop step failed (so the caller can stop THIS sequence).
+  async function runSeq(page: Page, steps: FlowStep[], vars: Record<string, unknown>, startIndex: number): Promise<{ failedHere: boolean }> {
+    let idx = startIndex;
+    for (let s = 0; s < steps.length; s++) {
+      const step = steps[s]!;
+      if (step.type === 'loop') {
+        const bodyLen = flattenCount(step.steps);
+        const par = Math.max(1, step.parallel ?? 1);
+        const loopBase = idx;
+        if (par > 1) {
+          // Parallel: each iteration in its OWN authed page; failures stay local.
+          const tasks = step.data.map((row, k) => async () => {
+            const iterBase = loopBase + k * bodyLen;
+            const rowVars = { ...vars, ...row, __index: k };
+            try {
+              await withPage({ prepareContext: prepare, seedStorage, viewport: opts.viewport, engine: opts.engine, locale: opts.locale, timezone: opts.timezone, reducedMotion: opts.reducedMotion }, (p2) => {
+                // Each parallel iteration drives its OWN page — attach there too,
+                // or a failure inside a loop reports no network at all.
+                collectFailures(p2);
+                return runSeq(p2, step.steps, rowVars, iterBase);
+              });
+            } catch (err) {
+              // a whole-iteration crash (e.g. auth/navigation) — record + move on
+              record({ index: iterBase, type: 'loop', label: `iteration ${k} crashed`, status: 'fail', testid: null, detail: err instanceof Error ? err.message : String(err), screenshot: null });
+              noteFail(iterBase, 'iteration crashed');
+            }
+          });
+          await runPool(tasks, par);
+        } else {
+          for (let k = 0; k < step.data.length; k++) {
+            const rowVars = { ...vars, ...step.data[k], __index: k };
+            await runSeq(page, step.steps, rowVars, loopBase + k * bodyLen);
+            // a failing iteration does NOT stop the loop — continue.
+          }
+        }
+        idx += step.data.length * bodyLen;
+        continue;
+      }
+
+      if (step.type === 'conditional') {
+        // F213.3 — probe the anchor's presence (short, non-fatal), then run the
+        // child block only when presence matches `present` ('if' vs 'unless');
+        // otherwise skip it (children report 'skip' — no failure). Children
+        // occupy a fixed [condBase, condBase+bodyLen) block so indices stay
+        // deterministic regardless of branch.
+        const bodyLen = flattenCount(step.steps);
+        const condBase = idx;
+        idx += bodyLen;
+        const probe = step.timeout ?? 2000;
+        let visible = false;
+        try {
+          await page.locator(sel(step.testid)).first().waitFor({ state: 'visible', timeout: probe });
+          visible = true;
+        } catch {
+          // anchor not present within the probe window → treated as absent
+        }
+        if (visible === step.present) {
+          const r = await runSeq(page, step.steps, vars, condBase);
+          if (r.failedHere) {
+            // a child step really failed → abort THIS sequence like any leaf fail.
+            skipFill(steps.slice(s + 1), idx, vars, 'skipped after failure');
+            return { failedHere: true };
+          }
+        } else {
+          skipFill(step.steps, condBase, vars, step.present ? 'if: anchor absent — skipped' : 'unless: anchor present — skipped');
+        }
+        continue;
+      }
+
+      // ── leaf step ──
+      const i = idx;
+      idx += 1;
+      const label = step.label ?? describe(step);
+      if (i < from) {
+        record({ index: i, type: step.type, label, status: 'skip', testid: testidOf(step), detail: 'resumed past', screenshot: null });
+        continue;
+      }
+      // F213.11 — read BEFORE the step runs, so the number is "how long after the
+      // page loaded did this start", never "how long did it take".
+      const stepStartedAt = Date.now();
+      const msAfterNav = stepStartedAt - lastNavAt;
+      // F213.13 — a goto's reading is measured from the PREVIOUS navigation, so it
+      // is not the same quantity as its siblings and must not sit in their column.
+      const navOffset = step.type === 'goto' ? {} : { ms_after_navigation: msAfterNav };
+      // Declared OUTSIDE the try: the failing step is exactly where the findings
+      // matter most, and a sink scoped to the try is unreachable from the catch.
+      const sink: CriticSink = { critic: null };
+      try {
+        const out = await execStep(page, step, base, vars, opts.critic ?? 'off', opts.localPath, sink, filledPasswords, notListening);
+        const obj = out !== null && !Buffer.isBuffer(out) && typeof out === 'object' ? out : null;
+        const inspect = obj && '__inspect' in obj ? (obj as { __inspect: string }).__inspect : null;
+        const via = obj && '__via' in obj ? (obj as { __via: string }).__via : null;
+        // F074.30 — a waitForBuild step KNOWS the live sha; it wins over the
+        // best-effort read taken before driving.
+        if (obj && '__build' in obj) observedBuild = (obj as { __build: string }).__build;
+        // F074.36 — remember the FIRST redirect so a later failure can lead with
+        // it. Kept even when every step passes: a green run that was silently
+        // rerouted is exactly the case a reader needs to be able to re-check.
+        const redirect = obj && '__redirect' in obj ? (obj as { __redirect?: string }).__redirect ?? null : null;
+        if (redirect && !firstRedirect) firstRedirect = redirect;
+        // A goto is the only step that can put us on — or take us off — a page we
+        // did not ask for.
+        if (step.type === 'goto') onWrongPage = redirect;
+        // F213.10 — remember where each navigation LANDED, so a later move away
+        // from it is measurable. Read after the goto settles, not from the
+        // requested URL: an app that legitimately rewrites /admin → /admin/users
+        // at load has not ejected us, and comparing against what we asked for
+        // would call that an ejection on every single run.
+        if (formsAVerdict(step.type)) formedAVerdict = true;
+        if (NAVIGATES_BY_DESIGN.has(step.type)) {
+          urlAtLoad = safeUrl(page) ?? urlAtLoad;
+          // A goto is already settled — Playwright waited for it. Any OTHER
+          // navigating action may commit after it returns, so it leaves a note
+          // saying "one URL change after this is mine". See classifyUrlChange.
+          if (step.type !== 'goto') navActionPending = true;
+        } else if (urlAtLoad) {
+          // A verdict step just formed an opinion. If the page moved out from
+          // under it, that opinion is void — and `page.url()` is a synchronous
+          // read of state Playwright already holds, so this costs nothing and
+          // adds no polling (the tax AC4 forbids).
+          const verdict = classifyUrlChange({ loaded: urlAtLoad, current: safeUrl(page) ?? urlAtLoad, navActionPending });
+          if (verdict.kind === 'flow-navigation') {
+            urlAtLoad = verdict.rebaseTo;
+            navActionPending = false;
+          } else if (verdict.kind === 'ejection') {
+            // InstrumentError, not a plain throw: this is a broken measurement,
+            // not an app bug, and F074.29's fault:'instrument' already carries
+            // that distinction through the report.
+            firstEjection = firstEjection ?? verdict.message;
+            throw new InstrumentError(verdict.message);
+          }
+        }
+        // The clock restarts here, so the goto itself reports its own pre-nav value
+        // and every following step is measured from THIS page, not the previous one.
+        if (step.type === 'goto') lastNavAt = Date.now();
+        record({
+          index: i,
+          type: step.type,
+          label,
+          status: 'pass',
+          ...navOffset,
+          ms_step_duration: Date.now() - stepStartedAt,
+          testid: testidOf(step),
+          detail: redirect ?? inspect ?? (via ? `resolved via ${via}` : null),
+          screenshot: Buffer.isBuffer(out) ? out : null,
+          // Attached on a PASSING step too. `high > 0` decides the status; it must
+          // not decide what gets reported. A screen with four medium findings and
+          // no high ones used to report nothing at all.
+          ...(sink.critic ? { critic: sink.critic } : {}),
+        });
+      } catch (err) {
+        // F213.13 — STOP THE CLOCK HERE, before the diagnostics. Everything below
+        // (a 5s failure screenshot, the 150ms settle for in-flight body reads) is
+        // OUR work, not the step's. Measured on the wire: a 500ms timeout reported
+        // ms_step_duration 5018, which reads as "this waited five seconds" — a
+        // fabricated measurement of exactly the kind this pair exists to expose,
+        // and on the failing step, where the number is read most carefully.
+        const failedAfter = Date.now() - stepStartedAt;
+        const msg = err instanceof Error ? err.message : String(err);
+        let shot: Buffer | null = null;
+        try {
+          shot = (await takeShot(page, 'viewport', null, 5000)).screenshot;
+        } catch {
+          // page may be in a bad state — a missing failure shot is acceptable
+        }
+        // F074.36 — a failure measured while standing on a page we never asked
+        // for is not evidence about the app, so it carries the same
+        // `fault:'instrument'` flag F074.29 introduced. `status` stays 'fail', so
+        // nothing that counts failures can stop seeing it.
+        // authReach outranks the URL check and covers the SPA case the URL check
+        // cannot see. It applies to the WHOLE run: the operator asked for an
+        // authenticated measurement and did not get one, so no step in it is the
+        // measurement they asked for.
+        const wrongPage =
+          (authReachCertain ? authReach : null) ??
+          (step.type !== 'goto' && onWrongPage ? onWrongPage : null);
+        // Give in-flight body reads a tick to settle: the refusal that explains
+        // a failure often lands with, or just after, the throw that surfaced it.
+        await new Promise((r) => setTimeout(r, 150));
+        // The MOST RECENT failures of the run, not this step's slice.
+        //
+        // MEASURED, and it is why the first version of this reported nothing: the
+        // refusal is caused by the CLICK and surfaces as a failure on the NEXT
+        // step (expectAbsent). A per-step slice attributes it to the passing step
+        // — where nothing is attached — and the failing step reports an empty
+        // array. Exactly the silence this card exists to remove, rebuilt by
+        // being tidy about step boundaries.
+        //
+        // A flow aborts at its first failure, so "recent" cannot drag in noise
+        // from later work; it can only include the responses that led here.
+        const netSlice = failedResponses.slice(-MAX_FAILED_RESPONSES_PER_STEP);
+        record({
+          index: i,
+          type: step.type,
+          label,
+          // Still 'fail' — a broken probe is never less than a failure.
+          status: 'fail',
+          // F213.11 — on the FAILING step above all: a lost write is exactly where
+          // "this ran 180ms after the page loaded" is the answer.
+          ...navOffset,
+          // F213.13 — and how long it spent failing: a step that burned its whole
+          // timeout and one that threw instantly are different diagnoses.
+          ms_step_duration: failedAfter,
+          testid: testidOf(step),
+          detail: wrongPage ? `${wrongPage} — this step was measured on that page:\n${msg}` : msg,
+          screenshot: shot,
+          ...(err instanceof InstrumentError || wrongPage ? { fault: 'instrument' as const } : {}),
+          // F126.7 — ALL the composition findings, not the count plus the first
+          // message. Without this a caller fixes the one issue it was shown, goes
+          // green, and the rest are silently recorded as resolved.
+          ...(sink.critic ? { critic: sink.critic } : {}),
+          // F074.48 — what the APP said while this step ran. Without it the
+          // report states only what the assertion expected, and a guard doing
+          // its job is indistinguishable from an app that is broken.
+          ...(netSlice.length ? { network: netSlice } : {}),
+        });
+        noteFail(i, msg);
+        // Skip the rest of THIS sequence (rest of the iteration / the top level).
+        skipFill(steps.slice(s + 1), idx, vars, 'skipped after failure');
+        return { failedHere: true };
+      }
+    }
+    return { failedHere: false };
+  }
+
+  // F255.5 — recording writes into a temp dir; Playwright only finalises the .webm when
+  // the context closes, so the file is read AFTER withPage resolves. `videoPage` holds
+  // the page reference across that boundary.
+  // F074.30 — which build this run measured. A waitForBuild step overwrites it
+  // with the authoritative post-wait sha; otherwise we take one best-effort read
+  // before driving, so the row still says what it was looking at. Stays null when
+  // the target exposes no marker — "not measured", never "same as the other run".
+  let observedBuild: string | null = await observeBuild(base);
+
+  const videoDir = opts.record ? await mkdtemp(nodePath.join(tmpdir(), 'lens-flow-video-')) : null;
+  let videoPage: Page | null = null;
+  const readVideo = async (): Promise<Buffer | null> => {
+    if (!videoDir) return null;
+    try {
+      const p = await videoPage?.video()?.path();
+      const bytes = p ? await readFile(p) : null;
+      return bytes;
+    } catch {
+      return null; // a missing recording must never fail an otherwise-good run
+    } finally {
+      await rm(videoDir, { recursive: true, force: true }).catch(() => {});
+    }
+  };
+
+  // F255.7 — gate the WHOLE run on the build under test actually serving, BEFORE a browser
+  // is even launched. A flow that verifies the previous build is the most expensive kind of
+  // green: it exercises real behaviour, so nothing in the report looks wrong.
+  if (flow.wait_for_build !== undefined && flow.wait_for_build !== false) {
+    try {
+      const expected = typeof flow.wait_for_build === 'string' ? flow.wait_for_build : null;
+      const r = await waitForBuild(base, { expected });
+      console.log(`[lens/flow] ${flow.name}: build ${r.build.slice(0, 8)} live after ${r.polls} polls (${r.mode})`);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      skipFill(flow.steps, 0, {}, 'skipped — the build under test never went live');
+      return {
+        name: flow.name,
+        status: 'error',
+        steps: results.sort((a, b) => a.index - b.index),
+        failed_at: 0,
+        reason: `wait_for_build: ${msg}`,
+        duration_ms: Date.now() - startedAt,
+        reduced_motion: opts.reducedMotion ?? 'reduce',
+      };
+    }
+  }
+
+  try {
+    await withPage(
+      {
+        prepareContext: prepare,
+        seedStorage,
+        viewport: opts.viewport,
+        engine: opts.engine,
+        locale: opts.locale,
+        timezone: opts.timezone,
+        reducedMotion: opts.reducedMotion,
+        ...(videoDir ? { recordVideoDir: videoDir } : {}),
+      },
+      async (page, context) => {
+        videoPage = page;
+        collectFailures(page);
+        // F074.36 — measure the credential BEFORE driving, so a run that cannot
+        // possibly be authenticated says so instead of producing a confident
+        // verdict about a login screen. Only when auth was actually requested:
+        // a deliberately anonymous run is not a problem to report.
+        if (prepare) {
+          try {
+            const held = (await context.cookies()).length;
+            const applicable = (await context.cookies(base)).length;
+            const reach = credentialReach(held, applicable, new URL(base).origin);
+            authReach = reach?.message ?? null;
+            authReachCertain = reach?.certain === true;
+          } catch {
+            // cookie read failed — leave authReach null rather than invent a verdict
+          }
+        }
+        const r = await runSeq(page, flow.steps, {}, 0);
+        if (r.failedHere) aborted = true; // a TOP-LEVEL step failed → flow aborts
+        // ── F213.10 · the window, and why it has to exist at all ──────────────
+        //
+        // MEASURED, and it is the finding that shaped this card: the fixture
+        // bounces 800ms after load, and the whole two-step run finishes 55ms
+        // after load. Every check above is free but sees nothing, because the
+        // run is OVER before the ejection happens. Detecting "we will be thrown
+        // off in 800ms" is not possible without staying to watch.
+        //
+        // So the grace is bounded, and it is charged only where a false green is
+        // actually dangerous:
+        //   · the run is otherwise GREEN — a failing run is already telling you
+        //     to look, and a red one must not be delayed;
+        //   · the run FORMED A VERDICT — a flow that only drives and never
+        //     asserts has no opinion to void, so it pays nothing;
+        //   · we are still standing where we landed — if the flow's own last act
+        //     moved the page, waiting tells us nothing about the page we judged.
+        //
+        // THE REACH, per F213.8's rule: a bounce later than eject_grace_ms is
+        // outside this check and the run stays green. This does not detect a
+        // slow ejection; it detects the ordinary one. Set eject_grace_ms: 0 to
+        // opt out entirely, or higher when you know the app's check is slow —
+        // fd-sundhed's was 3.6s.
+        const grace = flow.eject_grace_ms ?? DEFAULT_EJECT_GRACE_MS;
+        // …and it is charged only for the part of the window we have not ALREADY
+        // watched. The grace exists to make the total observation ≥ grace; a flow
+        // that spent two seconds on this page has already given the app twice the
+        // chance to eject it, so waiting again buys nothing.
+        //
+        // MEASURED — this is what keeps the guard affordable: a fast asserting
+        // flow paid +1030ms before this line existed, and every real E2E flow
+        // (which spends seconds on a page) now pays 0.
+        const remainingGrace = grace - (Date.now() - lastNavAt);
+        if (!aborted && formedAVerdict && urlAtLoad && !firstEjection) {
+          if (remainingGrace > 0) {
+            try {
+              // Resolves the INSTANT the page moves, so a real ejection costs ~0
+              // and only the honest all-clear pays the remainder.
+              // Main frame only: an ad or embed navigating is not our page moving,
+              // and letting one resolve the wait early would cut the window short
+              // for the bounce it exists to catch.
+              await page.waitForEvent('framenavigated', { predicate: (f) => f === page.mainFrame(), timeout: remainingGrace });
+            } catch {
+              // No navigation within the window — the expected, quiet outcome.
+            }
+          }
+          // OUTSIDE the wait, deliberately: when the flow already watched longer
+          // than the grace we skip the WAIT, never the COMPARISON. A page that
+          // ejected us during a long step would otherwise go unreported for the
+          // one reason that it took its time — and reading `page.url()` is free.
+          //
+          // Same free pass as mid-run, and it is NOT redundant here: a flow whose
+          // last act was a click can have that navigation commit during the grace,
+          // and calling the flow's own click an ejection is precisely the red on
+          // working software this guard must never produce (measured: 5/5 false
+          // ejections before classifyUrlChange existed).
+          const end = classifyUrlChange({ loaded: urlAtLoad, current: safeUrl(page) ?? urlAtLoad, navActionPending });
+          firstEjection = end.kind === 'ejection' ? end.message : null;
+        }
+        // F074.36 — WHERE the run ended. Read last, so it survives a mid-flow
+        // redirect; a past green run can then be re-checked for which page it
+        // actually judged.
+        try {
+          finalUrl = page.url();
+        } catch {
+          // page already closed — final_url stays null (not measured)
+        }
+      },
+    );
+  } catch (err) {
+    reason = reason ?? (err instanceof Error ? err.message : String(err));
+    // Keep the recording even on a crash — watching HOW it broke is the whole point.
+    const video = await readVideo();
+    return { name: flow.name, status: 'error', steps: results.sort((a, b) => a.index - b.index), failed_at: firstFailedAt, reason: leadWithRedirect(reason, firstRedirect), duration_ms: Date.now() - startedAt, video, build: observedBuild, final_url: finalUrl, redirected: firstRedirect, password_in_url: passwordInUrl(finalUrl, filledPasswords), not_listening: notListening[0] ?? null, reduced_motion: opts.reducedMotion ?? 'reduce' };
+  }
+
+  const video = await readVideo();
+  results.sort((a, b) => a.index - b.index);
+  const anyFail = results.some((s) => s.status === 'fail');
+  const baseReason = reason ?? (aborted ? 'flow aborted on a top-level failure' : null);
+  // The credential mismatch outranks a URL redirect: it explains the redirect.
+  const lead = authReach ?? firstRedirect;
+  // F213.10 — an ejection detected in the grace has no failing STEP behind it:
+  // every step genuinely passed, against a page we turned out not to be allowed
+  // to see. The steps stay truthful and the RUN goes red, because what is void
+  // is the verdict, not the observations.
+  const ejectedRun = !anyFail && firstEjection !== null;
+  return {
+    name: flow.name,
+    status: anyFail || ejectedRun ? 'fail' : 'pass',
+    steps: results,
+    failed_at: firstFailedAt,
+    // Only a FAILING run gets this prepended. A legitimate redirect — or an
+    // anonymous-by-design run — must never be turned into a failure; the guard
+    // adds explanation, it never manufactures a red.
+    reason: ejectedRun ? firstEjection : anyFail ? leadWithRedirect(baseReason, lead) : baseReason,
+    duration_ms: Date.now() - startedAt,
+    video,
+    build: observedBuild,
+    final_url: finalUrl,
+    redirected: firstRedirect,
+    // F074.99 — reported on PASSING runs for the same reason auth_reach is: the
+    // run that prompted this was 12 of 12 GREEN over two empty fields. A finding
+    // that only appears on a red run cannot see the failure it exists for.
+    //
+    // It does NOT fail the run, deliberately and as the plan-doc says. Escalating
+    // to red is defensible — there is no benign reading — but it would turn
+    // currently-green fleet runs red on the day it ships, and that is its own
+    // decision to announce rather than a side effect of this one.
+    password_in_url: passwordInUrl(finalUrl, filledPasswords),
+    // F074.99 part 1 — the FIRST page that was not listening. Reported on a
+    // passing run and never failing it: a plain server-rendered form legitimately
+    // has no listener, so a red here would be a regression for every repo that
+    // drives one. The first finding is what a reader acts on; the memo in
+    // consultReadiness is why there is rarely more than one.
+    not_listening: notListening[0] ?? null,
+    // Reported on PASSING runs too — a green run that was never authenticated is
+    // the more dangerous direction, and it is invisible unless we say so.
+    auth_reach: authReach,
+    ejected: firstEjection,
+    // F074.59 — say which browser this verdict came from. Stamped from what we
+    // ASKED for, defaulted the same way the context does, so the report and the
+    // context can never disagree about it.
+    reduced_motion: opts.reducedMotion ?? 'reduce',
+  };
+}
+
+/**
+ * F074.36 — put the redirect in front of the failure message.
+ *
+ * "waiting for [data-testid=board-root] to be visible" is true and useless when
+ * the browser was sitting on the sign-in wall: the reader concludes the board is
+ * broken. Leading with "asked for /board, landed on /" changes the conclusion
+ * from "our app regressed" to "this run was never logged in".
+ *
+ * Pure + exported so the wording itself is testable — a probe that also answers
+ * WHY needs its reason under test, or half the answer is unverified.
+ */
+/**
+ * F074.36 — can the credential we applied even REACH the host we are driving?
+ *
+ * The first cut of this card compared the requested URL to the landed URL, which
+ * is right for a server-rendered app and BLIND to ours: cardmem is an SPA, so an
+ * unauthenticated `/board` renders the sign-in screen at `/board`. The control
+ * caught it — `final_url` came back as the path we asked for while the
+ * screenshot showed the login wall. A correct check, applied one level from
+ * where the truth sits.
+ *
+ * So measure the credential instead of the routing. Playwright's
+ * `context.cookies(url)` returns exactly the cookies that would be SENT to that
+ * url, which answers the question directly and with no vocabulary of login-page
+ * words: a `localhost`-scoped cookie driven at `https://www.cardmem.com` matches
+ * nothing, and neither does an empty state file.
+ *
+ * `held > 0 && applicable === 0` is the unambiguous case — we are carrying
+ * credentials, none of them for this host. `held === 0` is softer: a
+ * localStorage-only credential legitimately brings no cookies, so it is reported
+ * without being called a mismatch.
+ *
+ * NOT detectable here, and deliberately not implied: a correctly-scoped cookie
+ * that the SERVER has expired or revoked. That truth lives on the other side of
+ * the request. Saying so is the point — a guard that quietly covers four of five
+ * cases while reading as "auth is verified" is the thing this card exists to
+ * remove.
+ */
+export function credentialReach(
+  held: number,
+  applicable: number,
+  targetOrigin: string,
+): { message: string; certain: boolean } | null {
+  if (held > 0 && applicable === 0) {
+    return {
+      message: `the credential applied carries ${held} cookie${held === 1 ? '' : 's'}, none valid for ${targetOrigin} — this run is NOT authenticated`,
+      certain: true,
+    };
+  }
+  if (held === 0) {
+    return {
+      message: `the credential applied left no cookies in the browser — if this app authenticates by cookie, this run is NOT authenticated`,
+      certain: false,
+    };
+  }
+  return null;
+}
+
+export function leadWithRedirect(reason: string | null, redirect: string | null): string | null {
+  if (!redirect) return reason;
+  if (!reason) return redirect;
+  if (reason.startsWith(redirect)) return reason; // already led with it
+  return `${redirect} — the failure below may be about that page, not the one you asked for:\n${reason}`;
+}
+
+/**
+ * F074.42 — ONE definition of what an assert means, owned by the engine.
+ *
+ * This used to be our own copy. `components` took it verbatim into
+ * `@broberg/lens-engine` 0.4.2 and exported it for exactly this reason (the same
+ * argument as `isEditableElement`): the local daemon and the hosted Cloud Lens
+ * must not each carry their own idea of the contract. **Two copies is how
+ * F074.39 arrived** — our flow surface and our verify surface had drifted apart,
+ * and the engine had drifted from both. Keeping a private copy while shipping
+ * the shared one would recreate that on day one.
+ *
+ * The split with the engine is deliberate: **it owns what an assert MEANS
+ * (compile, run, read `.pass`, report syntax/threw/value separately); we own how
+ * long we wait for one** — `nextAssertState` + `assertTimeoutMessage` below are
+ * our poll loop, which the engine intentionally does not have (its assert is
+ * single-shot, and adding retries would change timing for every consumer).
+ *
+ * Re-exported rather than merely imported so every existing call site — and the
+ * F074.39 tests, which now double as the upgrade gate — keeps one import path.
+ */
+export { evalAssertBody, type AssertOutcome };
+
+/** What the assert poll loop does with one evaluation result.
+ *
+ *  Pulled out of the loop so the three branches can be sealed by tests without
+ *  a browser — the loop itself is just `evaluate → decide → sleep`, and the
+ *  deciding is where F074.29's whole point lives. */
+export type AssertStep =
+  | { action: 'pass' }
+  | { action: 'fail_now'; reason: string }
+  | { action: 'retry'; lastThrow: string; lastDetail?: string };
+
+export function nextAssertState(out: AssertOutcome): AssertStep {
+  // A SyntaxError never becomes valid by waiting. Polling it to the deadline is
+  // what produced "stayed falsy" for a probe that could not run at all
+  // (torrent-search-api, #18574) — so it fails immediately, and says why.
+  if (out.kind === 'syntax') {
+    return { action: 'fail_now', reason: `assert body is not valid JavaScript (${out.message})` };
+  }
+  // A throw is NOT a verdict. Keep waiting — the element may not have hydrated
+  // yet, which is the case the polling exists for — but carry the message so
+  // the timeout can name it instead of blaming the predicate.
+  if (out.kind === 'threw') return { action: 'retry', lastThrow: out.message };
+  // engine 0.6.0 — a plain object with no `pass` key is an AUTHOR error, not a
+  // timing one, so polling it for 8s would be the old bug in slow motion. Fail
+  // immediately and name the keys it actually carried: that turns the fix into
+  // one line instead of a hunt. `{}` gets its own wording — there is no key to
+  // suggest a rename of, so it reads as a template nobody filled in.
+  if (out.kind === 'no-verdict') {
+    // The wording comes from the ENGINE (0.6.1's noVerdictMessage), not from us.
+    // We had hand-rebuilt both sentences here and in verify.ts — two copies of a
+    // message, which is the same shape as the two copies of the verdict logic
+    // that caused this whole class in the first place, one layer further out.
+    return { action: 'fail_now', reason: noVerdictMessage(out.keys) };
+  }
+  if (out.value) return { action: 'pass' };
+  // A clean false clears any earlier throw: the body is running now, it simply
+  // is not true yet, so the honest timeout is "stayed falsy". F074.39 — an
+  // author who wrote `{ pass: false, detail: 'expected 3 rows, got 0' }` said
+  // exactly what was wrong; carrying it out means the timeout reports THAT
+  // instead of the generic verdict.
+  return { action: 'retry', lastThrow: '', ...(out.detail ? { lastDetail: out.detail } : {}) };
+}
+
+export function assertTimeoutMessage(
+  timeoutMs: number,
+  body: string,
+  lastThrow: string,
+  lastDetail?: string,
+): string {
+  if (lastThrow) {
+    return `assert never became true within ${timeoutMs}ms; last evaluation threw: ${lastThrow} — ${body.slice(0, 80)}`;
+  }
+  const base = `assert stayed falsy for ${timeoutMs}ms: ${body.slice(0, 80)}`;
+  return lastDetail ? `${base} — detail: ${lastDetail.slice(0, 200)}` : base;
+}