@beryl-so/cli 0.34.0 → 0.34.3

package/README.md

@@ -252,7 +252,7 @@ Trigger a run of a project's tests (e.g. in CI), then watch, inspect, and downlo
 | Command | Summary | MCP tool |
 | --- | --- | --- |
 | `beryl runs trigger` | Trigger a test run (whole suite, a subset, or one environment) | `runs_trigger` |
-| `beryl runs local [test-ids...]` | Run tests on your machine with your own Playwright; results sync to Beryl | `runs_local` |
+| `beryl runs local [test-ids...]` | Run tests on your machine with Playwright; results sync to Beryl | `runs_local` |
 | `beryl runs list` | List recent runs | `runs_list` |
 | `beryl runs get <run-id>` | Show one run with its per-test results | `runs_get` |
 | `beryl runs watch <run-id>` | Attach to a run and stream progress until it finishes | `runs_watch` |

package/dist/beryl-test-skill.js

@@ -73,7 +73,7 @@ exception are in \`tests create\`'s own description.
 Before the first plan:
 
 \`\`\`
-npm i -D @playwright/test && npx playwright install chromium   # once, per project
+npx @beryl-so/cli@latest init                         # once per machine: installs the Chromium browser (the runner ships with the CLI)
 beryl envs list                                       # the root URL gotos resolve against (§2)
 beryl envs update <id> --url https://app.example.com  # set it if root_url is empty — required
 beryl accounts list                                   # who do authenticated tests sign in as? (§1)
@@ -370,7 +370,7 @@ Weak (describes steps + asserts nothing meaningful):
 ## 4. The local run-fix loop
 
 Iterate on your machine before you rely on the cloud. \`beryl runs local\` runs banked
-tests with your local \`@playwright/test\` — no cloud, no waiting for a scheduled run.
+tests with the Playwright runner bundled in the CLI — no cloud, no waiting for a scheduled run.
 
 \`\`\`
 beryl runs local <test-id> --no-sync --url-override http://localhost:3000 --dir ./beryl-local

package/dist/commands/auth.js

@@ -175,7 +175,7 @@ export const authCommands = [
             const human = `${green("Logged in")} as ${me.name} <${me.email}>` +
                 `\n${dim(`Token saved to ${saved}`)}`;
             return {
-                data: { email: me.email, name: me.name, config: saved },
+                data: { id: me.id, email: me.email, name: me.name, config: saved },
                 human,
             };
         },

package/dist/commands/init.js

@@ -8,6 +8,7 @@ import { AuthError, CliError } from "../errors.js";
 import { ApiClient } from "../http.js";
 import { bold, cyan, dim, green, red, yellow } from "../output.js";
 import { anyGap, describeGaps, installCommandsFor, installPlaywright, playwrightGaps, } from "../playwright-install.js";
+import { aliasSessionToAccount, captureCliEvent, flushTelemetry, shutdownTelemetry, } from "../telemetry.js";
 import { cliVersion, warnIfStale } from "../version-check.js";
 import { authCommands } from "./auth.js";
 import { flagStr } from "./util.js";
@@ -117,16 +118,16 @@ function writeSkills(cwd, scope) {
         writeSkillFile(skillLeaf(path.join(root, ".claude", "skills"))),
     ];
 }
-// Local authoring drives a real browser via `@playwright/test` + chromium, and the whole
-// authoring workflow (walk the flow first, then bank the plan) depends on it — so the
-// install is mandatory, not offered: missing means install now, no prompt, no opt-out.
-// Both halves count: the npm package without the browser binary is a real state, and it
-// fails every local run with the same launch error. Never throws — a failed install must not
-// fail `init`, which has already done its wiring; it prints the exact commands instead.
+// Local authoring drives a real browser, and the whole authoring workflow (walk the flow
+// first, then bank the plan) depends on it — so the install is mandatory, not offered:
+// missing means install now, no prompt, no opt-out. The runner ships with the CLI; the
+// browser is the per-machine half, fetched for the runner's own revision. Never throws — a
+// failed install must not fail `init`, which has already done its wiring; it prints the
+// exact commands instead.
 async function ensureLocalPlaywright(ctx, cwd) {
     const gaps = playwrightGaps(cwd);
     if (!anyGap(gaps)) {
-        ctx.err(`${green("✓")} @playwright/test + Chromium already installed ${dim("(local runs ready)")}`);
+        ctx.err(`${green("✓")} Playwright + Chromium already installed ${dim("(local runs ready)")}`);
         return;
     }
     try {
@@ -141,7 +142,7 @@ async function ensureLocalPlaywright(ctx, cwd) {
     catch (err) {
         ctx.err(`${red("✗")} Playwright install failed: ${err.message}`);
         ctx.err(`${dim("•")} Finish the install by hand — local runs and browser authoring need it:\n` +
-            `    ${cyan(installCommandsFor(gaps))}`);
+            `    ${cyan(installCommandsFor(gaps, cwd))}`);
     }
 }
 export const initCommands = [
@@ -153,8 +154,9 @@ export const initCommands = [
             "agent. Nothing is detected and nothing is conditional: every run wires the beryl AND " +
             "playwright MCP servers, writes the authoring skill (user scope: your home " +
             ".agents/skills/ + .claude/skills/, so it follows you into every session; --scope " +
-            "project: the repo's own dirs, committed for teammates), and installs @playwright/test " +
-            "+ chromium if missing, since browser authoring and local runs depend on it. By default the " +
+            "project: the repo's own dirs, committed for teammates), and installs the Chromium " +
+            "browser if missing (the Playwright runner ships with the CLI, so any repo can run tests " +
+            "locally), since browser authoring and local runs depend on it. By default the " +
             "servers are wired per-user (matching where your login token lives) via `claude mcp add " +
             "-s user`; pass --scope project to write a committed .mcp.json for a shared repo " +
             "instead. No workspace/project pin and no URL prompt: ask Claude to write tests for " +
