@beryl-so/cli 0.17.0 → 0.22.0

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

@@ -2,14 +2,36 @@ import fs from "node:fs";
 import path from "node:path";
 import { downloadRunArtifacts, failureImages, isFailing, resultsOf, } from "../artifacts.js";
 import { CliError, UsageError } from "../errors.js";
-import { buildImportForm, executeLocalSpec, toRunEntry, } from "../local-exec.js";
+import { buildImportForm, establishAccountSession, executeLocalSpec, IMPORT_MAX_ERROR_LEN, 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 behave as " +
+            "in the cloud: their account signs in once per invocation and every session-mode " +
+            "test rides that session; a failed sign-in fails those tests with the same " +
+            "SESSION_* reason a cloud run reports. 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.
@@ -149,19 +176,33 @@ export const runCommands = [
             const ids = all ? listed.filter((t) => t.is_active !== false).map((t) => t.id) : explicitIds;
             if (ids.length === 0)
                 throw new CliError("This project has no tests to run.");
+            const fetchScript = (id) => ctx.client.get(`${projectPath(workspaceId, projectId)}/tests/${id}/script`, {
+                // frames only matter when the run will be imported: they become the replay.
+                // environment_id keeps the baked login_email on the same environment the
+                // LOGIN_PASSWORD reveal below is scoped to.
+                base_url: urlOverride,
+                frames: sync ? true : undefined,
+                environment_id: flagStr(input, "env"),
+            });
+            const toLocalSpec = (id, script) => ({
+                id,
+                title: titles.get(id) ?? id.slice(0, 8),
+                content: script.content,
+                requiresAuth: Boolean(script.requires_auth),
+                usesEmail: /__vmInbox\(|__vmAwaitEmail\(/.test(script.content),
+                usesLoginPassword: Boolean(script.uses_login_password),
+                inlinedLoginSteps: script.inlined_login_steps ?? 0,
+                ...(script.session_mode && script.account_id
+                    ? { sessionMode: true, accountId: script.account_id }
+                    : {}),
+                ...(script.email ? { email: script.email } : {}),
+                ...(script.login_config_error ? { loginConfigError: script.login_config_error } : {}),
+            });
             const specs = [];
             for (const id of ids) {
                 let script;
                 try {
-                    script = (await ctx.client.get(`${projectPath(workspaceId, projectId)}/tests/${id}/script`, 
-                    // frames only matter when the run will be imported: they become the replay.
-                    // environment_id keeps the baked login_email on the same environment the
-                    // LOGIN_PASSWORD reveal below is scoped to.
-                    {
-                        base_url: urlOverride,
-                        frames: sync ? true : undefined,
-                        environment_id: flagStr(input, "env"),
-                    }));
+                    script = await fetchScript(id);
                 }
                 catch (err) {
                     // With --all an unrenderable test (no plan yet) is a skip, not an abort;
@@ -173,32 +214,66 @@ export const runCommands = [
                     }
                     throw err;
                 }
-                specs.push({
-                    id,
-                    title: titles.get(id) ?? id.slice(0, 8),
-                    content: script.content,
-                    requiresAuth: Boolean(script.requires_auth),
-                    usesEmail: /__vmInbox\(|__vmAwaitEmail\(/.test(script.content),
-                    usesLoginPassword: Boolean(script.uses_login_password),
-                    ...(script.login_config_error ? { loginConfigError: script.login_config_error } : {}),
-                });
+                specs.push(toLocalSpec(id, script));
             }
             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.
-            const skipped = specs.filter((s) => s.requiresAuth || s.loginConfigError);
-            const runnable = specs.filter((s) => !s.requiresAuth && !s.loginConfigError);
+            // A test that leans on a session this CLI cannot establish gets no session here,
+            // so skip it rather than run a spec doomed at the login wall. A session-mode test
+            // is NOT in that set: its account's session is established below, once, exactly as
+            // a cloud run's setup phase does. A test whose account is missing its password
+            // would type a literal placeholder into the page: skip, with the server's fix-it
+            // message.
+            const skipped = specs.filter((s) => (s.requiresAuth && !(s.sessionMode && s.accountId)) || s.loginConfigError);
+            const runnable = specs.filter((s) => !skipped.includes(s));
             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}: skipped — ${s.loginConfigError}`));
+                ctx.err(yellow(s.loginConfigError
+                    ? `! ${s.title}: skipped — ${s.loginConfigError}`
+                    : `! ${s.title}: needs a session only Beryl's cloud holds — skipped ` +
+                        `(use \`beryl runs trigger\`).`));
             }
             if (runnable.length === 0)
                 throw new CliError("None of the selected tests can run locally.");
+            // Once per account, before any test runs — the local counterpart of the cloud
+            // worker's run-setup phase, produced by the same server-side establish (stored-
+            // session cache, login replay, proof). A failure here fails only that account's
+            // tests, with the same stable-prefixed reason a cloud run reports; an account
+            // proven unable to carry a session gets its tests re-rendered to sign themselves
+            // in, the same degraded mode a cloud run applies.
+            const sessions = new Map();
+            const sessionErrors = new Map();
+            const accountIds = [
+                ...new Set(runnable.filter((s) => s.sessionMode && s.accountId).map((s) => s.accountId)),
+            ];
+            for (const accountId of accountIds) {
+                ctx.err(dim("Establishing the test account's session (once per run)…"));
+                const established = await establishAccountSession(ctx.client, projectPath(workspaceId, projectId), accountId);
+                if (established.session) {
+                    sessions.set(accountId, established.session);
+                }
+                else if (established.unsupported) {
+                    // The server just latched UNSUPPORTED, so a re-fetch renders these specs with
+                    // their account's sign-in steps inlined — they run self-signing like any other.
+                    // Whole-object replacement, not a merge: the inlined render carries no
+                    // session_mode, and a merge would leave the stale sessionMode/accountId behind.
+                    ctx.err(yellow(`! ${established.error} — signing in per test.`));
+                    try {
+                        for (const [i, s] of runnable.entries()) {
+                            if (s.accountId !== accountId)
+                                continue;
+                            runnable[i] = toLocalSpec(s.id, await fetchScript(s.id));
+                        }
+                    }
+                    catch (err) {
+                        // A failed re-fetch fails only this account's tests, like any other
+                        // establish failure — not the whole invocation.
+                        sessionErrors.set(accountId, err instanceof Error ? err.message : String(err));
+                    }
+                }
+                else {
+                    sessionErrors.set(accountId, established.error ?? "SESSION_UNAVAILABLE");
+                }
+            }
             // Revealed once for the batch over the member-gated, logged route — the same
             // secret the cloud runner banks into run-config.json; never in the spec source.
             let loginPassword;
@@ -233,16 +308,51 @@ export const runCommands = [
                 if (!bar.active)
                     ctx.err(dim(`Running ${spec.title}…`));
                 const testStarted = new Date().toISOString();
+                // No proven session for this account: running the spec would open the page
+                // logged out and pass every assertion that tolerates that — fail it in the
+                // setup phase with the establish error, exactly as a cloud run does.
+                const sessionError = spec.accountId ? sessionErrors.get(spec.accountId) : undefined;
+                if (spec.sessionMode && sessionError !== undefined) {
+                    entries.push({
+                        test_case_id: spec.id,
+                        status: "failed",
+                        phase: "setup",
+                        error_message: sessionError.slice(0, IMPORT_MAX_ERROR_LEN),
+                        started_at: testStarted,
+                        completed_at: new Date().toISOString(),
+                        frames: [],
+                        frame_urls: [],
+                        frame_durations_ms: [],
+                        files: [],
+                    });
+                    done += 1;
+                    failed += 1;
+                    bar.clear();
+                    ctx.err(`${red("✗")} ${spec.title}\n    ${dim(sessionError.split("\n")[0] ?? "")}`);
+                    continue;
+                }
+                const session = spec.sessionMode ? sessions.get(spec.accountId ?? "") : undefined;
                 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)),
+                    session,
+                    // 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);
                     },
                 });
