@homespunapps/cli 1.0.0 → 1.4.2

package/dist/commands/register.js

@@ -1,59 +1,58 @@
-// `homespun agent register` — self-provision an agent API key from the relay.
+// `homespun agent register` - provision an agent API key from the relay.
 //
 // This is the one command that needs no API key: it is the call that obtains
-// one. If the relay runs REGISTRATION_MODE=secret, pass the shared
-// registration secret via --secret or HOMESPUN_REGISTER_SECRET. On success the key
-// (and relay URL) are persisted under a named profile in the CLI config file,
-// so every later command works with only HOMESPUN_URL (or nothing) set.
+// one. Two paths:
+//
+//   DEVICE FLOW (default) - RFC 8628 style browser approval. The CLI asks the
+//   relay for a device_code + user_code pair, prints a verification URL the
+//   human can open on ANY device, and polls until the human approves. The
+//   resulting agent is already OWNED by the approving human (no separate
+//   `homespun agent claim` step needed).
+//
+//   DIRECT (fallback) - plain POST /v1/register, the pre-device-flow path.
+//   Used when the relay 404s the device endpoints (older relay), when a
+//   registration secret is supplied (REGISTRATION_MODE=secret relays), or on
+//   --no-device. Direct-registered agents are unowned until claimed.
+//
+// On success the key (and relay URL) are persisted under a named profile in
+// the CLI config file, so every later command works with only HOMESPUN_URL (or
+// nothing) set.
+import { hostname } from "node:os";
 import { registerAgent, HomespunApiError } from "@homespunapps/core";
 import { assertKnownFlags } from "../argv.js";
+import { specFor } from "../help-catalog.js";
 import { DEFAULT_RELAY_URL } from "../config.js";
+import { runDeviceFlow } from "../device-flow.js";
 import { printJson, fail, failUpgradeRequired } from "../output.js";
 import { isValidProfileName, DEFAULT_PROFILE_NAME, readStore, resolveProfile, upsertProfile, } from "../store.js";
 import { VERSION } from "../version.js";
-const KNOWN_FLAGS = ["name", "secret"];
-const KNOWN_BOOLS = ["print-key"];
-export const registerHelp = `homespun agent register — register this agent with the relay and save the key locally
-
-Usage:
-  homespun agent register [options]
-
-Calls POST /v1/register, then saves the returned API key (and relay URL) under
-a named profile in the CLI config file — so afterwards every other command
-works with only HOMESPUN_URL set (no HOMESPUN_API_KEY needed).
-
-If --profile is omitted, the registered key goes under the currently-active
-profile (or 'default' for a fresh install). Pass --profile <name> to keep
-multiple environments (dev/staging/prod) side by side; switch between them
-with 'homespun config use <name>' or '--profile <name>' / HOMESPUN_PROFILE.
-
-Options:
-  --name <n>          Agent display name on the relay. The relay defaults it
-                      if omitted.
-  --profile <name>    Local profile name to save under. Defaults to the active
-                      profile, or 'default' on a fresh install. Letters,
-                      digits, _ and -, up to 32 chars.
-  --url <url>         Relay base URL. Falls back to HOMESPUN_URL, then the active
-                      profile, then the hosted Homespun relay. Self-hosters set
-                      this.
-  --secret <s>        Registration secret, sent as a Bearer token. Only needed
-                      when the relay uses REGISTRATION_MODE=secret. Falls back
-                      to the HOMESPUN_REGISTER_SECRET env var.
-  --print-key         Also echo the full api_key in the output. By default the
-                      key is only persisted to the config file, never printed.
-  -h, --help          Show this help.
-
-Output (stdout, JSON):
-  { agent_id, key_prefix, profile, saved_to }   (+ api_key when --print-key)
-
-The API key is saved to the CLI config file (mode 0600); it is not printed
-unless --print-key is passed.`;
+/**
+ * Default agent name for the device flow: the consent screen must name what
+ * the human is approving, so an unnamed agent gets "cli-<hostname>" instead
+ * of the relay's unhelpful generic default. Control characters are stripped
+ * and the result clamped to the relay's 64-char cap.
+ */
+export function defaultDeviceAgentName(host = hostname()) {
+    let cleaned = "";
+    for (const ch of host.trim()) {
+        const codePoint = ch.codePointAt(0) ?? 0;
+        if (codePoint <= 0x1f || (codePoint >= 0x7f && codePoint <= 0x9f))
+            continue;
+        cleaned += ch;
+    }
+    const name = `cli-${cleaned}`.slice(0, 64).trim();
+    return name.length > "cli-".length ? name : "cli-agent";
+}
+/** Compute the display prefix of an API key, mirroring the relay's rule. */
+function apiKeyPrefix(key) {
+    return key.startsWith("hs_") ? key.slice(0, 9) : key.slice(0, 8);
+}
 export async function runRegister(args) {
-    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "homespun agent register");
+    assertKnownFlags(args, ...specFor("agent", "register"));
     // Profile selection for the WRITE side: --profile flag → HOMESPUN_PROFILE env
     // → the store's current profile → DEFAULT_PROFILE_NAME ('default') for
     // a fresh install. We deliberately don't fall through to "no profile, use
