@beryl-so/cli 0.22.0 → 0.24.1

package/dist/commands/accounts.js

@@ -172,9 +172,10 @@ export const testAccountCommands = [
             "--probe is the liveness check: a two-step plan (goto a gated page, then a POSITIVE " +
             "assertion that only holds when signed in — the account menu, a 'Sign out' control). " +
             "It is replayed in a fresh browser carrying only the captured session. It is " +
-            "REQUIRED, and not a formality: assertions like `hidden` and `count 0` all pass " +
-            "against a logged-out page, so without a positive signal a dead session would run " +
-            "every test logged-out and still report the run green.\n\n" +
+            "REQUIRED, and not a formality: assertions like `hidden`, `count 0`, and a URL " +
+            "match on a redirect all pass against a logged-out page, so without a positive " +
+            "signal a dead session would run every test logged-out and still report the run " +
+            "green.\n\n" +
             "Storing only stores. Run `beryl accounts check` to prove it against the live app.",
         scope: "project",
         args: [
@@ -264,8 +265,10 @@ export const testAccountCommands = [
             "itself did not complete (fix the plan); SESSION_PROOF_FAILED means the sign-in " +
             "worked but the session did not survive the move to a fresh browser, so this app " +
             "keeps its credential somewhere that cannot be carried (a service worker, a " +
-            "WebAuthn binding). In that case the account is marked unsupported and its tests " +
-            "keep signing in inline — degraded, not broken.\n\n" +
+            "WebAuthn binding). In that case the account is marked unsupported: its " +
+            "session-mode tests fail at setup with SESSION_UNSUPPORTED on every run until " +
+            "re-authored with auth_mode \"inline\" and their own sign-in steps; inline tests " +
+            "are unaffected.\n\n" +
             "Blocks for two browser replays.",
         scope: "project",
         args: [{ name: "account-id", description: "Account id", required: true }],

package/dist/commands/auth.js

@@ -1,6 +1,7 @@
 import { execFileSync } from "node:child_process";
 import os from "node:os";
 import { saveGlobalConfig } from "../config.js";
+import { deviceLogin, SWITCH_TO_OTP } from "../device-login.js";
 import { CliError, UsageError } from "../errors.js";
 import { ApiClient } from "../http.js";
 import { dim, green } from "../output.js";
@@ -48,18 +49,67 @@ export async function promptForOtpCode(ctx) {
         throw new UsageError("No valid 6-digit code entered");
     return code;
 }
+// The emailed-code flow, returning a raw PAT. With a --code the email already has a
+// code, so nothing is sent (and check-email is skipped entirely).
+async function otpLogin(ctx, input, codeFlag) {
+    const apiUrl = ctx.client.baseUrl;
+    const email = flagStr(input, "email") ?? (await promptForEmail(ctx));
+    if (!email.includes("@"))
+        throw new UsageError(`"${email}" is not an email address`);
+    const anon = new ApiClient(apiUrl);
+    let code = codeFlag;
+    if (!code) {
+        const check = (await anon.post("/auth/check-email", { email }));
+        if (!check.exists) {
+            await anon.post("/auth/signup", { email });
+            ctx.err(dim(`No Beryl account for ${email} yet — creating one. Sent a 6-digit code to ${email}`));
+        }
+        else if ((check.auth_methods ?? []).includes("otp")) {
+            await anon.post("/auth/request-login-otp", { email });
+            ctx.err(dim(`Sent a 6-digit code to ${email}`));
+        }
+        else {
+            const why = `${email} signs in with Google, so there is no emailed code`;
+            if (!ctx.interactive) {
+                throw new UsageError(`${why} — run \`beryl login\` in a terminal to sign in via the browser, ` +
+                    "or pass --token with a token from beryl.so → Account → API tokens");
+            }
+            ctx.err(`${why} — confirm the sign-in in your browser instead.`);
+            const fromBrowser = await deviceLogin(ctx, process.stdin, flagStr(input, "token-name"));
+            if (fromBrowser === SWITCH_TO_OTP)
+                throw new UsageError(why);
+            return fromBrowser;
+        }
+        code = await promptForOtpCode(ctx);
+    }
+    const login = (await anon.post("/auth/verify-otp", { email, code }));
+    if (!login.access_token)
+        throw new CliError("Login did not return an access token");
+    const session = new ApiClient(apiUrl, login.access_token);
+    const minted = (await session.post("/account/tokens", {
+        name: flagStr(input, "token-name") ?? `CLI on ${os.hostname()}`,
+    }));
+    return minted.token;
+}
 export const authCommands = [
     {
         name: "login",
         summary: "Authenticate the CLI with your Beryl account",
-        description: "Signs in with an emailed one-time code and mints a personal access token, " +
-            "which is stored in the CLI config. Pass --token to use an existing token " +
-            "from Account → API tokens instead. Pass --email plus --code (the 6 digits " +
-            "from the email, e.g. read from a `beryl inbox`) to complete the OTP flow " +
-            "without a prompt. In CI, prefer the BERYL_API_KEY environment variable.",
+        description: "Signs in via your browser (a code you confirm at beryl.so) and stores a personal " +
+            "access token in the CLI config. Pass --otp (or --email) to skip the browser and " +
+            "sign in with an emailed one-time code instead — a new email gets an account " +
+            "created automatically. Pass --token to use an existing token from Account → API " +
+            "tokens. Pass --email plus --code (the 6 digits from the email, e.g. read from a " +
+            "`beryl inbox`) to complete the OTP flow without a prompt. In CI, prefer the " +
+            "BERYL_API_KEY environment variable.",
         interactive: true,
         flags: [
             { name: "token", type: "string", description: "Use an existing personal access token" },
+            {
+                name: "otp",
+                type: "boolean",
+                description: "Skip the browser — sign in with an emailed code",
+            },
             {
                 name: "email",
                 type: "string",
@@ -81,6 +131,7 @@ export const authCommands = [
         ],
         examples: [
             "beryl login",
+            "beryl login --otp",
             "beryl login --token beryl_pat_…",
             "beryl login --email you@example.com",
             "beryl login --email agent@example.com --code 123456 --json",
@@ -96,26 +147,22 @@ export const authCommands = [
                     if (!flagStr(input, "email"))
                         throw new UsageError("--code requires --email");
                 }
-                const email = flagStr(input, "email") ?? (await promptForEmail(ctx));
-                if (!email.includes("@"))
-                    throw new UsageError(`"${email}" is not an email address`);
-                const anon = new ApiClient(apiUrl);
-                let code = codeFlag;
-                if (!code) {
-                    await anon.post("/auth/request-login-otp", { email });
-                    ctx.err(dim(`Sent a 6-digit code to ${email}`));
-                    ctx.err(dim("Not arriving? Check spam; if you're new to Beryl, sign up at https://beryl.so first — " +
-                        "or use `beryl login --token` with a token from beryl.so → Account → API tokens."));
-                    code = await promptForOtpCode(ctx);
+                // Guard before any network call — the OTP flow's check-email/signup would create
+                // a real account and send an email before dying on the interactive code prompt.
+                if (!ctx.interactive && codeFlag === undefined) {
+                    throw new UsageError("Cannot prompt for a code without a terminal — pass --email with --code, " +
+                        "--token, or set BERYL_API_KEY");
+                }
+                const wantsOtp = flagBool(input, "otp") ||
+                    flagStr(input, "email") !== undefined ||
+                    codeFlag !== undefined;
+                if (!wantsOtp && ctx.interactive) {
+                    const fromBrowser = await deviceLogin(ctx, process.stdin, flagStr(input, "token-name"));
+                    token = fromBrowser === SWITCH_TO_OTP ? await otpLogin(ctx, input) : fromBrowser;
+                }
+                else {
+                    token = await otpLogin(ctx, input, codeFlag);
                 }
-                const login = (await anon.post("/auth/verify-otp", { email, code }));
-                if (!login.access_token)
-                    throw new CliError("Login did not return an access token");
-                const session = new ApiClient(apiUrl, login.access_token);
-                const minted = (await session.post("/account/tokens", {
-                    name: flagStr(input, "token-name") ?? `CLI on ${os.hostname()}`,
-                }));
-                token = minted.token;
             }
             const authed = new ApiClient(apiUrl, token);
             const me = (await authed.get("/account/"));
@@ -240,4 +287,13 @@ export const authCommands = [
             return { human: "Revoked." };
         },
     },
+    {
+        name: "tokens dismiss",
+        summary: "Remove an already-revoked token from your list",
+        args: [{ name: "token-id", description: "Token id from `beryl tokens list`", required: true }],
+        async run(ctx, input) {
+            await ctx.client.post(`/account/tokens/${arg(input, "token-id")}/dismiss`, {});
+            return { human: "Dismissed." };
+        },
+    },
 ];

package/dist/commands/config-vars.js

@@ -57,6 +57,9 @@ export const configCommands = [
     {
         name: "config vars get",
         summary: "Show one config variable",
+        description: "Returns the variable row with its value in plaintext (variables are not secret) — " +
+            "a sensitive value lives in `config secrets`, readable only via `config secrets " +
+            "get --reveal`.",
         scope: "project",
         args: [{ name: "key", description: "Variable key or id", required: true }],
         async run(ctx, input) {
@@ -113,6 +116,8 @@ export const configCommands = [
     {
         name: "config secrets get",
         summary: "Show one secret's metadata, or reveal its value with --reveal",
+        description: "Returns metadata only by default; --reveal is a logged, member-gated decrypt — " +
+            "unlike `config vars get`, which returns its value in plaintext.",
         scope: "project",
         args: [{ name: "key", description: "Secret key or id", required: true }],
         flags: [

package/dist/commands/init.js

@@ -4,7 +4,7 @@ import os from "node:os";
 import path from "node:path";
 import { BERYL_TEST_SKILL, BERYL_TEST_SKILL_DIR, BERYL_TEST_SKILL_FILENAME, } from "../beryl-test-skill.js";
 import { loadConfig } from "../config.js";
-import { CliError } from "../errors.js";
+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";
@@ -148,7 +148,8 @@ export const initCommands = [
     {
         name: "init",
         summary: "Set up Beryl in this repo — sign in and wire up your coding agent",
-        description: "One-command onboarding: signs you in (emailed one-time code) and wires up your coding " +
+        description: "One-command onboarding: signs you in (browser confirm, or an emailed one-time code) " +
+            "and wires up your coding " +
             "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 " +
@@ -186,17 +187,33 @@ export const initCommands = [
         async run(ctx, input) {
             const cwd = process.cwd();
             let { client, config } = ctx;
-            if (config.token) {
-                const me = (await client.get("/account/"));
-                ctx.err(`${green("✓")} Signed in as ${me.email}`);
-            }
-            else {
+            const signIn = async () => {
+                // Non-interactive skips the picker and lets `login` fail with its own
+                // "interactive input required" message, exactly as before.
+                const answer = ctx.interactive
+                    ? 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: {} });
+                await login.run(ctx, { args: {}, flags: answer.trim() === "2" ? { otp: true } : {} });
                 config = loadConfig();
                 if (!config.token)
                     throw new CliError("Login did not persist a token");
                 client = new ApiClient(config.apiUrl, config.token);
+            };
+            if (config.token) {
+                try {
+                    const me = (await client.get("/account/"));
+                    ctx.err(`${green("✓")} Signed in as ${me.email}`);
+                }
+                catch (err) {
+                    if (!(err instanceof AuthError))
+                        throw err;
+                    ctx.err(yellow("Your session token is invalid or expired."));
+                    await signIn();
+                }
+            }
+            else {
+                await signIn();
             }
             const scope = (flagStr(input, "scope") ?? "user");
             const report = (label, fresh, where) => ctx.err(`${green("✓")} ${label} ${fresh ? "configured" : "already configured"} ${dim(where)}`);
@@ -268,8 +285,8 @@ export const initCommands = [
         description: "The full guide to authoring durable, healable tests: the ActionPlan shape, outcome " +
             "assertions, natural-language intent, test accounts and the project mailbox " +
             "({{login_email}}, {{mailbox_address}}, {{inbox_address}} + await_email), and the " +
-            "local run-fix loop. The same content `beryl init` installs as the beryl-test " +
-            "skill — call this before authoring your first plan when no skill is installed " +
+            "local run-fix loop. Same content as the beryl-test skill `beryl init` installs — " +
+            `skip if a loaded beryl-test skill states v${cliVersion()}; else call this first ` +
             "(works without logging in).",
         examples: ["beryl guide"],
         async run() {

package/dist/commands/mailboxes.js

@@ -91,7 +91,9 @@ export const mailboxCommands = [
             "the server caps the wait at 50s — re-run to keep waiting). With --extract-code, " +
             "also pulls the one-time code (4-8 digits) out of the body/subject. Use " +
             "--recipient-contains to read only one `+tag` alias's mail when several identities " +
-            "share the mailbox. Exits non-zero if nothing arrives before the timeout.",
+            "share the mailbox. Exits non-zero if nothing arrives before the timeout. Waits for " +
+            "and returns ONE latest matching email — `mailbox emails` lists what has already " +
+            "arrived, without waiting.",
         scope: "project",
         args: [{ name: "mailbox-id", description: "Mailbox id from `beryl mailbox list`", required: true }],
         flags: [
@@ -139,6 +141,8 @@ export const mailboxCommands = [
     {
         name: "mailbox emails",
         summary: "List the emails a mailbox has received",
+        description: "Returns the already-received emails without waiting — `mailbox read` blocks for " +
+            "a matching one and returns just it.",
         scope: "project",
         args: [{ name: "mailbox-id", description: "Mailbox id from `beryl mailbox list`", required: true }],
         flags: [

package/dist/commands/runs.js

@@ -102,17 +102,19 @@ export const runCommands = [
             "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 " +
+            "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 " +
+            "the fetched spec and 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 " +
+            "does, and scrubbed from any error text or DOM snapshot before results upload; a test " +
+            "whose account has no stored password is skipped with the exact fix-it command. 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. 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 " +
+            "captured server-side is skipped, with a note — run those with `runs trigger`. 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",
@@ -134,7 +136,12 @@ export const runCommands = [
                 type: "string",
                 description: "Run against this base URL instead of the environment's (e.g. http://localhost:3000)",
             },
-            { name: "env", type: "string", description: "Environment id to attach the imported run to" },
+            {
+                name: "env",
+                type: "string",
+                description: "Environment id to run against and attach the imported run to — use for a " +
+                    "standing environment; --url-override is for a throwaway host",
+            },
             {
                 name: "sync",
                 type: "boolean",
@@ -464,7 +471,9 @@ export const runCommands = [
         summary: "Show one run with its per-test results",
         description: "Over MCP the failure screenshots come back as viewable image content, so an agent can " +
             "look at the page that broke instead of guessing from the error string. Set screenshots " +
-            "to false to skip fetching them. Ignored outside MCP — the terminal cannot show an image.",
+            "to false to skip fetching them. Ignored outside MCP — the terminal cannot show an image. " +
+            "Returns the run row with its per-test results — `runs report` returns the generated " +
+            "report document, `runs explain` an AI explanation of one failed result.",
         scope: "project",
         args: [{ name: "run-id", description: "Run id", required: true }],
         flags: [
@@ -516,6 +525,8 @@ export const runCommands = [
     {
         name: "runs report",
         summary: "Show the generated report for a run",
+        description: "Returns the run's stored generated report (404 until it has been generated) — " +
+            "`runs get` returns the raw run row with per-test results.",
         scope: "project",
         args: [{ name: "run-id", description: "Run id", required: true }],
         async run(ctx, input) {
@@ -595,6 +606,8 @@ export const runCommands = [
     {
         name: "runs explain",
         summary: "Explain, with AI, why a test result failed",
+        description: "Takes a single test-RESULT id (not a run id) and returns an AI failure " +
+            "explanation for that result — `runs get` lists a run's results and their ids.",
         scope: "project",
         args: [{ name: "result-id", description: "Test result id (from `beryl runs get`)", required: true }],
         async run(ctx, input) {

package/dist/commands/tests.js

@@ -128,6 +128,9 @@ export const testCommands = [
     {
         name: "tests get",
         summary: "Show one test",
+        description: "Returns the test's metadata row (status, flags, per-environment last result), not " +
+            "the plan — `tests plan` prints the stored JSON plan, `tests script` the rendered " +
+            "Playwright spec.",
         scope: "project",
         args: [{ name: "test-id", description: "Test id", required: true }],
         async run(ctx, input) {
@@ -138,6 +141,8 @@ export const testCommands = [
     {
         name: "tests plan",
         summary: "Print a test's current step plan (JSON)",
+        description: "Returns the stored json_plan of the test's current version — `tests get` returns " +
+            "the metadata row, `tests script` the rendered Playwright spec.",
         scope: "project",
         args: [{ name: "test-id", description: "Test id", required: true }],
         async run(ctx, input) {
@@ -164,11 +169,16 @@ export const testCommands = [
             "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 " +
             "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 " +
+            "back to server-side verification automatically, and says so. 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.",
+            "cleans up the record it made on the runs that go red. " +
+            "Recovery: a 409 `duplicate_title` carries existing_test_id + existing_plan_hash — " +
+            "reconcile with that test (`tests get` / `tests set-plan`), don't rename-and-retry; a " +
+            "409 `plan_hash_mismatch` means the submitted plan is not the bytes that were replayed " +
+            "— re-run `tests create`; a 429 with Retry-After 30 means the verify slots are " +
+            "saturated — wait and retry.",
         scope: "project",
         flags: [
             { name: "title", type: "string", required: true, description: "Title for the new test" },
@@ -421,7 +431,9 @@ export const testCommands = [
         description: "Accepts the same plan shape as `tests create`, including the optional `before` and " +
             "`after` sections — `after` runs on pass and on fail, so cleanup happens even when the " +
             "test goes red. Pass `--description` when the re-authored plan changes what the test " +
-            "proves; omit it to keep the test's existing intent.",
+            "proves; omit it to keep the test's existing intent. Saves the edit with NO replay — " +
+            "it rides into the next run unproven; `tests recompile` is the verify-first " +
+            "alternative.",
         scope: "project",
         args: [{ name: "test-id", description: "Test id", required: true }],
         flags: [
@@ -464,9 +476,12 @@ export const testCommands = [
         name: "tests quarantine",
         summary: "Mute a flaky test: it keeps running, but its failures stop failing the run",
         description: "A quarantined test still executes and its result is still recorded and visible — its " +
-            "red just doesn't count towards the run's verdict, so it can't red-light a deploy. Use " +
+            "red lands in the run's quarantined_count and gates neither the run's verdict nor exit " +
+            "codes, so it can't red-light a deploy. Use " +
             "it on a persistently flaky test instead of deleting it (which destroys the history) or " +
-            "asking support to deactivate it (which stops it running at all). `off` un-quarantines.",
+            "asking support to deactivate it (which stops it running at all). After 5 consecutive " +
+            "clean passes the test reports rehab_ready — advisory only, nothing un-quarantines " +
+            "itself. `off` un-quarantines.",
         scope: "project",
         args: [
             { name: "test-id", description: "Test id", required: true },
@@ -501,6 +516,13 @@ export const testCommands = [
     {
         name: "tests recompile",
         summary: "Validate + verify an edited plan against the live site before persisting",
+        description: "Unlike `tests set-plan` (which saves the edit and lets it ride into the next run), " +
+            "this replays the edited plan against the live site before anything persists. A " +
+            "deterministic replay failure (verdict `drop`) REJECTS the edit — persisted:false, " +
+            "the prior plan stays live — and returns the failure evidence (over MCP the " +
+            "screenshot is image content). Verdict `flag` (the runner errored, no verdict on " +
+            "the flow) persists the plan but reports it unverified. Returns 429 with " +
+            "Retry-After 30 when the 2 inline-verify slots are saturated — wait and retry.",
         scope: "project",
         args: [{ name: "test-id", description: "Test id", required: true }],
         flags: [
@@ -569,6 +591,9 @@ export const testCommands = [
     {
         name: "tests restore",
         summary: "Restore a test to an earlier version",
+        description: "Copies the named older version's plan forward as a NEW head version — unlike " +
+            "`tests reset`, which flips authored_by back to `system` and leaves the plan " +
+            "untouched.",
         scope: "project",
         args: [
             { name: "test-id", description: "Test id", required: true },
@@ -584,6 +609,9 @@ export const testCommands = [
     {
         name: "tests reset",
         summary: "Discard user edits and return the test to its latest system-authored version",
+        description: "Flips authored_by back to `system` WITHOUT changing the plan (the next " +
+            "regeneration overwrites it) — unlike `tests restore`, which copies an older " +
+            "version's plan forward as a new version.",
         scope: "project",
         args: [{ name: "test-id", description: "Test id", required: true }],
         async run(ctx, input) {
@@ -632,7 +660,9 @@ export const testCommands = [
         summary: "Print the rendered Playwright spec for a test (or an unbanked plan file)",
         description: "With a test id, fetches the banked test's rendered .spec.ts. With --file, compiles a " +
             "plan JSON that has NOT been banked yet — the same render `tests create` proves locally — " +
-            "so you can inspect exactly what would run before creating anything.",
+            "so you can inspect exactly what would run before creating anything. This returns the " +
+            "executable spec — `tests plan` returns the stored JSON plan it is rendered from, " +
+            "`tests get` the metadata row.",
         scope: "project",
         args: [{ name: "test-id", description: "Test id (omit when passing --file)" }],
         flags: [

package/dist/device-login.js

@@ -0,0 +1,132 @@
+import { spawn } from "node:child_process";
+import os from "node:os";
+import { CliError } from "./errors.js";
+import { ApiClient, ApiError } from "./http.js";
+import { dim } from "./output.js";
+/** Returned when the user presses Enter to fall back to the emailed-code flow. */
+export const SWITCH_TO_OTP = Symbol("switch-to-otp");
+function openBrowser(url) {
+    const [cmd, args] = process.platform === "darwin"
+        ? ["open", [url]]
+        : process.platform === "win32"
+            ? ["cmd", ["/c", "start", "", url]]
+            : ["xdg-open", [url]];
+    try {
+        const child = spawn(cmd, args, { detached: true, stdio: "ignore" });
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch {
+        // no browser is fine — the URL is printed for copy-paste
+    }
+}
+/** Browser device-code sign-in: opens beryl.so, polls until the user confirms the code
+ *  there, and resolves to the raw PAT — or to SWITCH_TO_OTP on Enter. */
+export async function deviceLogin(ctx, stdin = process.stdin, tokenName) {
+    const anon = new ApiClient(ctx.client.baseUrl);
+    const start = (await anon.post("/auth/cli/start", {
+        token_name: tokenName ?? `CLI on ${os.hostname()}`,
+    }));
+    openBrowser(start.verification_url);
+    ctx.err(start.verification_url);
+    ctx.err(`Confirm this code in the browser: ${start.user_code}`);
+    ctx.err(dim("Press Enter to sign in with an emailed code instead"));
+    let timer;
+    let onData;
+    let done = false;
+    try {
+        return await new Promise((resolve, reject) => {
+            let interval = start.interval;
+            let failures = 0;
+            let pollInFlight = false;
+            let switchRequested = false;
+            const finish = (token) => {
+                done = true;
+                resolve(token);
+            };
+            const fail = (err) => {
+                done = true;
+                reject(err);
+            };
+            const switchToOtp = () => {
+                done = true;
+                resolve(SWITCH_TO_OTP);
+            };
+            onData = (chunk) => {
+                if (!/[\r\n]/.test(chunk.toString()))
+                    return;
+                if (done || switchRequested)
+                    return;
+                // An in-flight poll may already be approved server-side (the session is consumed);
+                // its result must win or the minted token is lost forever.
+                if (pollInFlight)
+                    switchRequested = true;
+                else
+                    switchToOtp();
+            };
+            stdin.on("data", onData);
+            stdin.resume();
+            const poll = async () => {
+                pollInFlight = true;
+                let res;
+                try {
+                    res = (await anon.post("/auth/cli/poll", {
+                        device_code: start.device_code,
+                    }));
+                }
+                catch (err) {
+                    pollInFlight = false;
+                    if (done)
+                        return;
+                    if (switchRequested) {
+                        switchToOtp();
+                    }
+                    else if (++failures >= 5) {
+                        fail(err);
+                    }
+                    else {
+                        if (err instanceof ApiError && err.status === 429)
+                            interval *= 2;
+                        timer = setTimeout(() => void poll(), interval * 1000);
+                    }
+                    return;
+                }
+                pollInFlight = false;
+                failures = 0;
+                if (done)
+                    return;
+                if (res.status === "approved" && res.token) {
+                    if (switchRequested)
+                        ctx.err("Already approved in the browser — signed in");
+                    finish(res.token);
+                }
+                else if (switchRequested) {
+                    switchToOtp();
+                }
+                else if (res.status === "approved") {
+                    fail(new CliError("Sign-in approved but no token was returned — try again"));
+                }
+                else if (res.status === "denied") {
+                    fail(new CliError("Sign-in was denied in the browser"));
+                }
+                else if (res.status !== "pending") {
+                    fail(new CliError("The sign-in request expired — run `beryl login` again"));
+                }
+                else {
+                    timer = setTimeout(() => void poll(), interval * 1000);
+                }
+            };
+            timer = setTimeout(() => void poll(), interval * 1000);
+        });
+    }
+    finally {
+        // Both racers are torn down whichever wins — a live timer or stdin listener would
+        // keep the process alive after login.
+        done = true;
+        if (timer)
+            clearTimeout(timer);
+        if (onData)
+            stdin.off("data", onData);
+        stdin.pause();
+    }
+}