fix(extension): Windows works without Node installed — bundle Node.exe in .vsix + sidebar path fix

v0.1.1 release. Two failed Windows attempts (PR #136 attempt 1 used
"node" on PATH; attempt 2 used Cursor.exe + ELECTRON_RUN_AS_NODE) both
left users with a non-functional extension on Windows. Deep review
2026-05-19 produced two concrete findings + one strategy change.

Finding 1 (concrete bug) — sidebar empty on Windows:
extension/src/sidebar-webview.ts:326-328 computed the per-project
header via `workspaceRoot.split("/").filter(Boolean).pop()`. Windows
paths use backslashes (`C:\Users\...\repo`), so split returns the
entire path as a single element and the header renders as the literal
full path. This corrupts downstream HTML layout — almost certainly
the root cause user reported as "монитор пустой экран". Fix: use
path.basename(), which is platform-aware.

Finding 2 (unverified assumption) — MCP env pass-through unreliable:
Cursor's `cursor.mcp.registerServer({command, args, env})` API is
undocumented, and there's no confirmation Cursor merges the `env`
field into the spawn call. ELECTRON_RUN_AS_NODE was almost certainly
never reaching the spawned MCP process. Forum threads document
inconsistent Cursor behaviour around this env var.

Strategy change — self-contained bundle:
Per user requirement, the extension must work on any Windows machine
without Node.js installed AND without depending on Cursor's internal
Node-as-Electron behaviour. The .vsix now ships an actual node.exe
inside extension/bin/node-windows-x64.exe, downloaded from official
nodejs.org during CI build (v20.20.2, SHA256-pinned). The extension
invokes that bundled Node directly with the bundled JS payload —
plain process spawn, no env tricks, no system-Node dependency.

Files:

- .github/workflows/publish-extension.yml — new Windows-only step
  downloads node-v20.20.2-win-x64.zip, verifies SHA256, extracts
  node.exe into extension/bin/node-windows-x64.exe. Runs before the
  existing "Bundle core CLI" step so the win32-x64 .vsix packages
  both files (the shebang-shim text payload AND the real Node
  interpreter).
- extension/src/binary-detect.ts — new findBundledNode() helper
  resolves the bundled-Node path on Windows; returns undefined on
  Linux/macOS (those execute the shebang shim natively).
- extension/src/spawn-binary.ts — Windows branch rewritten: uses the
  module-cached bundled-Node path instead of process.execPath +
  ELECTRON_RUN_AS_NODE. Adds setBundledNode() / getBundledNode()
  so the cache is set once at activation and read everywhere.
- extension/src/mcp-register.ts — Windows branch rewritten: registers
  Cursor MCP with command = bundled-node.exe path, args = [binary,
  serve, ...]. No env-field dependency. Drops ELECTRON_RUN_AS_NODE.
- extension/src/hooks-install.ts — `.cmd` wrapper template rewritten:
  invokes bundled Node directly with the bundled binary as argv. No
  env var set; cleaner cmd.exe semantics.
- extension/src/extension.ts — activate() now caches the
  bundled-Node path via setBundledNode() after findAxmeBinary()
  succeeds, before MCP register / hook install run. Logs the path
  for diagnostics. Non-Windows is a no-op (cached value is
  undefined and never read).
- extension/src/sidebar-webview.ts — projectName uses
  path.basename(), import added.
- extension/package.json — version 0.1.0 → 0.1.1.

VSIX size impact:
- linux-x64, linux-arm64, darwin-x64, darwin-arm64: unchanged (~580 KB)
- win32-x64: ~580 KB → ~30 MB (bundled node.exe)

Verification plan (separate from CI):
Real Windows machine without Node installed; install the artifact
.vsix; verify (1) Output channel shows "MCP: registered 'axme'
(command=...\node-windows-x64.exe, ...)", (2) sidebar renders project
name correctly, (3) chat agent can call axme_context successfully,
(4) self-test passes all 6 checks, (5) force-push is blocked by hook.

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

Author: George-iam

.github/workflows/publish-extension.yml

@@ -72,6 +72,35 @@ jobs:
         if: matrix.target != 'linux-arm64'
         run: npm test
 
