debutly 0.1.0 → 0.2.0

package/README.md

@@ -24,7 +24,7 @@ Website and docs: [debutly.dev](https://debutly.dev) ([quick start](https://debu
 
 ## Quick start
 
-Needs Node.js 20.12 or later. Until the first npm release, type `npx github:sroay/debutly` wherever this says `npx debutly`. In your app's folder:
+Needs Node.js 20.12 or later. In your app's folder:
 
 ```bash
 npx debutly init     # a few questions, then a debutly.json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "debutly",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Rehearse your launch: AI agents use your web app like your first customers and report what breaks.",
   "type": "module",
   "license": "AGPL-3.0-only",

package/src/agent/effect.ts

@@ -1,4 +1,5 @@
-import type { Action, ActionResult, Observation, Signal } from "../types";
+import type { Action, ActionResult, InteractiveElement, Observation, Signal } from "../types";
+import { controlLabel, type StepView } from "./label";
 
 const pathOf = (url: string) => {
   try {
@@ -9,16 +10,72 @@ const pathOf = (url: string) => {
   }
 };
 
+const MAX_LISTED = 4;
+const MAX_LINE = 80;
+
+type Label = (e: InteractiveElement) => string;
+
+/** Controls in `a` beyond those in `b`, counting copies: a second "Untitled" row is new. */
+function beyond(a: InteractiveElement[], b: InteractiveElement[], controlOf: Label): InteractiveElement[] {
+  const left = new Map<string, number>();
+  for (const e of b) left.set(controlOf(e), (left.get(controlOf(e)) ?? 0) + 1);
+  return a.filter((e) => {
+    const n = left.get(controlOf(e)) ?? 0;
+    if (n > 0) left.set(controlOf(e), n - 1);
+    return n === 0;
+  });
+}
+
+/** Controls still there whose state changed: a Save button now enabled, a box now checked. */
+function stateChanges(before: InteractiveElement[], after: InteractiveElement[], controlOf: Label): string[] {
+  const out: string[] = [];
+  for (const a of after) {
+    const b = before.find((e) => controlOf(e) === controlOf(a));
+    if (!b) continue;
+    if (!!b.disabled !== !!a.disabled) out.push(`now ${a.disabled ? "disabled" : "enabled"} ${controlOf(a)}`);
+    if (b.checked !== undefined && a.checked !== undefined && b.checked !== a.checked) out.push(`now ${a.checked ? "checked" : "unchecked"} ${controlOf(a)}`);
+    if (b.expanded !== undefined && a.expanded !== undefined && b.expanded !== a.expanded) out.push(`now ${a.expanded ? "open" : "closed"} ${controlOf(a)}`);
+  }
+  return out;
+}
+
+const listed = (items: string[]) => items.slice(0, MAX_LISTED).join(", ") + (items.length > MAX_LISTED ? `, and ${items.length - MAX_LISTED} more` : "");
+
+/**
+ * What changed on the page, as a person would notice it: controls that appeared or went, state
+ * that changed, and new lines of text. Told only "the page changed", agents missed a password
+ * field that had appeared, pressed "Create company" seven times without seeing seven new rows,
+ * and kept retyping values while waiting for a Save button to wake up.
+ */
+function whatChanged(before: Observation, after: Observation, controlOf: Label): string {
+  const appeared = beyond(after.elements, before.elements, controlOf);
+  const gone = beyond(before.elements, after.elements, controlOf);
+  const names = new Set(after.elements.map((e) => e.name));
+  const had = new Set(before.text.split("\n").map((l) => l.trim()));
+  const newText = [...new Set(after.text.split("\n").map((l) => l.trim()))].filter((l) => l && !had.has(l) && !names.has(l)).map((l) => `"${l.slice(0, MAX_LINE)}"`);
+  const parts = [
+    appeared.length ? `new ${listed(appeared.map(controlOf))}` : "",
+    gone.length ? `gone ${listed(gone.map(controlOf))}` : "",
+    ...stateChanges(before.elements, after.elements, controlOf).slice(0, MAX_LISTED),
+    newText.length ? `new text ${listed(newText)}` : "",
+  ].filter(Boolean);
+  return parts.length ? `the page changed: ${parts.join("; ")}` : "";
+}
+
 // What a person would notice after acting: where they are now, whether anything changed,
 // and whether something visibly broke. Without this, agents retry dead buttons forever.
-export function describeEffect(action: Action, before: Observation, after: Observation, signals: Signal[], result: ActionResult): string {
+// Controls are named as the agent meets them, as in its step message.
+export function describeEffect(action: Action, before: Observation, after: Observation, signals: Signal[], result: ActionResult, view: StepView = {}): string {
   if (result.blocked) return `blocked: ${result.blocked}`;
   if (result.error) return `failed: ${result.error}`;
   // check_email reports its own result; done ends the session.
   if (action.type === "done" || action.type === "check_email") return "";
 
   const parts: string[] = [];
+  if (result.enterIgnored) parts.push("Enter did nothing on it, so Space was pressed instead");
+  const changed = whatChanged(before, after, (e) => controlLabel(e, view.screenReader));
   if (pathOf(after.url) !== pathOf(before.url)) parts.push(`now on ${pathOf(after.url)}`);
+  else if (changed) parts.push(changed);
   else if (after.text !== before.text) parts.push("the page changed");
   else if (action.type !== "fill" && !signals.some((s) => s.kind === "download")) parts.push("nothing visibly changed");
 

package/src/agent/give-up.ts

@@ -0,0 +1,42 @@
+import type { Observation, Step } from "../types";
+
+// What a person presses before giving up: to go on, join, sign in or start, or to add or create
+// what they came to add (agents said adding a person was "missing" beside "Add person").
+// Arabic too, as agents often use Arabic interfaces.
+const WAY_ON =
+  /^(continue|next|proceed|join\b.*|accept\b.*|sign ?in|log ?in|sign ?up|create (an )?account|get started|start|confirm|verify|submit|(add|create|new)\b.*|استمر|متابعة|التالي|انضم.*|قبول.*|تسجيل الدخول|ابدأ.*|تأكيد|إرسال|(إنشاء|أضف|إضافة).*)$/i;
+// Buttons only: a page's own way on. A "Sign up" link in the site's menu is not one from where it stands.
+const PRESSABLE = /^(button|input:(submit|button))$/;
+
+const pathOf = (url: string) => {
+  try {
+    return new URL(url).pathname;
+  } catch {
+    return url;
+  }
+};
+
+/**
+ * The ways on that an agent about to give up hasn't tried on the page it is on: enabled buttons
+ * named like Continue, Join or Sign in that it hasn't pressed since it came to this page.
+ * A teammate agent gave up on Twenty's invite page saying there was "no way into the workspace",
+ * with a Continue button under its eyes (2026-10-25), and the report blamed the app.
+ */
+export function untriedWaysOn(obs: Observation, steps: Step[], screenReader = false): string[] {
+  const path = pathOf(obs.url);
+  const pressed = new Set<string>();
+  for (let i = steps.length - 1; i >= 0 && pathOf(steps[i].observation.url) === path; i--) {
+    const { action, observation } = steps[i];
+    if (action.type !== "click") continue;
+    const el = observation.elements.find((e) => e.id === action.id);
+    if (el) pressed.add((el.ax?.name || el.name).trim().toLowerCase());
+  }
+  const names = obs.elements
+    .filter((e) => PRESSABLE.test(e.role) && !e.disabled && !(screenReader && e.ax?.hidden))
+    .map((e) => (screenReader && e.ax ? e.ax.name : e.name || e.ax?.name || "").trim())
+    .filter((name) => WAY_ON.test(name) && !pressed.has(name.toLowerCase()));
+  return [...new Set(names)].slice(0, 3);
+}
+
+/** A page with nothing to press is often still arriving: one agent on a slow connection gave up the moment an invite page opened. */
+export const nothingToPressYet = (obs: Observation) => obs.elements.length === 0;

package/src/agent/label.ts

@@ -0,0 +1,19 @@
+import type { InteractiveElement } from "../types";
+
+// Apart from prompt.ts, which needs the browser (Playwright) through the inclusion briefs: the
+// dashboard imports effect.ts, and its build has no Playwright.
+
+export interface StepView {
+  /** As a screen reader presents the page: the browser's names and roles, without what is hidden from it. */
+  screenReader?: boolean;
+}
+
+/**
+ * A control as the agent meets it. A screen reader announces the role and name the browser gives
+ * it; a sighted person looking at a control with no text sees its icon.
+ */
+export function controlLabel(e: InteractiveElement, screenReader = false): string {
+  const heard = screenReader && e.ax ? e.ax : e;
+  const icon = !screenReader && !e.name && e.icon ? ` (${e.icon} icon)` : "";
+  return `${heard.role} "${heard.name}"${icon}`;
+}

package/src/agent/loop.ts

@@ -1,4 +1,4 @@
-import type { Page } from "playwright";
+import type { Page, Request } from "playwright";
 import type { ArtifactStore } from "../artifacts/store";
 import { execute } from "../browser/execute";
 import { observe } from "../browser/observe";
@@ -11,15 +11,20 @@ import type { LlmClient, LlmMessage } from "../llm/types";
 import type { ActionResult, Persona, Session, Step } from "../types";
 import { describeAction } from "./describe";
 import { describeEffect } from "./effect";
-import { parseAgentReply } from "./parse-reply";
+import { nothingToPressYet, untriedWaysOn } from "./give-up";
+import { NoActionError, parseAgentReply } from "./parse-reply";
 import { buildStepMessage, buildSystemPrompt, type AgentIdentity } from "./prompt";
 
 const MAX_REPLY_ATTEMPTS = 3;
+/** Steps a session may wait for want of an action in the reply, before that is an engine error. */
+const MAX_NO_ACTION_WAITS = 3;
 const LINKS_PER_EMAIL = 3;
 /** How long the first page may take to arrive; a slow-connection agent needs more than 30 s. */
 const FIRST_LOAD_MS = 90_000;
 /** A first page slower than this is reported. */
 const SLOW_LOAD_MS = 10_000;
+/** How long a slow first page's scripts and styles may take to be weighed before it is reported without. */
+const WEIGH_MS = 2_000;
 /** How long a step's screenshot may take before the step goes without one. */
 const SCREENSHOT_MS = 15_000;
 
@@ -73,14 +78,37 @@ async function openFirstPage(
 ): Promise<void> {
   const startedAt = Date.now();
   let finished = true;
+  // What its scripts and styles weigh as sent, and how much came uncompressed: a test copy served
+  // straight from its container may skip the compression its real hosting does (Twenty's sent
+  // 10 MB uncompressed, 2026-10-24), and then a slow page says more about the copy than the app.
+  const assets = { files: 0, bytes: 0, uncompressedBytes: 0 };
+  const weighing = new Set<Promise<void>>();
+  const weigh = (request: Request) => {
+    if (request.resourceType() !== "script" && request.resourceType() !== "stylesheet") return;
+    const done = (async () => {
+      const [{ responseBodySize }, encoding] = await Promise.all([request.sizes(), request.response().then((r) => r?.headerValue("content-encoding"))]);
+      assets.files++;
+      assets.bytes += responseBodySize;
+      if (!encoding || encoding === "identity") assets.uncompressedBytes += responseBodySize;
+    })()
+      .catch(() => {}) // the page moved on before it could be weighed
+      .finally(() => weighing.delete(done));
+    weighing.add(done);
+  };
+  page.on("requestfinished", weigh);
   try {
     await page.goto(origin, { waitUntil: "domcontentloaded", timeout: timeoutMs });
   } catch (err) {
     if (!(err instanceof Error && err.name === "TimeoutError")) throw err;
     finished = false;
+  } finally {
+    page.off("requestfinished", weigh);
   }
   const ms = Date.now() - startedAt;
-  if (!finished || ms >= slowMs) signals.note({ kind: "slow_load", url: origin, ms, finished, slowNetwork });
+  if (!finished || ms >= slowMs) {
+    await Promise.race([Promise.allSettled([...weighing]), new Promise((resolve) => setTimeout(resolve, WEIGH_MS))]);
+    signals.note({ kind: "slow_load", url: origin, ms, finished, slowNetwork, ...(assets.files ? { assets: { ...assets } } : {}) });
+  }
 }
 
 export async function runSession(o: RunSessionOptions): Promise<Session> {
@@ -129,6 +157,8 @@ interface SessionState {
 async function takeSteps(o: RunSessionOptions, { signals, system, steps, history, emailedLinks, meter, startedAt, end, reflow }: SessionState): Promise<Session> {
   // The screen-reader agent hears what the browser tells assistive technology and works by keyboard.
   const screenReader = o.persona.inclusion === "screen_reader";
+  let noActionWaits = 0;
+  const askedBeforeGivingUp = new Set<string>();
   for (let index = 0; index < o.maxSteps; index++) {
     if (o.shouldStop && (await o.shouldStop())) return end("cancelled", "run cancelled");
     const { inputTokens, outputTokens } = meter.total;
@@ -144,13 +174,14 @@ async function takeSteps(o: RunSessionOptions, { signals, system, steps, history
     // Now that we can see the page after the previous action, tell the agent what it did.
     const prev = steps.at(-1);
     if (prev) {
-      const effect = describeEffect(prev.action, prev.observation, observation, prev.signals, prev);
+      const effect = describeEffect(prev.action, prev.observation, observation, prev.signals, prev, { screenReader });
       if (effect) history[history.length - 1] += ` → ${effect}`;
     }
     const messages: LlmMessage[] = [{ role: "user", content: buildStepMessage(observation, history, { screenReader }) }];
     let reply: ReturnType<typeof parseAgentReply> | undefined;
     let raw = "";
     let problem = "";
+    let noAction: NoActionError | undefined;
     // Real models occasionally send prose, an empty reply or malformed JSON; say what was wrong and ask again.
     for (let attempt = 0; attempt < MAX_REPLY_ATTEMPTS && !reply; attempt++) {
       raw = await o.llm.complete({ system, messages: [...messages], maxTokens: 4096, onUsage: meter.add });
@@ -158,6 +189,7 @@ async function takeSteps(o: RunSessionOptions, { signals, system, steps, history
         reply = parseAgentReply(raw);
       } catch (err) {
         problem = err instanceof Error ? err.message : String(err);
+        noAction = err instanceof NoActionError ? err : undefined;
         messages.push(
           { role: "assistant", content: raw || "(empty reply)" },
           {
@@ -167,9 +199,47 @@ async function takeSteps(o: RunSessionOptions, { signals, system, steps, history
         );
       }
     }
+    // Asked three times, GLM 5.3 Flash went on sending only its reasoning, often "I will wait", and
+    // the agent ended on an engine error (2026-10-24). It waits instead, as someone unsure what to
+    // do next would; not for ever.
+    if (!reply && noAction && noActionWaits < MAX_NO_ACTION_WAITS) {
+      noActionWaits++;
+      reply = { reasoning: noAction.reasoning, action: { type: "wait" } };
+    }
     if (!reply) {
       return end("error", `${problem} | last reply: ${raw.slice(0, 300) || "(empty)"}`);
     }
+    // Giving up with a way on in plain sight that it never pressed here, or on a page with nothing
+    // to press yet: asked once per page. Still giving up, it gives up.
+    if (reply.action.type === "done" && !reply.action.success && !askedBeforeGivingUp.has(observation.url)) {
+      const wayOn = untriedWaysOn(observation, steps, screenReader);
+      const ask = wayOn.length
+        ? `Before you give up: on this page you haven't tried ${wayOn.map((n) => `"${n}"`).join(", ")}. Someone who wanted to get on would try that first.`
+        : nothingToPressYet(observation)
+          ? "Before you give up: nothing on this page can be pressed yet, so it may still be loading. Someone who wanted to get on would wait a little first."
+          : "";
+      if (ask) {
+        askedBeforeGivingUp.add(observation.url);
+        const again = await o.llm.complete({
+          system,
+          messages: [
+            ...messages,
+            { role: "assistant", content: raw },
+            {
+              role: "user",
+              content: `${ask} Reply again with one JSON object: go on, or give up if you are sure.`,
+            },
+          ],
+          maxTokens: 4096,
+          onUsage: meter.add,
+        });
+        try {
+          reply = parseAgentReply(again);
+        } catch {
+          // an unreadable second answer leaves the first one standing
+        }
+      }
+    }
 
     let result: ActionResult;
     let historyLine = describeAction(reply.action, observation);

