@leadbay/mcp 0.21.1 → 0.21.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog — @leadbay/mcp
 
+## 0.21.2 — 2026-06-17
+
+- **Early host shutdown no longer kills the OAuth flow mid-registration** (review P1): Claude Desktop's probe→teardown can close stdin within ~100ms — while the background bootstrap is still in region-probe/discovery/registration, before any browser-open exists. `shutdown()` now waits (bounded ~4s) on the whole bootstrap task, not just the browser-open promise, so the flow reaches the authorize-URL mint + open dispatch instead of dying early. Verified: stdin closed at 1s still produced `spawn OK` at ~2.7s.
+- **Terminal bootstrap failures surface `AUTH_FAILED`, not a forever-"pending"** (review P2): a non-browser failure (region probe / discovery / registration / token exchange) with no sign-in URL used to leave tools reporting "a browser window should have opened…" indefinitely. The failure reason is now recorded and the gate returns `AUTH_FAILED` with the real error + restart guidance; it takes priority over a stale sign-in link.
+
+- **Browser auto-open now reconstructs a missing `DISPLAY`/`WAYLAND_DISPLAY` on Linux**: a real Claude Desktop install log showed the spawned server's env had `DISPLAY=<unset> WAYLAND=<unset>` (the host strips them inconsistently — present on some launches, absent on others). Without a display var, `xdg-open` spawns "successfully" but can't reach the display server, so no tab opens — the silent install failure. `openInBrowser` now backfills the missing vars from `XDG_RUNTIME_DIR` (the `wayland-N` socket) and `/tmp/.X11-unix` (defaulting to `:0`) before spawning the launcher, and passes that env to the child. Already-set vars are left untouched; non-Linux is unaffected.
+- **OAuth client registration is cached & reused** (the actual "nothing opens" root cause): bootstrap was registering a fresh Dynamic-Client-Registration client on every launch, and Claude Desktop's probe-restarts (several launches per install) blew past the backend's ~10-registrations/IP/hour cap — so bootstrap 429'd *before* building a sign-in URL. The registered `client_id` is now persisted per auth server in `~/.leadbay/oauth-client.json` and reused (loopback clients accept any 127.0.0.1 port per RFC 8252), so registration happens at most once and the 429 never recurs.
+
+- **OAuth-on-install for the Claude Desktop `.dxt` no longer fails with "Unable to connect to extension server"**: the bundled stdio server ran the full interactive browser OAuth flow (up to 5 minutes) at startup, *before* answering the MCP `initialize` handshake — so Claude Desktop, which gives a launched extension only a few seconds to respond, timed out the connection and marked the server unreachable. The OAuth bootstrap is now **non-blocking**: the server answers `initialize` immediately with a real (tokenless) client, runs the browser sign-in in the background, and the first tool call returns a transient `AUTH_PENDING` envelope ("Signing you in to Leadbay — a browser window should have opened…") until the token lands. The moment the loopback callback completes, the token is set on the live client and the next tool call executes authenticated — no server rebuild, no restart.
+- **Browser auto-open now survives Claude Desktop's install-time probe race**: a freshly-installed extension is probed with rapid connect→shutdown cycles (the first spawned process can live <100ms — confirmed in the install logs), which killed the process before the background OAuth flow reached the browser-launch step, so no tab opened on install even though it works on a stable session. The bootstrap now fires the browser-open the moment the authorize URL is known (tracked in an in-flight handle), and the shutdown path waits up to 1.5s for that spawn to dispatch before exiting — the detached launcher then survives our exit. Net: the browser opens on install. The clickable sign-in link remains as the backstop.
+- **The sign-in link is also surfaced to the user instead of relying solely on auto-opening a browser**: the spawned `.dxt` stdio process frequently can't open a GUI browser at all — Claude Desktop strips `PATH` *and* `DISPLAY`/`WAYLAND_DISPLAY` from the child env, so `xdg-open`/`open` either `ENOENT`s or (worse) silently exits 0 without launching anything, leaving the user with no link and no error. The bootstrap now captures the live OAuth authorize URL and the gate returns it as a **clickable sign-in link** in the tool envelope ("Open this link to authorize Leadbay…"); the loopback listener stays alive in the background, so clicking it completes the flow and the next tool call is authenticated. The browser auto-open is still attempted (best-effort, now via absolute launcher paths `/usr/bin/open` / `%SystemRoot%\System32\cmd.exe` / `/usr/bin/xdg-open`) for environments where it works — but the surfaced link is the reliable path and no longer depends on it.
+
 ## 0.21.1 — 2026-06-16
 
 - **CSV import no longer 400s on a lead status the agent didn't uppercase** (product#3745): `leadbay_import_leads` / `leadbay_import_and_qualify` forwarded `default_status` / `statuses` values verbatim to `POST /imports/{id}/update_mappings`, whose backend `MappingsPayload` decodes them as the strict, case-sensitive `LeadStatus` enum (`DEFAULT, INBOUND, UNWANTED, WANTED, LOST, WON`). A value like "Won" failed deserialization and the whole call 400'd with an opaque "JSON deserialization error" before any record committed — JM hit this trying to tag 179 companies as Won. The MCP now owns the canonical set and enforces it before sending: status values are matched case-insensitively to their enum member ("Won" → "WON"), an empty default means no default, and a genuinely unknown status returns a clear `IMPORT_INVALID_STATUS` error naming the valid values instead of an opaque backend 400. The two tools' input schemas now declare the enum.

