@botbuddy/cli 1.39.0 → 1.40.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbuddy/cli",
-  "version": "1.39.0",
+  "version": "1.40.0",
   "description": "BotBuddy — Swarm coordination CLI for multi-agent workflows",
   "type": "module",
   "bin": {

package/src/auth.mjs

@@ -10,6 +10,13 @@ import {
   DEFAULT_LOGIN_TIMEOUT_MS,
   OAuthCallbackError,
 } from "./oauth-loopback.mjs";
+import {
+  DEVICE_CODE_GRANT_TYPE,
+  REQUESTING_HOST_MAX,
+  requestDeviceAuthorization,
+  pollDeviceToken,
+} from "./oauth-device.mjs";
+import { hostname as osHostname } from "node:os";
 
 // A login that could not complete. commands.mjs turns this into one terminal
 // error line; the core never calls process.exit so it stays unit-testable.
@@ -48,11 +55,72 @@ function callbackErrorMessage(err) {
   }
 }
 
+// BOT-2030: one actionable terminal message per device-flow failure.
+export const DEVICE_UNSUPPORTED_MESSAGE = "This server does not support device sign-in yet; use `--loopback` with an SSH tunnel";
+function deviceErrorMessage(err) {
+  if (!(err instanceof OAuthCallbackError)) {
+    return err?.message || "Device sign-in failed";
+  }
+  switch (err.code) {
+    case "expired_token":
+      return "The code expired before it was approved. Re-run `botbuddy login`.";
+    case "access_denied":
+      return "The sign-in was denied in the browser.";
+    case "device_unsupported":
+      return DEVICE_UNSUPPORTED_MESSAGE;
+    case "canceled":
+      return "Login canceled.";
+    case "invalid_grant":
+      return "The sign-in code is no longer valid. Re-run `botbuddy login`.";
+    default:
+      return `Device sign-in failed: ${err.message}`;
+  }
+}
+
+// Store a minted owner token. The ONE storage path for both login flows.
+async function storeOwnerToken(tokenData, { clientId, now, persist, getConfig, saveConfig, log, errorLog }) {
+  const expiresAt = tokenData.expires_in
+    ? now() + tokenData.expires_in * 1000
+    : now() + 24 * 60 * 60 * 1000; // default 24h if server omits expires_in
+
+  // BOT-1520: the durable secret goes to the Keychain (darwin); config.json
+  // keeps only non-secret metadata. On a non-darwin host without a Keychain,
+  // persistOwnerToken falls back to the 0600 config.json and warns.
+  // BOT-1566: a Keychain read-back mismatch (`keychain_readback_mismatch`)
+  // propagates from here, so login exits non-zero and the success line below
+  // is never printed for a credential that did not verifiably land.
+  // BOT-1571: record the token's scope. A server that predates tenant modes
+  // omits `tenant_mode`; such a token is sealed (or legacy), never assumed
+  // to be a user token.
+  const tenantMode = tokenData.tenant_mode === "user" ? "user" : "tenant";
+  const tenantId = typeof tokenData.tenant_id === "string" && tokenData.tenant_id ? tokenData.tenant_id : null;
+  const tenants = Array.isArray(tokenData.tenants) ? tokenData.tenants.filter((t) => typeof t === "string" && t) : [];
+  const { storedInKeychain } = await persist(
+    { token: tokenData.access_token, expiresAt, clientId, tenantMode, tenantId, tenants },
+    { getConfig, saveConfig, warn: errorLog },
+  );
+
+  log(
+    `\n${green("✓")} Logged in successfully! Token stored in ${
+      storedInKeychain ? "the macOS Keychain" : dim("~/.botbuddy/config.json")
+    }.`,
+  );
+  if (tenantMode === "user") {
+    log(`  Token scope: ${cyan("user")} — works for every tenant you belong to${tenants.length ? ` (${tenants.join(", ")})` : ""}; each ${cyan("botbuddy mcp setup --tenant <slug>")} mints a key pinned to its own.`);
+  } else if (tenantId) {
+    log(`  Token scope: ${cyan("tenant")} — sealed to ${cyan(tenantId)}. Run ${cyan("botbuddy login")} without ${dim("--tenant")} for a token that reaches all your tenants.`);
+  }
+}
+
 // AC-1..AC-13: orchestrate the loopback authorization-code flow.
