@capagents/forgeqe 0.0.0-stage → 1.0.1

package/src/code/handoff.ts

@@ -0,0 +1,541 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+import YAML from "yaml"
+
+import { caseMarkdown } from "../cases/goal.ts"
+import type { TestCase } from "../cases/types.ts"
+import { findPage, readPages, type MemoryElement, type MemoryPage } from "../memory.ts"
+import { replayOptions, replaySection, type Replay } from "./replay.ts"
+import { sliceFor } from "./slices.ts"
+
+/** What the coding agent gets from a browser run: the verified steps, their locators, and page memory. */
+
+/** `verified`: during the run this locator found exactly the acted-on element on the live page. */
+export type Locator = { type?: string; value?: string; confidence?: number | null; css?: string; attr?: string; verified?: boolean; playwright?: string; matches?: number }
+
+export type Step = {
+  op?: string
+  url?: string
+  page?: string
+  page_url?: string
+  label?: string
+  text?: string
+  text_env?: string
+  keys?: string
+  totp_env?: string
+  clear?: boolean
+  seconds?: number
+  down?: boolean
+  pages?: number
+  action_keys?: string[]
+  best_locator?: string | null
+  locators?: Locator[]
+  locator?: Record<string, unknown>
+  selector_candidates?: Locator[]
+  /** evaluate: the JavaScript the browser agent ran. */
+  code?: string
+  /** The browser agent's own words for the step that did this: what it saw and what it set out to do. */
+  note?: string
+  /** evaluate that changed the page: the run did this from a script, which a test cannot repeat. */
+  scripted?: boolean
+  /** click: the control sat in an overlay (cookie banner, sign-in prompt, dialog) that this click dismissed. */
+  overlay?: { kind?: string; name?: string; id?: string }
+}
+
+/** An element the engine found on the live page, with its locators (verified ones first). */
+export type CapturedElement = { tag?: string; role?: string; name?: string; locators?: Locator[] }
+
+/**
+ * A result the browser agent verified: the expected result in its words, the exact text the page showed for it, the
+ * element showing it and its container (found on the live page), and whether the text is live data.
+ */
+export type Check = {
+  expected: string
+  text: string
+  url?: string
+  dynamic?: boolean
+  element?: CapturedElement
+  container?: CapturedElement
+  /** The repeating item the element belongs to (a result card, a row): its selector, how many, and the element's selector inside one. */
+  item?: { selector: string; count: number; inside?: string | null }
+}
+
+/** A check as the Playwright replay found it on the final page: the locator that matched its text, and where. */
+export type CheckResult = Check & {
+  locator?: string
+  matches: number
+  where?: string[]
+  field?: boolean
+  /** For a heading: the part of the page it names, with a locator when the element has a stable one. */
+  section?: { locator: string; how: string; tag: string; links: number; items: number }
+}
+
+export type BrowserProfile = {
+  driver?: string
+  channel?: string
+  executable?: string
+  headless?: boolean
+  version?: string
+  user_agent?: string
+  webdriver?: boolean
+  language?: string
+  timezone?: string
+  viewport?: number[]
+  removed_default_args?: string[]
+  extra_http_headers?: Record<string, string>
+}
+
+type RunJson = {
+  success?: boolean
+  summary?: string
+  goal?: string
+  start_url?: string
+  final_url?: string
+  memory?: { dir?: string; left_out?: string[] }
+  browser?: BrowserProfile
+  judge?: { verdict?: boolean; reasoning?: string }
+}
+
+export type Handoff = {
+  goal: string
+  success: boolean
+  summary: string
+  finalUrl: string
+  markdown: string
+  file: string
+  /** Recorded steps and checks, and pages from page memory. */
+  steps: number
+  pages: number
+  checks: number
+}
+
+const MAX_PAGES = 4
+const MAX_ELEMENTS = 8
+/** Locators below this confidence (deep XPaths, text that matched other elements) are left out. */
+const MIN_CONFIDENCE = 30
+const MAX_LOCATORS = 4
+/** Page slices in a handoff: at most this many steps get one, of at most this many lines. */
+const MAX_SLICES = 15
+const SLICE_LINES = 14
+
+function readJson<T>(file: string): T | null {
+  try {
+    return JSON.parse(readFileSync(file, "utf8")) as T
+  } catch {
+    return null
+  }
+}
+
+function quote(s: string): string {
+  return JSON.stringify(s)
+}
+
+const playwrightOf = (l: Locator) => l.playwright || `${l.type}: ${l.value}`
+
+/** Locators checked on the live page during the run, the most stable first; XPath only when nothing else was. */
+function verifiedLocators(locs: Locator[] | undefined): Locator[] {
+  const ok = (locs || []).filter((l) => l.verified)
+  const plain = ok.filter((l) => l.type !== "xpath")
+  return (plain.length ? plain : ok).slice(0, MAX_LOCATORS)
+}
+
+function locatorList(step: Step): string[] {
+  const verified = verifiedLocators(step.locators)
+  if (verified.length) return verified.map((l) => `${l.type}: ${l.value} ✓`)
+  if (step.locators?.length) {
+    const strong = step.locators.filter((l) => l.confidence == null || l.confidence >= MIN_CONFIDENCE)
+    return (strong.length ? strong : step.locators.slice(0, 1))
+      .slice(0, MAX_LOCATORS)
+      .map((l) => `${l.type}: ${l.value}${l.confidence != null ? ` (${l.confidence}%)` : ""}`)
+  }
+  return (step.selector_candidates || []).slice(0, MAX_LOCATORS).map((l) => `${l.type}: ${l.value}`)
+}
+
+function stepLines(step: Step, n: number): string[] {
+  const where = step.page || step.page_url || ""
+  const target = step.label || Object.values(step.locator || {}).filter(Boolean).join(" ") || "element"
+  let head: string
+  switch (step.op) {
+    case "navigate":
+      return [`${n}. navigate ${step.url}`]
+    case "click":
+      head = `click ${target}`
+      break
+    case "input":
+      head = step.text_env
+        ? `fill ${target} with process.env.${step.text_env}`
+        : `fill ${target} with ${quote(step.text || "")}`
+      break
+    case "select":
+      head = `select ${quote(step.text || "")} in ${target}`
+      break
+    case "press":
+      return [`${n}. press ${step.keys}`]
+    case "evaluate":
+      return step.scripted
+        ? [
+            `${n}. changed the page from JavaScript, which a test cannot repeat: do what it did through the page's own control (find it in the page snapshot): ${(step.code || "").replace(/\s+/g, " ").trim().slice(0, 400)}`,
+          ]
+        : [`${n}. ran JavaScript on the page: ${(step.code || "").replace(/\s+/g, " ").trim().slice(0, 400)}`]
+    case "wait":
+    case "scroll":
+    case "back":
+      return [`${n}. ${step.op}`]
+    default:
+      return [`${n}. ${step.op || "unknown"}`]
+  }
+  const overlay = step.overlay ? `  [closes the ${step.overlay.kind || "overlay"}${step.overlay.name ? ` "${step.overlay.name}"` : ""}]` : ""
+  const lines = [`${n}. ${head}${where ? `  (on ${where.split("?")[0]})` : ""}${overlay}`]
+  if (step.best_locator) lines.push(`   best: ${step.best_locator}`)
+  const alts = locatorList(step)
+  if (alts.length) lines.push(`   locators: ${alts.join(" | ")}`)
+  return lines
+}
+
+/** The steps in order, each group led by the browser agent's note from the step that performed it. */
+function stepsSection(steps: Step[], slices: Map<number, string[]> = new Map()): string[] {
+  if (!steps.length) return ["(no recorded steps)"]
+  const lines: string[] = []
+  let last = ""
+  steps.forEach((step, i) => {
+    const note = step.note || ""
+    if (note && note !== last) lines.push(`> Browser agent: ${note}`)
+    last = note
+    lines.push(...stepLines(step, i + 1), ...(slices.get(i + 1) || []))
+  })
+  return lines
+}
+
+/** host + path of a URL or a step's page ("en.wikipedia.org/wiki/X"), to match a step to the replay's page snapshots. */
+function pageKey(url: string | undefined): string {
+  if (!url) return ""
+  try {
+    const u = new URL(/^https?:\/\//.test(url) ? url : `https://${url}`)
+    return `${u.host}${u.pathname}`.replace(/\/+$/, "")
+  } catch {
+    return ""
+  }
+}
+
+/** The Playwright locators a step can be found by in an aria snapshot: its best, then the recorded ones. */
+function stepLocators(step: Step): string[] {
+  const fromType = (l: Locator) => {
+    if (l.playwright) return l.playwright
+    const [role, name] = String(l.value || "").split("|")
+    if (l.type === "role" && role) return `getByRole(${JSON.stringify(role)}${name ? `, { name: ${JSON.stringify(name)} }` : ""})`
+    if ((l.type === "label" || l.type === "placeholder" || l.type === "text") && l.value) return `getByText(${JSON.stringify(l.value)})`
+    return ""
+  }
+  return [step.best_locator || "", ...(step.locators || []).map(fromType)].filter(Boolean)
+}
+
+/**
+ * Each element step's part of the page, from the replay's snapshot of that page: its section, its neighbours, and the
+ * element marked. A step whose section was just shown points back to it instead of repeating it.
+ */
+function stepSlices(steps: Step[], replay: Replay | null | undefined): Map<number, string[]> {
+  const out = new Map<number, string[]>()
+  const pass = replay?.passes.find((p) => p.reached && p.pages?.length) || replay?.passes.find((p) => p.pages?.length)
+  if (!pass?.pages) return out
+  const snaps = new Map<string, string>()
+  for (const p of pass.pages) {
+    try {
+      snaps.set(pageKey(p.url), readFileSync(p.snapshot, "utf8"))
+    } catch {}
+  }
+  const shown = new Map<string, number>()
+  steps.forEach((step, i) => {
+    if (out.size >= MAX_SLICES || !["click", "input", "select"].includes(step.op || "")) return
+    const snap = snaps.get(pageKey(step.page || step.page_url))
+    if (!snap) return
+    for (const loc of stepLocators(step)) {
+      const slice = sliceFor(snap, loc, `step ${i + 1}`, SLICE_LINES)
+      if (!slice) continue
+      const key = `${pageKey(step.page || step.page_url)}|${slice[0]}`
+      const earlier = shown.get(key)
+      out.set(i + 1, earlier ? [`   on the page: in the same section as step ${earlier}`] : ["   on the page:", "   ```yaml", ...slice.map((l) => `   ${l}`), "   ```"])
+      if (!earlier) shown.set(key, i + 1)
+      return
+    }
+  })
+  return out
+}
+
+/**
+ * The overlays the run closed, in order. They often show together (a sign-in prompt over a cookie banner), and a
+ * click on one is blocked while another covers it, so the test closes them in this order from one handler.
+ */
+function overlaysSection(steps: Step[]): string[] {
+  const closes = steps.filter((s) => s.op === "click" && s.overlay)
+  if (!closes.length) return []
+  const lines = closes.map((s, i) => {
+    const o = s.overlay!
+    const [best] = verifiedLocators(s.locators)
+    const container = o.id ? ` (container #${o.id})` : ""
+    return `${i + 1}. ${o.kind || "overlay"}${o.name ? ` "${o.name}"` : ""}${container}: close with ${best ? playwrightOf(best) : s.best_locator || s.label}`
+  })
+  return [
+    "## Overlays this run closed",
+    "",
+    "These covered the page and the run closed them in this order (the one on top first); the replay closed them the same way, as plain steps, and passed. In the test, write one helper that closes each of them that is visible, in this order, and call it after every navigation and right before each step that opens something (a date picker, a menu): an overlay can come back after a click. Use plain visibility checks and clicks; locator handlers and combined (or) locators block each other when two overlays show at once.",
+    "",
+    ...lines,
+  ]
+}
+
+/** The Playwright options of the replay pass that reached the run's final page: the test uses the same, so it gets the same page. */
+function launchSection(b: BrowserProfile | undefined, replay: Replay | null | undefined): string[] {
+  const pass = replay?.passes.find((p) => p.reached)
+  if (!b || !pass) return []
+  const { launch, context } = replayOptions(b, pass.setup)
+  return [
+    "## Browser options that reached the run's page",
+    "",
+    "The replay reached the run's final page with these Playwright options. Set the same in the repository's browser configuration (launch options, browser context options, run settings) before the first run, so the test gets the same version of each page (language, currency, layout) as the run:",
+    "",
+    "```json",
+    JSON.stringify({ launch, context }, null, 2),
+    "```",
+  ]
+}
+
+function browserSection(b: BrowserProfile): string[] {
+  const headers = Object.keys(b.extra_http_headers || {})
+  const lines = [
+    b.driver ? `- Driver: ${b.driver}` : "",
+    `- Browser: ${[b.version, b.channel ? `channel "${b.channel}"` : "", b.executable].filter(Boolean).join(", ") || "unknown"}`,
+    b.headless != null ? `- Mode: ${b.headless ? "headless" : "headed"}` : "",
+    b.user_agent ? `- User agent: ${b.user_agent}` : "",
+    b.webdriver != null ? `- navigator.webdriver: ${b.webdriver}` : "",
+    b.removed_default_args?.length ? `- Default launch switches removed: ${b.removed_default_args.join(" ")}` : "",
+    `- Extra HTTP headers: ${headers.length ? headers.join(", ") : "none"}`,
+    [b.language && `language ${b.language}`, b.timezone && `time zone ${b.timezone}`, b.viewport?.length === 2 && `viewport ${b.viewport[0]}×${b.viewport[1]}`]
+      .filter(Boolean)
+      .join(", "),
+  ]
+  return lines.filter(Boolean).map((l) => (l.startsWith("- ") ? l : `- ${l[0].toUpperCase()}${l.slice(1)}`))
+}
+
+function elementRow(e: MemoryElement): string {
+  const label = e.name || e.text || e.attributes?.placeholder || e.attributes?.["aria-label"] || ""
+  const others = e.locators
+    .slice(1)
+    .filter((l) => l.confidence >= MIN_CONFIDENCE)
+    .slice(0, 2)
+    .map((l) => `${l.playwright} (${l.confidence}%)`)
+    .join("; ")
+  const used = e.interactions ? `used ${e.interactions}×` : ""
+  return `| ${e.confidence}% | ${e.tag}${label ? ` "${label.slice(0, 40)}"` : ""} | ${used} | ${e.best || ""} | ${others} |`
+}
+
+/** A visited page's other strong elements; the ones the steps acted on are listed with the steps. */
+function pageSection(page: MemoryPage, inSteps: Set<string>): string[] {
+  const total = Object.keys(page.elements).length
+  const elements = Object.values(page.elements)
+    .filter((e) => !(e.best && inSteps.has(e.best)) && (e.interactions || e.confidence >= 70))
+    .sort((a, b) => (b.interactions || 0) - (a.interactions || 0) || b.confidence - a.confidence)
+  const lines = [
+    `### ${page.host}${page.path}${page.title ? ` — ${page.title}` : ""}`,
+    `${page.visits || 0} visits, last seen ${page.last_seen || "?"}, ${total} elements. File: ${page.file}`,
+  ]
+  const shown = Math.min(elements.length, MAX_ELEMENTS)
+  if (shown) lines.push("", "| conf | element | | best locator | other locators |", "|---|---|---|---|---|", ...elements.slice(0, shown).map(elementRow))
+  if (total > shown) lines.push("", shown ? `${total - shown} more elements in the file.` : "The steps above use this page's elements; the others are in the file.")
+  return lines
+}
+
+/** A check whose element the engine found and verified on the live page: its locator, its container, and whether it is live data. */
+function capturedCheckLine(c: Check, n: number): string | null {
+  const [best] = verifiedLocators(c.element?.locators)
+  if (c.item) {
+    // A check about items in a list: every item, located by what repeats, not by this run's values.
+    const inside = c.item.inside ? `; inside each: page.locator(${JSON.stringify(c.item.inside)})` : best ? `; the element: ${playwrightOf(best)}` : ""
+    return [
+      `${n}. ${c.expected} (the page showed ${quote(c.text)} in one of them)`,
+      `   Each item: page.locator(${JSON.stringify(c.item.selector)}) (${c.item.count} on the page during the run)${inside}. Assert it for the items the expected result names, not this run's values.`,
+    ].join("\n")
+  }
+  if (!best) return null
+  const live = c.dynamic ? " Live data: assert what the expected result says holds, not this value." : ""
+  const lines = [`${n}. ${c.expected} (the page showed ${quote(c.text)}): ${playwrightOf(best)} ✓${live}`]
+  const [box] = verifiedLocators(c.container?.locators)
+  if (box) lines.push(`   Inside ${c.container?.tag || "its container"}${c.container?.name ? ` "${c.container.name}"` : ""}: ${playwrightOf(box)} ✓ (assert what the section holds inside it)`)
+  return lines.join("\n")
+}
+
+function checkLine(c: Check | CheckResult, n: number): string {
+  const captured = capturedCheckLine(c, n)
+  if (captured) return captured
+  const head = `${n}. ${c.expected} (the page showed ${quote(c.text)})${c.dynamic ? " (live data: assert the rule, not this value)" : ""}`
+  if (!("matches" in c)) return head
+  if (!c.matches || !c.locator) return `${head}: not found on the replay's last page; find its element in the page snapshot or your live browser.`
+  if (c.field) return `${head}: a form field holds it: ${c.locator} (assert its value)`
+  const where = c.where?.length ? `; visible: ${c.where.join(", ")}` : ""
+  const line = `${head}: ${c.locator} (${c.matches} ${c.matches === 1 ? "match" : "matches"}${where})`
+  const s = c.section
+  if (!s) return line
+  const what = `${s.links} ${s.links === 1 ? "link" : "links"}, ${s.items} list ${s.items === 1 ? "item" : "items"}`
+  return `${line}\n   Its section (${s.how}, a ${s.tag}): ${s.locator || "no stable locator; reach it from the heading"} (${what})`
+}
+
+/** The browser agent's checks, with the locator the replay found for each when it ran. */
+function checksSection(checks: Check[], replay?: Replay | null): string[] {
+  if (!checks.length) return []
+  const pass = replay?.passes.find((p) => p.reached && p.checks?.length) || replay?.passes.find((p) => p.checks?.length)
+  const found = pass?.checks?.length === checks.length ? pass.checks : undefined
+  // The element the engine verified on the live page wins over the replay's text match.
+  const merged = found ? found.map((r, i) => ({ ...checks[i], ...r, element: checks[i]?.element, container: checks[i]?.container, dynamic: checks[i]?.dynamic, item: checks[i]?.item })) : checks
+  const captured = checks.every((c) => c.item || verifiedLocators(c.element?.locators).length)
+  return [
+    "## Checks the browser agent made",
+    "",
+    captured
+      ? "The results the goal asks to check, each with the locator of the element that showed it (✓: found exactly that element on the live page during the run) and the section it sits in. Assert each with that locator, and what a section holds inside the section locator. Add no other assertions."
+      : found
+      ? "The results the goal asks to check, with the text the page showed and the Playwright locator that matched that text on the replay's last page. Assert each of them with that locator (scope it to the container named when there are several matches); where the goal asks about what a section holds (its links, items, or a value in it), assert it inside the section given under the heading. Add no other assertions."
+      : "The results the goal asks to check, with the text the page showed. Assert each of them, and add no other assertions.",
+    "The text comes from one run: where it is live data (a price, a count, a date that moves), assert what the expected result says holds, not that value.",
+    "",
+    ...merged.map((c, i) => checkLine(c, i + 1)),
+  ]
+}
+
+/** The run found a functional defect: the test asserts the correct behaviour and is marked as an expected failure. */
+export type KnownDefect = { reason: string; bug?: { label: string; url?: string } }
+
+export function buildHandoff(runDir: string, memoryDir?: string, opts: { replay?: Replay | null; knownDefect?: KnownDefect } = {}): Handoff {
+  const run = readJson<RunJson>(path.join(runDir, "run.json"))
+  if (!run) throw new Error(`No run.json in ${runDir}. Point at a ForgeQE run directory.`)
+  const workflowFile = path.join(runDir, "workflow.yaml")
+  const workflow = existsSync(workflowFile) ? (YAML.parse(readFileSync(workflowFile, "utf8")) as { steps?: Step[]; checks?: Check[] }) : {}
+  const steps = workflow?.steps || []
+  const checks = (workflow?.checks || []).filter((c) => c && typeof c.text === "string" && c.text.trim())
+  const memDir = run.memory?.dir || memoryDir
+  const pages = memDir ? readPages(memDir) : []
+  const urls = [
+    ...steps.flatMap((s) => [s.page, s.page_url, s.op === "navigate" ? s.url : undefined]),
+    run.final_url,
+  ].filter((u): u is string => Boolean(u))
+  const seen = new Set<string>()
+  const visited: MemoryPage[] = []
+  for (const url of urls) {
+    const page = findPage(pages, url)
+    if (page && !seen.has(page.file)) {
+      seen.add(page.file)
+      visited.push(page)
+    }
+  }
+
+  const goal = run.goal || ""
+  const header = [
+    `Goal: ${goal}`,
+    `Result: ${run.success ? "passed" : opts.knownDefect ? "failed: the application has a functional defect (below); every step was done" : "failed"}`,
+    run.summary
+      ? `What the browser agent reported (values from this one run on live data; check them as rules that hold on every run, not as expected values): ${run.summary}`
+      : "",
+    run.judge?.reasoning ? `Judge's check of the trace: ${run.judge.reasoning}` : "",
+    run.start_url ? `Start URL: ${run.start_url}` : "",
+    run.final_url
+      ? `Final URL (the site built it during this run, with its own tracking and session parameters; reach it through the page, do not open it directly): ${run.final_url}`
+      : "",
+    `Run artifacts: ${runDir} (run.json, workflow.yaml, trace.md)`,
+  ]
+  const md: string[] = ["# Verified browser run", "", ...header.filter(Boolean), ""]
+  if (run.browser) {
+    md.push(
+      "## Browser ForgeQE used",
+      "",
+      ...browserSection(run.browser),
+      "",
+      "When the test's browser gets a different page, compare it with this one first.",
+      "",
+    )
+  }
+  const testCase = readJson<TestCase>(path.join(runDir, "testcase.json"))
+  if (testCase) {
+    md.push(caseMarkdown(testCase), "")
+    md.push(
+      "## Mapping the test to its test case",
+      "",
+      `Name the test "${testCase.id} ${testCase.title}" and tag or annotate it with the test case id ${testCase.id}${testCase.url ? ` and its link ${testCase.url}` : ""}, using the framework's own mechanism (Playwright's tag and annotation options, a pytest marker, an NUnit Property or Category, a JUnit Tag), so the test and the manual test case can be found from each other. Give the test's full name, as the framework reports it, in test_name.`,
+      "",
+    )
+  }
+  if (opts.knownDefect) {
+    const d = opts.knownDefect
+    const bug = d.bug ? `${d.bug.label}${d.bug.url ? ` (${d.bug.url})` : ""}` : testCase ? `the defect found in test case ${testCase.id}` : "the defect"
+    md.push(
+      "## Known defect: write the test for the correct behaviour",
+      "",
+      `The browser agent did every step, and the application did not do what the test case expects: ${d.reason}`,
+      bug === "the defect" ? "" : `It is tracked as ${bug}.`,
+      "",
+      "Write the test from the steps below as for any run, and assert the test case's expected results, the correct behaviour, not what the application shows now. Then mark the test as an expected failure with the framework's own mechanism, naming the defect: Playwright `test.fail()` with an annotation of type issue, pytest `@pytest.mark.xfail(strict=True, reason=...)`, JUnit 5 or NUnit with the repository's convention for known failures. It then passes while the defect is there and fails once the defect is fixed, which tells the team to remove the marker. When the framework has no expected-failure mechanism, skip the test with the defect as the reason.",
+      "ForgeQE runs it: the run passes when the marked assertion fails for the defect's reason. Do not weaken the assertion to make it pass.",
+      "",
+    )
+  }
+  md.push("## The path the browser agent took, in order", "")
+  const leftOut = run.memory?.left_out || []
+  if (leftOut.length) {
+    md.push(
+      `Only actions that changed the page are listed. ${leftOut.length} ${leftOut.length === 1 ? "action" : "actions"} that changed nothing (clicks that missed, scripts that only read the page) ${leftOut.length === 1 ? "was" : "were"} left out; the full trace is in trace.md and steps.json.`,
+      "",
+    )
+  }
+  if (steps.some((s) => verifiedLocators(s.locators).length)) {
+    md.push("Locators marked ✓ found exactly the acted-on element (the control itself, not an icon inside it) on the live page while the run was there.", "")
+  }
+  if (steps.some((s) => s.note)) {
+    md.push(
+      "Each \"Browser agent\" line is the agent's own note from the step that performed the steps under it: what it saw on the page and what it set out to do. It tells the flow the goal asks for apart from what this run met on the way, such as a pop-up or banner that covered the page and the steps redone after it.",
+      "",
+    )
+  }
+  const slices = stepSlices(steps, opts.replay)
+  if (slices.size) {
+    md.push(
+      "Under a step, \"on the page\" is its element in Playwright's snapshot of that page from ForgeQE's replay (roles and accessible names): the section it sits in and its neighbours, the element marked. Use it to choose locators and assertions instead of opening the page.",
+      "",
+    )
+  }
+  md.push(...stepsSection(steps, slices))
+  const overlays = overlaysSection(steps)
+  if (overlays.length) md.push("", ...overlays)
+  if (opts.replay) md.push("", ...replaySection(opts.replay))
+  const launch = launchSection(run.browser, opts.replay)
+  if (launch.length) md.push("", ...launch)
+  if (checks.length) md.push("", ...checksSection(checks, opts.replay))
+  const snapshots = Boolean(opts.replay?.passes.some((p) => p.pages?.length))
+  // Page memory is for finding elements the handoff does not give; with every step and check verified it is noise.
+  const elementSteps = steps.filter((s) => ["click", "input", "select"].includes(s.op || ""))
+  const allVerified =
+    elementSteps.every((s) => verifiedLocators(s.locators).length) && checks.every((c) => c.item || verifiedLocators(c.element?.locators).length)
+  if (visited.length && !snapshots && !allVerified) {
+    md.push(
+      "",
+      "## Pages and elements from ForgeQE page memory",
+      "",
+      "Other elements on each page, for assertions (the ones the steps used are listed with the steps). Confidence reflects how uniquely and reliably each locator matched across all runs on that page.",
+      "",
+    )
+    const inSteps = new Set(steps.map((s) => s.best_locator || "").filter(Boolean))
+    for (const page of visited.slice(0, MAX_PAGES)) md.push(...pageSection(page, inSteps), "")
+    if (memDir) md.push(`All pages: ${path.join(memDir, "pages")}`)
+  }
+  const markdown = md.filter((l, i, all) => l !== "" || all[i - 1] !== "").join("\n")
+  const file = path.join(runDir, "handoff.md")
+  writeFileSync(file, `${markdown}\n`)
+  return {
+    goal,
+    success: Boolean(run.success),
+    summary: run.summary || "",
+    finalUrl: run.final_url || "",
+    markdown,
+    file,
+    steps: steps.length,
+    pages: snapshots || allVerified ? 0 : Math.min(visited.length, MAX_PAGES),
+    checks: checks.length,
+  }
+}