debutly 0.1.0 → 0.3.0

package/src/browser/execute.ts

@@ -1,5 +1,6 @@
 import type { Locator, Page } from "playwright";
 import type { Action, ActionResult, InteractiveElement, Observation } from "../types";
+import { OPEN_LAYER_SCRIPT } from "./observe";
 import { sampleFiles, sampleFor, type SampleKind } from "./samples";
 
 const DESTRUCTIVE = /\b(delete|remove|destroy|deactivate|close account|cancel (my )?(subscription|account))\b/i;
@@ -37,6 +38,47 @@ export interface ExecuteOptions {
 const ARROW_KEY_ITEMS = new Set(["option", "menuitem", "menuitemcheckbox", "menuitemradio", "tab", "treeitem", "radio", "input:radio"]);
 // What Space presses; Enter presses the rest. Text fields and selects are only focused.
 const SPACE_KEY = new Set(["checkbox", "input:checkbox", "switch"]);
+// Buttons take Enter and Space alike, so a keyboard user who gets nothing from Enter tries Space.
+const BUTTON_ROLE = /^(button|input:(submit|button|reset|image))$/;
+/** How long to watch for Enter's effect before trying Space. */
+const ENTER_SETTLE_MS = 1_000;
+
+/**
+ * Presses Enter on the focused button; if nothing happened that a person would notice (the page
+ * sent nothing, kept its address and looks exactly the same), presses Space, as a keyboard user
+ * would. True when Space then did what Enter didn't: Twenty's set-up "Continue" ignores Enter and
+ * goes on with Space, and a keyboard-only agent that knew only Enter gave up there twice
+ * (2026-10-24). It goes by how the page looks, not its text, so a toggle whose change is only
+ * visual is never pressed twice.
+ */
+async function pressEnterThenSpace(page: Page, id: number): Promise<boolean> {
+  const look = () => page.screenshot({ animations: "disabled", timeout: 5_000 }).catch(() => undefined);
+  const url = page.url();
+  // The first key press on a page draws the focus ring; Shift, which presses nothing, draws it
+  // first, or Enter would always seem to have changed the page.
+  await page.keyboard.press("Shift");
+  const before = await look();
+  let sent = 0;
+  const count = () => sent++;
+  page.on("request", count);
+  try {
+    await page.keyboard.press("Enter");
+    await page.waitForTimeout(ENTER_SETTLE_MS);
+  } finally {
+    page.off("request", count);
+  }
+  const afterEnter = sent || page.url() !== url || !before ? undefined : await look();
+  if (!before || !afterEnter || !afterEnter.equals(before)) return false;
+  // Space goes to whatever has focus: only to the button that was checked before Enter, never to
+  // something Enter moved focus to unseen.
+  const stillFocused = await page.evaluate((target) => document.activeElement?.getAttribute("data-debutly-id") === target, String(id));
+  if (!stillFocused) return false;
+  await page.keyboard.press("Space");
+  await page.waitForTimeout(ENTER_SETTLE_MS);
+  if (page.url() !== url) return true;
+  const afterSpace = await look();
+  return !!afterSpace && !afterSpace.equals(before);
+}
 const FOCUS_ONLY = /^(input:(text|email|password|number|search|tel|url|date|time|datetime-local|month|week)|textarea|select|combobox)$/;
 
 // Is the focused element entirely hidden behind something else? Checks its middle and four points
@@ -44,6 +86,8 @@ const FOCUS_ONLY = /^(input:(text|email|password|number|search|tel|url|date|time
 const focusCoveredScript = (id: number) => `(() => {
   const el = document.querySelector('[data-debutly-id="${id}"]');
   if (!el) return null;
+  // A dropdown's own open list may be drawn over it, by design (2026-11-01).
+  if (el.getAttribute('aria-expanded') === 'true') return null;
   const r = el.getBoundingClientRect();
   const points = [[0.5, 0.5], [0.1, 0.1], [0.9, 0.1], [0.1, 0.9], [0.9, 0.9]].map(([fx, fy]) => [r.left + r.width * fx, r.top + r.height * fy]);
   let cover = null;
@@ -53,22 +97,92 @@ const focusCoveredScript = (id: number) => `(() => {
     if (!hit || hit === el || el.contains(hit) || hit.contains(el)) return null;
     cover = cover || hit;
   }
-  if (!cover) return 'the edge of the window';
+  if (!cover) return '${EDGE_OF_WINDOW}';
   const classes = typeof cover.className === 'string' ? cover.className.trim().split(/\\s+/).filter(Boolean).slice(0, 2) : [];
   const text = (cover.innerText || '').replace(/\\s+/g, ' ').trim().slice(0, 50);
   return cover.tagName.toLowerCase() + (cover.id ? '#' + cover.id : '') + classes.map((c) => '.' + c).join('') + (text ? ' ("' + text + '")' : '');
 })()`;
 
 class NotByKeyboard extends Error {}
+/** A control a person can't use at all right now, whatever they use: said as it is. */
+class Unusable extends Error {}
 
 /** Moves focus to the control as Tab would; refuses one that isn't in the tab order. Returns what hides it, if anything. */
 async function focusByKeyboard(page: Page, locator: Locator, id: number): Promise<string | undefined> {
-  const tabbable = await locator.evaluate((node) => (node as HTMLElement).tabIndex >= 0 && !node.closest("[inert]"), undefined, { timeout: 5_000 });
-  if (!tabbable) throw new NotByKeyboard(`${NOT_BY_KEYBOARD}: it isn't in the tab order`);
+  const reach = await locator.evaluate(
+    (node) => {
+      const el = node as HTMLElement & { disabled?: boolean };
+      if (el.disabled === true || el.getAttribute("aria-disabled") === "true") return "disabled";
+      return el.tabIndex >= 0 && !el.closest("[inert]") ? "tabbable" : "untabbable";
+    },
+    undefined,
+    { timeout: 5_000 },
+  );
+  // A disabled button can't take focus, so Enter went to whatever had it, and the agent was told
+  // only that nothing changed; it pressed "Create account" again and gave up (2026-10-24). A mouse
+  // click on it is told it is disabled; so is a key press.
+  if (reach === "disabled") throw new Unusable(UNUSABLE.disabled);
+  if (reach === "untabbable") throw new NotByKeyboard(`${NOT_BY_KEYBOARD}: it isn't in the tab order`);
   await locator.focus({ timeout: 5_000 });
+  const hidden = (await page.evaluate(focusCoveredScript(id))) as string | null;
+  // A page that scrolls smoothly brings the focused control into view a moment later: measured at
+  // once, a Continue button in plain sight was reported hidden by the edge of the window.
+  if (hidden !== EDGE_OF_WINDOW) return hidden ?? undefined;
+  await page.waitForTimeout(SMOOTH_SCROLL_MS);
   return ((await page.evaluate(focusCoveredScript(id))) as string | null) ?? undefined;
 }
 
+const EDGE_OF_WINDOW = "the edge of the window";
+
+// What the browser itself says when a submit finds a field invalid ("Please lengthen this text to
+// 8 characters or more"): a person sees that bubble; it isn't in the page's text, so an agent with
+// a 7-letter password saw nothing happen, and gave up saying sign-up was broken (2026-10-25).
+// Listened for during each action; a string, like SCAN_SCRIPT.
+const LISTEN_INVALID = `(() => {
+  if (window.__debutlyInvalid) return;
+  window.__debutlyInvalid = [];
+  document.addEventListener('invalid', (e) => {
+    const el = e.target;
+    const label = (el.labels && el.labels[0] && el.labels[0].textContent) || el.getAttribute('aria-label') || el.getAttribute('placeholder') || el.name || 'a field';
+    window.__debutlyInvalid.push('"' + label.replace(/\\s+/g, ' ').trim().slice(0, 60) + '": ' + el.validationMessage);
+  }, true);
+})()`;
+const READ_INVALID = `(() => {
+  const said = window.__debutlyInvalid || [];
+  window.__debutlyInvalid = [];
+  return [...new Set(said)].slice(0, 3);
+})()`;
+/** Long enough for a smooth scroll to finish. */
+const SMOOTH_SCROLL_MS = 600;
+
+/**
+ * Whether a click on the control was taken by something open over the page, which a person uses
+ * or closes first: a dialog, tour step, menu or dropdown list, or the backdrop that dims the page
+ * behind one (an open dropdown can also make the page itself take every click outside it). Says
+ * what is open, or "" when the cover is part of the page: a fixed bar, or an invisible layer over
+ * everything, which a person can't see to close and so stays a finding.
+ */
+const OPEN_OVER_SCRIPT = (id: number) => `(() => {
+  const el = document.querySelector('[data-debutly-id="${id}"]');
+  if (!el) return '';
+  const r = el.getBoundingClientRect();
+  const hit = document.elementFromPoint(Math.min(Math.max(r.left + r.width / 2, 0), innerWidth - 1), Math.min(Math.max(r.top + r.height / 2, 0), innerHeight - 1));
+  const open = ${OPEN_LAYER_SCRIPT};
+  if (!hit || hit === document.documentElement || hit === document.body) return open;
+  if (hit.closest('[role="dialog"], [role="alertdialog"], dialog, [aria-modal="true"], [role="listbox"], [role="menu"]')) return open || 'something';
+  const b = hit.getBoundingClientRect();
+  const s = getComputedStyle(hit);
+  const fills = (s.position === 'fixed' || s.position === 'absolute') && b.width >= innerWidth * 0.9 && b.height >= innerHeight * 0.9;
+  const bg = s.backgroundColor;
+  const alpha = bg === 'transparent' ? 0 : bg.startsWith('rgba') ? parseFloat(bg.slice(bg.lastIndexOf(',') + 1)) : 1;
+  const dims = alpha > 0 || (s.backdropFilter && s.backdropFilter !== 'none');
+  return fills && dims ? open || 'something (its backdrop dims the page)' : '';
+})()`;
+
+async function openOver(page: Page, id: number): Promise<string> {
+  return ((await page.evaluate(OPEN_OVER_SCRIPT(id)).catch(() => "")) as string) || "";
+}
+
 // Playwright's timeout message hides the cause in its call log; say it the way a person would notice it.
 export function describeFailure(err: unknown): string {
   const message = err instanceof Error ? err.message : String(err);
@@ -198,6 +312,7 @@ async function pick(page: Page, trigger: Locator, text: string): Promise<void> {
 //   (aria-activedescendant);
 // - Enter in a form field submits its form through the form's default button, which may sit
 //   outside the form (form="…"), or with no button through the form itself;
+// - Space presses the focused button, or ticks the focused box;
 // - an arrow key moves a focused native select to the next option.
 // Each thing the key would set off is listed with every name it goes by (aria-label, the elements
 // aria-labelledby points at, labels, text, value, title) and its data-debutly-id, so the check also
@@ -217,6 +332,7 @@ const keyTargetsScript = (key: string) => `(() => {
     }
     if (e.labels) for (const l of e.labels) names.push(l.textContent);
     if (e.tagName === 'INPUT' || e.tagName === 'BUTTON') names.push(e.value);
+    if (e.tagName === 'INPUT' && e.type === 'image') names.push(e.getAttribute('alt'));
     if (e.tagName !== 'INPUT') names.push(e.innerText);
     targets.push({ id: e.getAttribute('data-debutly-id'), names: names.filter((n) => n && n.trim()) });
   };
@@ -233,6 +349,9 @@ const keyTargetsScript = (key: string) => `(() => {
       add(el);
     }
   }
+  if (key === 'Space' && el.matches('button, summary, input[type="checkbox"], input[type="radio"], input[type="submit"], input[type="button"], input[type="reset"], input[type="image"], [role="button"], [role="checkbox"], [role="switch"], [role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"], [role="option"], [role="tab"]')) {
+    add(el);
+  }
   if ((key === 'ArrowDown' || key === 'ArrowUp') && el.tagName === 'SELECT') {
     const next = el.options[el.selectedIndex + (key === 'ArrowDown' ? 1 : -1)];
     if (next) targets.push({ id: null, names: [next.label] });
@@ -271,6 +390,7 @@ export async function execute(
   opts: ExecuteOptions = {},
 ): Promise<ActionResult> {
   const result: ActionResult = {};
+  await page.evaluate(LISTEN_INVALID).catch(() => {});
   try {
     switch (action.type) {
       case "click":
@@ -283,12 +403,21 @@ export async function execute(
         const byKeyboard = opts.keyboard && !ARROW_KEY_ITEMS.has(el.role);
         if (byKeyboard) result.focusObscured = await focusByKeyboard(page, locator, action.id);
         if (action.type === "click" && byKeyboard) {
-          if (!FOCUS_ONLY.test(el.role)) await page.keyboard.press(SPACE_KEY.has(el.role) ? "Space" : "Enter");
+          if (SPACE_KEY.has(el.role)) await page.keyboard.press("Space");
+          else if (BUTTON_ROLE.test(el.role)) {
+            if (await pressEnterThenSpace(page, action.id)) result.enterIgnored = true;
+          } else if (!FOCUS_ONLY.test(el.role)) await page.keyboard.press("Enter");
         } else if (action.type === "click") {
           try {
             await locator.click({ timeout: 5_000 });
           } catch (err) {
-            if (!describeFailure(err).startsWith(COVERED) || !(await clickVisiblePart(page, action.id))) throw err;
+            if (!describeFailure(err).startsWith(COVERED) || !(await clickVisiblePart(page, action.id))) {
+              // Something open over the page took the click: the agent is told what to do, as a
+              // person sees it, and it is no defect of the page behind.
+              const open = describeFailure(err).startsWith(COVERED) ? await openOver(page, action.id) : "";
+              if (open) throw new Unusable(`${open} is open over the page and takes the click: finish it, choose from it or close it (Escape, or its close button) first`);
+              throw err;
+            }
           }
         } else if (el.tag === "select") await choose(locator, action.text);
         else if (customDropdown) await pick(page, locator, action.text);
@@ -328,10 +457,12 @@ export async function execute(
     await page.waitForLoadState("domcontentloaded");
     // Let async handlers (fetch after submit, deferred errors) surface their signals.
     await page.waitForTimeout(300);
-    return result.focusObscured ? result : {};
+    const invalid = ((await page.evaluate(READ_INVALID).catch(() => [])) as string[]) ?? [];
+    if (invalid.length) result.invalid = invalid;
+    return result;
   } catch (err) {
     if (err instanceof Refused) return { blocked: err.message };
-    if (err instanceof NotByKeyboard) return { error: err.message };
+    if (err instanceof NotByKeyboard || err instanceof Unusable) return { error: err.message };
     const why = "id" in action ? await explainTimeout(page, action.id, err) : undefined;
     return { error: why ?? describeFailure(err), ...(result.focusObscured ? { focusObscured: result.focusObscured } : {}) };
   }

package/src/browser/observe.ts

@@ -43,6 +43,36 @@ const LANGUAGE_SCRIPT = `(() => {
   };
 })()`;
 
+/**
+ * What is open over the page and takes clicks outside it: a dialog (or a tour step, a bottom sheet),
+ * or a dropdown list or menu. Agents clicked behind a welcome dialog, an open menu and an open
+ * dropdown on three apps in one week (2026-10-25, 2026-11-01), and each was reported as
+ * "something covers it". "" when nothing is open.
+ */
+export const OPEN_LAYER_SCRIPT = `(() => {
+  const shown = (e) => {
+    const b = e.getBoundingClientRect();
+    const s = getComputedStyle(e);
+    return b.width > 0 && b.height > 0 && s.visibility !== 'hidden' && s.display !== 'none' && Number(s.opacity) !== 0;
+  };
+  const nameOf = (e) => {
+    const label = e.getAttribute('aria-label');
+    if (label) return label;
+    const by = (e.getAttribute('aria-labelledby') || '').split(/\\s+/)[0];
+    const titled = by && document.getElementById(by);
+    if (titled) return titled.textContent;
+    const heading = e.querySelector('h1, h2, h3, h4, [role="heading"]');
+    return heading ? heading.textContent : '';
+  };
+  const dialog = [...document.querySelectorAll('[role="dialog"], [role="alertdialog"], dialog[open], [aria-modal="true"]')].find(shown);
+  const list = [...document.querySelectorAll('[role="listbox"], [role="menu"]')].find((e) => shown(e) && document.querySelector('[aria-expanded="true"]'));
+  const layer = dialog || list;
+  if (!layer) return '';
+  const kind = layer === dialog ? 'a dialog' : layer.getAttribute('role') === 'menu' ? 'a menu' : 'a dropdown list';
+  const name = (nameOf(layer) || '').replace(/\\s+/g, ' ').trim().slice(0, 60);
+  return kind + (name ? ' ("' + name + '")' : '');
+})()`;
+
 export async function observe(page: Page): Promise<Observation> {
   const elements = (await page.evaluate(SCAN_SCRIPT)) as InteractiveElement[];
   const names = await accessibleNames(page);
@@ -50,7 +80,14 @@ export async function observe(page: Page): Promise<Observation> {
     const ax = names.get(el.id);
     if (ax) el.ax = ax;
   }
-  const text = (await page.locator("body").innerText()).replace(/\s+/g, " ").trim().slice(0, 2000);
+  // Line by line, as it reads on screen, so what changed after an action can be told line by line.
+  const text = (await page.locator("body").innerText())
+    .split("\n")
+    .map((line) => line.replace(/\s+/g, " ").trim())
+    .filter(Boolean)
+    .join("\n")
+    .slice(0, 2000);
   const language = (await page.evaluate(LANGUAGE_SCRIPT)) as Pick<Observation, "lang" | "dir" | "arabicShare" | "zoomBlocked">;
-  return { url: page.url(), title: await page.title(), elements, text, ...language };
+  const openLayer = (await page.evaluate(OPEN_LAYER_SCRIPT)) as string;
+  return { url: page.url(), title: await page.title(), elements, text, ...language, ...(openLayer ? { openLayer } : {}) };
 }

package/src/browser/scan-script.ts

@@ -12,6 +12,35 @@ export const SCAN_SCRIPT = `(() => {
     ? el.checkVisibility({ visibilityProperty: true })
     : (getComputedStyle(el).display !== 'none' && getComputedStyle(el).visibility !== 'hidden');
   const textOf = (el) => (el && (el.innerText || el.textContent)) || '';
+  // What a sighted person sees on a control with no text: its icon. Icon sets name their icons in
+  // class names (lucide-menu, tabler-icon-dots, fa-bars, i-ph-gear), data attributes, sprite
+  // references (<use href="#menu">) or an image's file name. Without it, agents met
+  // a row of buttons named "" and guessed.
+  const ICON_CLASS = /^(?:i-[a-z0-9]+-|lucide-|tabler-icon-|icon-tabler-|fa-|bi-|ti-|mdi-|ph-|ri-|feather-|heroicons?-|bx-|bxs-|octicon-|codicon-|icon-)([a-z][a-z0-9-]*)$/;
+  const NOT_ICON = /^(?:solid|regular|light|thin|duotone|brands|sharp|fw|xs|sm|md|lg|xl|spin|pulse|button|btn|wrapper|container|only|small|large|size-.*)$/;
+  const iconWord = (s) => {
+    const word = s.replace(/([a-z])([A-Z])/g, '$1 $2').toLowerCase().replace(/[-_]+/g, ' ')
+      .replace(/^icon /, '').replace(/( (?:icon|outline|outlined|filled|fill|line|solid|bold|regular|light|thin|duotone|round|rounded|sharp|[0-9]+))+$/, '').trim();
+    return word || s.toLowerCase();
+  };
+  const iconOf = (el) => {
+    for (const n of [el, ...el.querySelectorAll('svg, i, span, img, use')].slice(0, 15)) {
+      const tag = n.tagName.toLowerCase();
+      const href = tag === 'use' ? n.getAttribute('href') || n.getAttribute('xlink:href') || '' : '';
+      const testId = (n.getAttribute('data-testid') || '').match(/^(.+)Icon$/);
+      const named = n.getAttribute('data-icon') || n.getAttribute('data-lucide') || (href.includes('#') && href.split('#').pop()) || (testId && testId[1]);
+      if (named) return iconWord(named);
+      for (const token of n.classList || []) {
+        const m = token.match(ICON_CLASS);
+        if (m && !NOT_ICON.test(m[1])) return iconWord(m[1]);
+      }
+      if (tag === 'img') {
+        const file = (n.getAttribute('src') || '').split(/[?#]/)[0].split('/').pop().replace(/[.][a-z0-9]+$/i, '');
+        if (/^[a-z][a-z_-]{1,30}$/i.test(file)) return iconWord(file);
+      }
+    }
+    return '';
+  };
   const out = [];
   let next = 0;
   // Ids from the last look stay on elements that have since gone out of sight; the same number
@@ -48,6 +77,10 @@ export const SCAN_SCRIPT = `(() => {
     // A placeholder is an example, not a label: screen readers read it as the field's name (a
     // password's dots as "13 bullet"), and it's gone once someone types.
     if (!labelled && placeholder) item.nameFrom = 'placeholder';
+    if (!item.name) {
+      const icon = iconOf(el);
+      if (icon) item.icon = icon;
+    }
     // What a keyboard user can reach: a disabled control, or one out of the tab order, isn't.
     if (el.disabled === true || el.getAttribute('aria-disabled') === 'true') item.disabled = true;
     else if (el.tabIndex < 0 || el.closest('[inert]')) item.tabbable = false;
@@ -56,6 +89,19 @@ export const SCAN_SCRIPT = `(() => {
       item.value = chosen ? chosen.label.slice(0, 80) : '';
       item.options = Array.from(el.options).slice(0, 30).map((o) => o.label.slice(0, 60));
     }
+    // What a person sees of a control's state: what a field holds (a password only as filled),
+    // whether it can be edited, whether a box is ticked and whether a menu is open.
+    const textField = tag === 'textarea' || (tag === 'input' && !['checkbox', 'radio', 'file', 'submit', 'button', 'reset', 'image', 'range', 'color'].includes(el.type));
+    if (textField && el.value) {
+      if (el.type === 'password') item.filled = true;
+      else item.value = el.value.slice(0, 60);
+    }
+    if (textField && el.readOnly) item.readOnly = true;
+    const ariaChecked = el.getAttribute('aria-checked');
+    if (el.type === 'checkbox' || el.type === 'radio') item.checked = el.checked;
+    else if (ariaChecked === 'true' || ariaChecked === 'false') item.checked = ariaChecked === 'true';
+    const ariaExpanded = el.getAttribute('aria-expanded');
+    if (ariaExpanded === 'true' || ariaExpanded === 'false') item.expanded = ariaExpanded === 'true';
     out.push(item);
   }
   return out;

package/src/cli.ts

@@ -17,6 +17,7 @@ import { OUT_OF_CREDITS } from "./llm/types";
 import { generateUnits } from "./persona/generate";
 import { withInclusion } from "./persona/inclusion";
 import { languageName, parseLanguages, withLanguages } from "./persona/language";
+import { peopleCount, readPeople } from "./persona/people";
 import { exhibitsFromSessions } from "./perception/exhibits";
 import { runPerception } from "./perception/run-perception";
 import { renderLaunchReadiness } from "./report/launch-readiness";
@@ -26,7 +27,7 @@ import { HttpSandboxOutbox } from "./sandbox/outbox";
 import { runSimulation } from "./run";
 import { openDb } from "./store/db";
 import { PgRunStore } from "./store/pg-run-store";
-import type { Persona } from "./types";
+import type { CustomerUnit, Persona } from "./types";
 import { runOrigin } from "./util/run-origin";
 
 const MAX_EMPLOYEES = 4;
@@ -77,13 +78,15 @@ const { values } = parseArgs({
     evaluators: { type: "string" },
     // Customers' first languages, as lang codes (ar,en): agents take them in turn.
     languages: { type: "string" },
+    // An earlier run's people.json: the same agents again, e.g. to see whether a fix worked.
+    people: { type: "string" },
   },
 });
 
 const unitKind = values.unit;
 if (!values.url || !values.goal || !values.icp || (unitKind !== "individual" && unitKind !== "business")) {
   console.error(
-    'Usage: npx debutly (settings in debutly.json; npx debutly init writes one) or npx debutly --url <url> --goal "<goal>" --icp "<ideal customer profile>" [--unit individual|business] [--tier quick|standard|deep] [--agents N] [--employees N] [--max-cost USD] [--inclusion on|off] [--max-steps 30] [--concurrency 3] [--out runs/x] [--mailpit http://127.0.0.1:54324] [--email-domain agents.test] [--sandbox-outbox http://localhost:3000/api/sandbox/outbox] [--store postgres://…] [--app name] [--trigger nightly|pr|manual] [--ci-url url] [--screenshot-days 7] [--browser-state dir] [--queue redis://…] [--agent-token-cap N] [--agent-minutes N] [--evaluators N]',
+    'Usage: npx debutly (settings in debutly.json; npx debutly init writes one) or npx debutly --url <url> --goal "<goal>" --icp "<ideal customer profile>" [--unit individual|business] [--tier quick|standard|deep] [--agents N] [--employees N] [--max-cost USD] [--inclusion on|off] [--max-steps 30] [--concurrency 3] [--out runs/x] [--mailpit http://127.0.0.1:54324] [--email-domain agents.test] [--sandbox-outbox http://localhost:3000/api/sandbox/outbox] [--store postgres://…] [--app name] [--trigger nightly|pr|manual] [--ci-url url] [--screenshot-days 7] [--browser-state dir] [--queue redis://…] [--agent-token-cap N] [--agent-minutes N] [--evaluators N] [--people runs/x/people.json]',
   );
   process.exit(1);
 }
@@ -103,13 +106,20 @@ const size = resolveRunSize({
 const employees = Math.min(Math.max(size.employees || 0, 0), MAX_EMPLOYEES);
 const count = size.units;
 const maxSteps = Number(values["max-steps"]);
+let reused: CustomerUnit[] | undefined;
+try {
+  reused = values.people ? await readPeople(values.people) : undefined;
+} catch (err) {
+  console.error(err instanceof Error ? err.message : err);
+  process.exit(1);
+}
 if (unitKind === "business" && employees > 0 && !values.mailpit) {
   console.warn("Business crews need --mailpit for invites; employees will be recorded as not invited.");
 }
 
 // Before anything is spent: what could this run cost?
 const navModel = process.env.DEBUTLY_NAV_MODEL ?? (process.env.DEBUTLY_PROVIDER === "openai-compatible" ? "" : "claude-haiku-4-5");
-const agents = agentCount(unitKind, { ...size, employees });
+const agents = reused ? peopleCount(reused) : agentCount(unitKind, { ...size, employees });
 const price = await fetchModelPrice(navModel);
 const evaluatorCount = values.evaluators !== undefined ? Number(values.evaluators) : 0;
 const depthEstimate = estimateRunCost({ agents, maxSteps, price });
@@ -141,13 +151,19 @@ if (credits.refuse) {
 if (credits.warn) console.warn(`Warning: ${credits.warn}`);
 
 const { nav, judge } = createLlms(process.env);
-console.log(`Generating ${count} ${unitKind === "business" ? `business crew(s) with ${employees} employees each` : "individual(s)"}...`);
-let units = await generateUnits(judge, values.icp, { kind: unitKind, count, employees, languages });
-if (values.inclusion !== "off") {
-  const dayOfYear = Math.floor((Date.now() - Date.UTC(new Date().getUTCFullYear(), 0, 1)) / 86_400_000);
-  units = withInclusion(units, dayOfYear);
+let units: CustomerUnit[];
+if (reused) {
+  console.log(`The same ${agents} agents as before, from ${values.people}:`);
+  units = reused;
+} else {
+  console.log(`Generating ${count} ${unitKind === "business" ? `business crew(s) with ${employees} employees each` : "individual(s)"}...`);
+  units = await generateUnits(judge, values.icp, { kind: unitKind, count, employees, languages });
+  if (values.inclusion !== "off") {
+    const dayOfYear = Math.floor((Date.now() - Date.UTC(new Date().getUTCFullYear(), 0, 1)) / 86_400_000);
+    units = withInclusion(units, dayOfYear);
+  }
+  units = withLanguages(units, languages);
 }
-units = withLanguages(units, languages);
 
 const describe = (p: Persona) =>
   `${p.id} ${p.name}${p.role ? ` (${p.role})` : ""}${p.inclusion ? ` [${p.inclusion.replace(/_/g, " ")}]` : ""}${p.language && p.language !== "en" ? ` [${languageName(p.language)}]` : ""}: ${p.background}`;

package/src/detect/findings.ts

@@ -17,9 +17,10 @@ const BASE_SEVERITY: Record<FindingKind, Severity> = {
   reflow: "minor",
   language: "minor",
   zoom: "major",
+  hidden_focus: "major",
 };
 // What the browser measures, not what an agent made of the page: one measurement is enough.
-export const MEASURED: ReadonlySet<FindingKind> = new Set(["a11y_unlabeled", "covered", "keyboard", "focus_obscured", "reflow", "language", "zoom"]);
+export const MEASURED: ReadonlySet<FindingKind> = new Set(["a11y_unlabeled", "covered", "keyboard", "focus_obscured", "reflow", "language", "zoom", "hidden_focus"]);
 /** Sideways overflow this small is reported, but never raised above minor. */
 const SLIGHT_OVERFLOW_PX = 20;
 /** A page whose letters are at least this share Arabic is an Arabic page. */
@@ -34,6 +35,8 @@ const VERY_SLOW_MS = 30_000;
 // "no" and "API key", and the variable it wants.
 const MISSING_KEY =
   /no (?:[\w-]+ ){0,2}api[ _-]?key|api[ _-]?key (?:is )?(?:not set|missing|not configured|required)|no ai api configured|not configured|configure [a-z0-9_]*key\b|\bset [a-z0-9]+_[a-z0-9_]*key\b|\b[a-z0-9]+_api_key (?:is )?(?:not set|missing|undefined)/i;
+// How an auth server refuses a sign-in provider it has no keys for.
+const PROVIDER_OFF = /provider is not enabled|unsupported provider|provider (?:is )?(?:disabled|not configured)/i;
 // A web address typed in on its own, as an agent gives its company's site ("https://www.pulsehr.io/").
 const TYPED_SITE = /^(?:https?:\/\/)?(?:www\.)?((?:[a-z0-9-]+\.)+[a-z]{2,})(?:[/?#]\S*)?$/i;
 // How an app says it couldn't get at a site: "Could not read that website", "DNS lookup failed".
@@ -50,6 +53,14 @@ const SANDBOX_SLACK_MS = 2000;
 // /app/accounts/<their account>/onboarding, which listed the same unlabeled button once per agent.
 const ID_SEGMENT = /^(?:\d+|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|[0-9a-f]{16,}|(?=[a-z0-9]*\d)[a-z0-9]{20,})$/i;
 
+const originOf = (url: string) => {
+  try {
+    return new URL(url).origin;
+  } catch {
+    return "";
+  }
+};
+
 const pathOf = (url: string) => {
   try {
     return new URL(url).pathname
@@ -131,7 +142,7 @@ function fromSignal(signal: Signal): Candidate | null {
         signature: `slow:${signal.slowNetwork ? "slow" : "normal"}:${pagePath}`,
         kind: "slow_load",
         title: signal.finished ? `${pagePath} took ${seconds} s to load${connection}` : `${pagePath} still hadn't loaded after ${seconds} s${connection}`,
-        detail: `${signal.slowNetwork ? "On a slow connection (500 kbit/s, 400 ms round trips, like weak mobile data)" : "On a normal connection"}, ${pagePath} ${signal.finished ? `took ${seconds} s before the page arrived` : `had not arrived after ${seconds} s, so the agent went on with whatever was on screen`}. Until then a visitor sees a blank or half-drawn page, and many leave.`,
+        detail: `${signal.slowNetwork ? "On a slow connection (500 kbit/s, 400 ms round trips, like weak mobile data)" : "On a normal connection"}, ${pagePath} ${signal.finished ? `took ${seconds} s before the page arrived` : `had not arrived after ${seconds} s, so the agent went on with whatever was on screen`}. Until then a visitor sees a blank or half-drawn page, and many leave.${weightNote(signal.assets)}`,
         pagePath,
         severity: !signal.finished || signal.ms >= VERY_SLOW_MS ? "major" : BASE_SEVERITY.slow_load,
       };
@@ -161,6 +172,20 @@ const NAMED_CONTROLS: Record<string, string> = {
   "input:url": "web address field",
 };
 
+/** Said of a slow page whose scripts and styles came mostly uncompressed; the report's next step looks for it. */
+export const UNCOMPRESSED = "came uncompressed";
+const kb = (bytes: number) => (bytes >= 1024 * 1024 ? `${(bytes / 1024 / 1024).toFixed(1)} MB` : `${Math.round(bytes / 1024)} KB`);
+
+// What the scripts and styles that had arrived weighed. Mostly uncompressed, it may be the test
+// copy's doing (served straight from a container) rather than the real site's.
+function weightNote(assets: Extract<Signal, { kind: "slow_load" }>["assets"]): string {
+  if (!assets || assets.bytes < 100 * 1024) return "";
+  if (assets.uncompressedBytes >= assets.bytes / 2) {
+    return ` By then it had received ${kb(assets.bytes)} of scripts and styles, and ${kb(assets.uncompressedBytes)} of that ${UNCOMPRESSED}. Compressed (gzip or Brotli, which most hosting turns on), scripts are often a quarter of the size. If the real site compresses them, it is lighter than this test copy.`;
+  }
+  return ` By then it had received ${kb(assets.bytes)} of scripts and styles, compressed.`;
+}
+
 /** What to call a control that has no name, or undefined when it doesn't need one. */
 function unlabeledControl(role: string): string | undefined {
   return NAMED_CONTROLS[role];
@@ -197,6 +222,39 @@ function placeOf(elements: InteractiveElement[], i: number): string {
   return after ? `before ${q(after)}` : "";
 }
 
+/**
+ * Controls hidden from screen readers (aria-hidden) that Tab still reaches: a closed mobile menu
+ * left in the page, its ~15 links aria-hidden but focusable (2026-10-25). Keyboard focus goes into
+ * them unseen, and a screen reader says nothing or something misleading. Not while something is
+ * open over the page: a modal hides the page behind it on purpose, and keeps focus inside itself.
+ */
+function hiddenButReachable(obs: Observation, pagePath: string): Candidate | undefined {
+  if (obs.openLayer) return undefined;
+  const reached = obs.elements.filter((e) => e.ax?.ariaHidden && !e.disabled && e.tabbable !== false && e.role !== "input:file");
+  if (!reached.length) return undefined;
+  const names = [...new Set(reached.map((e) => e.name.trim()).filter(Boolean))].slice(0, 3).map((n) => `"${n.slice(0, 40)}"`);
+  const count = reached.length === 1 ? "A control" : `${reached.length} controls`;
+  return {
+    signature: `hidden-focus:${pagePath}`,
+    kind: "hidden_focus",
+    title: `${count} on ${pagePath} ${reached.length === 1 ? "is" : "are"} hidden from screen readers but reachable with Tab`,
+    detail: `${count}${names.length ? ` (${names.join(", ")}${reached.length > names.length ? ", …" : ""})` : ""} ${reached.length === 1 ? "is" : "are"} marked aria-hidden, often a closed menu or panel left in the page, yet Tab still lands on ${reached.length === 1 ? "it" : "them"}: keyboard focus disappears from view, and a screen reader says nothing or something misleading.`,
+    pagePath,
+    severity: severityFor("hidden_focus", [pagePath]),
+    wcag: ["4.1.2", "2.4.3"],
+  };
+}
+
+/** Whether the agent pressed the control without trouble later on the same page. */
+function pressedLater(steps: Step[], after: number, pagePath: string, control: string): boolean {
+  return steps.some((st) => {
+    if (st.index <= after || st.error || st.blocked || st.action.type !== "click" || pathOf(st.observation.url) !== pagePath) return false;
+    const id = st.action.id;
+    const el = st.observation.elements.find((e) => e.id === id);
+    return !!el && `${el.role} "${el.name}"` === control;
+  });
+}
+
 /** One finding per page, kind of control and kind of problem, naming up to three places. */
 function unnamedControls(elements: InteractiveElement[], pagePath: string): Candidate[] {
   const groups = new Map<string, { control: string; role: string; problem: Unnamed; places: string[]; said: string; count: number }>();
@@ -208,7 +266,8 @@ function unnamedControls(elements: InteractiveElement[], pagePath: string): Cand
     const key = `${problem}:${el.role}`;
     const g = groups.get(key) ?? { control, role: el.role, problem, places: [] as string[], said: problem === "placeholder" ? name : (el.ax?.description ?? ""), count: 0 };
     g.count++;
-    const place = placeOf(elements, i);
+    // The icon it shows, when its markup names one, is how a founder spots it on the page.
+    const place = [el.icon ? `the ${el.icon} icon` : "", placeOf(elements, i)].filter(Boolean).join(" ");
     if (place && g.places.length < MAX_PLACES) g.places.push(place);
     groups.set(key, g);
   });
@@ -267,12 +326,12 @@ function unnamedControls(elements: InteractiveElement[], pagePath: string): Cand
 
 const capitalize = (s: string) => s.charAt(0).toUpperCase() + s.slice(1);
 
-/** What a server error said, for quoting: its JSON `error` or `message` if it has one. */
+/** What a server error said, for quoting: its JSON `error`, `message` or `msg` (Supabase's auth) if it has one. */
 function said(body: string): string {
   let text = body;
   try {
-    const parsed = JSON.parse(body) as { error?: unknown; message?: unknown };
-    const field = parsed.error ?? parsed.message;
+    const parsed = JSON.parse(body) as { error?: unknown; message?: unknown; msg?: unknown };
+    const field = typeof parsed.error === "string" ? parsed.error : (parsed.message ?? parsed.msg);
     if (typeof field === "string") text = field;
   } catch {
     // not JSON: quote it as it is
@@ -283,8 +342,12 @@ function said(body: string): string {
 
 /** In a test environment, the app's own words when a server error says a key is missing. */
 function missingKey(signal: Signal, sandbox: boolean): string | undefined {
-  if (!sandbox || signal.kind !== "http_error" || signal.status < 500 || !signal.body || !MISSING_KEY.test(signal.body)) return undefined;
-  return said(signal.body);
+  if (!sandbox || signal.kind !== "http_error" || !signal.body) return undefined;
+  if (signal.status >= 500 && MISSING_KEY.test(signal.body)) return said(signal.body);
+  // A sign-in provider the test environment's auth server has no keys for (Google, Microsoft…)
+  // refuses with a 400: "Unsupported provider: provider is not enabled" (2026-10-25).
+  if (signal.status >= 400 && PROVIDER_OFF.test(signal.body)) return said(signal.body);
+  return undefined;
 }
 
 /** The site an agent typed in for its company, which is made up like the company. */
@@ -440,6 +503,8 @@ export function detectFindings(sessions: Session[], opts: DetectOptions = {}): F
   };
 
   for (const s of sessions) {
+    // The app's own pages are where it started; a sign-in server's raw error page is not one of them.
+    const appOrigin = originOf(s.steps[0]?.observation.url ?? "");
     let repeatKey = "";
     let repeats = 0;
     // Per control: how often a click on it was refused because another element lay on top.
@@ -491,8 +556,10 @@ export function detectFindings(sessions: Session[], opts: DetectOptions = {}): F
       }
 
       for (const c of unnamedControls(step.observation.elements, pagePath)) record(c, s.agentId, step.index);
+      const hiddenFocus = hiddenButReachable(step.observation, pagePath);
+      if (hiddenFocus) record(hiddenFocus, s.agentId, step.index);
 
-      for (const c of languageFindings(step.observation, pagePath)) record(c, s.agentId, step.index);
+      if (originOf(step.observation.url) === appOrigin) for (const c of languageFindings(step.observation, pagePath)) record(c, s.agentId, step.index);
 
       // Keyboard only (the screen-reader agent): a control Tab never reaches, and focus that
       // something entirely hides.
@@ -514,6 +581,23 @@ export function detectFindings(sessions: Session[], opts: DetectOptions = {}): F
           step.index,
         );
       }
+      // A button that takes Space but not Enter: most keyboard users press Enter, and stop there.
+      if (acted && step.enterIgnored) {
+        const control = `${acted.role} "${acted.ax?.name || acted.name}"`;
+        record(
+          {
+            signature: `enter:${pagePath}:${control}`,
+            kind: "keyboard",
+            title: `Enter doesn't press ${control} on ${pagePath}`,
+            detail: `With keyboard focus on it, Enter did nothing (no request, no change on the page), and Space pressed it. Buttons take both, and most keyboard and screen-reader users press Enter, so they get no further here.`,
+            pagePath,
+            severity: severityFor("keyboard", [pagePath]),
+            wcag: ["2.1.1"],
+          },
+          s.agentId,
+          step.index,
+        );
+      }
       if (acted && step.focusObscured) {
         const control = `${acted.role} "${acted.name}"`;
         record(
@@ -533,12 +617,14 @@ export function detectFindings(sessions: Session[], opts: DetectOptions = {}): F
 
       // A control something else keeps covering: the person can't press it either. The agent
       // works round it in other ways (keys, closing things), so this is not always "stuck".
+      // Unless the agent presses it later on the same page: then what lay over it went away once
+      // the agent dealt with it (a dropdown list chosen from, 2026-11-04), and it is no defect.
       const target = step.action.type === "click" && step.error?.startsWith(COVERED) ? step.observation.elements.find((e) => e.id === (step.action as { id: number }).id) : undefined;
       if (target) {
         const control = `${target.role} "${target.name}"`;
         const times = (covered.get(control) ?? 0) + 1;
         covered.set(control, times);
-        if (times === COVERED_REPEATS) {
+        if (times === COVERED_REPEATS && !pressedLater(s.steps, step.index, pagePath, control)) {
           const by = step.error!.slice(COVERED.length).replace(/^:\s*/, "");
           record(
             {