+// BOT-2030: `options.device === true` runs the device flow instead (the
+// command layer decides with shouldUseDeviceFlow, so this core stays
+// deterministic for callers and tests that never ask for it).
 //
-// options: { noBrowser, tenant }
+// options: { noBrowser, tenant, device, caller, callerHarness, callerTicket }
 // deps (all injectable for tests): serverUrl, fetch, openBrowser, saveConfig,
-//   getConfig, log, errorLog, timeoutMs, now.
+//   getConfig, log, errorLog, timeoutMs, now, persist; device mode also takes
+//   sleep, hostname, isTTY, exit, createReceiver.
 export async function doLogin(options = {}, deps = {}) {
   const {
     serverUrl = SERVER_URL,
@@ -65,7 +133,11 @@ export async function doLogin(options = {}, deps = {}) {
     timeoutMs = DEFAULT_LOGIN_TIMEOUT_MS,
     now = () => Date.now(),
     persist = persistOwnerToken,
+    createReceiver = createLoopbackReceiver,
   } = deps;
+  if (options.device === true) {
+    return doDeviceLogin(options, { ...deps, serverUrl, fetchImpl, saveConfig, getConfig, log, errorLog, now, persist });
+  }
   const noBrowser = Boolean(options.noBrowser);
   // BOT-1566: optional tenant preselection (validated by the argument parser).
   const tenant = typeof options.tenant === "string" && options.tenant ? options.tenant : null;
@@ -84,7 +156,7 @@ export async function doLogin(options = {}, deps = {}) {
 
   // AC-1/AC-2: start the loopback listener BEFORE registration or browser launch,
   // on 127.0.0.1 with an OS-assigned ephemeral port.
-  const receiver = createLoopbackReceiver({ expectedState: state });
+  const receiver = createReceiver({ expectedState: state });
   const { redirectUri } = await receiver.listen();
 
   // AC-11: Ctrl-C must close the listener and exit non-zero without saving.
@@ -160,37 +232,7 @@ export async function doLogin(options = {}, deps = {}) {
     if (!tokenData.access_token) throw new LoginError(`Token exchange failed: ${describeResponse(tokenData)}`);
     log(`  ${green("✓")} Access token received`);
 
-    const expiresAt = tokenData.expires_in
-      ? now() + tokenData.expires_in * 1000
-      : now() + 24 * 60 * 60 * 1000; // default 24h if server omits expires_in
-
-    // BOT-1520: the durable secret goes to the Keychain (darwin); config.json
-    // keeps only non-secret metadata. On a non-darwin host without a Keychain,
-    // persistOwnerToken falls back to the 0600 config.json and warns.
-    // BOT-1566: a Keychain read-back mismatch (`keychain_readback_mismatch`)
-    // propagates from here, so login exits non-zero and the success line below
-    // is never printed for a credential that did not verifiably land.
-    // BOT-1571: record the token's scope. A server that predates tenant modes
-    // omits `tenant_mode`; such a token is sealed (or legacy), never assumed
-    // to be a user token.
-    const tenantMode = tokenData.tenant_mode === "user" ? "user" : "tenant";
-    const tenantId = typeof tokenData.tenant_id === "string" && tokenData.tenant_id ? tokenData.tenant_id : null;
-    const tenants = Array.isArray(tokenData.tenants) ? tokenData.tenants.filter((t) => typeof t === "string" && t) : [];
-    const { storedInKeychain } = await persist(
-      { token: tokenData.access_token, expiresAt, clientId, tenantMode, tenantId, tenants },
-      { getConfig, saveConfig, warn: errorLog },
-    );
-
-    log(
-      `\n${green("✓")} Logged in successfully! Token stored in ${
-        storedInKeychain ? "the macOS Keychain" : dim("~/.botbuddy/config.json")
-      }.`,
-    );
-    if (tenantMode === "user") {
-      log(`  Token scope: ${cyan("user")} — works for every tenant you belong to${tenants.length ? ` (${tenants.join(", ")})` : ""}; each ${cyan("botbuddy mcp setup --tenant <slug>")} mints a key pinned to its own.`);
-    } else if (tenantId) {
-      log(`  Token scope: ${cyan("tenant")} — sealed to ${cyan(tenantId)}. Run ${cyan("botbuddy login")} without ${dim("--tenant")} for a token that reaches all your tenants.`);
-    }
+    await storeOwnerToken(tokenData, { clientId, now, persist, getConfig, saveConfig, log, errorLog });
     return { clientId, redirectUri };
   } finally {
     // AC-11/AC-13: always release the socket so re-running login starts clean.
@@ -198,3 +240,96 @@ export async function doLogin(options = {}, deps = {}) {
     await receiver.close();
   }
 }
+
+// BOT-2030: the device authorization grant (RFC 8628). No loopback listener
+// and no browser launch on this host: print the link + code, poll /token, then
+// store through the same storeOwnerToken as the loopback flow.
+async function doDeviceLogin(options, deps) {
+  const {
+    serverUrl, fetchImpl, saveConfig, getConfig, log, errorLog, now, persist,
+    sleep,
+    hostname = osHostname,
+    isTTY = Boolean(process.stdout.isTTY),
+    exit = (code) => process.exit(code),
+  } = deps;
+  const tenant = typeof options.tenant === "string" && options.tenant ? options.tenant : null;
+  const pick = (v) => (typeof v === "string" && v ? v : null);
+
+  log(`${bold("BotBuddy OAuth Login")}\n`);
+
+  // Ctrl-C while waiting: store nothing, exit 130 (128 + SIGINT).
+  const abort = new AbortController();
+  const onSigint = () => {
+    abort.abort();
+    errorLog(`\n${red("✗")} Login canceled.`);
+    exit(130);
+  };
+  process.once("SIGINT", onSigint);
+
+  try {
+    log(dim("→ Registering client..."));
+    const regRes = await fetchImpl(`${serverUrl}/register`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        client_name: "botbuddy-cli-node",
+        grant_types: [DEVICE_CODE_GRANT_TYPE],
+        token_endpoint_auth_method: "none",
+      }),
+    });
+    const regData = await regRes.json().catch(() => ({}));
+    const clientId = regData.client_id;
+    if (!clientId) throw new LoginError(`Client registration failed: ${describeResponse(regData)}`);
+    log(`  ${green("✓")} Client registered: ${dim(clientId)}`);
+
+    let grant;
+    try {
+      grant = await requestDeviceAuthorization({
+        serverUrl,
+        clientId,
+        tenant,
+        caller: pick(options.caller),
+        callerHarness: pick(options.callerHarness),
+        callerTicket: pick(options.callerTicket),
+        requestingHost: String(hostname() ?? "").slice(0, REQUESTING_HOST_MAX),
+        fetch: fetchImpl,
+      });
+    } catch (err) {
+      throw new LoginError(deviceErrorMessage(err));
+    }
+
+    // The code is printed once, here, and nowhere else. With no TTY (piped
+    // stdout) it goes to stderr so a pipe never swallows the sign-in prompt.
+    const prompt = isTTY ? log : errorLog;
+    const minutes = Math.max(1, Math.round((Number(grant.expires_in) || 600) / 60));
+    prompt("");
+    prompt("→ Sign in on any device:");
+    prompt(`  ${grant.verification_uri_complete || grant.verification_uri}`);
+    prompt(`  Code: ${grant.user_code}   (expires in ${minutes} minute${minutes === 1 ? "" : "s"})`);
+    prompt("  Waiting for approval…");
+
+    let tokenData;
+    try {
+      tokenData = await pollDeviceToken({
+        serverUrl,
+        clientId,
+        deviceCode: grant.device_code,
+        intervalSec: Number(grant.interval),
+        expiresInSec: Number(grant.expires_in),
+        fetch: fetchImpl,
+        ...(sleep ? { sleep } : {}),
+        now,
+        signal: abort.signal,
+      });
+    } catch (err) {
+      throw new LoginError(deviceErrorMessage(err));
+    }
+    if (abort.signal.aborted) throw new LoginError(deviceErrorMessage(new OAuthCallbackError("canceled", "Login canceled")));
+    log(`  ${green("✓")} Approved — access token received`);
+
+    await storeOwnerToken(tokenData, { clientId, now, persist, getConfig, saveConfig, log, errorLog });
+    return { clientId, device: true };
+  } finally {
+    process.removeListener("SIGINT", onSigint);
+  }
+}