+      - name: Download Node.exe for Windows bundling
+        # The win32-x64 .vsix ships a real Node interpreter inside
+        # extension/bin/node-windows-x64.exe. The extension invokes
+        # bundled-node.exe + bundled-axme-code.exe (text/CJS payload)
+        # directly — no shebang-shim trickery, no ELECTRON_RUN_AS_NODE
+        # pass-through dependency, no system-Node-on-PATH requirement.
+        #
+        # Version + SHA pinned for reproducible builds. Bump explicitly
+        # in this file when refreshing the bundled Node. SHA256 source:
+        #   curl -fsSL https://nodejs.org/dist/v20.20.2/SHASUMS256.txt
+        # Earlier attempts (PR #136) used the user's own Node or
+        # Cursor's bundled Electron via ELECTRON_RUN_AS_NODE — both
+        # fragile and inconsistent on real Windows machines.
+        if: matrix.target == 'win32-x64'
+        shell: bash
+        run: |
+          set -euo pipefail
+          NODE_VERSION="20.20.2"
+          ZIP="node-v${NODE_VERSION}-win-x64.zip"
+          curl -fsSL -o "$ZIP" "https://nodejs.org/dist/v${NODE_VERSION}/${ZIP}"
+          echo "dc3700fdd57a63eedb8fd7e3c7baaa32e6a740a1b904167ff4204bc68ed8bf77  $ZIP" | sha256sum -c -
+          # The Windows runner image already has 7z / unzip available.
+          # `unzip -q` works on the runner's Git-Bash environment.
+          unzip -q "$ZIP"
+          mkdir -p extension/bin
+          cp "node-v${NODE_VERSION}-win-x64/node.exe" extension/bin/node-windows-x64.exe
+          ls -la extension/bin/node-windows-x64.exe
+          rm -rf "$ZIP" "node-v${NODE_VERSION}-win-x64"
+
       - name: Bundle core CLI to a single platform-specific file
         shell: bash
         run: |

extension/package.json

