@botbuddy/cli 1.40.0 → 1.40.1

package/package.json

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

package/src/commands.mjs

@@ -399,6 +399,17 @@ export function parseLoginArgs(args) {
   return out;
 }
 
+/**
+ * BOT-2030/BOT-2044: the sign-in mode for parsed login options. `--device` /
+ * `--loopback` win; `--no-browser` is a loopback-only option (print the URL,
+ * keep the localhost listener), so on its own it is an explicit loopback
+ * choice; otherwise shouldUseDeviceFlow auto-detects (SSH, display-less Linux).
+ */
+export function resolveLoginDevice(options = {}, { env = process.env, platform = process.platform } = {}) {
+  const flag = typeof options.device === "boolean" ? options.device : options.noBrowser ? false : undefined;
+  return shouldUseDeviceFlow({ env, platform, flag });
+}
+
 // BOT-1580: resolve the caller identity from parsed flags, falling back to the
 // BOTBUDDY_CALLER* environment variables so an agent harness can advertise who it
 // is without every wrapper having to pass flags. A flag always wins over the env.
@@ -477,7 +488,7 @@ 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 {
-    const device = shouldUseDeviceFlow({ env: process.env, platform: process.platform, flag: options.device });
+    const device = resolveLoginDevice(options, { env: process.env, platform: process.platform });
     await doLogin({ noBrowser: options.noBrowser, tenant: options.tenant, device, ...caller });
   } catch (err) {
     die(err.message);
@@ -507,7 +518,7 @@ export async function cmdSetup(args, {
     return error.exitCode === 2 ? 2 : 4;
   }
   if (options.help) {
-    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.");
+    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). --loopback or --no-browser over SSH keeps the localhost callback on the remote host, so first forward its port with ssh -L <port>:127.0.0.1:<port> <host> (the port is in the printed URL), or setup times out. After it succeeds, use `bb wait <condition>` with no credential flags or environment variables.");
     return 0;
   }
   let bound;
@@ -533,7 +544,7 @@ export async function cmdSetup(args, {
     // reusable client key with a tenant-sealed one.
     await login({
       noBrowser: options.noBrowser,
-      device: shouldUseDeviceFlow({ env, platform, flag: options.device }),
+      device: resolveLoginDevice(options, { env, platform }),
       ...callerResolver(options, env),
     });
     // Setup is an explicit session bootstrap/repair command. Rotate before
@@ -604,8 +615,9 @@ ${bold("HOW IT WORKS")}
 ${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,
+                 still runs on this machine's localhost, so this implies
+                 ${cyan("--loopback")} unless ${cyan("--device")} is also given.
+  --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.
@@ -638,6 +650,9 @@ ${bold("NOTES")}
     listener and state.
   • ${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.
+    ${cyan("--loopback")} or ${cyan("--no-browser")} over SSH keeps the localhost callback on the
+    remote host, so first forward its port, e.g. ${cyan("ssh -L <port>:127.0.0.1:<port> <host>")}
+    (the port is in the printed URL), or the login times out.
 
 ${bold("RECOVERY")}
   If ${cyan("botbuddy status")} shows no client key, run ${cyan("botbuddy login")}. For an