@@ -282,7 +392,10 @@ export const runCommands = [
                     // result, not an aborted batch: the remaining tests still deserve their run.
                     runError = err instanceof Error ? err.message : String(err);
                 }
-                const entry = toRunEntry(spec, outcome, runError, testStarted, entries.length, spec.usesLoginPassword ? loginPassword : undefined);
+                const entry = toRunEntry(spec, outcome, runError, testStarted, entries.length, [
+                    ...(spec.usesLoginPassword && loginPassword ? [loginPassword] : []),
+                    ...(session?.secrets ?? []),
+                ]);
                 entries.push(entry);
                 done += 1;
                 if (entry.status === "passed")

package/dist/commands/tests.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import { CliError, UsageError } from "../errors.js";
 import { ApiError } from "../http.js";
 import { lintPlan } from "../lint.js";
-import { buildImportForm, executeLocalSpec, toRunEntry, } from "../local-exec.js";
+import { buildImportForm, establishAccountSession, executeLocalSpec, toRunEntry, } from "../local-exec.js";
 import { PlaywrightMissingError } from "../local-run.js";
 import { dim, green, red, table, yellow } from "../output.js";
 import { confirmInstall, installPlaywright } from "../playwright-install.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",
@@ -241,9 +243,27 @@ export const testCommands = [
                 frames: sync ? true : undefined,
             });
             let compiled = await compile();
+            // Session-mode plan: establish the account's session once (server-side, reused
+            // from the stored one when it still proves live) and replay against it — the
+            // cloud shape. An unsupported account is re-compiled to sign itself in.
+            let session;
+            if (compiled.session_mode && compiled.account_id) {
+                ctx.err(dim("Establishing the test account's session…"));
+                const established = await establishAccountSession(ctx.client, projectPath(workspaceId, projectId), compiled.account_id);
+                if (established.session) {
+                    session = established.session;
+                }
+                else if (established.unsupported) {
+                    ctx.err(yellow(`! ${established.error} — the replay signs in itself.`));
+                    compiled = await compile();
+                }
+                else {
+                    throw new CliError(established.error ?? "SESSION_UNAVAILABLE");
+                }
+            }
             // A captured session lives encrypted in Beryl's cloud and is never handed to
             // this machine — the cloud is the only place this plan can be proven.