package/src/commands.mjs

@@ -4,6 +4,7 @@ import { execFileSync } from "node:child_process";
 import { join } from "node:path";
 import { callTool, callToolJson, readResource } from "./api.mjs";
 import { doLogin } from "./auth.mjs";
+import { shouldUseDeviceFlow } from "./oauth-device.mjs";
 import { runBridge } from "./codex-bridge.mjs";
 import { bootstrapHarnessSession, clearHarnessSession, doctorBootstrapState, formatBootstrapLine, loadHarnessSession, withHarnessBootstrapLock } from "./session-bootstrap.mjs";
 import { loadConfig, getConfig, clearConfig, getConfigPath, SERVER_URL } from "./config.mjs";
@@ -166,9 +167,9 @@ ${bold("OPTIONS")}
     --no-server              Don't auto-start codex app-server
 
 ${bold("AUTH")}
-  login [--no-browser] [--tenant <slug>] [--caller <name>] [--caller-harness <h>] [--caller-ticket <ref>]
-                             Authenticate via OAuth (opens browser + localhost callback)
-  setup [--no-browser] [--tenant <slug>]
+  login [--no-browser] [--tenant <slug>] [--device | --loopback] [--caller <name>] [--caller-harness <h>] [--caller-ticket <ref>]
+                             Authenticate via OAuth (browser + localhost callback; a device code over SSH)
+  setup [--no-browser] [--tenant <slug>] [--device | --loopback]
                              Bootstrap this bound worktree for variable-free waits
   logout                     Remove saved credentials
   status                     Show current auth status (local metadata + server check)
