@beryl-so/cli 0.78.0 → 0.92.1

package/dist/commands/jobs.js

@@ -1,10 +1,12 @@
 import fs from "node:fs";
 import path from "node:path";
+import { SESSION_CAPTURE_EXTENSION_URL } from "../config.js";
 import { UsageError } from "../errors.js";
 import { arg, flagBool, flagStr, projectPath } from "./util.js";
 const jobsPath = (ws, p) => `${projectPath(ws, p)}/test-creation-jobs`;
-const LLM_NOTICE = "The document is sent to the LLM that drives the agent, so leave out anything you " +
-    "would not share with it.";
+const DOCUMENT_SUFFIX = /\.(md|markdown|txt|text|pdf|docx)$/i;
+const LLM_NOTICE = "The prompt and document are sent to the LLM that drives the agent, so leave out " +
+    "anything you would not share with it.";
 function readDocument(file) {
     try {
         return new Uint8Array(fs.readFileSync(file));
@@ -16,10 +18,25 @@ function readDocument(file) {
         throw new UsageError(`cannot read ${file} (${code ?? err.message})`);
     }
 }
+function decodeDocument(encoded) {
+    const compact = encoded.replace(/\s+/g, "");
+    // Buffer.from decodes a truncated string to wrong bytes instead of failing.
+    if (!/^[A-Za-z0-9+/_-]+={0,2}$/.test(compact) || compact.replace(/=+$/, "").length % 4 === 1) {
+        throw new UsageError("--content-base64 is not valid base64");
+    }
+    return new Uint8Array(Buffer.from(compact, "base64"));
+}
 export function jobHuman(job) {
     const lines = [`Job ${job.id}: ${job.status}`];
+    if (job.retry && job.cloned_from_id)
+        lines.push(`Retry of job ${job.cloned_from_id}`);
     if (job.error)
-        lines.push(`Error: ${job.error}`);
+        lines.push(`${job.status === "partial" ? "Missing" : "Error"}: ${job.error}`);
+    if (job.needs)
+        lines.push(`Needs: ${job.needs.reason}`);
+    if (job.needs?.kind === "session_capture") {
+        lines.push(`  Capture a signed-in session with the Beryl Chrome extension (${SESSION_CAPTURE_EXTENSION_URL}); the job resumes by itself.`);
+    }
     for (const t of job.tests)
         lines.push(`  ${t.title ?? t.id} [${t.surface}] ${t.id}`);
     if (!job.tests.length)
@@ -27,50 +44,125 @@ export function jobHuman(job) {
     const skipped = job.skipped_flows ?? [];
     if (skipped.length)
         lines.push("Skipped scenarios:");
-    for (const s of skipped)
-        lines.push(`  ${s.handle}: ${s.reason}`);
+    for (const s of skipped) {
+        lines.push(`  ${s.handle}: ${s.reason}${s.detail ? ` (${s.detail})` : ""}`);
+        if (s.advice)
+            lines.push(`    What to do: ${s.advice}`);
+    }
     for (const step of job.surface_steps ?? []) {
+        if (step.gaps?.length)
+            lines.push(`Not authored [${step.surface}]: ${step.gaps.join(", ")}`);
         for (const w of step.warnings ?? [])
             lines.push(`Warning [${step.surface}]: ${w}`);
     }
+    if (job.status === "partial" || job.status === "failed") {
+        lines.push(`Retry what is missing: beryl jobs retry ${job.id}`);
+    }
     return lines.join("\n");
 }
 export const jobCommands = [
     {
         name: "jobs create",
-        groupSummary: "Test-creation jobs: the cloud agent reads a document and authors tests from it.",
-        summary: "Create tests from a document (PRD, release notes) on Beryl's cloud",
-        description: "Uploads a document (Markdown, plain text, PDF or DOCX, or --text) and queues a " +
-            "job: the agent explores the environment, drafts one flow per scenario the document " +
-            "describes, and authors one test per enabled surface of the project. New tests get " +
-            "no groups. A job runs once; to run it again, use `jobs clone`. " +
+        groupSummary: "Test-creation jobs: the cloud agent follows a prompt, reads any document it comes " +
+            "with, and authors tests.",
+        summary: "Create tests from a prompt, with an optional document, on Beryl's cloud",
+        description: "Queues a job from a prompt (what to test; a line is enough) and an optional " +
+            "document (Markdown, plain text, PDF or DOCX: --file, --text, or --content-base64 " +
+            "with --filename): the agent explores the environment, drafts one flow per " +
+            "scenario the prompt asks for, reading the document when there is one, and authors " +
+            "one test per enabled surface of the project. The agent signs " +
+            "in as the environment's default test account, or the one --account names, and the " +
+            "tests it saves sign in as that account too. New tests get " +
+            "no groups. A job runs once and ends done, partial (some tests saved, the rest " +
+            "listed with why) or failed; `jobs retry` authors what a partial or failed job " +
+            "left out, `jobs clone` runs the whole document again. With --ci (or a " +
+            "project CI token as BERYL_TOKEN, which always creates CI jobs) the job never " +
+            "pauses for input: a scenario behind a login it cannot pass is skipped with the " +
+            "reason. " +
             LLM_NOTICE,
         scope: "project",
-        args: [{ name: "file", description: "Path to the document" }],
+        args: [
+            {
+                name: "prompt",
+                description: "What to test: the instruction the agent follows; a line is enough",
+                required: true,
+            },
+        ],
         flags: [
+            {
+                name: "file",
+                type: "string",
+                description: "Path to a document (PRD, release notes) the agent reads with the prompt",
+            },
             { name: "text", type: "string", description: "The document as text, instead of a file" },
+            {
+                name: "content-base64",
+                type: "string",
+                description: "A binary document (PDF, DOCX) base64-encoded, instead of a file; needs --filename",
+            },
+            {
+                name: "filename",
+                type: "string",
+                description: "With --content-base64: the document's name; its extension sets the type",
+            },
             {
                 name: "env",
                 type: "string",
                 description: "Environment id to explore (defaults to the project's default)",
             },
+            {
+                name: "account",
+                type: "string",
+                description: "Label of the test account to sign in as (see `accounts list`); defaults to the environment's default account",
+            },
+            {
+                name: "ci",
+                type: "boolean",
+                description: "Non-interactive job for CI: never waits for a captured session, skips what it blocks",
+            },
+        ],
+        examples: [
+            'beryl jobs create "Cover the checkout flow: add an item, pay by card, see the confirmation" --env <env-id>',
+            'beryl jobs create "Draft a test for each scenario in the release notes" --file ./release-notes.md',
+            'beryl jobs create "Cover the admin console" --file ./admin-console.md --account admin',
+            'BERYL_TOKEN=beryl_ci_... beryl jobs create "Cover the brief" --file ./brief.md --ci --workspace <ws-id> --project <project-id>',
         ],
-        examples: ["beryl jobs create ./release-notes.md --env <env-id>"],
         async run(ctx, input) {
-            const { workspaceId, projectId } = await ctx.requireProject(input);
-            const file = input.args.file;
+            const prompt = arg(input, "prompt");
+            const file = flagStr(input, "file");
             const text = flagStr(input, "text");
-            if (Boolean(file) === Boolean(text)) {
-                throw new UsageError("pass a document file or --text, not both");
+            const encoded = flagStr(input, "content-base64");
+            const filename = flagStr(input, "filename");
+            if ([file, text, encoded].filter(Boolean).length > 1) {
+                throw new UsageError("pass at most one of --file, --text or --content-base64");
+            }
+            // The pre-0.88 form put the document first; refuse it rather than test "./brief.md".
+            if (!file && !text && !encoded && DOCUMENT_SUFFIX.test(prompt)) {
+                throw new UsageError("the first argument is the prompt; pass the document with --file");
+            }
+            if (Boolean(encoded) !== Boolean(filename)) {
+                throw new UsageError("--content-base64 and --filename go together");
             }
             const form = new FormData();
-            if (file)
+            form.set("prompt", prompt);
+            if (file) {
                 form.set("file", new Blob([readDocument(file)]), path.basename(file));
-            else
+            }
+            else if (encoded) {
+                form.set("file", new Blob([decodeDocument(encoded)]), path.basename(filename));
+            }
+            else if (text) {
                 form.set("text", text);
+            }
+            const { workspaceId, projectId } = await ctx.requireProject(input);
             const envId = flagStr(input, "env");
             if (envId)
                 form.set("environment_id", envId);
+            const account = flagStr(input, "account");
+            if (account)
+                form.set("account", account);
+            if (flagBool(input, "ci"))
+                form.set("interactive", "false");
             const job = (await ctx.client.request("POST", jobsPath(workspaceId, projectId), {
                 form,
             }));
@@ -102,7 +194,7 @@ export const jobCommands = [
     },
     {
         name: "jobs clone",
-        summary: "Run a job again: queue a new job with the same document and environment",
+        summary: "Run a job again: queue a new job with the same prompt, document, environment and account",
         description: LLM_NOTICE,
         scope: "project",
         args: [{ name: "job-id", description: "Job id to clone", required: true }],
@@ -112,6 +204,46 @@ export const jobCommands = [
             return { data: job, human: `Job ${job.id} queued.` };
         },
     },
+    {
+        name: "jobs retry",
+        summary: "Author only what a partial or failed job left out, optionally with an edited prompt or document",
+        description: "Queues a new job that authors each scenario the job drafted but has no test on " +
+            "some surface, and each scenario it skipped, on the surfaces that miss them. The " +
+            "new tests join the same flows. --prompt replaces the job's instruction and " +
+            "--file or --text its document; anything not passed is reused from the job. " +
+            LLM_NOTICE,
+        scope: "project",
+        args: [{ name: "job-id", description: "Job id to retry", required: true }],
+        flags: [
+            { name: "prompt", type: "string", description: "An edited instruction for the agent" },
+            { name: "file", type: "string", description: "Path to an edited document (Markdown or plain text)" },
+            { name: "text", type: "string", description: "The edited document as text, instead of --file" },
+        ],
+        examples: [
+            "beryl jobs retry <job-id>",
+            'beryl jobs retry <job-id> --prompt "Refund lives under Orders; test it there"',
+            "beryl jobs retry <job-id> --file ./brief-v2.md",
+        ],
+        async run(ctx, input) {
+            const prompt = flagStr(input, "prompt");
+            const file = flagStr(input, "file");
+            const text = flagStr(input, "text");
+            if (file && text)
+                throw new UsageError("pass --file or --text, not both");
+            const document = file ? Buffer.from(readDocument(file)).toString("utf-8") : text;
+            const body = {};
+            if (prompt !== undefined)
+                body.prompt = prompt;
+            if (document !== undefined)
+                body.document_text = document;
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const job = (await ctx.client.post(`${jobsPath(workspaceId, projectId)}/${arg(input, "job-id")}/retry`, body));
+            return {
+                data: job,
+                human: `Job ${job.id} queued. Check it with \`beryl jobs get ${job.id}\`.`,
+            };
+        },
+    },
     {
         name: "jobs delete",
         summary: "Delete a job; the flows and tests it created stay",

package/dist/commands/projects.js

@@ -1,7 +1,7 @@
 import { detectAuthGating } from "../detect.js";
 import { UsageError } from "../errors.js";
 import { dim, green, table, timeAgo } from "../output.js";
-import { arg, argList, flagBool, flagNum, flagStr, projectPath } from "./util.js";
+import { arg, flagBool, flagNum, flagStr, flagStrings, projectPath } from "./util.js";
 import { pollCurrentExploration, watchExploration } from "./watch.js";
 // The API treats the auth choice as the visitor's answer and never infers it — a null
 // choice leaves the project waiting on a login capture that never comes — so resolve it
@@ -117,7 +117,7 @@ export const projectCommands = [
                     data: created,
                     human: `${green("Project created")}: ${created.project_id} ${dim("(empty)")}\n` +
                         `Add a site with \`beryl envs update <env-id>\`, then create tests with ` +
-                        `\`beryl jobs create <document>\`.`,
+                        `\`beryl jobs create "<what to test>"\`.`,
                 };
             }
             const auth = flagStr(input, "auth") ?? (await resolveAuthChoice(ctx, ws, url));
@@ -129,7 +129,8 @@ export const projectCommands = [
             return {
                 data: created,
                 human: `${green("Project created")}: ${created.project_id}\n` +
-                    `Create tests from a document describing the flows: \`beryl jobs create <file>\`.`,
+                    `Create tests from a prompt (and a document, if you have one): ` +
+                    `\`beryl jobs create "<what to test>" --file <doc>\`.`,
             };
         },
     },
@@ -194,36 +195,130 @@ export const projectCommands = [
             return { data: await ctx.client.patch(projectPath(workspaceId, projectId), body) };
         },
     },
+    {
+        name: "projects heal",
+        summary: "Turn self-heal on or off for a project and limit its time and runs",
+        description: "Self-heal is off by default: a failed test fails right away. With it on, a run holds " +
+            "a failed test that has passed before while a heal agent tries to repair its plan " +
+            "against the app, and the test passes if the repair is proven by a replay. --minutes " +
+            "caps the heal agent's time on one failed test (from 1 up to the platform limit, 5 " +
+            "unless the server is configured otherwise; the proving replay comes on top; 0 goes " +
+            "back to that limit) and --max-per-run caps " +
+            "how many failed tests one run may heal (0 removes the cap); past it the rest fail " +
+            "without a heal. A test turned off with `tests heal <id> off` never heals. " +
+            "`projects get` shows the current values.",
+        scope: "project",
+        args: [{ name: "state", description: "on | off; omit to only change the limits" }],
+        flags: [
+            { name: "minutes", type: "number", description: "Minutes the heal agent may spend on one failed test (0 = the platform limit, 5 by default)" },
+            { name: "max-per-run", type: "number", description: "Failed tests one run may heal (0 = no cap)" },
+        ],
+        examples: [
+            "beryl projects heal on",
+            "beryl projects heal on --minutes 2 --max-per-run 5",
+            "beryl projects heal --max-per-run 0",
+            "beryl projects heal off",
+        ],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const body = {};
+            const state = input.args.state;
+            if (typeof state === "string" && state) {
+                const lower = state.toLowerCase();
+                if (lower !== "on" && lower !== "off") {
+                    throw new UsageError(`Expected "on" or "off", got "${state}"`);
+                }
+                body.self_heal = lower === "on";
+            }
+            const minutes = flagNum(input, "minutes");
+            const maxPerRun = flagNum(input, "max-per-run");
+            if (minutes !== undefined)
+                body.heal_max_minutes = minutes === 0 ? null : minutes;
+            if (maxPerRun !== undefined)
+                body.heal_max_per_run = maxPerRun === 0 ? null : maxPerRun;
+            if (Object.keys(body).length === 0) {
+                throw new UsageError("Pass on|off or at least one of --minutes, --max-per-run");
+            }
+            const data = (await ctx.client.patch(projectPath(workspaceId, projectId), body));
+            const minutesText = data.heal_max_minutes === null ? "default" : `${data.heal_max_minutes} min`;
+            const capText = data.heal_max_per_run === null ? "no cap" : `${data.heal_max_per_run}`;
+            return {
+                data,
+                human: `Self-heal: ${data.self_heal ? "on" : "off"} ` +
+                    `(per heal: ${minutesText}, heals per run: ${capText})`,
+            };
+        },
+    },
     {
         name: "projects surfaces",
-        summary: "Set which surfaces are enabled for this project",
-        description: "Replaces the project's enabled surfaces with the ones listed: web-desktop, " +
-            "web-tablet, web-mobile, android, ios. A new project has web-desktop only. At least " +
-            "one is required; `projects get` shows the current set. Turning a surface off " +
-            "removes no tests: delete a surface's tests to stop running them. android and ios " +
-            "test the app named by each environment's app id for that surface (`envs update " +
-            "--app-id android=<package> --app-id ios=<bundle id>`) from its newest uploaded build " +
-            "(`config files upload app.apk`, `config files upload App.zip --kind ios_build`), on " +
-            "Beryl's Android and iOS workers.",
+        summary: "Turn project surfaces on or off",
+        description: "Surfaces are web-desktop, web-tablet, web-mobile, android, ios; a new project has " +
+            "web-desktop only. `--add` turns surfaces on and `--remove` turns them off, keeping the " +
+            "rest. Listing surfaces sets the exact set instead, and is refused when it would turn " +
+            "off a surface that is on unless you pass `--replace`. At least one surface stays on. " +
+            "Prints the set before and after. Turning a surface off removes no tests: delete a " +
+            "surface's tests to stop running them. android and ios test the app named by each " +
+            "environment's app id for that surface (`envs update --app-id android=<package> " +
+            "--app-id ios=<bundle id>`) from its newest uploaded build (`config files upload " +
+            "app.apk`, `config files upload App.zip --kind ios_build`), on Beryl's Android and iOS " +
+            "workers.",
         scope: "project",
         args: [
             {
                 name: "surfaces",
-                description: "web-desktop | web-tablet | web-mobile | android | ios, one or more",
-                required: true,
+                description: "The exact set to enable: web-desktop | web-tablet | web-mobile | android | ios",
                 variadic: true,
             },
         ],
+        flags: [
+            { name: "add", type: "strings", description: "Turn this surface on (repeatable)" },
+            { name: "remove", type: "strings", description: "Turn this surface off (repeatable)" },
+            {
+                name: "replace",
+                type: "boolean",
+                description: "Let a listed exact set turn off surfaces that are on now",
+            },
+        ],
         examples: [
-            "beryl projects surfaces web-desktop web-mobile",
-            "beryl projects surfaces web-desktop android ios",
+            "beryl projects surfaces --add android --add ios",
+            "beryl projects surfaces --remove web-tablet",
+            "beryl projects surfaces web-desktop web-mobile --replace",
         ],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
-            const data = (await ctx.client.patch(projectPath(workspaceId, projectId), {
-                enabled_surfaces: argList(input, "surfaces"),
-            }));
-            return { data, human: `Enabled surfaces: ${data.enabled_surfaces.join(", ")}` };
+            const listed = input.args.surfaces ?? [];
+            const add = flagStrings(input, "add");
+            const remove = flagStrings(input, "remove");
+            if (listed.length > 0 && (add || remove)) {
+                throw new UsageError("List the exact set, or use --add/--remove, not both");
+            }
+            if (listed.length === 0 && !add && !remove) {
+                throw new UsageError("Pass --add <surface>, --remove <surface>, or the exact set of surfaces");
+            }
+            const path = projectPath(workspaceId, projectId);
+            const before = (await ctx.client.get(path)).enabled_surfaces;
+            let body;
+            if (listed.length > 0) {
+                const dropped = before.filter((s) => !listed.includes(s));
+                if (dropped.length > 0 && !flagBool(input, "replace")) {
+                    throw new UsageError(`This would turn off ${dropped.join(", ")} (on now: ${before.join(", ")}). ` +
+                        "Use --add to turn surfaces on and keep the rest, or pass --replace to set exactly " +
+                        `${listed.join(", ")}.`);
+                }
+                body = { enabled_surfaces: listed };
+            }
+            else {
+                body = {};
+                if (add)
+                    body.add_surfaces = add;
+                if (remove)
+                    body.remove_surfaces = remove;
+            }
+            const data = (await ctx.client.patch(path, body));
+            return {
+                data: { ...data, previous_enabled_surfaces: before },
+                human: `Enabled surfaces: ${before.join(", ")} -> ${data.enabled_surfaces.join(", ")}`,
+            };
         },
     },
     {

package/dist/commands/runs.js

@@ -1,10 +1,18 @@
 import fs from "node:fs";
 import { downloadRunArtifacts, failureImages, isFailing, resultsOf, } from "../artifacts.js";
+import { codeRefLabel, isCommitSha, resolveCodeRef } from "../code-ref.js";
 import { UsageError } from "../errors.js";
 import { dim, yellow } from "../output.js";
 import { arg, flagBool, flagNum, flagStr, idsInGroup, projectPath } from "./util.js";
 import { watchRun } from "./watch.js";
 const MAX_FAILURE_SCREENSHOTS = 5;
+export function queuedNote(run) {
+    if (run.status !== "queued")
+        return null;
+    const behind = run.waiting_for_run_id ? ` behind run ${run.waiting_for_run_id}` : "";
+    return (`queued at position ${run.queue_position ?? "?"}${behind}; a project runs one run ` +
+        "at a time, so it starts when the runs ahead finish");
+}
 export function parseHeaders(raw) {
     if (!raw || raw.length === 0)
         return null;
@@ -26,7 +34,10 @@ export const runCommands = [
             "exits 0 only if every test passed, so wire it straight into CI. A run with a " +
             "heal-eligible failure completes only after Beryl has tried to heal it: a repaired " +
             "test is re-run inside the same run and counts as passed (reported as `healed`), so " +
-            "the final counts, the report and the completion email all reflect the repair.",
+            "the final counts, the report and the completion email all reflect the repair. " +
+            "A project runs one run at a time: a run triggered while another is in flight comes " +
+            "back `queued` with its `queue_position` and starts on its own, in trigger order, " +
+            "when the runs ahead of it finish (--watch waits through the queue).",
         scope: "project",
         flags: [
             { name: "test", type: "strings", description: "Run only these test ids (repeatable)" },
@@ -46,7 +57,13 @@ export const runCommands = [
                     "Reaches auth-walled preview deploys, e.g. --header x-vercel-protection-bypass=<token>",
             },
             { name: "watch", type: "boolean", description: "Follow progress and exit non-zero on failure" },
-            { name: "timeout", type: "number", description: "With --watch: max minutes to wait" },
+            {
+                name: "timeout",
+                type: "number",
+                description: "With --watch: max minutes to wait. A test that waits for an asynchronous " +
+                    "process (a wait_until step) can run for minutes, so set this generously for a " +
+                    "suite that has one.",
+            },
             {
                 name: "fail-fast",
                 type: "boolean",
@@ -58,6 +75,18 @@ export const runCommands = [
                 type: "number",
                 description: "Retry a failing test up to N times (0 disables); omit for the default",
             },
+            {
+                name: "commit",
+                type: "string",
+                description: "Commit sha of your app this run tests, shown on the run. Detected automatically " +
+                    "in GitHub Actions and GitLab CI (or from BERYL_COMMIT_SHA); this overrides it",
+            },
+            {
+                name: "branch",
+                type: "string",
+                description: "Branch of your app this run tests, shown on the run. Detected automatically " +
+                    "in GitHub Actions and GitLab CI (or from BERYL_BRANCH); this overrides it",
+            },
         ],
         examples: [
             "beryl runs trigger --watch",
@@ -66,6 +95,7 @@ export const runCommands = [
             "beryl runs trigger --test 4f… --test 9a…",
             "beryl runs trigger --group Smoke --group Checkout --watch",
             "beryl runs trigger --retries 0 --watch",
+            "beryl runs trigger --commit $(git rev-parse HEAD) --branch main --watch",
         ],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
@@ -88,13 +118,24 @@ export const runCommands = [
                 tests = [...union];
             }
             const extraHeaders = parseHeaders(input.flags.header);
+            const commitFlag = flagStr(input, "commit");
+            if (commitFlag !== undefined && !isCommitSha(commitFlag.trim()))
+                ctx.err(yellow(`--commit ${commitFlag} is not a commit sha; the run won't record it`));
+            const codeRef = resolveCodeRef({ commit: commitFlag, branch: flagStr(input, "branch") });
             const created = (await ctx.client.post(`${projectPath(workspaceId, projectId)}/runs`, {
                 test_case_ids: tests && tests.length > 0 ? tests : null,
                 environment_id: flagStr(input, "env") ?? null,
                 target_url_override: flagStr(input, "url-override") ?? null,
                 max_retries: flagNum(input, "retries") ?? null,
                 extra_headers: extraHeaders,
+                ...codeRef,
             }));
+            const label = codeRefLabel(codeRef);
+            if (label && !ctx.json)
+                ctx.err(dim(`testing ${label}`));
+            const note = queuedNote(created);
+            if (note && !ctx.json)
+                ctx.err(yellow(note));
             if (!flagBool(input, "watch"))
                 return { data: created };
             return await watchRun(ctx, workspaceId, projectId, created.id, flagNum(input, "timeout"), {
@@ -103,6 +144,20 @@ export const runCommands = [
             });
         },
     },
+    {
+        name: "runs queue",
+        summary: "Show the run in flight and the runs waiting behind it",
+        description: "A project runs one run at a time. Returns `active` (the pending or running run, " +
+            "or null) and `queued`, the waiting runs in the order they will start, each with " +
+            "its `queue_position`. Cancel a waiting run with `runs cancel`.",
+        scope: "project",
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            return {
+                data: await ctx.client.get(`${projectPath(workspaceId, projectId)}/runs/queue`),
+            };
+        },
+    },
     {
         name: "runs list",
         summary: "List recent runs",
@@ -259,7 +314,7 @@ export const runCommands = [
     },
     {
         name: "runs cancel",
-        summary: "Cancel an in-flight run",
+        summary: "Cancel an in-flight run, or take a queued one out of the queue",
         scope: "project",
         args: [{ name: "run-id", description: "Run id", required: true }],
         async run(ctx, input) {
@@ -273,6 +328,9 @@ export const runCommands = [
         name: "runs report",
         summary: "Show the generated report for a run",
         description: "Returns the run's stored generated report (404 until it has been generated). " +
+            "`causes` groups the failures: every test that failed inside the same signup " +
+            "steps (a fresh {{inbox_address}} user) is one `signup` cause, so a broken signup " +
+            "reads as one problem; each other failure is its own `test` cause. " +
             "`runs get` returns the raw run row with per-test results.",
         scope: "project",
         args: [{ name: "run-id", description: "Run id", required: true }],
@@ -285,11 +343,13 @@ export const runCommands = [
     },
     {
         name: "runs download",
-        summary: "Download a run's results, with its artifacts, to disk",
-        description: "With --dir, fetches the artifact bytes (screenshots, DOM snapshots, the Playwright " +
-            "trace zip, and the filmstrip frames of the failing tests) into <dir>/<test-result-id>/ " +
-            "alongside a run.json manifest. Artifact URLs are short-lived, so download rather than " +
-            "stash them. With --out (or neither), writes only the JSON manifest.",
+        summary: "Get a run's results with signed artifact URLs, or download them to disk",
+        description: "With neither --dir nor --out, writes nothing: returns the JSON manifest, whose " +
+            "screenshot, DOM snapshot, trace and frame URLs are short-lived signed links any " +
+            "HTTP client can fetch. With --dir, fetches the artifact bytes (screenshots, DOM " +
+            "snapshots, the Playwright trace zip, and the filmstrip frames of the failing tests) " +
+            "into <dir>/<test-result-id>/ alongside a run.json manifest. With --out, writes only " +
+            "the manifest. The URLs expire, so fetch rather than stash them.",
         scope: "project",
         args: [{ name: "run-id", description: "Run id", required: true }],
         flags: [