-    // a fresh name" — the agent needs to end up somewhere callable, and
+    // a fresh name" - the agent needs to end up somewhere callable, and
     // 'default' is a stable, predictable home.
     const profileFlag = args.flags.get("profile") ?? process.env.HOMESPUN_PROFILE;
     const store = readStore();
@@ -61,7 +60,7 @@ export async function runRegister(args) {
         ? profileFlag
         : (store.currentProfile ?? DEFAULT_PROFILE_NAME);
     if (!isValidProfileName(profileName)) {
-        fail(`invalid profile name '${profileName}' — letters, digits, _ and -, up to 32 chars`, "invalid_args");
+        fail(`invalid profile name '${profileName}' - letters, digits, _ and -, up to 32 chars`, "invalid_args");
     }
     // URL precedence for the relay we're registering against:
     //   --url flag > HOMESPUN_URL env > target-profile's existing url > default.
@@ -74,21 +73,70 @@ export async function runRegister(args) {
         activeUrl = active?.profile.url;
     }
     catch {
-        // Selector didn't resolve — fine on register: we're about to create it.
+        // Selector didn't resolve - fine on register: we're about to create it.
         activeUrl = undefined;
     }
-    const url = args.flags.get("url") ??
+    const url = (args.flags.get("url") ??
         process.env.HOMESPUN_URL ??
         activeUrl ??
-        DEFAULT_RELAY_URL;
+        DEFAULT_RELAY_URL).replace(/\/$/, "");
     const name = args.flags.get("name");
     const secret = args.flags.get("secret") ??
         process.env.HOMESPUN_REGISTER_SECRET ??
         undefined;
+    // The device flow is the default. A registration secret implies a
+    // REGISTRATION_MODE=secret relay whose operator hands out direct access,
+    // and --no-device is the explicit opt-out (CI, headless-with-no-human).
+    const wantDevice = !args.bools.has("no-device") && (secret === undefined || secret === "");
+    if (wantDevice) {
+        try {
+            const outcome = await runDeviceFlow({
+                url,
+                name: name ?? defaultDeviceAgentName(),
+                cliVersion: VERSION,
+            });
+            if (outcome.supported) {
+                const savedTo = upsertProfile(profileName, { url, apiKey: outcome.agent_key }, true);
+                const out = {
+                    agent_id: outcome.agent_id,
+                    key_prefix: apiKeyPrefix(outcome.agent_key),
+                    profile: profileName,
+                    saved_to: savedTo,
+                    registered_via: "device",
+                };
+                if (args.bools.has("print-key")) {
+                    out["api_key"] = outcome.agent_key;
+                }
+                printJson(out);
+                return;
+            }
+            // 404 on /v1/device/code: an older relay. Fall through to the direct
+            // path with a note so the behavior change is visible, not silent.
+            process.stderr.write("note: this relay does not support browser approval (older relay); " +
+                "falling back to direct registration. The agent will need " +
+                "'homespun agent claim <code>' to get an owner.\n");
+        }
+        catch (e) {
+            if (e instanceof HomespunApiError) {
+                if (e.status === 426 && e.code === "cli_upgrade_required") {
+                    failUpgradeRequired(e);
+                }
+                if (e.status === 429) {
+                    fail("device authorization rate limit exceeded - try again later", "rate_limited", undefined, { hint: e.hint, retryable: true, docs_url: e.docsUrl });
+                }
+                fail(e.message, e.code, e.details, {
+                    hint: e.hint,
+                    retryable: e.retryable,
+                    docs_url: e.docsUrl,
+                });
+            }
+            fail(e instanceof Error ? e.message : String(e), "internal");
+        }
+    }
     let result;
     try {
         result = await registerAgent({
-            url: url.replace(/\/$/, ""),
+            url,
             ...(name !== undefined ? { name } : {}),
             ...(secret !== undefined && secret !== "" ? { secret } : {}),
             cliVersion: VERSION,
@@ -103,7 +151,7 @@ export async function runRegister(args) {
                 failUpgradeRequired(e);
             }
             if (e.status === 429) {
-                fail("registration rate limit exceeded — try again later", "rate_limited", undefined, { hint: e.hint, retryable: e.retryable, docs_url: e.docsUrl });
+                fail("registration rate limit exceeded - try again later", "rate_limited", undefined, { hint: e.hint, retryable: e.retryable, docs_url: e.docsUrl });
             }
             fail(e.message, e.code, e.details, {
                 hint: e.hint,
@@ -117,12 +165,13 @@ export async function runRegister(args) {
     // registered against this relay, so the only sensible follow-up is to
     // start using it. The previous behaviour (one global URL+key) is exactly
     // the single-profile case of this.
-    const savedTo = upsertProfile(profileName, { url: url.replace(/\/$/, ""), apiKey: result.api_key }, true);
+    const savedTo = upsertProfile(profileName, { url, apiKey: result.api_key }, true);
     const out = {
         agent_id: result.agent_id,
         key_prefix: result.key_prefix,
         profile: profileName,
         saved_to: savedTo,
+        registered_via: "direct",
     };
     if (args.bools.has("print-key")) {
         out["api_key"] = result.api_key;

package/dist/commands/set-key.js

@@ -8,39 +8,9 @@
 // than guessing here and adding a network hop for what's a local config
 // write.
 import { assertKnownFlags } from "../argv.js";
+import { specFor } from "../help-catalog.js";
 import { isValidProfileName, DEFAULT_PROFILE_NAME, readStore, resolveProfile, upsertProfile, } from "../store.js";
 import { printJson, fail } from "../output.js";
-const KNOWN_FLAGS = ["url"];
-const KNOWN_BOOLS = [];
-export const setKeyHelp = `homespun agent set-key <api-key> — save a new API key to the local config
-
-Usage:
-  homespun agent set-key <api-key> [--url <url>] [--profile <name>]
-
-After regenerating an agent's API key in the relay's My-agents UI, run
-this on the agent's machine to land the new key in the CLI config file
-(\${XDG_CONFIG_HOME:-~/.config}/homespun/config.json, mode 0600). Every later
-command then works with no HOMESPUN_API_KEY env var.
-
-The key is saved under the ACTIVE profile (unless --profile picks a different
-one). To add a brand-new profile by hand (e.g. for an out-of-band key from a
-closed-registration relay), use 'homespun config add'.
-
-If you'd rather not touch the config file at all, set the new key as the
-HOMESPUN_API_KEY env var on the agent process — both work.
-
-Options:
-  --url <url>         Also update the saved relay URL on the target profile.
-                      Useful when pointing the agent at a different relay
-                      alongside the key swap.
-  --profile <name>    Target this profile instead of the active one. Created
-                      if it doesn't exist.
-  -h, --help          Show this help.
-
-Output (stdout, JSON):
-  { saved_to, profile, key_prefix }
-
-The key is never echoed back. To verify, run \`homespun key list\` afterwards.`;
 function keyPrefixOf(key) {
     // Match the relay's keyPrefix() display width for "hs_" + 6 hex chars
     // (11 total). Falls back to the first 8 chars for any unrecognised shape.
@@ -49,7 +19,7 @@ function keyPrefixOf(key) {
     return key.slice(0, 8);
 }
 export async function runSetKey(args) {
-    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "homespun agent set-key");
+    assertKnownFlags(args, ...specFor("agent", "set-key"));
     const apiKey = args.positionals[0];
     if (!apiKey) {
         fail("missing api-key — usage: homespun agent set-key <api-key>", "invalid_args");

package/dist/commands/skill.js

@@ -20,46 +20,10 @@
 // an agent on a too-old CLI must be able to read the upgrade instructions
 // even before it has registered (or before its key was minted).
 import { assertKnownFlags } from "../argv.js";
+import { specFor } from "../help-catalog.js";
 import { resolveRelayUrl } from "../config.js";
 import { fail } from "../output.js";
-const NO_FLAGS = [];
-const NO_BOOLS = [];
-const VERSION_BOOLS = ["plain"];
 import { VERSION } from "../version.js";
-export const skillHelp = `homespun skill — fetch the relay's SKILL.md (or its version)
-
-Usage:
-  homespun skill show                     Print the full skill to stdout.
-  homespun skill version [--plain]        Print just the relay's skill version.
-
-The skill is auto-updating: the relay's deployed image owns the version,
-so this is always the skill that matches the relay you are talking to.
-
-Unauthenticated — no API key needed. An agent can call either form
-before 'homespun agent register' to bootstrap or refresh its local skill copy.
-
-Verbs:
-  show                Fetch GET /skills/homespun/SKILL.md and write the raw
-                      markdown to stdout. Pipe to your local skill path:
-                          homespun skill show > ~/.claude/skills/homespun/SKILL.md
-  version             Fetch GET /skills/homespun/SKILL.md/version and print
-                      the relay's skill version. Default output is the
-                      JSON envelope; --plain prints just the version
-                      string so an agent can compare it inline in shell.
-
-Options:
-  --plain             (with 'version' only) print the bare version
-                      string on stdout, no JSON envelope. Useful inside
-                      a shell pipeline: \`if [ "$(homespun skill version
-                      --plain)" != "$LOCAL" ]; then ...\`.
-  --url <url>         Relay base URL (overrides HOMESPUN_URL).
-  -h, --help          Show this help.
-
-Output (stdout):
-  (bare)              Raw markdown, as served by the relay.
-  version             { "version": "1.0.0" } — or '1.0.0\\n' with --plain.
-
-Errors (stderr): { "error": { "code", "message" } } and non-zero exit.`;
 // Shared fetch with the consistent x-homespun-cli-version header (the skill
 // routes are exempt from the version-skew middleware, but sending it lets
 // access logs see which CLI versions are reading the skill).
@@ -84,7 +48,7 @@ async function failOnNon2xx(res, target) {
 }
 // `homespun skill show` — print the full skill.
 async function runSkillFetch(args) {
-    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "homespun skill show");
+    assertKnownFlags(args, ...specFor("skill", "show"));
     const url = resolveRelayUrl(args);
     const target = url + "/skills/homespun/SKILL.md";
     const res = await fetchOrFail(target);
@@ -99,7 +63,7 @@ async function runSkillFetch(args) {
 }
 // `homespun skill version [--plain]` — print just the version.
 async function runSkillVersion(args) {
-    assertKnownFlags(args, NO_FLAGS, VERSION_BOOLS, "homespun skill version");
+    assertKnownFlags(args, ...specFor("skill", "version"));
     const url = resolveRelayUrl(args);
     const target = url + "/skills/homespun/SKILL.md/version";
     const res = await fetchOrFail(target);

package/dist/commands/taste.js

@@ -19,54 +19,9 @@
 // when app gains first-class humans, this may move to per-human.
 import { readFileSync } from "node:fs";
 import { assertKnownFlags } from "../argv.js";
+import { specFor } from "../help-catalog.js";
 import { makeClient } from "../config.js";
 import { printJson, fail, failFromError } from "../output.js";
-const NO_FLAGS = [];
-const NO_BOOLS = [];
-const SET_FLAGS = ["file"];
-const CLEAR_BOOLS = ["yes"];
-export const tasteHelp = `homespun taste — read / write / clear YOUR agent's UI taste notes
-
-Taste notes are a small markdown attachment storing presentation preferences your
-agent has picked up from human feedback ("denser table", "no rounded corners",
-"use a dark header"). Read them before generating an app template so prior
-feedback shapes the output; rewrite them whenever the human gives new
-presentation feedback. Keep entries about UI/presentation taste only — not
-project context, todos, or homespun state.
-
-Usage:
-  homespun taste <subcommand> [options]
-
-Subcommands:
-  get        Print the current notes attachment:
-             { taste: string|null, updated_at: string|null, bytes: number }.
-             taste is null and bytes is 0 when notes have never been written.
-
-  set        Whole-attachment replace. Source the markdown via --file <path>,
-             --file - (read stdin), or by piping into 'homespun taste set' with
-             no flag. The relay rejects empty/whitespace-only payloads and
-             caps the attachment at MAX_TASTE_BYTES (utf8). To clear the notes,
-             use 'homespun taste clear', not 'set' with an empty body.
-
-  clear      Delete the notes. Requires --yes (it is destructive). Prints
-             { cleared: true }.
-
-Options:
-  --file <path|->     Source for 'set' — a file path, or '-' to read stdin
-                      explicitly. Omit to fall back to piped stdin.
-  --yes               Confirm 'clear'.
-  --url <url>         Relay base URL (overrides HOMESPUN_URL).
-  --api-key <key>     Agent API key (overrides HOMESPUN_API_KEY).
-  -h, --help          Show this help.
-
-Examples:
-  homespun taste get
-  homespun taste set --file ./taste.md
-  homespun taste set --file -            # explicit stdin
-  echo "- denser layout" | homespun taste set
-  homespun taste clear --yes
-
-Output: stdout is machine-readable JSON.`;
 // Drain process.stdin to a utf8 string. The caller is responsible for
 // deciding that stdin should be read (e.g. an explicit `--file -`, or a
 // non-TTY stdin where data is actually piped). In a TTY this would block
@@ -79,7 +34,7 @@ async function readStdin() {
     return Buffer.concat(chunks).toString("utf8");
 }
 async function runTasteGet(args) {
-    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "homespun taste get");
+    assertKnownFlags(args, ...specFor("taste", "get"));
     const client = makeClient(args);
     try {
         const info = await client.getTaste();
@@ -90,7 +45,7 @@ async function runTasteGet(args) {
     }
 }
 async function runTasteSet(args) {
-    assertKnownFlags(args, SET_FLAGS, NO_BOOLS, "homespun taste set");
+    assertKnownFlags(args, ...specFor("taste", "set"));
     const filePath = args.flags.get("file");
     // Source the attachment deterministically — no isTTY-flag fusing, because
     // `!process.stdin.isTTY` is true under every non-interactive caller
@@ -131,7 +86,7 @@ async function runTasteSet(args) {
     }
 }
 async function runTasteClear(args) {
-    assertKnownFlags(args, NO_FLAGS, CLEAR_BOOLS, "homespun taste clear");
+    assertKnownFlags(args, ...specFor("taste", "clear"));
     if (!args.bools.has("yes")) {
         fail("'homespun taste clear' deletes YOUR agent's taste notes — it is destructive. Pass --yes to confirm.", "confirmation_required");
     }

package/dist/device-flow.js

@@ -0,0 +1,162 @@
+// Device-authorization registration (RFC 8628 style) - the browser-approval
+// path behind `homespun agent register`.
+//
+// The CLI asks the relay for a device_code + user_code pair, prints the
+// verification URL + code for the human (who can open it on ANY device),
+// and polls POST /v1/device/token until the human approves, denies, or the
+// codes expire. On approval the relay creates an agent OWNED by the
+// approving human and returns its key exactly once.
+//
+// Everything human-facing goes to stderr - stdout stays reserved for the
+// final JSON envelope, like every other command. fetch/sleep/print are
+// injectable so the polling loop is unit-testable with a mocked relay.
+import { HomespunApiError } from "@homespunapps/core";
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function defaultPrint(line) {
+    process.stderr.write(line + "\n");
+}
+/** POST JSON, returning { status, body } with the body parsed best-effort. */
+async function postJson(fetchImpl, url, body, cliVersion) {
+    const headers = {
+        "content-type": "application/json",
+    };
+    if (cliVersion !== undefined && cliVersion !== "") {
+        headers["x-homespun-cli-version"] = cliVersion;
+    }
+    let res;
+    try {
+        res = await fetchImpl(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+        });
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        throw new HomespunApiError(0, "fetch_error", msg);
+    }
+    const text = await res.text().catch(() => "");
+    let parsed = null;
+    if (text !== "") {
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            parsed = null;
+        }
+    }
+    return { status: res.status, body: parsed };
+}
+/** The relay-envelope error code/message, when the body carries one. */
+function envelopeError(body) {
+    const err = body?.error;
+    if (err && typeof err === "object") {
+        const e = err;
+        return {
+            code: typeof e.code === "string" ? e.code : "relay_error",
+            message: typeof e.message === "string" ? e.message : "relay error",
+        };
+    }
+    return null;
+}
+/** The RFC 8628 error string ({ error: "authorization_pending" }), if any. */
+function rfcErrorCode(body) {
+    const err = body?.error;
+    return typeof err === "string" ? err : null;
+}
+/**
+ * Run the device-authorization flow end to end. Returns `supported: false`
+ * when the relay 404s the code request (an older relay - the caller falls
+ * back to plain POST /v1/register). Throws HomespunApiError on every other
+ * failure, including denial and expiry, with actionable codes:
+ *
+ *   device_flow_denied    the human clicked Deny
+ *   device_flow_expired   nobody approved within the code's lifetime
+ */
+export async function runDeviceFlow(opts) {
+    const base = opts.url.replace(/\/$/, "");
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const sleep = opts.sleepImpl ?? defaultSleep;
+    const print = opts.print ?? defaultPrint;
+    // ---- 1. Request the code pair -----------------------------------------
+    const start = await postJson(fetchImpl, `${base}/v1/device/code`, { name: opts.name }, opts.cliVersion);
+    if (start.status === 404) {
+        // Older relay without the device flow - signal the caller to fall back.
+        return { supported: false };
+    }
+    if (start.status !== 200) {
+        const env = envelopeError(start.body);
+        throw new HomespunApiError(start.status, env?.code ?? "relay_error", env?.message ?? `relay returned ${start.status} for /v1/device/code`);
+    }
+    const code = start.body;
+    if (!code ||
+        typeof code.device_code !== "string" ||
+        typeof code.user_code !== "string" ||
+        typeof code.verification_uri_complete !== "string") {
+        throw new HomespunApiError(200, "invalid_response", "relay returned an unexpected /v1/device/code body");
+    }
+    // ---- 2. Hand the human their marching orders ---------------------------
+    const expiresMin = Math.max(1, Math.round((code.expires_in ?? 900) / 60));
+    print("");
+    print("To approve this agent, open:");
+    print("");
+    print(`    ${code.verification_uri_complete}`);
+    print("");
+    print(`and confirm the code:  ${code.user_code}`);
+    print("");
+    print("You can open the link on any device (phone or laptop) and sign in there.");
+    print(`Waiting for approval... (expires in ${expiresMin} min; Ctrl-C to abort)`);
+    // ---- 3. Poll until a terminal answer -----------------------------------
+    let intervalSeconds = typeof code.interval === "number" && code.interval > 0 ? code.interval : 5;
+    const deadline = Date.now() + (code.expires_in ?? 900) * 1000;
+    while (Date.now() < deadline) {
+        await sleep(intervalSeconds * 1000);
+        // Re-check after sleeping: don't fire a poll we already know is past
+        // the code's lifetime (the relay would just answer expired_token).
+        if (Date.now() >= deadline)
+            break;
+        const poll = await postJson(fetchImpl, `${base}/v1/device/token`, { device_code: code.device_code }, opts.cliVersion);
+        if (poll.status === 200) {
+            const body = poll.body;
+            if (typeof body?.agent_key !== "string" ||
+                typeof body?.agent_id !== "string") {
+                throw new HomespunApiError(200, "invalid_response", "relay returned an unexpected /v1/device/token body");
+            }
+            print("Approved.");
+            return {
+                supported: true,
+                agent_id: body.agent_id,
+                agent_key: body.agent_key,
+                name: typeof body.name === "string" ? body.name : opts.name,
+            };
+        }
+        const rfc = rfcErrorCode(poll.body);
+        if (poll.status === 400 && rfc !== null) {
+            switch (rfc) {
+                case "authorization_pending":
+                    continue;
+                case "slow_down":
+                    // RFC 8628 §3.5: add 5 seconds to the interval and keep going.
+                    intervalSeconds += 5;
+                    continue;
+                case "access_denied":
+                    throw new HomespunApiError(400, "device_flow_denied", "the approval request was denied in the browser");
+                case "expired_token":
+                    throw new HomespunApiError(400, "device_flow_expired", "the device code expired before it was approved - run 'homespun agent register' again");
+                default:
+                    throw new HomespunApiError(400, rfc, `relay rejected the poll (${rfc})`);
+            }
+        }
+        if (poll.status === 429) {
+            // Transient general rate limit - back off like a slow_down and retry.
+            intervalSeconds += 5;
+            continue;
+        }
+        // 426 cli_upgrade_required and anything else: surface the envelope.
+        const env = envelopeError(poll.body);
+        throw new HomespunApiError(poll.status, env?.code ?? "relay_error", env?.message ?? `relay returned ${poll.status} for /v1/device/token`, poll.body?.error?.details);
+    }
+    throw new HomespunApiError(400, "device_flow_expired", "the device code expired before it was approved - run 'homespun agent register' again");
+}