@@ -341,10 +342,23 @@ export function parseLoginArgs(args) {
     "--caller-harness": "callerHarness",
     "--caller-ticket": "callerTicket",
   };
+  // BOT-2030: `--device` forces the device sign-in, `--loopback` forces the
+  // browser + localhost callback. With neither, `out.device` stays absent and
+  // shouldUseDeviceFlow decides (device over SSH / on a display-less Linux).
+  let sawDevice = false;
+  let sawLoopback = false;
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     if (arg === "--help" || arg === "-h") { out.help = true; continue; }
     if (arg === "--no-browser") { out.noBrowser = true; continue; }
+    if (arg === "--device" || arg === "--loopback") {
+      if (arg === "--device") sawDevice = true; else sawLoopback = true;
+      if (sawDevice && sawLoopback) {
+        throw new LoginUsageError("error: --device and --loopback cannot be used together", { exitCode: 2 });
+      }
+      out.device = arg === "--device";
+      continue;
+    }
     if (arg === "--tenant" || arg.startsWith("--tenant=")) {
       const value = arg.startsWith("--tenant=") ? arg.slice("--tenant=".length) : args[++i];
       if (typeof value !== "string" || !TENANT_SLUG_RE.test(value)) {
@@ -463,7 +477,8 @@ async function cmdLogin(args, { errorLog = (line) => console.error(line) } = {})
   // BOT-1580: merge caller flags with the BOTBUDDY_CALLER* env fallback.
   const caller = resolveCaller(options, process.env);
   try {
-    await doLogin({ noBrowser: options.noBrowser, tenant: options.tenant, ...caller });
+    const device = shouldUseDeviceFlow({ env: process.env, platform: process.platform, flag: options.device });
+    await doLogin({ noBrowser: options.noBrowser, tenant: options.tenant, device, ...caller });
   } catch (err) {
     die(err.message);
   }
@@ -479,6 +494,7 @@ export async function cmdSetup(args, {
   usageAgent = installUsageAgent,
   cwd = process.cwd(),
   env = process.env,
+  platform = process.platform,
   log = (line) => console.log(line),
   errorLog = (line) => console.error(line),
 } = {}) {
@@ -491,7 +507,7 @@ export async function cmdSetup(args, {
     return error.exitCode === 2 ? 2 : 4;
   }
   if (options.help) {
-    log("bb setup [--no-browser] [--tenant <slug>]\n\nSigns in, verifies the committed .botbuddy-agent.json binding, and caches this worktree's session. After it succeeds, use `bb wait <condition>` with no credential flags or environment variables.");
+    log("bb setup [--no-browser] [--tenant <slug>] [--device | --loopback]\n\nSigns in, verifies the committed .botbuddy-agent.json binding, and caches this worktree's session. Over SSH the sign-in uses a device code you approve from any browser (--device / --loopback force a mode). After it succeeds, use `bb wait <condition>` with no credential flags or environment variables.");
     return 0;
   }
   let bound;
@@ -515,7 +531,11 @@ export async function cmdSetup(args, {
     // The committed binding below is the only place setup scopes the minted
     // session.  Forwarding --tenant here would overwrite a multi-tenant user's
     // reusable client key with a tenant-sealed one.
-    await login({ noBrowser: options.noBrowser, ...callerResolver(options, env) });
+    await login({
+      noBrowser: options.noBrowser,
+      device: shouldUseDeviceFlow({ env, platform, flag: options.device }),
+      ...callerResolver(options, env),
+    });
     // Setup is an explicit session bootstrap/repair command. Rotate before
     // resolving so it cannot merely report an old cache as ready.
     await clearState(cwd);
@@ -560,7 +580,7 @@ export function loginHelp(log = console.log) {
   log(`${bold("botbuddy login")} — authenticate via OAuth (browser + loopback callback)
 
 ${bold("USAGE")}
-  botbuddy login [--no-browser] [--tenant <slug>]
+  botbuddy login [--no-browser] [--tenant <slug>] [--device | --loopback]
                  [--caller <name>] [--caller-harness <harness>] [--caller-ticket <ref>]
 
 ${bold("TOKEN SCOPE")}
@@ -585,6 +605,11 @@ ${bold("OPTIONS")}
   --no-browser   Don't launch a browser; print the authorization URL to open
                  in a browser on THIS machine yourself. The callback listener
                  still runs on this machine's localhost.
+  --device       Sign in with a device code: print a link and a short code,
+                 approve it in a browser on ANY machine (laptop, phone), and
+                 the login finishes on its own. No browser or listener here.
+  --loopback     Force the browser + localhost callback flow, even over SSH.
+                 ${dim("--device and --loopback cannot be combined.")}
   --tenant <slug>
                  Mint a token SEALED to one tenant (e.g. ${cyan("supply-guard")}); the
                  sign-in page shows it as requested by the CLI. Must be a lowercase
@@ -611,12 +636,8 @@ ${bold("NOTES")}
     saves nothing.
   • If sign-in fails, just re-run ${cyan("botbuddy login")} — each attempt uses a fresh
     listener and state.
-  • ${bold("Remote / SSH:")} the callback URL is ${dim("http://127.0.0.1:<port>/callback")}, which
-    always points at the machine whose browser opens it. If you run login on a
-    remote host but sign in from your laptop's browser, first forward that exact
-    port back to the host, e.g. ${cyan("ssh -L <port>:127.0.0.1:<port> <host>")}
-    (the port is printed in the URL). Without the tunnel the callback can't
-    reach the listener and login will time out.
+  • ${bold("Remote / SSH:")} over SSH (or on Linux with no display) login uses the device
+    code automatically: open the printed link on any machine and approve.
 
 ${bold("RECOVERY")}
   If ${cyan("botbuddy status")} shows no client key, run ${cyan("botbuddy login")}. For an
@@ -642,10 +663,10 @@ async function cmdStart(args) {
     const agentKey = owner ? null : await resolveAgentKey();
     if (!owner && !agentKey) {
       console.log(dim("→ No credentials found. Starting login...\n"));
-      await doLogin({ ...caller });
+      await doLogin({ ...caller, device: shouldUseDeviceFlow({ env: process.env, platform: process.platform }) });
     } else if (owner && owner.expiresAt && owner.expiresAt <= Date.now() && !(await resolveAgentKey())) {
       console.log(dim("→ Token expired. Re-authenticating...\n"));
-      await doLogin({ ...caller });
+      await doLogin({ ...caller, device: shouldUseDeviceFlow({ env: process.env, platform: process.platform }) });
     }
   } catch (err) {
     die(err.message);

package/src/oauth-device.mjs

@@ -0,0 +1,163 @@
+// BOT-2030: the CLI half of the OAuth device authorization grant (RFC 8628),
+// served by BOT-2029. A host with no usable browser (an SSH session, a headless
+// Linux box) asks the server for a device code + a short user code, prints the
+// verification link, and polls /token while the operator approves the code from
+// the browser on whatever machine they are sitting at. No loopback listener, no
+// browser launch on this host.
+//
+// Everything here is dependency-free and injectable (fetch, sleep, clock) so the
+// poll loop is unit-testable without waiting.
+
+import { OAuthCallbackError, sanitizeCallerField, CALLER_FIELD_LIMITS } from "./oauth-loopback.mjs";
+
+export const DEVICE_CODE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
+
+// RFC 8628 §3.5: on slow_down the client adds 5 seconds to its interval.
+export const SLOW_DOWN_STEP_SEC = 5;
+// RFC 8628 §3.2: when the server omits `interval`, poll every 5 seconds.
+export const DEFAULT_POLL_INTERVAL_SEC = 5;
+// The approval screen shows the requesting host; keep it short.
+export const REQUESTING_HOST_MAX = 80;
+
+const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Should `login` use the device flow instead of the loopback browser flow?
+ * An explicit flag always wins (`--device` → true, `--loopback` → false);
+ * otherwise the device flow is used over SSH, and on Linux with no display.
+ */
+export function shouldUseDeviceFlow({ env = process.env, platform = process.platform, flag } = {}) {
+  if (flag === true) return true;
+  if (flag === false) return false;
+  if (env?.SSH_CONNECTION || env?.SSH_TTY) return true;
+  if (platform === "linux" && !env?.DISPLAY && !env?.WAYLAND_DISPLAY) return true;
+  return false;
+}
+
+/**
+ * POST <server>/device_authorization. Returns the parsed RFC 8628 §3.2 body
+ * (`device_code`, `user_code`, `verification_uri`, `verification_uri_complete`,
+ * `expires_in`, `interval`).
+ *
+ * Token scope mirrors the loopback `buildAuthorizeUrl`: a plain login asks for a
+ * USER token (`tenant_mode=user`); `--tenant <slug>` asks for one sealed to it.
+ *
+ * Throws OAuthCallbackError:
+ *   - `device_unsupported` when the server has no device route (a 404, or the
+ *     pre-BOT-2029 route table's JSON-RPC fall-through), so the caller can say
+ *     so instead of silently falling back to the loopback flow;
+ *   - the server's OAuth `error` code otherwise.
+ */
+export async function requestDeviceAuthorization({
+  serverUrl,
+  clientId,
+  scope = "read write lock",
+  tenant = null,
+  caller = null,
+  callerHarness = null,
+  callerTicket = null,
+  requestingHost = null,
+  fetch: fetchImpl = fetch,
+}) {
+  const body = { client_id: clientId, scope };
+  if (tenant) {
+    body.tenant_mode = "tenant";
+    body.tenant = tenant;
+  } else {
+    body.tenant_mode = "user";
+  }
+  // Display-only, unverified hints for the approval screen (BOT-1580 rules).
+  const callerName = sanitizeCallerField(caller, CALLER_FIELD_LIMITS.name);
+  const harness = sanitizeCallerField(callerHarness, CALLER_FIELD_LIMITS.harness);
+  const ticket = sanitizeCallerField(callerTicket, CALLER_FIELD_LIMITS.ticket);
+  if (callerName) body.caller = callerName;
+  if (harness) body.caller_harness = harness;
+  if (ticket) body.caller_ticket = ticket;
+  const host = sanitizeCallerField(requestingHost, REQUESTING_HOST_MAX);
+  if (host) body.requesting_host = host;
+
+  const res = await fetchImpl(`${serverUrl}/device_authorization`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  if (res.status === 404) {
+    throw new OAuthCallbackError("device_unsupported", "The server has no device authorization endpoint");
+  }
+  const data = await res.json().catch(() => null);
+  if (res.ok && data && typeof data.device_code === "string" && typeof data.user_code === "string" && typeof data.verification_uri === "string") {
+    return data;
+  }
+  if (data && typeof data.error === "string" && data.error) {
+    throw new OAuthCallbackError(data.error, data.error_description || data.error);
+  }
+  // No OAuth error code: not a device-grant endpoint at all (an older server
+  // answers the unknown path from its JSON-RPC handler).
+  throw new OAuthCallbackError("device_unsupported", "The server did not answer as a device authorization endpoint");
+}
+
+/**
+ * Poll POST <server>/token with the device code until the operator decides.
+ *
+ * Waits `intervalSec` before every request. `authorization_pending` → keep
+ * polling; `slow_down` → +5 s on the interval, keep polling. `access_denied`,
+ * `expired_token` and `invalid_grant` (and any other failure) throw an
+ * OAuthCallbackError carrying that code. Gives up with `expired_token` once
+ * `expiresInSec` has passed, without another request. An aborted `signal`
+ * (Ctrl-C) stops with `canceled` before the next request.
+ *
+ * Returns the token response body.
+ */
+export async function pollDeviceToken({
+  serverUrl,
+  clientId,
+  deviceCode,
+  intervalSec = DEFAULT_POLL_INTERVAL_SEC,
+  expiresInSec,
+  fetch: fetchImpl = fetch,
+  sleep = realSleep,
+  now = () => Date.now(),
+  signal = null,
+}) {
+  let interval = Number.isFinite(intervalSec) && intervalSec > 0 ? intervalSec : DEFAULT_POLL_INTERVAL_SEC;
+  const deadline = now() + (Number.isFinite(expiresInSec) && expiresInSec > 0 ? expiresInSec : 600) * 1000;
+  const canceled = () => new OAuthCallbackError("canceled", "Login canceled");
+
+  for (;;) {
+    await sleep(interval * 1000);
+    if (signal?.aborted) throw canceled();
+    if (now() >= deadline) {
+      throw new OAuthCallbackError("expired_token", "The device code expired before it was approved");
+    }
+    const res = await fetchImpl(`${serverUrl}/token`, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({ grant_type: DEVICE_CODE_GRANT_TYPE, device_code: deviceCode, client_id: clientId }),
+    });
+    const data = await res.json().catch(() => ({}));
+    if (signal?.aborted) throw canceled();
+    if (res.ok && data && typeof data.access_token === "string" && data.access_token) return data;
+
+    const code = typeof data?.error === "string" && data.error ? data.error : null;
+    if (code === "authorization_pending") continue;
+    if (code === "slow_down") {
+      interval += SLOW_DOWN_STEP_SEC;
+      continue;
+    }
+    // access_denied / expired_token / invalid_grant, or anything unexpected
+    // (a tenant-state refusal carries its own `code`): stop, keep the reason.
+    const reason = (typeof data?.code === "string" && data.code) || code || `http_${res.status}`;
+    throw new OAuthCallbackError(reason, describe(data));
+  }
+}
+
+// Bounded, secret-free rendering of a failed /token body (no token on failure).
+function describe(data) {
+  let text;
+  try {
+    text = JSON.stringify(data);
+  } catch {
+    text = String(data);
+  }
+  return text && text.length > 300 ? `${text.slice(0, 300)}…` : text;
+}

package/src/stack.mjs

@@ -331,6 +331,29 @@ export function parseStackArgs(argv) {
   return { command, leaseId, opts, errors, childArgv };
 }
 
+/**
+ * BOT-2019: the human line for a queued lease's server position. `queue_position` is the
+ * server's dispatch rank (stack_lease_dispatch_queue — the order leases are considered in,
+ * not a guaranteed start order); a held / owner-offline lease has none and the server says
+ * why in `queue_position_reason`. `scored_ticket_id` is the ticket the lease is scored under
+ * (its own, or the requesting agent's when it has none). Older servers send neither field.
+ */
+export function describeQueuePosition(d) {
+  const reason = d?.queue_position_reason ? ` (${d.queue_position_reason})` : "";
+  const pos = d?.queue_position != null ? `queue position ${d.queue_position}` : `position: none${reason}`;
+  const where = [pos, d?.host_key ? `on ${d.host_key}` : null].filter(Boolean).join(" ");
+  return d?.scored_ticket_id ? `${where}, scored under ${d.scored_ticket_id}` : where;
+}
+
+/** BOT-2019: the queue fields a server returned for a queued lease, for a receipt. */
+function queueReceiptFields(d) {
+  return {
+    queue_position: d?.queue_position ?? null,
+    ...(d?.queue_position_reason !== undefined ? { queue_position_reason: d.queue_position_reason } : {}),
+    ...(d?.scored_ticket_id !== undefined ? { scored_ticket_id: d.scored_ticket_id } : {}),
+  };
+}
+
 /** Build the canonical receipt object (single JSON line to stdout). */
 export function buildReceipt(fields) {
   return { schema_version: STACK_SCHEMA_VERSION, ...fields };
@@ -1649,10 +1672,12 @@ export async function cmdUp(opts, {
 
   if (state === "queued") {
     // BOT-1319: a wrapped lefthook lane records this park as waiting for capacity.
-    const where = [d.queue_position != null ? `queue position ${d.queue_position}` : null, d.host_key ? `on ${d.host_key}` : null].filter(Boolean).join(" ");
+    // BOT-2019: the server's dispatch rank, or `position: none (<reason>)`, never a crash on null.
+    const where = describeQueuePosition(d);
     reportLaneStatus({ phase: "waiting", reason: "queued_for_capacity", detail: where || "host at capacity" });
+    process.stderr.write(`stack: lease ${leaseId} queued — ${where}\n`);
     if (opts.noWait) {
-      return emitResult(buildReceipt({ command: "up", outcome: "queued", lease_id: leaseId, state, host_key: d.host_key, slot, queued: true, queue_position: d.queue_position, holders: d.holders }), opts, EXIT.QUEUED);
+      return emitResult(buildReceipt({ command: "up", outcome: "queued", lease_id: leaseId, state, host_key: d.host_key, slot, queued: true, ...queueReceiptFields(d), holders: d.holders }), opts, EXIT.QUEUED);
     }
     // Park zero-poll until the lease leaves the queue (granted in BOT-1187 order).
     // BOT-2013: a lease reaped while queued (orphaned_agent, …) is lost, not "left the queue".
@@ -1837,7 +1862,9 @@ export async function cmdUp(opts, {
   }), opts, EXIT.OK);
 }
 
-export async function cmdStatus(leaseId, opts, { rpc = retryingStackCall(), emitResult = emit } = {}) {
+export async function cmdStatus(leaseId, opts, {
+  rpc = retryingStackCall(), emitResult = emit, stderr = (line) => process.stderr.write(`${line}\n`),
+} = {}) {
   const auth = await rpc.init();
   if (!auth) return emitResult(buildReceipt({ command: "status", outcome: "error", lease_id: leaseId, error: "not authenticated — run `botbuddy login`" }), opts, EXIT.AUTH);
   const got = await rpc.call("get_stack_lease", { lease_id: leaseId });
@@ -1846,10 +1873,15 @@ export async function cmdStatus(leaseId, opts, { rpc = retryingStackCall(), emit
     : emitResult(buildReceipt({ command: "status", outcome: "error", lease_id: leaseId, error: got.error }), opts, EXIT.BACKEND);
   const g = got.data;
   if (!g.success) return emitResult(buildReceipt({ command: "status", outcome: "error", lease_id: leaseId, code: g.code, error: g.code }), opts, EXIT.BACKEND);
+  // BOT-2019: a queued lease names its server dispatch rank (or why it has none) and the
+  // ticket it is scored under; a null position is reported, never a crash.
+  const queued = g.state === "queued";
+  if (queued) stderr(`stack: lease ${leaseId} queued — ${describeQueuePosition(g)}`);
   return emitResult(buildReceipt({
     command: "status", outcome: g.state, lease_id: leaseId, state: g.state,
     host_key: g.host_key, slot: g.slot, connection: g.connection,
-    queue_position: g.queue_position, idle_ttl_secs: g.idle_ttl_secs, queued: g.queued,
+    ...(queued ? queueReceiptFields(g) : { queue_position: g.queue_position }),
+    idle_ttl_secs: g.idle_ttl_secs, queued: g.queued,
     // BOT-1960: a lease fenced in `reaping` says since when, and — once the server gave up
     // retrying its failed reap — that it is reap_failed and why.
     ...(g.reap_requested_at ? { reap_requested_at: g.reap_requested_at } : {}),
@@ -2447,6 +2479,8 @@ export async function runStackLifecycle(opts, childArgv, adapters = {}) {
       return { exitCode: SIGNAL_EXIT[receivedSignal], outcome: "interrupted", leaseId, cleanup };
     }
     if (state === "queued") {
+      // BOT-2019: say where the lease sits (server dispatch rank, or why it has none) before parking.
+      stderrLine(`stack: lease ${leaseId} queued — ${describeQueuePosition(request.data)}`);
       activeWaitAbort = new AbortController();
       // BOT-2013: every reap state (reaping / reaped / reap_failed) means the queued lease is lost.
       const parked = await wait(leaseId, (s) => s !== "queued" && s != null, isReaped, { timeoutSec: opts.timeout, auth: rpc.auth, signal: activeWaitAbort.signal });