-            if (compiled.requires_auth) {
+            if (compiled.requires_auth && !session) {
                 ctx.err(yellow("! This plan signs in with a captured session, so it can only be verified " +
                     "in Beryl's cloud — verifying server-side instead."));
                 try {
@@ -279,6 +299,8 @@ export const testCommands = [
                 requiresAuth: false,
                 usesEmail: /__vmInbox\(|__vmAwaitEmail\(/.test(content),
                 usesLoginPassword: compiled.uses_login_password,
+                inlinedLoginSteps: compiled.inlined_login_steps ?? 0,
+                email: compiled.email ?? undefined,
             });
             const startedAt = new Date().toISOString();
             const attempts = 1 + Math.max(0, compiled.policy.error_retries);
@@ -300,6 +322,7 @@ export const testCommands = [
                         dir: flagStr(input, "dir"),
                         harvest: true,
                         loginPassword,
+                        session,
                         onEvent: (line) => ctx.err(dim(line)),
                     }));
                 }
@@ -366,7 +389,7 @@ export const testCommands = [
             }
             let runId;
             if (sync) {
-                const entry = toRunEntry({ ...specOf(compiled.content), id: String(created.id) }, outcome, undefined, startedAt, 0, loginPassword);
+                const entry = toRunEntry({ ...specOf(compiled.content), id: String(created.id) }, outcome, undefined, startedAt, 0, [...(loginPassword ? [loginPassword] : []), ...(session?.secrets ?? [])]);
                 const imported = (await ctx.client.request("POST", `${projectPath(workspaceId, projectId)}/runs/import`, {
                     form: buildImportForm([entry], {
                         environmentId: env,

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,13 +7,16 @@ 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
-    // bytes leave this machine. Frames and screenshots are pixels; nothing to scrub.
-    const scrub = (text) => (redact ? text.split(redact).join("***") : text);
-    const scrubBytes = (bytes) => redact && bytes.includes(redact)
-        ? Buffer.from(bytes.toString("utf8").split(redact).join("***"), "utf8")
+    // Mirrors the cloud runner's redact_result: the spec types secrets into the page
+    // and an injected session authenticates its requests, so error text and the DOM
+    // snapshot can echo them back — scrub before the bytes leave this machine. Frames
+    // and screenshots are pixels; nothing to scrub.
+    const values = (Array.isArray(redact) ? redact : [redact]).filter((v) => Boolean(v));
+    const scrub = (text) => values.reduce((out, v) => out.split(v).join("***"), text);
+    const scrubBytes = (bytes) => values.some((v) => bytes.includes(v))
+        ? Buffer.from(scrub(bytes.toString("utf8")), "utf8")
         : bytes;
     const completedAt = new Date().toISOString();
     const base = {
@@ -51,14 +54,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 +98,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,
@@ -107,10 +131,33 @@ export function buildImportForm(entries, opts) {
     }
     return form;
 }
+/** Establish (or reuse) an account's proven session server-side — the same establish a
+ *  cloud run's setup phase does, so one sign-in serves cloud and local alike. */
+export async function establishAccountSession(client, projectBase, accountId) {
+    let res;
+    try {
+        res = (await client.request("POST", `${projectBase}/test-accounts/${accountId}/session`));
+    }
+    catch (err) {
+        return { error: err instanceof Error ? err.message : String(err) };
+    }
+    if (res.ok && res.storage_state) {
+        return {
+            session: {
+                storageState: res.storage_state,
+                initScripts: res.init_scripts ?? [],
+                secrets: res.secrets ?? [],
+            },
+        };
+    }
+    return {
+        error: res.error ?? "SESSION_UNAVAILABLE",
+        unsupported: Boolean(res.unsupported),
+    };
+}
 /**
- * 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 +165,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({
@@ -130,7 +184,18 @@ export async function executeLocalSpec(deps, opts) {
             testName: spec.title,
             dir: opts.dir,
             harvest: opts.harvest,
-            redact: spec.usesLoginPassword ? opts.loginPassword : undefined,
+            redact: [
+                ...(spec.usesLoginPassword && opts.loginPassword ? [opts.loginPassword] : []),
+                ...(opts.session?.secrets ?? []),
+            ],
+            ...(opts.session
+                ? {
+                    authSession: {
+                        storageState: opts.session.storageState,
+                        initScripts: opts.session.initScripts,
+                    },
+                }
+                : {}),
             setup: inbox || (spec.usesLoginPassword && opts.loginPassword !== undefined)
                 ? (runDir) => {
                     if (inbox)
@@ -146,7 +211,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 +232,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);
-        }
-    }
 }