@leadbay/mcp 0.21.0 → 0.21.2

package/dist/bin.js

@@ -10828,6 +10828,13 @@ function coerceCell(client, v, path) {
     return String(v);
   throw client.makeError("IMPORT_INVALID_CELL_TYPE", `Cell at ${path} is ${Array.isArray(v) ? "an array" : typeof v}, expected string|number|boolean|null`, `Convert the value to a string before passing.`, "POST /imports");
 }
+function enforceLeadStatus(client, raw, path) {
+  const canonical = String(raw).trim().toUpperCase();
+  if (!LEAD_STATUS_SET.has(canonical)) {
+    throw client.makeError("IMPORT_INVALID_STATUS", `${path} ${JSON.stringify(raw)} is not a valid lead status`, `Use one of ${LEAD_STATUSES.join(", ")} (case-insensitive), or omit it.`, "POST /imports");
+  }
+  return canonical;
+}
 function prepareDomainsMode(client, inputs) {
   const validInputs = [];
   const malformedDomains = [];
@@ -10949,6 +10956,12 @@ function prepareRecordsMode(client, records, mappings, customFieldCatalog) {
     if (normDomain && !byDomain.has(normDomain))
       byDomain.set(normDomain, idx);
   });
+  const statuses = {};
+  for (const [cell, status] of Object.entries(mappings.statuses ?? {})) {
+    statuses[cell] = enforceLeadStatus(client, status, `mappings.statuses[${JSON.stringify(cell)}]`);
+  }
+  const rawDefault = mappings.default_status;
+  const default_status = rawDefault == null || String(rawDefault).trim() === "" ? null : enforceLeadStatus(client, rawDefault, "mappings.default_status");
   return {
     mode: "records",
     validInputs,
@@ -10958,8 +10971,8 @@ function prepareRecordsMode(client, records, mappings, customFieldCatalog) {
     header,
     mappings: {
       fields: { ...normalizedFields },
-      statuses: mappings.statuses ?? {},
-      default_status: mappings.default_status ?? null
+      statuses,
+      default_status
     }
   };
 }
@@ -11334,7 +11347,7 @@ async function runImportInBackground(client, prep, uploadedChunks, opts, ctx, ha
     })();
   }, 0);
 }
-var CHUNK_SIZE, POLL_INTERVAL_MS2, DEFAULT_PER_PHASE_BUDGET_MS, DEFAULT_TOTAL_BUDGET_MS, STABILIZATION_POLLS, MAX_COLUMN_NAME_LEN, RESERVED_COLUMN_RE, CUSTOM_FIELD_RE, IMPORT_RESOLVER_FIELDS, PUBLIC_MAILBOX_DOMAINS, importLeads;
+var CHUNK_SIZE, POLL_INTERVAL_MS2, DEFAULT_PER_PHASE_BUDGET_MS, DEFAULT_TOTAL_BUDGET_MS, STABILIZATION_POLLS, MAX_COLUMN_NAME_LEN, RESERVED_COLUMN_RE, CUSTOM_FIELD_RE, IMPORT_RESOLVER_FIELDS, PUBLIC_MAILBOX_DOMAINS, LEAD_STATUSES, LEAD_STATUS_SET, importLeads;
 var init_import_leads = __esm({
   "../core/dist/composite/import-leads.js"() {
     "use strict";
@@ -11379,6 +11392,15 @@ var init_import_leads = __esm({
       "163.com",
       "126.com"
     ]);
+    LEAD_STATUSES = [
+      "DEFAULT",
+      "INBOUND",
+      "UNWANTED",
+      "WANTED",
+      "LOST",
+      "WON"
+    ];
+    LEAD_STATUS_SET = new Set(LEAD_STATUSES);
     importLeads = {
       name: "leadbay_import_leads",
       annotations: {
@@ -11437,11 +11459,12 @@ var init_import_leads = __esm({
               },
               statuses: {
                 type: "object",
-                description: "Optional status string mapping (rarely needed). Defaults to {}."
+                description: `Optional map of raw CSV status-cell text \u2192 lead status (rarely needed). Keys are the verbatim cell strings; values must be one of ${LEAD_STATUSES.join(", ")} (case-insensitive). Defaults to {}.`
               },
               default_status: {
                 type: ["string", "null"],
-                description: "Optional default status. Defaults to null."
+                enum: [...LEAD_STATUSES, null],
+                description: `Optional default lead status applied to rows without an explicit status. One of ${LEAD_STATUSES.join(", ")} (case-insensitive). Defaults to null.`
               }
             },
             required: ["fields"]
@@ -17499,8 +17522,15 @@ var init_import_and_qualify = __esm({
                 type: "object",
                 description: "Ergonomic shorthand: `{CsvColumn: <number-id>}` or `{CsvColumn: '<field-name>'}` for custom-field mappings. Resolved against /crm/custom_fields catalog."
               },
-              statuses: { type: "object", description: "Optional status string mapping." },
-              default_status: { type: ["string", "null"], description: "Optional default status." }
+              statuses: {
+                type: "object",
+                description: `Optional map of raw CSV status-cell text \u2192 lead status. Values must be one of ${LEAD_STATUSES.join(", ")} (case-insensitive); keys are the verbatim cell strings.`
+              },
+              default_status: {
+                type: ["string", "null"],
+                enum: [...LEAD_STATUSES, null],
+                description: `Optional default lead status. One of ${LEAD_STATUSES.join(", ")} (case-insensitive).`
+              }
             },
             // mappings has a closed shape (fields/custom_fields/statuses/default_status).
             // Inner objects (fields, custom_fields, statuses) keep open shapes
@@ -22461,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.
@@ -24436,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,
@@ -25567,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"
@@ -25759,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(() => {
@@ -25773,6 +25919,7 @@ async function startLoopbackListener(opts) {
   }, opts.timeoutMs);
   return {
     redirectUri,
+    port: addr.port,
     waitForCallback: () => callbackPromise.finally(() => {
       clearTimeout(timer);
     }),
@@ -25838,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 ?? (() => {
@@ -25872,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()}
 `);
@@ -25899,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();
@@ -25907,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 };
@@ -25928,7 +26152,7 @@ var OAUTH_BASE_URLS = {
     fr: "https://staging.api.leadbay.app"
   }
 };
-var VERSION = "0.21.0";
+var VERSION = "0.21.2";
 var HELP = `
 leadbay-mcp ${VERSION} \u2014 Leadbay Model Context Protocol server
 
@@ -26057,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(
     `
@@ -26094,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");
@@ -26131,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;
@@ -26146,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"
     );
@@ -27000,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
@@ -27048,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 {
@@ -27101,10 +27483,12 @@ export {
   buildClaudeCodeRemoveArgs,
   buildCodexConfigBlock,
   buildShellExportBlock,
+  cacheOAuthClientId,
   checkLoginCollision,
   computeFreshDefaultPath,
   detectClaudeDesktopMode,
   formatInstallOsLabel,
+  getCachedOAuthClientId,
   installInClaudeCode,
   installInCodexConfig,
   installInJsonConfig,