@@ -187,6 +189,10 @@ export const initCommands = [
         async run(ctx, input) {
             const cwd = process.cwd();
             let { client, config } = ctx;
+            const scope = (flagStr(input, "scope") ?? "user");
+            captureCliEvent("cli_init_started", config.apiUrl, { scope });
+            flushTelemetry();
+            let accountId;
             const signIn = async () => {
                 // Non-interactive skips the picker and lets `login` fail with its own
                 // "interactive input required" message, exactly as before.
@@ -194,7 +200,11 @@ export const initCommands = [
                     ? await ctx.prompt("Sign in: [1] Browser (opens beryl.so)  [2] Email me a code — [1]: ")
                     : "";
                 const login = authCommands.find((c) => c.name === "login");
-                await login.run(ctx, { args: {}, flags: answer.trim() === "2" ? { otp: true } : {} });
+                const result = await login.run(ctx, {
+                    args: {},
+                    flags: answer.trim() === "2" ? { otp: true } : {},
+                });
+                accountId = (result ?? {}).data?.id;
                 config = loadConfig();
                 if (!config.token)
                     throw new CliError("Login did not persist a token");
@@ -203,6 +213,7 @@ export const initCommands = [
             if (config.token) {
                 try {
                     const me = (await client.get("/account/"));
+                    accountId = me.id;
                     ctx.err(`${green("✓")} Signed in as ${me.email}`);
                 }
                 catch (err) {
@@ -215,7 +226,10 @@ export const initCommands = [
             else {
                 await signIn();
             }
-            const scope = (flagStr(input, "scope") ?? "user");
+            if (accountId) {
+                aliasSessionToAccount(accountId);
+                flushTelemetry();
+            }
             const report = (label, fresh, where) => ctx.err(`${green("✓")} ${label} ${fresh ? "configured" : "already configured"} ${dim(where)}`);
             if (scope === "user") {
                 // Claude Code owns ~/.claude.json — shell out to `claude mcp add` rather than write it.
@@ -267,6 +281,7 @@ export const initCommands = [
             // The .mcp.json entry is pinned to @latest, but a global install / old npx cache
             // still wins resolution — so tell the user when the CLI they just ran is stale.
             await warnIfStale(cliVersion(), (msg) => ctx.err(yellow(msg)));
+            await shutdownTelemetry();
             return {
                 data: {
                     scope,

package/dist/commands/runs.js

@@ -5,7 +5,7 @@ import { CliError, UsageError } from "../errors.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 { anyGap, confirmInstall, describeGaps, installCommandsFor, installPlaywright, playwrightGaps, } from "../playwright-install.js";
+import { anyGap, confirmInstall, describeGaps, installCommandsFor, installHint, installPlaywright, playwrightGaps, } from "../playwright-install.js";
 import { ProgressBar } from "../progress.js";
 import { arg, flagBool, flagNum, flagStr, idsInGroup, projectPath } from "./util.js";
 import { watchRun } from "./watch.js";
@@ -17,8 +17,8 @@ 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}`;
+    const commands = installCommandsFor(gaps, process.cwd());
+    const hint = installHint(process.cwd(), gaps);
     if (!ctx.interactive || !(await confirmInstall(ctx.prompt, commands)))
         throw new CliError(hint);
     try {
@@ -115,12 +115,13 @@ export const runCommands = [
     },
     {
         name: "runs local",
-        summary: "Run tests on your machine with your own Playwright; results sync to Beryl",
+        summary: "Run tests on your machine with 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 and the Chromium binary it drives. " +
+            "fetched and run with the Playwright runner bundled in the CLI (your repo's own " +
+            "@playwright/test wins when present) 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). " +
+            "the missing browser; over MCP it prints the exact install command). " +
             "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: for a plan " +
             "that signs itself in with {{login_email}}/{{login_password}}, the email is baked into " +
@@ -412,7 +413,9 @@ export const runCommands = [
                         if (err instanceof PlaywrightMissingError && ctx.interactive && !installOffered) {
                             installOffered = true;
                             bar.clear();
-                            if (!(await confirmInstall(ctx.prompt)))
+                            const cwd = process.cwd();
+                            const commands = installCommandsFor(playwrightGaps(cwd), cwd);
+                            if (!(await confirmInstall(ctx.prompt, commands)))
                                 throw err;
                             try {
                                 await installPlaywright(process.cwd(), (line) => ctx.err(dim(line)));

package/dist/commands/tests.js

@@ -5,7 +5,7 @@ import { lintPlan } from "../lint.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";
+import { confirmInstall, installCommandsFor, installPlaywright, playwrightGaps, } from "../playwright-install.js";
 import { ACTION_PLAN_SCHEMA } from "../schema.generated.js";
 import { arg, argList, flagBool, flagNum, flagStr, flagStrings, inGroup, projectPath, readJsonFlag, } from "./util.js";
 const testPath = (ws, p, id) => `${projectPath(ws, p)}/tests/${id}`;
@@ -207,13 +207,14 @@ export const testCommands = [
         summary: "Create a test case from a JSON action plan (for tests authored locally, e.g. by your coding agent)",
         description: "The plan is a JSON object whose steps are {action, selector, url, value, ...}: the first " +
             "EXECUTED step must be a goto, and at least one step must be an expect. Before anything is " +
-            "banked, the plan is proven by replaying it in a browser ON YOUR MACHINE with your local " +
-            "@playwright/test: the server renders the spec (`tests/compile`), the CLI runs it (minting " +
+            "banked, the plan is proven by replaying it in a browser ON YOUR MACHINE with the " +
+            "Playwright runner bundled in the CLI (your repo's own @playwright/test wins when " +
+            "present): the server renders the spec (`tests/compile`), the CLI runs it (minting " +
             "a run inbox for await_email steps and resolving the saved login exactly as a cloud run " +
             "would), and only a green replay creates the test (bound to the replayed plan by its hash). " +
             "This holds over MCP too: the replay runs on the machine hosting the MCP server, never on " +
-            "Beryl's; if @playwright/test is missing there the tool returns the install commands (on a " +
-            "terminal the CLI offers to install it). " +
+            "Beryl's; if the Chromium browser is missing there the tool returns the install command " +
+            "(`beryl init` installs it; on a terminal the CLI offers to). " +
             "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 session Beryl captured " +
@@ -399,8 +400,10 @@ export const testCommands = [
                         // pipe the hint is the answer.
                         if (ctx.interactive && !installOffered) {
                             installOffered = true;
-                            if (await confirmInstall(ctx.prompt)) {
-                                await installPlaywright(process.cwd(), (line) => ctx.err(dim(line)));
+                            const cwd = process.cwd();
+                            const commands = installCommandsFor(playwrightGaps(cwd), cwd);
+                            if (await confirmInstall(ctx.prompt, commands)) {
+                                await installPlaywright(cwd, (line) => ctx.err(dim(line)));
                                 attempt -= 1;
                                 continue;
                             }

package/dist/local-run.js

@@ -1,11 +1,9 @@
 import { spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
-import { PLAYWRIGHT_INSTALL_COMMANDS } from "./playwright-install.js";
-// We invoke @playwright/test as an external rather than bundling it — the CLI's zero-runtime-dep
-// rule. In a node_modules install `playwright` is on PATH; otherwise fall back to `npx playwright`,
-// exactly as the cloud runner does. The install commands come from playwright-install.ts so the
-// hint text and the actual installer never drift apart.
+import { installHint, PLAYWRIGHT_INSTALL_COMMANDS, resolvePlaywrightRunner, } from "./playwright-install.js";
+// @playwright/test is invoked as an external, never bundled — the CLI's zero-runtime-dep rule.
+// The install commands come from playwright-install.ts so hint and installer never drift apart.
 export const PLAYWRIGHT_INSTALL_HINT = "Local Playwright not found. Install it in this project, then re-run:\n" +
     `  ${PLAYWRIGHT_INSTALL_COMMANDS}`;
 // Isolate the run from any playwright.config.ts in the customer's repo: a stray `testMatch`
@@ -51,25 +49,36 @@ function runProcess(command, args, cwd, env) {
         child.on("close", (code) => resolve({ code, stdout, stderr }));
     });
 }
-// `npx playwright` is the portable fallback when no local binary is on PATH — it resolves
-// the project's @playwright/test without us hard-coding a node_modules path.
-function playwrightBase(cwd) {
-    const binName = process.platform === "win32" ? "playwright.cmd" : "playwright";
-    const local = path.join(cwd, "node_modules", ".bin", binName);
-    if (fs.existsSync(local))
-        return { command: local, args: ["test"] };
+// Resolved from the run dir — the exact place the spec imports from — so the process we
+// spawn and the module the spec loads are the same copy. `npx playwright` is the last
+// resort for a CLI install that somehow lost its dependencies.
+export function playwrightBase(runDir) {
+    const runner = resolvePlaywrightRunner(runDir);
+    if (runner?.source === "project") {
+        return { command: process.execPath, args: [runner.cli, "test"], label: "playwright test" };
+    }
+    if (runner) {
+        return {
+            command: process.execPath,
+            args: [runner.cli, "test"],
+            label: "playwright test (bundled with the CLI)",
+            nodePath: path.resolve(path.dirname(runner.cli), "..", ".."),
+        };
+    }
     const npx = process.platform === "win32" ? "npx.cmd" : "npx";
-    return { command: npx, args: ["playwright", "test"] };
+    return { command: npx, args: ["playwright", "test"], label: "npx playwright test" };
 }
 // "unknown command 'test'" is the Python `playwright` shim (no `test` subcommand); the module
-// errors mean @playwright/test isn't installed. Either way the actionable answer is the same
-// install hint, not a stack trace.
+// errors mean @playwright/test isn't installed; "Executable doesn't exist" is the runner
+// launching a browser revision that was never downloaded. Either way the actionable answer
+// is the same install hint, not a stack trace.
 function looksLikePlaywrightMissing(r) {
     if (r.spawnError?.code === "ENOENT")
         return true;
     const blob = `${r.stdout}\n${r.stderr}`;
     return (/unknown command ['"]?test/i.test(blob) ||
         /Cannot find module ['"]@playwright\/test/i.test(blob) ||
+        /Executable doesn't exist/i.test(blob) ||
         /npm ERR!.*could not determine executable|npx.*not found/i.test(blob));
 }
 export function parsePlaywrightReport(data) {
@@ -249,12 +258,15 @@ export async function runSpecLocally(opts) {
     fs.writeFileSync(configPath, ISOLATING_CONFIG(runDir, artifactsDir));
     const reportPath = path.join(runDir, "report.json");
     const cleanup = () => fs.rmSync(runDir, { recursive: true, force: true });
-    const { command, args: base } = playwrightBase(cwd);
+    const { command, args: base, label, nodePath } = playwrightBase(runDir);
     const args = [...base, `--config=${configPath}`, "--reporter=json"];
-    opts.onProgress?.(`Running ${command} ${base.join(" ")} on ${opts.testName}…`);
+    opts.onProgress?.(`Running ${label} on ${opts.testName}…`);
     await opts.setup?.(runDir);
     const stop = opts.during?.(runDir);
     const env = { ...process.env, PLAYWRIGHT_JSON_OUTPUT_NAME: reportPath };
+    if (nodePath) {
+        env.NODE_PATH = [nodePath, process.env.NODE_PATH].filter(Boolean).join(path.delimiter);
+    }
     // cwd is the RUN dir, not the project: the spec's relative writes (frames/,
     // email-inbox.json, dom-snapshot.html, phase.json) must land where we harvest and
     // clean up, exactly as the cloud runner keys them to its per-run workdir.
@@ -267,7 +279,7 @@ export async function runSpecLocally(opts) {
     }
     if (looksLikePlaywrightMissing(result)) {
         cleanup();
-        throw new PlaywrightMissingError(PLAYWRIGHT_INSTALL_HINT);
+        throw new PlaywrightMissingError(installHint(cwd));
     }
     let results;
     try {

package/dist/playwright-install.js

@@ -12,15 +12,57 @@ export const PLAYWRIGHT_INSTALL_COMMANDS = `${INSTALL_TEST_RUNNER.join(" ")} &&
 // 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) {
+// @playwright/test is a dependency of the CLI, so a repo needs nothing installed to run
+// locally: the runner comes with `npx @beryl-so/cli`, and only the browser is per-machine.
+// A repo's own @playwright/test still wins when present (its version, its browser revision).
+const cliRequire = createRequire(import.meta.url);
+// cli.js is the package's bin, not an export, so it is located via package.json.
+function runnerAt(pkgPath, source) {
+    const { version } = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+    return { cli: path.join(path.dirname(pkgPath), "cli.js"), version, source };
+}
+function projectRunner(dir) {
     try {
-        projectRequire(cwd).resolve("@playwright/test");
-        return true;
+        return runnerAt(projectRequire(dir).resolve("@playwright/test/package.json"), "project");
     }
     catch {
-        return false;
+        return undefined;
+    }
+}
+function bundledRunner() {
+    try {
+        return runnerAt(cliRequire.resolve("@playwright/test/package.json"), "bundled");
+    }
+    catch {
+        return undefined;
     }
 }
+// The single answer to "which @playwright/test": what `import "@playwright/test"` from `dir`
+// resolves to (any ancestor's node_modules), else the bundled copy. Runner and spec must load
+// the same one or Playwright refuses to run ("did not expect test.use() to be called here").
+export function resolvePlaywrightRunner(dir) {
+    return projectRunner(dir) ?? bundledRunner();
+}
+export const bundledRunnerCli = () => bundledRunner()?.cli;
+// By hand, the browser must be fetched for the runner that will launch it: the repo's own
+// (`npx playwright` resolves it) or, in a bare repo, the CLI's pinned version. An unpinned
+// `npx playwright install` there downloads the registry's latest revision, which is not it.
+export function browserInstallCommand(cwd) {
+    const bundled = bundledRunner();
+    if (hasPlaywrightTest(cwd) || !bundled)
+        return INSTALL_CHROMIUM.join(" ");
+    const [npx, pkg, ...rest] = INSTALL_CHROMIUM;
+    return [npx, `${pkg}@${bundled.version}`, ...rest].join(" ");
+}
+function bundledCoreDir() {
+    try {
+        return path.dirname(cliRequire.resolve("playwright-core/package.json"));
+    }
+    catch {
+        return undefined;
+    }
+}
+export const hasPlaywrightTest = (cwd) => projectRunner(cwd) !== undefined;
 // 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.
@@ -89,7 +131,7 @@ const isComplete = (dir) => fs.existsSync(path.join(dir, INSTALL_MARKER));
  * problem that reads as a broken suite.
  */
 export function hasChromiumBrowser(cwd) {
-    const coreDir = playwrightCoreDir(cwd);
+    const coreDir = hasPlaywrightTest(cwd) ? playwrightCoreDir(cwd) : bundledCoreDir();
     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.
@@ -110,7 +152,7 @@ export function hasChromiumBrowser(cwd) {
     }
 }
 export function playwrightGaps(cwd) {
-    const runner = !hasPlaywrightTest(cwd);
+    const runner = !hasPlaywrightTest(cwd) && !bundledRunnerCli();
     // 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) };
@@ -122,10 +164,10 @@ export function describeGaps(gaps) {
     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) {
+export function installCommandsFor(gaps, cwd = process.cwd()) {
     const commands = [
         ...(gaps.runner ? [INSTALL_TEST_RUNNER.join(" ")] : []),
-        ...(gaps.browser ? [INSTALL_CHROMIUM.join(" ")] : []),
+        ...(gaps.browser ? [browserInstallCommand(cwd)] : []),
     ];
     return commands.length > 0 ? commands.join(" && ") : PLAYWRIGHT_INSTALL_COMMANDS;
 }
@@ -160,10 +202,19 @@ function runInherit(command, args, cwd) {
  * the browser binary — an installed runner with no browser still fails a real run.
  */
 export async function installPlaywright(cwd, onStep) {
-    if (!hasPlaywrightTest(cwd)) {
+    const bundled = bundledRunnerCli();
+    if (!hasPlaywrightTest(cwd) && !bundled) {
         onStep?.(`Installing @playwright/test — ${INSTALL_TEST_RUNNER.join(" ")}`);
         await runInherit(INSTALL_TEST_RUNNER[0], INSTALL_TEST_RUNNER.slice(1), cwd);
     }
-    onStep?.(`Installing the Chromium browser — ${INSTALL_CHROMIUM.join(" ")}`);
+    onStep?.(`Installing the Chromium browser — ${browserInstallCommand(cwd)}`);
+    if (!hasPlaywrightTest(cwd) && bundled) {
+        await runInherit(process.execPath, [bundled, ...INSTALL_CHROMIUM.slice(2)], cwd);
+        return;
+    }
     await runInherit(INSTALL_CHROMIUM[0], INSTALL_CHROMIUM.slice(1), cwd);
 }
+export function installHint(cwd, gaps = playwrightGaps(cwd)) {
+    const commands = installCommandsFor(gaps, cwd);
+    return `Local runs need ${describeGaps(gaps)}. Install it, then re-run:\n  ${commands}`;
+}

package/dist/telemetry.js

@@ -233,6 +233,24 @@ export function createPostHogClient() {
     posthog ??= new PostHog(POSTHOG_KEY, { host: POSTHOG_HOST, disableGeoip: false });
     return posthog;
 }
+// `beryl init` starts before there is an account to attribute to: its events land on the
+// process session id, and the session is aliased onto the account once init has signed in,
+// so the install joins the same person as the signup and the later MCP work.
+export function captureCliEvent(event, apiUrl, properties = {}) {
+    createPostHogClient().capture({
+        distinctId: sessionId,
+        event,
+        properties: { ...baseEventProperties(apiUrl), ...properties },
+    });
+}
+export function aliasSessionToAccount(userId) {
+    createPostHogClient().alias({ distinctId: userId, alias: sessionId });
+}
+export function flushTelemetry() {
+    // Fire-and-forget: init keeps running (login, installs) while the batch goes out, and a
+    // failed send must never surface to the user.
+    void posthog?.flush().catch(() => { });
+}
 export function analyticsOptions(apiUrl, identify) {
     const properties = baseEventProperties(apiUrl);
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beryl-so/cli",
-  "version": "0.34.0",
+  "version": "0.34.3",
   "description": "Beryl on the command line — projects, runs, the exploring agent, and an MCP server over the same commands.",
   "license": "MIT",
   "type": "module",
@@ -32,11 +32,11 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "@playwright/test": "^1.61.1",
     "@posthog/mcp": "^0.11.6",
     "posthog-node": "^5.49.1"
   },
   "devDependencies": {
-    "@playwright/test": "^1.61.1",
     "@types/node": "^26.1.1",
     "tsx": "^4.23.1",
     "typescript": "^7.0.2",