Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
fix(windows): harden native module bootstrap
Fabricio Casalic2899d5990bc
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 3de1fa824..79b2c8eaa 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -51,6 +51,10 @@ jobs:node-version: '22'cache: 'npm'+ - name: Verify Visual Studio C++ toolchain+ shell: cmd+ run: call "%GITHUB_WORKSPACE%\bootstrap-windows.bat" --check-vs-build-tools+- name: Install dependenciesrun: npm cidiff --git a/CLAUDE.md b/CLAUDE.mdindex 420fcd56d..3ef61bc81 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -3247,7 +3247,14 @@ winget hints (it never installs machine-wide tools itself, and the full bootstraelevated) and runs `npm ci`. Its `--check-vs-build-tools` mode is the narrow exception used by`quality-windows`: it branches before the elevation refusal, runs only the VS C++ probe, and exitsbefore the Node / Python / `npm ci` steps. Fixture injection additionally requires the explicit-`NODETERM_BOOTSTRAP_TESTING=1` sentinel. `.github/workflows/win-package-smoke.yml` is a+`NODETERM_BOOTSTRAP_TESTING=1` sentinel. The C++ probe also verifies the x64 Spectre runtime that+`node-pty`'s `/Qspectre` build requires; the workload alone can be present while that optional+component is absent, which otherwise fails only after the full install with `MSB8040`. Before+`npm ci`, the bootstrap sets `npm_config_enable_thin_lto=false` and+`npm_config_enable_lto=false`: official Node 26 Windows builds carry clang/lld ThinLTO settings in+`process.config`, and node-gyp 12 copies them into an MSVC addon project where `link.exe` rejects+`/opt:lldltojobs` with `LNK1117`. These are gyp overrides, not a reason to reject a Node version+allowed by `package.json`. `.github/workflows/win-package-smoke.yml` is a**workflow_dispatch-only** packaging smoke on windows-latest — build only, never publishes.**Follow-ups, in order:** code signing, then Windows auto-update wiring (electron-updater NSIS leg+ `latest.yml` on the nodeterm.dev feed — blocked on signing: an unsigned auto-update is adiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 0323b48ae..1b264a65a 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -17,6 +17,11 @@ npm run typecheck # tsc for both the node and web projects — the fastest corrnpm test # vitest, unit + integration```+On Windows, run `bootstrap-windows.bat` instead of `npm install`. It verifies the Visual Studio+C++ workload and its separately installed Spectre-mitigated libraries before compiling `node-pty`.+It also shields MSVC addon builds from the clang/lld ThinLTO settings inherited from Node 26; a+plain `npm install` under a stock Node 26 with node-gyp 12 otherwise fails with `LNK1117`.+`npm run server:dev` boots the Server Edition (browser UI) if you are working on that surface.**If `src/main/node-pty-patch.test.ts` is red, your `node_modules` is unpatched — not your code.**diff --git a/bootstrap-windows.bat b/bootstrap-windows.batindex 6dc5b8f49..fcb446ab6 100644--- a/bootstrap-windows.bat+++ b/bootstrap-windows.bat@@ -4,8 +4,9 @@ rem ============================================================================rem bootstrap-windows.bat — take a fresh Windows checkout to an installed, buildable nodeterm.remrem What it does: verifies the toolchain a native-module Electron build needs (Node >= 20, npm,-rem Visual Studio Build Tools with the C++ workload, Python 3 — node-pty and smart-whisper are-rem compiled against Electron's ABI by the npm `postinstall` hook), then runs `npm ci`.+rem Visual Studio Build Tools with the C++ workload + x64 Spectre libraries, Python 3 — node-pty+rem and smart-whisper are compiled against Electron's ABI by the npm `postinstall` hook), then+rem runs `npm ci`.remrem What it does NOT do: install anything machine-wide. Each missing tool is reported with therem exact winget command to run — installs that touch Program Files are a decision for the@@ -77,6 +78,11 @@ rem --- Install dependencies (postinstall patches node-pty + rebuilds native modecho.echo Running npm ci ...pushd "%REPO%"+rem Official Node 26 Windows builds carry clang/lld ThinLTO settings in process.config. node-gyp+rem 12 copies them into MSVC addon projects, where link.exe rejects /opt:lldltojobs (LNK1117).+rem npm forwards these overrides to node-gyp with higher precedence than process.config.+set "npm_config_enable_thin_lto=false"+set "npm_config_enable_lto=false"call npm ciset "NPM_EXIT=%ERRORLEVEL%"popd@@ -132,5 +138,17 @@ if not exist "%VS_INSTALLATION%\." (exit /b 1)+rem node-pty builds with /Qspectre and requires the matching x64 Spectre runtime libraries.+rem Checking only the compiler workload reports a healthy toolchain that fails later with MSB8040.+set "SPECTRE_RUNTIME="+for /d %%D in ("%VS_INSTALLATION%\VC\Tools\MSVC\*") do if exist "%%~fD\lib\spectre\x64\vcruntime.lib" if not defined SPECTRE_RUNTIME set "SPECTRE_RUNTIME=%%~fD\lib\spectre\x64\vcruntime.lib"+if not defined SPECTRE_RUNTIME (+ echo [MISSING] Visual Studio C++ Spectre-mitigated libraries were not found.+ echo Open Visual Studio Installer, modify Build Tools, then under Individual components install:+ echo MSVC v143 - VS 2022 C++ x64/x86 Spectre-mitigated libs ^(Latest^)+ exit /b 1+)+echo [OK] Visual Studio C++ build tools: "%VS_INSTALLATION%"+echo [OK] Visual Studio C++ Spectre-mitigated librariesexit /b 0diff --git a/src/main/bootstrap-windows.test.ts b/src/main/bootstrap-windows.test.tsindex 0ef43caaa..fab77a3dc 100644--- a/src/main/bootstrap-windows.test.ts+++ b/src/main/bootstrap-windows.test.ts@@ -25,6 +25,7 @@ interface ProbeResult {interface ProbeOptions {createVswhere?: boolean+ createSpectreRuntime?: booleantestingSentinel?: string | nullinheritInternalOverride?: boolean}@@ -43,6 +44,20 @@ function runVisualStudioProbe(vswhereBody: string, options: ProbeOptions = {}):scratchDirectories.push(scratch)const installation = path.join(scratch, 'VS Build Tools')mkdirSync(installation)+ if (options.createSpectreRuntime !== false) {+ const spectreRuntime = path.join(+ installation,+ 'VC',+ 'Tools',+ 'MSVC',+ '14.44.0',+ 'lib',+ 'spectre',+ 'x64'+ )+ mkdirSync(spectreRuntime, { recursive: true })+ writeFileSync(path.join(spectreRuntime, 'vcruntime.lib'), '')+ }const checkout = path.join(scratch, 'checkout with spaces')mkdirSync(checkout)@@ -225,6 +240,22 @@ describeWindows('bootstrap-windows Visual Studio probe', () => {expectVswhereInvocations(result, 1)})+ it('rejects a C++ toolchain without the Spectre-mitigated runtime', () => {+ const result = runVisualStudioProbe('echo %NODETERM_TEST_VS_INSTALLATION%', {+ createSpectreRuntime: false+ })++ expect(result.status).toBe(1)+ expect(result.stdout, result.stderr).toContain(+ '[MISSING] Visual Studio C++ Spectre-mitigated libraries were not found.'+ )+ expect(result.stdout).toContain(+ 'MSVC v143 - VS 2022 C++ x64/x86 Spectre-mitigated libs (Latest)'+ )+ expect(result.stdout).not.toContain('[OK] Visual Studio C++ build tools')+ expectVswhereInvocations(result, 1)+ })+it('accepts a reported C++ toolchain path, including spaces', () => {const result = runVisualStudioProbe('echo %NODETERM_TEST_VS_INSTALLATION%')@@ -234,4 +265,15 @@ describeWindows('bootstrap-windows Visual Studio probe', () => {)expectVswhereInvocations(result, 1)})++ it('disables inherited Node 26 LTO settings before npm ci', () => {+ const source = readFileSync(sourceBootstrap, 'utf8')+ const thinLtoOverride = source.indexOf('set "npm_config_enable_thin_lto=false"')+ const ltoOverride = source.indexOf('set "npm_config_enable_lto=false"')+ const npmCi = source.indexOf('call npm ci')++ expect(thinLtoOverride).toBeGreaterThan(-1)+ expect(ltoOverride).toBeGreaterThan(thinLtoOverride)+ expect(npmCi).toBeGreaterThan(ltoOverride)+ })})