@bugmole/cli 0.4.0 → 0.5.0

package/src/runtime/playwright-driver.test.ts

@@ -91,3 +91,148 @@ test("a worker without Playwright's ffmpeg loses the video, not the run", () =>
   assert.equal(isMissingVideoEncoder(new Error("Executable doesn't exist at /ms-playwright/chromium-1234/chrome-linux/chrome")), false);
   assert.equal(isMissingVideoEncoder(new Error("net::ERR_CONNECTION_REFUSED")), false);
 });
+
+// ── Page checks: assertLayout and assertLinks ──
+
+import http from "node:http";
+import type { AddressInfo } from "node:net";
+import { chromium } from "playwright";
+import { brokenStatus, checkLayout, checkLinks } from "./playwright-driver.js";
+
+async function browserOrSkip(t: { skip: (m: string) => void }) {
+  try {
+    return await chromium.launch();
+  } catch {
+    t.skip("Chromium is not installed");
+    return null;
+  }
+}
+
+const CARD = (height: string) => `<!doctype html><meta name="viewport" content="width=device-width">
+<style>body{margin:0;font:16px/1.5 sans-serif}.card{display:flex;gap:30px;${height};padding:0 18px;background:#fff;box-shadow:0 1px 3px #0002;margin:12px}</style>
+<div class="card"><span>icon</span><div><b>UI changes break tests</b><p>Locators and selectors become stale after every redesign of the product.</p></div></div>`;
+
+test("assertLayout catches text running out of a fixed-height card on a phone, and passes when it grows", async (t) => {
+  const browser = await browserOrSkip(t);
+  if (!browser) return;
+  try {
+    const page = await browser.newPage({ viewport: { width: 360, height: 800 } });
+    await page.setContent(CARD("height:60px"));
+    const problems = await checkLayout(page);
+    assert.equal(problems.length, 1);
+    assert.match(problems[0]!, /^Text runs out of its box: “icon UI changes break tests.*” \(div\.card\)/);
+    await page.setContent(CARD("min-height:60px"));
+    assert.deepEqual(await checkLayout(page), []);
+  } finally {
+    await browser.close();
+  }
+});
+
+test("assertLayout catches a page that scrolls sideways and text cut off without an ellipsis", async (t) => {
+  const browser = await browserOrSkip(t);
+  if (!browser) return;
+  try {
+    const page = await browser.newPage({ viewport: { width: 360, height: 800 } });
+    await page.setContent(`<!doctype html><body style="margin:0"><p style="width:600px">A paragraph wider than the phone</p>
+      <div style="width:120px;height:20px;overflow:hidden">A label much too long for its little box here</div>
+      <div style="width:120px;overflow:hidden;white-space:nowrap;text-overflow:ellipsis">An ellipsis is a deliberate cut</div>
+      <div style="overflow-x:auto"><div style="width:900px">A carousel scrolls on purpose</div></div></body>`);
+    const problems = await checkLayout(page);
+    assert.equal(problems.length, 2, problems.join("\n"));
+    assert.match(problems[0]!, /^The page scrolls sideways: it is 600px wide on a 360px screen, because of “A paragraph wider than the phone” \(p\)/);
+    assert.match(problems[1]!, /^Text is cut off: “A label much too long/);
+  } finally {
+    await browser.close();
+  }
+});
+
+test("assertLinks reports links that don't answer, and doesn't count robots being turned away elsewhere", async (t) => {
+  assert.equal(brokenStatus(404, true), true);
+  assert.equal(brokenStatus(403, true), true);
+  assert.equal(brokenStatus(403, false), false);
+  assert.equal(brokenStatus(429, false), false);
+  assert.equal(brokenStatus(410, false), true);
+  assert.equal(brokenStatus(503, false), true);
+  const browser = await browserOrSkip(t);
+  if (!browser) return;
+  const unsafeHits: string[] = [];
+  const server = http.createServer((req, res) => {
+    if (req.url === "/") {
+      res.setHeader("content-type", "text/html");
+      res.end(`<a href="/ok">ok</a><a href="/gone">gone</a><a href="/ok#part">same page</a><a href="mailto:a@b.c">mail</a>
+        <a href="/api/auth/logout">Sign out</a><a href="/items/9?action=delete">x</a>`);
+    } else if (req.url === "/api/auth/logout" || req.url?.includes("delete")) { unsafeHits.push(req.url); res.end("bye"); }
+    else if (req.url === "/ok") res.end("fine");
+    else { res.statusCode = 404; res.end("no"); }
+  });
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+  try {
+    const page = await browser.newPage();
+    await page.goto(`http://127.0.0.1:${(server.address() as AddressInfo).port}/`);
+    const broken = await checkLinks(page, false);
+    assert.deepEqual(broken.map((b) => b.replace(/^http:\/\/127\.0\.0\.1:\d+/, "")), ["/gone (404)"]);
+    assert.deepEqual(unsafeHits, [], "a link check must never sign out or delete");
+  } finally {
+    await browser.close();
+    server.close();
+  }
+});
+
+test("flows can ask for the page checks by name", () => {
+  const flow = parseMaestroStyleFlow("url: https://example.com\n---\n- launchApp\n- assertLayout\n- assertLinks\n- assertLinks:\n    external: true\n");
+  assert.deepEqual(flow.steps.slice(1), [{ type: "assertLayout" }, { type: "assertLinks", external: false }, { type: "assertLinks", external: true }]);
+});
+
+test("assertLayout also checks with a phone's larger text, and restores the page afterwards", async (t) => {
+  const browser = await browserOrSkip(t);
+  if (!browser) return;
+  try {
+    const page = await browser.newPage({ viewport: { width: 412, height: 800 } });
+    // Fits at normal size with a little room; not once text is 30% larger.
+    await page.setContent(`<!doctype html><body style="margin:0;font:16px/20px sans-serif">
+      <div style="height:48px;background:#eee;margin:8px"><b>Important flows get missed</b><br>Journeys are not tested.</div></body>`);
+    const problems = await checkLayout(page);
+    assert.equal(problems.length, 1, problems.join("\n"));
+    assert.match(problems[0]!, /^Text runs out of its box: .* with text 130% \(a phone's larger font setting\)$/);
+    assert.equal(await page.evaluate(`getComputedStyle(document.querySelector("b")).fontSize`), "16px");
+    assert.deepEqual(await checkLayout(page, 1), []);
+  } finally {
+    await browser.close();
+  }
+});
+
+test("a page too tall for one screenshot still gets evidence, and its flow isn't failed for it", async () => {
+  const { screenshotWholePage } = await import("./playwright-driver.js");
+  const shots: Array<boolean | undefined> = [];
+  const page = {
+    screenshot: async (options: { fullPage?: boolean }) => {
+      shots.push(options.fullPage);
+      if (options.fullPage) throw new Error("page.screenshot: Cannot take screenshot larger than 32767 pixels on any dimension");
+    },
+  };
+  const log: string[] = [];
+  await screenshotWholePage(page as never, "/tmp/x.png", log);
+  assert.deepEqual(shots, [true, false]);
+  assert.match(log[0]!, /too tall for one screenshot/);
+  const broken = { screenshot: async () => { throw new Error("Target closed"); } };
+  await assert.rejects(screenshotWholePage(broken as never, "/tmp/x.png"), /Target closed/);
+});
+
+test("assertClickable scrolls to a button below the fold, but still fails one that is covered", async (t) => {
+  const browser = await browserOrSkip(t);
+  if (!browser) return;
+  try {
+    const { waitForClickable } = await import("./playwright-driver.js");
+    const page = await browser.newPage({ viewport: { width: 393, height: 659 } });
+    await page.setContent(`<!doctype html><body style="margin:0">
+      <div style="height:1200px">Tall content</div>
+      <button id="below">Explore this URL</button>
+      <div style="position:relative;height:60px"><button id="covered">Covered</button>
+        <div style="position:absolute;inset:0;background:#fff"></div></div></body>`);
+    await waitForClickable(page, page.locator("#below"), "Explore this URL", 2_000);
+    await assert.rejects(waitForClickable(page, page.locator("#covered"), "Covered", 1_000), /something else is on top/);
+  } finally {
+    await browser.close();
+  }
+});
+

package/src/runtime/playwright-driver.ts

@@ -1,3 +1,4 @@
+import { UNSAFE_LINK } from "./site-discovery.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 import type { Browser, BrowserContext, Locator, Page } from "playwright";
@@ -87,17 +88,30 @@ const visibilityProbe = `(pattern, isRegex) => {
   return false;
 }`;
 
+/** The page moved on while a probe ran in it: try again on the new page. */
+export function isNavigationError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  return /Execution context was destroyed|Cannot find context with specified id|frame was detached|navigat/i.test(message);
+}
+
 async function waitForVisibility(page: Page, text: string, shouldBeVisible: boolean, timeoutMs: number): Promise<void> {
   const isRegex = isPatternText(text);
   const deadline = Date.now() + timeoutMs;
   for (;;) {
     // Compiled inside the page: Playwright evaluates a bare string as an
     // expression and drops the argument, so the probe is passed as data.
-    const visible = await page.evaluate(
-      (args: [string, string, boolean]) =>
-        (new Function(`return (${args[0]})`)() as (pattern: string, isRegex: boolean) => boolean)(args[1], args[2]),
-      [visibilityProbe, text, isRegex] as [string, string, boolean],
-    );
+    // A page that navigates mid-check (a sign-in redirecting to the app)
+    // destroys the context the probe ran in: that's "not yet", not a failure.
+    const visible = await page
+      .evaluate(
+        (args: [string, string, boolean]) =>
+          (new Function(`return (${args[0]})`)() as (pattern: string, isRegex: boolean) => boolean)(args[1], args[2]),
+        [visibilityProbe, text, isRegex] as [string, string, boolean],
+      )
+      .catch((error: unknown) => {
+        if (isNavigationError(error)) return null;
+        throw error;
+      });
     if (visible === shouldBeVisible) return;
     if (Date.now() >= deadline) {
       throw new Error(`Timed out after ${timeoutMs}ms waiting for "${text}" to be ${shouldBeVisible ? "visible" : "hidden"}.`);
@@ -179,9 +193,12 @@ const failureProbe = `() => {
  * mascot, a floating action button, a toast) sitting on top of a link or
  * button and silently swallowing the tap.
  */
-async function waitForClickable(page: Page, locator: Locator, text: string, timeoutMs: number): Promise<void> {
+export async function waitForClickable(page: Page, locator: Locator, text: string, timeoutMs: number): Promise<void> {
   const deadline = Date.now() + timeoutMs;
   for (;;) {
+    // A person scrolls to a button below the fold; only covered or hidden
+    // controls should fail. On a phone's short screen this is most of them.
+    await locator.scrollIntoViewIfNeeded({ timeout: 1_000 }).catch(() => undefined);
     const handle = await locator.elementHandle({ timeout: 1_000 }).catch(() => null);
     const reachable = handle
       ? await page
@@ -200,10 +217,206 @@ async function waitForClickable(page: Page, locator: Locator, text: string, time
   }
 }
 
+/**
+ * What a person notices first when a page doesn't fit the screen: it scrolls
+ * sideways, text runs out of the card it sits in, or text is cut off with no
+ * ellipsis. Runs in the page; returns problems in plain words.
+ */
+export const layoutProbe = `() => {
+  const W = document.documentElement.clientWidth;
+  const problems = [];
+  const skip = (e) => e.closest("svg, pre, code, [aria-hidden=true], dialog:not([open])");
+  const shown = (e, s) => {
+    const r = e.getBoundingClientRect();
+    return r.width > 2 && r.height > 2 && s.display !== "none" && s.visibility !== "hidden" && Number(s.opacity) !== 0;
+  };
+  // What a developer searches for: the text, then the element and its first classes.
+  const label = (e) => {
+    const t = (e.innerText || "").replace(/\\s+/g, " ").trim();
+    const cls = typeof e.className === "string" ? e.className.trim().split(/\\s+/).filter(Boolean).slice(0, 2) : [];
+    const where = e.tagName.toLowerCase() + cls.map((c) => "." + c).join("");
+    return (t ? "\u201c" + (t.length > 48 ? t.slice(0, 47) + "\u2026" : t) + "\u201d " : "") + "(" + where + ")";
+  };
+  // Pinned to the screen (a chat button, a banner): it can't make the page wider.
+  const pinned = (e) => {
+    for (let a = e; a && a !== document.body; a = a.parentElement) {
+      const p = getComputedStyle(a).position;
+      if (p === "fixed" || p === "sticky") return true;
+    }
+    return false;
+  };
+  // Inside something that scrolls or clips on purpose (a carousel, a code block, a marquee).
+  const contained = (e) => {
+    for (let a = e.parentElement; a && a !== document.body && a !== document.documentElement; a = a.parentElement) {
+      const s = getComputedStyle(a);
+      if (/(hidden|auto|scroll|clip)/.test(s.overflowX + " " + s.overflowY)) return true;
+    }
+    return false;
+  };
+  const boxed = (s) =>
+    (s.backgroundColor !== "rgba(0, 0, 0, 0)" && s.backgroundColor !== "transparent") ||
+    s.backgroundImage !== "none" || s.boxShadow !== "none" ||
+    parseFloat(s.borderTopWidth) + parseFloat(s.borderBottomWidth) + parseFloat(s.borderLeftWidth) + parseFloat(s.borderRightWidth) > 0;
+
+  if (document.documentElement.scrollWidth > W + 1) {
+    let culprit = null;
+    for (const e of document.body.querySelectorAll("*")) {
+      const s = getComputedStyle(e);
+      if (e.closest("svg, [aria-hidden=true]") || !shown(e, s) || contained(e) || pinned(e)) continue;
+      const r = e.getBoundingClientRect();
+      if (r.right > W + 1 && (e.innerText || "").trim()) culprit = e; // the deepest one wins
+    }
+    problems.push("The page scrolls sideways: it is " + document.documentElement.scrollWidth + "px wide on a " + W + "px screen" + (culprit ? ", because of " + label(culprit) : ""));
+  }
+  for (const e of document.body.querySelectorAll("*")) {
+    const s = getComputedStyle(e);
+    if (s.display === "inline" || skip(e) || !shown(e, s)) continue;
+    if (!(e.innerText || "").trim()) continue;
+    if (boxed(s) && s.overflowY === "visible" && e.scrollHeight > e.clientHeight + 1 && e.clientHeight > 0) {
+      problems.push("Text runs out of its box: " + label(e) + " overflows by " + (e.scrollHeight - e.clientHeight) + "px");
+      continue;
+    }
+    if (boxed(s) && s.overflowX === "visible" && e.scrollWidth > e.clientWidth + 1 && e.clientWidth > 0) {
+      problems.push("Text runs out of its box sideways: " + label(e) + " overflows by " + (e.scrollWidth - e.clientWidth) + "px");
+      continue;
+    }
+    const clips = /(hidden|clip)/.test(s.overflowX + " " + s.overflowY);
+    const clamped = s.textOverflow === "ellipsis" || (s.webkitLineClamp && s.webkitLineClamp !== "none");
+    if (clips && !clamped && e.children.length === 0 && e.clientWidth > 2 && e.clientHeight > 2 &&
+        (e.scrollWidth > e.clientWidth + 2 || e.scrollHeight > e.clientHeight + 2)) {
+      problems.push("Text is cut off: " + label(e));
+    }
+  }
+  return [...new Set(problems)];
+}`;
+
+/**
+ * Enlarges (or restores) every element's text by `factor`, the way a phone's
+ * font-size setting does: text grows, the boxes the page gave it don't. All
+ * sizes are read before any is changed, so nested sizes don't compound.
+ */
+const textScaleProbe = `(factor) => {
+  const key = "__bugmoleTextScale";
+  const elements = Array.from(document.querySelectorAll("body, body *"));
+  if (factor === 1) {
+    for (const e of elements) {
+      const saved = e[key];
+      if (!saved) continue;
+      e.style.fontSize = saved.fontSize;
+      e.style.lineHeight = saved.lineHeight;
+      delete e[key];
+    }
+    return;
+  }
+  const sizes = elements.map((e) => {
+    const s = getComputedStyle(e);
+    return [parseFloat(s.fontSize), s.lineHeight.endsWith("px") ? parseFloat(s.lineHeight) : null];
+  });
+  elements.forEach((e, i) => {
+    e[key] = { fontSize: e.style.fontSize, lineHeight: e.style.lineHeight };
+    const [font, line] = sizes[i];
+    if (font) e.style.fontSize = font * factor + "px";
+    if (line) e.style.lineHeight = line * factor + "px";
+  });
+}`;
+
+async function layoutProblems(page: Page): Promise<string[]> {
+  return page.evaluate((source: string) => (new Function(`return (${source})`)() as () => string[])(), layoutProbe);
+}
+
+async function scaleText(page: Page, factor: number): Promise<void> {
+  await page.evaluate(([source, value]: [string, number]) => (new Function(`return (${source})`)() as (f: number) => void)(value), [textScaleProbe, factor] as [string, number]);
+}
+
+/** Larger text, as set on many phones (Android's font size; WCAG asks pages to cope with up to 200%). */
+export const LARGE_TEXT = 1.3;
+
+/** Layout problems at normal text size, then those that appear only with larger text. */
+export async function checkLayout(page: Page, largeText = LARGE_TEXT): Promise<string[]> {
+  const normal = await layoutProblems(page);
+  if (!largeText || largeText === 1) return normal;
+  await scaleText(page, largeText);
+  try {
+    const large = await layoutProblems(page);
+    const label = `with text ${Math.round(largeText * 100)}% (a phone's larger font setting)`;
+    // The same box overflowing by more pixels isn't a new problem.
+    const same = (problem: string) => problem.replace(/\d+px/g, "");
+    const seen = new Set(normal.map(same));
+    return [...normal, ...large.filter((problem) => !seen.has(same(problem))).map((problem) => `${problem}, ${label}`)];
+  } finally {
+    await scaleText(page, 1);
+  }
+}
+
+/** A link a check must not follow: signing out, deleting, unsubscribing (by its text or address). */
+export function isUnsafeLink(href: string, text: string): boolean {
+  let path = href;
+  try {
+    const url = new URL(href);
+    path = `${url.pathname} ${url.search}`;
+  } catch {
+    // keep the raw href
+  }
+  return UNSAFE_LINK.test(text) || UNSAFE_LINK.test(path.replace(/[/_?=&.-]+/g, " "));
+}
+
+/** Answers that mean a link is broken, not that the site turned a robot away. */
+export function brokenStatus(status: number, sameSite: boolean): boolean {
+  if (sameSite) return status >= 400;
+  return status === 404 || status === 410 || status >= 500;
+}
+
+/** Requests every link on the page (same-site only unless `external`). Returns the broken ones. */
+export async function checkLinks(page: Page, external: boolean, limit = 80): Promise<string[]> {
+  const origin = new URL(page.url()).origin;
+  const links = (await page.evaluate(
+    `Array.from(document.querySelectorAll("a[href]")).map((a) => [a.href, (a.innerText || a.getAttribute("aria-label") || "").trim()])`,
+  )) as Array<[string, string]>;
+  // Requesting a link is visiting it: never sign out, delete or unsubscribe
+  // on the way (the same links discovery steers clear of).
+  const safe = links.filter(([href, text]) => !isUnsafeLink(href, text)).map(([href]) => href);
+  const targets = [...new Set(safe.filter((h) => /^https?:/i.test(h)).map((h) => h.split("#")[0]!))]
+    .filter((h) => external || new URL(h).origin === origin)
+    .slice(0, limit);
+  const request = page.context().request;
+  const broken: string[] = [];
+  const queue = [...targets];
+  const worker = async () => {
+    for (let url = queue.shift(); url; url = queue.shift()) {
+      const sameSite = new URL(url).origin === origin;
+      try {
+        let response = await request.head(url, { timeout: 10_000, maxRedirects: 5, failOnStatusCode: false });
+        // Plenty of servers answer HEAD badly; a GET is what a visitor sends.
+        if (response.status() >= 400) response = await request.get(url, { timeout: 10_000, maxRedirects: 5, failOnStatusCode: false });
+        if (brokenStatus(response.status(), sameSite)) broken.push(`${url} (${response.status()})`);
+      } catch (error) {
+        if (sameSite) broken.push(`${url} (no answer: ${error instanceof Error ? error.message.split("\n")[0] : String(error)})`);
+      }
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(6, targets.length) }, worker));
+  return broken.sort();
+}
+
 /**
  * Candidate locators in the order a person resolves a target: the control they
  * can name, then the field labelled that way, then anything reading that way.
  */
+/**
+ * A screenshot of the whole page, or of the screen when the page is taller
+ * than the browser can capture in one image (32,767px in WebKit): evidence
+ * must never turn a passing flow into a failure.
+ */
+export async function screenshotWholePage(page: Page, file: string, log?: string[]): Promise<void> {
+  try {
+    await page.screenshot({ path: file, fullPage: true });
+  } catch (error) {
+    if (!/larger than \d+ pixels|too large|maximum/i.test(error instanceof Error ? error.message : String(error))) throw error;
+    log?.push("The page is too tall for one screenshot; captured the screen instead.");
+    await page.screenshot({ path: file, fullPage: false });
+  }
+}
+
 /** Playwright needs its own ffmpeg build to write a video; nothing else does. */
 export function isMissingVideoEncoder(error: unknown): boolean {
   const message = error instanceof Error ? error.message : String(error);
@@ -378,7 +591,7 @@ export class PlaywrightDriver implements AppDriver {
 
       const capture = async (name: string) => {
         const screenshotPath = path.join(artifactsDir, `${name.replace(/[^a-z0-9_-]+/gi, "-")}.png`);
-        await page.screenshot({ path: screenshotPath, fullPage: true });
+        await screenshotWholePage(page, screenshotPath, log);
         screenshots.push({ path: screenshotPath, name: path.basename(screenshotPath) });
         return screenshotPath;
       };
@@ -431,6 +644,22 @@ export class PlaywrightDriver implements AppDriver {
             await waitForClickable(page, target, step.text, step.timeoutMs ?? stepTimeoutMs);
             return;
           }
+          case "assertLayout": {
+            const problems = await checkLayout(page);
+            if (problems.length) {
+              await capture(`layout-${String(Date.now()).slice(-6)}`).catch(() => undefined);
+              const shown = problems.slice(0, 6).map((problem) => `- ${problem}`).join("\n");
+              throw new Error(`The page doesn't fit a ${page.viewportSize()?.width ?? "?"}px-wide screen:\n${shown}${problems.length > 6 ? `\n…and ${problems.length - 6} more` : ""}`);
+            }
+            return;
+          }
+          case "assertLinks": {
+            const broken = await checkLinks(page, step.external);
+            if (broken.length) {
+              throw new Error(`${broken.length} broken link(s) on ${page.url()}:\n${broken.slice(0, 10).map((link) => `- ${link}`).join("\n")}`);
+            }
+            return;
+          }
           case "scrollUntilVisible": {
             const target = await resolveTapTarget(page, step.text, 0);
             if (!target) throw new Error(`No element matching "${step.text}" to scroll to.`);
@@ -582,7 +811,7 @@ export class PlaywrightDriver implements AppDriver {
         }
         if (failurePage) {
           const failurePath = path.join(artifactsDir, "playwright-failure.png");
-          await failurePage.screenshot({ path: failurePath, fullPage: true });
+          await screenshotWholePage(failurePage, failurePath);
           artifacts.push({ path: failurePath, contentType: "image/png", name: "playwright-failure.png" });
         }
       } catch {

package/src/runtime/run-job.test.ts

@@ -0,0 +1,21 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { executeRegistryRun } from "./run-job.js";
+
+test("only a passing run promotes the journey it ran, and before it reports done", async () => {
+  for (const status of ["success", "partial", "error"] as const) {
+    const order: string[] = [];
+    const client = { updateRun: async (_id: string, update: Record<string, unknown>) => { if (update.eventType === "completed") order.push("completed"); return {}; } };
+    const run = { id: `run_${status}`, planId: "discovered-home", journeyId: "discovered-home", status: "claimed" } as never;
+    await executeRegistryRun({}, client as never, run, {
+      projectId: "demo",
+      workerId: "w1",
+      execute: (async () => ({ status, stepsExecuted: 1, stepsPassed: 1, stepsFailed: 0 })) as never,
+      stabilize: async (_cfg, promoted) => {
+        order.push(`stabilize:${promoted.id}`);
+        return promoted.journeyId ?? null;
+      },
+    });
+    assert.deepEqual(order, status === "success" ? ["stabilize:run_success", "completed"] : ["completed"], status);
+  }
+});

package/src/runtime/run-job.ts

@@ -8,6 +8,7 @@ import { normalizeTargets } from "./browser-matrix.js";
 import { execute } from "./executor.js";
 import type { FailureAnalysis, FailureContext } from "./failure-analysis.js";
 import { loadDeviceCloudAccess, type DeviceCloudAccess } from "./device-clouds/index.js";
+import { stabilizeAfterPassingRun } from "./journey-editor.js";
 
 /** The registry expires a claim 60s after its last update, so a running run renews it well inside that. */
 export const RUN_HEARTBEAT_MS = 30_000;
@@ -56,6 +57,8 @@ export type ExecuteRunOptions = {
   heartbeatMs?: number;
   /** Loads device-cloud credentials and app builds, for runs that target cloud devices. */
   loadDeviceAccess?: () => Promise<DeviceCloudAccess>;
+  /** Promotes the journey a passing run proved; replaceable in tests. */
+  stabilize?: typeof stabilizeAfterPassingRun;
 };
 
 /** How a worker fetches a run's device access from the registry. */
@@ -112,6 +115,11 @@ export async function executeRegistryRun(
       },
     });
     clearInterval(heartbeat);
+    // Before reporting done, so a dashboard that reloads the graph on
+    // completion already sees the flow this run proved.
+    if (result.status === "success") {
+      await (options.stabilize ?? stabilizeAfterPassingRun)(cfg, run).catch(() => null);
+    }
     await client.updateRun(run.id, {
       workerId,
       status: result.status === "success" ? "success" : result.status === "partial" ? "partial" : "error",

package/src/runtime/site-discovery.test.ts

@@ -5,7 +5,7 @@ import os from "node:os";
 import path from "node:path";
 import test from "node:test";
 import { chromium } from "playwright";
-import { discoverableRoute, discoverSite, flowsFor, slugify } from "./site-discovery.js";
+import { discoverableRoute, discoverSite, flowsFor, slugify, stoppedAtSignIn } from "./site-discovery.js";
 import { discoveryUrl, runDiscoveryTask } from "./discovery-task.js";
 import { PlaywrightDriver } from "./playwright-driver.js";
 import { startLocalRegistryStub } from "./local-registry-stub.js";
@@ -118,6 +118,80 @@ test("explores a site from its URL like a visitor, and the flows it writes pass"
   });
 });
 
+test("explores a signed-in app from a saved session, and stays inside it", async (t) => {
+  if (!(await chromiumInstalled())) {
+    t.skip("Chromium is not installed");
+    return;
+  }
+  const hits: string[] = [];
+  const signedIn: Record<string, string> = {
+    // "Test plans" routes on the client, like a single-page app: the address
+    // and the page change some time after the click. "Billing" and "Sign out"
+    // only exist once the account menu is opened.
+    "/": `<h1>Overview</h1><a href="/plans" id="plans">Test plans</a><a href="/account/sign-out">Account</a><a href="/connect">Connect GitHub</a>
+      <a href="/manage/domains"><strong>Domains</strong> <span>Verify the sites Bugmole Cloud is allowed to run against.</span></a>
+      <button aria-expanded="false" id="account"><span aria-hidden="true">A</span> <strong>Account</strong> <small>menu</small></button><div id="menu"></div>
+      <script>
+        document.getElementById("plans").addEventListener("click", (event) => {
+          event.preventDefault();
+          setTimeout(() => {
+            history.pushState(null, "", "/plans" + location.search);
+            document.querySelector("h1").textContent = "Test plans";
+          }, 600);
+        });
+        const account = document.getElementById("account");
+        account.addEventListener("click", () => {
+          const open = account.getAttribute("aria-expanded") !== "true";
+          account.setAttribute("aria-expanded", String(open));
+          document.getElementById("menu").innerHTML = open ? '<a href="/billing">Billing</a><a href="/sign-out">Sign out</a>' : "";
+        });
+        document.addEventListener("keydown", (event) => { if (event.key === "Escape" && account.getAttribute("aria-expanded") === "true") account.click(); });
+      </script>`,
+    "/plans": `<h1>Test plans</h1><a href="/">Overview</a>`,
+    "/billing": `<h1>Billing</h1><a href="/">Overview</a>`,
+    "/manage/domains": `<h1>Domains</h1><a href="/">Overview</a>`,
+  };
+  const server = http.createServer((request, response) => {
+    const route = new URL(request.url ?? "/", "http://x").pathname;
+    hits.push(route);
+    if (!/session=ok/.test(request.headers.cookie ?? "")) {
+      response.writeHead(307, { location: "/login" });
+      return response.end();
+    }
+    // Same-origin link that hands off to another site, like an install redirect.
+    if (route === "/connect") {
+      response.writeHead(302, { location: `http://localhost:${(server.address() as { port: number }).port}/elsewhere` });
+      return response.end();
+    }
+    const body = signedIn[route];
+    response.writeHead(body ? 200 : 404, { "content-type": "text/html" });
+    response.end(`<!doctype html><html><body>${body ?? "Not found"}</body></html>`);
+  });
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-signed-in-"));
+  try {
+    const baseUrl = `http://127.0.0.1:${(server.address() as { port: number }).port}/`;
+    const storageState = path.join(directory, "state.json");
+    await fs.writeFile(storageState, JSON.stringify({
+      cookies: [{ name: "session", value: "ok", domain: "127.0.0.1", path: "/", expires: -1, httpOnly: true, secure: false, sameSite: "Lax" }],
+      origins: [],
+    }));
+    const result = await discoverSite(`${baseUrl}?project=p1`, { dwellMs: 0, storageState, openEachPage: true });
+    assert.deepEqual(result.pages.map((page) => page.route).sort(), ["/", "/billing", "/manage/domains", "/plans"]);
+    assert.equal(result.pages.find((page) => page.route === "/plans")?.heading, "Test plans", "waits for a client-side page to render");
+    assert.deepEqual(result.pages.find((page) => page.route === "/billing")?.path, ["Account menu", "Billing"]);
+    assert.ok(!hits.includes("/account/sign-out"), "a sign-out address is never opened, whatever its label");
+    assert.ok(!hits.includes("/sign-out"), "nor a sign-out link inside a menu");
+    assert.ok(result.events.some((event) => event.text === "“Connect GitHub” leaves the app"));
+    const plans = result.flows.find((flow) => flow.route === "/plans")!;
+    assert.match(plans.content, new RegExp(`^url: ${baseUrl}plans\\?project=p1\\n`), "the base URL's app context is kept");
+    assert.doesNotMatch(plans.content, /tapOn/, "each flow opens its page directly");
+  } finally {
+    server.close();
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+});
+
 test("a discovery task streams progress, then publishes plans and a valid journey graph", async (t) => {
   if (!(await chromiumInstalled())) {
     t.skip("Chromium is not installed");
@@ -166,3 +240,63 @@ test("a discovery task streams progress, then publishes plans and a valid journe
     }
   });
 });
+
+test("a crawl that only reached sign-in screens is reported as stopped at sign-in", () => {
+  const page = (extra: Record<string, unknown>) => ({ route: "/login", url: "https://app.test/login", title: "App", path: [], links: [], forms: [], ...extra });
+  assert.equal(stoppedAtSignIn({ pages: [page({ heading: "Welcome back", controls: ["Continue with Aegis"] })] }), true);
+  assert.equal(stoppedAtSignIn({ pages: [page({ forms: [{ name: "Log in", fields: [{ label: "Email", type: "email", required: true }, { label: "Password", type: "password", required: true }] }] })] }), true);
+  assert.equal(stoppedAtSignIn({ pages: [page({ heading: "Pricing" })] }), false, "a page that isn't a sign-in screen");
+  assert.equal(stoppedAtSignIn({ pages: [] }), false, "nothing explored is a different failure");
+  assert.equal(
+    stoppedAtSignIn({ pages: [page({ heading: "Welcome back" }), page({ route: "/", heading: "Home" }), page({ route: "/a", heading: "A" })] }),
+    false,
+    "a public site that also has a sign-in page",
+  );
+});
+
+test("an app that opens on a sign-in button: discovery records the button, says it stopped, and skips AI", async (t) => {
+  if (!(await chromiumInstalled())) {
+    t.skip("Chromium is not installed");
+    return;
+  }
+  const server = http.createServer((_request, response) => {
+    response.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+    response.end("<!doctype html><html><head><title>Bugmole</title></head><body><h1>Welcome back</h1><p>Sign in or create your account.</p><button>Continue with Aegis →</button></body></html>");
+  });
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const baseUrl = `http://127.0.0.1:${(server.address() as { port: number }).port}/`;
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-sign-in-wall-"));
+  const stub = await startLocalRegistryStub({ directory: path.join(directory, "registry") });
+  try {
+    const seen = await discoverSite(baseUrl, { dwellMs: 0 });
+    assert.deepEqual(seen.pages[0].controls, ["Continue with Aegis →"]);
+    assert.equal(stoppedAtSignIn(seen), true);
+
+    const client = new ControlPlaneClient({ registryUrl: stub.origin, apiKey: "local", projectId: "demo" });
+    const { task } = await client.createTask({ title: "Explore with AI app", description: `Explore ${baseUrl} like a first-time visitor, then have AI write multi-page journeys.`, taskType: "discovery", idempotencyKey: "discover-wall" });
+    const cfg = {
+      project: { id: "demo" },
+      runtime: { spec_dir: path.join(directory, "spec"), artifacts_dir: path.join(directory, "artifacts") },
+      storage: { provider: "local" },
+    };
+    const updates: Array<Record<string, unknown>> = [];
+    await runDiscoveryTask(cfg, {
+      claimTask: client.claimTask.bind(client),
+      publishPlan: client.publishPlan.bind(client),
+      updateTask: async (id: string, update: Record<string, unknown>) => {
+        updates.push(update);
+        return client.updateTask(id, update);
+      },
+    }, task, "worker-1");
+    const final = updates.at(-1)!;
+    assert.equal(final.status, "completed", String(final.errorMessage));
+    assert.match(String(final.completionSummary), /Stopped at a sign-in page/);
+    const texts = (final.continuation as { events: Array<{ text: string }> }).events.map((event) => event.text);
+    assert.ok(texts.some((text) => text.startsWith("Stopped at a sign-in page")), texts.join("\n"));
+    assert.ok(!texts.some((text) => /AI/.test(text) && !text.startsWith("Stopped")), "the AI step never ran");
+  } finally {
+    await stub.close();
+    server.close();
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+});