fix(mcp): Windows .dxt sign-in browser now opens reliably (product#3839) (#139)

* fix(mcp): Windows .dxt sign-in browser now opens reliably (product#3839)

On Windows, openInBrowser resolved the moment cmd.exe was CREATED — before
its `start` builtin actually handed the URL to the browser. A silent no-op
(no default-browser association / a locked-down shell / AppLocker) went
undetected: nothing opened yet the flow reported success and told the user
"a browser may have opened."

Windows now waits (bounded) for each launcher's exit code, treats a non-zero
exit as failure, and falls through to shell-free launchers — rundll32
url.dll,FileProtocolHandler (Explorer's ShellExecute path, honest exit code)
then PowerShell Start-Process. When all fail, browserOpenFailedAtBootstrap is
set and the AUTH_REQUIRED envelope honestly says the browser couldn't open,
with the clickable sign-in link. macOS/Linux keep resolve-on-spawn (the #3805
headless-hang fix). The #3801 &-quoting cmd candidate is unchanged, tried
first. Shutdown browser-open wait 1.5s -> 3s for the multi-launcher walk.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(mcp): quote PowerShell fallback URL so `&` isn't parsed as PS source

The PowerShell Start-Process fallback passed the raw URL after `-Command`, which
parses everything as PowerShell SOURCE — so an OAuth authorize URL's `&` (query
separators) would be read as PS's call/separator operator and the URL mangled or
split, breaking the last recovery path on locked-down Windows (both cmd
candidates failed + rundll32 unavailable). Wrap the URL in a single-quoted PS
string literal (verbatim form; escape embedded `'` by doubling). rundll32 keeps
the raw URL (no shell). New test covers the multi-`&` URL and the quote-escape.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: ArtyETH06

packages/mcp/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog — @leadbay/mcp
 
+## 0.23.11 — 2026-07-02
+
+Windows `.dxt` sign-in now opens the browser reliably (product#3839).
+
+- **`openInBrowser` (Windows)** — the auto-open resolved the moment `cmd.exe` was *created*, before its internal `start` builtin actually handed the URL to the default browser. So a silent no-op (no default-browser protocol association, a locked-down shell / AppLocker, a corrupt `HKCR\http\shell\open`) went undetected: `browserOpenFailedAtBootstrap` stayed false and the user was told "a browser may have opened" when nothing did. On Windows we now wait (bounded — 800ms for `cmd start`, 1200ms otherwise) for the launcher's **exit code**, treat a non-zero exit as failure, and fall through to `rundll32 url.dll,FileProtocolHandler` (no command interpreter — the same ShellExecute path Explorer uses, with an honest exit code) and finally PowerShell `Start-Process`. When every launcher fails, the `AUTH_REQUIRED` envelope honestly says the browser couldn't be opened and shows the clickable sign-in link. The #3801 `&`-quoting `cmd start` candidate is unchanged and still tried first. macOS/Linux keep resolve-on-`spawn` (the #3805 headless-hang fix — those launchers are the hand-off).
+- **`bin.ts` shutdown** — the `browserOpenInFlight` teardown wait rose 1.5s → 3s so the multi-launcher Windows walk can finish dispatching before exit (the sibling bootstrap wait already allows 4s; the surfaced sign-in link is the fallback either way).
+
 ## 0.23.10 — 2026-07-01
 
 A freshly-created lens no longer reads as "empty" (product#3833).

packages/mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leadbay/mcp",
-  "version": "0.23.10",
+  "version": "0.23.11",
   "mcpName": "io.github.leadbay/leadbay-mcp",
   "description": "Model Context Protocol (MCP) server for Leadbay — AI lead discovery, qualification, and enrichment for Claude Desktop, Cursor, and Claude Code.",
   "type": "module",

packages/mcp/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.leadbay/leadbay-mcp",
   "title": "Leadbay",
   "description": "AI lead discovery, qualification, and outreach prep on your Leadbay account.",
-  "version": "0.23.10",
+  "version": "0.23.11",
   "repository": {
     "url": "https://github.com/leadbay/mcp",
     "source": "github",
@@ -15,7 +15,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@leadbay/mcp",
-      "version": "0.23.10",
+      "version": "0.23.11",
       "transport": {
         "type": "stdio"
       },

packages/mcp/src/bin.ts

@@ -1765,11 +1765,16 @@ async function main(): Promise<void> {
       }
     }
     if (browserOpenInFlight) {
-      bootstrapDebug(`shutdown(code=${code}) browser-open still in flight — waiting up to 1.5s`);
+      // 3s (was 1.5s): on Windows openInBrowser now waits for each launcher's
+      // exit code and may walk cmd → rundll32 before one succeeds (#3839), so
+      // the dispatch can take longer than a single spawn. Best-effort during
+      // teardown; the sibling bootstrapInFlight race already waits 4s, and the
+      // surfaced sign-in link remains the fallback if we're still cut off.
+      bootstrapDebug(`shutdown(code=${code}) browser-open still in flight — waiting up to 3s`);
       try {
         await Promise.race([
           browserOpenInFlight,
-          new Promise((r) => setTimeout(r, 1500)),
+          new Promise((r) => setTimeout(r, 3000)),
         ]);
       } catch {
         // ignore — best-effort; the surfaced sign-in link is the fallback

packages/mcp/src/oauth.ts

@@ -558,6 +558,47 @@ export function browserOpenCandidates(url: string): Array<{ cmd: string; args: s
   ];
 }
 
+/**
+ * Windows-only SECOND-CHANCE launchers, tried by openInBrowser after every
+ * `cmd /c start` candidate above has failed (issue #3839).
+ *
+ * Why a separate list rather than more entries in browserOpenCandidates(): the
+ * `cmd start` candidates all end in a double-quoted `"<url>"` (the #3801
+ * fix, pinned by a regression test). These launchers take the URL as a RAW,
+ * unquoted single argument — mixing the two shapes in one list is confusing and
+ * would break that test's "every candidate is quoted" invariant. Keeping them
+ * apart also makes the intent explicit: cmd first (fast, familiar), these only
+ * when cmd silently no-ops.
+ *
+ *   1. rundll32 url.dll,FileProtocolHandler <url> — the same ShellExecute path
+ *      Explorer uses. No command interpreter, so no `&`-truncation and no
+ *      quoting dance; returns a non-zero exit when the protocol handler can't
+ *      be invoked, so openInBrowser's exit-wait DETECTS the failure. This is
+ *      the launcher that recovers #3839 when `cmd start` no-ops (no
+ *      default-browser association / a locked-down shell / AppLocker).
+ *   2. powershell Start-Process <url> — heavy (spins a PS runtime) and may be
+ *      blocked in locked-down orgs (constrained language mode / AppLocker), so
+ *      it's the last resort; where present it gives a reliable exit code.
+ *      -NoProfile/-NonInteractive keep it from sourcing a profile or prompting.
+ */
+export function windowsFallbackCandidates(url: string): Array<{ cmd: string; args: string[] }> {
+  const sysRoot = process.env.SystemRoot || process.env.windir || "C:\\Windows";
+  // `-Command` parses everything after it as PowerShell SOURCE, not literal
+  // args — so a raw OAuth URL (`…?a=1&b=2`) would have its `&` read as PS's
+  // call/separator operator and the URL would be mangled or split. Wrap it in a
+  // single-quoted PS string literal (the verbatim form: `&`, spaces, `?`, `=`
+  // are all inert inside `'…'`), escaping any embedded `'` by doubling it per
+  // PS convention. windowsVerbatimArguments at spawn keeps these quotes intact.
+  const psLiteral = `'${url.replace(/'/g, "''")}'`;
+  return [
+    { cmd: `${sysRoot}\\System32\\rundll32.exe`, args: ["url.dll,FileProtocolHandler", url] },
+    {
+      cmd: `${sysRoot}\\System32\\WindowsPowerShell\\v1.0\\powershell.exe`,
+      args: ["-NoProfile", "-NonInteractive", "-Command", "Start-Process", psLiteral],
+    },
+  ];
+}
+
 /**
  * Build the env to spawn the browser launcher with. On Linux, Claude Desktop
  * spawns the .dxt server with an INCONSISTENT environment — DISPLAY and
@@ -672,7 +713,13 @@ export async function openInBrowser(
   //
   // Try each candidate in order; only the LAST ENOENT propagates. This makes
   // the launch independent of the inherited PATH (see browserOpenCandidates).
-  const candidates = browserOpenCandidates(url);
+  // On Windows, append the shell-free second-chance launchers: the exit-wait
+  // below turns a silent `cmd start` no-op into a detected failure that falls
+  // through to rundll32 / PowerShell (issue #3839).
+  const candidates =
+    process.platform === "win32"
+      ? [...browserOpenCandidates(url), ...windowsFallbackCandidates(url)]
+      : browserOpenCandidates(url);
   const launchEnv = browserLaunchEnv(debug);
   debug?.(
     `openInBrowser: platform=${process.platform} ` +
@@ -685,17 +732,66 @@ export async function openInBrowser(
   for (const { cmd, args } of candidates) {
     try {
       await new Promise<void>((resolve, reject) => {
-        const spawnOpts: SpawnOptions = { stdio: "ignore", detached: true, env: launchEnv };
+        const isWin = process.platform === "win32";
+        // POSIX: detach + unref so the browser opener outlives us — `open` /
+        // `xdg-open` ARE the hand-off and return immediately, so resolving on
+        // `spawn` is correct (and load-bearing: #3805 deliberately moved OFF
+        // waiting for `close`, which a detached child often never emits, to
+        // stop the installer hanging in headless hosts). Windows: do NOT
+        // detach — we now observe the child's EXIT to detect a silent no-op
+        // (#3839), and a detached Win child in its own group only makes that
+        // harder and risks a console flash.
+        const spawnOpts: SpawnOptions = { stdio: "ignore", detached: !isWin, env: launchEnv };
         // On Windows the candidate args carry a pre-quoted "<url>" (see
         // browserOpenCandidates); verbatim mode stops Node's arg-quoter from
         // mangling those quotes, so cmd sees the whole URL as one token.
-        if (process.platform === "win32") spawnOpts.windowsVerbatimArguments = true;
+        if (isWin) spawnOpts.windowsVerbatimArguments = true;
         const child = spawn(cmd, args, spawnOpts);
         child.on("error", reject);
-        child.on("spawn", () => {
-          debug?.(`spawn OK: ${cmd} (pid=${child.pid})`);
+
+        if (!isWin) {
+          // mac/Linux: resolve the moment the opener is spawned, then detach.
+          child.on("spawn", () => {
+            debug?.(`spawn OK: ${cmd} (pid=${child.pid})`);
+            child.unref();
+            resolve();
+          });
+          return;
+        }
+
+        // Windows: `"spawn"` only means cmd/rundll32/powershell was CREATED —
+        // the real browser hand-off happens INSIDE it and can no-op / exit
+        // non-zero. So wait (bounded) for the exit code:
+        //   exit 0 (or null)     → launched OK → success
+        //   non-zero exit        → failed → fall through to the next candidate
+        //   no exit by the budget → still running → assume it dispatched + resolve
+        // `cmd start` gets a tighter budget (it normally returns instantly — a
+        // stall there is anomalous) so we reach rundll32 fast enough to stay
+        // inside shutdown()'s browserOpenInFlight wait.
+        const isCmd = /cmd(\.exe)?$/i.test(cmd);
+        const budgetMs = isCmd ? 800 : 1200;
+        let settled = false;
+        const finish = (fn: () => void) => {
+          if (settled) return;
+          settled = true;
+          fn();
+        };
+        const timer = setTimeout(() => {
+          debug?.(`exit-wait timeout (${budgetMs}ms): ${cmd} — assuming launched`);
           child.unref();
-          resolve();
+          finish(resolve);
+        }, budgetMs);
+        timer.unref?.();
+        child.on("spawn", () => debug?.(`spawn OK: ${cmd} (pid=${child.pid}) — awaiting exit`));
+        child.on("exit", (code) => {
+          clearTimeout(timer);
+          if (code === 0 || code === null) {
+            debug?.(`exit ${code}: ${cmd} — launched OK`);
+            finish(resolve);
+          } else {
+            debug?.(`exit ${code}: ${cmd} — treating as failed, next candidate`);
+            finish(() => reject(new Error(`${cmd} exited ${code}`)));
+          }
         });
       });
       return; // launched successfully

packages/mcp/test/unit/oauth-browser-open-win32-candidates.test.ts

@@ -0,0 +1,127 @@
+/**
+ * Regression tests for OAuth-broken-on-Windows, part 2 (issue #3839).
+ *
+ * The #3801 fix quoted the URL so `cmd start` wouldn't truncate it at `&`. But
+ * `cmd` ALWAYS spawns (fixed path), and its `start` builtin does the real
+ * browser hand-off — which can silently no-op (no default-browser protocol
+ * association / a locked-down shell) while spawn still reports success. So the
+ * browser never opened and the fallback never fired.
+ *
+ * Fix pinned here: two shell-free second-chance launchers live in a SEPARATE
+ * list, windowsFallbackCandidates(), which openInBrowser tries only after every
+ * `cmd start` candidate has failed the exit-wait (see the exit-wait test):
+ *   1. rundll32 url.dll,FileProtocolHandler <url>   — Explorer's ShellExecute
+ *      path, no command interpreter (no `&` hazard, raw URL), honest exit code.
+ *   2. powershell -NoProfile -NonInteractive -Command Start-Process <url>
+ *      — heavy last resort with a reliable exit code.
+ * They're kept OUT of browserOpenCandidates() so the #3801-pinned "every win32
+ * candidate ends in a quoted URL" invariant stays intact.
+ *
+ * New file — the existing oauth-browser-open.test.ts / -win32-url.test.ts pins
+ * are left untouched.
+ */
+import { describe, it, expect, afterEach } from "vitest";
+import { browserOpenCandidates, windowsFallbackCandidates } from "../../src/oauth.js";
+
+const AUTH_URL =
+  "https://leadbay.app/oauth/authorize?client_id=99" +
+  "&code_challenge=abc123&code_challenge_method=S256&state=xyz789" +
+  "&redirect_uri=http%3A%2F%2F127.0.0.1%3A51789%2Fcallback";
+
+const realPlatform = process.platform;
+function setPlatform(p: NodeJS.Platform) {
+  Object.defineProperty(process, "platform", { value: p, configurable: true });
+}
+afterEach(() => setPlatform(realPlatform));
+
+describe("browserOpenCandidates — win32 head is still just the #3801 cmd pair", () => {
+  it("returns exactly the two `cmd start` candidates (no shell-free launchers mixed in)", () => {
+    setPlatform("win32");
+    const savedRoot = process.env.SystemRoot;
+    process.env.SystemRoot = "C:\\Windows";
+    try {
+      const cands = browserOpenCandidates(AUTH_URL);
+      expect(cands).toHaveLength(2);
+      // Every candidate ends in the double-quoted URL — the invariant the
+      // #3801 regression test loops over. Appending raw-URL launchers HERE
+      // would break it; that's why they live in windowsFallbackCandidates.
+      for (const c of cands) {
+        expect(c.args[c.args.length - 1]).toBe(`"${AUTH_URL}"`);
+      }
+    } finally {
+      if (savedRoot === undefined) delete process.env.SystemRoot;
+      else process.env.SystemRoot = savedRoot;
+    }
+  });
+});
+
+describe("windowsFallbackCandidates — shell-free second-chance launchers (#3839)", () => {
+  it("returns rundll32 then powershell, both with the RAW (unquoted) URL", () => {
+    const savedRoot = process.env.SystemRoot;
+    process.env.SystemRoot = "C:\\Windows";
+    try {
+      const cands = windowsFallbackCandidates(AUTH_URL);
+      expect(cands).toHaveLength(2);
+
+      // 1: rundll32 with the raw URL as one literal arg — no shell, so no
+      // quoting dance and no `&`-truncation hazard.
+      expect(cands[0]).toEqual({
+        cmd: "C:\\Windows\\System32\\rundll32.exe",
+        args: ["url.dll,FileProtocolHandler", AUTH_URL],
+      });
+      expect(cands[0].args[cands[0].args.length - 1]).toBe(AUTH_URL);
+      expect(cands[0].args[cands[0].args.length - 1]).not.toMatch(/^".*"$/);
+
+      // 2: PowerShell Start-Process, last resort, also with the raw URL.
+      expect(cands[1].cmd).toBe(
+        "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe"
+      );
+      expect(cands[1].args).toContain("Start-Process");
+      expect(cands[1].args).toContain("-NoProfile");
+      expect(cands[1].args).toContain("-NonInteractive");
+      // The URL is passed to `-Command` as a SINGLE-QUOTED PowerShell string
+      // literal so its `&` (and `?`, `=`, spaces) can't be parsed as PS source.
+      // The raw, unquoted URL must NOT appear as an arg on its own.
+      expect(cands[1].args).toContain(`'${AUTH_URL}'`);
+      expect(cands[1].args).not.toContain(AUTH_URL);
+      // …and the quoted literal still carries the full multi-`&` URL intact.
+      const psArg = cands[1].args[cands[1].args.length - 1];
+      expect(psArg).toBe(`'${AUTH_URL}'`);
+      expect(psArg).toContain("&code_challenge=abc123");
+      expect(psArg).toContain("redirect_uri=http%3A%2F%2F127.0.0.1%3A51789%2Fcallback");
+    } finally {
+      if (savedRoot === undefined) delete process.env.SystemRoot;
+      else process.env.SystemRoot = savedRoot;
+    }
+  });
+
+  it("resolves both launchers under %windir% when SystemRoot is unset", () => {
+    const savedRoot = process.env.SystemRoot;
+    const savedWindir = process.env.windir;
+    delete process.env.SystemRoot;
+    process.env.windir = "D:\\WINNT";
+    try {
+      const cands = windowsFallbackCandidates(AUTH_URL);
+      expect(cands[0].cmd).toBe("D:\\WINNT\\System32\\rundll32.exe");
+      expect(cands[1].cmd).toBe(
+        "D:\\WINNT\\System32\\WindowsPowerShell\\v1.0\\powershell.exe"
+      );
+    } finally {
+      if (savedRoot === undefined) delete process.env.SystemRoot;
+      else process.env.SystemRoot = savedRoot;
+      if (savedWindir === undefined) delete process.env.windir;
+      else process.env.windir = savedWindir;
+    }
+  });
+
+  it("escapes an embedded single quote in the PowerShell literal (PS doubling)", () => {
+    // Defensive: a normal authorize URL is percent-encoded and won't contain a
+    // literal `'`, but if one ever appears it must be doubled so it can't close
+    // the PS string early and inject source. rundll32 keeps the raw URL.
+    const trickyUrl = "https://x.test/authorize?state=a'b&c=1";
+    const cands = windowsFallbackCandidates(trickyUrl);
+    expect(cands[0].args).toContain(trickyUrl); // rundll32 unquoted
+    const psArg = cands[1].args[cands[1].args.length - 1];
+    expect(psArg).toBe("'https://x.test/authorize?state=a''b&c=1'");
+  });
+});