bitfab-cli 0.2.186 → 0.2.188

package/dist/index.js

@@ -8837,6 +8837,12 @@ var DaemonUnavailableError = class extends Error {
     this.name = "DaemonUnavailableError";
   }
 };
+var DaemonOpenTimeoutError = class extends Error {
+  constructor(message = "daemon did not respond to open") {
+    super(message);
+    this.name = "DaemonOpenTimeoutError";
+  }
+};
 var StudioNavigationError = class extends Error {
   reason;
   blockedReason;
@@ -9566,6 +9572,40 @@ function updateActiveStudioSession(updates) {
   writeStateFile(sessionFilePath(), updated);
   return updated;
 }
+function clearActiveStudioSession(sessionId, opts = {}) {
+  try {
+    const current = readStateFile(sessionFilePath());
+    if (!current) {
+      return clearLegacySession(sessionId, opts);
+    }
+    if (current.sessionId !== sessionId) {
+      return false;
+    }
+    if (!opts.force && current.pollerPid != null && current.pollerPid !== process.pid && isProcessAlive(current.pollerPid)) {
+      return false;
+    }
+    fs7.unlinkSync(sessionFilePath());
+    return true;
+  } catch {
+    return false;
+  }
+}
+function clearLegacySession(sessionId, opts = {}) {
+  try {
+    const raw = fs7.readFileSync(legacyFilePath(), "utf-8");
+    const parsed = JSON.parse(raw);
+    if (parsed.sessionId !== sessionId) {
+      return false;
+    }
+    if (!opts.force && typeof parsed.pid === "number" && parsed.pid !== process.pid && isProcessAlive(parsed.pid)) {
+      return false;
+    }
+    fs7.unlinkSync(legacyFilePath());
+    return true;
+  } catch {
+    return false;
+  }
+}
 function isProcessAlive(pid) {
   try {
     process.kill(pid, 0);
@@ -9948,6 +9988,9 @@ function closeStudioWindowsBySession(sessionId) {
     }
   }
 }
+function osDefaultResult(pid) {
+  return pid !== null ? { pid, launched: true, method: "os-default" } : { pid: null, launched: false, method: "none", reason: "spawn-failed" };
+}
 function openChromelessWindow(url2) {
   if (process.env.VITEST || process.env.NODE_ENV === "test") {
     throw new Error("openChromelessWindow called in a test environment without being mocked");
@@ -9958,12 +10001,16 @@ function openChromelessWindow(url2) {
   }
   if (recentOpens.length >= WINDOW_OPEN_RATE_LIMIT) {
     console.error(`[browser] rate limit: ${recentOpens.length} windows opened in the last ${WINDOW_OPEN_RATE_WINDOW_MS / 1e3}s, refusing to open another`);
-    return null;
+    return {
+      pid: null,
+      launched: false,
+      method: "none",
+      reason: "rate-limited"
+    };
   }
   recentOpens.push(now);
   if (shouldDisableChromelessWindows()) {
-    openOsDefault(url2);
-    return null;
+    return osDefaultResult(openOsDefault(url2));
   }
   const browsers = getChromiumBrowsers();
   const defaultId = getDefaultBrowserId();
@@ -9974,29 +10021,31 @@ function openChromelessWindow(url2) {
     if (binary) {
       const pid = openChromiumApp(binary, url2, sizeArgs);
       if (pid !== null) {
-        return pid;
+        return { pid, launched: true, method: "app" };
       }
-      openOsDefault(url2);
-      return null;
+      return osDefaultResult(openOsDefault(url2));
     }
   }
   if (defaultId !== null && defaultChromium === null) {
-    openOsDefault(url2);
-    return null;
+    return osDefaultResult(openOsDefault(url2));
   }
   for (const browser of browsers) {
     const binary = findExistingBinary(browser.binaryPaths);
     if (binary) {
       const pid = openChromiumApp(binary, url2, sizeArgs);
       if (pid !== null) {
-        return pid;
+        return { pid, launched: true, method: "app" };
       }
-      openOsDefault(url2);
-      return null;
+      return osDefaultResult(openOsDefault(url2));
     }
   }
-  openOsDefault(url2);
-  return null;
+  return osDefaultResult(openOsDefault(url2));
+}
+
+// ../bitfab-plugin-lib/dist/output.js
+function emitJson(event) {
+  process.stdout.write(`${JSON.stringify(event)}
+`);
 }
 
 // ../bitfab-plugin-lib/dist/parseArgs.js
@@ -10112,14 +10161,19 @@ async function createStudioSession({ serviceUrl, apiKey, sessionId, initialPath
     sessionId,
     extraHeaders: clientHeaders
   });
-  const windowPid = openChromelessWindow(target.url);
+  const open = openChromelessWindow(target.url);
   writeActiveStudioSession({
     sessionId,
     serviceUrl,
-    windowPid,
+    windowPid: open.pid,
     currentPath: target.path
   });
-  return { sessionId, serviceUrl };
+  return {
+    sessionId,
+    serviceUrl,
+    launched: open.launched,
+    launchReason: open.reason
+  };
 }
 
 // ../bitfab-plugin-lib/dist/daemon/client.js
@@ -10163,6 +10217,8 @@ var BROWSER_HEALTH_INTERVAL_MS = 10 * 1e3;
 var ENSURE_POLL_INTERVAL_MS = 200;
 var ENSURE_TIMEOUT_MS = 5e3;
 var PING_TIMEOUT_MS = 2e3;
+var OPEN_TIMEOUT_MS = 1e4;
+var COMMAND_TIMEOUT_MS = 3e4;
 function serialize(msg) {
   return `${JSON.stringify(msg)}
 `;
@@ -10336,7 +10392,7 @@ async function waitForLockHolderDaemon(socketPath, timeoutMs, localBuild = local
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
     const ping = await pingSocket(socketPath);
-    if (ping.alive && (localBuild === "unknown" || !ping.build || ping.build === localBuild)) {
+    if (ping.alive && buildMatches(localBuild, ping.build)) {
       return;
     }
     await new Promise((r) => setTimeout(r, ENSURE_POLL_INTERVAL_MS));
@@ -10347,6 +10403,12 @@ async function waitForLockHolderDaemon(socketPath, timeoutMs, localBuild = local
   }
   throw new Error(`daemon did not become ready within ${timeoutMs}ms`);
 }
+function buildMatches(localBuild, remoteBuild) {
+  if (localBuild === "unknown") {
+    return true;
+  }
+  return remoteBuild === localBuild;
+}
 function localBuildFingerprint() {
   try {
     const thisDir = path9.dirname(fileURLToPath3(import.meta.url));
@@ -10498,11 +10560,10 @@ async function ensureDaemon(paths = SINGLETON_DAEMON_PATHS) {
     const ping = await pingSocket(socketPath);
     if (ping.alive) {
       const localBuild = localBuildFingerprint();
-      if (ping.build && ping.build !== localBuild && localBuild !== "unknown") {
-        console.error(`[daemon] build mismatch (running: ${ping.build}, local: ${localBuild}), restarting`);
-      } else {
+      if (buildMatches(localBuild, ping.build)) {
         return;
       }
+      console.error(`[daemon] build mismatch (running: ${ping.build ?? "unreported"}, local: ${localBuild}), restarting`);
     }
   }
   if (!acquireLock(socketPath)) {
@@ -10527,9 +10588,19 @@ var DaemonClient = class {
   disconnectHandler = null;
   paths;
   socketPath;
-  constructor(paths = SINGLETON_DAEMON_PATHS) {
+  openTimeoutMs;
+  commandTimeoutMs;
+  // The single in-flight wedged-daemon reap, shared by every timeout path.
+  // Sharing it is load-bearing: `open`'s retry must AWAIT the same reap the
+  // command timeout fire-and-forgot, or a trailing reap's file cleanup could
+  // finish after the respawned daemon bound its socket and wrote its pid
+  // file, unlinking the new daemon's files and orphaning it.
+  reapInFlight = null;
+  constructor(paths = SINGLETON_DAEMON_PATHS, timeouts = {}) {
     this.paths = paths;
     this.socketPath = paths.socketPath;
+    this.openTimeoutMs = timeouts.openTimeoutMs ?? OPEN_TIMEOUT_MS;
+    this.commandTimeoutMs = timeouts.commandTimeoutMs ?? COMMAND_TIMEOUT_MS;
   }
   async connect() {
     await ensureDaemon(this.paths);
@@ -10579,28 +10650,97 @@ var DaemonClient = class {
       idx = this.buffer.indexOf("\n");
     }
   }
-  sendCommand(cmd) {
+  // Every command runs under a timeout so a wedged daemon can never hang a
+  // caller indefinitely: a never-resolving promise is not a rejection, so it
+  // slips straight past callers' .catch() guards. `open` passes its own tighter
+  // timeout + typed error to drive the reap-and-retry path; everything else
+  // gets the generous default ceiling.
+  sendCommand(cmd, opts = {}) {
     if (!this.socket) {
       return Promise.reject(new Error("not connected"));
     }
+    const timeoutMs = opts.timeoutMs ?? this.commandTimeoutMs;
+    const cmdName = cmd.cmd ?? "command";
     return new Promise((resolve2, reject) => {
-      this.responseQueue.push(resolve2);
+      let settled = false;
+      const timer = setTimeout(() => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        const pending = this.responseQueue;
+        this.responseQueue = [];
+        for (const other of pending) {
+          if (other !== resolver) {
+            other({
+              ok: false,
+              error: `daemon connection reset after ${cmdName} timed out`
+            });
+          }
+        }
+        this.destroy();
+        void this.reapWedgedDaemon();
+        reject(opts.onTimeout?.() ?? new Error(`daemon did not respond to ${cmdName} within ${timeoutMs}ms`));
+      }, timeoutMs);
+      const resolver = (msg) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        clearTimeout(timer);
+        resolve2(msg);
+      };
+      this.responseQueue.push(resolver);
       try {
         this.socket.write(serialize(cmd));
       } catch (err) {
-        this.responseQueue.pop();
+        settled = true;
+        clearTimeout(timer);
+        const idx = this.responseQueue.indexOf(resolver);
+        if (idx !== -1) {
+          this.responseQueue.splice(idx, 1);
+        }
         reject(err);
       }
     });
   }
   async open(opts) {
+    try {
+      return await this.openOnce(opts);
+    } catch (err) {
+      if (!(err instanceof DaemonOpenTimeoutError)) {
+        throw err;
+      }
+      this.destroy();
+      await this.reapWedgedDaemon();
+      await this.connect();
+      return await this.openOnce(opts);
+    }
+  }
+  async openOnce(opts) {
     const cmd = { cmd: "open", ...opts };
-    const res = await this.sendCommand(cmd);
+    const res = await this.sendCommand(cmd, {
+      timeoutMs: this.openTimeoutMs,
+      onTimeout: () => new DaemonOpenTimeoutError()
+    });
     if (!res.ok) {
       throw new Error(res.error);
     }
     return res;
   }
+  // Start (or join) the wedged-daemon reap. All timeout paths funnel through
+  // this so at most one reap runs at a time and `open`'s retry can await the
+  // in-flight one instead of racing it - a reap that finished AFTER the retry
+  // respawned would unlink the new daemon's socket/pid files and orphan it.
+  reapWedgedDaemon() {
+    if (!this.reapInFlight) {
+      this.reapInFlight = reapAllDaemons(this.paths).catch(() => {
+      }).finally(() => {
+        this.reapInFlight = null;
+      });
+    }
+    return this.reapInFlight;
+  }
   async navigate(key, navPath) {
     const res = await this.sendCommand({ cmd: "navigate", key, path: navPath });
     if (!res.ok) {
@@ -10780,11 +10920,11 @@ var DirectChannel = class {
         path: initialPath,
         sessionId: sessionId2
       });
-      const windowPid = openChromelessWindow(url2);
+      const open = openChromelessWindow(url2);
       writeActiveStudioSession({
         sessionId: sessionId2,
         serviceUrl: this.serviceUrl,
-        windowPid,
+        windowPid: open.pid,
         currentPath: initialPath,
         // A keyless login window is pre-auth: writeActiveStudioSession defaults
         // authenticated to true, but this window has no token yet. Record it as
@@ -10793,7 +10933,12 @@ var DirectChannel = class {
         // (openStudioTo) is what later excludes it from reuse.
         authenticated: false
       });
-      return { sessionId: sessionId2, opened: true };
+      return {
+        sessionId: sessionId2,
+        opened: true,
+        launched: open.launched,
+        launchReason: open.reason
+      };
     }
     const existing = readActiveStudioSession();
     if (existing && existing.windowState !== "closed") {
@@ -10817,7 +10962,12 @@ var DirectChannel = class {
       initialPath: path21,
       clientHeaders: opts?.clientHeaders
     });
-    return { sessionId: session.sessionId, opened: true };
+    return {
+      sessionId: session.sessionId,
+      opened: true,
+      launched: session.launched,
+      launchReason: session.launchReason
+    };
   }
   async close(sessionId, message) {
     await closeStudio({ serviceUrl: this.serviceUrl, apiKey: this.apiKey, sessionId }, message);
@@ -10899,7 +11049,12 @@ var DaemonChannel = class _DaemonChannel {
       }
       return { sessionId: openRes.sessionId, opened: false };
     }
-    return { sessionId: openRes.sessionId, opened: true };
+    return {
+      sessionId: openRes.sessionId,
+      opened: true,
+      launched: openRes.launched,
+      launchReason: openRes.launchReason
+    };
   }
   async close(sessionId, message) {
     await Promise.all([
@@ -11003,6 +11158,48 @@ async function resolveChannel(apiKey, serviceUrl) {
   return new DirectChannel(apiKey, serviceUrl);
 }
 
+// ../bitfab-plugin-lib/dist/studioTeardown.js
+function killStudioWindow(sessionId) {
+  const record2 = readActiveStudioSession();
+  if (record2?.sessionId !== sessionId || record2.windowPid == null) {
+    return;
+  }
+  try {
+    process.kill(record2.windowPid, "SIGTERM");
+  } catch {
+  }
+}
+function killPollerProcess(sessionId) {
+  const record2 = readActiveStudioSession();
+  if (record2?.sessionId !== sessionId || record2.pollerPid == null || record2.pollerPid === process.pid) {
+    return;
+  }
+  try {
+    process.kill(record2.pollerPid, "SIGTERM");
+  } catch {
+  }
+}
+
+// ../bitfab-plugin-lib/dist/commands/clearStudioSession.js
+async function clearStudioSessionById(sessionId, record2) {
+  killStudioWindow(sessionId);
+  const alreadyClosed = record2?.sessionId === sessionId && record2.windowState === "closed";
+  if (!alreadyClosed) {
+    closeStudioWindowsBySession(sessionId);
+  }
+  killPollerProcess(sessionId);
+  try {
+    const channel = await resolveChannel("", record2?.serviceUrl ?? "");
+    try {
+      await channel.clearSession(sessionId);
+    } finally {
+      channel.destroy();
+    }
+  } catch {
+  }
+  return clearActiveStudioSession(sessionId, { force: true });
+}
+
 // ../bitfab-plugin-lib/dist/replayCapabilities.js
 var semver = __toESM(require_semver2(), 1);
 
@@ -11210,6 +11407,20 @@ function applyFocusTarget(target) {
   }
 }
 
+// ../bitfab-plugin-lib/dist/studioConnectGrace.js
+var CONNECT_GRACE_MS = 45e3;
+function connectGraceMs() {
+  const raw = process.env.BITFAB_STUDIO_CONNECT_GRACE_MS;
+  const parsed = raw ? Number(raw) : Number.NaN;
+  return Number.isFinite(parsed) ? parsed : CONNECT_GRACE_MS;
+}
+var PRE_AUTH_CONNECT_GRACE_MS = 10 * 60 * 1e3;
+function preAuthConnectGraceMs() {
+  const raw = process.env.BITFAB_STUDIO_PREAUTH_CONNECT_GRACE_MS;
+  const parsed = raw ? Number(raw) : Number.NaN;
+  return Number.isFinite(parsed) ? parsed : PRE_AUTH_CONNECT_GRACE_MS;
+}
+
 // ../bitfab-plugin-lib/dist/commands/openStudioTo.js
 function lineToAgentEvent(line) {
   const name = typeof line.event === "string" ? line.event : "";
@@ -11219,17 +11430,31 @@ function lineToAgentEvent(line) {
 var WINDOW_CLOSE_GRACE_PERIOD_MS = 1e4;
 var LOGIN_TIMEOUT_MS = 10 * 60 * 1e3;
 function formatStudioUrlMessage(url2) {
-  return `Studio opened at: ${url2}`;
+  return `Opening Studio at: ${url2}`;
+}
+function defaultLifecycleEmit(event) {
+  emitJson(event);
+  if (event.event === "window-open-requested" && typeof event.url === "string") {
+    console.error(formatStudioUrlMessage(event.url));
+  }
 }
-function createEventSubscription(channel, sessionId, onEvent, restoreFocus) {
+function createEventSubscription(channel, sessionId, onEvent, restoreFocus, freshOpenGraceMs = null) {
   let graceTimer = null;
+  let connectWatchdog = null;
   let endedNotified = false;
+  const ownsPointer = !channel.isPersistent();
   const clearGraceTimer = () => {
     if (graceTimer) {
       clearTimeout(graceTimer);
       graceTimer = null;
     }
   };
+  const clearConnectWatchdog = () => {
+    if (connectWatchdog) {
+      clearTimeout(connectWatchdog);
+      connectWatchdog = null;
+    }
+  };
   const notifyEnded = (baseEvent) => {
     if (!endedNotified) {
       endedNotified = true;
@@ -11237,14 +11462,20 @@ function createEventSubscription(channel, sessionId, onEvent, restoreFocus) {
       onEvent({ ...baseEvent, type: "studio:session-ended" });
     }
     clearGraceTimer();
+    clearConnectWatchdog();
     sub.abort();
   };
   const sub = channel.subscribe(sessionId, (event) => {
+    if (!event.type.startsWith("agent:")) {
+      clearConnectWatchdog();
+    }
     if (event.type === "studio:window-closed") {
       clearGraceTimer();
       graceTimer = setTimeout(() => {
         graceTimer = null;
-        updateActiveStudioSession({ windowState: "closed" });
+        if (ownsPointer) {
+          updateActiveStudioSession({ windowState: "closed" });
+        }
         notifyEnded(event);
       }, WINDOW_CLOSE_GRACE_PERIOD_MS);
       return;
@@ -11277,9 +11508,36 @@ function createEventSubscription(channel, sessionId, onEvent, restoreFocus) {
   }, (err) => {
     console.error(`studio event stream: ${err.message}`);
   });
+  if (freshOpenGraceMs != null) {
+    connectWatchdog = setTimeout(() => {
+      connectWatchdog = null;
+      if (endedNotified) {
+        return;
+      }
+      endedNotified = true;
+      restoreFocus();
+      if (ownsPointer) {
+        updateActiveStudioSession({ windowState: "closed" });
+      }
+      onEvent({
+        id: "",
+        type: "studio:session-ended",
+        data: { reason: "never-connected" }
+      });
+      clearGraceTimer();
+      void (async () => {
+        try {
+          await channel.clearSession(sessionId);
+        } catch {
+        }
+        sub.abort();
+      })();
+    }, freshOpenGraceMs);
+  }
   return {
     abort: () => {
       clearGraceTimer();
+      clearConnectWatchdog();
       sub.abort();
     },
     done: sub.done
@@ -11293,7 +11551,19 @@ async function openStudioTo(path21, opts = {}) {
   const focusTarget = captureFocusTarget();
   const restoreFocus = () => applyFocusTarget(focusTarget);
   const channel = await resolveChannel(apiKey ?? "", serviceUrl);
-  const finish = (sessionId2, opened2, resolvedApiKey, url3) => {
+  const emit = opts.emit ?? defaultLifecycleEmit;
+  const reportFreshOpen = (url3, launched2, reason) => {
+    if (launched2 === false) {
+      emit({
+        event: "open-failed",
+        reason: reason ?? "could not launch a browser",
+        url: url3
+      });
+    } else {
+      emit({ event: "window-open-requested", url: url3 });
+    }
+  };
+  const finish = (sessionId2, opened2, resolvedApiKey, url3, launched2, windowProven = false) => {
     const persistent = channel.isPersistent();
     const base = {
       sessionId: sessionId2,
@@ -11304,6 +11574,7 @@ async function openStudioTo(path21, opts = {}) {
       url: url3
     };
     const wantsEvents = opts.tail || Boolean(opts.onEvent);
+    const freshOpenGraceMs = opened2 && !windowProven ? launched2 === false ? preAuthConnectGraceMs() : connectGraceMs() : null;
     if (persistent) {
       if (!wantsEvents || opts.tail) {
         if (!opts.tail) {
@@ -11316,7 +11587,7 @@ async function openStudioTo(path21, opts = {}) {
         };
       }
       const subscription = createEventSubscription(channel, sessionId2, opts.onEvent ?? (() => {
-      }), restoreFocus);
+      }), restoreFocus, freshOpenGraceMs);
       return { ...base, ...subscription };
     }
     if (!wantsEvents) {
@@ -11334,7 +11605,7 @@ async function openStudioTo(path21, opts = {}) {
         appendStudioEvent(key, studioEventToLogLine(event, sessionId2));
         userOnEvent2(event);
       };
-      const subscription = createEventSubscription(channel, sessionId2, sink, restoreFocus);
+      const subscription = createEventSubscription(channel, sessionId2, sink, restoreFocus, freshOpenGraceMs);
       return {
         ...base,
         abort: subscription.abort,
@@ -11378,9 +11649,11 @@ async function openStudioTo(path21, opts = {}) {
     const sessionId2 = openResult.sessionId;
     const signInUrl = `${serviceUrl}${buildSignInPath(sessionId2)}`;
     if (openResult.opened) {
-      opts.onWindowOpened?.(signInUrl);
+      reportFreshOpen(signInUrl, openResult.launched, openResult.launchReason);
+    } else {
+      emit({ event: "navigated", sessionId: sessionId2, path: buildSignInPath(sessionId2) });
     }
-    opts.onLoginRequired?.(sessionId2, signInUrl);
+    emit({ event: "auth-required", sessionId: sessionId2, signInUrl });
     const loginApiKey = await new Promise((resolve2, reject) => {
       const timer = setTimeout(() => {
         sub.abort();
@@ -11404,19 +11677,30 @@ async function openStudioTo(path21, opts = {}) {
     });
     saveCredentials(loginApiKey);
     updateActiveStudioSession({ authenticated: true });
-    opts.onAuthenticated?.(sessionId2);
+    emit({ event: "authenticated", sessionId: sessionId2 });
     channel.setApiKey(loginApiKey);
-    return finish(sessionId2, openResult.opened, loginApiKey, openResult.opened ? signInUrl : void 0);
+    return finish(
+      sessionId2,
+      openResult.opened,
+      loginApiKey,
+      openResult.opened ? signInUrl : void 0,
+      openResult.launched,
+      // The sign-in page pushed studio:authenticated to get here, so the
+      // window demonstrably exists: never arm the connect watchdog on it.
+      true
+    );
   }
-  const { sessionId, opened } = await channel.openOrNavigate(path21, {
+  const { sessionId, opened, launched, launchReason } = await channel.openOrNavigate(path21, {
     clientHeaders: opts.clientHeaders,
     focusTarget: focusTarget ?? void 0
   });
   const url2 = opened ? resolveStudioSessionTarget({ serviceUrl, path: path21, sessionId }).url : void 0;
-  if (url2) {
-    opts.onWindowOpened?.(url2);
+  if (opened && url2) {
+    reportFreshOpen(url2, launched, launchReason);
+  } else {
+    emit({ event: "navigated", sessionId, path: path21 });
   }
-  return finish(sessionId, opened, apiKey, url2);
+  return finish(sessionId, opened, apiKey, url2, launched);
 }
 
 // ../bitfab-plugin-lib/dist/commands/login.js
@@ -11451,20 +11735,33 @@ Already logged in as ${identity}${endpoint}. Run the login command with --force
       return;
     }
   }
+  if (force) {
+    const record2 = readActiveStudioSession();
+    if (record2) {
+      await clearStudioSessionById(record2.sessionId, record2).catch(() => {
+      });
+    }
+  }
   try {
     let printedSignInUrl = false;
     const result = await openStudioTo("/studio", {
       forceLogin: true,
       freshWindowPath: `/studio/close?autoClose=true&message=${encodeURIComponent("Login complete")}`,
-      onLoginRequired: (_sessionId, signInUrl) => {
-        if (!printedSignInUrl) {
+      // login is a human-facing command, not a JSONL stream, so it renders the
+      // Studio lifecycle events as text instead of the default stdout JSON. It
+      // only cares about surfacing a sign-in link (once) and reporting a failed
+      // browser launch; navigated/authenticated are handled by the flow below.
+      emit: (event) => {
+        if (event.event === "open-failed") {
           printedSignInUrl = true;
-          console.log(formatStudioUrlMessage(signInUrl));
+          console.log(`Could not open a browser (${event.reason}). Open this link to sign in: ${event.url}`);
+          return;
+        }
+        const url2 = event.event === "window-open-requested" ? event.url : event.event === "auth-required" ? event.signInUrl : null;
+        if (url2 && !printedSignInUrl) {
+          printedSignInUrl = true;
+          console.log(formatStudioUrlMessage(url2));
         }
-      },
-      onWindowOpened: (url2) => {
-        printedSignInUrl = true;
-        console.log(formatStudioUrlMessage(url2));
       }
     });
     const apiKey = getConfig().apiKey;
@@ -11495,7 +11792,7 @@ ${greeting}`);
   } catch (err) {
     if (exitOnComplete) {
       if (err instanceof StudioNavigationError && err.staleSessionId) {
-        console.error("\nA Studio window is recorded as open but is not responding. Close it (or run the clearStudioSession command), then try again.");
+        console.error("\nA Studio window is recorded as open but is not responding. Close the Studio window and try again. To force-clear a stale session, a user can re-run with `bitfab login --force` (manual recovery - automated agents should not run it).");
       } else {
         console.error(`
 ${err.message}`);
@@ -33004,7 +33301,7 @@ var GLOBAL_HELP_TEXT = `Usage: bitfab <command> [options]
 Commands:
   init [--editor <name>]              Full onboarding: plugin-install, login, and setup
   plugin-install [--editor <name>]    Install the Bitfab plugin in one editor
-  login                               Authenticate with Bitfab (opens browser)
+  login [--force]                     Authenticate with Bitfab (opens browser)
   logout                              Remove stored credentials
   session-logs [status|enable|disable] Read or update session log collection
   setup [--editor <name>]             Launch /bitfab:setup in the editor
@@ -33021,6 +33318,7 @@ Options:
   --no-upload-logs       analyze-repo: keep session logs local (skips the prompt)
   --limit <n>            analyze-repo: cap how many draft trace plans to upload (default 5)
   --prompt, -p <text>    analyze-repo: free-text guidance steering what to focus on
+  --force                login: re-authenticate and clear any stale Studio session first
 
 Examples:
   bitfab init                              Full setup (detect editor, install, login, setup)
@@ -33028,6 +33326,7 @@ Examples:
   bitfab analyze-repo                      Scan the repo and upload draft trace plans (headless)
   bitfab analyze-repo --limit 3            Scan the repo and upload at most 3 draft trace plans
   bitfab analyze-repo "focus on billing"   Scan with free-text guidance on what to prioritize
+  bitfab login --force                     Re-authenticate and clear a stale Studio session
   bitfab session-logs enable               Enable session log collection
   bitfab session-logs disable              Disable session log collection
   bitfab assistant investigate             Investigate traces
@@ -33060,15 +33359,16 @@ Examples:
   bitfab plugin-install
   bitfab plugin-install --editor cursor
 `,
-  login: `Usage: bitfab login
+  login: `Usage: bitfab login [--force]
 
 Authenticate with Bitfab in the browser and save credentials locally.
 
 Options:
-  This command has no options.
+  --force    Re-authenticate even when already signed in, and clear any stale Studio session first
 
 Examples:
   bitfab login
+  bitfab login --force
 `,
   logout: `Usage: bitfab logout
 
@@ -33230,7 +33530,7 @@ function wantsHelp(argv) {
 var COMMAND_SPECS = {
   init: { flags: ["editor", "skipPermissions"], unknownOption: "error" },
   "plugin-install": { flags: ["editor"], unknownOption: "error" },
-  login: { flags: [], unknownOption: "error" },
+  login: { flags: ["force"], unknownOption: "error" },
   logout: { flags: [], unknownOption: "error" },
   "session-logs": { flags: [], unknownOption: "error" },
   setup: { flags: ["editor", "skipPermissions"], unknownOption: "error" },
@@ -33304,6 +33604,12 @@ function applyFlag(key, token, next, values) {
         return 1;
       }
       return null;
+    case "force":
+      if (token === "--force") {
+        values.force = true;
+        return 1;
+      }
+      return null;
   }
 }
 function parseArgs2(argv) {
@@ -33350,6 +33656,7 @@ function parseArgs2(argv) {
     uploadLogs: values.uploadLogs,
     limit: values.limit,
     prompt: values.prompt,
+    force: values.force,
     rest
   };
 }
@@ -33369,7 +33676,16 @@ ${GLOBAL_HELP_TEXT}`
     process.stdout.write(helpText);
     return;
   }
-  const { command, editor, skipPermissions, uploadLogs, limit, prompt, rest } = parseArgs2(argv);
+  const {
+    command,
+    editor,
+    skipPermissions,
+    uploadLogs,
+    limit,
+    prompt,
+    force,
+    rest
+  } = parseArgs2(argv);
   const abortUpdateCheck = startUpdateCheck();
   if (command === "init") {
     await runInit({ editor, skipPermissions });
@@ -33382,7 +33698,7 @@ ${GLOBAL_HELP_TEXT}`
     return;
   }
   if (command === "login") {
-    await runLoginCommand();
+    await runLoginCommand({ force });
     abortUpdateCheck();
     return;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bitfab-cli",
-  "version": "0.2.186",
+  "version": "0.2.188",
   "description": "Install and configure the Bitfab plugin in Claude Code, Codex, or Cursor.",
   "type": "module",
   "main": "dist/index.js",