package/dist/bin.js

@@ -22491,6 +22491,49 @@ After your first \`leadbay_pull_leads\` call, capture \`response.lens.id\` (the
 
 You don't need to memorize every tool here \u2014 each tool's own description carries a RENDERING block (how to present the response) and a NEXT STEPS block (observation \u2192 suggestion table). Read the relevant tool's description in full when the user picks an entry point. This overview just gets you to the right starting tool.
 
+## Proposing a next step \u2014 only when it genuinely helps
+
+After reporting account state, you MAY propose a concrete next step \u2014 but only when one is genuinely useful, not by reflex. A reflexive "want me to also\u2026?" on every turn is noise; the user notices and it erodes trust.
+
+**Propose a next step when** the overview surfaced an obvious unfinished thread or a blocker the user would want resolved \u2014 a fresh discovery batch waiting, follow-ups due today, or a quota/auth blocker with a specific unblock action. In those cases the next move is real and worth offering.
+
+**Skip it when** there's no clear unfinished thread, the user only wanted the status (a bare "where do I stand?"), or the work they asked for is plainly done. A status read that ends cleanly is a complete answer \u2014 don't manufacture a next step just to have one.
+
+**Lean on memory.** Check the \`_meta.agent_memory.summary\` for prior signal on how this user reacts to next-step offers. If the memory shows they routinely dismiss them, default to NOT proposing (let them ask). If they routinely act on them, lean toward proposing. When the user dismisses or accepts a proposal this turn, that's a material signal \u2014 call \`leadbay_agent_memory_capture\` (\`source:"inferred"\`, low confidence) so the preference compounds across sessions.
+
+**When you do propose, the proposal IS a native choice dialog \u2014 never a prose "let me know if\u2026".** Route 2\u20134 mutually-exclusive next moves into your host's next-step widget (\`ask_user_input_v0\` on Claude chat / ChatGPT, \`AskUserQuestion\` on Claude cowork / Claude Code). The widget is the question; do not also list the same options as prose.
+
+**ALWAYS render NEXT STEPS via your host's next-step widget.** Use whichever is in your tool set \u2014 the NAME and SCHEMA differ: **\`ask_user_input_v0\`** (Claude chat / ChatGPT) takes plain-string options with \`type:"single_select"\`; **\`AskUserQuestion\`** (Claude cowork / Claude Code) takes object options \`{label, description}\` plus a required short \`header\` (\u226412 chars) and \`multiSelect\`, NO \`type\` field, and never add an "Other" option (the host adds it). Match the schema to the tool you actually have \u2014 the wrong schema fails silently and you fall back to prose. Prose bullets are the fallback ONLY when NEITHER widget exists. Any turn that would end with a choice must be the widget \u2014 the widget IS the question.
+
+**If the tool result carries a \`next_steps\` object, that is the source of truth \u2014 use it directly.** Each option has a short \`.label\` (\u22645 words) and a full \`.description\`. Map \`next_steps.options[]\` into your host widget VERBATIM and in order: for \`AskUserQuestion\` (cowork / Claude Code) pass each as \`{label, description}\`; for \`ask_user_input_v0\` (Claude chat / ChatGPT, string options only) pass each option's \`.description\` as the string (it's the full sentence). Do NOT reword, reorder, drop, or prose-ify them \u2014 they're built deterministically by the server so the offer (incl. the artifact option at position 0) fires every time. Fall back to the table below only when there is NO \`next_steps\` field.
+
+**One exception \u2014 skip the widget** when the user's original message contained a complete sequential instruction chain ("show me X and then do Y") AND all stated steps have been completed. In that case, end with STOP directly \u2014 the user stated their full plan and does not need a "what next?" prompt.
+- Skip example: "Show me today's leads and then research the top one for me." \u2192 after research completes, emit STOP without the widget.
+- Do NOT skip for: plain requests ("show me today's leads", "run my check-in"), recurring-language requests ("I do this every day"), or requests where only one action was stated.
+
+Pick 2\u20134 rows from the (Observation, Suggest, Calls) table below most relevant to the response, then call your host's widget with ITS schema (per the schema rules above \u2014 wrong schema fails silently):
+- \`ask_user_input_v0\`: \`{questions:[{question,type:"single_select",options:["<Suggest 1>","<Suggest 2>"]}]}\`
+- \`AskUserQuestion\`: \`{questions:[{question,header:"Next step",multiSelect:false,options:[{label:"<\u22645 words>",description:"<Suggest 1>"}]}]}\`
+
+User picks \u2192 call the matching \`Calls\` tool. Constraints: 2\u20134 mutually-exclusive options, AskUserQuestion labels \u22645 words (full text in \`description\`), max 3 questions. Table stays internal; never recite it.
+
+---
+
+
+
+The overview itself returns no \`next_steps\` object, so when you DO propose, build the options from this table \u2014 pick the 2\u20134 rows that match what the account state actually showed. If none apply cleanly, propose none (the status read was complete) rather than inventing an option.
+
+All \`Calls\` below are agent-callable \`leadbay_*\` tools (never an MCP prompt name like \`leadbay_daily_check_in\` \u2014 the agent cannot invoke a prompt from a turn; route to the underlying tool instead).
+
+| Observation                                                         | Suggest                                                | Calls                                                        |
+|---------------------------------------------------------------------|--------------------------------------------------------|--------------------------------------------------------------|
+| Fresh discovery batch waiting / user wants new leads                | "See today's best new leads"                           | leadbay_pull_leads(lensId = pinned)                          |
+| Follow-ups due / known leads to re-engage                           | "Show follow-ups due now"                              | leadbay_pull_followups                                       |
+| Quota/credit read shows low or exhausted balance                    | "Review what's eating your quota"                      | leadbay_account_status (deeper read)                         |
+| Auth/connection blocker (e.g. 401 / AUTH_EXPIRED on a read)         | "Reconnect Leadbay to unblock actions"                 | (guide the user to re-authenticate \u2014 no tool call)           |
+| Lens audience looks mismatched (batch is off-ICP)                   | "Adjust the lens audience to match your ICP"           | ASK first \u2014 collect the target sectors / sizes / exclusions, THEN leadbay_adjust_audience(...) with those params. NEVER call it with no args (an empty call writes the current filter / may clone the default lens \u2014 a no-op or unwanted change). |
+| Status is healthy and nothing is pending                            | propose nothing \u2014 the overview is a complete answer    | \u2014                                                            |
+
 GATE \u2014 DEFER TO TOOL RENDERING. When you call a Leadbay composite that ships its own RENDERING block (every composite in 0.9.0+ does), render the response using that block's recipe verbatim \u2014 score bars, glyph palette, column order, hide-list, link priorities, all of it. Do NOT substitute prose, a numbered list, or a different column structure even when an orchestrating prompt's body suggests alternate framing. Prompt-specific commentary (motivational nudges, summaries, next-action recommendations) belongs ABOVE or BELOW the canonical table, never in place of it.
 
 If the prompt's body and the tool's RENDERING appear to conflict, the tool's RENDERING wins for the structural layout; the prompt's voice wins for the commentary that surrounds it.
@@ -24466,6 +24509,56 @@ function buildServer(client, opts = {}) {
       };
     };
     try {
+      const bootstrapState = opts.bootstrapStatus?.() ?? { done: true };
+      if (!bootstrapState.done) {
+        const url = bootstrapState.signInUrl;
+        const envelope = bootstrapState.failureMessage ? {
+          error: true,
+          code: "AUTH_FAILED",
+          message: "Couldn't sign you in to Leadbay.",
+          hint: `Sign-in failed: ${bootstrapState.failureMessage}
+
+Restart the Leadbay extension in Claude Desktop to retry. If it keeps failing, check your network/region and that Leadbay is reachable.`
+        } : url ? {
+          // Prefer surfacing the live sign-in URL — the spawned MCP process
+          // often can't open a GUI browser itself (no DISPLAY / sanitized
+          // env), so a clickable link the agent renders is the reliable path.
+          error: true,
+          code: "AUTH_REQUIRED",
+          message: "Sign in to Leadbay to finish connecting.",
+          hint: `Open this link to authorize Leadbay, then re-run this tool:
+
+${url}
+
+` + (bootstrapState.openFailed ? "(The extension couldn't open your browser automatically.)" : "(A browser may have opened automatically \u2014 if not, use the link above.)")
+        } : {
+          error: true,
+          code: "AUTH_PENDING",
+          message: "Signing you in to Leadbay \u2014 a browser window should have opened. Authorize there, then try again.",
+          hint: "Complete the Leadbay sign-in in your browser, then re-run this tool."
+        };
+        const pendingText = formatErrorForLLM(envelope);
+        const pendingDur = Date.now() - callStart;
+        telemetry.captureToolCall({
+          tool: name,
+          ok: false,
+          duration_ms: pendingDur,
+          format: "error-envelope",
+          bytes: pendingText.length,
+          error_code: envelope.code,
+          triggered_by
+        });
+        if (DEBUG_ON) {
+          process.stderr.write(
+            `[leadbay-mcp debug] tool=${name} dur=${pendingDur}ms ok=false code=${envelope.code} (auth-bootstrap, no-sentry)
+`
+          );
+        }
+        return {
+          content: [{ type: "text", text: pendingText }],
+          isError: true
+        };
+      }
       if (COMPOSITE_FILE_TOOL_NAMES.has(name) && !triggered_by) {
         const envelope = {
           error: true,
@@ -25597,6 +25690,18 @@ import { createHash as createHash5, randomBytes } from "crypto";
 import { createServer } from "http";
 import { request as httpsRequestRaw } from "https";
 import { spawn as spawn3 } from "child_process";
+import { readdirSync as readdirSync2 } from "fs";
+var LEADBAY_LOOPBACK_PORTS = [51789, 51790, 51791, 51792];
+var BrowserOpenFailedError = class extends Error {
+  authorizeUrl;
+  constructor(authorizeUrl, cause) {
+    super(
+      `Could not open a browser automatically: ${cause?.message ?? cause}`
+    );
+    this.name = "BrowserOpenFailedError";
+    this.authorizeUrl = authorizeUrl;
+  }
+};
 var STARGATE_URLS = {
   prod: "https://stargate.leadbay.app/1.0/user_info",
   staging: "https://staging.stargate.leadbay.app/1.0/user_info"
@@ -25789,13 +25894,24 @@ async function startLoopbackListener(opts) {
     res.end(renderHtml("You're signed in", "You can close this tab and return to the terminal."));
     resolveCallback({ code, state });
   });
-  await new Promise((resolve, reject) => {
-    server.once("error", reject);
-    server.listen(0, "127.0.0.1", () => {
-      server.off("error", reject);
+  const bindPort = async (port) => new Promise((resolve, reject) => {
+    const onErr = (e) => reject(e);
+    server.once("error", onErr);
+    server.listen(port, "127.0.0.1", () => {
+      server.off("error", onErr);
       resolve();
     });
   });
+  let bound = false;
+  for (const port of opts.preferredPorts ?? []) {
+    try {
+      await bindPort(port);
+      bound = true;
+      break;
+    } catch {
+    }
+  }
+  if (!bound) await bindPort(0);
   const addr = server.address();
   const redirectUri = `http://127.0.0.1:${addr.port}/callback`;
   const timer = setTimeout(() => {
@@ -25803,6 +25919,7 @@ async function startLoopbackListener(opts) {
   }, opts.timeoutMs);
   return {
     redirectUri,
+    port: addr.port,
     waitForCallback: () => callbackPromise.finally(() => {
       clearTimeout(timer);
     }),
@@ -25868,28 +25985,79 @@ async function exchangeCodeForToken(opts) {
   }
   return { accessToken: parsed.access_token };
 }
-async function openInBrowser(url) {
+function browserOpenCandidates(url) {
   const platform2 = process.platform;
-  let cmd;
-  let args;
   if (platform2 === "darwin") {
-    cmd = "open";
-    args = [url];
-  } else if (platform2 === "win32") {
-    cmd = "cmd";
-    args = ["/c", "start", '""', url];
-  } else {
-    cmd = "xdg-open";
-    args = [url];
+    return [
+      { cmd: "/usr/bin/open", args: [url] },
+      { cmd: "open", args: [url] }
+    ];
   }
-  await new Promise((resolve, reject) => {
-    const child = spawn3(cmd, args, { stdio: "ignore", detached: true });
-    child.on("error", reject);
-    child.on("spawn", () => {
-      child.unref();
-      resolve();
-    });
-  });
+  if (platform2 === "win32") {
+    const sysRoot = process.env.SystemRoot || process.env.windir || "C:\\Windows";
+    const cmdExe = `${sysRoot}\\System32\\cmd.exe`;
+    return [
+      { cmd: cmdExe, args: ["/c", "start", '""', url] },
+      { cmd: "cmd", args: ["/c", "start", '""', url] }
+    ];
+  }
+  return [
+    { cmd: "/usr/bin/xdg-open", args: [url] },
+    { cmd: "/usr/local/bin/xdg-open", args: [url] },
+    { cmd: "xdg-open", args: [url] }
+  ];
+}
+function browserLaunchEnv(debug) {
+  const env = { ...process.env };
+  if (process.platform !== "linux") return env;
+  const runtimeDir = env.XDG_RUNTIME_DIR;
+  if (!env.WAYLAND_DISPLAY && runtimeDir) {
+    try {
+      const sock = readdirSync2(runtimeDir).find((f) => /^wayland-\d+$/.test(f));
+      if (sock) {
+        env.WAYLAND_DISPLAY = sock;
+        debug?.(`browserLaunchEnv: injected WAYLAND_DISPLAY=${sock}`);
+      }
+    } catch {
+    }
+  }
+  if (!env.DISPLAY) {
+    try {
+      const x = readdirSync2("/tmp/.X11-unix").map((f) => f.match(/^X(\d+)$/)?.[1]).filter((n) => !!n).sort((a, b) => Number(a) - Number(b))[0];
+      env.DISPLAY = x !== void 0 ? `:${x}` : ":0";
+    } catch {
+      env.DISPLAY = ":0";
+    }
+    debug?.(`browserLaunchEnv: injected DISPLAY=${env.DISPLAY}`);
+  }
+  return env;
+}
+async function openInBrowser(url, debug) {
+  const candidates = browserOpenCandidates(url);
+  const launchEnv = browserLaunchEnv(debug);
+  debug?.(
+    `openInBrowser: platform=${process.platform} DISPLAY=${launchEnv.DISPLAY ?? "<unset>"} WAYLAND=${launchEnv.WAYLAND_DISPLAY ?? "<unset>"} DBUS=${launchEnv.DBUS_SESSION_BUS_ADDRESS ? "set" : "<unset>"} candidates=[${candidates.map((c) => c.cmd).join(", ")}]`
+  );
+  let lastErr;
+  for (const { cmd, args } of candidates) {
+    try {
+      await new Promise((resolve, reject) => {
+        const child = spawn3(cmd, args, { stdio: "ignore", detached: true, env: launchEnv });
+        child.on("error", reject);
+        child.on("spawn", () => {
+          debug?.(`spawn OK: ${cmd} (pid=${child.pid})`);
+          child.unref();
+          resolve();
+        });
+      });
+      return;
+    } catch (err) {
+      lastErr = err;
+      debug?.(`spawn FAILED: ${cmd} \u2192 ${err?.code ?? err?.message ?? err}`);
+    }
+  }
+  debug?.(`openInBrowser: ALL candidates failed (lastErr=${lastErr?.message ?? lastErr})`);
+  throw lastErr ?? new Error("no browser launcher available");
 }
 async function oauthLogin(opts) {
   const log = opts.log ?? (() => {
@@ -25902,22 +26070,45 @@ async function oauthLogin(opts) {
   const state = base64UrlEncode(randomBytes(16));
   const pkce = generatePkce();
   log("Starting loopback listener on 127.0.0.1\u2026\n");
-  const listener = await startLoopbackListener({ expectedState: state, timeoutMs });
+  const listener = await startLoopbackListener({
+    expectedState: state,
+    timeoutMs,
+    preferredPorts: LEADBAY_LOOPBACK_PORTS
+  });
   try {
-    log(`Registering client at ${doc.registration_endpoint}\u2026
+    const boundPort = listener.port;
+    let clientId = opts.getCachedClientId?.(boundPort);
+    if (clientId) {
+      log(`Reusing cached OAuth client_id (${clientId}) for port ${boundPort} \u2014 skipping registration.
 `);
-    const client = await registerClient(doc.registration_endpoint, {
-      clientName: opts.clientName,
-      redirectUri: listener.redirectUri,
-      logoUri: opts.logoUri
-    });
+    } else {
+      log(`Registering client at ${doc.registration_endpoint} (redirect ${listener.redirectUri})\u2026
+`);
+      const registered = await registerClient(doc.registration_endpoint, {
+        clientName: opts.clientName,
+        redirectUri: listener.redirectUri,
+        // exact bound-port redirect
+        logoUri: opts.logoUri
+      });
+      clientId = registered.client_id;
+      try {
+        opts.onClientRegistered?.(clientId, boundPort);
+      } catch {
+      }
+    }
     const authorizeUrl = new URL(doc.authorization_endpoint);
     authorizeUrl.searchParams.set("response_type", "code");
-    authorizeUrl.searchParams.set("client_id", client.client_id);
+    authorizeUrl.searchParams.set("client_id", clientId);
     authorizeUrl.searchParams.set("redirect_uri", listener.redirectUri);
     authorizeUrl.searchParams.set("state", state);
     authorizeUrl.searchParams.set("code_challenge", pkce.challenge);
     authorizeUrl.searchParams.set("code_challenge_method", pkce.method);
+    if (opts.onAuthorizeUrl) {
+      try {
+        opts.onAuthorizeUrl(authorizeUrl.toString());
+      } catch {
+      }
+    }
     log(`Opening browser to authorize\u2026
   ${authorizeUrl.toString()}
 `);
@@ -25929,6 +26120,9 @@ async function oauthLogin(opts) {
   ${authorizeUrl.toString()}
 `
       );
+      if (opts.failFastOnOpenError) {
+        throw new BrowserOpenFailedError(authorizeUrl.toString(), err);
+      }
     }
     log("Waiting for authorization (5 min timeout)\u2026\n");
     const { code } = await listener.waitForCallback();
@@ -25937,7 +26131,7 @@ async function oauthLogin(opts) {
       tokenEndpoint: doc.token_endpoint,
       code,
       codeVerifier: pkce.verifier,
-      clientId: client.client_id,
+      clientId,
       redirectUri: listener.redirectUri
     });
     return { accessToken };
@@ -25958,7 +26152,7 @@ var OAUTH_BASE_URLS = {
     fr: "https://staging.api.leadbay.app"
   }
 };
-var VERSION = "0.21.1";
+var VERSION = "0.21.2";
 var HELP = `
 leadbay-mcp ${VERSION} \u2014 Leadbay Model Context Protocol server
 
@@ -26087,8 +26281,65 @@ function resolveOAuthBootstrapCredentialsPath() {
     legacy: resolved.legacy
   };
 }
+var pendingSignInUrl;
+var browserOpenFailedAtBootstrap = false;
+var bootstrapFailureMessage;
+function bootstrapDebug(msg) {
+  try {
+    const { appendFileSync, mkdirSync } = require_("node:fs");
+    const { join: join4 } = require_("node:path");
+    const { homedir: homedir5 } = require_("node:os");
+    const dir = join4(homedir5(), ".leadbay");
+    mkdirSync(dir, { recursive: true });
+    const ts = (/* @__PURE__ */ new Date()).toISOString();
+    appendFileSync(join4(dir, "oauth-bootstrap-debug.log"), `${ts} [pid ${process.pid}] ${msg}
+`);
+  } catch {
+  }
+}
+function oauthClientCachePath() {
+  const { join: join4 } = require_("node:path");
+  const { homedir: homedir5 } = require_("node:os");
+  return join4(homedir5(), ".leadbay", "oauth-client.json");
+}
+function getCachedOAuthClientId(authServerBaseUrl, port) {
+  try {
+    const { readFileSync: readFileSync3 } = require_("node:fs");
+    const parsed = JSON.parse(readFileSync3(oauthClientCachePath(), "utf8"));
+    const byPort = parsed?.clients?.[authServerBaseUrl]?.byPort;
+    const id = byPort?.[String(port)];
+    return typeof id === "string" && id.length > 0 ? id : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function cacheOAuthClientId(authServerBaseUrl, clientId, port) {
+  try {
+    const { readFileSync: readFileSync3, writeFileSync, mkdirSync } = require_("node:fs");
+    const { dirname: dirname3 } = require_("node:path");
+    const path = oauthClientCachePath();
+    let data = { clients: {} };
+    try {
+      data = JSON.parse(readFileSync3(path, "utf8"));
+      if (!data || typeof data !== "object" || typeof data.clients !== "object") data = { clients: {} };
+    } catch {
+    }
+    const server = data.clients[authServerBaseUrl];
+    const byPort = server && typeof server === "object" && server.byPort && typeof server.byPort === "object" ? server.byPort : {};
+    byPort[String(port)] = clientId;
+    data.clients[authServerBaseUrl] = { byPort };
+    mkdirSync(dirname3(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(data, null, 2) + "\n", { mode: 384 });
+  } catch {
+  }
+}
+var browserOpenInFlight = null;
+var bootstrapInFlight = null;
 async function bootstrapOAuthIfMissing(logger) {
   if (process.env.LEADBAY_TOKEN) return false;
+  bootstrapDebug(
+    `bootstrap START \u2014 clientName=Leadbay MCP, REGION=${process.env.LEADBAY_REGION ?? "<unset>"} BASE_URL=${process.env.LEADBAY_BASE_URL ?? "<unset>"}`
+  );
   const { hostname } = await import("os");
   process.stderr.write(
     `
@@ -26124,7 +26375,49 @@ async function bootstrapOAuthIfMissing(logger) {
     const { accessToken } = await oauthLogin({
       authServerBaseUrl,
       clientName: `Leadbay MCP @ ${hostname()}`,
-      log: (m) => process.stderr.write(m)
+      log: (m) => process.stderr.write(m),
+      // The moment the URL is known: (1) stash it so the AUTH_PENDING envelope
+      // surfaces a clickable link (reliable fallback), and (2) fire the browser
+      // auto-open OURSELVES, tracked in browserOpenInFlight so shutdown waits
+      // for the spawn to dispatch. This wins the install-time race: Claude
+      // Desktop probes a fresh extension with <100ms connect→shutdown cycles,
+      // and tracking the open lets us finish dispatching the detached child
+      // even if SIGTERM/stdin-end arrives first. We pass our own opener as
+      // `openBrowser` so oauthLogin doesn't ALSO open (no double tab).
+      onAuthorizeUrl: (url) => {
+        pendingSignInUrl = url;
+        bootstrapDebug(`authorize URL ready \u2014 spawning browser open`);
+        browserOpenInFlight = openInBrowser(url, bootstrapDebug).then(() => {
+          bootstrapDebug(`auto-open dispatched OK`);
+        }).catch((err) => {
+          browserOpenFailedAtBootstrap = true;
+          bootstrapDebug(`auto-open FAILED: ${err?.message ?? err}`);
+          process.stderr.write(
+            `[leadbay-mcp] auto-open browser failed (${err?.message ?? err}); user has the sign-in link.
+`
+          );
+        }).finally(() => {
+          browserOpenInFlight = null;
+        });
+      },
+      // No-op: we drive the open from onAuthorizeUrl (tracked) instead, so the
+      // shutdown race can be handled. Returning resolved means oauthLogin won't
+      // try its own open or hit the fail-fast path.
+      openBrowser: async () => {
+      },
+      // Reuse a cached client_id (keyed by auth server + loopback port) so we
+      // register at most once — avoids the 429 from re-registering on every
+      // probe-restart. Port is part of the key because the backend pins the
+      // exact redirect_uri (port included).
+      getCachedClientId: (port) => {
+        const id = getCachedOAuthClientId(authServerBaseUrl, port);
+        if (id) bootstrapDebug(`reusing cached client_id=${id} (port ${port}) for ${authServerBaseUrl}`);
+        return id;
+      },
+      onClientRegistered: (id, port) => {
+        bootstrapDebug(`registered new client_id=${id} (port ${port}) \u2014 caching for ${authServerBaseUrl}`);
+        cacheOAuthClientId(authServerBaseUrl, id, port);
+      }
     });
     try {
       const { writeFileSync, mkdirSync, chmodSync } = require_("node:fs");
@@ -26161,12 +26454,27 @@ async function bootstrapOAuthIfMissing(logger) {
     process.env.LEADBAY_TOKEN = accessToken;
     process.env.LEADBAY_REGION = region;
     if (isStaging || envBaseUrl) process.env.LEADBAY_BASE_URL = authServerBaseUrl;
+    pendingSignInUrl = void 0;
+    bootstrapDebug(`bootstrap COMPLETE \u2014 token acquired, region=${region}`);
     logger.info?.(`OAuth bootstrap complete \u2014 region=${region}`);
     return true;
   } catch (err) {
+    if (err instanceof BrowserOpenFailedError) {
+      browserOpenFailedAtBootstrap = true;
+      process.stderr.write(
+        `[leadbay-mcp] Could not open a browser automatically: ${err.message}
+  The sign-in link is surfaced to the user via the AUTH_PENDING envelope.
+`
+      );
+      return false;
+    }
+    const message = err?.message ?? String(err);
+    bootstrapFailureMessage = message;
+    pendingSignInUrl = void 0;
+    bootstrapDebug(`bootstrap FAILED (non-open): ${message}`);
     process.stderr.write(
-      `[leadbay-mcp] OAuth bootstrap failed: ${err?.message ?? err}
-  The server will start but tools will return AUTH_MISSING until you authorize.
+      `[leadbay-mcp] OAuth bootstrap failed: ${message}
+  Tools will return AUTH_FAILED until you restart the extension to retry.
 `
     );
     return false;
@@ -26176,30 +26484,16 @@ async function resolveClientFromEnv(logger) {
   if (process.env.LEADBAY_OAUTH_BOOTSTRAP === "1") {
     hydrateEnvFromCredentialsFile();
     if (!process.env.LEADBAY_TOKEN) {
-      await bootstrapOAuthIfMissing(logger);
+      const regionEnv2 = process.env.LEADBAY_REGION;
+      const region = regionEnv2 === "fr" ? "fr" : "us";
+      const config = { region };
+      if (process.env.LEADBAY_BASE_URL) config.baseUrl = process.env.LEADBAY_BASE_URL;
+      logger.info?.("OAuth bootstrap pending \u2014 server will come up unauthenticated, OAuth runs in background");
+      return { client: createClient(config), authState: "pending" };
     }
   }
   const token = process.env.LEADBAY_TOKEN;
   if (!token) {
-    if (process.env.LEADBAY_OAUTH_BOOTSTRAP === "1") {
-      process.stderr.write(
-        "leadbay-mcp: OAuth authorization is required but no token is available.\n  Restart the Claude Desktop extension to authorize Leadbay in your browser.\n\nRun `leadbay-mcp --help` for the full config template.\n"
-      );
-      const regionEnv3 = process.env.LEADBAY_REGION;
-      const region2 = regionEnv3 === "fr" ? "fr" : "us";
-      return {
-        client: makeBrokenClient(
-          {
-            error: true,
-            code: "AUTH_MISSING",
-            message: "Leadbay OAuth authorization has not completed.",
-            hint: "Restart the Claude Desktop extension and complete the Leadbay OAuth browser authorization."
-          },
-          region2
-        ),
-        authState: "missing"
-      };
-    }
     process.stderr.write(
       "leadbay-mcp: LEADBAY_TOKEN environment variable is required.\n  1. Run: npx -y @leadbay/mcp install --oauth\n  2. Set it in your MCP client config (e.g. claude_desktop_config.json).\n\nRun `leadbay-mcp --help` for the full config template.\n"
     );
@@ -27030,7 +27324,8 @@ async function main() {
   installStartupSafetyNets(logger);
   const telemetry = initTelemetry({ version: VERSION, logger });
   const { client, authState } = await resolveClientFromEnv(logger);
-  telemetry.identify(client);
+  const bootstrapPending = authState === "pending";
+  if (!bootstrapPending) telemetry.identify(client);
   telemetry.captureStartup({
     auth_state: authState,
     region: client.region
@@ -27078,14 +27373,71 @@ async function main() {
     notificationsInbox,
     version: VERSION,
     telemetry,
-    updateStateStore
+    updateStateStore,
+    // Non-blocking OAuth bootstrap gate. Read per tool call: once the
+    // background flow lands the token (client.isAuthenticated → true) this
+    // reports done and tools execute. While waiting it surfaces the live
+    // sign-in URL (captured via onAuthorizeUrl) so the agent can render a
+    // clickable link — the reliable path when the spawned process can't open
+    // a browser itself.
+    bootstrapStatus: bootstrapPending ? () => client.isAuthenticated ? { done: true } : {
+      done: false,
+      signInUrl: pendingSignInUrl,
+      openFailed: browserOpenFailedAtBootstrap,
+      failureMessage: bootstrapFailureMessage
+    } : void 0
   });
   const transport = new StdioServerTransport();
   logger.info?.(
     `Starting MCP server v${VERSION} (advanced=${includeAdvanced}, write=${includeWrite}, baseUrl=${client.baseUrl}, bulk_store=${bulkTracker.durability}, notifications_ws=${WS_DISABLED ? "disabled" : "enabled"}, auth_state=${authState})`
   );
   await server.connect(transport);
+  if (bootstrapPending) {
+    bootstrapDebug(`server connected; launching background OAuth bootstrap`);
+    bootstrapInFlight = (async () => {
+      const ok = await bootstrapOAuthIfMissing(logger);
+      if (!ok) return;
+      const region = process.env.LEADBAY_REGION === "fr" ? "fr" : "us";
+      const apiBaseUrl = process.env.LEADBAY_BASE_URL ?? REGIONS[region];
+      client.setBaseUrl(apiBaseUrl, region);
+      client.setToken(process.env.LEADBAY_TOKEN);
+      logger.info?.(`OAuth bootstrap landed \u2014 client authenticated (region=${region})`);
+      telemetry.identify(client);
+      if (process.env.LEADBAY_NOTIFICATIONS_WS_DISABLED !== "1" && !notificationsWs) {
+        notificationsWs = new NotificationsWsClient({
+          client,
+          inbox: notificationsInbox,
+          logger
+        });
+        void notificationsWs.start().catch((err) => {
+          logger.warn?.(`notifications.ws start_failed (post-oauth): ${err?.message ?? err}`);
+        });
+      }
+    })().catch((err) => {
+      logger.warn?.(`oauth.bootstrap_bg_failed ${err?.message ?? err}`);
+    });
+  }
   const shutdown = async (code) => {
+    if (bootstrapInFlight && !client.isAuthenticated) {
+      bootstrapDebug(`shutdown(code=${code}) while bootstrap in flight \u2014 waiting up to 4s for URL/open`);
+      try {
+        await Promise.race([
+          bootstrapInFlight,
+          new Promise((r) => setTimeout(r, 4e3))
+        ]);
+      } catch {
+      }
+    }
+    if (browserOpenInFlight) {
+      bootstrapDebug(`shutdown(code=${code}) browser-open still in flight \u2014 waiting up to 1.5s`);
+      try {
+        await Promise.race([
+          browserOpenInFlight,
+          new Promise((r) => setTimeout(r, 1500))
+        ]);
+      } catch {
+      }
+    }
     try {
       notificationsWs?.stop();
     } catch {
@@ -27131,10 +27483,12 @@ export {
   buildClaudeCodeRemoveArgs,
   buildCodexConfigBlock,
   buildShellExportBlock,
+  cacheOAuthClientId,
   checkLoginCollision,
   computeFreshDefaultPath,
   detectClaudeDesktopMode,
   formatInstallOsLabel,
+  getCachedOAuthClientId,
   installInClaudeCode,
   installInCodexConfig,
   installInJsonConfig,