Skip to content

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.

fix(windows): harden native module bootstrap

Fabricio Casalic2899d5990bc
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 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 dependencies
run: npm ci
diff --git a/CLAUDE.md b/CLAUDE.md
index 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 bootstra
elevated) 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 exits
before 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 a
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 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 corr
npm 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.bat
index 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.
rem
rem 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`.
rem
rem What it does NOT do: install anything machine-wide. Each missing tool is reported with the
rem 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 mod
echo.
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 ci
set "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 libraries
exit /b 0
diff --git a/src/main/bootstrap-windows.test.ts b/src/main/bootstrap-windows.test.ts
index 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?: boolean
testingSentinel?: string | null
inheritInternalOverride?: 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)
+ })
})