package/src/agent/parse-reply.ts

@@ -19,7 +19,56 @@ export function parseAgentReply(raw: string): { reasoning: string; action: Actio
   const start = raw.indexOf("{");
   const end = raw.lastIndexOf("}");
   if (start === -1 || end <= start) throw new Error("no JSON object in agent reply");
-  return ReplySchema.parse(actionAsObject(parseQuotedAction(raw.slice(start, end + 1))));
+  const reply = actionAsObject(parseQuotedAction(raw.slice(start, end + 1)));
+  const parsed = ReplySchema.safeParse(reply);
+  if (!parsed.success) throw new Error(problemWith(reply, parsed.error));
+  return parsed.data;
+}
+
+/** A reply with reasoning and no action. It carries the reasoning, so the agent can be left to wait. */
+export class NoActionError extends Error {
+  constructor(readonly reasoning: string) {
+    super(`the reply has no "action". Add one, for example {"reasoning":"…","action":{"type":"wait"}}`);
+  }
+}
+
+// Said back to the agent when it is asked again, so in words it can act on. Shown the validator's
+// own JSON for a reply with reasoning and no action, one model sent the same reply three times.
+function problemWith(reply: unknown, error: z.ZodError): string {
+  if (reply && typeof reply === "object" && !("action" in reply)) {
+    const reasoning = (reply as { reasoning?: unknown }).reasoning;
+    throw new NoActionError(typeof reasoning === "string" ? reasoning : "");
+  }
+  return error.issues.map((i) => `${i.path.join(".") || "reply"}: ${i.message}`).join("; ");
+}
+
+/**
+ * The reply split into objects one after another, merged: {"reasoning":"…"} and on the next line
+ * {"action":"press","key":"Enter"} (GLM 5.3 Flash, 2026-10-24, twice in one run). When two whole
+ * replies come, the first one counts. Undefined when there is only one object or one doesn't parse.
+ */
+function splitReply(text: string): Record<string, unknown> | undefined {
+  const objects: string[] = [];
+  let depth = 0;
+  let from = 0;
+  let inString = false;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (inString) {
+      if (c === "\\") i++;
+      else if (c === '"') inString = false;
+    } else if (c === '"') inString = true;
+    else if (c === "{" && depth++ === 0) from = i;
+    else if (c === "}" && depth > 0 && --depth === 0) objects.push(text.slice(from, i + 1));
+  }
+  if (objects.length < 2) return undefined;
+  try {
+    const parsed = objects.map((o) => JSON.parse(o) as unknown);
+    if (!parsed.every((p) => p && typeof p === "object" && !Array.isArray(p))) return undefined;
+    return Object.assign({}, ...(parsed as Record<string, unknown>[]).reverse());
+  } catch {
+    return undefined;
+  }
 }
 
 // Some models (GLM 5.3 Flash) send the action as a string. Unescaped,
