@beryl-so/cli 0.17.0 → 0.21.4

package/dist/commands/mcp.js

@@ -1,4 +1,29 @@
+import { cliVersion, fetchLatestVersion, isBehind } from "../version-check.js";
 export const mcpCommands = [
+    {
+        name: "version",
+        summary: "Show the running CLI version, API URL, and Node version",
+        description: "Answers \"which build am I actually talking to?\" — the one question a long-lived " +
+            "`beryl mcp` process can't otherwise answer, since it loads source at spawn and never " +
+            "hot-reloads. Needs no login, so it still works when a token is missing or broken. " +
+            "Also reports whether the running build is behind npm's `latest` (best-effort: " +
+            "`update_available` is null when the registry can't be reached, and the check is " +
+            "skipped entirely under BERYL_NO_UPDATE_CHECK).",
+        examples: ["beryl version", "beryl version --json"],
+        async run(ctx) {
+            const current = cliVersion();
+            const latest = process.env.BERYL_NO_UPDATE_CHECK ? null : await fetchLatestVersion();
+            return {
+                data: {
+                    cli_version: current,
+                    api_url: ctx.config.apiUrl,
+                    node_version: process.version,
+                    latest_version: latest,
+                    update_available: latest === null ? null : isBehind(current, latest),
+                },
+            };
+        },
+    },
     {
         name: "mcp",
         summary: "Run the Beryl MCP server (stdio) — every CLI command as an agent tool",

package/dist/commands/projects.js

@@ -93,11 +93,6 @@ export const projectCommands = [
                 description: "Whether the site needs a login (gated) or not (public). Default: detected from the " +
                     "site — only asked when detection is genuinely unsure",
             },
-            {
-                name: "allow-mutations",
-                type: "boolean",
-                description: "Let the agent perform state-changing actions while exploring",
-            },
             { name: "force-new-login", type: "boolean", description: "Ignore any reusable saved login" },
             {
                 name: "no-explore",
@@ -141,7 +136,6 @@ export const projectCommands = [
             const created = (await ctx.client.post(`/workspaces/${ws}/projects`, {
                 root_url: url,
                 requires_auth_choice: auth,
-                mutation_choice: flagBool(input, "allow-mutations") ? "allow_mutations" : null,
                 force_new_login: flagBool(input, "force-new-login"),
                 skip_exploration: noExplore,
             }));

package/dist/commands/runs.js

@@ -5,11 +5,33 @@ import { CliError, UsageError } from "../errors.js";
 import { buildImportForm, executeLocalSpec, toRunEntry, } from "../local-exec.js";
 import { countPlannedFrames, countWrittenFrames, PlaywrightMissingError, } from "../local-run.js";
 import { dim, green, red, yellow } from "../output.js";
-import { confirmInstall, installPlaywright } from "../playwright-install.js";
+import { anyGap, confirmInstall, describeGaps, installCommandsFor, installPlaywright, playwrightGaps, } from "../playwright-install.js";
 import { ProgressBar } from "../progress.js";
 import { arg, flagBool, flagNum, flagStr, projectPath } from "./util.js";
 import { watchRun } from "./watch.js";
 const MAX_FAILURE_SCREENSHOTS = 5;
+// One filesystem check before a single spec is fetched. A missing browser binary otherwise
+// fails EVERY test with the same launch error, which reads as a broken suite instead of a
+// box that can't run tests. On a TTY it's an offer; over MCP / CI it's the exact commands.
+async function ensureRunnableLocally(ctx) {
+    const gaps = playwrightGaps(process.cwd());
+    if (!anyGap(gaps))
+        return;
+    const commands = installCommandsFor(gaps);
+    const hint = `Local runs need ${describeGaps(gaps)}. Install it, then re-run:\n  ${commands}`;
+    if (!ctx.interactive || !(await confirmInstall(ctx.prompt, commands)))
+        throw new CliError(hint);
+    try {
+        await installPlaywright(process.cwd(), (line) => ctx.err(dim(line)));
+    }
+    catch (err) {
+        throw new CliError(`${err instanceof Error ? err.message : String(err)}\n\nFinish it by hand:\n  ${commands}`);
+    }
+    const left = playwrightGaps(process.cwd());
+    if (anyGap(left))
+        throw new CliError(hint);
+    ctx.err(green(`✓ ${describeGaps(gaps)} installed`));
+}
 export function parseHeaders(raw) {
     if (!raw || raw.length === 0)
         return null;
@@ -75,20 +97,24 @@ export const runCommands = [
         name: "runs local",
         summary: "Run tests on your machine with your own Playwright; results sync to Beryl",
         description: "Unlike `runs trigger`, the browser runs on YOUR machine — each test's rendered spec is " +
-            "fetched and run with your local @playwright/test (on a terminal the CLI offers to " +
-            "install it the first time it's missing; over MCP it prints the install commands). " +
-            "Signup/OTP flows work: the CLI mints a fresh run inbox and answers the spec's " +
-            "await_email steps over the API, exactly as the cloud runner would. Saved-login tests " +
-            "({{login_email}}/{{login_password}}) work too: the password is fetched once over the " +
-            "logged secret-reveal route, handed to the spec the way the cloud runner does, and " +
-            "scrubbed from any error text or DOM snapshot before results upload. When the run " +
-            "finishes, the results and replay artifacts are imported into Beryl as a normal run " +
+            "fetched and run with your local @playwright/test and the Chromium binary it drives. " +
+            "Both are checked once before any spec is fetched, so a machine that can't run tests " +
+            "says so once instead of failing every test (on a terminal the CLI offers to install " +
+            "whichever half is missing; over MCP it prints the exact install commands). " +
+            "Signup/OTP flows work: the CLI answers the spec's await_email steps over the API " +
+            "against the same mailbox the cloud runner uses. Authenticated tests work too: a plan " +
+            "that signs itself in with {{login_email}}/{{login_password}} has its password fetched " +
+            "once over the logged secret-reveal route, handed to the spec the way the cloud runner " +
+            "does, and scrubbed from any error text or DOM snapshot before results upload. When the " +
+            "run finishes, the results and replay artifacts are imported into Beryl as a normal run " +
             "(trigger source `local`) — history, replay, and reports all work; pass --no-sync to " +
-            "keep a run entirely off the record while iterating. A captured-session test still " +
-            "refuses to run locally (its session lives encrypted in Beryl's cloud and is never " +
-            "decrypted to your disk) — it is skipped with a note. Point --url-override at a local " +
-            "dev server or preview, and --dir to keep specs, artifacts, and reports on disk. " +
-            "Exits 0 only if every executed test passed.",
+            "keep a run entirely off the record while iterating. Session-mode tests run here too: " +
+            "in the cloud their account signs in once per run and every test rides that session, " +
+            "and locally the server hands you the same test with that account's sign-in steps in " +
+            "front, so it proves the same thing on your machine. Only a test that depends on a " +
+            "session Beryl captured server-side is skipped, with a note. Point " +
+            "--url-override at a local dev server or preview, and --dir to keep specs, artifacts, " +
+            "and reports on disk. Exits 0 only if every executed test passed.",
         scope: "project",
         args: [
             {
@@ -129,6 +155,7 @@ export const runCommands = [
             "beryl runs local 4f… --no-sync --dir ./beryl-local",
         ],
         async run(ctx, input) {
+            await ensureRunnableLocally(ctx);
             const { workspaceId, projectId } = await ctx.requireProject(input);
             // Deduped: a repeated id would put the same test twice in one imported run,
             // which the import manifest rejects.
@@ -180,21 +207,25 @@ export const runCommands = [
                     requiresAuth: Boolean(script.requires_auth),
                     usesEmail: /__vmInbox\(|__vmAwaitEmail\(/.test(script.content),
                     usesLoginPassword: Boolean(script.uses_login_password),
+                    inlinedLoginSteps: script.inlined_login_steps ?? 0,
+                    ...(script.email ? { email: script.email } : {}),
                     ...(script.login_config_error ? { loginConfigError: script.login_config_error } : {}),
                 });
             }
             if (specs.length === 0)
                 throw new CliError("No runnable tests were found.");
-            // A captured-session test's login lives encrypted in Beryl's cloud and is never
-            // handed to a local runner — skip it rather than run a spec doomed at the wall.
-            // A saved-login test missing its backing config would type a literal placeholder
-            // into the page: same treatment, with the server's fix-it message.
+            // A test that leans on a session Beryl holds server-side gets no session here, so
+            // skip it rather than run a spec doomed at the login wall. Session-mode tests are
+            // NOT in that set: the server renders them with their account's own sign-in steps
+            // in front, so they sign themselves in here and run like any other. A test whose
+            // account is missing its password would type a literal placeholder into the page:
+            // same treatment, with the server's fix-it message.
             const skipped = specs.filter((s) => s.requiresAuth || s.loginConfigError);
             const runnable = specs.filter((s) => !s.requiresAuth && !s.loginConfigError);
             for (const s of skipped) {
                 ctx.err(yellow(s.requiresAuth
-                    ? `! ${s.title}: signs in with a captured session, so it only runs in Beryl's ` +
-                        `cloud — skipped (use \`beryl runs trigger\`).`
+                    ? `! ${s.title}: needs a session only Beryl's cloud holds — skipped ` +
+                        `(use \`beryl runs trigger\`).`
                     : `! ${s.title}: skipped — ${s.loginConfigError}`));
             }
             if (runnable.length === 0)
@@ -235,14 +266,24 @@ export const runCommands = [
                 const testStarted = new Date().toISOString();
                 let outcome;
                 let runError;
+                let lastStep = 0;
                 const attempt = () => executeLocalSpec({ client: ctx.client, workspaceId, projectId }, {
                     spec,
                     dir: dir ? path.join(dir, spec.id) : undefined,
                     harvest: sync,
                     loginPassword,
-                    onEvent: (line) => ctx.err(dim(line)),
+                    // Clear the rewriting bar before a mid-test log line, or the line is
+                    // appended onto the live bar and fossilises it into scrollback.
+                    onEvent: (line) => {
+                        bar.clear();
+                        ctx.err(dim(line));
+                        bar.update({ ...state(), step: lastStep });
+                    },
                     onSpawn: (runDir) => {
-                        const ticker = setInterval(() => bar.update({ ...state(), step: countWrittenFrames(runDir) }), 300);
+                        const ticker = setInterval(() => {
+                            lastStep = countWrittenFrames(runDir);
+                            bar.update({ ...state(), step: lastStep });
+                        }, 300);
                         return () => clearInterval(ticker);
                     },
                 });

package/dist/commands/tests.js

@@ -162,9 +162,11 @@ export const testCommands = [
             "terminal the CLI offers to install it). " +
             "A red replay banks NOTHING: the failure evidence comes back (over MCP the screenshot is " +
             "image content), you fix the plan file and re-run. The proving run is imported as the " +
-            "test's first run (--no-sync to skip). A plan that signs in with a captured session cannot " +
-            "replay locally (the session never leaves Beryl's cloud) — it falls back to server-side " +
-            "verification automatically. Optional `before` and `after` arrays hold setup and teardown " +
+            "test's first run (--no-sync to skip). A plan that signs in with a session Beryl captured " +
+            "server-side cannot replay locally (that session never leaves Beryl's cloud) — it falls " +
+            "back to server-side verification automatically. A session-mode plan replays locally " +
+            "fine: the server renders it with its account's stored sign-in steps in front, so " +
+            "the same identity is exercised on your machine. Optional `before` and `after` arrays hold setup and teardown " +
             "steps: `after` runs even when a main step fails, which is how a create/update/delete test " +
             "cleans up the record it made on the runs that go red.",
         scope: "project",
@@ -279,6 +281,7 @@ export const testCommands = [
                 requiresAuth: false,
                 usesEmail: /__vmInbox\(|__vmAwaitEmail\(/.test(content),
                 usesLoginPassword: compiled.uses_login_password,
+                email: compiled.email ?? undefined,
             });
             const startedAt = new Date().toISOString();
             const attempts = 1 + Math.max(0, compiled.policy.error_retries);

package/dist/email-pump.js

@@ -10,14 +10,17 @@ export function startEmailPump(opts) {
     let stopped = false;
     const served = new Set();
     const consumed = new Set();
-    let since = opts.since;
+    let storedAfter = opts.storedAfter;
+    let since;
     const fetchLatest = async (req, timeoutS) => {
         try {
-            return (await opts.client.get(`/workspaces/${opts.workspaceId}/inboxes/${opts.inboxId}/emails/latest`, {
+            return (await opts.client.get(`/workspaces/${opts.workspaceId}/mailboxes/${opts.inboxId}/emails/latest`, {
                 timeout_s: timeoutS,
                 since,
+                stored_after: storedAfter,
                 from_contains: req.from_contains,
                 subject_contains: req.subject_contains,
+                recipient_contains: opts.recipientContains,
             }));
         }
         catch (err) {

package/dist/http.js

@@ -52,7 +52,10 @@ export class ApiClient {
         }
         if (response.status === 401) {
             throw new AuthError(this.token
-                ? "Authentication failed — the token is invalid, expired, or revoked. Run `beryl login`."
+                ? "Authentication failed — the token is invalid, expired, or revoked. Run " +
+                    "`beryl login`. If you just did, and this is an MCP server started with an " +
+                    "explicit BERYL_API_KEY/BERYL_TOKEN, that env var wins over the login — " +
+                    "re-register the server to pick up the new token."
                 : "Not logged in. Run `beryl login` or set BERYL_API_KEY.");
         }
         if (!response.ok) {

package/dist/local-exec.js

@@ -7,6 +7,7 @@ import { PlaywrightMissingError, runSpecLocally, } from "./local-run.js";
 export const IMPORT_MAX_ERROR_LEN = 5000;
 export const IMPORT_MAX_FILE_BYTES = 14 * 1024 * 1024;
 export const IMPORT_MAX_TOTAL_BYTES = 180 * 1024 * 1024;
+export const IMPORT_MAX_FILES = 3600;
 export function toRunEntry(spec, outcome, runError, startedAt, ordinal, redact) {
     // Mirrors the cloud runner's redact_result: the spec types the secret into the
     // page, so error text and the DOM snapshot can echo it back — scrub before the
@@ -51,14 +52,19 @@ export function toRunEntry(spec, outcome, runError, startedAt, ordinal, redact)
         return entry;
     // A frame over the per-file cap would force dropping mid-list and shift the
     // index-aligned url/duration sidecars — drop the whole filmstrip instead.
-    if (harvested.frames.every((f) => f.length <= IMPORT_MAX_FILE_BYTES)) {
-        harvested.frames.forEach((bytes, i) => {
+    // Drop the inlined sign-in's frames before anything is index-aligned to the stored
+    // plan: `runs explain` zips the plan's steps against these lists, so an off-by-K here
+    // shows every step's screenshot next to the wrong step.
+    const skip = Math.min(spec.inlinedLoginSteps ?? 0, harvested.frames.length);
+    const frames = harvested.frames.slice(skip);
+    if (frames.every((f) => f.length <= IMPORT_MAX_FILE_BYTES)) {
+        frames.forEach((bytes, i) => {
             const name = `r${ordinal}-frame-${String(i).padStart(3, "0")}.png`;
             entry.frames.push(name);
             entry.files.push({ name, bytes });
         });
-        entry.frame_urls = harvested.frameUrls;
-        entry.frame_durations_ms = harvested.frameDurationsMs;
+        entry.frame_urls = harvested.frameUrls.slice(skip);
+        entry.frame_durations_ms = harvested.frameDurationsMs.slice(skip);
     }
     if (harvested.screenshot && harvested.screenshot.length <= IMPORT_MAX_FILE_BYTES) {
         entry.screenshot = `r${ordinal}-screenshot.png`;
@@ -90,6 +96,22 @@ export function buildImportForm(entries, opts) {
         total -= frameBytes;
         opts.onNote?.(`replay frames for test ${entry.test_case_id} dropped (upload size cap)`);
     }
+    // File-count budget: the server parses at most RUN_IMPORT_MAX_FILES multipart
+    // parts, so a big suite's filmstrips can overflow on count with bytes to spare.
+    let fileCount = entries.reduce((n, e) => n + e.files.length, 0);
+    for (const entry of entries) {
+        if (fileCount <= IMPORT_MAX_FILES)
+            break;
+        const frameFiles = entry.files.filter((f) => entry.frames.includes(f.name)).length;
+        if (frameFiles === 0)
+            continue;
+        entry.files = entry.files.filter((f) => !entry.frames.includes(f.name));
+        entry.frames = [];
+        entry.frame_urls = [];
+        entry.frame_durations_ms = [];
+        fileCount -= frameFiles;
+        opts.onNote?.(`replay frames for test ${entry.test_case_id} dropped (upload file-count cap)`);
+    }
     const manifest = {
         environment_id: opts.environmentId ?? null,
         target_url_override: opts.targetUrlOverride ?? null,
@@ -108,9 +130,8 @@ export function buildImportForm(entries, opts) {
     return form;
 }
 /**
- * Run one rendered spec on this machine with its full service harness: mint a run
- * inbox when the spec awaits email (deleted after, best-effort), write the
- * inbox/login sidecars, pump `await_email` requests over the API while Playwright
+ * Run one rendered spec on this machine with its full service harness: write the
+ * inbox/login sidecars and pump `await_email` requests over the API while Playwright
  * runs. The one local-execution seam shared by `runs local` and the local-verify
  * `tests create`. {@link PlaywrightMissingError} propagates (environmental — the
  * caller decides whether to offer an install); any other throw is captured as
@@ -118,11 +139,18 @@ export function buildImportForm(entries, opts) {
  */
 export async function executeLocalSpec(deps, opts) {
     const { spec } = opts;
-    const inbox = spec.usesEmail
-        ? (await deps.client.post(`/workspaces/${deps.workspaceId}/inboxes`, {
-            ttl_hours: 1,
-            project_id: deps.projectId,
-        }))
+    const inbox = spec.email
+        ? {
+            id: spec.email.inbox_id,
+            address: spec.email.address,
+            recipientContains: spec.email.recipient_contains ?? undefined,
+            // NOW, not the mailbox's creation time: it already holds every earlier run's
+            // mail, and an older code served as this run's would pass the step with a value
+            // the app then rejects. Sent as stored_after, which fences on the server's own
+            // INGESTION time and is clamped server-side — `since` compares against the
+            // sender's Date: header, so a fast local clock would fence out mail that arrived.
+            storedAfter: new Date().toISOString(),
+        }
         : undefined;
     try {
         const outcome = await runSpecLocally({
@@ -146,7 +174,8 @@ export async function executeLocalSpec(deps, opts) {
                         client: deps.client,
                         workspaceId: deps.workspaceId,
                         inboxId: inbox.id,
-                        since: inbox.created_at,
+                        storedAfter: inbox.storedAfter,
+                        recipientContains: inbox.recipientContains,
                         onEvent: opts.onEvent,
                     })
                     : undefined;
@@ -166,11 +195,4 @@ export async function executeLocalSpec(deps, opts) {
         // caller records, not an aborted command.
         return { runError: err instanceof Error ? err.message : String(err) };
     }
-    finally {
-        if (inbox) {
-            await deps.client
-                .del(`/workspaces/${deps.workspaceId}/inboxes/${inbox.id}`)
-                .catch(() => undefined);
-        }
-    }
 }

package/dist/playwright-install.js

@@ -1,5 +1,7 @@
 import { spawn } from "node:child_process";
+import fs from "node:fs";
 import { createRequire } from "node:module";
+import os from "node:os";
 import path from "node:path";
 // The two commands that turn "nothing Playwright-related installed" into "local runs work":
 // the test runner as a dev dep, then its browser binary. Kept as data so the CLI can both
@@ -7,24 +9,133 @@ import path from "node:path";
 export const INSTALL_TEST_RUNNER = ["npm", "i", "-D", "@playwright/test"];
 export const INSTALL_CHROMIUM = ["npx", "playwright", "install", "chromium"];
 export const PLAYWRIGHT_INSTALL_COMMANDS = `${INSTALL_TEST_RUNNER.join(" ")} && ${INSTALL_CHROMIUM.join(" ")}`;
-// Resolve `@playwright/test` the way Playwright itself will at run time — from the project
-// tree, not from wherever the globally-installed CLI happens to live. `createRequire` rooted
-// at cwd walks up the same node_modules chain, so this is true iff a local run would find it.
+// Resolve from the project tree, not from wherever the globally-installed CLI happens to
+// live — `createRequire` rooted at cwd walks up the same node_modules chain Playwright will.
+const projectRequire = (cwd) => createRequire(path.join(cwd, "package.json"));
 export function hasPlaywrightTest(cwd) {
     try {
-        createRequire(path.join(cwd, "package.json")).resolve("@playwright/test");
+        projectRequire(cwd).resolve("@playwright/test");
         return true;
     }
     catch {
         return false;
     }
 }
-export const INSTALL_PROMPT = `Install local Playwright now (${PLAYWRIGHT_INSTALL_COMMANDS})? [Y/n] `;
+// A local run launches chromium headless, which Playwright serves from a separate
+// `chromium_headless_shell` build (`playwright install chromium` fetches both). That is the
+// only engine a run ever launches, so it is the only one we install or check for.
+const HEADLESS_SHELL = "chromium-headless-shell";
+// Written last by Playwright's downloader, so its presence means a complete browser.
+const INSTALL_MARKER = "INSTALLATION_COMPLETE";
+function playwrightCoreDir(cwd) {
+    const req = projectRequire(cwd);
+    try {
+        return path.dirname(req.resolve("playwright-core/package.json"));
+    }
+    catch {
+        // Not hoisted (pnpm) — look from @playwright/test's own tree instead.
+    }
+    try {
+        const fromRunner = createRequire(req.resolve("@playwright/test"));
+        return path.dirname(fromRunner.resolve("playwright-core/package.json"));
+    }
+    catch {
+        return undefined;
+    }
+}
+// Mirrors playwright-core's registry root: PLAYWRIGHT_BROWSERS_PATH ("0" means inside the
+// package), else the per-platform cache dir. undefined on a platform Playwright doesn't
+// support, where we have no verdict to offer.
+function browsersRoot(coreDir) {
+    const override = process.env.PLAYWRIGHT_BROWSERS_PATH;
+    if (override === "0")
+        return coreDir ? path.join(coreDir, ".local-browsers") : undefined;
+    if (override)
+        return path.resolve(override);
+    const home = os.homedir();
+    if (process.platform === "darwin")
+        return path.join(home, "Library", "Caches", "ms-playwright");
+    if (process.platform === "win32") {
+        const local = process.env.LOCALAPPDATA || path.join(home, "AppData", "Local");
+        return path.join(local, "ms-playwright");
+    }
+    if (process.platform === "linux") {
+        return path.join(process.env.XDG_CACHE_HOME || path.join(home, ".cache"), "ms-playwright");
+    }
+    return undefined;
+}
+// The exact directory this project's Playwright will look in: <root>/<browser name with
+// dashes as underscores>-<revision>, straight out of playwright-core's browsers.json — so a
+// browser downloaded for an older Playwright doesn't read as the one this one needs.
+function wantedChromiumDir(coreDir) {
+    if (!coreDir)
+        return undefined;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(coreDir, "browsers.json"), "utf8"));
+        const entry = parsed.browsers?.find((b) => b.name === HEADLESS_SHELL) ??
+            parsed.browsers?.find((b) => b.name === "chromium");
+        if (!entry?.name || !entry.revision)
+            return undefined;
+        return `${entry.name.replace(/-/g, "_")}-${entry.revision}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+const isComplete = (dir) => fs.existsSync(path.join(dir, INSTALL_MARKER));
+/**
+ * Is the browser binary a local run actually launches present? Without it every test in a
+ * run dies with the same `browserType.launch: Executable doesn't exist` — an environment
+ * problem that reads as a broken suite.
+ */
+export function hasChromiumBrowser(cwd) {
+    const coreDir = playwrightCoreDir(cwd);
+    const root = browsersRoot(coreDir);
+    // Nowhere known to look — say nothing rather than block; the run surfaces Playwright's
+    // own error if it really is missing.
+    if (!root)
+        return true;
+    const wanted = wantedChromiumDir(coreDir);
+    if (wanted)
+        return isComplete(path.join(root, wanted));
+    // Revision unknown (no resolvable playwright-core): any completed chromium build is the
+    // best evidence there is, and guessing wrong only costs an idempotent re-install.
+    try {
+        return fs
+            .readdirSync(root)
+            .some((d) => /^chromium(_headless_shell)?-\d+$/.test(d) && isComplete(path.join(root, d)));
+    }
+    catch {
+        return false;
+    }
+}
+export function playwrightGaps(cwd) {
+    const runner = !hasPlaywrightTest(cwd);
+    // With no runner there is no revision to judge a cached browser against, so the honest
+    // answer is the full install — not the npm half and a second failure right after it.
+    return { runner, browser: runner || !hasChromiumBrowser(cwd) };
+}
+export const anyGap = (gaps) => gaps.runner || gaps.browser;
+export function describeGaps(gaps) {
+    if (gaps.runner && gaps.browser)
+        return "@playwright/test + the Chromium browser";
+    return gaps.browser ? "the Chromium browser" : "@playwright/test";
+}
+/** Only the commands the missing halves need — a present @playwright/test isn't reinstalled. */
+export function installCommandsFor(gaps) {
+    const commands = [
+        ...(gaps.runner ? [INSTALL_TEST_RUNNER.join(" ")] : []),
+        ...(gaps.browser ? [INSTALL_CHROMIUM.join(" ")] : []),
+    ];
+    return commands.length > 0 ? commands.join(" && ") : PLAYWRIGHT_INSTALL_COMMANDS;
+}
+export const installPrompt = (commands) => `Install local Playwright now (${commands})? [Y/n] `;
+export const INSTALL_PROMPT = installPrompt(PLAYWRIGHT_INSTALL_COMMANDS);
 // Ask (default-yes) whether to install. Returns false — not throwing — when there is no answer
 // or the prompt fails, so callers uniformly fall back to printing the install hint.
-export async function confirmInstall(prompt) {
+export async function confirmInstall(prompt, commands = PLAYWRIGHT_INSTALL_COMMANDS) {
     try {
-        return !/^n(o)?$/i.test(await prompt(INSTALL_PROMPT));
+        return !/^n(o)?$/i.test(await prompt(installPrompt(commands)));
     }
     catch {
         return false;

package/dist/registry/index.js

@@ -1,9 +1,10 @@
 import { accountCommands } from "../commands/account.js";
+import { testAccountCommands } from "../commands/accounts.js";
 import { authCommands } from "../commands/auth.js";
 import { configCommands } from "../commands/config-vars.js";
 import { environmentCommands } from "../commands/environments.js";
 import { explorationCommands } from "../commands/explorations.js";
-import { inboxCommands } from "../commands/inboxes.js";
+import { mailboxCommands } from "../commands/mailboxes.js";
 import { initCommands } from "../commands/init.js";
 import { mcpCommands } from "../commands/mcp.js";
 import { projectCommands } from "../commands/projects.js";
@@ -61,7 +62,8 @@ export const commands = [
     ...explorationCommands,
     ...configCommands,
     ...slackCommands,
-    ...inboxCommands,
+    ...mailboxCommands,
+    ...testAccountCommands,
     ...accountCommands,
     ...mcpCommands,
 ].map(withScopeFlags).map(hideFromMcp);

package/dist/schema.generated.js

@@ -25,6 +25,15 @@ export const ACTION_PLAN_SCHEMA = {
             "title": "ActionType",
             "type": "string"
         },
+        "AuthMode": {
+            "description": "How an authenticated test reaches its logged-in start state. The AUTHOR sets\nthis, explicitly, on every plan that sets ``requires_auth`` \u2014 a submitted plan\nthat omits it is rejected, because the wrong guess banks a plan that runs logged\nout and fails somewhere misleading.\n\n``inline`` \u2014 the plan signs itself in: its own steps fill ``{{login_email}}`` /\n``{{login_password}}``, or it rides the project's captured session.\n\n``session`` \u2014 the test's account signs in ONCE per run, ahead of the tests; the\nresulting browser session is proved against a fresh context and then handed to every\nsession-mode test in the run. The plan itself carries NO sign-in steps, so it starts\nwhere the flow it actually tests begins. Requires the account to have a stored\nlogin plan (``accounts set-login``).",
+            "enum": [
+                "inline",
+                "session"
+            ],
+            "title": "AuthMode",
+            "type": "string"
+        },
         "DialogChoice": {
             "enum": [
                 "accept",
@@ -865,6 +874,7 @@ export const ACTION_PLAN_SCHEMA = {
                                     "inbox_address",
                                     "login_email",
                                     "login_password",
+                                    "mailbox_address",
                                     "timestamp",
                                     "unique",
                                     "uuid"
@@ -1130,6 +1140,24 @@ export const ACTION_PLAN_SCHEMA = {
     "$id": "https://api.beryl.so/api/v1/schemas/action-plan.schema.json",
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "allOf": [
+        {
+            "$comment": "requires_auth demands an explicit auth_mode \u2014 there is no default. 'inline' when the plan signs itself in, 'session' when it rides its account's once-per-run session and carries no sign-in steps.",
+            "if": {
+                "properties": {
+                    "requires_auth": {
+                        "const": true
+                    }
+                },
+                "required": [
+                    "requires_auth"
+                ]
+            },
+            "then": {
+                "required": [
+                    "auth_mode"
+                ]
+            }
+        },
         {
             "$comment": "The first executed step must be a goto, so the test loads a page before acting (that is before[0] when there is a setup section, else steps[0]).",
             "else": {
@@ -1242,6 +1270,10 @@ export const ACTION_PLAN_SCHEMA = {
             "default": null,
             "title": "Auth Label"
         },
+        "auth_mode": {
+            "$ref": "#/$defs/AuthMode",
+            "default": "inline"
+        },
         "before": {
             "items": {
                 "$ref": "#/$defs/PlanStep"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beryl-so/cli",
-  "version": "0.17.0",
+  "version": "0.21.4",
   "description": "Beryl on the command line — projects, runs, the exploring agent, and an MCP server over the same commands.",
   "license": "MIT",
   "type": "module",