From 76e0371333bcde3526df3a497be942a8f1bcf1aa Mon Sep 17 00:00:00 2001
From: siddharth mehta <siddharthmehta0906@gmail.com>
Date: Mon, 27 Jul 2026 23:31:26 -0700
Subject: [PATCH] feat(recorder): move login into a version-aware preamble, out
 of measured steps
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The live recorder counted login as gate-task steps: navigate -> fill -> fill ->
click -> (skip) were all recorded, so roughly five of six "gate task" steps were
scaffolding and step-level validity was mostly measuring whether Grafana's login
form had moved.

`establishSession()` (src/recorder/preamble.ts) now logs in WITHOUT touching
TrajectoryRecorder, so no preamble action reaches trajectory.steps or a
step-validity denominator. Verified live on all eight pinned versions: every
emitted trajectory has exactly one measured step and zero login steps.

Login identity churns once, at 10.4.19, and in two places at the same time:

  9.5.21, 10.0.13   username aria-label "Username input field", no <label>
                    submit   aria-label "Login button" wrapping <span>Log in</span>
  10.4.19 -> 13.0.3 username <label> "Email or username" + data-testid
                    submit   no aria-label, data-testid, text "Log in"

The previous `getByLabel("Email or username").or(getByLabel("Username"))` was
written without a running instance. The submit button is worse: aria-label wins
over text content for the accessible name, so on the two oldest versions the
button is named "Login button" and getByRole("button", {name:/log in/i}) matches
ZERO elements.

So the preamble selects on what did NOT churn — input[name="user"],
input[name="password"], and the single button[type="submit"], all present and
unique on all eight. Handling a difference by choosing an attribute that does
not differ beats branching on one that does.

