@beryl-so/cli 0.78.0 → 0.92.1

package/README.md

@@ -54,6 +54,11 @@ beryl runs trigger --url-override "$PREVIEW_URL" --watch --timeout 30
 
 Exit codes: `0` success / all tests passed · `1` failure · `2` usage error · `3` auth error.
 
+A project CI token (`BERYL_TOKEN=beryl_ci_…`, from the project's Settings, CI tab) is
+enough to trigger runs and to turn a brief into tests: `beryl jobs create "Cover the brief" --file ./brief.md --ci`
+(pass `--workspace` and `--project` ids). A CI job never waits for input; what a login
+blocks is listed as skipped in `beryl jobs get`.
+
 ## MCP server
 
 ```bash
@@ -176,7 +181,8 @@ Create and manage projects: a site you author tests for and run.
 | `beryl projects create [url]` | Create a project for a URL, or an empty one with just --name | `projects_create` |
 | `beryl projects rename <name>` | Rename a project | `projects_rename` |
 | `beryl projects quarantine [state]` | Turn auto quarantine on or off and tune when it mutes and releases a test | `projects_quarantine` |
-| `beryl projects surfaces <surfaces...>` | Set which surfaces are enabled for this project | `projects_surfaces` |
+| `beryl projects heal [state]` | Turn self-heal on or off for a project and limit its time and runs | `projects_heal` |
+| `beryl projects surfaces [surfaces...]` | Turn project surfaces on or off | `projects_surfaces` |
 | `beryl projects findings-gate <mode>` | Turn the findings gate on each run on or off | `projects_findings_gate` |
 | `beryl projects delete` | Delete a project and all its tests and runs | `projects_delete` |
 | `beryl projects re-explore` | Send the agent back in to run/heal existing tests and discover new flows | none |
@@ -217,7 +223,7 @@ Author, inspect, version, and heal a project's tests: the checks Beryl runs on e
 | `beryl tests list` | List the project's tests with their latest result | `tests_list` |
 | `beryl tests get <test-id>` | Show one test | `tests_get` |
 | `beryl tests plan <test-id>` | Print a test's current step plan (JSON) | `tests_plan` |
-| `beryl tests set-plan <test-id>` | Replace a test's step plan from a JSON file (creates a new version) | `tests_set_plan` |
+| `beryl tests set-plan <test-id>` | Replace a test's step plan (creates a new version) | `tests_set_plan` |
 | `beryl tests rename <test-id> <title>` | Rename a test | `tests_rename` |
 | `beryl tests set-intent <test-id> <intent>` | Edit what a test proves, the target heal judges against | `tests_set_intent` |
 | `beryl tests set-groups <test-id>` | Replace the groups a test belongs to | `tests_set_groups` |
@@ -259,12 +265,13 @@ Trigger a run of a project's tests (e.g. in CI), then watch, inspect, and downlo
 | Command | Summary | MCP tool |
 | --- | --- | --- |
 | `beryl runs trigger` | Trigger a test run (whole suite, a subset, or one environment) | `runs_trigger` |
+| `beryl runs queue` | Show the run in flight and the runs waiting behind it | `runs_queue` |
 | `beryl runs list` | List recent runs | `runs_list` |
 | `beryl runs get <run-id>` | Show one run with its per-test results | `runs_get` |
 | `beryl runs watch <run-id>` | Follow a run until it finishes | `runs_watch` |
-| `beryl runs cancel <run-id>` | Cancel an in-flight run | `runs_cancel` |
+| `beryl runs cancel <run-id>` | Cancel an in-flight run, or take a queued one out of the queue | `runs_cancel` |
 | `beryl runs report <run-id>` | Show the generated report for a run | `runs_report` |
-| `beryl runs download <run-id>` | Download a run's results, with its artifacts, to disk | `runs_download` |
+| `beryl runs download <run-id>` | Get a run's results with signed artifact URLs, or download them to disk | `runs_download` |
 | `beryl runs explain <result-id>` | Explain, with AI, why a test result failed | `runs_explain` |
 
 ### health
@@ -287,14 +294,15 @@ Site Health, or how your site reads to search engines and visitors: content, spe
 
 ### jobs
 
-Test-creation jobs: the cloud agent reads a document and authors tests from it.
+Test-creation jobs: the cloud agent follows a prompt, reads any document it comes with, and authors tests.
 
 | Command | Summary | MCP tool |
 | --- | --- | --- |
-| `beryl jobs create [file]` | Create tests from a document (PRD, release notes) on Beryl's cloud | `jobs_create` |
+| `beryl jobs create <prompt>` | Create tests from a prompt, with an optional document, on Beryl's cloud | `jobs_create` |
 | `beryl jobs list` | List the project's test-creation jobs | `jobs_list` |
 | `beryl jobs get <job-id>` | Show a job's status and the tests it created | `jobs_get` |
-| `beryl jobs clone <job-id>` | Run a job again: queue a new job with the same document and environment | `jobs_clone` |
+| `beryl jobs clone <job-id>` | Run a job again: queue a new job with the same prompt, document, environment and account | `jobs_clone` |
+| `beryl jobs retry <job-id>` | Author only what a partial or failed job left out, optionally with an edited prompt or document | `jobs_retry` |
 | `beryl jobs delete <job-id>` | Delete a job; the flows and tests it created stay | `jobs_delete` |
 
 ### explorations
@@ -323,6 +331,9 @@ Manage the variables, secrets, and files the agent can use while exploring and r
 | `beryl config secrets set <key> <value>` | Create a secret (write-only; re-setting a key replaces it) | `config_secrets_set` |
 | `beryl config secrets get <key>` | Show one secret's metadata, or reveal its value with --reveal | `config_secrets_get` |
 | `beryl config secrets delete <key>` | Delete a secret | `config_secrets_delete` |
+| `beryl config signing get` | Which key signs Android builds converted from an .aab, with its fingerprints | `config_signing_get` |
+| `beryl config signing set` | Sign converted Android builds with your own keystore | `config_signing_set` |
+| `beryl config signing clear` | Forget your keystore; converted builds go back to Beryl's key | `config_signing_clear` |
 | `beryl config files list` | List uploaded files: fixtures tests attach and Android and iOS app builds | `config_files_list` |
 | `beryl config files get <file>` | Show one uploaded file's metadata | `config_files_get` |
 | `beryl config files upload <file>` | Upload a file: a fixture an upload step attaches, or an Android or iOS app build | `config_files_upload` |

package/dist/adapters/mcp.js

@@ -42,8 +42,8 @@ function commandToTool(text) {
 function flagsToParams(text, wrap) {
     return text
         .replace(/--json\b/g, "JSON output (always on over MCP)")
-        .replace(/--no-([a-z][a-z-]*)/g, (_, name) => flagNames.has(`no-${name}`) ? wrap(`no-${name}`) : wrap(`${name}: false`))
-        .replace(/--([a-z][a-z-]*)/g, (_, name) => wrap(name));
+        .replace(/--no-([a-z][a-z0-9-]*)/g, (_, name) => flagNames.has(`no-${name}`) ? wrap(`no-${name}`) : wrap(`${name}: false`))
+        .replace(/--([a-z][a-z0-9-]*)/g, (_, name) => wrap(name));
 }
 /** Registry text is written for `beryl --help`; the agent sees JSON parameters and tool
  *  names, so `--wide` becomes `wide`, `beryl groups list` becomes `groups_list`, and a
@@ -78,12 +78,14 @@ export function toolInputSchema(spec) {
         properties[f.name] =
             f.type === "strings"
                 ? { type: "array", items: { type: "string" }, description, ...withDefault }
-                : {
-                    type: f.type,
-                    description,
-                    ...(f.enum ? { enum: f.enum } : {}),
-                    ...withDefault,
-                };
+                : f.type === "json"
+                    ? { type: "object", description }
+                    : {
+                        type: f.type,
+                        description,
+                        ...(f.enum ? { enum: f.enum } : {}),
+                        ...withDefault,
+                    };
         if (f.required)
             required.push(f.name);
     }
@@ -156,6 +158,16 @@ export function exampleArgs(spec, example) {
         // parseArgv fills declared defaults in; only what the example explicitly set teaches.
         if (value === undefined || value === f?.default)
             continue;
+        if (f?.type === "json") {
+            // Over MCP a json flag is an object; an example that passes a path teaches the wrong shape.
+            try {
+                out[name] = JSON.parse(String(value));
+            }
+            catch {
+                return null;
+            }
+            continue;
+        }
         out[name] =
             f?.type === "number" && typeof value === "string" && Number.isFinite(Number(value))
                 ? Number(value)
@@ -280,8 +292,9 @@ export function mcpInstructions() {
         "action plans replayed in real cloud browsers, signing in as a durable test " +
         "account whose mail arrives at the project's own mailbox, so signup/OTP/" +
         "magic-link flows are self-contained, with no human login needed. " +
-        "New tests are authored only by Beryl's cloud agent: give it a document describing " +
-        "the flows with `jobs_create`; there is no local authoring. " +
+        "New tests are authored only by Beryl's cloud agent: give it a prompt saying what " +
+        "to test, plus a document if there is one, with `jobs_create`; there is no local " +
+        "authoring. " +
         "The guide (plan shape, outcome assertions, accounts, email/OTP wiring, the " +
         "run-fix loop) ships as both the beryl-test skill and the `guide` tool, same " +
         `content. If a beryl-test skill stating v${version} is already loaded, do not ` +

package/dist/beryl-test-skill.js

@@ -5,6 +5,7 @@
 // embedded string so it ships in the published package (`files: ["dist"]`) with no
 // build-time asset copy, and so there is ONE source for the guidance — not a copy in
 // the CLI and another in the docs. Edit here; `init` writes it verbatim.
+import { SESSION_CAPTURE_EXTENSION_URL } from "./config.js";
 import { actionTable, expectTable, extractLine } from "./skill-tables.js";
 import { cliVersion } from "./version-check.js";
 const indent = (text) => text
@@ -23,7 +24,8 @@ ActionPlan shape, outcome assertions, test accounts and the project mailbox, and
 local run-fix loop.
 
 Then use the Beryl MCP tools: \`projects_list\` to find the project, \`jobs_create\` to
-have Beryl's cloud agent author tests from a document, and \`runs_trigger\` to run them.
+have Beryl's cloud agent author tests from a prompt (plus any document), and
+\`runs_trigger\` to run them.
 
 The \`guide\` tool ships with the CLI and always matches the installed version, so treat
 it as the source of truth over anything cached here.`;
@@ -90,7 +92,7 @@ export const BERYL_TEST_SKILL_OTP_EXAMPLE_PLAN = {
 };
 export const BERYL_TEST_SKILL = `---
 name: beryl-test
-description: Create, run, and fix durable, healable end-to-end tests for a web app with Beryl. Use when asking Beryl's cloud agent to create tests from a document (\`jobs_create\`), running them in Beryl's cloud with \`runs_trigger\`, setting up test accounts, or fixing a banked test's plan with your own coding agent.
+description: Create, run, and fix durable, healable end-to-end tests for a web app with Beryl. Use when asking Beryl's cloud agent to create tests from a prompt and an optional document (\`jobs_create\`), running them in Beryl's cloud with \`runs_trigger\`, setting up test accounts, or fixing a banked test's plan with your own coding agent.
 ---
 
 # Beryl tests
@@ -108,15 +110,24 @@ it durable: a real **outcome assertion**, a strong **natural-language intent**,
 ## 0. Start here
 
 **New tests are authored only by Beryl's cloud agent.** There is no local authoring: you
-do not draft a new plan here. A human writes a document (a PRD, release notes, a list of
-flows) and \`jobs_create\` hands it to the agent, which explores the environment and
-authors one test per scenario and surface. \`jobs_get\` shows the job's status, the tests
-it produced and any scenario it skipped. The document is sent to the LLM that drives the
-agent, so it must not hold anything the user would not share with it.
+do not draft a new plan here. A human writes a prompt (what to test; a line is enough)
+and, if they have one, attaches a document (a PRD, release notes, a list of flows);
+\`jobs_create\` hands both to the agent, which explores the environment and authors one
+test per scenario and surface. \`jobs_get\` shows the job's status, the tests it produced
+and any scenario it skipped. The prompt and document are sent to the LLM that drives the
+agent, so they must not hold anything the user would not share with it.
 
 What you do here: set up the accounts tests sign in as (§1), trigger and read runs
 (§4), and fix a banked test's plan when it needs it (§2).
 
+Files: the Beryl tools may not share your filesystem, so read local files with your own
+file tools and pass the content inline. A plan, session or probe goes in as a JSON
+object (\`plan\`, \`session\`, \`probe\`); a document goes to \`jobs_create\` as
+\`text\`, or a PDF or DOCX as \`content-base64\` plus \`filename\`, alongside the
+required \`prompt\`. Outputs come back
+the same way: \`tests_export\` with \`inline\` returns the spec files, and
+\`runs_download\` with no \`dir\` returns signed artifact URLs to fetch.
+
 Set up (once): if you cannot call the Beryl tools yet, run \`beryl init\` in a terminal
 to wire them. Then, before the first job:
 
@@ -133,16 +144,20 @@ login plan is stored.
 
 Then:
 
-1. **Create tests** with \`jobs_create\` (the document, and the environment to
-   explore). \`jobs_get\` shows progress, the tests it banked (each one already
+1. **Create tests** with \`jobs_create\` (the prompt, any document, and the environment
+   to explore). \`jobs_get\` shows progress, the tests it banked (each one already
    proven by a clean replay), and every scenario it skipped, with why.
 2. A job can pause as \`awaiting_input\` when the app's login wall blocks it (no
    self-serve signup). Its \`needs\` field says what to do: capture a signed-in
-   session with the Beryl browser extension from the webapp. The job resumes by
+   session with the Beryl Chrome extension (${SESSION_CAPTURE_EXTENSION_URL}). The job resumes by
    itself and keeps everything it already banked.
-3. When the job is done, run the new ids together ONCE with \`runs_trigger\` so they
+3. A job ends \`done\`, \`partial\` (some tests saved; its \`error\` and
+   \`skipped_flows\` say what is missing and why) or \`failed\`. \`jobs_retry\`
+   authors only what a partial or failed job left out, optionally with an edited
+   prompt or document; the new tests join the same flows.
+4. When the job is done, run the new ids together ONCE with \`runs_trigger\` so they
    land as one run with real first results.
-4. **A test is red or wrong?** Fix its plan with the run-fix loop (§4).
+5. **A test is red or wrong?** Fix its plan with the run-fix loop (§4).
 
 ## 1. First: who do your tests sign in as?
 
@@ -190,14 +205,21 @@ The trade is drift — run 200 has 200 of everything run 1 created. So:
   it.** \`after\` runs on pass AND fail; a trailing step inside \`steps\` does not, so
   never put cleanup in \`steps\`.
   - **Created something?** Delete it in \`after\`.
+  - **Needs data the account doesn't have (an empty list, nothing to act on)?** Create it
+    in \`before\` the way a user would, \`{{unique}}\`-named (a \`wait_until\` when the app
+    builds it in the background), and remove it in \`after\`.
   - **Deleting something?** Create your own victim first (in \`before\` or the opening
     steps, \`{{unique}}\`-named), then delete it and prove \`gone\`; when the deleted thing
     must persist, re-create it in \`after\` as it was. Never aim a delete at standing data:
     run 2 has nothing to delete, and it eats the account's accumulated coverage.
-  - **Changed a value (rename, toggle)?** Restore it in \`after\`: set it back to what it
-    was. Capture the original BEFORE you change it with \`capture_text\` (or \`capture_value\`
-    for a form input), banking it under \`capture_as\`, then \`fill {{handle}}\` in \`after\`
-    to put it back.
+  - **Changed a value already there (a setting, option, toggle, rename)?** Restore it in
+    \`after\`. \`capture_value\` the field BEFORE you change it (banking it under
+    \`capture_as\`), change it to a value different from the one you found, then set it
+    back from that handle: \`select\` with option \`{{handle}}\` for a dropdown,
+    \`fill {{handle}}\` for a text field, the opposite \`check\` / \`uncheck\` for a
+    toggle. Prove each one saved, not just shown: after the change, \`goto\` the page
+    again, reopen it and end with \`have_value\` on the field; in \`after\`, the same
+    after the restore, checking \`{{handle}}\`. A write that skips any of this is refused.
 - **You label each test \`read\` or \`write\`; Beryl takes your word for it.** Set its
   \`access\` (default \`read\`). Beryl does NOT infer it from your selectors, so YOU
   decide, by one test: **would the app be different after this test runs?**
@@ -212,9 +234,9 @@ The trade is drift — run 200 has 200 of everything run 1 created. So:
     menu or dialog and reading it, or clicking a destructive button and then CANCELLING.
     Nothing is committed. Opening a confirm dialog and cancelling is a \`read\`; a submit
     that stays disabled is a \`read\`.
-  A flow that both changes and reads is a \`write\`. Only the \`write\` label is checked
-  (its closing teardown proof and its \`{{unique}}\` names, and a \`write\` whose teardown
-  removes nothing fails the run); \`read\` is taken at your word, so a real write you mislabel \`read\` silently
+  A flow that both changes and reads is a \`write\`. A \`write\` is checked for its closing
+  teardown proof and its \`{{unique}}\` names (and one whose teardown removes nothing fails
+  the run); \`read\` is taken at your word, so a real write you mislabel \`read\` silently
   drifts the account. Label deliberately, and flip a banked test with \`tests_set_access\`.
 
 ### If there is no account yet
@@ -246,7 +268,7 @@ An empty \`accounts_list\` means nothing is set up. In order of preference:
 
 Every saved login is a test account: \`{{login_email}}\` and \`{{login_password}}\` resolve
 only from the environment's account, and a login password is never set with
-\`config secrets set\`. The webapp's Test accounts tab edits the same accounts.
+\`config secrets set\`. The webapp's Test accounts page edits the same accounts.
 
 ### Session mode: sign in once per run, not once per test
 
@@ -273,6 +295,13 @@ An expired session is never your problem: every run proves the stored session an
 miss, signs in again from the login plan. A "reconnect" message only appears when there
 is no stored login plan to refresh from.
 
+A sign-in that breaks at run setup alerts the workspace once (run Slack channel and
+email) with the code, the blocked tests, and the fix, and again only as a reminder or
+when it is restored. Until then that account's tests error at setup with the same
+\`SESSION_*\` code instead of running: session-mode tests always, inline ones too when
+the cause is the account itself (rejected password, locked, captcha, a code that never
+arrives). Fix the account, then \`accounts_check\`.
+
 When \`accounts_check\` fails, its description explains which half broke and each
 \`SESSION_*\` reason. The one that changes your plans: an account marked
 unsupported (its session cannot survive a fresh browser) is not your bug, but it IS
@@ -281,11 +310,46 @@ sign-in steps.
 
 ### Two identities in one test
 
-Invite-a-teammate-and-accept-as-them needs two identities mid-flow, so it is not bankable
-as one test. Bank the half the app shows to account A ("the invitation is listed as
-pending", "the share link is issued"): a real, strong outcome. While fixing a plan you can
-drive the full handshake live: a second account (\`accounts_create\`, labelled), or a
-second mailbox (\`mailbox_create\`, read with \`mailbox_read\`).
+A \`sign_in_as\` step continues the test as another identity, so a multi-user flow is
+one test: an admin invites a teammate who accepts, user A makes something private and
+user B is refused, an admin changes a role and the user's access changes.
+
+- \`"account": "<label>"\` opens that test account in its own browser, already signed
+  in on the run's session for it. The account needs a stored sign-in
+  (\`accounts_set_login\`) or a captured session, the same as a session-mode test's;
+  the run signs it in once at setup, and if that breaks the test errors at setup with
+  the \`SESSION_*\` code.
+- \`"account": "inbox_address_2"\` (a fresh-address handle the plan types somewhere)
+  opens a signed-out browser for that throwaway user, so the next steps accept the
+  invitation or sign up as it.
+- Switching back to an identity resumes its page where it was left. The test's own
+  \`auth_label\` names where it started; a test that starts signed out or as the
+  environment's default account cannot switch back to its start by name.
+- \`after\` starts as the test's own account; add a \`sign_in_as\` there when the
+  cleanup needs another identity.
+- Web plans only. The authoring replay (\`jobs_create\`, \`tests_recompile\`) does not
+  sign switched-to accounts in: add the step with \`tests_set_plan\` and prove it with
+  \`runs_trigger\`.
+
+\`\`\`json
+{
+  "requires_auth": true, "auth_mode": "session", "auth_label": "admin",
+  "steps": [
+    {"action": "goto", "url": "/settings/team"},
+    {"action": "fill", "selector": "#invite-email", "value": "{{inbox_address}}"},
+    {"action": "click", "selector": "text=Send invite"},
+    {"action": "sign_in_as", "account": "inbox_address"},
+    {"action": "await_email", "extract": "link", "capture_as": "invite"},
+    {"action": "goto", "url": "{{invite}}"},
+    {"action": "click", "selector": "text=Accept invitation"},
+    {"action": "expect", "expect_kind": "visible", "selector": "text=Welcome to the team"}
+  ],
+  "after": [
+    {"action": "goto", "url": "/settings/team"},
+    {"action": "click", "selector": "text=Remove", "optional": true}
+  ]
+}
+\`\`\`
 
 SSO-only sites are not a dead end: with a dedicated Google test account they follow §1
 item 2 like any password account. The captured session is the FALLBACK — no test account
@@ -382,10 +446,13 @@ teardown rules are unchanged; \`device\` only sets the frame it runs in.
 
 ### App tests (Android and iOS)
 \`device: "android"\` and \`device: "ios"\` are not browsers: the plan drives the environment's
-app (its \`app_ids.android\` from the newest APK, or \`app_ids.ios\` from the newest simulator
-build, uploaded to Files) on an emulator or simulator in Beryl's cloud. App tests are written
-and verified by a test-creation job (\`jobs_create\`), never run locally. When you edit one,
-its rules differ from a web plan's:
+app (its \`app_ids.android\` from the newest APK, uploaded as an .apk or an .aab Beryl converts
+and signs, or \`app_ids.ios\` from the newest simulator build, uploaded to Files; the first
+ready build fills the environment's app id) on an emulator or simulator in Beryl's cloud. A job authors them only
+once the surface is on: \`projects_surfaces\` with \`add: ["android", "ios"]\` (CLI
+\`beryl projects surfaces --add android --add ios\`), which keeps the web surfaces on. App tests
+are written and verified by a test-creation job (\`jobs_create\`), never run locally. When you
+edit one, its rules differ from a web plan's:
 
 - The first step is \`launch\` (open the app), not \`goto\`. A later \`launch\` relaunches
   with the app's data kept, which is how a plan proves something persisted.
@@ -520,8 +587,15 @@ this test alone.
 | creates an account, or signs in as one it created (a returning-user test: \`before\` signs up the alias and logs out, the steps sign in as it) | an \`after\` section that deletes it through the app, its steps marked \`optional\`; a plan that reads its signup mail is refused at save time without one |
 | only makes mail arrive, read or not, no account created | nothing to clean up; mail is kept for 48 hours |
 
-Every alias minted is listed by \`mailbox_identities\` with how its teardown
-ended; the run detail shows the same outcome on each result.
+Every alias minted is a throwaway test account owned by the execution that minted it:
+\`accounts_list\` groups them as throwaway (and \`mailbox_identities\` filters them by run
+or test) with how each teardown ended, for 30 days; the run detail shows the same
+outcome on each result.
+
+A test that needs several fresh users (an owner who invites a teammate) cites
+\`{{inbox_address_2}}\` up to \`{{inbox_address_9}}\` for the others, each its own alias.
+An \`await_email\` reading one of those sets \`recipient\` to the handle name
+(\`"recipient": "inbox_address_2"\`); without it, it reads \`{{inbox_address}}\`'s mail.
 
 The wiring is a three-part chain:
 
@@ -560,7 +634,73 @@ Two caveats:
 - §2's outcome discipline still applies: the green signal is the post-verification
   state (the welcome screen, the dashboard), not "an email arrived".
 
-## 6. Why this shape: durable and healable
+### Fresh users without typing the signup
+
+When the test is about what a new user does, not about signup itself, a
+\`create_account\` step signs one up for you: it replays the environment's default test
+account's signup plan (the one \`accounts_signup\` stored) at that point, typing a fresh
+alias and a password minted for this run, so every run gets a different user.
+
+- \`"value": "{{inbox_address_2}}"\` names the alias it signs up (default
+  \`{{inbox_address}}\`). No earlier step may type that alias; later steps may cite it
+  (an \`await_email\` with \`recipient\`, a \`sign_in_as\` before the step to sign up in
+  its own browser).
+- The browser continues signed in as the new user. To sign in as it again later, type
+  the same alias and \`{{created_password}}\`, the password it signed up with. Like any
+  signup, the test needs an \`after\` that deletes it, and \`create_account\` is not
+  allowed in \`after\`.
+- The default account must have a stored signup plan, or the save is refused and a run
+  errors at setup with \`CREATE_ACCOUNT_NO_SIGNUP\`. A signup that breaks fails the
+  \`create_account\` step, and the run report groups those failures as one signup cause.
+- Web plans only, run in the cloud (\`tests script\` and \`runs local\` refuse them).
+  Auto-heal skips these tests.
+
+\`\`\`json
+{
+  "steps": [
+    {"action": "goto", "url": "/"},
+    {"action": "create_account"},
+    {"action": "goto", "url": "/projects"},
+    {"action": "expect", "expect_kind": "visible", "selector": "text=Create your first project"}
+  ],
+  "after": [
+    {"action": "goto", "url": "/settings/account"},
+    {"action": "click", "selector": "text=Delete account", "optional": true}
+  ]
+}
+\`\`\`
+
+## 6. Flows that wait for an asynchronous process (\`wait_until\`)
+
+Some flows kick off work that finishes minutes later, not in the next frame: an export,
+an import, AI generation, a job you start and watch. An ordinary step times out long
+before the result lands. \`wait_until\` holds the browser and polls a selector until it
+appears, past the per-step and per-test limits.
+
+- Do the trigger step (click Export, start the job), then a \`wait_until\` on the region
+  that shows the FINISHED state, never the spinner.
+- \`deadline_s\` is how long to keep polling (bounded); \`every_s\` is the gap between
+  checks; \`"reload": true\` reloads between polls when a status only updates on
+  navigation; \`fail_on\` lists selectors whose appearance means the process failed, so
+  it fails fast instead of waiting out the deadline. The deadline passing is itself a
+  failure.
+- Assert the real outcome AFTER it: \`wait_until\` only reaches the finished state, the
+  \`expect\` is still the test. The deadline is added to the test's budget, so a plan
+  without the step runs exactly as before. A deadline that passes is never retried or
+  auto-healed; raise \`deadline_s\` or check why the process stalled.
+
+\`\`\`json
+{
+  "steps": [
+    {"action": "goto", "url": "/exports"},
+    {"action": "click", "selector": "role=button[name=Export]"},
+    {"action": "wait_until", "selector": "text=Download ready", "deadline_s": 600, "every_s": 20, "reload": true, "fail_on": ["text=Export failed"]},
+    {"action": "expect", "expect_kind": "visible", "selector": "a.download"}
+  ]
+}
+\`\`\`
+
+## 7. Why this shape: durable and healable
 
 Beryl's cloud runs your test on a schedule. When markup drifts and a selector stops
 matching, a heal-vs-fail agent decides whether to **heal** (silently re-derive the
@@ -580,7 +720,11 @@ So a test is *healable* exactly when it has **a strong intent + a real outcome
 assertion**. With a vague intent and a chrome-only assertion Beryl can't tell
 regression from cosmetic drift — it either heals over real breakage or fails on noise.
 
-## 7. Third party integration tests
+Healing is **off by default** for each project: a failed test fails right away. Turn
+it on with \`projects_heal\` (\`beryl projects heal on\`), optionally with
+\`--minutes\` (per heal attempt) and \`--max-per-run\` (heals one run may start).
+
+## 8. Third party integration tests
 
 An app's own integrations (its "Connect Slack" button, the message it then posts) are
 testable against Beryl's account on that provider. Call

package/dist/code-ref.js

@@ -0,0 +1,81 @@
+import fs from "node:fs";
+const SHA = /^[0-9a-f]{4,64}$/i;
+const SHORT_SHA = 7;
+const clean = (v) => typeof v === "string" ? v.trim() || undefined : undefined;
+export const isCommitSha = (v) => SHA.test(v);
+function prNumber(v) {
+    const n = typeof v === "string" ? Number(v.trim()) : v;
+    return typeof n === "number" && Number.isInteger(n) && n > 0 ? n : undefined;
+}
+// On a pull_request event GITHUB_SHA is GitHub's throwaway merge commit, not the
+// commit the customer pushed; the PR head lives only in the event payload.
+function githubEvent(env, readFile) {
+    const file = env.GITHUB_EVENT_PATH;
+    if (!file || !env.GITHUB_EVENT_NAME?.startsWith("pull_request"))
+        return {};
+    try {
+        const event = JSON.parse(readFile(file));
+        return event && typeof event === "object" ? event : {};
+    }
+    catch {
+        // Best-effort: an unreadable payload falls back to GITHUB_SHA.
+        return {};
+    }
+}
+function fromGithub(env, readFile) {
+    const pr = githubEvent(env, readFile).pull_request;
+    const sha = clean(pr?.head?.sha) ?? clean(env.GITHUB_SHA);
+    const server = clean(env.GITHUB_SERVER_URL);
+    const repo = clean(env.GITHUB_REPOSITORY);
+    return {
+        commit_sha: sha,
+        branch: clean(env.GITHUB_HEAD_REF) ??
+            (env.GITHUB_REF_TYPE === "tag" ? undefined : clean(env.GITHUB_REF_NAME)),
+        commit_url: sha && server && repo ? `${server}/${repo}/commit/${sha}` : undefined,
+        pr_number: prNumber(pr?.number) ?? prNumber(/^refs\/pull\/(\d+)\//.exec(env.GITHUB_REF ?? "")?.[1]),
+    };
+}
+// In a merged-results MR pipeline CI_COMMIT_SHA is GitLab's merge commit; the source
+// branch sha is the commit the customer pushed.
+function fromGitlab(env) {
+    const sha = clean(env.CI_MERGE_REQUEST_SOURCE_BRANCH_SHA) ?? clean(env.CI_COMMIT_SHA);
+    const project = clean(env.CI_PROJECT_URL);
+    return {
+        commit_sha: sha,
+        branch: clean(env.CI_MERGE_REQUEST_SOURCE_BRANCH_NAME) ??
+            clean(env.CI_COMMIT_BRANCH) ??
+            (env.CI_COMMIT_TAG ? undefined : clean(env.CI_COMMIT_REF_NAME)),
+        commit_url: sha && project ? `${project}/-/commit/${sha}` : undefined,
+        pr_number: prNumber(env.CI_MERGE_REQUEST_IID),
+    };
+}
+export function detectCodeRef(env = process.env, readFile = (p) => fs.readFileSync(p, "utf8")) {
+    if (env.GITHUB_ACTIONS === "true")
+        return fromGithub(env, readFile);
+    if (env.GITLAB_CI === "true")
+        return fromGitlab(env);
+    return {};
+}
+// Precedence: flags, then BERYL_COMMIT_SHA / BERYL_BRANCH, then the CI provider. A
+// detected commit_url or PR number only rides along with the sha it was built from.
+export function resolveCodeRef(flags, env = process.env, readFile) {
+    const detected = detectCodeRef(env, readFile);
+    const explicitSha = clean(flags.commit) ?? clean(env.BERYL_COMMIT_SHA);
+    const sha = explicitSha ?? detected.commit_sha;
+    const sameCommit = !explicitSha || explicitSha.toLowerCase() === detected.commit_sha?.toLowerCase();
+    const ref = {
+        commit_sha: sha && isCommitSha(sha) ? sha.toLowerCase() : undefined,
+        branch: clean((clean(flags.branch) ?? clean(env.BERYL_BRANCH) ?? detected.branch)?.replace(/^refs\/heads\//, "")),
+        commit_url: sameCommit ? detected.commit_url : undefined,
+        pr_number: sameCommit ? detected.pr_number : undefined,
+    };
+    if (!ref.commit_sha)
+        ref.commit_url = undefined;
+    return Object.fromEntries(Object.entries(ref).filter(([, v]) => v !== undefined));
+}
+export function codeRefLabel(ref) {
+    const sha = ref.commit_sha?.slice(0, SHORT_SHA);
+    if (ref.branch && sha)
+        return `${ref.branch} @ ${sha}`;
+    return ref.branch ?? sha ?? null;
+}