@@ -31,6 +80,8 @@ function parseQuotedAction(text: string): unknown {
   try {
     return JSON.parse(text);
   } catch (err) {
+    const split = splitReply(text);
+    if (split) return split;
     const unquoted = text.replace(/("action"\s*:\s*)"(\{[^{}]*\})"/, "$1$2");
     if (unquoted !== text) {
       try {

package/src/agent/prompt.ts

@@ -1,6 +1,9 @@
 import { inclusionBrief } from "../persona/inclusion";
 import { languageBrief } from "../persona/language";
 import type { InteractiveElement, Observation, Persona } from "../types";
+import { controlLabel, type StepView } from "./label";
+
+export type { StepView } from "./label";
 
 // Stays constant for the whole session so providers can cache it; everything that changes goes in the user message.
 export interface AgentIdentity {
@@ -38,24 +41,30 @@ Action is one of:
 {"type":"fill","id":number,"text":string}  (on a select or dropdown, text is the option to choose)
 {"type":"upload","id":number,"file":"photo"|"document"}  (attach a file through an upload button or file field: you have a sample photo and a sample CV/document)
 {"type":"goto","path":string}
-{"type":"press","key":"Escape"|"Enter"|"Tab"|"ArrowDown"|"ArrowUp"}  (e.g. Escape closes a popup that blocks the page)
+{"type":"press","key":"Escape"|"Enter"|"Space"|"Tab"|"ArrowDown"|"ArrowUp"}  (e.g. Escape closes a popup that blocks the page; Space presses the focused button or ticks a box)
 {"type":"wait"}  (the page is still loading, e.g. a spinner or a form that has not appeared yet: wait a few seconds rather than leave)${identity ? `\n{"type":"check_email"}` : ""}
 {"type":"done","success":boolean,"note":string}`;
 }
 
+/** A control's state, as a person sees it (and a screen reader announces it). */
+function stateOf(e: InteractiveElement): string {
+  const states = [
+    e.disabled ? "disabled" : "",
+    e.readOnly ? "read-only" : "",
+    e.checked === undefined ? "" : e.checked ? "checked" : "not checked",
+    e.expanded === undefined ? "" : e.expanded ? "open" : "closed",
+    e.filled ? "filled in" : "",
+    !e.options && e.value ? `holds "${e.value}"` : "",
+  ].filter(Boolean);
+  return states.length ? ` (${states.join(", ")})` : "";
+}
+
 function describeElement(e: InteractiveElement, screenReader = false): string {
-  // A screen reader announces the role and name the browser gives it.
-  const heard = screenReader && e.ax ? e.ax : e;
-  const line = `[${e.id}] ${heard.role} "${heard.name}"`;
+  const line = `[${e.id}] ${controlLabel(e, screenReader)}${stateOf(e)}`;
   if (!e.options) return line;
   return `${line} set to "${e.value ?? ""}", options: ${e.options.map((o) => `"${o}"`).join(" | ")}`;
 }
 
-export interface StepView {
-  /** As a screen reader presents the page: the browser's names and roles, without what is hidden from it. */
-  screenReader?: boolean;
-}
-
 export function buildStepMessage(obs: Observation, history: string[], view: StepView = {}): string {
   const shown = view.screenReader ? obs.elements.filter((e) => !e.ax?.hidden) : obs.elements;
   const elements = shown.map((e) => describeElement(e, view.screenReader)).join("\n");

package/src/browser/execute.ts

@@ -37,6 +37,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
@@ -60,11 +101,25 @@ const focusCoveredScript = (id: number) => `(() => {
 })()`;
 
 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 });
   return ((await page.evaluate(focusCoveredScript(id))) as string | null) ?? undefined;
 }
@@ -198,6 +253,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 +273,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 +290,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] });
@@ -283,7 +343,10 @@ 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 });
@@ -328,10 +391,10 @@ 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 : {};
+    return result.focusObscured || result.enterIgnored ? 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

@@ -50,7 +50,13 @@ 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 };
 }

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

@@ -131,7 +131,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 +161,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];
@@ -208,7 +222,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);
   });
@@ -514,6 +529,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(

package/src/init.ts

@@ -103,15 +103,15 @@ async function guessCustomers(url: string): Promise<string | undefined> {
   }
 }
 
-export async function init(cwd: string = process.cwd()): Promise<number> {
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
+export async function init(cwd: string = process.cwd(), input: NodeJS.ReadableStream & { isTTY?: boolean } = process.stdin): Promise<number> {
+  const rl = createInterface({ input, output: process.stdout });
   // Lines are buffered, so answers piped in by a script aren't lost between questions; at the end
   // of the input every question takes its default.
   const lines = rl[Symbol.asyncIterator]();
   const ask = async (question: string, fallback = "") => {
     process.stdout.write(fallback ? `${question} [${fallback}] ` : `${question} `);
     const { value, done } = await lines.next();
-    if (done || !process.stdin.isTTY) process.stdout.write("\n");
+    if (done || !input.isTTY) process.stdout.write("\n");
     return (done ? "" : String(value).trim()) || fallback;
   };
   try {
@@ -126,8 +126,9 @@ export async function init(cwd: string = process.cwd()): Promise<number> {
     console.log("\nWhat should the agents try to do?");
     GOALS.forEach((g, i) => console.log(`  ${i + 1}. ${g}`));
     console.log("  4. Something else");
-    const pick = await ask("Choose 1-4:", "1");
-    const goal = GOALS[Number(pick) - 1] ?? (await ask("Describe it in a sentence:"));
+    // A goal typed here instead of a number is the goal.
+    const pick = await ask("Choose 1-4, or type the goal:", "1");
+    const goal = GOALS[Number(pick) - 1] ?? (/^\d*$/.test(pick) ? await ask("Describe it in a sentence:") : pick);
 
     const guess = await guessCustomers(url);
     const icp = await ask("\nWho are your customers? One sentence, e.g. who they are and how big.", guess);

package/src/persona/people.ts

@@ -0,0 +1,32 @@
+import { readFile } from "node:fs/promises";
+import type { CustomerUnit } from "../types";
+
+/** Each run writes its people here, next to the report, so a later run can meet the same ones. */
+export const PEOPLE_FILE = "people.json";
+
+/**
+ * The people of an earlier run, to run the same agents again: after a fix, whether it worked is
+ * only clear with the same people, needs and languages. Generated afresh, a run had a different
+ * crew every day (needs rotate daily), and two runs of one app could not be compared.
+ */
+export async function readPeople(path: string): Promise<CustomerUnit[]> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(await readFile(path, "utf8"));
+  } catch (err) {
+    throw new Error(`${path} can't be read: ${err instanceof Error ? err.message : err}`);
+  }
+  const ok = (u: unknown) => {
+    const unit = u as Partial<CustomerUnit> | null;
+    if (!unit || typeof unit !== "object" || typeof unit.id !== "string") return false;
+    if (unit.kind === "individual") return !!unit.person?.id;
+    return unit.kind === "business" && !!unit.owner?.id && Array.isArray(unit.employees);
+  };
+  if (!Array.isArray(parsed) || !parsed.length || !parsed.every(ok)) {
+    throw new Error(`${path} doesn't hold a run's people: use the ${PEOPLE_FILE} from an earlier run's report folder.`);
+  }
+  return parsed as CustomerUnit[];
+}
+
+/** How many agents the units make: everyone in a crew is one. */
+export const peopleCount = (units: CustomerUnit[]) => units.reduce((n, u) => n + (u.kind === "individual" ? 1 : 1 + u.employees.length), 0);

package/src/report/fix-first.ts

@@ -0,0 +1,121 @@
+import { UNCOMPRESSED } from "../detect/findings";
+import type { Finding, Session } from "../types";
+
+/** At most this many items, so the section reads in a couple of minutes. */
+const MAX_ITEMS = 5;
+const MAX_QUOTE = 200;
+const RANK: Record<Finding["severity"], number> = { blocker: 0, major: 1, minor: 2 };
+
+// Agents that didn't reach the goal because of the app, or seemingly so. An engine error or a
+// cancelled run says nothing about the app; a run cut short for credit has its own section.
+const STOPPED: Partial<Record<Session["outcome"], string>> = {
+  gave_up: "gave up",
+  budget_exhausted: "ran out of steps",
+  not_invited: "never got an invite",
+};
+
+/** What to do about a finding, in a line. */
+export function nextStep(f: Finding): string {
+  switch (f.kind) {
+    case "http_error": {
+      const status = Number(/^HTTP (\d{3})/.exec(f.title)?.[1] ?? 0);
+      return status >= 500
+        ? "The server failed: its log for this request says why."
+        : "The server refused the request: compare what the page sent with what the server expects.";
+    }
+    case "page_error":
+      return "Fix the JavaScript error; the reproduction below shows the step that sets it off.";
+    case "console_error":
+      return "Read the error in the browser console on that page.";
+    case "a11y_unlabeled":
+      if (f.control?.problem === "placeholder") return "Give the field a visible <label>, and keep the placeholder as an example.";
+      if (f.control?.problem === "described") return "Name it: visible text or an aria-label, with the description kept as a hint.";
+      if (f.control && !/^(button|link|menuitem|tab|summary)/.test(f.control.role)) return "Give each one a <label> (or an aria-label) that says what goes in it.";
+      return 'Give each one visible text, or an aria-label that says what it does (aria-label="Open menu" on a menu icon).';
+    case "stuck":
+      return "Watch the reproduction below: the agent repeated an action that seemed to do nothing. Make the page show that it worked, or why it didn't.";
+    case "slow_load":
+      return f.detail.includes(UNCOMPRESSED)
+        ? "Turn on compression (gzip or Brotli) for scripts and styles, or check that the real site has it."
+        : "Find what holds the page up: the agents sat waiting for it.";
+    case "covered":
+      return "Move or close whatever lies over the control, so it can be clicked.";
+    case "keyboard":
+      if (f.signature.startsWith("enter:")) return "Let Enter press it too: look for a key handler that catches Enter and stops it (a page-wide shortcut, a form's own Enter handling).";
+      return 'Use a real <button> or <a>, or add tabindex="0" and handle Enter and Space.';
+    case "focus_obscured":
+      return "Keep the control with keyboard focus in view: move or shrink what covers it.";
+    case "reflow":
+      return "Let the page wrap at narrow widths instead of scrolling sideways: look for fixed widths.";
+    case "language":
+      if (f.signature.startsWith("dir:")) return 'Set dir="rtl" on Arabic pages (on <html>, or on the part that holds the Arabic).';
+      if (f.signature === "lang:missing") return 'Add a lang attribute to the <html> element, e.g. lang="en".';
+      return 'Set lang="ar" on Arabic pages.';
+    case "zoom":
+      return "Remove user-scalable=no and maximum-scale from the page's viewport meta tag.";
+  }
+}
+
+const lastPath = (s: Session) => {
+  try {
+    return new URL(s.steps.at(-1)?.observation.url ?? "").pathname;
+  } catch {
+    return "";
+  }
+};
+
+const quote = (s: string) => `"${s.length > MAX_QUOTE ? `${s.slice(0, MAX_QUOTE)}…` : s}"`;
+
+/** A screenshot as the report's reader finds it: next to the report, not on the machine that ran it. */
+export function shotPath(path: string): string {
+  if (/^https?:/.test(path)) return path;
+  const at = path.replace(/\\/g, "/").lastIndexOf("/screenshots/");
+  return at >= 0 ? path.replace(/\\/g, "/").slice(at + 1) : path;
+}
+
+function stoppedItem(s: Session, needs: string, environment: boolean): string {
+  const who = [s.role, needs !== "—" ? needs : ""].filter(Boolean).join("; ");
+  const where = lastPath(s) ? ` on ${lastPath(s)}` : "";
+  const shot = [...s.steps].reverse().find((st) => st.screenshotPath)?.screenshotPath;
+  // Out of steps, the note only says so; the agent's last thought says where it was.
+  const said = s.outcome === "budget_exhausted" && s.steps.at(-1)?.reasoning ? `Its last thought: ${quote(s.steps.at(-1)!.reasoning)}` : `In the agent's words: ${quote(s.outcomeNote)}`;
+  return [
+    `**${s.personaName}${who ? ` (${who})` : ""} ${STOPPED[s.outcome]}${where}.** ${said}`,
+    environment ? "Part of it may be the test environment: see the end of the report." : "",
+    shot ? `Start with the last screenshot, ${shotPath(shot)}.` : "",
+  ]
+    .filter(Boolean)
+    .join(" ");
+}
+
+/**
+ * The few things to look at first: agents the app seemingly stopped, in their own words, then the
+ * blocker and major findings, those that stopped an agent first, each with what to do.
+ */
+export function renderFixFirst(sessions: Session[], findings: Finding[], needLabel: (s: Session) => string): string[] {
+  const stopped = sessions.filter((s) => STOPPED[s.outcome]);
+  const failed = new Set(stopped.map((s) => s.agentId));
+  const caused = findings.filter((f) => f.sandboxCause);
+  const serious = findings
+    .filter((f) => !f.sandboxCause && f.confidence !== "low" && f.severity !== "minor")
+    .map((f, order) => ({ f, order, stoppedSome: f.hitBy.some((id) => failed.has(id)) }))
+    // Most severe first; within that, one an agent didn't get past.
+    .sort((a, b) => RANK[a.f.severity] - RANK[b.f.severity] || Number(b.stoppedSome) - Number(a.stoppedSome) || a.order - b.order)
+    .map(({ f }) => f);
+  const reached = sessions.filter((s) => s.outcome === "success").length;
+  const stops = stopped.slice(0, MAX_ITEMS).map((s) => stoppedItem(s, needLabel(s), caused.some((f) => f.hitBy.includes(s.agentId))));
+  const fixes = serious.slice(0, MAX_ITEMS - stops.length).map((f) => `**${f.title}** (${f.severity}). ${nextStep(f)}`);
+  const shown = [...stops, ...fixes];
+  const rest = findings.filter((f) => !f.sandboxCause).length - fixes.length;
+  return [
+    `## Fix these first`,
+    "",
+    `${reached} of ${sessions.length} agents reached the goal.`,
+    "",
+    ...(shown.length
+      ? shown.map((item, i) => `${i + 1}. ${item}`)
+      : ["Nothing stopped an agent, and nothing serious was found."]),
+    ...(rest > 0 ? ["", `${rest === 1 ? "One" : rest}${fixes.length ? " more" : ""} ${rest === 1 ? "finding is" : "findings are"} below.`] : []),
+    "",
+  ];
+}

package/src/report/markdown.ts

@@ -4,6 +4,7 @@ import { describeCriterion } from "../detect/wcag";
 import { OUT_OF_CREDITS } from "../llm/types";
 import { languageName } from "../persona/language";
 import type { CustomerUnit, Finding, Session } from "../types";
+import { renderFixFirst, shotPath } from "./fix-first";
 
 export interface ReportInput {
   targetUrl: string;
@@ -40,7 +41,7 @@ function renderFinding(f: Finding, sessions: Session[]): string {
       lines.push(`${step.index + 1}. ${describeAction(step.action, step.observation)} — "${step.reasoning}"`);
     }
     const shot = session.steps[ev.stepIndex]?.screenshotPath;
-    if (shot) lines.push("", `Screenshot: ${shot}`);
+    if (shot) lines.push("", `Screenshot: ${shotPath(shot)}`);
   }
   return lines.join("\n");
 }
@@ -164,6 +165,7 @@ export function renderReport(input: ReportInput): string {
     `Findings: ${count("blocker")} blocker, ${count("major")} major, ${count("minor")} minor (${low.length} low-confidence${caused.length ? `, ${caused.length} caused by the test environment` : ""})`,
     "",
     ...renderOutOfCredits(input.sessions),
+    ...renderFixFirst(input.sessions, input.findings, needLabel),
     ...renderUnits(input.units ?? [], input.sessions),
     `## Agent outcomes`,
     "",

package/src/run.ts

@@ -7,6 +7,7 @@ import { runUnit, type RunAgent } from "./crew/run-unit";
 import { detectFindings } from "./detect/findings";
 import type { Inbox } from "./inbox/types";
 import type { LlmClient } from "./llm/types";
+import { PEOPLE_FILE } from "./persona/people";
 import { renderReport } from "./report/markdown";
 import type { ModelPrice } from "./llm/meter";
 import { blockedCalls, type SandboxOutbox } from "./sandbox/outbox";
@@ -43,8 +44,8 @@ export interface SimulationOptions {
   price?: ModelPrice | null;
   /** In-memory kill switch when there is no store (e.g. Ctrl+C). */
   shouldStop?: () => boolean | Promise<boolean>;
-  /** Where to keep each agent's browser state (cookies, storage) at the end, for `debutly hear`. */
-  browserStateDir?: string;
+  /** Where to keep each agent's browser state (cookies, storage) at the end, for `debutly hear`. */
+  browserStateDir?: string;
   /** Sends each agent somewhere else to run (e.g. a queue of workers) instead of this process. */
   dispatch?: (ctx: { runId?: string; runTag: string }) => RunAgent;
 }
@@ -120,6 +121,7 @@ export async function runSimulation(o: SimulationOptions): Promise<SimulationRes
     const reportPath = join(o.outDir, "report.md");
     await writeFile(join(o.outDir, "sessions.json"), JSON.stringify(sessions, null, 2));
     await writeFile(join(o.outDir, "findings.json"), JSON.stringify(findings, null, 2));
+    await writeFile(join(o.outDir, PEOPLE_FILE), JSON.stringify(o.units, null, 2));
     await writeFile(reportPath, reportMd);
     if (store && runId) {
       const status = sessions.some((s) => s.outcome === "cancelled") ? "cancelled" : "finished";

package/src/types.ts

@@ -33,7 +33,7 @@ export type CustomerUnit =
   | { kind: "business"; id: string; business: Business; owner: Persona; employees: Persona[] };
 
 /** Keys a person uses to drive popups and forms; nothing that could close tabs or run shortcuts. */
-export const PRESS_KEYS = ["Escape", "Enter", "Tab", "ArrowDown", "ArrowUp"] as const;
+export const PRESS_KEYS = ["Escape", "Enter", "Space", "Tab", "ArrowDown", "ArrowUp"] as const;
 export type PressKey = (typeof PRESS_KEYS)[number];
 
 export type Action =
@@ -55,7 +55,8 @@ export type Signal =
   | { kind: "http_error"; status: number; requestUrl: string; url: string; startedAt?: number; at?: number; body?: string }
   | { kind: "dialog"; dialogType: string; message: string; url: string }
   // A page that took long to arrive. finished: false when the agent's wait ran out first.
-  | { kind: "slow_load"; url: string; ms: number; finished: boolean; slowNetwork: boolean }
+  // assets: the scripts and styles received by then, as sent, and how much of that came uncompressed.
+  | { kind: "slow_load"; url: string; ms: number; finished: boolean; slowNetwork: boolean; assets?: { files: number; bytes: number; uncompressedBytes: number } }
   // A file the page handed over (a report, an export): the page itself often doesn't change.
   | { kind: "download"; filename: string; url: string };
 
@@ -73,9 +74,18 @@ export interface InteractiveElement {
   role: string;
   name: string;
   tag: string;
-  /** A native select's chosen option and its options, by label. */
+  /** What a field holds: a native select's chosen option, or a text field's text (never a password's). */
   value?: string;
+  /** A native select's options, by label. */
   options?: string[];
+  /** A password field with something typed in it. */
+  filled?: true;
+  /** Shown but not editable. */
+  readOnly?: true;
+  /** A checkbox, radio button or switch: on or off. */
+  checked?: boolean;
+  /** A control that opens something (a menu, a dropdown): open or closed. */
+  expanded?: boolean;
   /** The browser's own accessible name and role (Chromium), as a screen reader would announce them. */
   ax?: AccessibleName;
   /** Named only by its placeholder: no label, aria-label or aria-labelledby. */
@@ -84,6 +94,8 @@ export interface InteractiveElement {
   disabled?: true;
   /** Out of the tab order (tabindex -1, or inside an inert part of the page). */
   tabbable?: false;
+  /** A control with no text: the icon it shows, as its markup names it ("menu", "trash"). What a sighted person sees. */
+  icon?: string;
 }
 
 export interface Observation {
@@ -104,6 +116,8 @@ export interface ActionResult {
   error?: string;
   /** Keyboard only: what entirely hid the control once it had focus. */
   focusObscured?: string;
+  /** Keyboard only: Enter did nothing on the button, and Space pressed it. */
+  enterIgnored?: true;
 }
 
 export interface Step extends ActionResult {