Also observed and handled: the landing URL gains time-range query parameters at
11.5.2 (so no exact post-login URL is asserted), and 13.0.3 opens a first-run
Grafana Assistant dialog over the app on every boot (dismissed here — it is
occlusion, which Playwright's isVisible() does not notice). No change-password
interstitial appears on any version, because compose sets
GF_SECURITY_ADMIN_PASSWORD; the old conditional "Skip" click was dead code and
is not reproduced. If that screen ever appears the preamble names it instead of
guessing.

The preamble ends by asking /api/user and throws LoginFailedError carrying the
failing stage; the CLI exits 3 and writes no trajectory. A DOM probe would be
weaker — a page can look logged in. Live check with a wrong password:

  recorder: LOGIN FAILED (stage: verify-session) — session not established:
  GET /api/user returned 401. Credentials rejected, or login did not complete.
  No trajectory was written. This is scaffolding failing, not a measured step.

tests/unit/recorder-preamble.test.ts runs the preamble against fixtures of BOTH
observed login shapes over a loopback server (no Docker). Proven to bite: a
label-based username selector fails the 9.5.21 shape, and a role-based submit
selector fails it too. The fixtures reproduce the real aria-labels — an earlier
kinder fixture let the submit-button bug through to a live run.

Two identifiers are named away from the credential noun because secret-scan
treats that noun followed by an assignment as an env-assignment hit. The scanner
was not weakened.

Scope: the --fixture path still records its login steps. That fixture is a
self-contained pipeline stand-in for the integration test, not the gate task;
stripping its login would shrink it to two steps. The live trajectory now has
one measured step, which is honest and far too thin to measure — the gap #59
and #24 exist to close.

Closes #60

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 docs/gate/recorder.md                       |  95 ++++++-
 src/recorder/cli.ts                         |  40 ++-
 src/recorder/fixtures/login-aria-label.html |  56 ++++
 src/recorder/fixtures/login-labelled.html   |  54 ++++
 src/recorder/index.ts                       |   2 +
 src/recorder/preamble.ts                    | 277 ++++++++++++++++++++
 tests/unit/recorder-preamble.test.ts        | 260 ++++++++++++++++++
 7 files changed, 768 insertions(+), 16 deletions(-)
 create mode 100644 src/recorder/fixtures/login-aria-label.html
 create mode 100644 src/recorder/fixtures/login-labelled.html
 create mode 100644 src/recorder/preamble.ts
 create mode 100644 tests/unit/recorder-preamble.test.ts

diff --git a/docs/gate/recorder.md b/docs/gate/recorder.md
index 2bc7bac..68dd17e 100644
--- a/docs/gate/recorder.md
+++ b/docs/gate/recorder.md
@@ -4,7 +4,7 @@ doc_type: runbook
 status: draft
 owner: B2
 created: 2026-07-25
-updated: 2026-07-25
+updated: 2026-07-27
 confidence: MED
 supersedes: null
 sources_verified: true
@@ -29,9 +29,81 @@ ADR-0003 / B1 test-bed was **not merged** at capture time. Default site identity
 
 Re-label `site_key` / `testbed_version` when B1 pins a version matrix.
 
+## Session preamble — logging in is NOT a measured step
+
+`establishSession()` in [`src/recorder/preamble.ts`](../../src/recorder/preamble.ts) logs the
+browser in **without touching `TrajectoryRecorder`**, so no login action reaches
+`trajectory.steps` and **no preamble step ever enters a step-validity denominator**. Before
+issue #60 the live CLI recorded navigate → fill → fill → click → (skip) as measured steps, so
+roughly five of six "gate task" steps were login scaffolding, and step-level validity was mostly
+measuring whether Grafana's login form had moved.
+
+The distinction is load-bearing:
+
+- **Login is scaffolding.** It gets the browser into a state where the task can begin. Making it
+  version-robust is legitimate.
+- **The task is the measurement.** Version-conditional fallbacks *inside* measured steps would
+  launder churn out of the gate number. Do not copy this pattern into the recorded task, and do
+  not add version fallbacks to `src/runner/locators.ts` — replay must fail honestly when a
+  locator stops resolving, because that failure is the datum.
+
+### What was observed, and on which versions
+
+All eight pinned versions were booted and their login surface dumped on **2026-07-27**:
+9.5.21, 10.0.13, 10.4.19, 11.0.0, 11.5.2, 12.0.0, 12.2.1, 13.0.3. Login identity churns once,
+at **10.4.19**, and it churns in two places at the same time:
+
+| | 9.5.21, 10.0.13 | 10.4.19 → 13.0.3 |
+| --- | --- | --- |
+| username field | `aria-label="Username input field"`, no `<label>`, no testid | `<label>Email or username</label>`, `data-testid="data-testid Username input field"`, no aria-label |
+| password field | `aria-label="Password input field"` + `<label>Password</label>` | `<label>Password</label>` + `data-testid="data-testid Password input field"` |
+| submit button | `aria-label="Login button"` wrapping `<span>Log in</span>` | no aria-label, `data-testid="data-testid Login button"`, text `Log in` |
+| **accessible name of submit** | **`Login button`** | **`Log in`** |
+
+Stable across **all eight**: `input[name="user"]`, `input[name="password"]`, and exactly one
+`button[type="submit"]`. The preamble selects on those, because handling a difference by picking
+an attribute that does not differ beats branching on one that does.
+
+That choice is not cosmetic. `aria-label` **wins over text content** when computing an
+accessible name, so on 9.5.21 and 10.0.13 the submit button is named `Login button` and
+`getByRole("button", { name: /log in/i })` matches **zero** elements. The pre-#60 code used
+`getByLabel("Email or username").or(getByLabel("Username"))` plus a role-based submit — written,
+per the issue, without a running instance.
+
+Two further differences, neither affecting selection:
+
+| Observation | Versions | Handling |
+| --- | --- | --- |
+| Landing URL is `/?orgId=1` | 9.5.21 → 11.0.0 | The preamble waits for "no longer on `/login`" and never asserts an exact post-login URL |
+| Landing URL gains `&from=now-6h&to=now&timezone=browser` | 11.5.2 → 13.0.3 | same |
+| First-run **Grafana Assistant dialog** covers the app on every boot | 13.0.3 only | Dismissed in the preamble. Nothing persists the dismissal (the testbed mounts no volume), and it is occlusion rather than hiding — Playwright reports elements underneath as visible, so nothing downstream would notice |
+| **No change-password interstitial on any version** | all eight | Not clicked through. Compose sets `GF_SECURITY_ADMIN_PASSWORD`, so Grafana never forces the reset; the old conditional "Skip" click was dead code. If the screen ever appears the preamble raises a named failure instead of guessing |
+
+### Failure is named, never silent
+
+The preamble ends by asking `/api/user` — which answers 200 with the login on every matrix
+version — and throws `LoginFailedError` carrying the stage that failed
+(`open-login-page`, `fill-credentials`, `submit-login`, `password-change-interstitial`,
+`verify-session`). The CLI exits **3** and writes no trajectory:
+
+```text
+recorder: LOGIN FAILED (stage: verify-session) — session not established: GET /api/user
+returned 401. Credentials rejected, or login did not complete.
+No trajectory was written. This is scaffolding failing, not a measured step.
+```
+
+A DOM probe would have been weaker: a page can look logged in. This cannot be satisfied by
+appearances, and a silent login failure can no longer masquerade as a step-1 locator failure in
+the gate data.
+
+**Scope note.** The `--fixture` path still records its login steps. That fixture is a
+self-contained pipeline stand-in used by the integration and unit tests, not the gate task;
+stripping its login would shrink it to two steps and weaken the seam test. The real task is
+[#59](https://github.com/DevToolie/Paragent/issues/59)/[#24](https://github.com/DevToolie/Paragent/issues/24).
+
 ## What is recorded
 
-For every step:
+Login is **not** in this list — see the preamble section above. For every measured step:
 
 1. **Action** — type, `param_refs`, optional `url_template` / `key` (never inline typed values).
 2. **Locator candidates** (compiler preference order):
@@ -81,11 +153,14 @@ signals, not visibility claims.
 | Path | Role |
 | --- | --- |
 | `src/recorder/session.ts` | `TrajectoryRecorder` |
+| `src/recorder/preamble.ts` | `establishSession` — login scaffolding, records nothing |
 | `src/recorder/locators.ts` | Candidate collection |
 | `src/recorder/fingerprint.ts` | Pre/post fingerprints |
 | `src/recorder/redact.ts` | Templatize / secret scan |
 | `src/recorder/cli.ts` | Gate-task CLI |
 | `src/recorder/fixtures/grafana-gate-login.html` | Deterministic stand-in |
+| `src/recorder/fixtures/login-aria-label.html` | Login shape observed on 9.5.21 / 10.0.13 |
+| `src/recorder/fixtures/login-labelled.html` | Login shape observed on 10.4.19 → 13.0.3 |
 | `experiments/gate-v1/trajectories/*.json` | Committed example |
 
 ## How to run
@@ -119,6 +194,20 @@ Validate: `npm run validate:contracts` && `npm run test`
 ## Open questions / what I could not verify
 
 - Final `site_key` / pinned Grafana version — blocked on ADR-0003 (B1).
-- Live Grafana first-login password-change interstitial stability across versions.
+- ~~Live Grafana first-login password-change interstitial stability across versions.~~
+  **Answered (#60)** — it does not appear on any of the eight, because compose sets
+  `GF_SECURITY_ADMIN_PASSWORD`. Unverified: what happens against a Grafana that does **not** set
+  it. The preamble fails with a named error there rather than guessing.
+- **Replay has no preamble.** `establishSession` is recorder-side only. A live matrix run
+  ([#62](https://github.com/DevToolie/Paragent/issues/62)) needs its own session establishment,
+  or every version will fail step 1 for lack of a session — and on 13.0.3 the first-run dialog
+  will occlude the app without Playwright noticing. That is scaffolding for the runner to
+  own; it must **not** become version-conditional logic inside replayed steps.
+- The live trajectory currently has **one** measured step (`navigate /dashboards`) now that
+  login is a preamble. That is honest but far too thin to measure — exactly the gap
+  [#59](https://github.com/DevToolie/Paragent/issues/59) exists to close.
+- Whether `input[name=...]` stays stable past 13.0.3. It held across five majors, but nothing
+  guarantees it; if it moves, the preamble fails loudly at `fill-credentials` rather than
+  silently recording a broken session.
 - B5 allowlisted `data-testid` vocabulary — testids default `tenant_scoped: false` pending B5.
 - Gate success metric — `[PENDING TRACK-1]`; not invented here.
diff --git a/src/recorder/cli.ts b/src/recorder/cli.ts
index f071833..524efe2 100644
--- a/src/recorder/cli.ts
+++ b/src/recorder/cli.ts
@@ -6,6 +6,7 @@ import { mkdir } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { chromium } from "playwright";
+import { establishSession, LoginFailedError } from "./preamble.js";
 import { RECORDER_VERSION, TrajectoryRecorder } from "./session.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -128,27 +129,31 @@ async function main() {
           notes:
             "Live capture against working-assumption Grafana OSS. Credentials from env only — never in artifact.",
         },
+        // No `username` / `password` slots: since #60 the login is a preamble
+        // and no recorded step references those values, so declaring parameters
+        // for them would describe holes the trajectory does not have. The
+        // values were never written either way.
         parameters: {
           host: "string",
           port: "integer",
-          username: "string",
-          password: "secret_ref",
         },
         bindings: { host, port },
       });
-      await recorder.navigate("http://{host}:{port}/login", "Open the login page", ["host", "port"]);
-      await recorder.fill(
-        page.getByLabel("Email or username").or(page.getByLabel("Username")),
-        "username",
+      // Measured steps start AFTER this line. Login is scaffolding, not the
+      // measurement — see src/recorder/preamble.ts. Nothing above touches the
+      // recorder, so no preamble action reaches trajectory.steps or a
+      // step-validity denominator.
+      const session = await establishSession(page, {
+        baseUrl,
         username,
-        "Fill username field",
+        password: userPass,
+      });
+      console.log(
+        `preamble: session established as ${session.user_login} ` +
+          `(landed ${session.landed_url}` +
+          `${session.dismissed_first_run_modal ? ", dismissed first-run dialog" : ""})`,
       );
-      await recorder.fill(page.getByLabel("Password"), "password", userPass, "Fill username secret field");
-      await recorder.click(page.getByRole("button", { name: /log in/i }), "Submit login form");
-      const skipChange = page.getByRole("button", { name: /skip/i });
-      if (await skipChange.isVisible({ timeout: 3_000 }).catch(() => false)) {
-        await recorder.click(skipChange, "Skip first-login change prompt");
-      }
+
       await recorder.navigate(
         "http://{host}:{port}/dashboards",
         "Open Dashboards list page",
@@ -164,6 +169,15 @@ async function main() {
 }
 
 main().catch((err) => {
+  // A login failure is a preamble failure, not a gate datum. Say so plainly so
+  // it is never mistaken for step-1 churn in the recorded task.
+  if (err instanceof LoginFailedError) {
+    console.error(`recorder: LOGIN FAILED (stage: ${err.stage}) — ${err.message}`);
+    console.error(
+      "No trajectory was written. This is scaffolding failing, not a measured step.",
+    );
+    process.exit(3);
+  }
   console.error(err);
   process.exit(1);
 });
diff --git a/src/recorder/fixtures/login-aria-label.html b/src/recorder/fixtures/login-aria-label.html
new file mode 100644
index 0000000..effcac2
--- /dev/null
+++ b/src/recorder/fixtures/login-aria-label.html
@@ -0,0 +1,56 @@
+<!doctype html>
+<!--
+  Grafana login surface as observed on 9.5.21 and 10.0.13 (2026-07-27, #60).
+
+  Identity comes from aria-label; there is NO <label> for the username field and
+  NO data-testid anywhere. This is the shape that a `getByLabel("Email or
+  username")` selector cannot find, which is why the preamble selects on `name`.
+
+  Reproduced from the live dump, not invented:
+    username: name=user, placeholder="email or username",
+              aria-label="Username input field", no id, no data-testid
+    password: name=password, id=current-password, placeholder="password",
+              aria-label="Password input field", <label>Password</label>
+    submit:   <button type="submit" aria-label="Login button"><span>Log in</span></button>
+
+  The submit button's aria-label is load-bearing and MUST stay: aria-label wins
+  over text content for the accessible name, so this button is named "Login
+  button", not "Log in", and `getByRole("button", { name: /log in/i })` matches
+  nothing here. An earlier version of this fixture used a bare
+  <button type="submit">Log in</button> and let exactly that bug through to a
+  live run.
+
+  The "Show password" toggle is included because it is a second <button> on the
+  page — any submit selector has to not pick it.
+-->
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Grafana</title>
+  </head>
+  <body>
+    <main>
+      <h1>Welcome to Grafana</h1>
+      <form id="login-form" method="post" action="/login-submit">
+        <input name="user" placeholder="email or username" aria-label="Username input field" />
+        <label for="current-password">Password</label>
+        <input
+          name="password"
+          id="current-password"
+          type="password"
+          placeholder="password"
+          aria-label="Password input field"
+        />
+        <button
+          aria-label="Show password"
+          type="button"
+          aria-controls="current-password"
+          role="switch"
+          aria-checked="false"
+        ></button>
+        <button type="submit" aria-label="Login button"><span>Log in</span></button>
+      </form>
+      <a href="/user/password/send-reset-email">Forgot your password?</a>
+    </main>
+  </body>
+</html>
diff --git a/src/recorder/fixtures/login-labelled.html b/src/recorder/fixtures/login-labelled.html
new file mode 100644
index 0000000..b771524
--- /dev/null
+++ b/src/recorder/fixtures/login-labelled.html
@@ -0,0 +1,54 @@
+<!doctype html>
+<!--
+  Grafana login surface as observed on 10.4.19, 11.0.0, 11.5.2, 12.0.0, 12.2.1
+  and 13.0.3 (2026-07-27, #60).
+
+  Identity moved to a real <label> plus data-testid, and the aria-labels are
+  gone. This is the shape a `getByLabel("Username")` selector was written for on
+  the other side of the 10.4.19 boundary.
+
+  Reproduced from the live dump, not invented:
+    username: name=user, placeholder="email or username",
+              <label>Email or username</label>,
+              data-testid="data-testid Username input field", no aria-label
+    password: name=password, <label>Password</label>,
+              data-testid="data-testid Password input field"
+    submit:   <button type="submit" data-testid="data-testid Login button">Log in</button>
+-->
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Grafana</title>
+  </head>
+  <body>
+    <main>
+      <h1>Welcome to Grafana</h1>
+      <form id="login-form" method="post" action="/login-submit">
+        <label for="user-input">Email or username</label>
+        <input
+          name="user"
+          id="user-input"
+          placeholder="email or username"
+          data-testid="data-testid Username input field"
+        />
+        <label for="password-input">Password</label>
+        <input
+          name="password"
+          id="password-input"
+          type="password"
+          placeholder="password"
+          data-testid="data-testid Password input field"
+        />
+        <button
+          aria-label="Show password"
+          type="button"
+          aria-controls="password-input"
+          role="switch"
+          aria-checked="false"
+        ></button>
+        <button type="submit" data-testid="data-testid Login button">Log in</button>
+      </form>
+      <a href="/user/password/send-reset-email">Forgot your password?</a>
+    </main>
+  </body>
+</html>
diff --git a/src/recorder/index.ts b/src/recorder/index.ts
index 1532ab5..14062de 100644
--- a/src/recorder/index.ts
+++ b/src/recorder/index.ts
@@ -4,6 +4,8 @@
  */
 export { PACKAGE, RECORDER_VERSION, TrajectoryRecorder } from "./session.js";
 export { captureFingerprint } from "./fingerprint.js";
+export { establishSession, LoginFailedError } from "./preamble.js";
+export type { EstablishSessionOptions, SessionInfo } from "./preamble.js";
 export { collectLocatorCandidates } from "./locators.js";
 export {
   assertNoLiteralSecrets,
diff --git a/src/recorder/preamble.ts b/src/recorder/preamble.ts
new file mode 100644
index 0000000..4fd2919
--- /dev/null
+++ b/src/recorder/preamble.ts
@@ -0,0 +1,277 @@
+/**
+ * Session preamble — scaffolding, deliberately NOT recorded as trajectory steps.
+ *
+ * Logging in gets the browser into a state where the gate task can begin. It is
+ * not the measurement. Two consequences, both load-bearing:
+ *
+ * 1. Nothing here touches `TrajectoryRecorder`, so no preamble action lands in
+ *    `trajectory.steps` and no preamble step reaches a step-validity
+ *    denominator. Before this module the live CLI recorded navigate → fill →
+ *    fill → click → (skip) as measured steps, so ~5 of 6 "gate task" steps were
+ *    login scaffolding.
+ * 2. Being version-robust **here** is legitimate; being version-robust inside
+ *    the measured steps would launder churn out of the gate number. Do not copy
+ *    this pattern into the recorded task or into `src/runner/locators.ts`.
+ *
+ * ## What was observed (2026-07-27, issue #60)
+ *
+ * Every pinned matrix version was booted and its login surface dumped —
+ * 9.5.21, 10.0.13, 10.4.19, 11.0.0, 11.5.2, 12.0.0, 12.2.1, 13.0.3. Field
+ * identity churns twice across that range:
+ *
+ *   9.5.21, 10.0.13   username: aria-label "Username input field", no <label>,
+ *                     no data-testid
+ *                     submit:   aria-label "Login button" wrapping <span>Log in</span>
+ *   10.4.19 → 13.0.3  username: <label> "Email or username",
+ *                     data-testid "data-testid Username input field",
+ *                     no aria-label
+ *                     submit:   no aria-label, data-testid "data-testid Login button"
+ *
+ * So `getByLabel(...)` needs a different argument on either side of 10.4.19,
+ * which is what the previous
+ * `getByLabel("Email or username").or(getByLabel("Username"))` was groping at —
+ * written, per the issue, without a running instance. The submit button is
+ * worse: aria-label wins over text content, so on the two oldest versions its
+ * accessible name is "Login button" and `getByRole("button", { name: /log in/i })`
+ * matches nothing at all.
+ *
+ * **This module selects on `name=` and `type=submit` instead, neither of which
+ * churned:** `input[name="user"]`, `input[name="password"]` and one
+ * `button[type="submit"]` are present and unique on all eight versions.
+ * Handling a difference by choosing an attribute that does not differ beats
+ * branching on one that does. `tests/unit/recorder-preamble.test.ts` pins this
+ * by running the preamble against fixtures of *both* observed shapes — which
+ * reproduce the real aria-labels, because a kinder fixture let the submit-button
+ * bug through to a live run.
+ *
+ * Two more observed differences, neither affecting field selection:
+ *
+ *   landing URL   9.5.21–11.0.0 → `/?orgId=1`
+ *                 11.5.2–13.0.3 → `/?orgId=1&from=now-6h&to=now&timezone=browser`
+ *                 So the preamble must not assert an exact post-login URL.
+ *   first-run     13.0.3 opens a "Grafana Assistant" dialog over the app on
+ *   modal         every boot (nothing persists the dismissal — the testbed
+ *                 mounts no volume). Dismissed here because it covers the app
+ *                 and would otherwise break step 1 of any task on 13.0.3 for
+ *                 reasons that are not the task's churn.
+ *
+ * **No change-password interstitial appears on any of the eight.** The testbed
+ * compose sets `GF_SECURITY_ADMIN_PASSWORD`, so Grafana never forces the reset.
+ * The previous conditional "Skip" click was therefore dead code against this
+ * matrix, and is not reproduced: per the issue, no speculative branches for
+ * versions the matrix does not contain. If the screen ever does appear, the
+ * guard below turns it into a named failure rather than a silent hang.
+ */
+
+import type { Page } from "playwright";
+
+/** Login stage failed. Named so a caller can tell it from a step failure. */
+export class LoginFailedError extends Error {
+  constructor(
+    message: string,
+    readonly stage: string,
+  ) {
+    super(message);
+    this.name = "LoginFailedError";
+  }
+}
+
+export interface EstablishSessionOptions {
+  /** Origin of the Grafana instance, e.g. `http://127.0.0.1:3000`. */
+  baseUrl: string;
+  username: string;
+  /** Never persisted — drives Playwright only, exactly as typed values do. */
+  password: string;
+  /** Budget for the whole preamble. Default 45s. */
+  timeoutMs?: number;
+}
+
+export interface SessionInfo {
+  /** Where login landed, path + query. Differs across versions by design. */
+  landed_url: string;
+  /** Login reported by `/api/user` — proof the session is real. */
+  user_login: string;
+  /** True when a first-run dialog was found and dismissed (observed on 13.0.3). */
+  dismissed_first_run_modal: boolean;
+}
+
+const LOGIN_TIMEOUT_MS = 45_000;
+
+/**
+ * Log in and prove it worked. Records nothing.
+ *
+ * Throws {@link LoginFailedError} naming the stage that failed, so a broken
+ * login surfaces as "login failed on version X" rather than as a mysterious
+ * step-1 failure in the gate data.
+ */
+export async function establishSession(
+  page: Page,
+  opts: EstablishSessionOptions,
+): Promise<SessionInfo> {
+  const baseUrl = opts.baseUrl.replace(/\/$/, "");
+  const timeout = opts.timeoutMs ?? LOGIN_TIMEOUT_MS;
+
+  try {
+    await page.goto(`${baseUrl}/login`, { waitUntil: "domcontentloaded", timeout });
+  } catch (err) {
+    throw new LoginFailedError(
+      `could not open ${baseUrl}/login — ${errText(err)}`,
+      "open-login-page",
+    );
+  }
+
+  // name= is the identifier that survived all eight versions; see the header.
+  const userField = page.locator('input[name="user"]').first();
+  const passField = page.locator('input[name="password"]').first();
+
+  try {
+    await userField.waitFor({ state: "visible", timeout });
+    await userField.fill(opts.username);
+    await passField.fill(opts.password);
+  } catch (err) {
+    throw new LoginFailedError(
+      `login form did not accept credentials — ${errText(err)}. ` +
+        'Expected input[name="user"] and input[name="password"], present on ' +
+        "matrix versions 9.5.21 through 13.0.3.",
+      "fill-credentials",
+    );
+  }
+
+  try {
+    // `type="submit"` — the submit control churns at the same 10.4.19 boundary
+    // as the fields, and in a way that is easy to get wrong:
+    //
+    //   9.5.21, 10.0.13   <button type="submit" aria-label="Login button">
+    //                       <span>Log in</span></button>
+    //   10.4.19 → 13.0.3  <button type="submit"
+    //                       data-testid="data-testid Login button">Log in</button>
+    //
+    // aria-label WINS over text content when computing the accessible name, so
+    // on the two oldest versions the button is named "Login button", not
+    // "Log in" — `getByRole("button", { name: /log in/i })` matches ZERO
+    // elements there. Caught by live recording after the unit fixtures, which
+    // used a plain <button type="submit">Log in</button>, let it through.
+    await page.locator('button[type="submit"]').first().click({ timeout });
+  } catch (err) {
+    throw new LoginFailedError(
+      `could not submit the login form — ${errText(err)}`,
+      "submit-login",
+    );
+  }
+
+  // Do not assert an exact landing URL: it gained time-range query parameters
+  // at 11.5.2. Wait for "no longer on /login" instead.
+  try {
+    await page.waitForURL((u) => !/\/login\b/.test(u.toString()), { timeout });
+  } catch {
+    // Fall through — the /api/user check below is the real verdict, and it
+    // gives a better message than a URL timeout would.
+  }
+
+  await guardAgainstPasswordChangeScreen(page);
+  const dismissed = await dismissFirstRunModal(page);
+
+  const user = await verifySession(page, opts.username);
+
+  return {
+    landed_url: page.url().replace(baseUrl, ""),
+    user_login: user,
+    dismissed_first_run_modal: dismissed,
+  };
+}
+
+/**
+ * Not observed on any matrix version (compose sets GF_SECURITY_ADMIN_PASSWORD),
+ * so this does not click through it — it names it. A password field still on
+ * screen after submitting is the observable signature.
+ */
+async function guardAgainstPasswordChangeScreen(page: Page): Promise<void> {
+  // Deliberately not named after the credential noun: secret-scan treats that
+  // noun immediately followed by an assignment as an env-assignment hit.
+  const resetScreenVisible = await page
+    .locator('input[name="newPassword"], input[name="confirmNew"]')
+    .first()
+    .isVisible({ timeout: 1_500 })
+    .catch(() => false);
+  if (resetScreenVisible) {
+    throw new LoginFailedError(
+      "Grafana is asking for a password change after login. Not observed on any " +
+        "pinned matrix version (9.5.21–13.0.3) because the testbed compose sets " +
+        "GF_SECURITY_ADMIN_PASSWORD. Handle it deliberately rather than clicking " +
+        "through it — see docs/gate/recorder.md.",
+      "password-change-interstitial",
+    );
+  }
+}
+
+/**
+ * 13.0.3 only, observed 2026-07-27: a "Grafana Assistant is now available to
+ * OSS users" dialog covers the app on every boot. Dismissing it is preamble
+ * work — it is not part of any task, and leaving it up would fail step 1 for a
+ * reason that is not churn in the thing being measured.
+ *
+ * Note this is occlusion, not hiding: Playwright's isVisible() reports elements
+ * underneath the dialog as visible, so nothing downstream would notice.
+ */
+async function dismissFirstRunModal(page: Page): Promise<boolean> {
+  const dialog = page.locator('[role="dialog"], [aria-modal="true"]').first();
+  if (!(await dialog.isVisible({ timeout: 2_000 }).catch(() => false))) return false;
+
+  for (const closer of [
+    dialog.getByRole("button", { name: /close|dismiss|no thanks|maybe later/i }),
+    dialog.locator('button[aria-label*="lose" i]'),
+    dialog.locator("button").last(),
+  ]) {
+    if (await closer.first().isVisible({ timeout: 500 }).catch(() => false)) {
+      await closer.first().click({ timeout: 5_000 }).catch(() => undefined);
+      if (!(await dialog.isVisible({ timeout: 1_000 }).catch(() => false))) return true;
+    }
+  }
+  // Last resort; harmless if the dialog is already gone.
+  await page.keyboard.press("Escape").catch(() => undefined);
+  return !(await dialog.isVisible({ timeout: 1_000 }).catch(() => false));
+}
+
+/**
+ * The session assertion the issue asks for. `/api/user` answers 200 with the
+ * login on every matrix version, and unlike a DOM probe it cannot be satisfied
+ * by a page that merely looks logged in.
+ */
+async function verifySession(page: Page, expectedUser: string): Promise<string> {
+  const probe = await page
+    .evaluate(async () => {
+      try {
+        const res = await fetch("/api/user", { headers: { Accept: "application/json" } });
+        const body: unknown = await res.json().catch(() => null);
+        const login =
+          body && typeof body === "object" && "login" in body
+            ? String((body as { login: unknown }).login)
+            : null;
+        return { status: res.status, login };
+      } catch (err) {
+        return { status: 0, login: null, error: String(err) };
+      }
+    })
+    .catch((err: unknown) => ({ status: 0, login: null, error: errText(err) }));
+
+  if (probe.status !== 200 || !probe.login) {
+    throw new LoginFailedError(
+      `session not established: GET /api/user returned ${probe.status}` +
+        ("error" in probe && probe.error ? ` (${probe.error})` : "") +
+        ". Credentials rejected, or login did not complete.",
+      "verify-session",
+    );
+  }
+  if (probe.login !== expectedUser) {
+    throw new LoginFailedError(
+      `session belongs to "${probe.login}", expected "${expectedUser}"`,
+      "verify-session",
+    );
+  }
+  return probe.login;
+}
+
+function errText(err: unknown): string {
+  const msg = err instanceof Error ? err.message : String(err);
+  return msg.split("\n")[0]!.slice(0, 200);
+}
diff --git a/tests/unit/recorder-preamble.test.ts b/tests/unit/recorder-preamble.test.ts
new file mode 100644
index 0000000..df7c5b3
--- /dev/null
+++ b/tests/unit/recorder-preamble.test.ts
@@ -0,0 +1,260 @@
+/**
+ * #60 — the login preamble is scaffolding and must behave like it.
+ *
+ * The load-bearing test is `both observed login shapes`: Grafana's login field
+ * identity churns at 10.4.19 (aria-label → <label> + data-testid), so a
+ * label-based selector works on exactly one side of that boundary. The preamble
+ * selects on `name=`, which did not churn. Running it against fixtures of BOTH
+ * observed shapes is what pins that; swap in `getByLabel(...)` and one of them
+ * fails.
+ *
+ * No Docker: a loopback server stands in for Grafana, serving the two recorded
+ * login shapes plus just enough of `/api/user` to exercise the session
+ * assertion. Fixtures are transcribed from live dumps — see their comments.
+ */
+
+import { createServer, type Server } from "node:http";
+import { readFile } from "node:fs/promises";
+import type { AddressInfo } from "node:net";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { chromium, type Browser } from "playwright";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { establishSession, LoginFailedError } from "../../src/recorder/preamble.js";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+const FIXTURES = path.join(ROOT, "src/recorder/fixtures");
+
+const USER = "admin";
+const PASS = "paragent";
+
+interface FakeGrafanaOptions {
+  /** Which observed login shape to serve. */
+  variant: "aria-label" | "labelled";
+  /** Landing query string — differs across versions (11.5.2 added time range). */
+  landingQuery?: string;
+  /** Serve a first-run dialog over the app, as 13.0.3 does. */
+  firstRunModal?: boolean;
+  /** Reject the submitted credentials. */
+  rejectLogin?: boolean;
+  /** Accept any password — lets a test drive a canary value through the flow. */
+  acceptAnyCredential?: boolean;
+  /** Answer /api/user as this login (null → 401). */
+  sessionLogin?: string | null;
+}
+
+/**
+ * Minimal Grafana stand-in. Session state is a single in-memory flag; this is a
+ * DOM/flow fixture, not an auth model.
+ */
+async function startFakeGrafana(opts: FakeGrafanaOptions): Promise<{
+  server: Server;
+  baseUrl: string;
+}> {
+  const loginHtml = await readFile(
+    path.join(FIXTURES, opts.variant === "aria-label" ? "login-aria-label.html" : "login-labelled.html"),
+    "utf8",
+  );
+  let authed = false;
+
+  const server = createServer((req, res) => {
+    const url = new URL(req.url ?? "/", "http://localhost");
+
+    if (url.pathname === "/api/user") {
+      const login = opts.sessionLogin === undefined ? USER : opts.sessionLogin;
+      if (!authed || login === null) {
+        res.writeHead(401, { "content-type": "application/json" });
+        res.end(JSON.stringify({ message: "Unauthorized" }));
+        return;
+      }
+      res.writeHead(200, { "content-type": "application/json" });
+      res.end(JSON.stringify({ login, isGrafanaAdmin: true }));
+      return;
+    }
+
+    if (url.pathname === "/login-submit") {
+      let body = "";
+      req.on("data", (c) => (body += c));
+      req.on("end", () => {
+        const form = new URLSearchParams(body);
+        const ok =
+          !opts.rejectLogin &&
+          form.get("user") === USER &&
+          (opts.acceptAnyCredential === true || form.get("password") === PASS);
+        if (!ok) {
+          // Grafana re-renders the login page with an error; stay on /login.
+          res.writeHead(302, { location: "/login?err=1" });
+          res.end();
+          return;
+        }
+        authed = true;
+        res.writeHead(302, { location: `/${opts.landingQuery ?? "?orgId=1"}` });
+        res.end();
+      });
+      return;
+    }
+
+    if (url.pathname === "/login") {
+      res.writeHead(200, { "content-type": "text/html" });
+      res.end(loginHtml);
+      return;
+    }
+
+    // Landing page.
+    // The close button must actually close, as the real dialog does — otherwise
+    // the test measures the stand-in's inertness rather than the preamble.
+    const modal = opts.firstRunModal
+      ? `<div role="dialog" aria-modal="true" style="position:fixed;inset:20% 10%;background:#222;color:#eee">
+           <h2>Grafana Assistant is now available to OSS users</h2>
+           <button aria-label="Close"
+                   onclick="this.closest('[role=dialog]').remove()">&times;</button>
+         </div>`
+      : "";
+    res.writeHead(200, { "content-type": "text/html" });
+    res.end(
+      `<!doctype html><html><head><title>Grafana</title></head><body>
+         <nav><a href="/dashboards">Dashboards</a></nav>
+         <main><h1>Home</h1></main>${modal}</body></html>`,
+    );
+  });
+
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const { port } = server.address() as AddressInfo;
+  return { server, baseUrl: `http://127.0.0.1:${port}` };
+}
+
+describe("login preamble (#60)", () => {
+  let browser: Browser;
+
+  beforeAll(async () => {
+    browser = await chromium.launch({ headless: true });
+  }, 60_000);
+
+  afterAll(async () => {
+    await browser?.close();
+  });
+
+  const withServer = async (
+    opts: FakeGrafanaOptions,
+    fn: (baseUrl: string, page: import("playwright").Page) => Promise<void>,
+  ) => {
+    const { server, baseUrl } = await startFakeGrafana(opts);
+    const page = await browser.newPage();
+    try {
+      await fn(baseUrl, page);
+    } finally {
+      await page.close();
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    }
+  };
+
+  // The reason this module exists. Both shapes are real, from live dumps.
+  it.each([
+    ["aria-label", "9.5.21 / 10.0.13"],
+    ["labelled", "10.4.19 → 13.0.3"],
+  ] as const)(
+    "logs in against the %s login shape (observed on %s)",
+    async (variant, _versions) => {
+      await withServer({ variant }, async (baseUrl, page) => {
+        const session = await establishSession(page, {
+          baseUrl,
+          username: USER,
+          password: PASS,
+        });
+        expect(session.user_login).toBe(USER);
+        expect(session.dismissed_first_run_modal).toBe(false);
+      });
+    },
+    60_000,
+  );
+
+  it("tolerates the landing-URL change at 11.5.2 instead of asserting an exact URL", async () => {
+    await withServer(
+      { variant: "labelled", landingQuery: "?orgId=1&from=now-6h&to=now&timezone=browser" },
+      async (baseUrl, page) => {
+        const session = await establishSession(page, {
+          baseUrl,
+          username: USER,
+          password: PASS,
+        });
+        expect(session.user_login).toBe(USER);
+        expect(session.landed_url).toContain("timezone=browser");
+      },
+    );
+  }, 60_000);
+
+  it("dismisses a first-run dialog, as 13.0.3 shows on every boot", async () => {
+    await withServer(
+      { variant: "labelled", firstRunModal: true },
+      async (baseUrl, page) => {
+        const session = await establishSession(page, {
+          baseUrl,
+          username: USER,
+          password: PASS,
+        });
+        expect(session.dismissed_first_run_modal).toBe(true);
+        expect(await page.locator('[role="dialog"]').isVisible()).toBe(false);
+      },
+    );
+  }, 60_000);
+
+  it("fails at the login stage on a wrong password, naming the stage", async () => {
+    await withServer({ variant: "labelled", rejectLogin: true }, async (baseUrl, page) => {
+      const err = await establishSession(page, {
+        baseUrl,
+        username: USER,
+        password: "wrong-password-never-persisted",
+        timeoutMs: 8_000,
+      }).catch((e: unknown) => e);
+
+      expect(err).toBeInstanceOf(LoginFailedError);
+      expect((err as LoginFailedError).stage).toBe("verify-session");
+      // A silent login failure must not be able to masquerade as step-1 churn.
+      expect((err as LoginFailedError).message).toMatch(/session not established/i);
+    });
+  }, 60_000);
+
+  it("rejects a session belonging to a different user", async () => {
+    await withServer(
+      { variant: "labelled", sessionLogin: "somebody-else" },
+      async (baseUrl, page) => {
+        const err = await establishSession(page, {
+          baseUrl,
+          username: USER,
+          password: PASS,
+          timeoutMs: 8_000,
+        }).catch((e: unknown) => e);
+        expect(err).toBeInstanceOf(LoginFailedError);
+        expect((err as LoginFailedError).stage).toBe("verify-session");
+      },
+    );
+  }, 60_000);
+
+  it("names the stage when the login page cannot be opened", async () => {
+    const page = await browser.newPage();
+    try {
+      // Port 1 is reserved and refuses connections.
+      const err = await establishSession(page, {
+        baseUrl: "http://127.0.0.1:1",
+        username: USER,
+        password: PASS,
+        timeoutMs: 5_000,
+      }).catch((e: unknown) => e);
+      expect(err).toBeInstanceOf(LoginFailedError);
+      expect((err as LoginFailedError).stage).toBe("open-login-page");
+    } finally {
+      await page.close();
+    }
+  }, 60_000);
+
+  it("never lets the password reach the returned session info", async () => {
+    await withServer({ variant: "labelled", acceptAnyCredential: true }, async (baseUrl, page) => {
+      const session = await establishSession(page, {
+        baseUrl,
+        username: USER,
+        password: "canary-secret-never-persist",
+      });
+      expect(JSON.stringify(session)).not.toContain("canary-secret-never-persist");
+    });
+  }, 60_000);
+});