@@ -2,7 +2,7 @@
   "name": "axme-code",
   "displayName": "AXME Code",
   "description": "Persistent memory, decisions, and safety guardrails for Cursor, GitHub Copilot, Cline, Continue, Roo Code, Windsurf, and VS Code chat agents",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "publisher": "AxmeAI",
   "repository": {
     "type": "git",

extension/src/binary-detect.ts

@@ -46,6 +46,35 @@ function bundledBinaryPath(context: vscode.ExtensionContext): string {
   return join(context.extensionPath, "bin", `axme-code${ext}`);
 }
 
+/**
+ * Locate the bundled Node.exe that ships inside the .vsix on Windows.
+ *
+ * Why we need this: extension/bin/axme-code.exe is a shebang-shim text
+ * file (`#!/usr/bin/env node` + CJS payload). POSIX systems execute it
+ * via the shebang. Windows ignores shebangs entirely — it can't execute
+ * the file as a PE binary. Previous fixes tried using Cursor's own
+ * Electron binary as a Node interpreter via ELECTRON_RUN_AS_NODE=1, but
+ * Cursor's `registerServer({env})` API is undocumented and the env var
+ * doesn't reliably reach the spawned process. The current strategy is
+ * the simplest one that works: ship an actual Node.exe inside the .vsix
+ * and invoke it directly.
+ *
+ * The CI matrix downloads node-v20.x.x-win-x64.zip during build, copies
+ * node.exe into extension/bin/node-windows-x64.exe, and packages it
+ * into the win32-x64 .vsix. This function returns its absolute path at
+ * runtime so spawn-binary / mcp-register / hooks-install can use it.
+ *
+ * Returns undefined on non-Windows platforms (Linux/macOS execute the
+ * shebang shim natively, no bundled Node needed there) and when the
+ * file is missing (broken install — caller surfaces an actionable
+ * error to the user).
+ */
+export function findBundledNode(context: vscode.ExtensionContext): string | undefined {
+  if (process.platform !== "win32") return undefined;
+  const p = join(context.extensionPath, "bin", "node-windows-x64.exe");
+  return existsSync(p) ? p : undefined;
+}
+
 function standardInstallLocations(): string[] {
   const home = homedir();
   const ext = process.platform === "win32" ? ".cmd" : "";

extension/src/extension.ts

@@ -26,9 +26,10 @@
 
 import * as vscode from "vscode";
 import { detectIde, IdeKind } from "./ide-detect.js";
-import { findAxmeBinary } from "./binary-detect.js";
+import { findAxmeBinary, findBundledNode } from "./binary-detect.js";
 import { registerMcpServer } from "./mcp-register.js";
 import { installUserHooks } from "./hooks-install.js";
+import { setBundledNode } from "./spawn-binary.js";
 import { ensureAuditorAuth } from "./auditor-auth.js";
 import { isAxmeInitialized } from "./setup-controller.js";
 import { AxmeStatusBar } from "./status-bar.js";
@@ -116,6 +117,18 @@ export async function activate(context: vscode.ExtensionContext): Promise<void>
     return;
   }
 
+  // Cache the bundled Node.exe path (Windows only). Used by mcp-register,
+  // hooks-install, and every spawn through spawnBinary(). On Linux/macOS
+  // this resolves to undefined and the shebang shim is executed directly.
+  // If we're on Windows and node-windows-x64.exe is missing from the
+  // .vsix, downstream spawns throw a clear "reinstall the extension"
+  // error rather than failing mysteriously with ENOENT.
+  const bundledNode = findBundledNode(context);
+  setBundledNode(bundledNode);
+  if (process.platform === "win32") {
+    log(`  Bundled Node: ${bundledNode ?? "(missing — Windows spawns will fail)"}`);
+  }
+
   // ---- Step 3: MCP registration ------------------------------------------
   // We need the workspace folder BEFORE Step 6 — pass it to mcp-register so
   // the server's --workspace flag points at the real project, not Cursor's

extension/src/hooks-install.ts

@@ -26,6 +26,7 @@ import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 import { IdeKind } from "./ide-detect.js";
 import { log, logError } from "./log.js";
+import { getBundledNode } from "./spawn-binary.js";
 
 type HookKind = "preToolUse" | "postToolUse" | "sessionEnd";
 
@@ -71,29 +72,40 @@ function windowsHookWrapperPath(): string {
 
 /**
  * Write the Windows .cmd wrapper that lets Cursor's hook runner invoke
- * our shebang-shim binary without requiring `node.exe` on PATH. Returns
- * the wrapper path (caller writes it into the hook command string).
+ * our shebang-shim binary using the bundled Node.exe that ships inside
+ * the .vsix. Returns the wrapper path (caller writes it into the hook
+ * command string).
  *
- * The wrapper captures the Cursor.exe path (process.execPath in the
- * extension host) AND the absolute path to the bundled binary, so it
- * works even when the user's PATH lacks Node and even when Cursor is
- * installed in a non-standard location. ELECTRON_RUN_AS_NODE=1 tells
- * Electron to behave as a plain Node interpreter; same trick VS Code
- * uses internally for language servers.
+ * Previously this wrapper invoked Cursor.exe with ELECTRON_RUN_AS_NODE=1
+ * to use Cursor's own Electron as a Node interpreter. That approach
+ * worked in theory but proved fragile in practice — Cursor's spawn
+ * behaviour around that env var is inconsistent, and any Cursor update
+ * could change it. Now the wrapper points at the Node.exe we ship
+ * ourselves (extension/bin/node-windows-x64.exe), which is a plain
+ * Node interpreter that just works.
  */
 function writeWindowsHookWrapper(binary: string): string {
   const path = windowsHookWrapperPath();
+  const bundledNode = getBundledNode();
+  if (!bundledNode) {
+    throw new Error(
+      "AXME Code: cannot install Cursor hooks — bundled Node.exe not " +
+        "found at extension/bin/node-windows-x64.exe. The .vsix may be " +
+        "incomplete; please reinstall the extension.",
+    );
+  }
   // cmd.exe parser quirks:
   //   - `@echo off` silences the prompt echo
-  //   - `setlocal` scopes the env var to this script invocation
+  //   - `setlocal` scopes any env changes to this script invocation
   //   - `%*` forwards all caller args verbatim (with quoting preserved)
-  // The Cursor.exe path comes from process.execPath at install time —
-  // if Cursor relocates, user re-runs setup and we rewrite this file.
+  // The bundled Node and binary paths are absolute, captured at install
+  // time. If the extension is uninstalled and reinstalled to a
+  // different location, the user runs setup again and we rewrite this
+  // file with the new paths.
   const content =
     `@echo off\r\n` +
     `setlocal\r\n` +
-    `set ELECTRON_RUN_AS_NODE=1\r\n` +
-    `"${process.execPath}" "${binary}" %*\r\n`;
+    `"${bundledNode}" "${binary}" %*\r\n`;
   mkdirSync(dirname(path), { recursive: true });
   writeFileSync(path, content, "utf-8");
   log(`Hooks: wrote Windows wrapper at ${path}`);

extension/src/mcp-register.ts

@@ -15,6 +15,7 @@
 
 import * as vscode from "vscode";
 import { log, logError } from "./log.js";
+import { getBundledNode } from "./spawn-binary.js";
 
 interface CursorMcpApi {
   registerServer(config: {
@@ -59,25 +60,43 @@ export async function registerMcpServer(
   // `spawn(command, args)` directly and gets ENOENT, which surfaces in
   // the chat as "MCP server does not exist … No MCP servers available."
   //
-  // The fix uses Cursor's own Electron binary as the Node interpreter.
-  // `process.execPath` in the extension host = path to Cursor.exe (or
-  // Code.exe in VS Code), which is an Electron binary that can run as
-  // plain Node when invoked with the env var `ELECTRON_RUN_AS_NODE=1`.
-  // This eliminates the dependency on the user having `node.exe` on
-  // PATH — most Windows users of a chat-agent IDE will not. Same
-  // pattern VS Code uses internally for language servers and other
-  // Node subprocesses.
+  // Earlier attempts:
+  //   1. spawn("node", ...) — required user to have Node on PATH, which
+  //      most Windows chat-IDE users don't.
+  //   2. spawn(process.execPath, ..., env: { ELECTRON_RUN_AS_NODE: "1" })
+  //      — relied on Cursor's MCP runner passing the env field through
+  //      to spawn(). Cursor's registerServer() API is undocumented and
+  //      the env pass-through is NOT reliable in practice. User-reported
+  //      MCP still failed to boot on Windows even with this fix.
   //
-  // Documented: https://www.electronjs.org/docs/latest/api/environment-variables#electron_run_as_node
+  // Current strategy: ship an actual Node.exe inside the .vsix and tell
+  // Cursor to spawn THAT as the MCP server command, with the bundled JS
+  // payload as argv[0]. This is a plain process spawn — no env tricks,
+  // no Electron-as-Node, no system Node dependency. The bundled Node
+  // path is resolved at activation time via findBundledNode() and
+  // cached in spawn-binary.ts.
   const isWindows = process.platform === "win32";
-  const command = isWindows ? process.execPath : binary;
-  const args = isWindows ? [binary, ...serveArgs] : serveArgs;
-  const env: Record<string, string> = isWindows ? { ELECTRON_RUN_AS_NODE: "1" } : {};
+  let command: string;
+  let args: string[];
+  if (isWindows) {
+    const bundledNode = getBundledNode();
+    if (!bundledNode) {
+      throw new Error(
+        "AXME Code: bundled Node.exe not found at extension/bin/node-windows-x64.exe. " +
+          "MCP server cannot start. This usually means the .vsix is incomplete — please reinstall.",
+      );
+    }
+    command = bundledNode;
+    args = [binary, ...serveArgs];
+  } else {
+    command = binary;
+    args = serveArgs;
+  }
   cursor.registerServer({
     name: "axme",
-    server: { command, args, env },
+    server: { command, args, env: {} },
   });
-  log(`MCP: registered 'axme' (command=${command}, binary=${binary}, workspace=${workspaceRoot ?? "(none)"}, electron-as-node=${isWindows ? "yes" : "no"})`);
+  log(`MCP: registered 'axme' (command=${command}, binary=${binary}, workspace=${workspaceRoot ?? "(none)"})`);
   // Cursor needs ~3s to process the registration before tools become
   // available to the chat agent. Verified empirically against the
   // browser-devtools-mcp reference implementation.

extension/src/sidebar-webview.ts

@@ -16,7 +16,7 @@
 
 import * as vscode from "vscode";
 import { readFileSync } from "node:fs";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 import { KbWatcher, KbCounts, readCounts } from "./kb-watcher.js";
 import { readBacklog, BacklogItemLite } from "./backlog-reader.js";
 import { readActiveSession, ActiveSession } from "./session-tracker.js";
@@ -323,9 +323,13 @@ export class AxmeSidebarProvider implements vscode.WebviewViewProvider {
     // it obvious WHICH repo the current numbers / setup state belong to.
     // VS Code reloads the window on folder switch, so this static bake
     // is safe — the webview's lifetime equals one workspace's lifetime.
-    const projectName = this.workspaceRoot
-      ? this.workspaceRoot.split("/").filter(Boolean).pop() ?? ""
-      : "";
+    // path.basename() is platform-aware: returns "repo" on both
+    // /home/me/repo and C:\Users\me\repo. The previous split("/") form
+    // broke on Windows backslash paths — the entire workspaceRoot
+    // rendered into the sidebar header as one long string, which in
+    // turn corrupted the rest of the HTML layout (reported by
+    // @geobelsky as "монитор пустой экран" on Windows v0.1.0).
+    const projectName = this.workspaceRoot ? basename(this.workspaceRoot) : "";
     const titleHtml = projectName
       ? `AXME · ${escapeHtmlServer(projectName)}`
       : `AXME Code`;

extension/src/spawn-binary.ts

@@ -7,15 +7,20 @@
  * and rejects the file with ENOENT / UNKNOWN when treated as an
  * executable, regardless of the .exe / .cjs file-extension we ship.
  *
- * The fix on Windows: invoke via Cursor's own Electron binary
- * (`process.execPath`) with the env var `ELECTRON_RUN_AS_NODE=1`. That
- * makes Cursor.exe behave as a plain Node interpreter and execute the
- * JS payload. We DO NOT rely on the user having `node.exe` on PATH —
- * most Windows users of a chat-agent IDE will not.
+ * The Windows strategy: ship an actual Node.exe inside the .vsix
+ * (extension/bin/node-windows-x64.exe, copied from the official
+ * node-v20.x.x-win-x64.zip during CI). Invoke that bundled Node
+ * directly with the bundled JS payload as argv[0]. No system Node
+ * dependency, no shebang gymnastics, no ELECTRON_RUN_AS_NODE
+ * pass-through quirks — works regardless of whether the user has Node
+ * installed.
  *
- * This is the same pattern VS Code itself uses internally for spawning
- * Node subprocesses (e.g. language servers via vscode-languageclient).
- * Documented at https://www.electronjs.org/docs/latest/api/environment-variables#electron_run_as_node
+ * The bundled-node path is set once on extension activation via
+ * `setBundledNode()` (called from extension.ts after findBundledNode()
+ * resolves it from context.extensionPath). `spawnBinary` doesn't
+ * receive vscode context, so caching it module-level is the cleanest
+ * way to give every spawn site access without threading context
+ * through every caller.
  *
  * Every spawn of the bundled binary in the extension should go through
  * this helper. A direct `spawn(binary, args)` will work on Linux + macOS
@@ -24,6 +29,22 @@
 
 import { spawn, ChildProcess, ChildProcessWithoutNullStreams, SpawnOptions } from "node:child_process";
 
+let _bundledNode: string | undefined;
+
+/**
+ * Cache the bundled Node.exe path discovered by findBundledNode() at
+ * activation time. Called once from extension.ts. No-op on non-Windows
+ * platforms where bundled Node isn't shipped or needed.
+ */
+export function setBundledNode(path: string | undefined): void {
+  _bundledNode = path;
+}
+
+/** For diagnostics / tests. */
+export function getBundledNode(): string | undefined {
+  return _bundledNode;
+}
+
 /**
  * Cross-platform spawn of the bundled binary. Two overloads mirror
  * Node's own `spawn` typing so callers keep the non-null stdio
@@ -45,10 +66,15 @@ export function spawnBinary(
 ): ChildProcess {
   const opts = options ?? {};
   if (process.platform === "win32") {
-    return spawn(process.execPath, [binary, ...args], {
-      ...opts,
-      env: { ...process.env, ...(opts.env as NodeJS.ProcessEnv | undefined), ELECTRON_RUN_AS_NODE: "1" },
-    });
+    if (!_bundledNode) {
+      throw new Error(
+        "AXME Code: bundled Node.exe not found. " +
+          "This usually means extension/bin/node-windows-x64.exe is missing " +
+          "from the .vsix you installed. Try reinstalling the extension; " +
+          "if the problem persists open an issue at https://github.com/AxmeAI/axme-code/issues.",
+      );
+    }
+    return spawn(_bundledNode, [binary, ...args], opts);
   }
   return spawn(binary, args, opts);
 }